## 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
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
`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
When a DAG node fails, the sub-agent's report opens a turn in the user's own conversation (origin `SUBAGENT`). The asker already bound in that turn whenever a surface was watching the conversation, so the person could answer `ask_user` there and pick "continue". The approval responder, however, bound only for `USER` turns, so the `resolve_dag_node` call that acts on that answer was refused in the same turn as "this turn is not interactive". The run ended on the person's own decision: the node could be neither continued nor abandoned from the TUI or the WebUI.
The fix binds the approval responder on the gate the asker already used: a `USER` turn always, a `SUBAGENT` relay when its conversation has a live watcher, every other origin never. One expression, shared by both bindings, in `RpcTurnRunner.run`.
The gateway's channel runner (`GatewayTurnRunner`) is deliberately left as it is: a channel session has no watched-signal to gate on, and widening there would turn an abandoned-channel question from an instant decline into a stall, as its own comment says.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_rpc_spine.py tests/test_agent_loop_approval.py tests/test_shell_approval.py tests/test_permissions*.py -q`: 361 passed. Two new cases: a `SUBAGENT` turn in a watched conversation reaches the responder and the gated tool runs; the same turn with nobody watching is still refused as not interactive.
- Reverse check: with the spine change reverted, the watched-relay case fails on the gated tool not running.
- `make lint-python`: clean.
- `uv run --all-extras pytest -q` (before rebase): 20150 passed, 4 failed, 165 skipped. The 4 failures (`test_agent_loop_token_budget`, `test_agents_code_launcher`, `test_agents_oncall_launcher`, `test_ppt_engine_image_search`) fail identically with this change reverted and again on the rebased head; none of them imports `raven.rpc.spine`. Pre-existing on `main`.
End to end, no permission override in the config, host started from this branch, port owner start time checked against the last code change:
| Frontend | Flow | Result |
|---|---|---|
| TUI (`raven tui --dev`) | run a playbook whose carried server is down -> node fails -> host calls `resolve_dag_node continue` -> approval overlay "Approve this action: resolve_dag_node {...}" -> key 1 -> tool runs -> attempt-2 dispatched | pass (before the fix the same step ended in "This call requires user approval (ask tier), but this turn is not interactive") |
| WebUI (`raven serve`) | same flow -> approval sheet "Approve this action: resolve_dag_node {...}" -> "Allow once" -> tool runs (the model chose abandon this time, so no second attempt; the point under test is that the approval reaches the person and the gated tool executes) | pass |
- [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 the approval gate)
## Risk
- Permission semantics: an ask-tier tool called in a sub-agent relay turn now reaches the person watching the conversation instead of being refused. It still fails closed with nobody watching (`has_subscribers` false), on timeout, and on every other origin. This is the same reachability rule the asker has had since the relay widening; approval was the one binding that had not followed it.
- Backward compatibility: `USER` and `CRON` turns are unchanged. The channel gateway runner is unchanged.
- Rollback: revert the squash commit; no data or config involved.
## Related Issues
N/A
## Summary
When a DAG node fails, the sub-agent's report opens a turn in the user's own conversation (origin `SUBAGENT`). The asker already bound in that turn whenever a surface was watching the conversation, so the person could answer `ask_user` there and pick "continue". The approval responder, however, bound only for `USER` turns, so the `resolve_dag_node` call that acts on that answer was refused in the same turn as "this turn is not interactive". The run ended on the person's own decision: the node could be neither continued nor abandoned from the TUI or the WebUI.
The fix binds the approval responder on the gate the asker already used: a `USER` turn always, a `SUBAGENT` relay when its conversation has a live watcher, every other origin never. One expression, shared by both bindings, in `RpcTurnRunner.run`.
The gateway's channel runner (`GatewayTurnRunner`) is deliberately left as it is: a channel session has no watched-signal to gate on, and widening there would turn an abandoned-channel question from an instant decline into a stall, as its own comment says.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_rpc_spine.py tests/test_agent_loop_approval.py tests/test_shell_approval.py tests/test_permissions*.py -q`: 361 passed. Two new cases: a `SUBAGENT` turn in a watched conversation reaches the responder and the gated tool runs; the same turn with nobody watching is still refused as not interactive.
- Reverse check: with the spine change reverted, the watched-relay case fails on the gated tool not running.
- `make lint-python`: clean.
- `uv run --all-extras pytest -q` (before rebase): 20150 passed, 4 failed, 165 skipped. The 4 failures (`test_agent_loop_token_budget`, `test_agents_code_launcher`, `test_agents_oncall_launcher`, `test_ppt_engine_image_search`) fail identically with this change reverted and again on the rebased head; none of them imports `raven.rpc.spine`. Pre-existing on `main`.
End to end, no permission override in the config, host started from this branch, port owner start time checked against the last code change:
| Frontend | Flow | Result |
|---|---|---|
| TUI (`raven tui --dev`) | run a playbook whose carried server is down -> node fails -> host calls `resolve_dag_node continue` -> approval overlay "Approve this action: resolve_dag_node {...}" -> key 1 -> tool runs -> attempt-2 dispatched | pass (before the fix the same step ended in "This call requires user approval (ask tier), but this turn is not interactive") |
| WebUI (`raven serve`) | same flow -> approval sheet "Approve this action: resolve_dag_node {...}" -> "Allow once" -> tool runs (the model chose abandon this time, so no second attempt; the point under test is that the approval reaches the person and the gated tool executes) | pass |
- [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 the approval gate)
## Risk
- Permission semantics: an ask-tier tool called in a sub-agent relay turn now reaches the person watching the conversation instead of being refused. It still fails closed with nobody watching (`has_subscribers` false), on timeout, and on every other origin. This is the same reachability rule the asker has had since the relay widening; approval was the one binding that had not followed it.
- Backward compatibility: `USER` and `CRON` turns are unchanged. The channel gateway runner is unchanged.
- Rollback: revert the squash commit; no data or config involved.
## Related Issues
N/A
## Summary
These are aggregate ceilings on how far import cycles reach, not a proof that no
cycle was deepened: an edge added between two members of the existing component
leaves every total unmoved, and that case is left to the contracts and to review.
The module docstring says so too.
`acyclic_siblings` is the import-linter contract that would forbid import cycles
among raven's top-level subpackages outright. It is not in `pyproject.toml`
because it is BROKEN: **18 of the 40 top-level subpackages sit in a single
strongly connected component**. Added as a gate it would paint CI red on arrival
and be switched off within the week.
This states the same rule as a budget instead of an absolute. Three ceilings, set
to what the tree measures today, and they may only go down:
```
PACKAGES_IN_CYCLES_CEILING = 18
MUTUAL_PAIRS_CEILING = 13
MODULES_IN_CYCLES_CEILING = 42
```
This branch carries the vocabulary refactor (MR 610) underneath it, because the
ceilings are the numbers that hold once that lands. If 610 merges first this
becomes a single-commit change; either way the ceilings match the tree the guard
runs against.
A change that draws a package or a module into a cycle for the first time, or
makes a new pair import each other, fails here. An edge added between two
members of the existing component does not: every total stays put, and that
case is left to the contracts and to review. Unpicking one lowers a ceiling,
which is a reviewed edit to the test file rather than a drive-by -- the same
shape `tests/test_kernel_budget.py` already uses, and for the same reason its
docstring gives.
Three numbers, because each is blind where another sees. Mutual pairs (a imports
b and b imports a) are the edges people actually add, and the failure message
names them. A cycle three packages long shows up in no pair at all, so a
component measure carries the general case.
The third exists because the package measure is an artifact of granularity as
much as of design. Collapsing a package to one node turns "config's writer
reaches agent, which reaches config's loader" into a cycle even where no module
imports itself back; measured per module, 42 of 635 modules sit in a cycle
rather than 18 of 40 packages. The two answer different questions -- whether a
package can be lifted out on its own, and whether a reader has a real knot to
walk around -- and they move independently: the refactor underneath took the
package count from 22 to 18 while moving the module count by three.
The numbers were still moving while this was written. `agent <-> permissions`
became the fourteenth mutual pair during the drafting, on a `permissions`
package that had just arrived. Nothing reported it, because nothing was
watching -- which is the case for pinning them.
`grimp` becomes an explicit dev dependency rather than staying a transitive one
through import-linter, since a test now imports it directly.
This changes no production code and unpicks no cycle. It fixes the number in
place so that the unpicking, when it happens, is not undone by the next branch.
### Both graph options are chosen, not defaulted
`exclude_type_checking_imports` is read out of `[tool.importlinter]` rather than
hardcoded, so the guard measures the same graph the contracts are checked
against. Without it, `gateway` counts as cyclic on a type-checking-only import
and the module count moves by three -- the guard would have been ratcheting a
graph no contract enforces.
`cache_dir=None` because grimp's default is a shared `.grimp_cache` that
outlives a branch switch. A guard whose job is to report the graph of the
checked-out tree must not serve one an earlier revision left behind: a stale hit
turns it red or green for reasons absent from the diff. Building fresh costs
about a second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: an architecture guard, in the shape of a budget. Closest to `test`, which
is the commit type used.
## Verification
```
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py -q
4 passed in 1.06s
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py \
tests/test_kernel_closure.py tests/test_kernel_budget.py -q
10 passed in 1.51s
$ uv run --frozen --python 3.12 lint-imports
Contracts: 8 kept, 0 broken.
$ uv run --frozen --python 3.12 --extra dev ruff check tests/test_import_cycle_budget.py
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check tests/test_import_cycle_budget.py
1 file already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Checked in the failing direction once per ceiling, since a gate that has never
been seen red is not known to work.
Making `utils` import the subagent presets trips the two package ceilings and
leaves the module count untouched -- which is the granularity point above, seen
from the failing side:
```
AssertionError: 23 subpackages are inside an import cycle, over the ceiling of 18
AssertionError: 15 pairs of subpackages import each other, over the ceiling of 13
```
Making `utils.text` and `importer.skills.hermes` import each other is a real
module-level cycle, and trips the third:
```
AssertionError: 45 modules are inside an import cycle, over the ceiling of 42
```
Both probes were reverted; the diff carries only the guard, the ceilings and the
dependency line.
- [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 runtime behaviour change. The guard reads the import graph and asserts three
counts; it adds about a second to the suite. All three ceilings are met on
arrival,
so nothing that exists today is blocked. Rollback is reverting the one commit.
The known limit of a count-based ratchet is the one the coverage ratchet already
carries: a change that closes one cycle and opens another leaves the totals
unmoved and passes. Naming the pairs in the failure message is what makes that
visible in review when it matters.
## Related Issues
N/A
## Summary
These are aggregate ceilings on how far import cycles reach, not a proof that no
cycle was deepened: an edge added between two members of the existing component
leaves every total unmoved, and that case is left to the contracts and to review.
The module docstring says so too.
`acyclic_siblings` is the import-linter contract that would forbid import cycles
among raven's top-level subpackages outright. It is not in `pyproject.toml`
because it is BROKEN: **18 of the 40 top-level subpackages sit in a single
strongly connected component**. Added as a gate it would paint CI red on arrival
and be switched off within the week.
This states the same rule as a budget instead of an absolute. Three ceilings, set
to what the tree measures today, and they may only go down:
```
PACKAGES_IN_CYCLES_CEILING = 18
MUTUAL_PAIRS_CEILING = 13
MODULES_IN_CYCLES_CEILING = 42
```
This branch carries the vocabulary refactor (MR 610) underneath it, because the
ceilings are the numbers that hold once that lands. If 610 merges first this
becomes a single-commit change; either way the ceilings match the tree the guard
runs against.
A change that draws a package or a module into a cycle for the first time, or
makes a new pair import each other, fails here. An edge added between two
members of the existing component does not: every total stays put, and that
case is left to the contracts and to review. Unpicking one lowers a ceiling,
which is a reviewed edit to the test file rather than a drive-by -- the same
shape `tests/test_kernel_budget.py` already uses, and for the same reason its
docstring gives.
Three numbers, because each is blind where another sees. Mutual pairs (a imports
b and b imports a) are the edges people actually add, and the failure message
names them. A cycle three packages long shows up in no pair at all, so a
component measure carries the general case.
The third exists because the package measure is an artifact of granularity as
much as of design. Collapsing a package to one node turns "config's writer
reaches agent, which reaches config's loader" into a cycle even where no module
imports itself back; measured per module, 42 of 635 modules sit in a cycle
rather than 18 of 40 packages. The two answer different questions -- whether a
package can be lifted out on its own, and whether a reader has a real knot to
walk around -- and they move independently: the refactor underneath took the
package count from 22 to 18 while moving the module count by three.
The numbers were still moving while this was written. `agent <-> permissions`
became the fourteenth mutual pair during the drafting, on a `permissions`
package that had just arrived. Nothing reported it, because nothing was
watching -- which is the case for pinning them.
`grimp` becomes an explicit dev dependency rather than staying a transitive one
through import-linter, since a test now imports it directly.
This changes no production code and unpicks no cycle. It fixes the number in
place so that the unpicking, when it happens, is not undone by the next branch.
### Both graph options are chosen, not defaulted
`exclude_type_checking_imports` is read out of `[tool.importlinter]` rather than
hardcoded, so the guard measures the same graph the contracts are checked
against. Without it, `gateway` counts as cyclic on a type-checking-only import
and the module count moves by three -- the guard would have been ratcheting a
graph no contract enforces.
`cache_dir=None` because grimp's default is a shared `.grimp_cache` that
outlives a branch switch. A guard whose job is to report the graph of the
checked-out tree must not serve one an earlier revision left behind: a stale hit
turns it red or green for reasons absent from the diff. Building fresh costs
about a second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: an architecture guard, in the shape of a budget. Closest to `test`, which
is the commit type used.
## Verification
```
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py -q
4 passed in 1.06s
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py \
tests/test_kernel_closure.py tests/test_kernel_budget.py -q
10 passed in 1.51s
$ uv run --frozen --python 3.12 lint-imports
Contracts: 8 kept, 0 broken.
$ uv run --frozen --python 3.12 --extra dev ruff check tests/test_import_cycle_budget.py
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check tests/test_import_cycle_budget.py
1 file already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Checked in the failing direction once per ceiling, since a gate that has never
been seen red is not known to work.
Making `utils` import the subagent presets trips the two package ceilings and
leaves the module count untouched -- which is the granularity point above, seen
from the failing side:
```
AssertionError: 23 subpackages are inside an import cycle, over the ceiling of 18
AssertionError: 15 pairs of subpackages import each other, over the ceiling of 13
```
Making `utils.text` and `importer.skills.hermes` import each other is a real
module-level cycle, and trips the third:
```
AssertionError: 45 modules are inside an import cycle, over the ceiling of 42
```
Both probes were reverted; the diff carries only the guard, the ceilings and the
dependency line.
- [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 runtime behaviour change. The guard reads the import graph and asserts three
counts; it adds about a second to the suite. All three ceilings are met on
arrival,
so nothing that exists today is blocked. Rollback is reverting the one commit.
The known limit of a count-based ratchet is the one the coverage ratchet already
carries: a change that closes one cycle and opens another leaves the totals
unmoved and passes. Naming the pairs in the failure message is what makes that
visible in review when it matters.
## Related Issues
N/A
## Summary
`raven.config` and `raven.agent` imported each other. config validated sub-agent
declarations against tables living in `raven.agent.subagent`; the agent package
reads config for its shapes and paths. Both sides deferred their import into a
function body to keep module init off the cycle, which is what kept it invisible
to everything except a graph walk.
The validation needs the **vocabulary**, not the behaviour: which names are
legal, never what those names run. Only membership was ever read at the two call
sites -- `command`, `description`, `kind` and `readyTimeoutMs` were not. So the
names move down to `raven/config/agent_names.py` and the tables stay where they
are:
- **config owns what is legal** -- `BUILTIN_AGENT_NAMES`, `LEGACY_AGENT_ALIASES`,
`THIRD_PARTY_PRESET_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`.
Pure data and pure string functions, no IO.
- **`raven.agent.subagent` owns what it does** -- the preset table with its
commands, transports and timeouts is untouched.
`builtin_agents` re-exports the moved names, so its eight consumers (`registry`,
`rpc.methods.subagents`, `manager`, `spawn_tool`,
`context_engine.segments.identity`) are not touched at all.
### Why the check did not move up instead
Moving the validation later, rather than moving the data down, would also break
the cycle and would cost nothing in cohesion. It was rejected because the check
is deliberately at parse time. It runs as a `@model_validator(mode="after")` on
all three sub-agent transports, on both paths that build a model from a dict
(`load_config` reading the file, and `update_subagents` validating before an
atomic write). Its own docstring names what it catches: a hand-edited
`preset: "hermes"` on an unrelated entry, which would otherwise both dodge the
reserved-name guard and hide the real Hermes preset from the Presets group.
An invalid row would become constructible, and every later reader would treat it
as valid.
### The cost, and the pin
The split spells one name set in two places. A preset added to
`THIRD_PARTY_SUBAGENT_PRESETS` without its key added to the vocabulary would ship
and then be refused by the schema meant to accept it, with nothing reporting the
mismatch. `tests/test_subagent_name_vocabulary.py` pins both sets equal in both
directions, and does the same for the seed table against the reserved names.
## 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_subagent_name_vocabulary.py tests/test_subagent_builtin_agents.py \
tests/test_update_subagents.py tests/test_subagent_registry.py \
tests/test_subagent_acp.py tests/test_rpc_subagents.py tests/test_kernel_closure.py -q
350 passed in 13.91s
$ uv run --frozen --python 3.12 --extra dev ruff check <the five changed files>
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check <the five changed files>
5 files already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Both the contract run and the test run above were repeated after rebasing onto
the current main, since this one touches production code.
Every call site of every moved symbol was enumerated before the edit
(`BUILTIN_AGENT_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`,
`GENERIC_AGENT`, `LEGACY_AGENT_ALIASES`, `THIRD_PARTY_SUBAGENT_PRESETS`) and the
re-export is what keeps them all valid.
Effect on the dependency graph, measured before and after:
```
config -> agent edges 2 -> 0
packages in an import cycle 22 -> 19 (out of 40)
mutually importing pairs 14 -> 13
```
The three packages that leave the cycle were only ever pulled in through this
one pair.
- [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: the same names, the same validation, the same failure
messages. The reserved-name guard and the preset provenance check both still run
at parse time on all three transports. Backward compatibility is why
`builtin_agents` re-exports rather than relocating its public surface, and why
`LEGACY_AGENT_ALIASES` moves intact -- stored records under the old lowercase
name still resolve.
Rollback is reverting the one commit. The risk this leaves behind is the
two-spellings drift, which is why the equality pin ships in the same commit
rather than as a follow-up.
## Related Issues
N/A
## Summary
`raven.config` and `raven.agent` imported each other. config validated sub-agent
declarations against tables living in `raven.agent.subagent`; the agent package
reads config for its shapes and paths. Both sides deferred their import into a
function body to keep module init off the cycle, which is what kept it invisible
to everything except a graph walk.
The validation needs the **vocabulary**, not the behaviour: which names are
legal, never what those names run. Only membership was ever read at the two call
sites -- `command`, `description`, `kind` and `readyTimeoutMs` were not. So the
names move down to `raven/config/agent_names.py` and the tables stay where they
are:
- **config owns what is legal** -- `BUILTIN_AGENT_NAMES`, `LEGACY_AGENT_ALIASES`,
`THIRD_PARTY_PRESET_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`.
Pure data and pure string functions, no IO.
- **`raven.agent.subagent` owns what it does** -- the preset table with its
commands, transports and timeouts is untouched.
`builtin_agents` re-exports the moved names, so its eight consumers (`registry`,
`rpc.methods.subagents`, `manager`, `spawn_tool`,
`context_engine.segments.identity`) are not touched at all.
### Why the check did not move up instead
Moving the validation later, rather than moving the data down, would also break
the cycle and would cost nothing in cohesion. It was rejected because the check
is deliberately at parse time. It runs as a `@model_validator(mode="after")` on
all three sub-agent transports, on both paths that build a model from a dict
(`load_config` reading the file, and `update_subagents` validating before an
atomic write). Its own docstring names what it catches: a hand-edited
`preset: "hermes"` on an unrelated entry, which would otherwise both dodge the
reserved-name guard and hide the real Hermes preset from the Presets group.
An invalid row would become constructible, and every later reader would treat it
as valid.
### The cost, and the pin
The split spells one name set in two places. A preset added to
`THIRD_PARTY_SUBAGENT_PRESETS` without its key added to the vocabulary would ship
and then be refused by the schema meant to accept it, with nothing reporting the
mismatch. `tests/test_subagent_name_vocabulary.py` pins both sets equal in both
directions, and does the same for the seed table against the reserved names.
## 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_subagent_name_vocabulary.py tests/test_subagent_builtin_agents.py \
tests/test_update_subagents.py tests/test_subagent_registry.py \
tests/test_subagent_acp.py tests/test_rpc_subagents.py tests/test_kernel_closure.py -q
350 passed in 13.91s
$ uv run --frozen --python 3.12 --extra dev ruff check <the five changed files>
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check <the five changed files>
5 files already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Both the contract run and the test run above were repeated after rebasing onto
the current main, since this one touches production code.
Every call site of every moved symbol was enumerated before the edit
(`BUILTIN_AGENT_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`,
`GENERIC_AGENT`, `LEGACY_AGENT_ALIASES`, `THIRD_PARTY_SUBAGENT_PRESETS`) and the
re-export is what keeps them all valid.
Effect on the dependency graph, measured before and after:
```
config -> agent edges 2 -> 0
packages in an import cycle 22 -> 19 (out of 40)
mutually importing pairs 14 -> 13
```
The three packages that leave the cycle were only ever pulled in through this
one pair.
- [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: the same names, the same validation, the same failure
messages. The reserved-name guard and the preset provenance check both still run
at parse time on all three transports. Backward compatibility is why
`builtin_agents` re-exports rather than relocating its public surface, and why
`LEGACY_AGENT_ALIASES` moves intact -- stored records under the old lowercase
name still resolve.
Rollback is reverting the one commit. The risk this leaves behind is the
two-spellings drift, which is why the equality pin ships in the same commit
rather than as a follow-up.
## Related Issues
N/A
## Summary
Raven-Code gains a product-owned coding tool set and engineering guidance. The code-flow plugin supplies read_file, write_file, edit_file, list_dir, glob, todo, and exec through the host's existing plugin interfaces. It adds long-line read limits, explicit non-overlapping occurrence edits, Python syntax feedback, brace globbing with visible partial/error results, persistent checklists, and execution timeout/output reporting. All implementation changes are under agents/raven-code; raven/, other agent implementations, and both UIs have no diff.
Read-before-edit checks use records isolated by Raven-Code runtime and conversation. A successful read or full write establishes a record; appending to unseen or stale existing content does not grant editing permission. Fresh ACP sessions have distinct keys and separate records/checklists. Resuming an existing session restores its plan, and session deletion clears its product state. Tool binding covers user and subagent turns, including runs with flow guidance disabled.
Repository AGENTS.md, CLAUDE.md, and CONTEXT.md enter system context through Raven-Code's existing before_iteration hook. User queries, persisted transcripts, and /new and /help command handling stay intact. Each candidate is resolved and read only if it remains inside the resolved working directory, including absolute names, parent traversal, and symlink targets. Contained aliases are read once. The hook preserves the host system prefix, replaces its own addition on repeated iterations, and sizes it against the remaining prompt allowance with tools, pending checklist restoration, and the active model's reply ceiling counted. Truncation is explicit. The product uses existing hook and observer interfaces; no shared runtime extension or new command interception is added. The launcher seeds model-specific coding conduct, independently switchable engineering discipline, the product identity, and tool guidance. Untouched managed prompt copies refresh across upgrades while operator edits are preserved. Workspace and execution settings follow host configuration, including when rendering an already rendered configuration. One-shot CLI hosting defaults permissions to full because it cannot answer approval prompts; explicit permission configuration wins, and ACP hosting keeps the host default.
Completion verification gates and the code-verifier plugin are outside this change.
## 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 --frozen --python 3.12 --extra dev pytest tests/test_agents_code*.py tests/test_agent_hook*.py tests/test_context_engine_factory.py tests/test_kernel_budget.py tests/test_agents_research_tools.py tests/test_contracts_two_tier_ledger.py tests/test_l4_entrances.py tests/test_core_runtime_swap.py tests/test_acp_methods.py tests/test_context_scent.py tests/test_skill_hub_policy.py -q --tb=short`: 723 passed after rebasing onto current main. Coverage includes real ACP session creation and product-state isolation, real AgentLoop command dispatch and model-visible message roles, repository containment, user/subagent and concurrent-session binding, append behavior, permission propagation, tool schemas, prompt migration, and runtime contracts. Ordinary text mentioning /new reaches the provider; only the host's exact command form takes its existing command branch. Hook tests cover repeated/deep-copied contexts, token limits, host-prefix preservation, and checklist failure isolation.
- `make lint-python`: passed, including Ruff formatting across 1,899 Python files.
- `uv run --frozen --python 3.12 lint-imports`: 9 contracts kept, 0 broken.
- `make check-large-files check-source-language`, `git diff --check origin/main...HEAD`, and `uv run --frozen --python 3.12 python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- The title and description pass the repository's canonical PR checkers. No frontend sources, generated RPC artifacts, or dependency lockfiles changed. Rebase comparison preserves all eight commits; the only file touched by both the feature and intervening main changes is CONTEXT.md, in separate domain entries. Tests for main's updated skill policy are included above.
Earlier full-suite validation, before the final read-state, repository-instruction, and hook changes, used `uv run --frozen --python 3.12 --extra dev pytest -q --tb=short`. Clean main reported 20,241 passed, 6 failed, 20 errors, and 212 skipped. The candidate reported 20,392 passed, 7 failed, 20 errors, and 212 skipped on each of two runs. Both checkouts used Python 3.12.13 and identical versions of all 212 installed distributions. The 6 cron failures and 20 cron errors had identical test IDs. The additional failure differed between candidate runs:
- `test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`: an intermittent `KeyError: served_url` in unchanged research tooling. The module passed all 82 tests separately on both checkouts and in the final targeted run. A controlled main-only DNS response reproduces the symptom; the original failure's cause remains unconfirmed.
- `test_doctor_answers_where_the_memories_are`: the temporary-directory path caused terminal wrapping inside `mem-root`, breaking the unchanged assertion. The original test reproduces on main with a 30-character `--basetemp`; shorter paths pass on both checkouts.
The full suite was not rerun after the final read-state, repository-instruction, and hook changes, and is not claimed green. Validation ran on Linux; no macOS/Windows execution, live-model run, or prompt-cache cost measurement was performed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The workspace fence remains opt-in and uses the host's path enforcement. Read-before-edit is session-local editing discipline, not a file lock or an atomic concurrency guarantee. Runtime restart requires a fresh read. Full overwrite retains its existing behavior; reading before overwrite remains model guidance rather than a new hard restriction. The exec replacement is offered only when the configured sandbox backend is none; otherwise the host's exec remains active.
Automatic repository-instruction loading always enforces containment, independently of the optional file-tool workspace fence. Injection runs after host history selection and does not evict transcript messages to make room. If even the truncation/concurrency notice cannot fit beside the reply allowance, the turn reports insufficient context instead of making a model call. The added repository text is not promoted into the host's stable cache prefix. New tasks use new session IDs. The host's in-place /new command retains its session key and clears the transcript without clearing separate Raven-Code todo/read state. This existing command behavior is preserved; the product does not add refusal messages or a reset callback. Resuming a session intentionally retains its plan, and deleting it removes its saved plan. Large exec output is retained under the agent home's exec-output directory without a new TTL or count cap; files can be removed manually. Operator-edited prompt copies may require manual updates.
Set plugins.config.code-flow.tools.enabled to false to restore the host tool set. CODE_PROJECT_FILES=off disables repository instruction loading; CODE_CONDUCT=off and CODE_CONDUCT_DISCIPLINE=off control guidance independently. Reverting the change restores the previous product behavior.
## 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
- Add LM Studio, NVIDIA NIM, and separate MiniMax Global and MiniMax CN provider paths across configuration, routing, onboarding, and model discovery.
- Add bundled provider icons and accessible connected or disconnected status indicators to provider lists.
- Add provider homepage metadata to the RPC contract and link provider names in Settings, onboarding, and the model picker.
- Preserve the latest main branch per-model protocol metadata while mapping provider UI rows.
{width=876 height=600}
## 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 pytest tests/test_provider_catalog.py tests/test_rpc_model.py tests/test_rpc_schema_match.py tests/test_rpc_contract_shapes.py -x` - 534 passed, 4 skipped.
* `npm test` from `ui-web/` - 1,378 passed.
* `npm run type-check`, `npm run gen:check`, and `npm run build` from `ui-web/` - passed.
* `npm run type-check` and `npm run lint:rpc` from `ui-tui/` - passed.
* `.venv/bin/ruff check raven/providers/registry.py raven/rpc/methods/model.py raven/rpc/models.py tests/test_provider_catalog.py tests/test_rpc_model.py` - passed.
* `make check-source-language check-large-files` - passed.
* `git diff --check origin/main...HEAD` - passed.
* Visually verified the assembled Settings and onboarding provider lists; repository rules prohibit committing standalone screenshots.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The RPC homepage field is optional, and existing provider configuration remains compatible. Provider routing changes are covered by focused resolution, factory, and RPC tests. Roll back by reverting this feature commit.
## Related Issues
N/A
## Summary
- Add LM Studio, NVIDIA NIM, and separate MiniMax Global and MiniMax CN provider paths across configuration, routing, onboarding, and model discovery.
- Add bundled provider icons and accessible connected or disconnected status indicators to provider lists.
- Add provider homepage metadata to the RPC contract and link provider names in Settings, onboarding, and the model picker.
- Preserve the latest main branch per-model protocol metadata while mapping provider UI rows.
{width=876 height=600}
## 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 pytest tests/test_provider_catalog.py tests/test_rpc_model.py tests/test_rpc_schema_match.py tests/test_rpc_contract_shapes.py -x` - 534 passed, 4 skipped.
* `npm test` from `ui-web/` - 1,378 passed.
* `npm run type-check`, `npm run gen:check`, and `npm run build` from `ui-web/` - passed.
* `npm run type-check` and `npm run lint:rpc` from `ui-tui/` - passed.
* `.venv/bin/ruff check raven/providers/registry.py raven/rpc/methods/model.py raven/rpc/models.py tests/test_provider_catalog.py tests/test_rpc_model.py` - passed.
* `make check-source-language check-large-files` - passed.
* `git diff --check origin/main...HEAD` - passed.
* Visually verified the assembled Settings and onboarding provider lists; repository rules prohibit committing standalone screenshots.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The RPC homepage field is optional, and existing provider configuration remains compatible. Provider routing changes are covered by focused resolution, factory, and RPC tests. Roll back by reverting this feature commit.
## Related Issues
N/A
## Summary
Retires raven-code's worktree isolation and moves its workspace report off the reply text and onto the ACP wire; gives raven-code real effort tiers named after the host's ladder; and ports the two engine fixes of MR !512 from the retired vendored fork to trunk `raven/`, which is the engine the `agents/raven-code` product actually runs (the host discovers `agents/*/subagent.json` only, so !512's fixes protected code the host no longer launches). Rebased onto main after per-model API protocols (4fe30b0a) landed; what that changed for this branch is called out below.
Three product decisions behind the first part: an unattended dispatch has nobody to answer the write gate's authorization question, so a dirty checkout parked the node until its timeout; the coordination between parallel raven-code sessions becomes a prompt-level contract, told only when it applies; and the host keeps getting a machine-read report of what each session did to the working directory, without reading it out of prose.
- Retire the write gate and its worktree isolation (`agents/raven-code/plugins/code-flow`): the gate, the worktree allocation and the release observer go, the launcher renders no arming, and the roster line stops promising an authorization prompt. The vendored A side under `subagents/` is frozen and untouched.
- Tell parallel sessions about each other: the code-flow hook books each session into a process-wide ledger at its turn start, and when other sessions are mid-turn in the same working directory it puts a concurrency notice in front of this turn's prompt (the model's view of this turn only). A lone session hears nothing. Parallel DAG nodes are sessions of one raven-code process on one directory, so the process can count them itself; the host has no per-node place to say it.
- Relay a turn's `acp_meta` observer stash as the prompt response's `_meta` (`raven/acp/methods.py`): the loop_hooks paper already files what a hook stashes under `metadata["observers"]` onto the turn's last substantive assistant message and saves the session before the turn's ending reaches the stream; the methods layer reads that entry back and answers with it under `_meta`, the field ACP reserves for an agent's own metadata. Only messages the turn appended are read; a turn that filed nothing answers exactly as before. Generic: nothing in `raven/` knows what any plugin puts there.
- File raven-code's workspace report through it: at the send the hook measures the directory against the base commit pinned at the session's first turn (root, branch, head, commits past base, working tree, diff stat, a status that is ready only when every fact answered) and stashes it as `raven.harnessManifest`. Nothing comes from model prose; a directory outside git is reported as plain. The report is workspace-scoped (`scope: workspace`): with no worktree, HEAD is shared by every session in the directory, so `baseCommit..HEAD` is what the tree gained since the session's base, by whoever wrote it. The ledger remembers which sessions shared a directory (peers, for the rest of their lives); a report from a session with peers carries `attribution: shared` and `sharedWith`, keeps the git facts, but takes the status `shared_workspace` with the blocker spelled out and is never ready. A lone session keeps `attribution: session` and the previous statuses.
- Keep the response `_meta` on the run record (`raven/acp_client/acp_agent.py`, `RunActivity.response_meta`): verbatim, namespaced as the agent sent it, as `acp_response_meta` -- so it reaches the spawn record's `meta.json` and the DAG run's per-node entry through the same channel as the frame pointer. The host reads none of it.
- Give raven-code real effort tiers on the agents/ tree, named after the host's ladder: the product had no tiers of its own and fell back to raven's three built-in rungs, which by design leave raven's own effort untouched, so a host asking for `medium` or `max` changed nothing about the model's reasoning (and the vendored twin's `low` / `high` / `max` catalogue was one the host's clamp refused to map `medium` onto). main now carries the engine side itself (4fe30b0a: `AcpModeConfig.reasoningEffort`, carried through the resolved profile and the session policy onto every model call of the turn; the built-in tiers leave it inherited and stay inert for raven itself), so this branch keeps only what main lacks there: the tools-disabled wrap-up call a turn makes when it exhausts its iterations asks for the same effort, plus the tests for the knob. On top of it the launcher declares `medium` / `high` / `max` with `medium` and `max` as overlays moving exactly `agents.defaults.reasoningEffort` and `high` as the baseline, and the LiteLLM provider mirrors the effort into OpenRouter's `extra_body.reasoning.effort`, which litellm's `drop_params` never touches -- without that mirror the effort could be silently dropped for any model litellm cannot map behind the gateway. Verified against OpenRouter's documented vocabulary (`max` / `xhigh` / `high` / `medium` / `low` / `minimal` / `none`; for Anthropic, thinking budgets of roughly 95 / 80 / 50 / 20 percent of `max_tokens` for `max` / `high` / `medium` / `low`).
- Never prefill a thinking-only turn on a model that refuses it (`raven/agent/loop/recovery.py`, `turn_path.py`, `raven/contracts/llm_provider.py`, `raven/providers/*`). Empty-response recovery re-fed a thinking-only response as a trailing assistant message; Anthropic rejects that request while thinking is on, and through the gateway the rejection arrived as a stream that never produced a byte, so the turn sat on the request budget (the 2026-09-01 dispatched-run report, item 1). Providers now answer `supports_assistant_prefill(model)` -- default True; `LiteLLMProvider` says no for the Anthropic family by the same rule that puts `thinking_blocks` on the wire, and the lazy / per-model / resolving / endpoint-rotor wrappers forward the question to the provider they wrap. The classifier consults it before the prefill budget: a refused prefill takes the post-tool nudge when a tool just ran, else the plain retry budget, else gives up, so no request handed to such a provider ends on an assistant message. Nothing changes for a provider that accepts the prefill. The native Anthropic Messages provider needs no answer of its own: it already rewrites a trailing assistant message into user-side text, so no request it sends ends on an assistant message.
- Give the LLM stream its own idle timeout (`raven/providers/litellm_provider.py`, `raven/contracts/llm_provider.py`, `raven/config/schema.py`, `raven/providers/factory.py`, `resolving_provider.py`). `chat_stream` waited the whole request budget for every chunk, so behind `llmCallTimeout: 1800` a dead stream cost half an hour (report item 2). `agents.defaults.streamIdleTimeout` (default 180s, 0 disables) decides whether the stream is dead and resets on every chunk; the request budget is enforced separately on top, so a backend that trickles forever is still bounded. Every wait in the LiteLLM stream -- the open, the first pull, the retry after a refused cache breakpoint, each later chunk -- takes the smaller of the idle line and what is left of the budget. Per-model protocols now route a claude model onto the native Anthropic Messages provider and a gpt model onto the OpenAI Responses provider by default, so the deployed raven-code route (OpenRouter, `anthropic/claude-opus-5`) no longer streams through LiteLLM at all; both native SSE consumers had the same single cap and take the idle line beside the budget too, and the Anthropic provider, the Responses provider and the Codex request helper hand their idle line to the consumer.
- Replay the incident end to end (`tests/test_agent_loop_incident_replay.py`): the real `LiteLLMProvider` built from `agents/raven-code/config.json`'s provider and defaults blocks, driven over the streaming call with `acompletion` faked to behave as the gateway did. The replay pins the model to the chat protocol, the transport the incident ran on (per-model protocols arrived later); the native providers' idle line has its own suite. Run against `origin/main` before the fixes it reproduces the incident (requests end on an assistant message and the turn waits out the scaled budget; a dead stream stalls for the whole budget; the deployed block arms no idle line). On this branch all four tests pass.
- The two provider shape changes are on the contract tier, so `CONTRACTS_VERSION` moves 7 -> 8 -> 9 with the ledger pin (main took 6 -> 7 for `ChatDelta.thinking_blocks`). `CONTEXT.md` gains Response Meta, Harness Manifest and Concurrency Notice, the Session Mode entry names its third knob, and the Empty-Response Recovery entry names the new question.
Deliberately not in this MR: a main-model-visible summary line of the report (dag_tool / manager), a capability declaration for the relay in the initialize handshake, and a report for a turn that failed or was cancelled (`after_send` does not fire there; the host sees the stop reason). Also not ported from !512: the turn-policy pin against a concurrent `session/set_mode` (the host sends `set_mode` before `session/prompt` and never during a running turn of the same session, so the race is unreachable in this deployment) and `extra="forbid"` on the `acp` config block (trunk's stated posture for such fields is warn-and-drop, and the raven-code launcher writes that block from code).
Known limit, same as in !512: the loop asks about the model the call was made for, so a routing fallback onto an Anthropic model mid-call would not be guarded (no routing is configured for raven-code, and the streaming path has no fallback).
Review round one on !529, three findings, all addressed here. (1) Blocking, effort did not cover compaction: the two head-summary calls transcript compaction pays for (proactive over the trigger line, reactive after an overflow) called `provider.chat` with no effort, so a `max` session that compacted mid-turn summarized at the connection's default; `_summarize_head` now takes the turn's effort and both call sites pass the policy the turn read at its start, with two tests driving a turn across the context limit. (2) Blocking, the report claimed shared commits: two sessions from one base, A commits, B does nothing, and B's `baseCommit..HEAD` listed A's commit as B's, even ready for integration; fixed by the workspace scope and attribution described above -- git alone cannot say whose commit is whose, so the report says whether it may be read as one session's at all. (3) Nonblocking, the ledger's in-flight mark was refreshed only at a turn's start and send, so a turn longer than the ttl vanished from the count its peers were told; the hook now refreshes the mark at every iteration, and the ttl keeps expiring only a turn that stopped reporting. The pipeline failure on the previous head was the test job hitting the runner's 45-minute limit ("Node is not ready" at about 43 percent), not a test verdict; the same job reproduced in the CI image on this head passes completely (see Verification).
Review round two on !529, one blocking finding, addressed here: the session effort still bypassed the in-turn watch-work classifier. After a relevant tool result the turn may pay for one more model call, the judgement of whether the request touches an on-call agent's watched path (two call sites in `_note_watch_work`: the look at a path, and the shape of a hand-off); both went through `_llm_call_stream` with no effort, so a medium/max session with an on-call watcher ran that classifier at the provider default. `_note_watch_work` now takes the turn's pinned effort and hands it to both calls, and the turn path passes the policy it read at its start; three unit tests read the kwargs each classifier call was made with, and one loop-level test checks the turn path hands the pinned effort to the helper for every tool result it judges. Left nonblocking, as the review marked them: a single provider or tool wait longer than the ledger's one-hour ttl still has no heartbeat inside it (the mark is refreshed at every iteration, not mid-wait), and the recovery-rung suggestion.
## Type
- [x] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_watch_work.py tests/test_agent_loop_session_effort.py -q` -> 75 passed (round two: the watch-work classifier is called with the pinned effort at both sites, nothing when none is pinned, and the turn path hands it over)
- `uv run pytest tests/test_agent_loop_session_effort.py tests/test_agents_code_flow_manifest.py tests/test_agents_code_flow_sessions.py tests/test_agents_code_flow_plugin.py tests/test_agent_loop_context_overflow.py tests/test_plugin_session_observers.py tests/test_agent_hook_contract.py tests/test_agents_code_launcher.py -q` -> 169 passed (the round-one fixes: the compaction summary carries the session's effort across the context limit; a shared directory turns the report to `shared_workspace` and unready; a long turn stays counted)
- `uv run pytest tests/test_agent_loop_incident_replay.py tests/test_providers_native_stream_idle.py -q` -> 19 passed; the replay file against a clean `origin/main` worktree -> 3 failed on exactly the incident's three symptoms (four requests in a row end on an assistant message; the dead stream stalls for the whole scaled budget; `GenerationSettings` has no idle line), 1 passed
- Targeted suites on the rebased branch (`-p no:xdist`): code-flow plugin / sessions / manifest, both launchers, `test_acp_methods` / `test_acp_modes` / `test_acp_server`, `test_subagent_acp` (against the real stub server, which gained a `meta` mode that answers a prompt with `_meta`), `test_agent_loop_session_effort` / `test_agent_loop_iteration_hooks`, `test_litellm_provider_reasoning`, `test_agent_hook_contract` (the hook surface fingerprint is unchanged; the relay reads an existing seam), `test_contracts_two_tier_ledger` (the pin at 9), `test_plugin_tool_gates` / `test_plugin_session_observers`, `test_agent_loop_empty_recovery` (13 new tests), `test_litellm_provider_timeout` (5 new), `test_litellm_provider_stream`, `test_provider_stream_fallback`, `test_providers_factory`, `test_resolving_provider`, `test_openai_codex_provider`, `test_provider_protocol`, `test_agent_loop_context_overflow`, `test_watch_work`, `test_agents_oncall_flow_hooks` -> 888 passed
- `make lint-python` green; `make lint-imports` -> 8 contracts kept, 0 broken; `make check-large-files`, `make check-vendored-subagents` and `make check-vendored-invariants` green (nothing under `subagents/` changed); `git diff --check` clean
- The CI `tests` job reproduced locally in its own image and command sequence (`python:3.12-slim`, `uv sync --locked --all-extras --dev`, `uv run --all-extras pytest -q`, four xdist workers) on this head -> 19250 passed, 192 skipped, 0 failed in 5m40s. The pipeline on the branch's first head died with the runner's node ("Node is not ready" at about 43 percent, then the 45-minute cap hit during after_script and cleanup), not on a test verdict: the same job reproduced on that commit (a78636b3, a real clone) -> 19014 passed, 0 failed, and pipeline 2826205430 on the round-one head passed.
- Full host suite (`make test-python`) on the rebased branch -> 19269 passed; the failing set is the pre-existing cron timezone family only (6 failed + 20 errors, no tzdata on the machine), nothing else
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour changes for raven-code: no more first-write authorization prompt and no worktree; parallel sessions on one directory can write the same file, and are told so; a host `medium` or `max` session now actually changes the model's reasoning effort (it used to change nothing), and every OpenRouter-routed request carries the effort in the gateway's own `reasoning` object. The prompt response of a raven-serving-ACP agent gains a `_meta` key only when a hook filed one; existing clients that read `stopReason` alone are unaffected (the ACP schema declares `_meta` on the response). The host's run records gain one optional key. The workspace report's `readyForIntegration` is false whenever another Raven-Code session shared the directory, so an integration step reading it must expect `shared_workspace` on parallel DAG nodes and handle that case itself.
Behaviour changes for every raven-serving product on trunk, not only raven-code: a thinking-only empty response on an Anthropic-family model is now retried or nudged instead of prefilled (previously a hang behind a gateway, a 400 direct); a stream silent for 180s is reported as a timeout instead of waiting out `llmCallTimeout` (a backend that stays silent while thinking for longer than that needs `streamIdleTimeout` raised or set to 0) -- on the LiteLLM path and on the native Anthropic Messages, OpenAI Responses and Codex paths alike. Providers that accept a prefill and streams that keep producing bytes see no change.
Rollback is a revert of the branch's commits.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Follows MR !512, which carried the same two engine fixes on the retired vendored line under `subagents/`; the host no longer launches that line.
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
The serve lane leaves the vendored fork engine for installed trunk
raven acp, and everything the swap was waiting on boards in the same
commit: the rendered config carries the plugin dirs so the write gate
is production-discovered, the workspace env arming retires into the
config slice with both layouts spoken for, the CLI adjudication host
lands in fork bytes on trunk's public session API, and the factory
face pins two-sided against the fork's config intent with trunk's six
new tools disabled by name. The review's finding lands with it: the
render that arms the gate also enables it, because a launcher whose
own two lines disagree reopens the ungated-writes hole on any custom
config, while an operator's explicit opt-out still survives the
render. One commit reverts the whole swap; neither engine can misread
the other's session files, and that dormancy is on the ledger.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
The fork's workspace-gate semantics port onto the tool-gate face as
the code product's plugin: the classifiers, the lock discipline and
the pending protocol keep their fork bytes, approval asks travel the
direct-ask grant, the escape guard reads the explicitly threaded
workdir, and release rides the session-delete observer keeping any
worktree that still holds ignored-only content. One deliberate
departure closes the seam's own edge: a malformed config slice casts a
fail-closed sentinel gate that blocks mutating calls naming the slice,
because the plugin stack skips a raising factory and an enabled deploy
must never run ungated. Seventy of the fork's seventy-two gate tests
port tonight with one more brought forward and two deferred with
reasons on the ledger; the plugin stays undiscovered in production
until the exec swap renders the plugin dirs, keeping the swap ordering
intact.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>