## 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
## 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
## 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
## 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
## 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
## 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
## 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).
## 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).
## 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
## 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
## Summary
A playbook that carries its own MCP server (`mcpServers:` in the spec) needs that server's credential at run time, and a conversation is the one place a credential may not pass. On the TUI/WebUI path there was no other entry: a `type: secret` param was collected by the model in chat (and so landed in the transcript), and a carried `auth: oauth` server was refused by the grant because the host never connects it. The CLI already had its own pre-flight; this PR gives the conversation path an equivalent.
Both credential kinds now live on the machine, keyed by playbook, under the credentials root the host's own MCP OAuth tokens use:
- secret params: `<credentials>/playbooks/<name>/params.json` (0600). Written from the playbook page's new Credentials tab or `raven playbook secret set <name> <PARAM>` (prompted without echo; `--value` is available but visible in `ps`). Read at load and again on every dispatch, so a value stored after a node failed reaches that node when it is continued.
- OAuth tokens: `<credentials>/playbooks/<name>/mcp/<server>.json`. Minted by the tab's Authorize button or `raven playbook auth <name> <server>`, always under the playbook's scope, so a carried server never shares a token file with a host server of the same name (a carried `sentry` may shadow the host's `sentry`).
Behaviour the user sees:
- A secret is never a gap and never "required" in the tool description. The listing says "stored on this machine -- do not ask for it" or "not set on this machine -- the user sets it on the playbook page, do not ask for it". An unset one is mentioned in the load reply and the run goes ahead without the server it fills (an unresolved `{{ params.X }}` header/env entry is dropped, never dialed literally).
- A carried OAuth server without tokens is mentioned in the load reply, and the failed node's note says which playbook's tab holds the authorization and that `continue` is enough after it.
- The grant checks the scoped token file for a carried OAuth server instead of the host connection state it does not have; `_bridged_auth` dials with the scoped provider.
Plumbing:
- `raven/playbook/credentials.py` (new): the store. `dag_mcp_scope` now carries the run's credential scope and takes a callable for the definitions so they are re-rendered per dispatch. `McpServerView`/`GrantedServer`/`MissingServer` carry `scope`. `credentials_path`/`FileTokenStorage`/`provider_for`/`MCPConnectionManager` take an optional scope.
- RPC: `playbooks.credentials.get/set/clear`, `playbooks.oauth.authorize/clear` (`rpc-schema/openrpc.json` + generated clients). `get` returns names and booleans only, never a value.
- WebUI: Credentials tab on the playbook detail (shown only when the playbook has a secret param or an OAuth server), with password inputs, Authorize/re-authorize/clear, a "shadows host" badge and the parked authorization link.
- The per-session MCP manager a sub-agent builds inside `session/new` gets a 45s handshake bound, under the host's 60s budget, so a wedged upstream costs that session one server instead of the whole session.
CLI path (`raven playbook run`), after review: the pre-flight folds stored secret params into the definitions it renders, dials carried servers under the playbook's credential scope (per-name scope on `MCPConnectionManager`) and host servers under the host's, and the source it yields reports that same scope so the bridged node's endpoint dials under it too. Carried server names are admitted only as plain filenames and `credentials_path()` refuses anything else on every read and write; an equal carried/host OAuth definition no longer folds onto the host connection.
Continuing a failed node after its credential landed: the pre-flight used to hand every attempt the grant it resolved before the store, so the continued node dialled headerless again (found end to end, fixed in the last commit: the grant is resolved per attempt). Verified on the TUI: node fails without the secret, the secret is stored, `continue` is chosen, the re-dispatched attempt reaches the server.
Known limitation, not introduced here: on both frontends the model's `resolve_dag_node` call is refused when it happens in the turn a sub-agent's failure report opened (`raven/permissions/gate.py`: `turn.responder is None`, "this turn is not interactive"), so the continue above could only be driven with `permissions.tools.resolve_dag_node: allow` in the test config. The decision flow after a node failure is otherwise stuck on the TUI/WebUI path at `origin/main` too. Worth its own issue.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Unit and lint, on the rebased branch:
- `uv run --all-extras pytest -q`: 20145 passed, 1 failed, 165 skipped in 5m03s. The one failure was `test_core_runtime_swap::test_the_generation_doors_have_exactly_their_declared_operators`, caused by this branch (the authorize method reached `loop.mcp_manager` to reuse its oauth-event sink); fixed in the follow-up commit by dropping the relay, after which `tests/test_rpc*.py tests/test_core_runtime_swap.py tests/test_playbook*.py` pass (2099 passed). The 165 skips are the pre-existing ppt-engine template-payload skips, unrelated to this PR.
- `make lint-python`, `make lint-ui`, `make lint-tui`: pass
- `cd ui-web && npm run type-check && npx vitest run && npm run build`: 1536 tests pass, build ok
- `npm run gen` (ui-web) / `npm run gen:rpc && npm run gen:i18n` (ui-tui): regenerated output committed
- Hands-on pass of the acceptance manual with a person driving the page, on a build carrying both this branch and !634: it found the missing-credential silence above, and an unstable reply where the model sometimes advised setting the secret instead of starting the run. Both fixed here.
- After the review fixes: `tests/test_rpc*.py tests/test_core_runtime_swap.py tests/test_playbook*.py tests/test_subagent_mcp_grant.py tests/test_subagent_dag_mcp_scope.py tests/test_mcp_manager.py tests/test_cli_playbook_commands.py tests/test_mcp_oauth*.py`: 2279 passed; `make lint-python` clean. Each isolation fix was reverse-verified (fix removed, its test red at the claimed symptom).
End to end, against a local streamable-HTTP MCP server that answers 401 without `Authorization: Bearer <token>` and a carried Sentry MCP server whose tokens sit in the playbook-scoped file; the sub-agent is Raven-Oncall from `agents/`:
| Scenario | TUI | WebUI | Evidence |
|---|---|---|---|
| secret stored (CLI / Credentials tab) -> carried header server delivered | pass | pass | node answers `CALLED=mcp_tokened_whoami GOT=authorized caller: tokened-probe`; host reply says the value was filled from local credentials, does not ask for it |
| secret unset -> run not blocked, reminder, model does not ask | pass | same executor code | host reply names the param and the Credentials tab; node runs with no tools |
| secret set afterwards -> next run delivered | pass | pass | as row 1 |
| carried OAuth with scoped tokens -> delivered | pass | pass | `CALLED=find_organizations GOT=1 org` |
| carried OAuth unauthorized -> not delivered, note, load reminder | pass | pass | node note "carried by playbook 'carried-oauth' -- authorize it on that playbook's MCP tab"; host reply says it is not authorized on this machine |
| Credentials tab: clear / save / Authorize | - | pass | file 0600 with the typed value, no echo in the DOM; Authorize returns the parked URL and creates the scoped file, the host's `sentry.json` untouched |
| leakage | pass | pass | token absent from the day's session and trace files and from `ps` |
| CLI `raven playbook run`: stored secret -> carried header server delivered | CLI | - | pre-flight connects `tokened` with the stored value, node answers `CALLED=mcp_tokened_whoami` |
| CLI `raven playbook run`: carried OAuth with scoped tokens -> delivered, no host-scope file | CLI | - | `CALLED=find_organizations`; no `<credentials>/mcp/sentry-carried-test.json` appears (before the last fix the node's endpoint re-dialled unscoped and left one) |
| WebUI carried token and carried OAuth on the final head (fresh gateway, port owner start time checked) | - | pass | `CALLED=mcp_tokened_whoami`; `CALLED=find_organizations`; no host-scope file |
| TUI: node fails without the secret -> secret stored -> `continue` -> re-dispatched attempt delivered | pass | - | attempt-1 `TOOLS=<none>`, attempt-2 `CALLED=mcp_tokened_whoami GOT=authorized caller: tokened-probe` (with `resolve_dag_node` allow-tier in the test config, see limitation) |
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs exist for playbook credentials yet)
## Risk
- Security: secret values are written only to 0600 files under `~/.raven/credentials/playbooks/<name>/`; the RPC `get` and the CLI listing never return a value; the value is substituted into headers/env at host dial time and never reaches the sub-agent, the playbook file, the transcript, or the command line (CLI prompts without echo unless `--value` is passed). A carried OAuth server's tokens never touch the host's bare-name token file.
- Backward compatibility: a playbook with no secret params and no OAuth server is unaffected (no tab, no scope, `mcp_scope=None`). Existing host MCP servers keep `scope=None` everywhere. `run_mcp_scope` still accepts a mapping.
- Behaviour change: a `required: true` secret param that is unset no longer stops the run with a gap; the run proceeds and says so. This is the intended fix for the secret-in-chat leak.
- Behaviour change: a node naming a carried server whose secret param has no value now runs without that server, and its note says where the credential is set. Before, the server was handed over and dialled with an incomplete credential, the upstream answered 401, and the sub-agent reported an empty tool list with nothing to say why -- which is what led a host agent, in a hands-on run, to ask the user for the token in the conversation. A carried OAuth server without tokens was already withheld for the same reason.
- Rollback: revert the squash commit; stored credential files are inert without the code.
## Related Issues
N/A
## Summary
A playbook that carries its own MCP server (`mcpServers:` in the spec) needs that server's credential at run time, and a conversation is the one place a credential may not pass. On the TUI/WebUI path there was no other entry: a `type: secret` param was collected by the model in chat (and so landed in the transcript), and a carried `auth: oauth` server was refused by the grant because the host never connects it. The CLI already had its own pre-flight; this PR gives the conversation path an equivalent.
Both credential kinds now live on the machine, keyed by playbook, under the credentials root the host's own MCP OAuth tokens use:
- secret params: `<credentials>/playbooks/<name>/params.json` (0600). Written from the playbook page's new Credentials tab or `raven playbook secret set <name> <PARAM>` (prompted without echo; `--value` is available but visible in `ps`). Read at load and again on every dispatch, so a value stored after a node failed reaches that node when it is continued.
- OAuth tokens: `<credentials>/playbooks/<name>/mcp/<server>.json`. Minted by the tab's Authorize button or `raven playbook auth <name> <server>`, always under the playbook's scope, so a carried server never shares a token file with a host server of the same name (a carried `sentry` may shadow the host's `sentry`).
Behaviour the user sees:
- A secret is never a gap and never "required" in the tool description. The listing says "stored on this machine -- do not ask for it" or "not set on this machine -- the user sets it on the playbook page, do not ask for it". An unset one is mentioned in the load reply and the run goes ahead without the server it fills (an unresolved `{{ params.X }}` header/env entry is dropped, never dialed literally).
- A carried OAuth server without tokens is mentioned in the load reply, and the failed node's note says which playbook's tab holds the authorization and that `continue` is enough after it.
- The grant checks the scoped token file for a carried OAuth server instead of the host connection state it does not have; `_bridged_auth` dials with the scoped provider.
Plumbing:
- `raven/playbook/credentials.py` (new): the store. `dag_mcp_scope` now carries the run's credential scope and takes a callable for the definitions so they are re-rendered per dispatch. `McpServerView`/`GrantedServer`/`MissingServer` carry `scope`. `credentials_path`/`FileTokenStorage`/`provider_for`/`MCPConnectionManager` take an optional scope.
- RPC: `playbooks.credentials.get/set/clear`, `playbooks.oauth.authorize/clear` (`rpc-schema/openrpc.json` + generated clients). `get` returns names and booleans only, never a value.
- WebUI: Credentials tab on the playbook detail (shown only when the playbook has a secret param or an OAuth server), with password inputs, Authorize/re-authorize/clear, a "shadows host" badge and the parked authorization link.
- The per-session MCP manager a sub-agent builds inside `session/new` gets a 45s handshake bound, under the host's 60s budget, so a wedged upstream costs that session one server instead of the whole session.
CLI path (`raven playbook run`), after review: the pre-flight folds stored secret params into the definitions it renders, dials carried servers under the playbook's credential scope (per-name scope on `MCPConnectionManager`) and host servers under the host's, and the source it yields reports that same scope so the bridged node's endpoint dials under it too. Carried server names are admitted only as plain filenames and `credentials_path()` refuses anything else on every read and write; an equal carried/host OAuth definition no longer folds onto the host connection.
Continuing a failed node after its credential landed: the pre-flight used to hand every attempt the grant it resolved before the store, so the continued node dialled headerless again (found end to end, fixed in the last commit: the grant is resolved per attempt). Verified on the TUI: node fails without the secret, the secret is stored, `continue` is chosen, the re-dispatched attempt reaches the server.
Known limitation, not introduced here: on both frontends the model's `resolve_dag_node` call is refused when it happens in the turn a sub-agent's failure report opened (`raven/permissions/gate.py`: `turn.responder is None`, "this turn is not interactive"), so the continue above could only be driven with `permissions.tools.resolve_dag_node: allow` in the test config. The decision flow after a node failure is otherwise stuck on the TUI/WebUI path at `origin/main` too. Worth its own issue.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Unit and lint, on the rebased branch:
- `uv run --all-extras pytest -q`: 20145 passed, 1 failed, 165 skipped in 5m03s. The one failure was `test_core_runtime_swap::test_the_generation_doors_have_exactly_their_declared_operators`, caused by this branch (the authorize method reached `loop.mcp_manager` to reuse its oauth-event sink); fixed in the follow-up commit by dropping the relay, after which `tests/test_rpc*.py tests/test_core_runtime_swap.py tests/test_playbook*.py` pass (2099 passed). The 165 skips are the pre-existing ppt-engine template-payload skips, unrelated to this PR.
- `make lint-python`, `make lint-ui`, `make lint-tui`: pass
- `cd ui-web && npm run type-check && npx vitest run && npm run build`: 1536 tests pass, build ok
- `npm run gen` (ui-web) / `npm run gen:rpc && npm run gen:i18n` (ui-tui): regenerated output committed
- Hands-on pass of the acceptance manual with a person driving the page, on a build carrying both this branch and !634: it found the missing-credential silence above, and an unstable reply where the model sometimes advised setting the secret instead of starting the run. Both fixed here.
- After the review fixes: `tests/test_rpc*.py tests/test_core_runtime_swap.py tests/test_playbook*.py tests/test_subagent_mcp_grant.py tests/test_subagent_dag_mcp_scope.py tests/test_mcp_manager.py tests/test_cli_playbook_commands.py tests/test_mcp_oauth*.py`: 2279 passed; `make lint-python` clean. Each isolation fix was reverse-verified (fix removed, its test red at the claimed symptom).
End to end, against a local streamable-HTTP MCP server that answers 401 without `Authorization: Bearer <token>` and a carried Sentry MCP server whose tokens sit in the playbook-scoped file; the sub-agent is Raven-Oncall from `agents/`:
| Scenario | TUI | WebUI | Evidence |
|---|---|---|---|
| secret stored (CLI / Credentials tab) -> carried header server delivered | pass | pass | node answers `CALLED=mcp_tokened_whoami GOT=authorized caller: tokened-probe`; host reply says the value was filled from local credentials, does not ask for it |
| secret unset -> run not blocked, reminder, model does not ask | pass | same executor code | host reply names the param and the Credentials tab; node runs with no tools |
| secret set afterwards -> next run delivered | pass | pass | as row 1 |
| carried OAuth with scoped tokens -> delivered | pass | pass | `CALLED=find_organizations GOT=1 org` |
| carried OAuth unauthorized -> not delivered, note, load reminder | pass | pass | node note "carried by playbook 'carried-oauth' -- authorize it on that playbook's MCP tab"; host reply says it is not authorized on this machine |
| Credentials tab: clear / save / Authorize | - | pass | file 0600 with the typed value, no echo in the DOM; Authorize returns the parked URL and creates the scoped file, the host's `sentry.json` untouched |
| leakage | pass | pass | token absent from the day's session and trace files and from `ps` |
| CLI `raven playbook run`: stored secret -> carried header server delivered | CLI | - | pre-flight connects `tokened` with the stored value, node answers `CALLED=mcp_tokened_whoami` |
| CLI `raven playbook run`: carried OAuth with scoped tokens -> delivered, no host-scope file | CLI | - | `CALLED=find_organizations`; no `<credentials>/mcp/sentry-carried-test.json` appears (before the last fix the node's endpoint re-dialled unscoped and left one) |
| WebUI carried token and carried OAuth on the final head (fresh gateway, port owner start time checked) | - | pass | `CALLED=mcp_tokened_whoami`; `CALLED=find_organizations`; no host-scope file |
| TUI: node fails without the secret -> secret stored -> `continue` -> re-dispatched attempt delivered | pass | - | attempt-1 `TOOLS=<none>`, attempt-2 `CALLED=mcp_tokened_whoami GOT=authorized caller: tokened-probe` (with `resolve_dag_node` allow-tier in the test config, see limitation) |
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs exist for playbook credentials yet)
## Risk
- Security: secret values are written only to 0600 files under `~/.raven/credentials/playbooks/<name>/`; the RPC `get` and the CLI listing never return a value; the value is substituted into headers/env at host dial time and never reaches the sub-agent, the playbook file, the transcript, or the command line (CLI prompts without echo unless `--value` is passed). A carried OAuth server's tokens never touch the host's bare-name token file.
- Backward compatibility: a playbook with no secret params and no OAuth server is unaffected (no tab, no scope, `mcp_scope=None`). Existing host MCP servers keep `scope=None` everywhere. `run_mcp_scope` still accepts a mapping.
- Behaviour change: a `required: true` secret param that is unset no longer stops the run with a gap; the run proceeds and says so. This is the intended fix for the secret-in-chat leak.
- Behaviour change: a node naming a carried server whose secret param has no value now runs without that server, and its note says where the credential is set. Before, the server was handed over and dialled with an incomplete credential, the upstream answered 401, and the sub-agent reported an empty tool list with nothing to say why -- which is what led a host agent, in a hands-on run, to ask the user for the token in the conversation. A carried OAuth server without tokens was already withheld for the same reason.
- Rollback: revert the squash commit; stored credential files are inert without the code.
## Related Issues
N/A
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
Ruff carried no complexity rule, so nothing bounded the number of paths through
a function. This adds `C901` with a ceiling chosen to stop the untestable and
nothing else.
**What the number means.** Cyclomatic complexity is the count of linearly
independent paths through a function, which makes it the floor on how many cases
a suite needs to walk them all. A body with a hundred of them has paths nobody
will ever write a case for, and those paths are first executed in production.
That is the failure this rule prevents; it is not a style preference.
Two properties of the metric matter for reading the numbers below. A nested
function's score is counted into its enclosing function as well as reported on
its own, so an outer function with no branches of its own scores one more than
the inner function it holds. And Ruff reports `C901` only when the score is
*greater* than `max-complexity`, so a function at exactly 40 passes a ceiling of
40 and needs no suppression.
**Where 40 comes from.** The measured distribution, not McCabe's recommendation
of 10:
| max-complexity | functions flagged |
|---|---|
| 10 | 253 |
| 25 | 26 |
| 30 | 17 |
| **40** | **9** |
| 50 | 5 |
Ten would flag 253 functions and be switched off within the week. Forty is not a
claim that 39 is fine -- it is where a function stops being complex and starts
being untestable. Tightening later means lowering the number, which is a
reviewed edit to `pyproject.toml`.
**The nine over the ceiling.** Each carries a `noqa: C901` naming its actual
score. Seven are in `raven/`, two in the oncall-flow plugin under `agents/`:
```
100 raven/agent/loop/turn_path.py _run_agent_loop
87 raven/cli/gateway_commands.py register
86 raven/cli/gateway_commands.py gateway
69 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
68 raven/cli/gateway_commands.py run
54 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
47 raven/agent/loop/turn_path.py _process_message
46 raven/config/loader.py _migrate_config
41 raven/agent/loop/turn_path.py _run_turn
```
A tenth suppression sits on `benchmarks/proactivity_eval/runners/_common/longrun_adapters.py`
(`tick_to`, 41). `benchmarks/` is outside `PYTHON_LINT_TARGETS` and so outside
CI, but inside what the pre-commit Ruff hook sees on a changed file -- marking it
means the gate does not ambush whoever next edits that adapter.
**Nine entries, fewer distinct problems.** In `gateway_commands.py` the three
are nested inside each other at indent 0, 4 and 8: `run` at 68 is the body,
`gateway` adds its own branches on top, and `register` contributes about one. In
`turn_path.py` the three are sibling methods, but `_run_turn` holds ten nested
callbacks (`on_token`, `on_tool`, `on_progress` and so on) which is most of its
41. The one that is a large body by itself is `_run_agent_loop`: 1134 lines with
only two nested functions, so its 100 is its own.
Per-function rather than per-file, on purpose: a whole-file ignore on
`gateway_commands.py` would let a new 80-path function in the same file through,
while these entries do not. The score is in the comment so the debt is visible
where the code is, not parked in a config file.
Nothing has to be refactored to land this. Normal work is undisturbed unless
someone writes a forty-one-path function.
**Why the PLR09xx rules are left out.** They count arguments (230 occurrences
here), branches (125), statements (78) and returns (81). All four are proxies
for what `C901` measures directly, so adding them would report one fact four
times and bury the signal under 230 argument-count warnings.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: a lint gate plus the `noqa` entries that let it land green. No runtime
code changes; every production edit is an end-of-line comment.
## Verification
Verified against the lint roster read out of the Makefile
(`PYTHON_LINT_TARGETS = raven evolver agents plugins-dist tests scripts`) rather
than a chosen subset, and then against the whole tree. The first revision of
this MR checked only `raven/` and went red in CI on the two `agents/` functions;
that is what the roster-wide check exists to prevent.
```
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
raven evolver agents plugins-dist tests scripts
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache .
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
--extend-select RUF100 raven evolver agents plugins-dist tests scripts
(no unused C901 directive)
$ uv run --frozen --python 3.12 --extra dev ruff format --check \
raven evolver agents plugins-dist tests scripts
1886 files already formatted
$ uv run --frozen --python 3.12 pytest tests/ -q -k "turn_path or gateway or loader or console or config_precedence"
511 passed, 19 skipped
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The 19 skips are pre-existing and environmental: `test_provider_resolution_invariants.py`
skips its gateway-only cases when no gateway is configured.
Checked in the failing direction, since a gate never seen red is not known to
work. A fresh forty-branch function appended to `config/loader.py` is reported,
and the `noqa` on `_migrate_config` in the same file keeps holding rather than
being swallowed by it:
```
raven/config/loader.py:1088:5: C901 `_probe_over_ceiling` is too complex (41 > 40)
Found 1 error.
```
The probe was reverted. Note for the reviewer: reverting that file also reverted
its `noqa`, which the roster-wide check caught immediately.
One entry was removed after review rather than kept: `settings_usage` scores
exactly 40, which a ceiling of 40 does not flag, so its suppression was dead.
`--extend-select RUF100` reports such a directive as unused, and keeping it would
have defeated the documented tightening path -- lowering the number later would
have left that function exempt with nothing to show it.
The production diff is comment-only and can be read as such:
```
- async def _run_agent_loop(
+ async def _run_agent_loop( # noqa: C901 (cc 100: pre-existing, above the ceiling)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No behaviour change: every production edit is an end-of-line comment, and the
diff can be verified as such. The risk this carries is a false sense of
coverage, which is why the rationale in `pyproject.toml` states what the ceiling
does not mean. Two limits of the metric are worth a reviewer knowing: it does
not see nesting depth (five sequential `if`s and five nested ones both score 6),
and in Ruff's implementation boolean operators, ternaries and comprehension
conditions do not count at all. It is a filter for the untestable, not a
readability score.
Rollback is reverting the commits. Loosening instead of reverting is a one-line
change to `max-complexity`, which is the intended escape if the gate turns out
to obstruct real work.
## Related Issues
N/A
## Summary
Ruff carried no complexity rule, so nothing bounded the number of paths through
a function. This adds `C901` with a ceiling chosen to stop the untestable and
nothing else.
**What the number means.** Cyclomatic complexity is the count of linearly
independent paths through a function, which makes it the floor on how many cases
a suite needs to walk them all. A body with a hundred of them has paths nobody
will ever write a case for, and those paths are first executed in production.
That is the failure this rule prevents; it is not a style preference.
Two properties of the metric matter for reading the numbers below. A nested
function's score is counted into its enclosing function as well as reported on
its own, so an outer function with no branches of its own scores one more than
the inner function it holds. And Ruff reports `C901` only when the score is
*greater* than `max-complexity`, so a function at exactly 40 passes a ceiling of
40 and needs no suppression.
**Where 40 comes from.** The measured distribution, not McCabe's recommendation
of 10:
| max-complexity | functions flagged |
|---|---|
| 10 | 253 |
| 25 | 26 |
| 30 | 17 |
| **40** | **9** |
| 50 | 5 |
Ten would flag 253 functions and be switched off within the week. Forty is not a
claim that 39 is fine -- it is where a function stops being complex and starts
being untestable. Tightening later means lowering the number, which is a
reviewed edit to `pyproject.toml`.
**The nine over the ceiling.** Each carries a `noqa: C901` naming its actual
score. Seven are in `raven/`, two in the oncall-flow plugin under `agents/`:
```
100 raven/agent/loop/turn_path.py _run_agent_loop
87 raven/cli/gateway_commands.py register
86 raven/cli/gateway_commands.py gateway
69 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
68 raven/cli/gateway_commands.py run
54 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
47 raven/agent/loop/turn_path.py _process_message
46 raven/config/loader.py _migrate_config
41 raven/agent/loop/turn_path.py _run_turn
```
A tenth suppression sits on `benchmarks/proactivity_eval/runners/_common/longrun_adapters.py`
(`tick_to`, 41). `benchmarks/` is outside `PYTHON_LINT_TARGETS` and so outside
CI, but inside what the pre-commit Ruff hook sees on a changed file -- marking it
means the gate does not ambush whoever next edits that adapter.
**Nine entries, fewer distinct problems.** In `gateway_commands.py` the three
are nested inside each other at indent 0, 4 and 8: `run` at 68 is the body,
`gateway` adds its own branches on top, and `register` contributes about one. In
`turn_path.py` the three are sibling methods, but `_run_turn` holds ten nested
callbacks (`on_token`, `on_tool`, `on_progress` and so on) which is most of its
41. The one that is a large body by itself is `_run_agent_loop`: 1134 lines with
only two nested functions, so its 100 is its own.
Per-function rather than per-file, on purpose: a whole-file ignore on
`gateway_commands.py` would let a new 80-path function in the same file through,
while these entries do not. The score is in the comment so the debt is visible
where the code is, not parked in a config file.
Nothing has to be refactored to land this. Normal work is undisturbed unless
someone writes a forty-one-path function.
**Why the PLR09xx rules are left out.** They count arguments (230 occurrences
here), branches (125), statements (78) and returns (81). All four are proxies
for what `C901` measures directly, so adding them would report one fact four
times and bury the signal under 230 argument-count warnings.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: a lint gate plus the `noqa` entries that let it land green. No runtime
code changes; every production edit is an end-of-line comment.
## Verification
Verified against the lint roster read out of the Makefile
(`PYTHON_LINT_TARGETS = raven evolver agents plugins-dist tests scripts`) rather
than a chosen subset, and then against the whole tree. The first revision of
this MR checked only `raven/` and went red in CI on the two `agents/` functions;
that is what the roster-wide check exists to prevent.
```
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
raven evolver agents plugins-dist tests scripts
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache .
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
--extend-select RUF100 raven evolver agents plugins-dist tests scripts
(no unused C901 directive)
$ uv run --frozen --python 3.12 --extra dev ruff format --check \
raven evolver agents plugins-dist tests scripts
1886 files already formatted
$ uv run --frozen --python 3.12 pytest tests/ -q -k "turn_path or gateway or loader or console or config_precedence"
511 passed, 19 skipped
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The 19 skips are pre-existing and environmental: `test_provider_resolution_invariants.py`
skips its gateway-only cases when no gateway is configured.
Checked in the failing direction, since a gate never seen red is not known to
work. A fresh forty-branch function appended to `config/loader.py` is reported,
and the `noqa` on `_migrate_config` in the same file keeps holding rather than
being swallowed by it:
```
raven/config/loader.py:1088:5: C901 `_probe_over_ceiling` is too complex (41 > 40)
Found 1 error.
```
The probe was reverted. Note for the reviewer: reverting that file also reverted
its `noqa`, which the roster-wide check caught immediately.
One entry was removed after review rather than kept: `settings_usage` scores
exactly 40, which a ceiling of 40 does not flag, so its suppression was dead.
`--extend-select RUF100` reports such a directive as unused, and keeping it would
have defeated the documented tightening path -- lowering the number later would
have left that function exempt with nothing to show it.
The production diff is comment-only and can be read as such:
```
- async def _run_agent_loop(
+ async def _run_agent_loop( # noqa: C901 (cc 100: pre-existing, above the ceiling)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No behaviour change: every production edit is an end-of-line comment, and the
diff can be verified as such. The risk this carries is a false sense of
coverage, which is why the rationale in `pyproject.toml` states what the ceiling
does not mean. Two limits of the metric are worth a reviewer knowing: it does
not see nesting depth (five sequential `if`s and five nested ones both score 6),
and in Ruff's implementation boolean operators, ternaries and comprehension
conditions do not count at all. It is a filter for the untestable, not a
readability score.
Rollback is reverting the commits. Loosening instead of reverting is a one-line
change to `max-complexity`, which is the intended escape if the gate turns out
to obstruct real work.
## Related Issues
N/A
## Summary
`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.
The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.
Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.
Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.
This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
tests/test_permissions_gate.py tests/test_acp_server.py \
tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s
$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s
$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
raven/acp/server.py raven/agent/tools/shell.py
All checks passed!
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.
Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.
Effect on the dependency graph:
```
permissions -> agent edges 1 -> 0
mutually importing pairs 14 -> 13
packages in an import cycle 22 -> 22 (unchanged)
```
The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.
No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.
## Related Issues
N/A
## 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.
## 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>
## Summary
Reported from real use, with a screenshot: an open spawn card's stream box could not be scrolled back up, and the page behind it would not move either. It reads as the surface freezing.
The box is `overscroll-behavior: contain`:
```css
.dlgchat { max-height: 340px; overflow-y: auto; overscroll-behavior: contain; }
```
That is right at its **bottom** edge -- reading a stream to its end should not then carry the whole conversation past the card. At the **top** edge it has nothing to hold back and takes something away. The box is a third of the window tall and the full width of the column, so a reader's cursor is very likely inside it; once the box itself is at the top, every further wheel-up is swallowed and the page stays where it is.
## What I tried first, and why neither works
Both were measured in a real Chromium against a minimal page with the same two boxes, one `contain` and one `auto`.
**Dropping `contain`.** It protects something real: with `auto`, one continuous gesture that scrolls past the box's end dragged the page 840px. That is the annoyance the property was added for.
**Toggling the property from a handler** (on `scroll`, and on `wheel` by direction). Both released the top -- and both leaked 600px downwards. The browser reads `overscroll-behavior` when the gesture *starts*, so a value written mid-gesture applies to the next one, by which time the reader has already watched the page refuse to move. CSS has no directional form of this.
So the containment stays, and the upward remainder is handed to the page by hand.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Measured in a real browser
Same probe, all three states, with the cursor re-centred on the box before each phase -- an earlier run of this probe reported a false leak because the page had scrolled the box out from under the pointer:
```
A box still has room, wheel up box 560 -> 440 page 1021 -> 1021 page still
B box at its top, wheel up box 0 page 1021 -> 781 page follows
C wheel down past the box's end box 0 -> 560 page 781 -> 781 page not dragged
```
B is the bug. C is what `contain` is for, and it still holds.
## The ancestor walk, and the guard that turned out to be load-bearing
The page scroller is walked for rather than named, so the same card works wherever it is mounted. The walk skips an ancestor whose content already fits, and that is not a formality -- run against the live page, the chain from the box is:
```
.bd overflow-y: auto scrollHeight 94 clientHeight 94 skipped
.dtl.dlg hidden
.wkin .wk .step.in .tfb .tfold visible
#stage.col visible
#scroll overflow-y: auto scrollHeight 1980 clientHeight 846 taken
```
`.bd` sits directly between the box and `#scroll` and is a scroller that cannot scroll. Without the `scrollHeight > clientHeight` test the gesture would be forwarded into it, which swallows it in a new place.
## The wheel is read in the unit it was reported in
Review caught that the first revision assigned `deltaY` straight onto `scrollTop`. Only `deltaMode` 0 is pixels: a mouse reporting lines sends about `-3` for one notch and a page-mode device sends `-1`, so the page would have crept a few pixels while the box went on consuming the gesture -- the same freeze this change is for, with a smaller number.
`pixelDelta` normalises first, on the convention `PlaybooksPage.tsx:630` already uses: a line is 16px (exported as `WHEEL_LINE_PX`, so two readings of one device cannot drift), a page is the **scroller's own** visible height -- a page means a page of the thing being scrolled -- and a scroller reporting no height falls back to a line rather than multiplying by zero, which would report a move and make none.
The line and page arithmetic is covered by unit cases, not by a real device: Playwright's `mouse.wheel` emits pixel mode only, so a line-mode gesture could not be driven through a real browser. What was measured there is the containment behaviour itself, above.
## Verification
```
make test-ui 96 files, 1422 tests passed
make lint-ui gen:check 162 methods, type-check
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed -- no docs surface; the measurements above are the record
Ten cases on the rule and one on the wiring. Nine mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the direction test | 2 |
| drop the at-the-top test | 2 |
| drop `scrollHeight > clientHeight` | 1 |
| stop the walk at the immediate parent | 3 |
| line mode treated as pixels | 2 |
| page mode treated as pixels | 2 |
| drop the zero-height fallback | 1 |
| stop passing `deltaMode` from the component | 1 |
| remove `onWheel` from the card | 1 |
Geometry is fabricated in the unit cases rather than laid out: happy-dom lays nothing out, so `scrollHeight` and `clientHeight` are both 0 there and every ancestor would look unscrollable -- the walk would find nothing and the cases would pass having forwarded nothing. The scroll position they assert is then only ever the number the code under test wrote, which is the whole of what is being checked.
## Risk
- [x] Security impact considered -- no new data, no network or storage surface; the change is which element a wheel gesture moves
- [x] Backward compatibility considered -- one new module and one handler on one element. The CSS is untouched, so every other nested scroller behaves exactly as before, and a page with nothing to scroll finds no target and does nothing
- [x] Rollback path is clear for risky changes -- single-commit revert; the box returns to swallowing the gesture
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over the branch diff.
- **1 (a write location moved)** -- nothing moved; a gesture that reached no scroller now reaches one.
- **2 (a value with several entry points)** -- `#scroll`'s `scrollTop` also has `tail.ts` as a writer, which follows the tail while `stuck`. A reader scrolling up clears `stuck`, so the two cannot fight: by the time this forwards anything the follow is already off.
- **3d (several lanes through one sink)** -- one handler on one element; the decision is a pure function with its own cases.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
- **9 (error handling)** -- the two ways out are both silent and both correct: no scrollable ancestor, and a wheel the box can still answer. Neither is an error and neither throws.
- **11** -- `npm ci` in `ui-web`; this worktree was fresh.
Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
## Summary
Reported from real use, with a screenshot: an open spawn card's stream box could not be scrolled back up, and the page behind it would not move either. It reads as the surface freezing.
The box is `overscroll-behavior: contain`:
```css
.dlgchat { max-height: 340px; overflow-y: auto; overscroll-behavior: contain; }
```
That is right at its **bottom** edge -- reading a stream to its end should not then carry the whole conversation past the card. At the **top** edge it has nothing to hold back and takes something away. The box is a third of the window tall and the full width of the column, so a reader's cursor is very likely inside it; once the box itself is at the top, every further wheel-up is swallowed and the page stays where it is.
## What I tried first, and why neither works
Both were measured in a real Chromium against a minimal page with the same two boxes, one `contain` and one `auto`.
**Dropping `contain`.** It protects something real: with `auto`, one continuous gesture that scrolls past the box's end dragged the page 840px. That is the annoyance the property was added for.
**Toggling the property from a handler** (on `scroll`, and on `wheel` by direction). Both released the top -- and both leaked 600px downwards. The browser reads `overscroll-behavior` when the gesture *starts*, so a value written mid-gesture applies to the next one, by which time the reader has already watched the page refuse to move. CSS has no directional form of this.
So the containment stays, and the upward remainder is handed to the page by hand.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Measured in a real browser
Same probe, all three states, with the cursor re-centred on the box before each phase -- an earlier run of this probe reported a false leak because the page had scrolled the box out from under the pointer:
```
A box still has room, wheel up box 560 -> 440 page 1021 -> 1021 page still
B box at its top, wheel up box 0 page 1021 -> 781 page follows
C wheel down past the box's end box 0 -> 560 page 781 -> 781 page not dragged
```
B is the bug. C is what `contain` is for, and it still holds.
## The ancestor walk, and the guard that turned out to be load-bearing
The page scroller is walked for rather than named, so the same card works wherever it is mounted. The walk skips an ancestor whose content already fits, and that is not a formality -- run against the live page, the chain from the box is:
```
.bd overflow-y: auto scrollHeight 94 clientHeight 94 skipped
.dtl.dlg hidden
.wkin .wk .step.in .tfb .tfold visible
#stage.col visible
#scroll overflow-y: auto scrollHeight 1980 clientHeight 846 taken
```
`.bd` sits directly between the box and `#scroll` and is a scroller that cannot scroll. Without the `scrollHeight > clientHeight` test the gesture would be forwarded into it, which swallows it in a new place.
## The wheel is read in the unit it was reported in
Review caught that the first revision assigned `deltaY` straight onto `scrollTop`. Only `deltaMode` 0 is pixels: a mouse reporting lines sends about `-3` for one notch and a page-mode device sends `-1`, so the page would have crept a few pixels while the box went on consuming the gesture -- the same freeze this change is for, with a smaller number.
`pixelDelta` normalises first, on the convention `PlaybooksPage.tsx:630` already uses: a line is 16px (exported as `WHEEL_LINE_PX`, so two readings of one device cannot drift), a page is the **scroller's own** visible height -- a page means a page of the thing being scrolled -- and a scroller reporting no height falls back to a line rather than multiplying by zero, which would report a move and make none.
The line and page arithmetic is covered by unit cases, not by a real device: Playwright's `mouse.wheel` emits pixel mode only, so a line-mode gesture could not be driven through a real browser. What was measured there is the containment behaviour itself, above.
## Verification
```
make test-ui 96 files, 1422 tests passed
make lint-ui gen:check 162 methods, type-check
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed -- no docs surface; the measurements above are the record
Ten cases on the rule and one on the wiring. Nine mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the direction test | 2 |
| drop the at-the-top test | 2 |
| drop `scrollHeight > clientHeight` | 1 |
| stop the walk at the immediate parent | 3 |
| line mode treated as pixels | 2 |
| page mode treated as pixels | 2 |
| drop the zero-height fallback | 1 |
| stop passing `deltaMode` from the component | 1 |
| remove `onWheel` from the card | 1 |
Geometry is fabricated in the unit cases rather than laid out: happy-dom lays nothing out, so `scrollHeight` and `clientHeight` are both 0 there and every ancestor would look unscrollable -- the walk would find nothing and the cases would pass having forwarded nothing. The scroll position they assert is then only ever the number the code under test wrote, which is the whole of what is being checked.
## Risk
- [x] Security impact considered -- no new data, no network or storage surface; the change is which element a wheel gesture moves
- [x] Backward compatibility considered -- one new module and one handler on one element. The CSS is untouched, so every other nested scroller behaves exactly as before, and a page with nothing to scroll finds no target and does nothing
- [x] Rollback path is clear for risky changes -- single-commit revert; the box returns to swallowing the gesture
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over the branch diff.
- **1 (a write location moved)** -- nothing moved; a gesture that reached no scroller now reaches one.
- **2 (a value with several entry points)** -- `#scroll`'s `scrollTop` also has `tail.ts` as a writer, which follows the tail while `stuck`. A reader scrolling up clears `stuck`, so the two cannot fight: by the time this forwards anything the follow is already off.
- **3d (several lanes through one sink)** -- one handler on one element; the decision is a pure function with its own cases.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
- **9 (error handling)** -- the two ways out are both silent and both correct: no scrollable ancestor, and a wheel the box can still answer. Neither is an error and neither throws.
- **11** -- `npm ci` in `ui-web`; this worktree was fresh.
Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
## Summary
Land the permission-mode design: a permission gate the tool registry consults before dispatching any tool call, replacing the lexical blacklist inside ExecTool and its abort-the-whole-turn refusals.
Decision waterfall, per call: the builtin unconditional deny list (catastrophe-class commands only), then the user's deny/allow tiers and exec prefix rules from the new `permissions` config node, then the permission mode's reading of the ask tier: `ask` prompts for everything, `smart` has an LLM reviewer allow or escalate (fail-closed; the reviewer's verdict and the final decision are audited as attributes on the call's own tool.call trace span, alongside every other terminal decision -- no permission-only audit file), `full` runs it without prompting while the deny list and user deny rules still hold. The default mode is `ask`.
One ruling language, on purpose. Three specials that punched holes in each other were folded into the tiers during review (the later commits in this MR; the earlier design had them):
- A command family a surface declares (none by default; the ACP editor declares deletion and six external-effect families) does not decide anything. It names the prompt -- the human reads "push to a remote" rather than the bare command -- and is recorded on the call's tool.call span as `permission.family` whichever way the tiers decide; the call answers to the tiers and the mode like any other mutation, so a user allow rule lifts it and full mode runs it.
- A sub-agent's gate reads the turn's mode and asks through the responder the parent turn bound (the permission turn is a ContextVar its task inherits), instead of being pinned to full with asking disabled. The user authorized the spawn, not every command composed afterwards: a delegated `git push` reaches the human exactly as a direct one does, and an unattended parent (cron, one-shot) leaves it unattended.
- `tools.exec.allowDestructiveCommands` is retired. It lifted a blanket recursive-delete refusal that no longer exists (an ordinary `rm -rf build/` is ask-tier daily work; only a root or home tree is catastrophe-class). The key is still accepted and ignored, with a startup notice naming the tiers; the settings toggle, the live reader, the launcher inheritance and the settings-whitelist entry are removed.
A conversation can run in its own mode. `permissions.mode` in config is the default every conversation starts on; `config.set` with a `session_id` (same scope rule as a model switch, one shared helper) gives one conversation its own, kept the way its model is kept (in memory and on the conversation's record, so a restart does not undo it), and the gate reads the conversation's own mode first on every tool call, sub-agent tasks included. Bidirectional: the person at the keyboard can tighten or loosen either. Surfaces: `/perm X` in the TUI changes this conversation, `/perm default X` the default; on the web the composer chip changes the open conversation (a pick made in a draft is staged and applied to the session the first message mints, like the model and tier chips) and the settings panel gains the default-mode picker.
Other key decisions:
- Refusals continue the turn: every deny path returns a reasoned tool error with `continuation=CONTINUE`; the one path that ends a turn is the deny-and-stop approval choice. Parallel siblings of a blocked call still never execute. A command the policy cannot parse is refused with instructions to fix it (close the quote, or write the script to a file) rather than to give up.
- The gate is a built-in registry step ahead of the plugin tool gates: platform authority precedes plugin policy, and the gate can wait on a human and answer with a full ToolResult, which the plugin paper deliberately cannot.
- Approval outcomes carry choice (`allow`/`deny`/`deny_stop`) plus optional feedback the human types, relayed verbatim to the model. Both frontends grow the third key and the note field, localized. A channel user answers approvals through the same ask round-trip that already carries questions (`ApprovalViaAsk`); cron/sentinel/one-shot turns stay unattended and the ask tier refuses with a reason there.
- A command bound for a registered machine (the target's new exec `machine` lane) names that machine on its approval prompt -- `rm -rf /data (on prod-gpu-1)` -- and in the per-turn dedup key, so a refusal here does not pre-refuse the same text elsewhere; the gate's rulings themselves apply on every machine alike. The background lane is ruled on at the registry door like any other call and cannot be a way around a refusal.
- ShellCommandPolicy stays in place (classification, wrapper stripping, surface family registration) and is consumed by the gate; ExecTool keeps only its own integrity boundary (allowlist, workspace fence) and execution.
- Contracts: `contracts/permissions.py` is a new contract paper (ledger re-pinned across the review rounds, CONTRACTS_VERSION 5 -> 9); `SupportsApprovalTurn` is removed with its last consumer. `rpc-schema/openrpc.json` gains `config.get.session_id`; both generated clients are regenerated.
- Sandboxing earns no relaxation anywhere in the permission path: Boxlite mounts the real workspace read-write, so the deny list and the catastrophic-delete checks apply to sandboxed and direct execution alike.
- The target's config hot-reload for `tools.exec.extra_deny_patterns` is preserved and enforced at the gate: `BuiltinRulings` re-reads the live source before each ruling, a non-compiling pattern rejects the edit and keeps the current policy.
Deliberate v1 cuts, called out for review: the smart-mode reviewer sees only the tool request itself (no conversation tail); gate refusals always set `blocks_call=True` except the parse-error refusal, which the model keeps to fix. Approval frames carry the real per-call `tool_call_id`.
Out of scope, stated in CONTEXT.md: ACP-dispatched external agents (auto-approved by `acp_client/permissions.py`) and vendored out-of-process sub-agents are not covered by the gate. The channel approval transport keys late replies by conversation only; the expired-approval-then-second-approval overlap is recorded as a QuestionBroker follow-up.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- `uv run --all-extras pytest tests/ -q` on the final tree (rebased onto main): 19424 passed, 144 skipped, 0 failed.
- `make lint`: all stages green (python, ui, tui, bridge, vendored checks).
- TUI `npx vitest run`: 2023 passed, 0 failed. Web `npx vitest run`: 1378 passed, 0 failed. `tsc --noEmit` clean on both.
- Reverse verification: with the continuation flip removed, `test_denied_delete_continues_the_turn` fails on the claimed symptom (the turn ends with the canned abort reply); restored and green. The TUI localization change was mutation-verified (keys pointed at a missing id -> red, restored -> green).
- Manual acceptance against `raven serve` with a real model (isolated RAVEN_HOME; TUI through tmux, web through Playwright), reconciled on three layers (UI rendering, server config.json, audit spans): ask prompts / allow-once / deny-with-feedback / deny-and-stop / same-turn dedupe / unconditional deny / full / smart reviewer states, on both surfaces. Two defects found there are fixed in this MR (`/perm` always reported ask: wrong `config.get` shape; approval prompt not localized).
- The delegated-approval path passed a manual pass of its own, which found and fixed a real defect: a sub-agent's first command is often asked AFTER the parent turn has ended, and the end-of-turn overlay reset wiped that prompt off the TUI with nobody having answered, so the call died at the runtime's 35s ceiling and the sub-agent reported a refusal for a prompt the user never saw. Measured both ways on a live gateway: before, the span was deny/approval at exactly 35.0s with no TUI response; after, the prompt stays up past the turn's end and the span is allow/approval/allow at 13.3s with the file written.
- The per-conversation mode passed the same manual pass (TUI and web, 13 steps): a conversation switched to full ran a write with while the default moved to smart underneath it and a new conversation followed the default; after a gateway restart the same conversation still ran at (had the record not been read back, smart would have sent the call to the reviewer); a mode picked on the web draft page landed on the session its first message minted (record metadata, prompt shown, ), and the settings panel moved only the default.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible behavior changes: the default mode is `ask`, so mutating tools (write/edit/exec and unknown MCP tools) prompt on interactive surfaces and are refused with a reason on unattended ones; previously they ran freely. Policy refusals no longer end the turn. Cron/sentinel turns lose mutating tools under the default mode until the user picks `smart` or `full`.
Changes to positions the earlier rounds of this MR had documented: on the ACP surface, full mode now runs a delete or a push it used to refuse, and a user allow rule can lift a declared family; a sub-agent in ask mode now prompts the human through the parent turn where it used to run silently; `tools.exec.allowDestructiveCommands` is read but ignored (startup notice). A conversation's own mode is stored on its session record, like its model, and survives a restart.
Rollback: set `permissions.mode` to `full`, which reproduces the old no-prompt behavior except that catastrophe-class commands are refused rather than run.
## Related Issues
N/A
## 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.
## 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>
## 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
## 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>
## Summary
First of two cuts on the over-termination half of ledger record `001`. The
lexical half merged in `!270`; this one is about what a refusal *says*, and it
moves no control flow at all.
Four different causes reached the user as one sentence:
```
Error: Command blocked by safety guard (policy evaluation failed)
```
A denied pattern, a recursive delete, a power-off and a command that could not
be parsed were indistinguishable. In the session the record was written from,
that is what the user asked about four times, and what the model, given
nothing to go on, then guessed wrong about twice.
### The reason travels with the decision
`classify` returns a `PolicyOutcome` carrying the decision and a stable
`reason_code`. The message names something its reader can act on: an operator
list to edit, a quote to close, a tree the command would have walked away.
`reason_code` is an identifier rather than prose because more than one surface
has to say the same thing about one refusal -- the text handed to the model, the
approval prompt, and later the trace.
### One classification per command
`classify` is now the one place the rules run. `evaluate` and `approval_reason`
read their answers off it, where each used to re-run the matchers itself.
That is not tidying: it is how they came to disagree. Review on `!270` found
that a comment mentioning a recursive delete tripped the short-circuit in
`approval_reason` and erased the family the approval prompt was going to name,
so the user was asked to approve a deletion under a generic line. Two answers
about one command cannot diverge if there is only one classification.
### The deny list loses its second reader
`ExecTool._guard_command` searched the deny list against the same patterns
`ShellCommandPolicy` was constructed with. Running it twice bought nothing and
cost a second message for one cause -- "dangerous pattern detected" at that gate
against whatever the policy said at the other.
One test moved as a result. `test_the_other_gate_still_denies_the_real_thing`
asserted at the gate; it now asserts through `execute`, because which of two
places refuses a command is not a thing worth pinning in place. The invariant it
guards -- a denied pattern is refused -- is unchanged and asserted more
strongly.
### What does not change
Every refusal still ends the turn exactly as before. `abort_action` still means
both "refuse this call" and "end this turn"; separating those is the second cut,
and it needs this data to decide on. Splitting the two keeps a contract
migration -- `ToolResult`, both loops, tracing, the UI -- out of a change whose
whole content is a message.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
pytest -q 11160 passed, 83 skipped
pytest tests/test_shell_*.py -q 259 passed
ruff check / ruff format --check clean
```
Four mutations, each caught:
```
every deny reports one reason code 6 failed
the message goes back to being generic 4 failed
approval_reason stops reading the classification 54 failed
an unknown reason code is printed raw 1 failed
```
The third is the one worth reading: 54 failures is the measure of how much
already depended on those two answers agreeing.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
The refusal texts change, which is the point. Nothing that was refused is now
allowed and nothing that was allowed is now refused: `evaluate` returns
`classify(...).decision`, so the decision is the same expression it was, and the
full suite passes without a test being relaxed.
The one behavioural edge is the deny list moving to a single owner. It was the
same list in both places and both ran only when not sandboxed, so the decision
is unchanged; what changes is which message a denied pattern produces.
A reason code this build does not know about falls back to the bare sentence
rather than being printed raw -- worth stating because the map is a place a
future rule can be forgotten, and the failure mode should be a vaguer message
rather than an identifier leaking into a user-facing string.
No interface removals. `evaluate` and `approval_reason` keep their signatures;
`PolicyOutcome` and `classify` are additive.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Ledger record `001`, over-termination half, first cut. The second cut is where
`abort_action` stops carrying two meanings, with restricted replan and bypass
detection behind it.
## Summary
The lexical half of RAVEN-20260823-001. Three read-only commands were refused
in one session because their comments said `there's`, `what's` and `raven's`.
`shell_policy.py` turns `#` off in its lexer, so English prose keeps taking
part in quote parsing: the apostrophe opened a quote that never closed, `shlex`
raised `No closing quotation`, and the fail-closed branch answered `hard_deny`.
Reproduced verbatim from the ledger's artifacts before touching anything --
all three `hard_deny`, `_command_segments` raising, and the same commands
without their comments allowed every time.
The user saw only `policy evaluation failed`, asked four times why, and the
model, given nothing to go on, guessed wrong twice.
### Both gates, not one
The same blindness runs the other way and reaches a second gate.
`ExecTool._guard_command` searches the deny list against raw text, so it never
hit the parse failure -- but a denied pattern written inside a comment blocked
the command there just the same:
```
ls -la # unlike dd if=/dev/zero, this one only lists
```
Fixing `ShellCommandPolicy` alone would only have changed which message the
user got. A test pins each gate, and a mutation that reverts one of them is
caught.
### One lexical view
Comments are removed once, by a walk that shares the quote and escape rules
`_split_on_operators` already uses -- those rules are what decide whether a `#`
is a comment at all. Every safety check reads that view: the deny patterns, the
delete and power matchers, the approval families a surface registered, and the
second gate's own list. The raw command still goes to the executor, the audit
trail and the approval prompt, which are about what the user asked for rather
than about what it does.
A `#` opens a comment only outside quoting and at the start of a word.
`foo#bar`, `${#PATH}`, `$#`, `file#1` and `'#!/bin/sh'` are arguments. Cutting
at every `#` would quietly shorten commands, which is how a classifier stops
seeing the half that matters -- pinned with `echo a#b; rm -rf /tmp/tree`, which
must still deny.
### What does not change
Fail-closed. An unterminated quote in the executable region is still refused,
including when a well-formed comment precedes it. `rm -rf` or `shutdown` beside
a comment still denies, on either side of it. A `bash -c` script is still read
through to the command it carries, comments and all.
### Scope
This is deliberately half the ledger entry. The other half -- separating
"refuse this tool call" from "end the whole turn", which today share one
`abort_action` flag across the main loop, the sub-agent loop, tracing and the
UI -- is a change to the `ToolResult` control contract and belongs in its own
MR. This one stops the false refusals without touching that contract.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
pytest -q 11056 passed, 83 skipped
pytest tests/test_shell_comments.py -q 26 passed
ruff check / ruff format --check clean
```
Four mutations, each caught:
```
comments are never stripped 5 failed
a `#` anywhere starts a comment 1 failed
a `#` inside quotes starts one too 1 failed
only the policy gate learns the view 1 failed
```
The last is the one worth reading: it is what proves the second gate is
covered rather than assumed.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
The change is narrowing what the classifier reads, so the direction that
matters is whether anything dangerous can now hide in a comment. It cannot:
the shell would not run it either, and the executable half is classified
exactly as before. Tests cover a denied pattern on both sides of a comment, a
recursive delete and a power command before and after one, and a wrapper
carrying its own script.
The opposite risk -- over-eager stripping cutting a command short -- is the
reason a `#` must start a word. Six shapes that are not comments are pinned.
No interface changes and no migration. `executable_text` is a new export;
`_guard_command` and `evaluate` keep their signatures. Rollback is a revert.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
RAVEN-20260823-001, lexical half.
One note for the ledger while this is open: the entry's header carries P1 while
its own impact section concludes P2, on the grounds that the trigger is
bounded by comment style and recoverable by removing the comment. The two
readings imply different things about whether there is a workaround, and the
priority field is what the queue is ordered by.