23 Commits

Author SHA1 Message Date
userName20260323
e708f34a91
docs: align bilingual documentation with runtime behavior (#551)
## Summary

- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.

## Type

- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Passed on the rebased revision:

```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed

uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed

UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.

## Risk

Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
0xKT
8716ec525c feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary

Two things arrive together because the second is what made the first usable.

**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.

**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.

Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.

## Type

- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Commands run on the branch head, with their results:

- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean

Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.

The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:

- nginx rewrites the `Origin` header, because the engine accepts only an Origin
  naming its own loopback port and no browser reaching a published port can send
  one. This drops a defence-in-depth layer. The session cookie is
  SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
  ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
  every page load, so anyone who can reach the published port is signed in. It
  is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
  deployment reachable from elsewhere. These are two settings that must agree,
  and nothing warns when they do not.

Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).

Rollback is by revert; nothing here migrates state or changes an on-disk format.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-11 03:27:52 +00:00
KevinHuSh
4a4a3fe15b feat(docker): run raven in a docker container and make a first run configurable from the page
## Summary

Two things arrive together because the second is what made the first usable.

**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.

**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.

Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.

## Type

- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Commands run on the branch head, with their results:

- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean

Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.

The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:

- nginx rewrites the `Origin` header, because the engine accepts only an Origin
  naming its own loopback port and no browser reaching a published port can send
  one. This drops a defence-in-depth layer. The session cookie is
  SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
  ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
  every page load, so anyone who can reach the published port is signed in. It
  is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
  deployment reachable from elsewhere. These are two settings that must agree,
  and nothing warns when they do not.

Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).

Rollback is by revert; nothing here migrates state or changes an on-disk format.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-11 03:27:52 +00:00
0xKT
9c965e2470 fix(rpc): anchor the file viewer's state-dir fence on agent home, not the session workdir
## Summary

The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.

`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.

`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.

`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Commands and results, all at the branch head after rebasing onto `main`:

```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s

$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s

$ make lint-python          # ruff check + ruff format --check
exit 0

$ make lint-imports
Contracts: 9 kept, 0 broken.

$ make lint-ui
exit 0

$ make check-source-language
exit 0

$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```

Two regression tests were added next to the existing state-directory fence cases:

- the session-workdir call reads a node's report under the sessions tree and still
  refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
  while one pinned at the state root itself does not.

The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.

Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.

Known gaps, disclosed rather than worked around:

- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
  reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
  identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
  `bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
  gateway's own file paths, not through a rebuilt page bundle.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.

`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.

Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.

## Related Issues

N/A
2026-09-11 03:26:58 +00:00
userName20260323
236f66af24 fix(rpc): anchor the file viewer's state-dir fence on agent home, not the session workdir
## Summary

The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.

`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.

`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.

`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Commands and results, all at the branch head after rebasing onto `main`:

```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s

$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s

$ make lint-python          # ruff check + ruff format --check
exit 0

$ make lint-imports
Contracts: 9 kept, 0 broken.

$ make lint-ui
exit 0

$ make check-source-language
exit 0

$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```

Two regression tests were added next to the existing state-directory fence cases:

- the session-workdir call reads a node's report under the sessions tree and still
  refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
  while one pinned at the state root itself does not.

The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.

Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.

Known gaps, disclosed rather than worked around:

- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
  reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
  identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
  `bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
  gateway's own file paths, not through a rebuilt page bundle.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.

`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.

Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.

## Related Issues

N/A
2026-09-11 03:26:57 +00:00
0xKT
8581b9d933 feat(*): tell the node verdict when a run was cut at the output ceiling
## Summary

A sub-agent whose whole output budget goes to reasoning returns an empty turn, and nothing
downstream can tell that apart from a run that simply had nothing to say. The observed case
spent sixteen minutes on six generations, each cut at the model's ceiling, with no tool call
and nothing on disk. The node was recorded `completed`, because the turn returned normally,
so the DAG never saw the cuts at all.

This carries that one fact from the run to the thing that judges it.

**Re-measured on the current base, because the target moved under this.** A change landed
meanwhile that attacks the same incident from the other side: the plain-empty retry now asks
a different question each time by lowering the reasoning effort, and a spent ladder ends the
turn as an error naming the budgets it burned rather than as the canned no-answer line. That
covers the lane running the shared agent loop, and on it this branch now adds the typed fact
and the category rather than the only account of what happened.

It does not cover the built-in sub-agent lane, which has no empty-response ladder at all. A
single cut response with no tool call leaves the raw content as the answer; an empty string
is not `None`, so the guard that raises for "nothing to hand back" does not fire, the run
logs that it completed successfully, and the reply is empty with nothing saying why.

Both lanes were re-measured through the real DAG runner on this branch, with the judge stubbed
to pass so the raw status could be read. A node whose run was cut at the ceiling ends
`completed`, `crashed` False, with an empty answer, and carries this fact. So the verdict is
still the only thing that can catch it, and on the built-in lane this fact is the only signal
that anything went wrong.

**Where the fact comes from.** Whichever lane holds it. A run this process hosts reads the
response flag directly, and reports before the no-answer raise so a run that ends with
nothing carries the reason too. A run behind ACP reports it the way the protocol already
provides for: `stopReason: max_tokens`. Raven serving the agent side sends that for a turn
whose generation stopped at the ceiling, refined from `end_turn` only -- `cancelled` and
`refusal` already say why the turn ended and the ceiling does not overwrite them -- and
driving the agent side it reads that value.

Using the protocol's field rather than a private metadata key is what makes the feature
work for agents other than Raven: any conforming agent already reports a ceiling hit this
way. It also keeps the Response Meta boundary intact -- that table is the agent's own
record, which the canonical term says the host decides nothing from.

**Why the session carries it inside a Raven agent.** A turn that spent its budget reasoning
persists no assistant row at all, so the message-seated observer stash has nowhere to land.
The slot is stamped with the index the turn's rows start at, which is how a reader tells this
turn's fact from an earlier one's, and every turn either writes it or clears it. The index
alone would not be enough: it is only monotonic until a history reset or an undo moves it
back, and an old marker could then sit at an index a later turn's own start satisfies -- so
that turn would be reported as cut, which is a wrong fact rather than a missing one. Writing
or clearing on every turn is what makes the slot turn-scoped.

**Why the response flag rather than the finish reason, in-process.** The flag is the union of
two pieces of evidence, and an upstream can answer a ceiling hit with a success claim
instead. One live trace in the investigated session reported `tool_calls` at exactly 16384
output tokens.

**What the judge is told.** The fact reaches both verdict calls -- the ordinary one and the
crashed-node one, since a run can crash because it was cut and naming why is that call's job
-- and `output_limit` joins the verdict categories, so the report the orchestrator
adjudicates on says what happened instead of falling to `other`.

It is stated outside the untrusted fence because it is read off the run's transport rather
than out of the answer the sub-agent composed. It does not claim to be a measurement made
here: for a delegated agent it is that agent's own report of why its turn ended, and the
wording says so, because an unfenced fact an agent can assert about itself is one the judge
should know the source of.

The instruction is deliberately neutral about what arrived. The trigger proves the run was
cut and says nothing about what the task owed, so an instruction presuming a short answer
would mislead on a turn cut after delivering one. It says the cut does not excuse work that
is not there, and leaves the judging to the material.

**Meaning of the signal.** The run's last generation was cut. A round that was cut and then
answered in full does not carry it. It is absent wherever a transport cannot report it --
the OpenAI-compatible agent protocol exposes no finish reason at all -- so absence reads as
"not known to have been cut", never "ran to completion".

**One fix found on the way, and it is the sharper half.** The verdict fail-open exists so an
unavailable judgement cannot fail a node, and it was swallowing `TypeError` from the call
itself. A judge whose signature drifts from the runner therefore marked every node
accomplished -- the verdict system switched off with nothing anywhere failing. Adding the
keyword above reproduced exactly that: the production judge had a strict signature, so a run
reported two nodes completed and zero failed while the traceback was logged. Raising is not
enough, because the raise is caught further out and the node stays `completed`; the node now
fails and says the judge could not be called.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Commands and results, in a worktree cut from the target branch:

- `uv run --all-extras pytest` -- 20821 passed, 170 skipped, 1 failed.
  The one failure is `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
  which is inherited and terminal-width dependent, not introduced here. Proven both ways at
  the current base: it fails identically there, and it passes on this branch under
  `COLUMNS=200`. 0 introduced.
- The touched suites, re-run after the rebase onto the current base -- 842 passed, 0 failed.
  The agent loop is touched, so the loop, ACP, verdict, runner, manager, truncation, budget
  and living-docs suites were run rather than the changed files alone.
- Node-level attribution measured through the real DAG runner, with a real built-in backend
  whose every generation is cut at the ceiling and the judge stubbed to pass: both nodes end
  `completed`, `crashed` False, output empty, and both carry the fact to the judge.
- `uv run ruff check raven/ tests/` -- All checks passed.
- `uv run ruff format --check raven/ tests/` -- 1538 files already formatted.
- `uv run python scripts/check_commit_messages.py` over the range -- exit 0.
- `make check-source-language` -- exit 0.
- `uv run --all-extras pytest tests/test_kernel_budget.py` -- 5 passed. This gate caught a
  real defect during development: a new constant put the papers tree one line over its
  reviewed ceiling, so the constant moved rather than the ceiling being bumped. The switch
  to the protocol stop reason later removed that constant entirely.

Each new test was watched failing before the code that satisfies it, including the two
findings from the pre-submit sweep and both review blockers. The stop-reason rework was
driven red first: five tests, covering the refinement, the earlier-turn scoping, the refusal
to overwrite a more specific reason, the client reading the protocol field, and Response
Meta alone never recording the fact.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

**Behaviour changes a reader should know about.** Three.

A cut reply from a Raven agent behind ACP now carries the `[raven]` notice the client already
appends for any non-`end_turn` stop reason, naming `max_tokens`. That is the documented
purpose of that notice, and it is an improvement here: the original incident's reply said
nothing at all about having been cut. It is new visible text on that path.

A DAG node whose judge cannot be called now fails instead of passing. That is the point of
that fix, and it converts a silent, total loss of the verdict gate into a loud per-node
failure. If a judge implementation outside this repo has a strict signature, its nodes will
fail rather than silently pass; the error text names the cause.

A judged node can now be reported under a new category. Anything switching on the category
set sees one more member; unknown categories already fold to `other` on the read side, so an
older reader degrades rather than breaks.

**Rollback.** Revert the commits; nothing migrates and nothing persists beyond one
per-session metadata key that is overwritten each turn and ignored when absent.

**Deliberately not fixed, with reasons.** The OpenAI-compatible agent backend exposes no
finish reason, so it reports nothing and its nodes keep today's behaviour -- the signal is
either reported or absent, never inferred.

The built-in sub-agent lane treating an empty answer as an answer -- assigning the raw
content, so `""` sails past the `is None` guard written to raise for exactly this -- is a
defect of its own, older than this branch and reachable without it. Naming it here rather
than widening the diff into that loop under a branch about reporting. A host-side heuristic over the transcript shape
was considered and rejected: it cannot separate "hit the ceiling" from "returned empty",
which is the distinction the change exists to make.

**Checked and deliberately not changed.** The archived plan document carries the older
category list; the living-document rule makes it correct about its own date, so the spec was
updated and the plan was left alone.

## Related Issues

N/A
2026-09-11 03:24:58 +00:00
LivXue
f414a5a485 feat(*): tell the node verdict when a run was cut at the output ceiling
## Summary

A sub-agent whose whole output budget goes to reasoning returns an empty turn, and nothing
downstream can tell that apart from a run that simply had nothing to say. The observed case
spent sixteen minutes on six generations, each cut at the model's ceiling, with no tool call
and nothing on disk. The node was recorded `completed`, because the turn returned normally,
so the DAG never saw the cuts at all.

This carries that one fact from the run to the thing that judges it.

**Re-measured on the current base, because the target moved under this.** A change landed
meanwhile that attacks the same incident from the other side: the plain-empty retry now asks
a different question each time by lowering the reasoning effort, and a spent ladder ends the
turn as an error naming the budgets it burned rather than as the canned no-answer line. That
covers the lane running the shared agent loop, and on it this branch now adds the typed fact
and the category rather than the only account of what happened.

It does not cover the built-in sub-agent lane, which has no empty-response ladder at all. A
single cut response with no tool call leaves the raw content as the answer; an empty string
is not `None`, so the guard that raises for "nothing to hand back" does not fire, the run
logs that it completed successfully, and the reply is empty with nothing saying why.

Both lanes were re-measured through the real DAG runner on this branch, with the judge stubbed
to pass so the raw status could be read. A node whose run was cut at the ceiling ends
`completed`, `crashed` False, with an empty answer, and carries this fact. So the verdict is
still the only thing that can catch it, and on the built-in lane this fact is the only signal
that anything went wrong.

**Where the fact comes from.** Whichever lane holds it. A run this process hosts reads the
response flag directly, and reports before the no-answer raise so a run that ends with
nothing carries the reason too. A run behind ACP reports it the way the protocol already
provides for: `stopReason: max_tokens`. Raven serving the agent side sends that for a turn
whose generation stopped at the ceiling, refined from `end_turn` only -- `cancelled` and
`refusal` already say why the turn ended and the ceiling does not overwrite them -- and
driving the agent side it reads that value.

Using the protocol's field rather than a private metadata key is what makes the feature
work for agents other than Raven: any conforming agent already reports a ceiling hit this
way. It also keeps the Response Meta boundary intact -- that table is the agent's own
record, which the canonical term says the host decides nothing from.

**Why the session carries it inside a Raven agent.** A turn that spent its budget reasoning
persists no assistant row at all, so the message-seated observer stash has nowhere to land.
The slot is stamped with the index the turn's rows start at, which is how a reader tells this
turn's fact from an earlier one's, and every turn either writes it or clears it. The index
alone would not be enough: it is only monotonic until a history reset or an undo moves it
back, and an old marker could then sit at an index a later turn's own start satisfies -- so
that turn would be reported as cut, which is a wrong fact rather than a missing one. Writing
or clearing on every turn is what makes the slot turn-scoped.

**Why the response flag rather than the finish reason, in-process.** The flag is the union of
two pieces of evidence, and an upstream can answer a ceiling hit with a success claim
instead. One live trace in the investigated session reported `tool_calls` at exactly 16384
output tokens.

**What the judge is told.** The fact reaches both verdict calls -- the ordinary one and the
crashed-node one, since a run can crash because it was cut and naming why is that call's job
-- and `output_limit` joins the verdict categories, so the report the orchestrator
adjudicates on says what happened instead of falling to `other`.

It is stated outside the untrusted fence because it is read off the run's transport rather
than out of the answer the sub-agent composed. It does not claim to be a measurement made
here: for a delegated agent it is that agent's own report of why its turn ended, and the
wording says so, because an unfenced fact an agent can assert about itself is one the judge
should know the source of.

The instruction is deliberately neutral about what arrived. The trigger proves the run was
cut and says nothing about what the task owed, so an instruction presuming a short answer
would mislead on a turn cut after delivering one. It says the cut does not excuse work that
is not there, and leaves the judging to the material.

**Meaning of the signal.** The run's last generation was cut. A round that was cut and then
answered in full does not carry it. It is absent wherever a transport cannot report it --
the OpenAI-compatible agent protocol exposes no finish reason at all -- so absence reads as
"not known to have been cut", never "ran to completion".

**One fix found on the way, and it is the sharper half.** The verdict fail-open exists so an
unavailable judgement cannot fail a node, and it was swallowing `TypeError` from the call
itself. A judge whose signature drifts from the runner therefore marked every node
accomplished -- the verdict system switched off with nothing anywhere failing. Adding the
keyword above reproduced exactly that: the production judge had a strict signature, so a run
reported two nodes completed and zero failed while the traceback was logged. Raising is not
enough, because the raise is caught further out and the node stays `completed`; the node now
fails and says the judge could not be called.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Commands and results, in a worktree cut from the target branch:

- `uv run --all-extras pytest` -- 20821 passed, 170 skipped, 1 failed.
  The one failure is `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
  which is inherited and terminal-width dependent, not introduced here. Proven both ways at
  the current base: it fails identically there, and it passes on this branch under
  `COLUMNS=200`. 0 introduced.
- The touched suites, re-run after the rebase onto the current base -- 842 passed, 0 failed.
  The agent loop is touched, so the loop, ACP, verdict, runner, manager, truncation, budget
  and living-docs suites were run rather than the changed files alone.
- Node-level attribution measured through the real DAG runner, with a real built-in backend
  whose every generation is cut at the ceiling and the judge stubbed to pass: both nodes end
  `completed`, `crashed` False, output empty, and both carry the fact to the judge.
- `uv run ruff check raven/ tests/` -- All checks passed.
- `uv run ruff format --check raven/ tests/` -- 1538 files already formatted.
- `uv run python scripts/check_commit_messages.py` over the range -- exit 0.
- `make check-source-language` -- exit 0.
- `uv run --all-extras pytest tests/test_kernel_budget.py` -- 5 passed. This gate caught a
  real defect during development: a new constant put the papers tree one line over its
  reviewed ceiling, so the constant moved rather than the ceiling being bumped. The switch
  to the protocol stop reason later removed that constant entirely.

Each new test was watched failing before the code that satisfies it, including the two
findings from the pre-submit sweep and both review blockers. The stop-reason rework was
driven red first: five tests, covering the refinement, the earlier-turn scoping, the refusal
to overwrite a more specific reason, the client reading the protocol field, and Response
Meta alone never recording the fact.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

**Behaviour changes a reader should know about.** Three.

A cut reply from a Raven agent behind ACP now carries the `[raven]` notice the client already
appends for any non-`end_turn` stop reason, naming `max_tokens`. That is the documented
purpose of that notice, and it is an improvement here: the original incident's reply said
nothing at all about having been cut. It is new visible text on that path.

A DAG node whose judge cannot be called now fails instead of passing. That is the point of
that fix, and it converts a silent, total loss of the verdict gate into a loud per-node
failure. If a judge implementation outside this repo has a strict signature, its nodes will
fail rather than silently pass; the error text names the cause.

A judged node can now be reported under a new category. Anything switching on the category
set sees one more member; unknown categories already fold to `other` on the read side, so an
older reader degrades rather than breaks.

**Rollback.** Revert the commits; nothing migrates and nothing persists beyond one
per-session metadata key that is overwritten each turn and ignored when absent.

**Deliberately not fixed, with reasons.** The OpenAI-compatible agent backend exposes no
finish reason, so it reports nothing and its nodes keep today's behaviour -- the signal is
either reported or absent, never inferred.

The built-in sub-agent lane treating an empty answer as an answer -- assigning the raw
content, so `""` sails past the `is None` guard written to raise for exactly this -- is a
defect of its own, older than this branch and reachable without it. Naming it here rather
than widening the diff into that loop under a branch about reporting. A host-side heuristic over the transcript shape
was considered and rejected: it cannot separate "hit the ceiling" from "returned empty",
which is the distinction the change exists to make.

**Checked and deliberately not changed.** The archived plan document carries the older
category list; the living-document rule makes it correct about its own date, so the spec was
updated and the plan was left alone.

## Related Issues

N/A
2026-09-11 03:24:58 +00:00
0xKT
83c2ed7861 fix(agent): tell the model when an empty turn was cut at the output limit
## Summary

Empty-Response Recovery now descends the reasoning effort on each retry and FAILs
when no rung is left. That answers two of the three things this branch was opened
for: the retry is no longer the same bytes, and a turn that produces nothing ends
as an error naming the budgets it spent instead of a canned reply that reads as an
answer.

What the descent cannot do is tell the model anything, and it buys nothing at all
where the ceiling went on a payload rather than on thinking: no effort rung shrinks
a write, and a model that does no reasoning is unaffected by the rung it is given.
`Tool.truncation_hint` carries the right advice for that case but rides a refused
tool call, and a turn cut before any call produced none. So a retry after a turn cut
at the ceiling additionally carries `OUTPUT_LIMIT_NUDGE`, once per turn.

Every sentence in it is held to what the trigger proves, which is only that an empty
turn hit the ceiling. Two earlier claims were cut for failing that test:

- "the reasoning alone spent the whole budget" -- true of a reasoning model, false of
  one whose answer simply ran long, and the trigger cannot tell them apart.
- an instruction to emit a tool call -- a plain question arrives here too, so the text
  now names an answer and a call as equally valid recoveries.

The gate reads `response.truncated` rather than `finish_reason`. That is the field the
contract provides for "stopped at the ceiling", and it says an upstream may claim
success instead. The two agree today, so this changes no behaviour; it stops the
repository holding one fact under two names, an open sibling change having already
chosen the contract's field for the same question.

Three rules, three regression guards, each shown to fail under a mutation of the rule
it holds:

| rule | mutation that breaks it |
|---|---|
| fires only on a turn cut at the ceiling | drop the condition; an uncut empty turn is told it was cut |
| the synthetic assistant sits before the nudge | skip the placeholder; a bare tool-then-user pair reaches the provider |
| said once per turn, not once per retry | ignore the flag; the advice accumulates |

The second is the one worth naming. Driven through a turn with no tool call, nothing
precedes the nudge that could be a tool result, so that assertion passes whether or
not the placeholder is written -- coverage-shaped and empty. It is driven instead with
a tool result last and the post-tool nudge switched off, so RETRY is reached directly
and the mutation is visible.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Regression batch, same selection and interpreter on both sides, baseline taken at this
branch's own merge base:

    python -m pytest tests/ -q -p no:randomly --tb=no \
      -k "loop or provider or rates or truncation or compaction or budget or overflow or context"
    -> base:   2 failed, 3 errors, 3056 passed
    -> branch: 2 failed, 3 errors, 3061 passed

The failing and erroring ID sets are identical on both sides, so zero introduced. All
five are ppt-engine tests that do not run from a worktree checkout. The pass count
rises by exactly the five tests this branch adds.

Targeted:

    python -m pytest tests/test_agent_loop_empty_recovery.py -q -p no:randomly
    -> 53 passed

Each guard was verified by running the mutation of its own rule and watching that test,
and only that test, go red; the tree was restored and re-run green afterwards.

Gates:

    ruff check raven/ tests/            -> All checks passed
    ruff format --check                 -> already formatted
    scripts/check_commit_messages.py    -> exit 0
    scripts/check_source_language.py    -> exit 0

Not run: the web and TUI suites, which this change does not touch.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

A turn that ends empty at the ceiling now sees one extra synthetic user message in the
request that follows. It is marked `_recovery_synthetic`, so the existing
strip-before-persistence step drops it, and a test asserts it reaches neither the
returned messages nor the session record.

The nudge is prompt text and ships as product, so the risk is a model taking the wrong
advice from it. It asks the model to keep the turn short, which is always available;
offers an answer and a tool call as equally valid, so it cannot push an answer-only turn
at a tool; and its batching clause is conditional on there having been a payload too
large to finish.

Rollback is a single revert. No data, schema, config or wire-format changes.

Two things checked and deliberately left:

- A non-thinking empty turn that follows tool calls takes the NUDGE branch and receives
  `POST_TOOL_NUDGE`, which does not mention the ceiling. Covering it needs a second
  injection site for a narrower shape.
- An open sibling change adds a near-twin of this branch's always-cut provider fixture to
  the same test file. Whichever lands second should collapse the two rather than keep both.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-11 03:22:20 +00:00
LivXue
31e2584b5a fix(agent): tell the model when an empty turn was cut at the output limit
## Summary

Empty-Response Recovery now descends the reasoning effort on each retry and FAILs
when no rung is left. That answers two of the three things this branch was opened
for: the retry is no longer the same bytes, and a turn that produces nothing ends
as an error naming the budgets it spent instead of a canned reply that reads as an
answer.

What the descent cannot do is tell the model anything, and it buys nothing at all
where the ceiling went on a payload rather than on thinking: no effort rung shrinks
a write, and a model that does no reasoning is unaffected by the rung it is given.
`Tool.truncation_hint` carries the right advice for that case but rides a refused
tool call, and a turn cut before any call produced none. So a retry after a turn cut
at the ceiling additionally carries `OUTPUT_LIMIT_NUDGE`, once per turn.

Every sentence in it is held to what the trigger proves, which is only that an empty
turn hit the ceiling. Two earlier claims were cut for failing that test:

- "the reasoning alone spent the whole budget" -- true of a reasoning model, false of
  one whose answer simply ran long, and the trigger cannot tell them apart.
- an instruction to emit a tool call -- a plain question arrives here too, so the text
  now names an answer and a call as equally valid recoveries.

The gate reads `response.truncated` rather than `finish_reason`. That is the field the
contract provides for "stopped at the ceiling", and it says an upstream may claim
success instead. The two agree today, so this changes no behaviour; it stops the
repository holding one fact under two names, an open sibling change having already
chosen the contract's field for the same question.

Three rules, three regression guards, each shown to fail under a mutation of the rule
it holds:

| rule | mutation that breaks it |
|---|---|
| fires only on a turn cut at the ceiling | drop the condition; an uncut empty turn is told it was cut |
| the synthetic assistant sits before the nudge | skip the placeholder; a bare tool-then-user pair reaches the provider |
| said once per turn, not once per retry | ignore the flag; the advice accumulates |

The second is the one worth naming. Driven through a turn with no tool call, nothing
precedes the nudge that could be a tool result, so that assertion passes whether or
not the placeholder is written -- coverage-shaped and empty. It is driven instead with
a tool result last and the post-tool nudge switched off, so RETRY is reached directly
and the mutation is visible.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Regression batch, same selection and interpreter on both sides, baseline taken at this
branch's own merge base:

    python -m pytest tests/ -q -p no:randomly --tb=no \
      -k "loop or provider or rates or truncation or compaction or budget or overflow or context"
    -> base:   2 failed, 3 errors, 3056 passed
    -> branch: 2 failed, 3 errors, 3061 passed

The failing and erroring ID sets are identical on both sides, so zero introduced. All
five are ppt-engine tests that do not run from a worktree checkout. The pass count
rises by exactly the five tests this branch adds.

Targeted:

    python -m pytest tests/test_agent_loop_empty_recovery.py -q -p no:randomly
    -> 53 passed

Each guard was verified by running the mutation of its own rule and watching that test,
and only that test, go red; the tree was restored and re-run green afterwards.

Gates:

    ruff check raven/ tests/            -> All checks passed
    ruff format --check                 -> already formatted
    scripts/check_commit_messages.py    -> exit 0
    scripts/check_source_language.py    -> exit 0

Not run: the web and TUI suites, which this change does not touch.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

A turn that ends empty at the ceiling now sees one extra synthetic user message in the
request that follows. It is marked `_recovery_synthetic`, so the existing
strip-before-persistence step drops it, and a test asserts it reaches neither the
returned messages nor the session record.

The nudge is prompt text and ships as product, so the risk is a model taking the wrong
advice from it. It asks the model to keep the turn short, which is always available;
offers an answer and a tool call as equally valid, so it cannot push an answer-only turn
at a tool; and its batching clause is conditional on there having been a payload too
large to finish.

Rollback is a single revert. No data, schema, config or wire-format changes.

Two things checked and deliberately left:

- A non-thinking empty turn that follows tool calls takes the NUDGE branch and receives
  `POST_TOOL_NUDGE`, which does not mention the ceiling. Covering it needs a second
  injection site for a narrower shape.
- An open sibling change adds a near-twin of this branch's always-cut provider fixture to
  the same test file. Whichever lands second should collapse the two rather than keep both.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-11 03:22:19 +00:00
LivXue
3f3ee04e88 feat(*): address llm.input messages by content sha1
## Summary

An agent loop appends one message per turn and re-records the whole conversation each
time. `persist_artifact` deduplicates whole payloads by sha1, which cannot see that turn
N+1 differs from turn N by one appended message, so `llm.input` grew at roughly
4.3 GiB/day on the host this was measured on. Two commits, the second depending on the
first.

**1. Stop restating the message list.** `_llm_input_payload` split the flat list into
three views for the viewer and kept the raw list alongside them, so the same turns were
serialized twice per artifact. `historyMessages` had no reader anywhere in the tree - its
only two mentions were the docstring describing it and the line writing it - because the
viewer stopped using the split and says so at `ui/app.js:1441` while the writer was never
brought along. Over 1,806 recorded artifacts: 8.665 GiB before, 5.007 GiB after, a 42.2%
saving of 3.658 GiB.

**2. Address each message by its content sha1.** `llm.input` is now written as
`audit.artifact.v2`: each message is stored once under
`audit-artifacts/_messages/<sha1[:2]>/<sha1>.json` and the artifact carries a
`{"$msg": sha1}` reference in its place, with `systemPrompt` and `prompt` aliasing their
own element rather than restating its text. On the largest recorded artifact that is
32.906 MiB down to 0.063 MiB. Over a 1,733-artifact snapshot, 106,247 message occurrences
carried 6,454 distinct contents - a 93.9% reuse rate whole-payload addressing cannot
reach.

Key decisions and why:

- **`raven/tracing/artifact_v2.py` is the format's single authority** because the bundled
  viewer mirrors it in JavaScript. A cross-language test asserts both resolvers return
  byte-identical JSON for one shell. Its fixture carries non-string content deliberately:
  Python's default JSON separators carry spaces and JavaScript's do not, so `coerce_text`
  pins `separators=(",", ":")` to match `JSON.stringify`.
- **Message blobs sit beside `_blobs/`, never inside it.** `compact` removes any blob in
  `_blobs/` whose link count is 1, and a message blob's is permanently 1 because a shell
  references it from JSON text rather than by hard link. Inside `_blobs/` the whole corpus
  would be swept on the next `raven tracing compact`. The sibling layout is not free,
  which the first review round established: `_iter_day_dirs` skipped only `_blobs/`, and
  `_messages/<sha1[:2]>/<sha1>.json` has exactly the shape of `<kind>/<day>/<file>`, so
  the walk read the message store as an artifact tree. `compact` now names both
  content-addressed stores in `_CONTENT_STORES` and walks neither. Its "no referenced
  artifact is removed, pure convergence" invariant is untouched; what changed is which
  directories it considers artifacts at all.
- **Two resolution points, both at boundaries that already reformat**: `bundle` when
  packing a trajectory, and `readArtifact` in the viewer's `server.js`. Consequence:
  replay, cassette minimization and the viewer's UI read v1 shapes and needed no change.
  Their suites pass unmodified, which the Verification below asserts rather than claims.
- **Key order is preserved, not sorted.** Sorting lets two orderings share a blob, but
  resolution then hands back a reordered copy, and the text fields carry that order inside
  a serialized string, so the exact round trip - the invariant the design rests on - is
  lost. Over 406,357 occurrences, sorting changed the distinct count by zero. The design
  document records this as a first choice rejected by implementation, with the numbers.
- **`llm.input.artifact_bytes` now measures the shell**, and `llm.request_bytes` is the
  request-size signal. That attribute is `main`'s, not this branch's: an earlier revision
  added `llm.input.content_bytes` for the same reason, and the rebase below found `main`
  had landed a better-specified measurement of the same fact. See Rebase.

The design document is `docs/specs/2026-09-10-llm-input-message-addressing-design.md` and
the plan `docs/plans/2026-09-10-llm-input-message-addressing.md`. Both carried a claim the
first review falsified - that a sibling directory left `compact` unchanged - and both now
record what review established instead; the plan additionally records why its own green
`test_tracing_compact.py` run was not evidence, that suite having no `_messages/` tree in
any fixture.

**Review round 1** (chandler.zhang, one blocking finding, fixed in `fix(tracing): keep
compact out of the message store`): reproduced independently before fixing - one addressed
message aged past `FRESH_SECONDS` gave `scanned=1`, the message at `st_nlink == 2`, and a
new `_blobs/f3/f3c1153f5fe09fae848cada6617f0ebbada69851.json`; after the fix the same
script reports `scanned=0`, `st_nlink == 1`, no `_blobs` entry. The regression sits in
`test_tracing_compact.py` and was verified load-bearing by restoring the old condition and
watching it redden. A second test pins the stale-tmp half of the same walk, so a future
widening of the exclusion cannot silently start deleting inside the message store.

## Rebase onto `main` at `9c531c232`

Not a pure replay. `main` moved 36 commits and `855d12185 fix(providers): honour the
declared output ceiling` extended the same function this branch rewrites, so three
conflicts were resolved by hand and two of this branch's own claims changed as a result.

**The substantive one: a duplicate fact, resolved in `main`'s favour.** `main` added
`_request_attrs` - `llm.request_bytes`, `llm.request_images`, `llm.request_image_bytes` -
whose docstring gives the same reason this branch had added `llm.input.content_bytes`:
the request's size should be greppable without opening the artifact. Keeping both would
have left one fact under two names with different definitions. `main`'s is the better
one and landed first: it counts `{"messages": ..., "tools": ...}` with the separators an
HTTP client uses rather than messages alone with Python's, streams through `iterencode`
so a 20 MB request is measured without a second copy in memory, and reports decoded
image bytes beside the total. It reads `bound["messages"]` rather than the artifact, so
addressing the messages does not move it. `content_bytes` and its helper are gone.

**`main` also added two keys to the `llm.input` payload**, `request` and `generation`.
They are carried in the shell verbatim. Neither holds message content - three integers
and the parameters the provider resolved - so referencing them would cost an indirection
and save nothing. Measured on the largest real artifact in the local store (1200
messages, 3.45 MiB): the shell is 134.8 KiB without them and 135.0 KiB with, a cost of
192 bytes, 0.005% of the original. The frozen key-set test accepts them explicitly rather
than by widening.

Note that `git merge-tree` reported those two keys as an automatic merge. They collide
semantically, not textually, and only the frozen key-set test surfaced it - which is the
argument for that test existing.

Three smaller consequences, all in this branch's own text:

- The `llm.call` row in `docs/TRACING_STANDARD_API.md` is merged rather than chosen: it
  keeps every attribute `main` added and describes `llm.input` as `audit.artifact.v2`.
- `test_llm_call_records_the_resolved_size` became
  `test_the_request_size_signal_survives_the_shell`, asserting the relationship
  (`llm.request_bytes` carries the conversation, `artifact_bytes` is smaller) rather than
  the presence of a now-deleted attribute.
- The first commit's own frozen key set needed the two new keys too. Git's auto-merge
  kept that commit's test and `main`'s code, each correct alone and red together; it was
  caught by running each commit separately, not the branch head, where the second commit
  replaces that test and hides it.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Ran in a worktree whose imports were confirmed to resolve to the worktree, not the main
checkout (`python -c "import raven; print(raven.__file__)"`).

Targeted suites at the rebased head:

```
python -m pytest tests/test_tracing_api.py tests/test_tracing_artifact_v2.py \
  tests/test_trajectory_bundle.py tests/test_trajectory_replay.py \
  tests/test_trajectory_cassette.py tests/test_trajectory_regressions.py \
  tests/test_tracing_compact.py tests/test_living_docs.py \
  tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py \
  tests/test_agent_loop_truncation_paths.py tests/test_no_otel_tracing.py
-> 258 passed

python -m pytest tests/integration/test_tracing_viewer_e2e.py -m integration -n0
-> 19 passed   (spawns the real Node viewer and drives it over HTTP)

lint-imports
-> Contracts: 9 kept, 0 broken
```

At the rebased head those are **288 passed** and **19 passed**, with
`test_context_scent.py` now included (`main` added two cases for its own `CONTEXT.md`
text). Each commit was also run on its own, since a rebase can leave a commit red while
the head is green: **133**, **169**, **171** passed.

Full suite before the rebase: `28 failed, 20325 passed, 140 skipped`. All 28 are
pre-existing, established by A/B rather than inference:

- Zero file overlap between this branch's twelve files and any ppt / office /
  `plugins-dist` path.
- The failures name `plugins-dist/ppt-engine/...` under the **main checkout**, which is
  where `plugins-dist` is installed editable, so a worktree's engine tests run against
  whatever that checkout currently holds.
- Reverting this branch to a pristine tree and re-running the six files that held the
  failures gave the same 26. The two the file list did not cover
  (`test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
  `test_ppt_engine_assembly.py::test_the_image_generator_answers_configured_from_the_live_host_section`)
  were run separately on the pristine tree and failed there too.
- `comm -13` over the two sorted failing-ID sets is empty. 0 introduced.

Gates:

```
ruff check raven/ tests/            -> All checks passed
ruff format --check raven/ tests/   -> 1522 files already formatted
scripts/check_commit_messages.py    -> exit 0
scripts/check_source_language.py    -> exit 0
scripts/check_large_files.py        -> exit 0
```

Tests were observed failing before each implementation step. Two were then found unable
to fail and strengthened: the cross-language resolver test was verified by deliberately
diverging the JavaScript side (it named the exact bytes of the multimodal `prompt` field),
and the recorded-round-trip test gained `assert v2.is_v2(payload)`, without which it
passed on v1 payloads that `resolve_payload` returns untouched.

End-to-end on real data: six real recorded conversations of 989-999 messages each, replayed
through `semconv.llm_call`, round-tripped exactly with span attributes present -
23.80 MiB of content behind 729.3 KiB of shells, and every message blob at link count 1.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

**Format change with a discriminator.** A v1 artifact has no `artifactFormat` key and is
read by the old path, permanently. Existing artifacts are never rewritten: their content
would stop hashing to the name recorded in `artifact_sha1`, which is the integrity check
`_blob_is_intact` enforces.

**Behaviour changes worth naming.** Two rules differ from v1 on purpose, both recorded in
the payload builder's docstring and pinned by tests. The system field takes the first
system message where v1 took the first non-empty one, because a reference has no notion of
emptiness. `messages` is always a list where v1 passed a non-list argument through; the
extractors always hand it a real call's list, so the branch is unreachable in practice.

**Degradation.** A message whose blob cannot be written is inlined in the shell, so one
filesystem failure costs that message its sharing rather than the record. A blob that is
gone becomes a labelled placeholder at its own index - never dropped, because consumers
compare message-list length and position. `cassette.minimize` already refuses a bundle
that is not fully replayable, so a placeholder propagates correctly.

**Blast radius.** A message blob is shared: on the measured corpus each distinct message
was referenced about 16 times, and the system prompt far more. Losing one blob affects
every artifact referencing it, where before it affected one record. This is the cost of
content addressing and was accepted deliberately; the read path does not verify blobs,
matching `readArtifact`'s existing behaviour, and verification belongs to `compact` or a
future verify command.

**Rollback.** Revert both commits. Shells already on disk become unreadable to the
reverted code (it has no resolver), so a rollback after real traffic wants either the
`_messages/` tree kept and shells resolved out of band, or the affected date directories
deleted - `llm.input` artifacts are diagnostics, and `raven trajectory pin` is what marks
the ones that are corpus.

**Security.** A reference's sha1 is rejected unless it is 40 lowercase hex characters
before any path is built from it, on both the Python and the JavaScript side, with a test
per side driving `../../../etc/passwd`. `isSafeArtifactPath` remains the second line. No
new network surface and no credential handling.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Checked and deliberately not fixed

- **No reclaim path for `_messages/`.** The corpus grows about 65 MiB/day against the
  4.3 GiB/day it replaces. Its natural trigger is the deletion of a referencing artifact -
  the retention tooling `raven/trajectory/store.py` already reserves a place for - and
  adding it now would mean teaching `compact` to delete, discarding the invariant this
  design was shaped to preserve. Recorded in the design document's non-goals and in
  `CONTEXT.md`'s Message Blob entry.
- **Only `llm.input` is addressed.** Every other artifact kind together held 65 MiB in the
  same `du` run, under 1% of what `llm.input` held, so no generic chunked-artifact layer
  was built. The write API is generic enough to be reused later without a format change.
- **The read path does not verify blob integrity.** `_repair_blob` can restore a torn blob
  only because the write path still holds the content; a reader does not, and re-hashing
  every message per render is not affordable. `readArtifact` performs no verification
  today either.
- **`CONTEXT.md`'s Trajectory Pin promise was widened rather than left alone.** It said
  purge tooling must never delete a pinned attempt's spans or the artifacts they reference.
  A v2 shell holds no messages of its own, so that promise had silently stopped covering
  what a pinned trajectory needs - deleting a message blob destroys it while leaving the
  artifact file in place. Now stated explicitly.
- **`artifact_v2.blob_path` was renamed to `message_path`.** `store._blob_path` already
  exists for the other store; same name, different store is what a reader cannot
  disambiguate.

## Related Issues

N/A
2026-09-11 03:17:10 +00:00
0xKT
324a750b07 fix(*): retire the trunk output-drop pin and the claims it held
## Summary

`tests/test_agents_code_flow_exec.py` carried a pin on trunk's `DirectExecutor`
dropping a timed-out command's output. That was one of the reasons the code flow
replaced the executor, and the pin's own docstring said what should happen to
it: "pinned so a trunk fix can retire it". The trunk fix landed, the pin
asserted the opposite of the truth, and `main` went red.

**`main` is no longer red.** While this sat in review, a separate change
replaced the pin with `test_trunks_executor_preserves_output_on_timeout`. That
resolved the breakage and is the version kept here; this branch was rebased onto
it rather than carrying a competing test. What remains is what that replacement
did not cover:

- **Why the fork exists on that axis.** The replacement asserts the new fact in
  one line and says nothing about what still separates the two executors. Trunk
  signals a kill through the stderr line and `exit_code` and nothing more, while
  `CodeExecResult` also flags `timed_out` and renders `TIMED_OUT_NOTE`, which
  tells the model its output is a fragment rather than a whole run. That
  difference is now asserted and explained where the pin used to sit.
- **Three prose claims that are still false on `main`.** Both module docstrings
  advertise "the fork's three fixes" and describe trunk waiting on
  `communicate()` and losing the buffered output, in the present tense; the exec
  factory's docstring lists partial output as a difference. Each is corrected to
  say what is true now and what is left.

The fork's drain now duplicates trunk's. That is noted in the docstring as the
fork owners' call, because nothing depends on which of the two performs it and
this change should not spend itself on that. No code is removed and no behaviour
changes.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `pytest tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
  tests/test_sandbox_unit.py tests/test_agents_oncall_flow_hooks.py` -- 183 passed
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0

Mutation, to show the added assertions are load-bearing rather than decorative:

```
trunk discards partial stdout again   -> 1 failed   (the inherited assertions)
fork stops rendering TIMED_OUT_NOTE   -> 2 failed   (the added pair)
```

One mutation deliberately reported because it did **not** bite. An earlier
revision asserted only that trunk's rendering lacks `TIMED_OUT_NOTE`. Making
trunk emit a partial-output note in its own wording left the file green, because
the constant is matched verbatim -- and that form of assertion is equally
satisfied by a fork that stopped marking anything at all. Both sides are now
measured in one run, so the absence reads as a difference rather than as a
feature nobody has; removing the fork's append is what the second mutation
above does.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Left unchecked: no user-facing document describes either executor's timeout
behaviour. The three corrected texts are module and factory docstrings. The
model-facing half was checked separately and needed nothing -- the `timeout`
parameter description says a command that hits its limit "is killed and the
output it produced so far comes back marked partial", which is still true of
this tool.

## Disclosed

Four failures in `tests/test_ppt_engine_build_tool.py` appear in a wider
selection and are **not** from this change. They reproduce at the `main` tip in
a worktree holding none of it, and the cause is local layout rather than code:
`raven_ppt` resolves to the primary checkout's `plugins-dist/ppt-engine`, which
sits at an older revision than a fresh worktree's tests. Not investigated
further here.

How the red reached `main` is worth stating, since the cause was process rather
than code. The executor fix was pushed and then rebased onto a `main` that had
gained the pin in the meantime; the rebase surfaced the collision, and the merge
landed on the pre-rebase head before the rebase was pushed. Rebasing before the
push, as the contribution rules require, would have surfaced it while that
merge request was still open.

## Risk

No behaviour change: assertions added to an existing test, three docstrings
corrected, no production statement altered and no code removed. The duplicated
drain in the fork's executor is left exactly as it is.

Rollback is a revert of the two commits. `main` stays green either way, since
the breakage itself was resolved separately; what a revert costs is the stated
difference between the two executors and the accuracy of the three docstrings.

## Related Issues

N/A
2026-09-11 02:45:09 +00:00
LivXue
f2d76abce8 fix(*): retire the trunk output-drop pin and the claims it held
## Summary

`tests/test_agents_code_flow_exec.py` carried a pin on trunk's `DirectExecutor`
dropping a timed-out command's output. That was one of the reasons the code flow
replaced the executor, and the pin's own docstring said what should happen to
it: "pinned so a trunk fix can retire it". The trunk fix landed, the pin
asserted the opposite of the truth, and `main` went red.

**`main` is no longer red.** While this sat in review, a separate change
replaced the pin with `test_trunks_executor_preserves_output_on_timeout`. That
resolved the breakage and is the version kept here; this branch was rebased onto
it rather than carrying a competing test. What remains is what that replacement
did not cover:

- **Why the fork exists on that axis.** The replacement asserts the new fact in
  one line and says nothing about what still separates the two executors. Trunk
  signals a kill through the stderr line and `exit_code` and nothing more, while
  `CodeExecResult` also flags `timed_out` and renders `TIMED_OUT_NOTE`, which
  tells the model its output is a fragment rather than a whole run. That
  difference is now asserted and explained where the pin used to sit.
- **Three prose claims that are still false on `main`.** Both module docstrings
  advertise "the fork's three fixes" and describe trunk waiting on
  `communicate()` and losing the buffered output, in the present tense; the exec
  factory's docstring lists partial output as a difference. Each is corrected to
  say what is true now and what is left.

The fork's drain now duplicates trunk's. That is noted in the docstring as the
fork owners' call, because nothing depends on which of the two performs it and
this change should not spend itself on that. No code is removed and no behaviour
changes.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `pytest tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
  tests/test_sandbox_unit.py tests/test_agents_oncall_flow_hooks.py` -- 183 passed
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0

Mutation, to show the added assertions are load-bearing rather than decorative:

```
trunk discards partial stdout again   -> 1 failed   (the inherited assertions)
fork stops rendering TIMED_OUT_NOTE   -> 2 failed   (the added pair)
```

One mutation deliberately reported because it did **not** bite. An earlier
revision asserted only that trunk's rendering lacks `TIMED_OUT_NOTE`. Making
trunk emit a partial-output note in its own wording left the file green, because
the constant is matched verbatim -- and that form of assertion is equally
satisfied by a fork that stopped marking anything at all. Both sides are now
measured in one run, so the absence reads as a difference rather than as a
feature nobody has; removing the fork's append is what the second mutation
above does.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Left unchecked: no user-facing document describes either executor's timeout
behaviour. The three corrected texts are module and factory docstrings. The
model-facing half was checked separately and needed nothing -- the `timeout`
parameter description says a command that hits its limit "is killed and the
output it produced so far comes back marked partial", which is still true of
this tool.

## Disclosed

Four failures in `tests/test_ppt_engine_build_tool.py` appear in a wider
selection and are **not** from this change. They reproduce at the `main` tip in
a worktree holding none of it, and the cause is local layout rather than code:
`raven_ppt` resolves to the primary checkout's `plugins-dist/ppt-engine`, which
sits at an older revision than a fresh worktree's tests. Not investigated
further here.

How the red reached `main` is worth stating, since the cause was process rather
than code. The executor fix was pushed and then rebased onto a `main` that had
gained the pin in the meantime; the rebase surfaced the collision, and the merge
landed on the pre-rebase head before the rebase was pushed. Rebasing before the
push, as the contribution rules require, would have surfaced it while that
merge request was still open.

## Risk

No behaviour change: assertions added to an existing test, three docstrings
corrected, no production statement altered and no code removed. The duplicated
drain in the fork's executor is left exactly as it is.

Rollback is a revert of the two commits. `main` stays green either way, since
the breakage itself was resolved separately; what a revert costs is the stated
difference between the two executors and the accuracy of the three docstrings.

## Related Issues

N/A
2026-09-11 02:45:09 +00:00
0xKT
7a0b5dd311 feat(acp): a prompt is held open while the agent sleeps on an armed wake, and takes a steer
## Summary

An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed !573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.

- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.

What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.

## Review round 1 (2026-09-09, on !600, superseded by this MR)

- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.

## Review round 2 (2026-09-10)

- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.

## Review round 3 (2026-09-10)

- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.

## Review round 4 (2026-09-10)

- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
  tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q      # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
  tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
  tests/test_agents_oncall_flow_escalation_tools.py -q                                       # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents        # clean
uv run lint-imports                                                                          # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit   # in sync, clean
```

New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).

Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)

## Risk

- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.

A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.

## Related

Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
2026-09-11 02:37:55 +00:00
silverLXT
83aac42909 feat(acp): a prompt is held open while the agent sleeps on an armed wake, and takes a steer
## Summary

An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed !573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.

- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.

What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.

## Review round 1 (2026-09-09, on !600, superseded by this MR)

- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.

## Review round 2 (2026-09-10)

- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.

## Review round 3 (2026-09-10)

- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.

## Review round 4 (2026-09-10)

- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
  tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q      # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
  tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
  tests/test_agents_oncall_flow_escalation_tools.py -q                                       # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents        # clean
uv run lint-imports                                                                          # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit   # in sync, clean
```

New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).

Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)

## Risk

- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.

A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.

## Related

Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
2026-09-11 02:37:55 +00:00
Tchen
3f1453d5fe fix(providers): honour the declared output ceiling, retry differently, record a failed call
## Summary

A model call that returned nothing used to end a turn, and nothing in the record said why.
This branch closes that in five parts, all on the host runtime.

- **The output ceiling is the model's, not ours.** `resolve_max_output_tokens` takes the
  figure the model declares instead of a repo default, reserves it against the id the
  request actually goes out under, and counts cached prompt tokens toward the window so a
  cached prefix stops looking free. One call is given 64k of room and says so on the wire;
  the transcript summary budget goes to 32k. Two small output pins keep deliberate
  headroom, and the commit says why they do not move.
- **A retry has to ask a different question.** An empty completion previously repeated the
  same request and got the same answer. The ladder now descends by **what a rung sends**
  rather than by its label, the transcript summary is no longer asked to think, and the
  empty-completion retry differs from the call it replaces.
- **Time to first byte is bounded.** `llmFirstByteTimeout` applies on the direct adapters
  as well as through the gateway, a bound of zero means off rather than a bound at the
  total, and the guard's deadline is distinguished from a strategy's own `TimeoutError` so
  a fallback answers for the right one.
- **An effort travels as an effort.** `glm` is out of `inferred_protocol`'s Anthropic prefix
  tuple and the hand-written `_THINKING_BUDGETS` table is deleted, so a label reaches the
  vendor as a label rather than as a token count this repo invented. Measured on the wire
  before the change: 42 calls produced 261,980 characters of reasoning against a budget of
  1024 that the route discarded, while our own `max_tokens` went out on every call because
  that transport requires the field.
- **The record says what was asked and what came back.** A failed call is visible in the
  turn and readable in the record; the reasoning count is kept; a failure's headers are
  recorded as the failure's, not as a stream's server; `llm.input` gains a `generation`
  block and the span gains `llm.request.*`, with a test pinning that no credential appears
  in either. `llm.request_bytes` is documented as an estimate instead of claiming to be
  the wire. A frozen turn is stopped rather than nudged once.

## Type

- [x] Fix
- [x] Feature

## Verification

- `uv run --frozen pytest` over the full suite: **20354 passed**, with 6 failures and 20
  errors that are this box lacking `/usr/share/zoneinfo` -- all in `test_cron_tool.py` and
  `test_cli_cron_commands.py`, which this branch does not touch. Reproduced with the
  identical signature on a clean detached `origin/main` worktree, and CI ships tzdata, so
  its `tests` job is the authoritative check. Gated on `set -o pipefail` and
  `${PIPESTATUS[0]}`.
- `make lint-python` exit 0; `lint-imports` 9 kept, 0 broken.
- Contract pins re-derived against current `main` rather than carried over:
  `CONTRACTS_VERSION` **17** (main is 16), the digest from one run of the pinning test, and
  `CONTRACTS_LINE_CEILING` **2_791** against 2771 actual. 34 pinning tests pass.
- The request shape verified on real captured bodies rather than inferred: after the change
  a deck call is `POST /v1/chat/completions` carrying `reasoning: {"effort": ...}` at the
  top level, the configured temperature, and **no** `max_tokens`; before it, the same call
  was `POST /v1/messages` carrying `thinking: {"type": "enabled", "budget_tokens": 1024}`.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

The routing change moves every `glm` model from the native Anthropic Messages transport to
LiteLLM chat. That changes which client serves the deck agent and the host default model,
so it is the one item here worth a real run before it is relied on. Measured consequences
on a live deck: no truncations, no length-stops, no empty completions and no retries across
40 calls, and prompt-cache read rates in the same band as the Messages route -- `glm` takes
no `cache_control` breakpoints on either transport because OpenRouter caches it
automatically, so caching is unaffected. A provider that needs an Anthropic-compatible
address can still name `protocol: "anthropic"` explicitly, and a test pins that route.

Rollback is per part: each of the five is its own commit range, and the routing change is a
single line in `raven/providers/protocol.py`.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-11 02:37:37 +00:00
Handsome-wzw
7b45527b5b fix(tools): an array sent as its own JSON is still an array
## Summary

Reported as "deliver_files is broken". It is not: **the tool never ran.**

Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:

```
Error: Invalid parameters for tool 'deliver_files': files should be array
```

What the model sent was the array, spelled as a string:

```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```

`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.

## Type

- [x] Fix
- [ ] Feature

## The edge of the forgiving is the design

When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.

**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.

**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.

## Not just deliver_files

Six built-in tools declare an array or object parameter and were all exposed:

| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |

The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.

## Verification

```
make lint-python    ruff check + ruff format --check, 1850 files
make lint-imports   9 contracts kept, 0 broken
pytest tests/       19,699 passed, 7 failed (all pre-existing, see below)
```

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string

**End to end, through the real tool**, with the exact payload that failed five times in production:

```
files sent as:            str -> [{"path": ".../poster.png", "title": "..."}]
returned:                 Delivered 1 file(s): poster.png (72 B).
still "should be array":  False
registered in the store:  True
```

Twelve cases, five mutations, each killing at least one:

| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |

The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.

**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.

## Risk

- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert

## Related Issues

N/A

## Swept

`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.

- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.

Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).

## Deliberately not fixed

The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.

## Moved from !594

Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.

Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
2026-09-09 15:42:36 +00:00
forrestjgq
f01231fef6 fix(cli): overhaul trajectory browser interaction ux (#379)
## Summary

Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:

- Navigation: every screen opens with a help area under its title (page
  purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
  sentinel can never reach a conversion or the data layer; a cancelled
  report keeps its pre-confirm bundle-and-pin side effects (the existing
  declined-report contract). Back/Exit menu entries are gone; answered
  prompts erase themselves and navigation is echoed as breadcrumb lines
  with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
  attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
  budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
  drops as a whole column when it no longer fits, and below the dynamic
  minimum width the tightest layout is kept while the renderer clips
  overlong lines at the terminal edge. Every dynamic cell passes a
  single-line sanitization gate before width math (verdict sidecars only
  guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
  fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
  table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
  passes the terminal's CPR reply through to the renderer instead of
  treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
  (advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
  and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
  laggy Esc feel.

The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- The interactive browser's look and key protocol change wholesale (that
is
  the point of this PR): Esc no longer quits from the top level (Ctrl+C
  does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
  interaction wholesale, no data migration involved.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-05 23:58:20 +08:00
Handsome-wzw
9a87470fdf fix(rpc): turn.started is a turn event, and says so on all three sides
## Summary

Found while investigating the first row of Dizhan's `子智能体功能与显示问题` doc (*回注内容过程中未正常显示,刷新后才会正常显示*). This is not that bug's fix, but it is a real defect on the same wire, and it is the one that explains why "前后端接线没有约定好" was a fair thing to say.

**`turn.started` is not in the `TurnEvent` union — on either side.** It has a schema component, it has a Pydantic model, and neither is reachable from the union that `tests/test_rpc_schema_match.py` walks. The 290-test contract guard has never looked at this event.

So it drifted the first time anyone touched it. `05957452` (judge a dag node) taught `announce_dag_exception` to emit:

```python
mark = {"kind": "dag", "label": run_id, "status": "exception", "run_id": run_id, "node_id": node_id}
```

while `TurnStartedEvent.payload.delegated` still declared `status: enum ["ok","error"]` with `additionalProperties: false`, and `TurnStartedPayload` had **no `delegated` field at all** under `extra="forbid"`. Verified with `jsonschema` against the published contract before changing anything:

```
Additional properties are not allowed ('node_id' was unexpected)
```

That commit did carry `exception` into `TranscriptDelegated` and `SubagentDeliveredEvent` — two of the three places this status lives. The third is the one no test covers.

**It does not crash today**, and I want to be exact about that: `SubscriptionEmitter.emit` pushes a raw dict with no validation, and the page reads only the fields it knows. But the contract test's own docstring says what the cost is — *"both sides declare `additionalProperties: false` / `extra="forbid"`, so a consumer validating against the schema rejects the whole event, not just the unknown field"*. Losing this event loses the boundary that advances the workspace turn counter and draws the delegated row.

## What this does

- `TurnStartedEvent` joins the `TurnEvent` union, in `openrpc.json` and in `raven/rpc/models.py`, so the existing sweep covers it from now on.
- The schema's `delegated.status` gains `exception`; `node_id` is declared.
- `TurnStartedPayload` gains `delegated` as a typed model (`TurnStartedDelegated`), three-valued status included.
- Both generated TypeScript clients regenerated.
- A new test drives **the exact marker `manager.py` builds** through both validators, so the next status or field fails here instead of in a client nobody is watching.

## One thing the union surfaced

`ui-tui` never handled `turn.started`. Its exhaustiveness check said so the moment the variant existed. It draws the delegated row from `subagent.delivered`, which the page deliberately ignores in favour of this event — the two mark different moments: **submitted** versus **started**.

Left as it is, with an explicit `case 'turn.started'` saying why. Moving that surface onto the truer moment changes when the TUI draws the row, which is a product change, not a contract fix.

## Verification

- New test red before the fix, by construction: adding the variant to the union alone reds `test_schema_match_turn_event_discriminated_union` and `..._payload_fields` (schema/pydantic drift), which is how the gap was proved.
- Mutation checks, each reverting one thing:

| reverted | reds |
|---|---|
| `exception` out of the schema enum | 1 |
| `node_id` out of the schema | 1 |
| `delegated` off the Pydantic payload | 2 |

- `uv run pytest -q` — **12900 passed**, 50 skipped, 5 failed; the same five pre-existing on `origin/main` (four `test_security_network.py` NAT64 cases, one `test_doctor_answers_where_the_memories_are`), reproduced on an untouched merge-base worktree.
- `uv run ruff check` / `ruff format --check` on `raven tests scripts` — both clean (both halves of `make lint-python`).
- `ui`: `gen:check` 147 methods, `type-check` clean, `npx vitest run` 89 files / **1225 passed**.
- `ui-tui`: `type-check` clean, `lint:rpc` in sync, `lint:i18n` up to date, `npm test` 138 files / **1990 passed**.
  - Worth recording: with `ui-tui/node_modules` symlinked from another checkout the suite reports 82 failed / 59 failed — and reports **the same numbers on an untouched `origin/main`**. It is the symlink, not the branch. Ran `npm ci` in the worktree to get a trustworthy number.
- `scripts/commit_lint` — no errors.
- `git ls-files | grep -c node_modules` — 0.

## Type

- [x] Fix

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear

Widening a contract to match what the runtime already emits: every payload valid before is valid now. No emit site changes, no behaviour changes. The one code change outside the schema and the models is an explicit no-op branch in `ui-tui`. Rollback is a revert.
2026-08-28 12:51:10 +00:00
forrestjgq
8ecfae3e0c test(tracing): isolate span emission into per-test tmp dirs (#371)
## Summary

Unit tests were leaking tracing spans into the real `~/.raven/traces`
store. Tracing is on by default and `trace.span()` calls are embedded in
library code (agent loop, subagents, TUI RPC), so any test exercising
those paths emitted spans with fabricated session keys (`session-a`,
`weixin:c`, `tui:default`, ...). Those spans then surfaced as phantom
sessions in `raven trajectory`, while the TUI `/sessions` list (which
reads the real session store) stayed clean.

This PR adds an autouse fixture in `tests/conftest.py` that:

- redirects `RAVEN_TRACING_DIR` to a per-test tmp directory, and
- resets the lazy module-level `TraceStore` cache
(`raven.tracing.spans._store`) around each test, since it pins the
directory resolved at first emit.

Key decisions:

- Only the directory is redirected, not the enabled switch, so the suite
keeps exercising the real emission path with zero behavior change; leaks
land in tmp instead.
- This centralizes the setenv-plus-cache-reset pattern that 8
tracing/trajectory test files already perform manually. Those tests keep
working: their own `monkeypatch.setenv` runs after the fixture and wins,
and they already reset the cache themselves.
- Existing phantom sessions come from archived span logs written before
this fix; the fixture only prevents new leaks. One archive file mixes a
real session with test keys, so cleanup needs line-level filtering and
is left out of scope.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other

Test-suite hygiene (`test` commit type).

## Verification

- `uv run pytest tests/test_tracing_api.py
tests/test_trajectory_store.py tests/test_trajectory_bundle.py
tests/test_trajectory_replay.py tests/test_trajectory_redact.py
tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py -q`: 308 passed, 1 failed
(`test_viewer_health_true_for_our_viewer`, fails identically on
unmodified `main`, environment-specific)
- `uv run pytest tests/test_agent_loop_run_emit.py
tests/test_subagent_manager.py tests/test_tui_rpc_turn_send.py
tests/test_deep_research_tool.py tests/test_agent_loop_approval.py -q`:
109 passed; the real `~/.raven/traces` log did not grow during the run
- Positive check: running `tests/test_agent_loop_run_emit.py` with
`--basetemp` shows the previously leaked session keys (`cli:c`, `tg:c`,
`weixin:c`) now land in per-test tmp dirs
- `uv run pytest tests/ --ignore=tests/integration -q`: 6837 passed, 11
failed, 20 errors; the same failure set reproduces on unmodified `main`
(environment-specific: cron/tz, everos server, theme, config loader,
viewer health), zero regressions from this change
- `uv run ruff check tests/conftest.py` and `uv run ruff format --check
tests/conftest.py`: both pass

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Docs box left blank: test-only change, no user-facing docs affected.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

Test-only change; no production code touched. One known interaction:
`RAVEN_TRACING_DIR` takes precedence over `RAVEN_HOME`, so a future test
that fakes `RAVEN_HOME` and expects traces under it must also set
`RAVEN_TRACING_DIR` itself. Rollback: revert the single commit.

## Related Issues

N/A

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-28 19:21:16 +08:00
arelchan
7c33c4133a fix(rpc): let the viewer open the files a turn actually wrote
## Summary

A delivered artifact could not be opened from the page: the file viewer answered
403 and the transcript drew "Raven is confined to the workspace, so this file
cannot be opened here" over a delivery card it had just rendered.

The viewer's state-directory fence exempts the workspace subtree, on the stated
grounds that the default workspace lives inside raven's home and denying it
would refuse every file the agent itself wrote. Since agent home and the working
directory were split apart, a turn no longer writes there: it writes in
`~/.raven/tmp/<channel>`, a sibling of the workspace, inside the same state root
and outside the carve-out. So the fence denied exactly what the carve-out exists
to allow, one directory over, for every artifact produced since that split.

This exempts the working-directory root alongside the workspace, using the same
containment test in the same direction, so a working-directory root that happens
to sit above raven's home earns no exemption. `config.json`, `oauth/` and
`serve.json` are siblings of both and stay refused, which is what the fence is
for.

Worth noting for a reviewer: the bytes were already reachable. `/files/download`
serves a delivered file by token with no path fence, so this was never a
security boundary for deliveries -- only a viewer that refused to render what
the same page could already download.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `uv run pytest tests/test_rpc_transport.py tests/test_rpc_files.py tests/test_rpc_knowledge.py tests/test_rpc_console.py -q` -> 123 passed
- `uv run ruff check` and `uv run ruff format --check` on both changed files -> clean
- Both new assertions were mutation-checked, each against its own mutation:
  - narrowing the carve-out back to the workspace alone reds
    `test_the_turn_working_directory_is_exempt_from_the_state_dir_fence` only (1 failed, 3 passed)
  - dropping the containment-direction guard reds
    `test_a_working_directory_root_that_contains_the_state_root_earns_no_exemption`
    and the pre-existing state-dir test (2 failed, 2 passed)
- Against the real reporting case: the two files that were answering 403
  (`~/.raven/tmp/tui/*.md`, `*.pptx`) now resolve, while `~/.raven/config.json`
  and `~/.raven/serve.json` still raise PermissionError.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

- Widens what the file viewer will render by exactly one subtree: the directory
  turns work in. Everything the fence was written to protect (provider keys in
  `config.json`, the OAuth token store, `serve.json`) sits beside that subtree,
  not inside it, and stays refused -- pinned by the tests above.
- `fs.list` / `fs.reveal` share the function but pass the session's working
  directory as the root, which their own containment check already bounds, so
  their behaviour is unchanged.
- Rollback is a one-line revert of the exemption tuple.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-08-28 04:57:29 +00:00
LivXue
4e35a5d627 fix(tui): show the copy-on-select confirmation as a transient notice (#366)
## Summary

PR #360 reports every copy-on-select write as a permanent transcript
line, so a
reading session that drags through the transcript piles up "copied N
characters" rows under the conversation. The confirmation splits by what
the
line is for: the unbounded terse repeats become a transient notice
rendered
above the input box -- one line that replaces itself on every new copy
and
clears after 3 seconds -- while the first copy of a session keeps its
path
caveat in the transcript. The caveat is the answer a user comes looking
for
after a paste comes up empty minutes later, and it cannot pile up
because it
is once per session by construction.

The reporter still owns the per-session caveat tally and now returns
`{ text, firstOfSession }` so the caller can route the caveat to the
transcript and the repeats to the notice. A new `copyNoticeStore` holds
the
single notice; `showCopyNotice` keeps one dismiss timer, clearing any
pending
one before arming the next, so an earlier deadline can never clear a
newer
notice. `/copy` is deliberately untouched: an explicit command's answer
still
belongs in the transcript, and it cannot stack on its own.

## Type

- [x] Fix

## Verification

Run from `ui-tui/` at branch head, in a fresh worktree of `github/main`.
Dependencies came from `npm ci` in `ui-tui/` and in the hermes package;
the
hermes package's own `node_modules` holds only esbuild, so the ink
render
tests run against one react copy (two copies break every hook call).

```
npx vitest run --no-file-parallelism
  Test Files  93 passed (93)
  Tests  1084 passed | 13 skipped (1097)

npm run type-check
  clean, exit 0

npm run lint
  22 problems (0 errors, 22 warnings)

npx prettier --check src/app/copyNoticeStore.ts src/__tests__/copyNotice.test.tsx
  src/__tests__/clipboard.test.ts src/app/useMainApp.ts
  src/components/appLayout.tsx src/lib/clipboard.ts
  All matched files use Prettier code style!

python3 -m scripts.check_commit_messages github/main..HEAD
  exit 0
```

The 22 lint warnings are the baseline, not new: 22 before the branch and
22
after, none in a file this branch touches. The suite is run with
`--no-file-parallelism` deliberately: the ink render tests fail under
default
worker parallelism at this suite size, and no CI job runs them.

Suites that exercise the changed code directly:
`src/__tests__/copyNotice.test.tsx`
(7 cases), `src/__tests__/clipboard.test.ts` (30 cases, the 3 reporter
cases
updated to the new return shape).

New tests were proved load-bearing rather than assumed:

- Removing the notice render line in `appLayout.tsx` makes the render
test
  fail (content and placement above the input box).
- Removing the pending-timer clear in `showCopyNotice` makes the
re-shown-notice test fail: the earlier 3s deadline then clears the newer
  notice.
- The dismissed-notice case now shows a notice first, and removing
  `dismissCopyNotice`'s atom clear turns it red (review fix).

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No doc change. `ui-tui/CONTEXT.md` has no clipboard or selection entry,
and
"copy notice" continues the existing "notice" vocabulary of
`copyResultNotice`
/ `copyOnSelectNotice`, so nothing new is coined.

## Risk

Behaviour change: the per-drag copy confirmation is now transient and
above
the input box instead of a permanent transcript line, and the first copy
of a
session lands one transcript line, exactly as on `main`. Reverting the
branch
restores the #360 behaviour; no data or on-disk format is involved.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: Claude (deepseek-v4-pro) <noreply@anthropic.com>
2026-08-25 14:27:24 +08:00
gloryfromca
e86a7c9cb0 fix(*): take memory backend latency off the turn's critical path
## Summary

Two defects put the memory backend's latency on the conversation turn's critical path. Recorded in the issue ledger as 032 (recall has no timeout on the turn path) and 033 (the turn-completion signal waits for after-turn bookkeeping).

**Write side.** `_dispatch_backend_store` awaited the plugin write for up to five seconds inside the turn coroutine, and the coroutine returning is what emits `TurnEnded` and then `message.complete`. Measured on a local instance: the answer was fully on screen at 8.23s and the input box unlocked at 13.41s, with 5.00s of that gap being one `memory.store` that hit its budget on every single turn. The same code also cancelled writes outright once four were outstanding, so a fast typist silently lost turns.

It is now a synchronous enqueue onto a bounded per-session queue drained by its own worker. Serial per session is not optional: the everos write is an append followed by a flush, so concurrency within one session lets a later turn's flush overtake an earlier turn's append. Bounded at 64 records dropping the oldest, five attempts per record with 2/5/15/30 second backoff. Shutdown cuts retries short and then waits at most two seconds, so quitting is not held hostage by a worker asleep in a backoff.

**Read side.** The context engine awaited `backend.recall` with no bound at all, ahead of the model call, so a hung backend left the turn with nothing to show and no exit but a manual cancel. Recall now has a five second budget and degrades to no hits; the everos plugin's own timeout drops from eight seconds to four so its circuit breaker (which demotes the service and makes later turns cost nothing) fires before the outer cancellation. This deliberately replaces the segment's previous "hard failure propagates" contract, and the comments asserting that contract were updated with it.

`flush_every_turns` stays at 1, deliberately. It was raised to 4 mid-review, on the reasoning that a per-turn flush triggered a minute-scale extraction every turn; that reasoning stopped holding once the write left the turn's critical path. Only a flush makes everos extract, and the turn counter is per-process, so batching leaves a session that ends before the boundary never extracted -- a run of one to three turns, which is most of them on a desktop host, would learn nothing. Measured against a real everos: an add takes 3.6s and a flush 6.7s, and both now run behind the answer with the turn's own tail at 39 to 76ms.

**Accounting.** The retry loop broke several counts a user actually sees, all fixed here: a dropped-write message inflated roughly fivefold and firing for turns that succeeded on retry; a shutdown report that said zero while discarding everything still queued; a full queue shedding turns with no health signal, so a backend that was slow but eventually succeeded reset the failure streak on every write and the alarm could never fire; and an install with no memory service being told it lost turns it never had, after paying a minute of retries per turn to be told so. `BAD_IDENTITY` is deliberately excluded from that last case: that service works, the config is wrong, and the turns it refuses really are lost.

**Tracing.** A long-lived worker inherits the contextvars snapshot of whichever turn spawned it, so without care every `memory.store` span would be stamped with turn one's trace id forever. Each queued record now carries the trace context captured at enqueue, re-entered around that record's span. That needed one new primitive in the tracing facade, `trace.use_context(ctx)`, since nothing there could restore a captured context. The turn-side span is renamed `memory.enqueue` and the real write keeps `memory.store`, so the audit timeline still shows where the time goes.

**Known gaps, deliberately out of scope.** Retrying `store` is not idempotent against everos: a client-side timeout on `POST /memory/add` does not mean the server did not buffer the turn, so a retry can append it twice. Settling that needs the everos endpoint contract. Separately, `recall` is called twice per turn and the second caller (`SkillForgeRouter._safe_search`) still has no framework-level bound; today the plugin's own four second timeout covers it, but a third-party backend without one would still hang that path.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Commands run on this branch, rebased onto the current `main`:

- `uv run pytest tests/ -q` -- FULL The two warnings (a feishu never-awaited coroutine and a config deprecation) are on `main` too and are untouched by this branch.
- `uv run ruff check raven tests scripts` -- All checks passed
- `uv run ruff format --check raven tests scripts` -- 1208 files already formatted

New coverage pins the behavior that regressed or could regress: the turn returning before the write lands, same-session ordering under jittered write latency, ten quick turns all landing where the old in-flight cap dropped them, the five-attempt cap and its give-up accounting, the queue shedding the oldest when full, drain returning inside its budget while a write is backing off, drain still letting a quick write land, recall degrading on both a hang and a raise, the two recall budgets nesting strictly, the indexed slice being byte-identical to the persisted one, one health alarm per run of failed turns rather than per retry, and each write's span landing in its own turn's trace.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Not checked: no user-facing docs cover this path. `docs/TRACING_STANDARD_API.md` was corrected where it described `trace.current()`'s return type, which the new `use_context` row made load-bearing.

## Risk

User-visible changes:

- The input box unlocks when the answer finishes rather than after indexing. On the measured instance that is 13.41s down to roughly the answer's own completion.
- What reaches the memory index is now the persisted slice rather than the raw one, so a large tool result is truncated the same way the session log truncates it and inline images are stripped. Judgement is that this is a correction, but it changes what a backend receives.
- Extraction still runs on every turn, so memory freshness is unchanged. It now runs behind the answer instead of in front of the input box, which is the whole point. An install that configures batching still gets a shutdown flush for a session that ended before its boundary, bounded at five seconds.
- A turn whose write is still in flight when the process exits is lost: a real add takes about 3.6s and the drain budget is 2s, so quitting within a few seconds of the last answer costs that turn. At a human pace the writes land between turns; measured over six turns eight seconds apart against a real everos, all six landed and nothing was lost at exit.
- Recall failures no longer propagate. A turn whose recall times out or errors continues without recalled memory and says so in the log.
- Shutdown waits at most two seconds on memory writes rather than fifteen.
- The "turn(s) were not written to long-term memory" notice now comes from the agent loop's real give-up count instead of the plugin's per-attempt one.

Rollback: revert the commit range. Nothing persists to disk and no format changed, so a revert needs no migration. The one shared-surface addition is `trace.use_context`, which has a single caller.

## Related Issues

N/A

Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
2026-08-28 11:21:30 +08:00
arelchan
bb96e4dd08 feat(tracing): in-tree tracing subsystem with decoupled adopter contract (#135)
## Summary

Add an in-tree tracing subsystem and adopt it across raven, giving every
run
a structured `audit.span.v1` trace (turn -> model / tool / memory /
skill /
subagent) viewable in a bundled dashboard.

The design keeps raven and tracing decoupled so they can iterate
independently,
coupled only by a small contract:

- **tracing owns the standard.** `raven/tracing` exposes a thin facade
(`trace.span` / `@trace.instrument`) over an `audit.span.v1` record
format,
a set of semantic conventions, and a dependency-free Node viewer. Custom
nodes are supported with no registration (any owned `<domain>.<verb>`
name).
- **raven adopts it as a pure consumer.** Instrumentation is one import
+ one
`@trace.instrument` decorator per method; **method bodies are
untouched**.
Purposes self-nest via contextvars, so a model call under `skill.gate`,
`memory.extract`, `subagent.run`, etc. is distinguished by its parent
node
  and by a derived `llm.invocation_source` (nearest non-model ancestor).
- **tracing can never break raven.** The facade is no-op when disabled
(`[tracing]` config or `RAVEN_TRACING=0`) and swallows its own failures
while
  re-raising the application's exception unchanged.

Open the dashboard with `raven tracing` (or `/tracing` in the TUI).

Key node behavior: all skill pulls (`use_skill` / `read_skill` / a
`read_file`
of a SKILL.md) unify into one `skill.read` node, differentiated by
content
(`skill.read.via_tool`, and `skill.scripts_dir` when a runnable bundle
was
materialized) rather than by tool name.

## Type

- [x] Feature

## Verification

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

Commands run:

- `uv run pytest tests/test_tracing_api.py -q` -> 20 passed (nesting,
kinds,
  attributes, artifacts, retype, invocation_source, and the frozen
  contract + non-interference gates).
- `uv run pytest tests/ -q` -> 4091 passed, 85 failed, 12 errors. The
failures
are pre-existing and unrelated: an identical run with `RAVEN_TRACING=0`
(this
change fully inert) produces the byte-identical failing set, so this
change
adds zero failures. The failures are environment-only (TUI subprocess
e2e,
EverOS real-LLM, sandbox VM, npx MCP) plus a pre-existing async-mock
ordering
  issue in the sentinel/attention suite (passes in isolation).
- `uv run ruff check` / `uv run ruff format` -> clean.
- Verified at runtime: raven core diff is annotation-only (each touched
file is
+2 lines: one import, one decorator); disabled pass-through and
internal-
  failure isolation confirmed by dedicated tests.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

Backward compatibility: additive only. No existing behavior changes;
tracing is
observation-only and defaults can be turned off with `RAVEN_TRACING=0`.
Rollback: revert the branch, or disable via config; raven runs
identically
without it. Note: `raven/tracing/instrument.py` monkeypatch path is
gone; all
instrumentation is explicit decorators in raven's own source.

Coverage note: the personalizer's four steps (which call `provider.chat`
directly) are instrumented as `personalize.*` purpose spans, so no model
activity is untraced. The only remaining follow-up is the standalone-OSS
extraction (import-optional shim, move raven-specific extractors out,
drop raven
branding) -- a planned separate phase that ships tracing as its own
package,
out of scope for this PR.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
2026-07-16 18:28:52 +08:00