## Summary
The canonical failure sentence `Error calling LLM
(<category>[@<provider>]): <detail>` was built in eleven places and
bounded in none, and every reader treated it as a sentence for a person:
the gateway handed a channel the vendor's whole body (for an auth
failure that is a masked key and the account URL it was rejected for; a
rejected-request body can quote the prompt back and run past Telegram's
split), the loop wrote the same body into the marker the model reads on
its next turn and into `turn_ended.reason`, and cron (since #675) stores
it as the job's `last_error`. Only the one-shot CLI had a 200-character
cut and a per-category wording.
One constructor now builds the sentence (`canonical_llm_error` in
`raven/providers/base.py`) and cuts the detail to 200 characters after
the verdict has been taken, so a needle deep in a rejected-request body
still decides the category; the untouched body stays on the call record.
A category table (`llm_error_summary`) gives every bucket the classifier
can reach one sentence with no vendor text. `TurnFailed` gains an
in-process `reported` flag, set by the Lane when the runner worded the
failure itself, and the gateway's reply to a channel reads: a canonical
failure -> the category sentence; a reported non-canonical failure ->
its own words, bounded; a crash -> the canned sentence. The marker a
broken turn leaves is worded for its two readers: the model-facing text
names the category, `turn_ended.reason` keeps the provider's account for
whoever diagnoses it. A crash's text is bounded by a kernel-local
constant so `raven.spine` still imports nothing from `raven.providers`.
Folded in: the cut-stream exit in `streaming.py` now spends the
verdict's retryability when a thought had already reached a wired
reasoning callback (the rule the exits beside it hold since #673), and
the gateway pops a read-back conversation's stored reply on every exit
so a failed cron run cannot hand its submitter the previous run's text.
This reverses the choice #666 made to send a channel the provider's own
sentence.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_error_classification.py tests/test_gateway_spine.py tests/test_agent_loop_broken_turn.py \
tests/test_cli_agent_commands.py tests/test_agent_loop_stream.py tests/test_agent_loop_llm_error_patience.py \
tests/test_spine_scheduler.py tests/test_spine_scheduler_lane.py tests/test_core_cron_stack.py tests/test_spine_events.py -q
uv run pytest tests -q --ignore=tests/integration
uv run ruff check . && uv run ruff format --check . && uv run lint-imports
```
Live check with an isolated agent home, `raven serve` and a
playwright-driven page, against local fake endpoints. (1)
OpenAI-compatible endpoint answering 401 with a masked key and the
account URL: `raven agent -m hi` still prints the vendor reason and the
`Fix:` line and exits 1; the page shows the red failed-turn row; the
persisted `turn_ended.reason` is exactly 200 characters ending in `...`
(this failure raises, so it takes the crash path and gets the kernel
bound). (2) The same endpoint answering 500 with a 5000-character body:
the persisted reason is again 200 characters. (3) Anthropic Messages
endpoint that streams two text deltas and then sends an `error` event
with a 5000-character message (an error response, so the canonical
path): the page row reads `Error calling LLM (server@anthropic):
overloaded_error: Overloaded: ...`, `turn_ended.reason` is the head plus
200 characters of detail (238 in total), and the model-facing marker
text reads `(turn failed: The provider returned a server error
(anthropic). The runtime log has the provider's own account.)`. (4) The
same endpoint cutting the stream without a terminal event: the row reads
the unchanged short canonical sentence. The channel reply is covered by
tests/test_gateway_spine.py, which drives a real DeliveryHub through a
fake channel.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
(CONTEXT.md entries updated in this change; no user-facing doc describes
channel error wording)
## Risk
- A channel reader gets the failure's category and endpoint (for example
`The provider rejected the credentials (openrouter). The runtime log has
the provider's own account.`) instead of the vendor's sentence; a
single-user deployment loses detail it could only get from the chat, a
group stops seeing key fragments and account URLs.
- Every canonical failure sentence is cut to 200 characters of detail
with a trailing `...`, on the page, in the TUI, in `turn_ended.reason`,
in cron's `last_error` and in the CLI line; the full body stays on the
call record and in the runtime log. A long `invalid_request` tail that
the page used to show in full is now cut.
- The marker text the model reads back after a failed turn names the
category instead of quoting the vendor; the model's visible history
changes.
- With a wired reasoning callback (web, TUI) a stream cut after its
thought is no longer retried by the loop's ladder unless
`llmRetryAfterOutput` is on.
- `TurnFailed` has a new in-process field; an out-of-tree consumer
constructing it positionally with five arguments would now set it.
- Rollback: the gateway commit alone restores the vendor sentence to
channels; the other commits stand on their own.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
On the Anthropic Messages adapter a stream that fails after the reply
has started is reported as a terminal error delta, and `stream_llm_call`
in `raven/providers/streaming.py` never applied its own rule to that
exit: a failure after rendered output is not asked again unless
`llmRetryAfterOutput` says so. The verdict came back retryable, the
loop's ladder (15/30/60s) asked again up to three more times, and each
attempt re-streamed the same paragraph as a fresh episode before the
turn finally failed. The sub-agent backend read the same verdict and
re-asked too.
The error-delta exit now spends the verdict's retryability when output
was rendered and the caller did not ask for retries after output,
through one helper that classifies a missing verdict first (so the loop
cannot re-derive a retryable one from the text); a warning records the
decision. Spent rather than raised, so the classification survives for
the surfaces that show it and the other error-response recoveries
(window shrink, image drop) still run.
Second, a failed call's `LLMResponse.content` now always carries the
provider's account of the failure. The `TimeoutError` exit used to put
the half answer there when retries after output were on, and
`_llm_failure_detail` in the loop had to guess which meaning `content`
had from that setting. The streaming exit words the failure; the turn
already buffers what streamed from its own delta callback and files it
as the assistant message it was, so nothing the reader saw is lost. This
reverses the decision PR #467 pinned in
`tests/test_agent_loop_stream.py` (content stays the words after
output); that test is rewritten to the new rule, not deleted.
Covered at three altitudes: the helper, the whole loop, and the real
Messages adapter over an `httpx.MockTransport` that cuts the SSE stream
after two text deltas.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_loop_stream.py tests/test_agent_loop_llm_error_patience.py \
tests/test_agent_loop_broken_turn.py tests/test_provider_protocol.py tests/test_agent_loop_run_emit.py \
tests/test_agent_loop_dead_end_retry.py tests/test_provider_stream_fallback.py tests/test_litellm_provider_stream.py \
tests/test_transport_failure_paths.py tests/test_provider_endpoint_rotor.py tests/test_subagent_direct_chat.py -q
uv run ruff check . && uv run ruff format --check .
```
Live check with an isolated agent home whose Anthropic provider points
at a local endpoint that answers `/v1/messages` with `message_start`,
`content_block_start`, two `content_block_delta` text events and then
closes the socket, with `llm_error_retry_delays=[2,2,2]`. Before the
change the endpoint was called 4 times and the wire carried
`episode.start` x4 and `token.delta` x8 (the same paragraph streamed
four times) before the `error` frame. After the change the endpoint is
called once, the wire is `message.start`, `episode.start`, `token.delta`
x2, `error`, the log says `Stream LLM error [unknown] after 103 chars of
output; not asking again`, and the page shows the one paragraph followed
by the red failed-turn row, after a reload too.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no
user-facing doc describes the retry ladder)
## Risk
- Anthropic (the only in-tree adapter that reports a stream failure as a
terminal error delta): a failure after the first delta now fails the
turn at once instead of the loop waiting out its ladder and redrawing
the same answer up to four times. A turn that used to recover on a later
attempt now ends as a failed turn with the words that streamed kept
above the marker.
- `rendered()` counts a streamed thought as output when the caller wired
`on_reasoning_delta`, so on the web page and the TUI a stream that died
after reasoning and before any text now also fails without the ladder;
channels, cron and the one-shot CLI wire text only and are unaffected.
- A failed call's content is always the failure's account now. With
`llmRetryAfterOutput` on, a mid-answer stall's reason changes from the
loop's generic sentence to the provider's own canonical one; the
sub-agent backend raises `SubagentNoAnswerError` for a rendered stream
that failed instead of re-asking through the non-streaming call.
- With `llmRetryAfterOutput` on and a provider whose error response is
not in the canonical shape (LiteLLM's `upstream_transport_failure`
account is the one in-tree case), the reason is now that provider's own
sentence instead of the loop's generic one; a channel reader then gets
the canned failure sentence from the gateway, since it forwards only
canonical sentences. The follow-up that bounds and categorises the
channel wording covers this.
- Rollback: revert the two commits; no data or wire shape changes.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.
`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.
`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.
`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands and results, all at the branch head after rebasing onto `main`:
```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s
$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s
$ make lint-python # ruff check + ruff format --check
exit 0
$ make lint-imports
Contracts: 9 kept, 0 broken.
$ make lint-ui
exit 0
$ make check-source-language
exit 0
$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```
Two regression tests were added next to the existing state-directory fence cases:
- the session-workdir call reads a node's report under the sessions tree and still
refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
while one pinned at the state root itself does not.
The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.
Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.
Known gaps, disclosed rather than worked around:
- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
`bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
gateway's own file paths, not through a rebuilt page bundle.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.
`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.
Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.
## Related Issues
N/A
## Summary
The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.
`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.
`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.
`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands and results, all at the branch head after rebasing onto `main`:
```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s
$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s
$ make lint-python # ruff check + ruff format --check
exit 0
$ make lint-imports
Contracts: 9 kept, 0 broken.
$ make lint-ui
exit 0
$ make check-source-language
exit 0
$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```
Two regression tests were added next to the existing state-directory fence cases:
- the session-workdir call reads a node's report under the sessions tree and still
refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
while one pinned at the state root itself does not.
The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.
Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.
Known gaps, disclosed rather than worked around:
- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
`bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
gateway's own file paths, not through a rebuilt page bundle.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.
`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.
Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.
## Related Issues
N/A
## Summary
`tests/test_agents_code_flow_exec.py` carried a pin on trunk's `DirectExecutor`
dropping a timed-out command's output. That was one of the reasons the code flow
replaced the executor, and the pin's own docstring said what should happen to
it: "pinned so a trunk fix can retire it". The trunk fix landed, the pin
asserted the opposite of the truth, and `main` went red.
**`main` is no longer red.** While this sat in review, a separate change
replaced the pin with `test_trunks_executor_preserves_output_on_timeout`. That
resolved the breakage and is the version kept here; this branch was rebased onto
it rather than carrying a competing test. What remains is what that replacement
did not cover:
- **Why the fork exists on that axis.** The replacement asserts the new fact in
one line and says nothing about what still separates the two executors. Trunk
signals a kill through the stderr line and `exit_code` and nothing more, while
`CodeExecResult` also flags `timed_out` and renders `TIMED_OUT_NOTE`, which
tells the model its output is a fragment rather than a whole run. That
difference is now asserted and explained where the pin used to sit.
- **Three prose claims that are still false on `main`.** Both module docstrings
advertise "the fork's three fixes" and describe trunk waiting on
`communicate()` and losing the buffered output, in the present tense; the exec
factory's docstring lists partial output as a difference. Each is corrected to
say what is true now and what is left.
The fork's drain now duplicates trunk's. That is noted in the docstring as the
fork owners' call, because nothing depends on which of the two performs it and
this change should not spend itself on that. No code is removed and no behaviour
changes.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
tests/test_sandbox_unit.py tests/test_agents_oncall_flow_hooks.py` -- 183 passed
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
Mutation, to show the added assertions are load-bearing rather than decorative:
```
trunk discards partial stdout again -> 1 failed (the inherited assertions)
fork stops rendering TIMED_OUT_NOTE -> 2 failed (the added pair)
```
One mutation deliberately reported because it did **not** bite. An earlier
revision asserted only that trunk's rendering lacks `TIMED_OUT_NOTE`. Making
trunk emit a partial-output note in its own wording left the file green, because
the constant is matched verbatim -- and that form of assertion is equally
satisfied by a fork that stopped marking anything at all. Both sides are now
measured in one run, so the absence reads as a difference rather than as a
feature nobody has; removing the fork's append is what the second mutation
above does.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Left unchecked: no user-facing document describes either executor's timeout
behaviour. The three corrected texts are module and factory docstrings. The
model-facing half was checked separately and needed nothing -- the `timeout`
parameter description says a command that hits its limit "is killed and the
output it produced so far comes back marked partial", which is still true of
this tool.
## Disclosed
Four failures in `tests/test_ppt_engine_build_tool.py` appear in a wider
selection and are **not** from this change. They reproduce at the `main` tip in
a worktree holding none of it, and the cause is local layout rather than code:
`raven_ppt` resolves to the primary checkout's `plugins-dist/ppt-engine`, which
sits at an older revision than a fresh worktree's tests. Not investigated
further here.
How the red reached `main` is worth stating, since the cause was process rather
than code. The executor fix was pushed and then rebased onto a `main` that had
gained the pin in the meantime; the rebase surfaced the collision, and the merge
landed on the pre-rebase head before the rebase was pushed. Rebasing before the
push, as the contribution rules require, would have surfaced it while that
merge request was still open.
## Risk
No behaviour change: assertions added to an existing test, three docstrings
corrected, no production statement altered and no code removed. The duplicated
drain in the fork's executor is left exactly as it is.
Rollback is a revert of the two commits. `main` stays green either way, since
the breakage itself was resolved separately; what a revert costs is the stated
difference between the two executors and the accuracy of the three docstrings.
## Related Issues
N/A
## Summary
`tests/test_agents_code_flow_exec.py` carried a pin on trunk's `DirectExecutor`
dropping a timed-out command's output. That was one of the reasons the code flow
replaced the executor, and the pin's own docstring said what should happen to
it: "pinned so a trunk fix can retire it". The trunk fix landed, the pin
asserted the opposite of the truth, and `main` went red.
**`main` is no longer red.** While this sat in review, a separate change
replaced the pin with `test_trunks_executor_preserves_output_on_timeout`. That
resolved the breakage and is the version kept here; this branch was rebased onto
it rather than carrying a competing test. What remains is what that replacement
did not cover:
- **Why the fork exists on that axis.** The replacement asserts the new fact in
one line and says nothing about what still separates the two executors. Trunk
signals a kill through the stderr line and `exit_code` and nothing more, while
`CodeExecResult` also flags `timed_out` and renders `TIMED_OUT_NOTE`, which
tells the model its output is a fragment rather than a whole run. That
difference is now asserted and explained where the pin used to sit.
- **Three prose claims that are still false on `main`.** Both module docstrings
advertise "the fork's three fixes" and describe trunk waiting on
`communicate()` and losing the buffered output, in the present tense; the exec
factory's docstring lists partial output as a difference. Each is corrected to
say what is true now and what is left.
The fork's drain now duplicates trunk's. That is noted in the docstring as the
fork owners' call, because nothing depends on which of the two performs it and
this change should not spend itself on that. No code is removed and no behaviour
changes.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
tests/test_sandbox_unit.py tests/test_agents_oncall_flow_hooks.py` -- 183 passed
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
Mutation, to show the added assertions are load-bearing rather than decorative:
```
trunk discards partial stdout again -> 1 failed (the inherited assertions)
fork stops rendering TIMED_OUT_NOTE -> 2 failed (the added pair)
```
One mutation deliberately reported because it did **not** bite. An earlier
revision asserted only that trunk's rendering lacks `TIMED_OUT_NOTE`. Making
trunk emit a partial-output note in its own wording left the file green, because
the constant is matched verbatim -- and that form of assertion is equally
satisfied by a fork that stopped marking anything at all. Both sides are now
measured in one run, so the absence reads as a difference rather than as a
feature nobody has; removing the fork's append is what the second mutation
above does.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Left unchecked: no user-facing document describes either executor's timeout
behaviour. The three corrected texts are module and factory docstrings. The
model-facing half was checked separately and needed nothing -- the `timeout`
parameter description says a command that hits its limit "is killed and the
output it produced so far comes back marked partial", which is still true of
this tool.
## Disclosed
Four failures in `tests/test_ppt_engine_build_tool.py` appear in a wider
selection and are **not** from this change. They reproduce at the `main` tip in
a worktree holding none of it, and the cause is local layout rather than code:
`raven_ppt` resolves to the primary checkout's `plugins-dist/ppt-engine`, which
sits at an older revision than a fresh worktree's tests. Not investigated
further here.
How the red reached `main` is worth stating, since the cause was process rather
than code. The executor fix was pushed and then rebased onto a `main` that had
gained the pin in the meantime; the rebase surfaced the collision, and the merge
landed on the pre-rebase head before the rebase was pushed. Rebasing before the
push, as the contribution rules require, would have surfaced it while that
merge request was still open.
## Risk
No behaviour change: assertions added to an existing test, three docstrings
corrected, no production statement altered and no code removed. The duplicated
drain in the fork's executor is left exactly as it is.
Rollback is a revert of the two commits. `main` stays green either way, since
the breakage itself was resolved separately; what a revert costs is the stated
difference between the two executors and the accuracy of the three docstrings.
## Related Issues
N/A
## Summary
An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed!573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.
- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.
What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.
## Review round 1 (2026-09-09, on !600, superseded by this MR)
- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.
## Review round 2 (2026-09-10)
- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.
## Review round 3 (2026-09-10)
- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.
## Review round 4 (2026-09-10)
- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
tests/test_agents_oncall_flow_escalation_tools.py -q # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents # clean
uv run lint-imports # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit # in sync, clean
```
New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).
Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)
## Risk
- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.
A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.
## Related
Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
## Summary
An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed!573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.
- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.
What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.
## Review round 1 (2026-09-09, on !600, superseded by this MR)
- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.
## Review round 2 (2026-09-10)
- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.
## Review round 3 (2026-09-10)
- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.
## Review round 4 (2026-09-10)
- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
tests/test_agents_oncall_flow_escalation_tools.py -q # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents # clean
uv run lint-imports # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit # in sync, clean
```
New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).
Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)
## Risk
- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.
A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.
## Related
Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
## Summary
A model call that returned nothing used to end a turn, and nothing in the record said why.
This branch closes that in five parts, all on the host runtime.
- **The output ceiling is the model's, not ours.** `resolve_max_output_tokens` takes the
figure the model declares instead of a repo default, reserves it against the id the
request actually goes out under, and counts cached prompt tokens toward the window so a
cached prefix stops looking free. One call is given 64k of room and says so on the wire;
the transcript summary budget goes to 32k. Two small output pins keep deliberate
headroom, and the commit says why they do not move.
- **A retry has to ask a different question.** An empty completion previously repeated the
same request and got the same answer. The ladder now descends by **what a rung sends**
rather than by its label, the transcript summary is no longer asked to think, and the
empty-completion retry differs from the call it replaces.
- **Time to first byte is bounded.** `llmFirstByteTimeout` applies on the direct adapters
as well as through the gateway, a bound of zero means off rather than a bound at the
total, and the guard's deadline is distinguished from a strategy's own `TimeoutError` so
a fallback answers for the right one.
- **An effort travels as an effort.** `glm` is out of `inferred_protocol`'s Anthropic prefix
tuple and the hand-written `_THINKING_BUDGETS` table is deleted, so a label reaches the
vendor as a label rather than as a token count this repo invented. Measured on the wire
before the change: 42 calls produced 261,980 characters of reasoning against a budget of
1024 that the route discarded, while our own `max_tokens` went out on every call because
that transport requires the field.
- **The record says what was asked and what came back.** A failed call is visible in the
turn and readable in the record; the reasoning count is kept; a failure's headers are
recorded as the failure's, not as a stream's server; `llm.input` gains a `generation`
block and the span gains `llm.request.*`, with a test pinning that no credential appears
in either. `llm.request_bytes` is documented as an estimate instead of claiming to be
the wire. A frozen turn is stopped rather than nudged once.
## Type
- [x] Fix
- [x] Feature
## Verification
- `uv run --frozen pytest` over the full suite: **20354 passed**, with 6 failures and 20
errors that are this box lacking `/usr/share/zoneinfo` -- all in `test_cron_tool.py` and
`test_cli_cron_commands.py`, which this branch does not touch. Reproduced with the
identical signature on a clean detached `origin/main` worktree, and CI ships tzdata, so
its `tests` job is the authoritative check. Gated on `set -o pipefail` and
`${PIPESTATUS[0]}`.
- `make lint-python` exit 0; `lint-imports` 9 kept, 0 broken.
- Contract pins re-derived against current `main` rather than carried over:
`CONTRACTS_VERSION` **17** (main is 16), the digest from one run of the pinning test, and
`CONTRACTS_LINE_CEILING` **2_791** against 2771 actual. 34 pinning tests pass.
- The request shape verified on real captured bodies rather than inferred: after the change
a deck call is `POST /v1/chat/completions` carrying `reasoning: {"effort": ...}` at the
top level, the configured temperature, and **no** `max_tokens`; before it, the same call
was `POST /v1/messages` carrying `thinking: {"type": "enabled", "budget_tokens": 1024}`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
The routing change moves every `glm` model from the native Anthropic Messages transport to
LiteLLM chat. That changes which client serves the deck agent and the host default model,
so it is the one item here worth a real run before it is relied on. Measured consequences
on a live deck: no truncations, no length-stops, no empty completions and no retries across
40 calls, and prompt-cache read rates in the same band as the Messages route -- `glm` takes
no `cache_control` breakpoints on either transport because OpenRouter caches it
automatically, so caching is unaffected. A provider that needs an Anthropic-compatible
address can still name `protocol: "anthropic"` explicitly, and a test pins that route.
Rollback is per part: each of the five is its own commit range, and the routing change is a
single line in `raven/providers/protocol.py`.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
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
Three DAG-side behaviours from the autoresearch runs, none of which adds a node field.
- A running node that shows no sign of life for ten minutes is announced to the main agent through the existing exception channel, once per silent stretch. A notice, not a timeout: nothing is cancelled, and the message says waiting is fine when the rest of the run is moving. `RunActivity.last_event_ms` is stamped by every activity report, transcript republishes included, so the acp and openai_api lanes (whose only in-flight report is a transcript) are seen as alive; the review reproduction of the false positive is kept as the regression. The announcer's required keyword is passed (a TypeError used to be swallowed).
- An invented node field (`mode`, three runs in a row) is answered with the closed field set in one message instead of pydantic's field-only rendering.
- An oversized graph call is told about the ref escape hatch rather than only that it is too big.
- `resolve_dag_node` accepts `action` as an alias for `decision` (the name the model reaches for; three calls lost to "missing required decision"); the schema keeps `decision`.
## Type
- [x] Fix
## Verification
```
uv run ruff check raven tests && uv run ruff format --check raven tests # clean
uv run pytest tests/test_subagent_dag_runner.py tests/test_subagent_dag_core.py tests/test_subagent_dag_control_tools.py tests/test_subagent_acp.py tests/test_rpc_dag.py -q # 606 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD # clean
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] 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
No schema change: the node field set is what main has. The stall notice is informational and reaches the main agent through the channel node exceptions already use. Rollback is a revert of the squash commit.
## Related Issues
Split from !475 (closed), retargeted at main; the stall-watcher blind spot found in that review (note 3786214590) is fixed here.
## Summary
Three DAG-side behaviours from the autoresearch runs, none of which adds a node field.
- A running node that shows no sign of life for ten minutes is announced to the main agent through the existing exception channel, once per silent stretch. A notice, not a timeout: nothing is cancelled, and the message says waiting is fine when the rest of the run is moving. `RunActivity.last_event_ms` is stamped by every activity report, transcript republishes included, so the acp and openai_api lanes (whose only in-flight report is a transcript) are seen as alive; the review reproduction of the false positive is kept as the regression. The announcer's required keyword is passed (a TypeError used to be swallowed).
- An invented node field (`mode`, three runs in a row) is answered with the closed field set in one message instead of pydantic's field-only rendering.
- An oversized graph call is told about the ref escape hatch rather than only that it is too big.
- `resolve_dag_node` accepts `action` as an alias for `decision` (the name the model reaches for; three calls lost to "missing required decision"); the schema keeps `decision`.
## Type
- [x] Fix
## Verification
```
uv run ruff check raven tests && uv run ruff format --check raven tests # clean
uv run pytest tests/test_subagent_dag_runner.py tests/test_subagent_dag_core.py tests/test_subagent_dag_control_tools.py tests/test_subagent_acp.py tests/test_rpc_dag.py -q # 606 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD # clean
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] 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
No schema change: the node field set is what main has. The stall notice is informational and reaches the main agent through the channel node exceptions already use. Rollback is a revert of the squash commit.
## Related Issues
Split from !475 (closed), retargeted at main; the stall-watcher blind spot found in that review (note 3786214590) is fixed here.
## Summary
Three engine-side fixes from this weekend's live deck runs, one commit each, `plugins-dist/ppt-engine` only.
**1. The PDF preview follows a renamed deck; every turn starts in the deck folder.** The author copied the published `deck.pptx` to a title of its own with `exec` and named the copy; the digest check let it through, but the preview PDF sat beside the original under the original's stem, so the copy went out with none. `published_original(state_dir, copy)` finds the published deck a copy was taken from, and the hook puts the PDF beside the copy under its own name before announcing it. Separately, a turn started by a sub-agent's late result skips `before_user_inbound`, so the engine's repoint to `decks/<session>` never ran: a live run answered such a return one level above the deck (three `edit_file` calls on a path that was not there, a `ppt_build` that found no brief, a rebuild from nothing). The repoint is now an idempotent helper that `before_iteration` also runs on the first iteration, with the bookkeeping `after_send` needs.
**2. A page with no number is numbered by its place; a refused build says why.** The amber run wrote every outline page without `page` and lost the whole outline to `missing required pages[N].page`; `_numbering` demands 1..n in order anyway, so `page` is optional and defaults to the position in all three readers. A full build refused for blocking findings answered `not_delivered: the deck was not published` with no reason; the stage now names the count and the pages.
**3. A cover keeps the template's composition; `backdrop` dims under a scrim; `washed_backdrop` warns.** The Shanghai cover adapted the template's cover page, then deleted the layout's whole design group to make room for a photograph washed to 30% on a white page under black type, which read as fog. Three things pushed the author there: the skill's cover paragraph spoke only of `backdrop`, `replace_picture` refused a layout drawing and pointed at `backdrop`, and `ppt_generate_image`'s rule sent a real place to photography. Now: `backdrop` defaults to the form a reference cover uses (photograph at full strength, a plane of the theme's ink at `scrim=0.62`, type set to the theme's light colour with saturated accents kept; `scrim=None` with `alpha` at 0.12 or under is the texture form); `washed_backdrop` is a WARNING gate for a picture covering 80% of the page washed to 12%-80%, calibrated on the 8 bundled templates, 8 delivered decks and a reference deck (0 findings, fires only on the live cover and closing page); `drop_shape` refuses a layout shape and names `replace_picture(layout_pictures(slide)[0], ...)`; the bind reply, the generate-image description and the skill say the cover and closing page keep the template's composition, with an illustration slot taking a cut-out in the template's manner (`transparent=true`) even for a real place. Recorded as D31 in `docs/ppt-raven-design.md`.
Verified live on a fresh stack with the canonical templates: given the same Shanghai brief on `blue_minimal`, the author generated four cut-outs in the template's manner on its own, swapped them into the cover's and the closing page's layout slots through `layout_pictures`, and delivered an 8-page deck with no blocking finding in 69 minutes.
**4. A reply naming an unpublished copy is sent back with the build's refusal.** Two live runs answered a refused build with a `cp` of the build to a name of their own under `out/` and a reply that the deck was delivered; the turn ended on it, the correction the announcement appends reached only the delegating agent, and the run had to be adjudicated and started again to continue. The build stage now records why a build was refused (`deck/state/refused.json`: the note and the blocking findings; cleared by the next publish), and the hook rolls the iteration back once when a closing reply names a deck under `out/` that the publish step never recorded, putting the copy's name and the recorded refusal in front of the author before the hands-back test. A second such reply falls through to the unfinished nudges; the announcement's correction carries the same reason to the delegating agent.
Review fixes on top: a page that says no number keeps its declared role at its place (the roles take the plan's positional fallback instead of filing under page 0); `backdrop` with a `box` sets light only the type the scrim plane reaches (a title above a boxed photograph keeps the template's ink); the `alpha=0.25` layout-picture advice is gone from all five surfaces that carried it (skill row and paragraph, `layout_pictures` and `replace_picture` docstrings, the `ppt_template` roster ask, the `layout_picture` finding), which now agree with D31: `alpha=0.1` is a texture, 0.12-0.80 is the fog `washed_backdrop` reports, a photograph meant to be seen goes in at full strength under a plane of ink with light type.
Guidance corrected against the runtime: the skill said nobody is attached to a deck build and the run has no `ask_user`; the deck agent has the tool, `ppt_prepare` and `ppt_brief` already tell it to ask, and the identity prompt says questions go to the user. The skill now says to ask once (all questions in one call, a recommended option each), that the host relays the answer (a direct chat's user answers; a delegated run's host answers what the conversation settled and puts the rest to the user), and that only an empty or "not sent" answer is the unattended case where the recommended option is recorded as an assumption. The carried identity prompt stays the fork's bytes (it already says questions go to the user with `ask_user`; the byte-parity guard holds). The skill also said matplotlib is not a dependency of this route; it is (the formula typesetter) and imports in the program, so the sentence now says why a chart is still drawn as shapes, and the runner comment that repeated the claim is corrected.
## Type
- [x] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
GITLAB_TOKEN=... python3 plugins-dist/ppt-engine/fetch_templates.py (the canonical payload; the fork tree's copies differ on all 8)
PYTHONPATH=plugins-dist/ppt-engine uv run --frozen --no-sync pytest tests/test_ppt_engine_*.py -q
-> 3430 passed, 1 skipped
uv run --frozen --no-sync ruff check / ruff format --check <touched files> -> clean
uv run --frozen --no-sync python scripts/check_source_language.py origin/main..HEAD -> ok
```
At 7f98edd5 (review fixes and the copy nudge): `uv run --frozen --no-sync --python 3.12 pytest -q tests/test_ppt_engine_*.py` passed (full engine suite, exit 0); ruff check and ruff format --check clean on the changed files; `git diff --check` clean. New tests: `test_a_page_that_says_no_number_keeps_its_role_at_its_place`, `test_backdrop_in_a_box_lightens_only_the_type_the_plane_covers`, `test_a_refused_build_leaves_its_reason_where_the_hook_reads_it`, `test_a_reply_naming_a_copy_the_publish_step_never_wrote_is_sent_back_with_the_refusal`.
Mutation checks, each toggled and restored: the preview-beside-copy call removed (renamed-copy test fails), `before_iteration` renamed (skipped-inbound test fails), `page` required again (numbering test fails), the roster/scrim default toggled (backdrop tests fail), the gate registered without a fixture (`test_every_check_produces_the_severity_it_declares` fails). The skill's signature claims are checked by `test_every_checkable_claim_in_the_skill_still_holds` (2170 claims).
Replayed against the recorded failures, with the real tools and files (`.tmp/ppt_port/replay_fixes.py`): (a) the amber run's `ppt_outline` call, 20 pages and no `page` on any, against a copy of that deck's state -- accepted and numbered 1..20 (its web-verified `swept` entries removed first, since the tool re-opens those URLs live); (b) the Shanghai run's final reply naming the hand-copied pptx, against a copy of that deck's `out/` and `state/` -- the announce names the copy and a PDF now sits beside it under its own name; (c) the red run's late sub-agent return as an `Origin.SUBAGENT` turn through a real `AgentLoop` with the engine hook, reading `deck/build/build.py` -- "File not found" with `before_iteration` disabled, the file's contents with it.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (skill, tool descriptions, design doc D31)
## Risk
Author-visible behaviour only. `backdrop`'s default output changes (dark plane and light type instead of a wash); a script that wants the old wash passes `scrim=None` with a low `alpha`. `drop_shape` now raises on a layout shape. `ppt_outline` accepts pages without `page`. The new gate is WARNING-only and in no blocking set. Rollback: revert the three commits.
- [x] Security impact considered (no new input reaches anything)
- [x] Backward compatibility considered (recorded outlines unaffected; `replace_picture` and `layout_pictures` unchanged)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Three engine-side fixes from this weekend's live deck runs, one commit each, `plugins-dist/ppt-engine` only.
**1. The PDF preview follows a renamed deck; every turn starts in the deck folder.** The author copied the published `deck.pptx` to a title of its own with `exec` and named the copy; the digest check let it through, but the preview PDF sat beside the original under the original's stem, so the copy went out with none. `published_original(state_dir, copy)` finds the published deck a copy was taken from, and the hook puts the PDF beside the copy under its own name before announcing it. Separately, a turn started by a sub-agent's late result skips `before_user_inbound`, so the engine's repoint to `decks/<session>` never ran: a live run answered such a return one level above the deck (three `edit_file` calls on a path that was not there, a `ppt_build` that found no brief, a rebuild from nothing). The repoint is now an idempotent helper that `before_iteration` also runs on the first iteration, with the bookkeeping `after_send` needs.
**2. A page with no number is numbered by its place; a refused build says why.** The amber run wrote every outline page without `page` and lost the whole outline to `missing required pages[N].page`; `_numbering` demands 1..n in order anyway, so `page` is optional and defaults to the position in all three readers. A full build refused for blocking findings answered `not_delivered: the deck was not published` with no reason; the stage now names the count and the pages.
**3. A cover keeps the template's composition; `backdrop` dims under a scrim; `washed_backdrop` warns.** The Shanghai cover adapted the template's cover page, then deleted the layout's whole design group to make room for a photograph washed to 30% on a white page under black type, which read as fog. Three things pushed the author there: the skill's cover paragraph spoke only of `backdrop`, `replace_picture` refused a layout drawing and pointed at `backdrop`, and `ppt_generate_image`'s rule sent a real place to photography. Now: `backdrop` defaults to the form a reference cover uses (photograph at full strength, a plane of the theme's ink at `scrim=0.62`, type set to the theme's light colour with saturated accents kept; `scrim=None` with `alpha` at 0.12 or under is the texture form); `washed_backdrop` is a WARNING gate for a picture covering 80% of the page washed to 12%-80%, calibrated on the 8 bundled templates, 8 delivered decks and a reference deck (0 findings, fires only on the live cover and closing page); `drop_shape` refuses a layout shape and names `replace_picture(layout_pictures(slide)[0], ...)`; the bind reply, the generate-image description and the skill say the cover and closing page keep the template's composition, with an illustration slot taking a cut-out in the template's manner (`transparent=true`) even for a real place. Recorded as D31 in `docs/ppt-raven-design.md`.
Verified live on a fresh stack with the canonical templates: given the same Shanghai brief on `blue_minimal`, the author generated four cut-outs in the template's manner on its own, swapped them into the cover's and the closing page's layout slots through `layout_pictures`, and delivered an 8-page deck with no blocking finding in 69 minutes.
**4. A reply naming an unpublished copy is sent back with the build's refusal.** Two live runs answered a refused build with a `cp` of the build to a name of their own under `out/` and a reply that the deck was delivered; the turn ended on it, the correction the announcement appends reached only the delegating agent, and the run had to be adjudicated and started again to continue. The build stage now records why a build was refused (`deck/state/refused.json`: the note and the blocking findings; cleared by the next publish), and the hook rolls the iteration back once when a closing reply names a deck under `out/` that the publish step never recorded, putting the copy's name and the recorded refusal in front of the author before the hands-back test. A second such reply falls through to the unfinished nudges; the announcement's correction carries the same reason to the delegating agent.
Review fixes on top: a page that says no number keeps its declared role at its place (the roles take the plan's positional fallback instead of filing under page 0); `backdrop` with a `box` sets light only the type the scrim plane reaches (a title above a boxed photograph keeps the template's ink); the `alpha=0.25` layout-picture advice is gone from all five surfaces that carried it (skill row and paragraph, `layout_pictures` and `replace_picture` docstrings, the `ppt_template` roster ask, the `layout_picture` finding), which now agree with D31: `alpha=0.1` is a texture, 0.12-0.80 is the fog `washed_backdrop` reports, a photograph meant to be seen goes in at full strength under a plane of ink with light type.
Guidance corrected against the runtime: the skill said nobody is attached to a deck build and the run has no `ask_user`; the deck agent has the tool, `ppt_prepare` and `ppt_brief` already tell it to ask, and the identity prompt says questions go to the user. The skill now says to ask once (all questions in one call, a recommended option each), that the host relays the answer (a direct chat's user answers; a delegated run's host answers what the conversation settled and puts the rest to the user), and that only an empty or "not sent" answer is the unattended case where the recommended option is recorded as an assumption. The carried identity prompt stays the fork's bytes (it already says questions go to the user with `ask_user`; the byte-parity guard holds). The skill also said matplotlib is not a dependency of this route; it is (the formula typesetter) and imports in the program, so the sentence now says why a chart is still drawn as shapes, and the runner comment that repeated the claim is corrected.
## Type
- [x] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
GITLAB_TOKEN=... python3 plugins-dist/ppt-engine/fetch_templates.py (the canonical payload; the fork tree's copies differ on all 8)
PYTHONPATH=plugins-dist/ppt-engine uv run --frozen --no-sync pytest tests/test_ppt_engine_*.py -q
-> 3430 passed, 1 skipped
uv run --frozen --no-sync ruff check / ruff format --check <touched files> -> clean
uv run --frozen --no-sync python scripts/check_source_language.py origin/main..HEAD -> ok
```
At 7f98edd5 (review fixes and the copy nudge): `uv run --frozen --no-sync --python 3.12 pytest -q tests/test_ppt_engine_*.py` passed (full engine suite, exit 0); ruff check and ruff format --check clean on the changed files; `git diff --check` clean. New tests: `test_a_page_that_says_no_number_keeps_its_role_at_its_place`, `test_backdrop_in_a_box_lightens_only_the_type_the_plane_covers`, `test_a_refused_build_leaves_its_reason_where_the_hook_reads_it`, `test_a_reply_naming_a_copy_the_publish_step_never_wrote_is_sent_back_with_the_refusal`.
Mutation checks, each toggled and restored: the preview-beside-copy call removed (renamed-copy test fails), `before_iteration` renamed (skipped-inbound test fails), `page` required again (numbering test fails), the roster/scrim default toggled (backdrop tests fail), the gate registered without a fixture (`test_every_check_produces_the_severity_it_declares` fails). The skill's signature claims are checked by `test_every_checkable_claim_in_the_skill_still_holds` (2170 claims).
Replayed against the recorded failures, with the real tools and files (`.tmp/ppt_port/replay_fixes.py`): (a) the amber run's `ppt_outline` call, 20 pages and no `page` on any, against a copy of that deck's state -- accepted and numbered 1..20 (its web-verified `swept` entries removed first, since the tool re-opens those URLs live); (b) the Shanghai run's final reply naming the hand-copied pptx, against a copy of that deck's `out/` and `state/` -- the announce names the copy and a PDF now sits beside it under its own name; (c) the red run's late sub-agent return as an `Origin.SUBAGENT` turn through a real `AgentLoop` with the engine hook, reading `deck/build/build.py` -- "File not found" with `before_iteration` disabled, the file's contents with it.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (skill, tool descriptions, design doc D31)
## Risk
Author-visible behaviour only. `backdrop`'s default output changes (dark plane and light type instead of a wash); a script that wants the old wash passes `scrim=None` with a low `alpha`. `drop_shape` now raises on a layout shape. `ppt_outline` accepts pages without `page`. The new gate is WARNING-only and in no blocking set. Rollback: revert the three commits.
- [x] Security impact considered (no new input reaches anything)
- [x] Backward compatibility considered (recorded outlines unaffected; `replace_picture` and `layout_pictures` unchanged)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
A streaming reply whose connection the upstream closed before the terminal chunk came back as a finished, empty reply, and the agent loop's empty-reply recovery re-sent the identical request. This MR makes that end a transport failure instead.
- LiteLLM's stream wrapper fabricates a final chunk with `finish_reason="stop"` when the upstream closes the stream without one, and keeps the reason it actually received (`None`) on the wrapper. `LiteLLMProvider.chat_stream` now stamps such a delta `finish_synthesized` (new field on `ChatDelta`, default False; a wrapper without the attribute is trusted).
- `stream_llm_call` treats a made-up stop with no content and no tool call as a retryable network error: one WARNING line with the elapsed seconds and the reasoning characters lost, an `LLMResponse(finish_reason="error")` classified `network`/retryable for the loop's existing error ladder, and a reply sentence naming the cut when the ladder is spent. Content that did arrive is delivered as before; only its finish reason is left `unknown` rather than `stop`, since the upstream never said why it ended. A stop the upstream did send with no content is unchanged and still goes to the empty-reply recovery.
Why now: on 2026-09-06 the egress proxy was down and the deck agent's LLM path went straight to OpenRouter, where a streaming response is cut about 300 s after the request. Nine deck-build calls ended at 307 to 314 s with 11k to 15k reasoning tokens streamed and no content; the loop re-sent the same 380k-token request after each (two prefill retries, three plain retries), so one run spent 30 minutes on six identical five-minute calls and ended with no deck and no message saying why. A direct probe reproduced the cut at 303 s on a plain long completion (server closed the stream; no finish_reason, no usage); via the proxy, calls of 392 to 565 s completed on the same days. The cut itself is the network path's; this MR is about recognising it and not repeating it blindly.
No change to reasoning effort, context compaction or the empty-reply budgets.
The synthesized-finish check reads both of the wrapper's records, `received_finish_reason` and `intermittent_finish_reason`: gemini and vertex_ai chunks are stamped `_hidden_params["is_finished"] = False` on every chunk, so their terminal reason is only ever the intermittent one, and reading the received record alone called every healthy gemini reply a cut. Only a stream with neither record is a cut. The tests drive the provider through LiteLLM's own `CustomStreamWrapper` (openai and gemini, finished and cut) so the attribute names are bound to the library's API.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run --frozen --no-sync pytest tests/test_litellm_provider_stream_end.py tests/test_agent_loop_stream.py \
tests/test_transport_failure_paths.py tests/test_litellm_provider_timeout.py \
tests/test_provider_stream_fallback.py tests/test_rpc_reasoning_render.py -q
84 passed
uv run --frozen --no-sync pytest tests/test_provider*.py tests/test_litellm*.py tests/test_agent_loop*.py \
tests/test_transport*.py tests/test_rpc_reasoning_render.py tests/test_watch_work.py tests/test_trajectory_replay.py -q
1392 passed, 33 skipped in 33.90s
uv run --frozen --no-sync ruff check <changed files> -> All checks passed
uv run --frozen --no-sync ruff format --check <changed files> -> already formatted
```
New tests: the provider marks a stop the library made up and not one the upstream sent (and trusts a wrapper without the record); the streaming call turns a cut with reasoning only into a network error with the log line, delivers content that arrived before a made-up stop, and leaves an honest empty stop to the empty-reply recovery.
Evidence the rule targets the real shape: audit artifacts of the nine cut calls carry `finish_reason: stop`, `completion_tokens: 0`, `reasoning_tokens` 11k to 15k, and a usage dict without the cost and cache fields the upstream's terminal chunk normally brings.
## Risk
- A provider whose wrapper never records an upstream finish reason and whose replies carry no content would now be reported as a transport failure instead of an empty reply. LiteLLM's wrapper records it for every OpenAI-shaped stream; a wrapper without the attribute is trusted, so duck-typed providers are unaffected.
- Recorded trajectories: a reply that arrived with content but whose stream ended without a terminal chunk now records `finish_reason: unknown` instead of `stop`.
- After the loop's error ladder (three waits) a cut that persists ends the turn with an error message naming the cut, where before it ended with an empty reply after five more identical calls. Worst case is four calls, not six.
Rollback: revert the single commit; no config or schema change.
- [x] Security impact considered (no new input reaches the model)
- [x] Backward compatibility considered (new dataclass field has a default; no wire change)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Change description
> ``Ports the design-domain work onto the current main and closes the gaps found while running the WebUI end to end.
>
> - Per-model API protocol: `providers.<slug>.protocol` and `providers.<slug>.modelProtocols` pick OpenAI Chat, OpenAI Responses or Anthropic Messages per model; gpt models default to Responses and claude models to Anthropic Messages, everything else stays on the LiteLLM chat path. Two native transports implement the new protocols (OpenRouter routing, per-model overrides, tool-name normalisation, prompt-cache markers). The model picker shows and pins the protocol.
> - Anthropic streaming: signed thinking blocks travel on the terminal stream delta and are replayed on the next request; before this every claude turn with extended thinking ended in an error as soon as it reached a tool call.
> - Destructive-command preference: `tools.exec.allowDestructiveCommands` lifts the recursive-delete refusal, applies live, is exposed as a settings toggle behind a confirmation, and is inherited by every product launcher so ACP sub-agents follow the host.
> - ACP sub-agents: a pooled worker follows the parent session's model/provider/protocol instead of the binding captured at first launch; early `session/update` frames are buffered rather than dropped; the hard process exit that avoids a native teardown crash fires only after a real stdio session.
> - One-shot runs wait for spawned sub-agents before the process exits.
> - File viewer: `/file` roots relative paths at the session working directory (message links no longer 404); the sign-in nonce lives 30 minutes.
> - WebUI agent stage: the provisional redraw no longer stacks a copy of every in-flight tool call into the fold on each poll (53 real calls rendered as 271).
> - Review round one: URL image references on the `/images/edits` path go through `guarded_fetch` (a private or link-local target is refused, nothing fetched or uploaded); the ACP pool holds one connection per parent binding under an agent name, so two sessions on different models no longer tear each other's worker down; `run_subagent_dag` carries the invoking turn's provider and model to every node like `spawn` does; the contract tier moves to version 7 for the `ChatDelta` field; the WebUI keeps a reader's opened fold across a delegated run's polls.
> - Anthropic transport ceiling: a request without a configured `max_tokens` asked for 4096 with the thinking budget inside it, so file writes were cut on every attempt and high-effort turns came back as thinking alone. The ceiling is now 64000 (the smallest among current claude models), thinking takes at most half, only signed thinking blocks are replayed, Claude 4.7+ use adaptive thinking with `output_config.effort`, and a 400 naming a smaller ceiling or the other thinking mode repairs the body for one retry (the learned ceiling is kept per model).
> - Review round two: the Anthropic ceiling comes from the shared owner `send_max_tokens` (the claude fallback for a model the catalogue does not know lives in `rates.CLAUDE_MAX_OUTPUT_TOKENS`), only a 400 that names a ceiling teaches one, Claude 4.7+ requests carry no temperature, and the destructive-command toggle's threat model is stated beside the settings whitelist rule (a rail against the model's mistakes, not a boundary against the credential holder, who already has `shell.exec`).
> - `image_generate` drives gpt-image models through the Images API (OpenRouter `/images` with `input_references`, OpenAI-compatible `/images/generations` and `/images/edits`), with `aspect_ratio` and `quality`.
> - Rendering: scaled browser captures (`scale` 1-4, larger viewport ceilings, corrected PDF fallback size).
> - Design skills: procedures aligned with the shared foundation, anti-slop review centralised in `review-against-ai-patterns`, brand defaults relaxed, reference galleries refreshed.
>
> Verification:
> - `uv run --all-extras pytest -q` (the CI command): 19097 passed, 112 skipped, 6 failed; the 6 (`tests/test_security_network.py` NAT64 cases x4, `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`, `tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`) are environment-dependent on the development box, fail identically on a pristine `main`, and passed on the CI runner.
> - `uv run pytest -m integration tests/integration/test_design_agent_acp_smoke.py`: 1 passed (real launcher -> installed raven -> design-engine -> ACP, exit 0); real-Chromium rendering integration tests: 7 passed.
> - `make lint` sub-targets (lint-python, lint-ui, lint-tui, lint-bridge, vendored checks), `make check-large-files`, `make check-source-language`: pass. `npm test --prefix ui-web`: 1311 passed.
> - Live checks against real endpoints: gpt-image-2 generation and reference-image edit through OpenRouter and an OpenAI-compatible gateway; a two-turn claude-opus-5 call with extended thinking and a tool call, thinking blocks replayed on the second turn; the rendered design-worker config carries the host's `allowDestructiveCommands`; `/file` served a workspace file by relative path.
>
> Compatibility: without `protocol`/`modelProtocols` a provider behaves as before, except that gpt and claude model ids now infer Responses/Anthropic; set `modelProtocols` to `chat` to pin the old path. `allowDestructiveCommands` defaults to off and does not touch the sandbox or workspace fences. Rollback is a revert of the squash commit; no data migration is involved.
> ``
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others
## Related issues (if there is)
> Fix#1
## Checklists
### Development
- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass
### Security
- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines
### Code review
- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [x] Merge request linked to JIRA ticket when applicable
## Change description
> ``Ports the design-domain work onto the current main and closes the gaps found while running the WebUI end to end.
>
> - Per-model API protocol: `providers.<slug>.protocol` and `providers.<slug>.modelProtocols` pick OpenAI Chat, OpenAI Responses or Anthropic Messages per model; gpt models default to Responses and claude models to Anthropic Messages, everything else stays on the LiteLLM chat path. Two native transports implement the new protocols (OpenRouter routing, per-model overrides, tool-name normalisation, prompt-cache markers). The model picker shows and pins the protocol.
> - Anthropic streaming: signed thinking blocks travel on the terminal stream delta and are replayed on the next request; before this every claude turn with extended thinking ended in an error as soon as it reached a tool call.
> - Destructive-command preference: `tools.exec.allowDestructiveCommands` lifts the recursive-delete refusal, applies live, is exposed as a settings toggle behind a confirmation, and is inherited by every product launcher so ACP sub-agents follow the host.
> - ACP sub-agents: a pooled worker follows the parent session's model/provider/protocol instead of the binding captured at first launch; early `session/update` frames are buffered rather than dropped; the hard process exit that avoids a native teardown crash fires only after a real stdio session.
> - One-shot runs wait for spawned sub-agents before the process exits.
> - File viewer: `/file` roots relative paths at the session working directory (message links no longer 404); the sign-in nonce lives 30 minutes.
> - WebUI agent stage: the provisional redraw no longer stacks a copy of every in-flight tool call into the fold on each poll (53 real calls rendered as 271).
> - Review round one: URL image references on the `/images/edits` path go through `guarded_fetch` (a private or link-local target is refused, nothing fetched or uploaded); the ACP pool holds one connection per parent binding under an agent name, so two sessions on different models no longer tear each other's worker down; `run_subagent_dag` carries the invoking turn's provider and model to every node like `spawn` does; the contract tier moves to version 7 for the `ChatDelta` field; the WebUI keeps a reader's opened fold across a delegated run's polls.
> - Anthropic transport ceiling: a request without a configured `max_tokens` asked for 4096 with the thinking budget inside it, so file writes were cut on every attempt and high-effort turns came back as thinking alone. The ceiling is now 64000 (the smallest among current claude models), thinking takes at most half, only signed thinking blocks are replayed, Claude 4.7+ use adaptive thinking with `output_config.effort`, and a 400 naming a smaller ceiling or the other thinking mode repairs the body for one retry (the learned ceiling is kept per model).
> - Review round two: the Anthropic ceiling comes from the shared owner `send_max_tokens` (the claude fallback for a model the catalogue does not know lives in `rates.CLAUDE_MAX_OUTPUT_TOKENS`), only a 400 that names a ceiling teaches one, Claude 4.7+ requests carry no temperature, and the destructive-command toggle's threat model is stated beside the settings whitelist rule (a rail against the model's mistakes, not a boundary against the credential holder, who already has `shell.exec`).
> - `image_generate` drives gpt-image models through the Images API (OpenRouter `/images` with `input_references`, OpenAI-compatible `/images/generations` and `/images/edits`), with `aspect_ratio` and `quality`.
> - Rendering: scaled browser captures (`scale` 1-4, larger viewport ceilings, corrected PDF fallback size).
> - Design skills: procedures aligned with the shared foundation, anti-slop review centralised in `review-against-ai-patterns`, brand defaults relaxed, reference galleries refreshed.
>
> Verification:
> - `uv run --all-extras pytest -q` (the CI command): 19097 passed, 112 skipped, 6 failed; the 6 (`tests/test_security_network.py` NAT64 cases x4, `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`, `tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`) are environment-dependent on the development box, fail identically on a pristine `main`, and passed on the CI runner.
> - `uv run pytest -m integration tests/integration/test_design_agent_acp_smoke.py`: 1 passed (real launcher -> installed raven -> design-engine -> ACP, exit 0); real-Chromium rendering integration tests: 7 passed.
> - `make lint` sub-targets (lint-python, lint-ui, lint-tui, lint-bridge, vendored checks), `make check-large-files`, `make check-source-language`: pass. `npm test --prefix ui-web`: 1311 passed.
> - Live checks against real endpoints: gpt-image-2 generation and reference-image edit through OpenRouter and an OpenAI-compatible gateway; a two-turn claude-opus-5 call with extended thinking and a tool call, thinking blocks replayed on the second turn; the rendered design-worker config carries the host's `allowDestructiveCommands`; `/file` served a workspace file by relative path.
>
> Compatibility: without `protocol`/`modelProtocols` a provider behaves as before, except that gpt and claude model ids now infer Responses/Anthropic; set `modelProtocols` to `chat` to pin the old path. `allowDestructiveCommands` defaults to off and does not touch the sandbox or workspace fences. Rollback is a revert of the squash commit; no data migration is involved.
> ``
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others
## Related issues (if there is)
> Fix#1
## Checklists
### Development
- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass
### Security
- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines
### Code review
- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [x] Merge request linked to JIRA ticket when applicable
## Summary
The thirteen observations 0xKT left on the merged !474, plus two defects this branch's
own pre-submit sweep found. One commit per finding.
**One rule, one home.** "Which mode is the catalogue default" had drifted into two
implementations (`build_mode_catalogue` and `SessionModes.__init__`); the tier a session
is on was spelled out twice inside `raven/agent/loop`, once per caller. Both are written
once now. `SessionModes.profiles()` had no readers left and is gone. `session_tier` lives
on `WiringMixin` beside the `session_policy` / `set_session_policy` pair it derives from,
so both callers reach it on `self` and nothing imports anything new.
**A named `defaultMode` that matches nothing is refused at load.** The old answer was to
fall through to the catalogue's first entry, which for the built-in ladder is the cheapest
rung, so a one-character slip downgraded every session's sub-agents with nothing logged
and worse answers as the only symptom. Matching is case-insensitive because a config file
is hand-written and a shift key is not a decision. Naming nothing is still fine and still
degrades to the first declared entry, which is the documented contract for a deployment
bringing its own catalogue. This converges on what the raven-research fork already does
(`subagents/raven-research/Raven-X/raven/config/schema.py:794`), minus the case fold.
**The declined-tier log names the side that actually declined.** `clamp_tier` answers
`None` for two different reasons and the line said "sub-agent X offers no tier from
medium/high/max" either way, so an agent offering the complete ladder was blamed when the
session's own vocabulary was the unrankable one.
**Two defects from the sweep itself, both in code written to close the above.** The case
fold answered from a dict, so a catalogue declaring both `High` and `high` resolved `HIGH`
by declaration order -- the same logical config, two answers, nothing logged. Its first
remedy then refused an exact spelling that was never ambiguous, while its own error message
asked the operator to name one exactly. Shipped order is exact, then unique fold, then
refuse; the regression reddens under a mutant in each direction.
**Prose that had stopped matching the code.** The design spec forbade a `default_mode`
validator outright; the rule it was protecting is narrower (a config naming NO default may
not be failed at startup) and now says so, with the refusal carrying its own Risks entry.
`clamp_tier` grew two rules whose pseudocode still showed four and read an unbound name.
The generated-artefacts table listed one RPC client where there are two, with two
generators and two `make` targets -- the omission that produced zwwu0215's blocker on
!474. Two present-tense fleet facts had gone stale: `raven-research` is named as sharing
no word with this ladder when it moved onto `medium` / `high` / `max` in `92cb4e11a`
before the document landed, and the partial menu that motivated the climb guard belonged
to MR !472, since closed unmerged.
`docs/plans/2026-09-03-subagent-mode-tiers.md` carries the same superseded prohibition and
is deliberately untouched: CONTEXT.md makes `docs/plans/` an archive of the tree as it
stood, with an explicit instruction to fix the living document instead.
Both RPC clients were regenerated. The `mode` parameter was withdrawn from the spawn tool
in !474, so `resolve_mode` lost its `requested` argument; a test fake still carried it
while calling itself "the real signature".
**Round two, from 0xKT's five observations on `d73b7a3f`.** `clamp_tier` refused for three
reasons and returned a bare `None`, so the caller re-tested one condition and rendered a
two-way branch over a three-way answer: a menu of `low`/`max` was told it "offers no tier"
while plainly offering `max`. `resolve_tier` now answers which decline applies and the
reason carries its sentence, so the caller decides nothing -- which also removes the second
in-path membership test of a rule `mode_tiers` already owned, the pair this branch's own
`mode_catalogue` comment warns about. The spec credited `92cb4e11a` with moving
raven-research onto the shared ladder; that commit introduced `fast`/`deep`/`ultra`, and
the move is `e97551a81`. The "before this document landed" clause went with it: the doc
landed in `3a2c77a41` at 04:09:10 and `e97551a81` is at 04:12:09, neither an ancestor of
the other. A `!472` docstring kept the present tense the spec had dropped, and a dead
binding was left behind when an assertion changed source.
**Round two also invalidated one of its own claims.** The rebase brought in `669c913a4`,
which gives `raven-code` a `low`/`high`/`max` catalogue -- so "no agent in the fleet
advertises a partial menu today", written an hour earlier and true then, is false at this
base. The climb guard and the decline line it prints are both reachable in production now.
Both are corrected, and the regression takes the shipped menu as a case.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run at head `fee5e5d5`, after two rebases. The first brought the branch onto `1685fc82`
(main had gained 8 commits over 170 files, 7 shared with this branch including all three
RPC artifacts); the second onto `ed74b8b1` (8 more commits, zero shared files).
Rebase purity, since a shared-file rebase can replay cleanly and still land on content
someone else was editing:
- `git range-diff` reports every commit as `=` across both rebases (10/10, then 14/14)
- aggregate stable patch-id over the branch was byte-identical across the first
(`c7c11bb56ce9333d9d6e97b33ddfcf4f`)
- per overlapping file, the intersection of upstream's added lines with this branch's
removed lines was empty for all four Python files in the first rebase; the second had
no overlapping files at all
Then, at `fee5e5d5`:
- `COLUMNS=200 uv run --all-extras --frozen pytest -q` -> `19130 passed, 138 skipped`,
0 failed. `COLUMNS` is set because `test_doctor_answers_where_the_memories_are` is
width-sensitive under xdist and is a known pre-existing flake at narrow widths.
- `uv run --frozen --all-extras lint-imports` -> `Contracts: 8 kept, 0 broken`. This gate
is GitHub-only; the GitLab pipeline is the Python unit suite and does not run it, which
is how two contracts broke under a green pipeline on !474.
- `uv run --frozen --all-extras ruff format --check raven/ tests/` -> 1457 files already
formatted; `ruff check` -> All checks passed
- `make lint-ui` -> generated client matches the contract + `tsc --noEmit` clean
- `make lint-tui` -> generated client in sync, i18n catalogue up to date, `tsc --noEmit` clean
- `uv run --frozen --all-extras python scripts/check_commit_messages.py origin/main..HEAD`
-> pass; `commitlint` per commit -> all 15 pass. These two disagree: `docs(specs)` is
accepted by the repo's own script and rejected by commitlint's scope enum, so three
commits were reworded to `docs(subagent)` before the first push.
- `uv run --frozen --all-extras python scripts/check_large_files.py origin/main..HEAD` -> pass
Each new test was proved load-bearing by reverting the behaviour it covers and observing it
go red, then restoring. The ambiguous-fold regression was run against a mutant in each
direction; the three-way decline regression goes red when the caller is put back to two
branches.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two behaviour changes, both at config load.
A named `acp.defaultMode` that matches no mode in the catalogue now fails the load instead
of silently selecting the catalogue's first entry. The blast radius is a config file that
was already wrong. It lands in the path an invalid config already takes: `load_config`
raises a `ValueError` quoting the message, `raven status` prints it verbatim
(`defaultMode 'higgh' is not a mode in this catalogue; it offers medium, high, max`),
`raven doctor` reports the schema as invalid, and `raven --help` still works, so the
operator keeps a route to diagnose and repair. Verified end to end against a scratch
`RAVEN_HOME`. Disclosed gap, pre-existing and not introduced here: `raven doctor`'s summary
line does not quote the validator's message for any schema error, so an operator who runs
only `doctor` is told to recreate the config rather than fix one word.
A config combining `"modes": {}` with a named `defaultMode` is also refused now, where it
previously degraded silently. That combination has no meaning, and the message says the
catalogue is empty. No shipped config does this.
Everything else is inert: the log split changes only what is printed, and the prose changes
touch no runtime path.
Rollback is per commit -- each finding is one commit and each reverts independently.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A. Follows up the merged !474 (`b09a9d6a`).
## Summary
The thirteen observations 0xKT left on the merged !474, plus two defects this branch's
own pre-submit sweep found. One commit per finding.
**One rule, one home.** "Which mode is the catalogue default" had drifted into two
implementations (`build_mode_catalogue` and `SessionModes.__init__`); the tier a session
is on was spelled out twice inside `raven/agent/loop`, once per caller. Both are written
once now. `SessionModes.profiles()` had no readers left and is gone. `session_tier` lives
on `WiringMixin` beside the `session_policy` / `set_session_policy` pair it derives from,
so both callers reach it on `self` and nothing imports anything new.
**A named `defaultMode` that matches nothing is refused at load.** The old answer was to
fall through to the catalogue's first entry, which for the built-in ladder is the cheapest
rung, so a one-character slip downgraded every session's sub-agents with nothing logged
and worse answers as the only symptom. Matching is case-insensitive because a config file
is hand-written and a shift key is not a decision. Naming nothing is still fine and still
degrades to the first declared entry, which is the documented contract for a deployment
bringing its own catalogue. This converges on what the raven-research fork already does
(`subagents/raven-research/Raven-X/raven/config/schema.py:794`), minus the case fold.
**The declined-tier log names the side that actually declined.** `clamp_tier` answers
`None` for two different reasons and the line said "sub-agent X offers no tier from
medium/high/max" either way, so an agent offering the complete ladder was blamed when the
session's own vocabulary was the unrankable one.
**Two defects from the sweep itself, both in code written to close the above.** The case
fold answered from a dict, so a catalogue declaring both `High` and `high` resolved `HIGH`
by declaration order -- the same logical config, two answers, nothing logged. Its first
remedy then refused an exact spelling that was never ambiguous, while its own error message
asked the operator to name one exactly. Shipped order is exact, then unique fold, then
refuse; the regression reddens under a mutant in each direction.
**Prose that had stopped matching the code.** The design spec forbade a `default_mode`
validator outright; the rule it was protecting is narrower (a config naming NO default may
not be failed at startup) and now says so, with the refusal carrying its own Risks entry.
`clamp_tier` grew two rules whose pseudocode still showed four and read an unbound name.
The generated-artefacts table listed one RPC client where there are two, with two
generators and two `make` targets -- the omission that produced zwwu0215's blocker on
!474. Two present-tense fleet facts had gone stale: `raven-research` is named as sharing
no word with this ladder when it moved onto `medium` / `high` / `max` in `92cb4e11a`
before the document landed, and the partial menu that motivated the climb guard belonged
to MR !472, since closed unmerged.
`docs/plans/2026-09-03-subagent-mode-tiers.md` carries the same superseded prohibition and
is deliberately untouched: CONTEXT.md makes `docs/plans/` an archive of the tree as it
stood, with an explicit instruction to fix the living document instead.
Both RPC clients were regenerated. The `mode` parameter was withdrawn from the spawn tool
in !474, so `resolve_mode` lost its `requested` argument; a test fake still carried it
while calling itself "the real signature".
**Round two, from 0xKT's five observations on `d73b7a3f`.** `clamp_tier` refused for three
reasons and returned a bare `None`, so the caller re-tested one condition and rendered a
two-way branch over a three-way answer: a menu of `low`/`max` was told it "offers no tier"
while plainly offering `max`. `resolve_tier` now answers which decline applies and the
reason carries its sentence, so the caller decides nothing -- which also removes the second
in-path membership test of a rule `mode_tiers` already owned, the pair this branch's own
`mode_catalogue` comment warns about. The spec credited `92cb4e11a` with moving
raven-research onto the shared ladder; that commit introduced `fast`/`deep`/`ultra`, and
the move is `e97551a81`. The "before this document landed" clause went with it: the doc
landed in `3a2c77a41` at 04:09:10 and `e97551a81` is at 04:12:09, neither an ancestor of
the other. A `!472` docstring kept the present tense the spec had dropped, and a dead
binding was left behind when an assertion changed source.
**Round two also invalidated one of its own claims.** The rebase brought in `669c913a4`,
which gives `raven-code` a `low`/`high`/`max` catalogue -- so "no agent in the fleet
advertises a partial menu today", written an hour earlier and true then, is false at this
base. The climb guard and the decline line it prints are both reachable in production now.
Both are corrected, and the regression takes the shipped menu as a case.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run at head `fee5e5d5`, after two rebases. The first brought the branch onto `1685fc82`
(main had gained 8 commits over 170 files, 7 shared with this branch including all three
RPC artifacts); the second onto `ed74b8b1` (8 more commits, zero shared files).
Rebase purity, since a shared-file rebase can replay cleanly and still land on content
someone else was editing:
- `git range-diff` reports every commit as `=` across both rebases (10/10, then 14/14)
- aggregate stable patch-id over the branch was byte-identical across the first
(`c7c11bb56ce9333d9d6e97b33ddfcf4f`)
- per overlapping file, the intersection of upstream's added lines with this branch's
removed lines was empty for all four Python files in the first rebase; the second had
no overlapping files at all
Then, at `fee5e5d5`:
- `COLUMNS=200 uv run --all-extras --frozen pytest -q` -> `19130 passed, 138 skipped`,
0 failed. `COLUMNS` is set because `test_doctor_answers_where_the_memories_are` is
width-sensitive under xdist and is a known pre-existing flake at narrow widths.
- `uv run --frozen --all-extras lint-imports` -> `Contracts: 8 kept, 0 broken`. This gate
is GitHub-only; the GitLab pipeline is the Python unit suite and does not run it, which
is how two contracts broke under a green pipeline on !474.
- `uv run --frozen --all-extras ruff format --check raven/ tests/` -> 1457 files already
formatted; `ruff check` -> All checks passed
- `make lint-ui` -> generated client matches the contract + `tsc --noEmit` clean
- `make lint-tui` -> generated client in sync, i18n catalogue up to date, `tsc --noEmit` clean
- `uv run --frozen --all-extras python scripts/check_commit_messages.py origin/main..HEAD`
-> pass; `commitlint` per commit -> all 15 pass. These two disagree: `docs(specs)` is
accepted by the repo's own script and rejected by commitlint's scope enum, so three
commits were reworded to `docs(subagent)` before the first push.
- `uv run --frozen --all-extras python scripts/check_large_files.py origin/main..HEAD` -> pass
Each new test was proved load-bearing by reverting the behaviour it covers and observing it
go red, then restoring. The ambiguous-fold regression was run against a mutant in each
direction; the three-way decline regression goes red when the caller is put back to two
branches.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two behaviour changes, both at config load.
A named `acp.defaultMode` that matches no mode in the catalogue now fails the load instead
of silently selecting the catalogue's first entry. The blast radius is a config file that
was already wrong. It lands in the path an invalid config already takes: `load_config`
raises a `ValueError` quoting the message, `raven status` prints it verbatim
(`defaultMode 'higgh' is not a mode in this catalogue; it offers medium, high, max`),
`raven doctor` reports the schema as invalid, and `raven --help` still works, so the
operator keeps a route to diagnose and repair. Verified end to end against a scratch
`RAVEN_HOME`. Disclosed gap, pre-existing and not introduced here: `raven doctor`'s summary
line does not quote the validator's message for any schema error, so an operator who runs
only `doctor` is told to recreate the config rather than fix one word.
A config combining `"modes": {}` with a named `defaultMode` is also refused now, where it
previously degraded silently. That combination has no meaning, and the message says the
catalogue is empty. No shipped config does this.
Everything else is inert: the log split changes only what is printed, and the prose changes
touch no runtime path.
Rollback is per commit -- each finding is one commit and each reverts independently.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A. Follows up the merged !474 (`b09a9d6a`).
## Summary
Follow-ups to the replan decision, each finding reproduced before it was changed. Three
change what the model reads at a refusal, one removes a duplicated record shape, three
correct claims that had drifted from the code, and one is formatting.
**A reference to a node in one of two live states got a message it could not act on.** The
replan overlay reads the run being replaced as it stands rather than as it finalized, so a
node can be `pending` or `exception` when a replacement graph names it -- states a finalized
manifest never records. Neither had a branch in the reference refusal, so both fell through
to `depends on unknown '<id>'`. That id is not unknown, it is claimed, and a model following
that advice to re-declare it walks straight into the uniqueness refusal saying so: two
messages, neither actionable.
Both now say what happened, and both point at a new id rather than at waiting. That is the
part worth stating rather than assuming: a still-running node takes "re-submit once that run
reports", but these two belong to a run a landing replan discards, so its remaining nodes
never produce anything to wait for. The glossary entry that enumerated four such states now
names all of them.
**The `pending` message then described a replacement that had not happened.** It said the
node "had not started when it was replaced" -- but every branch of that function is raised as
a validation error, `prepare_replan` returns it as a refusal, and the control tool returns
that before `resolve_node` is ever called. So the decision is never signalled and the old run
is still going as submitted. This is not a matter of the phrasing being early: those two
states reach the function only through the replan overlay, and the function only ever
refuses, so there is no path on which the sentence renders after a replacement. It now states
the node's state in the present and the loss as what replanning would do, which keeps the
advice and its reason -- a replan that does land marks a pending node `skipped`. The
`exception` message claims no replacement and is unchanged. The comment above both branches,
the test that pinned the wording, and the glossary entry carried the same presumption and are
corrected with it.
**The guide the refusal sends the model to prescribed the opposite fix.** That refusal
appends `read_skill("local/subagent-dag-orchestration")` -- `_validation_error`'s docstring
says why: a validation failure is the one moment the graph shape is known to be wrong. The
guide injects by `description`, so its body reaches the model through that call and nowhere
else, which means the sentence the refusal gives and the rule the guide gives are read one
after the other.
They disagreed. The guide reserved "re-do it under a new id" for work that failed, was
cancelled or was skipped, and prescribed the opposite for a node of a run still in flight:
submit again once it reports. Right for a fresh graph, wrong inside a replan, which discards
the replaced run's unfinished nodes -- and `pending` and `exception` are exactly those. At
base the two agreed, because no in-flight node had ever been given the re-do advice; the two
branches added here are what created the disagreement. The guide's own replan section already
said every node of the replaced run but the completed ones needs a new id, so only this one
passage contradicted it. It now carries that inversion, and names the no-outcome-recorded case
it never listed. Its two "of the four" counts are gone rather than corrected to seven, the set
having grown twice already. A test pins the agreement, because nothing did: `test_living_docs`
checks that a cited path exists, not that claims about it hold.
**Two artefacts asserted a closed set with a member outside it.** The state test was named
for the states the replan overlay can carry, and `interrupted` is one of them -- a run left
unfinalized and held by no tool has its nodes reconciled to that value by `dag_resume`, and it
falls to the caller's unknown-id fallback. The name is now about the states the function
answers, which is a set of seven and true, and the comment at the branches says outright that
it is not an enumeration of the overlay. `interrupted` is deliberately left unasserted: it
predates these branches, it is only presentable when the run is not live -- the same condition
that leaves `resolve_dag_node` without a desk, so the replan fails either way -- and pinning
today's return would turn a later branch for it into a test change rather than an addition.
**`await_finalized` had no test that observed it waiting.** Replacing its body with `return`
left the whole DAG suite green, the two tests named after it included -- they drive a stub
that records the call, so they pin where it sits in the sequence and nothing about what it
does there. Its docstring's whole claim is that the successor's validation needs the
predecessor's per-node outcomes on disk, which is exactly what returning early takes away. It
now has a test that drives the real method against a real pending task and asserts the order
of two events. The wait is sampled after a real interval rather than one loop turn, because a
bare `sleep(0)` reads the same whether the call parked or returned.
**Three records corrected.** The replan link's shape was written out twice, once for the
ordinary hand-off and once for the interrupted one, so a field added later for whoever reads
these records would have reached half of them; one builder owns it now, with the ordinary
path still stamping `decided_at` before the submission rather than after. `record_replan`
said all four readers of `graph.json` take their keys out of a raw dict and the reserved key
is inert to every one of them -- there are five, and the fifth is the exception that matters:
`prepare_replan` parses through a model that rejects the key outright, which is why it strips
it first. And the graph cache's own note claimed its stamp check is load-bearing because a
replan's note would otherwise never be seen there; true of the mechanism, irrelevant to that
reader, which returns two title fields both written at init.
**One formatting fix.** `ui-tui/src/domain/dagRun.ts` is one of the files `prettier --check`
reports. That hook is already red across the tree and runs with `pass_filenames: false`, so
it was not made red here -- but this is a file the replan work touched, and leaving it makes
the hook one file harder to bring back to green. Formatting only; the tree's count goes from
30 to 29.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `make test-python` -- 19070 passed, 1 failed, 115 skipped. The one failure is
`test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`, which this branch
does not touch and does not cause; see Risk.
- `make lint-python` -- clean.
- `make check-commits` -- clean, both the commitlint pass and `scripts/check_commit_messages.py`.
- `make check-source-language` -- clean.
- `make check-large-files` -- clean.
- `npm run type-check --prefix ui-tui` -- clean.
- `npm run lint:rpc --prefix ui-tui` -- in sync.
- `npm run lint:i18n --prefix ui-tui` -- generated catalogue up to date.
- `npm test --prefix ui-tui -- dagRun.test` -- 24 passed.
- The five DAG suites plus every suite that reads the guide skill
(`test_living_docs`, `test_agent_loop_injected_skill_ids`, `test_curator_context_engine`,
`test_skill_forge_loader_parity`) -- 579 passed; `test_segments` and
`test_subagent_manager`, the other two readers -- 152 passed.
- `npx prettier --check "ui-tui/src/**/*.{ts,tsx}"` -- 29 files reported, down from 30. The
branch touches exactly one file under `ui-tui/`, and that file is red at `origin/main`
(checked through `--stdin-filepath`, so it resolves the same config) and clean at this head.
Every behaviour or product-text change was reproduced first and then sabotage-verified:
- Driving `_unreadable` across all seven states showed `pending` and `exception` returning
`None` where the other five return a specific message. With the two branches deleted again,
the new test fails with `state 'pending' fell through to the unknown-id fallback`.
- Replacing the body of `await_finalized` with `return` left 438 tests green beforehand.
Against the same mutation, the new test now fails with `returned while the run it was told
to wait for was still going`.
- The tense claim was reproduced by driving the real `prepare_replan` with each live state in
the overlay and printing what the model receives, then driving the control tool with a
refusing `prepare_replan`: `['prepare_replan']` ran and nothing else, against
`['prepare_replan', 'resolve_node', 'emit_replanned', 'await_finalized', 'start_replan']`
for an accepted plan. Restoring the old wording turns the new assertion red.
- The guide disagreement was read off the two texts, then the new agreement test was run
against the guide restored to its pre-fix content: it fails on the premise assertion
(`the fresh-graph rule is the premise`), so it is pinning the guide's wording and not
only the refusal's.
The state test asserts all seven states, the five settled ones included, so a regression that
collapses that function into one message cannot pass by answering only the two added here.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Two refusal messages change, and only in cases that previously produced a wrong one.** A
reference to a `pending` or `exception` node was refused either way; what changes is which
sentence the model reads. The five settled states are untouched and asserted. Nothing else in
this branch changes behaviour: one builder replaces two identical literals, and the rest is
prose and formatting. Rolling back is reverting the branch.
**The one failing test is not this branch's.** Its inputs are byte-identical to the base
(`git diff --stat origin/main...HEAD -- raven/cli/ raven/config/ tests/test_cli_doctor_commands.py`
is empty), and the failure is console width plus path length rather than code: under xdist at
the default width it fails, serially at the default width it passes, and under xdist with
`COLUMNS=200` it passes. xdist inserts a worker directory into the temp path and narrows the
captured console, and between them the path wraps across the substring the assertion looks
for.
**No changelog entry.** The replan feature itself carries none, and the entry describing
which node states are refused already reads "in a run still in flight", which covers both
states added here.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Follow-ups to the replan decision, each finding reproduced before it was changed. Three
change what the model reads at a refusal, one removes a duplicated record shape, three
correct claims that had drifted from the code, and one is formatting.
**A reference to a node in one of two live states got a message it could not act on.** The
replan overlay reads the run being replaced as it stands rather than as it finalized, so a
node can be `pending` or `exception` when a replacement graph names it -- states a finalized
manifest never records. Neither had a branch in the reference refusal, so both fell through
to `depends on unknown '<id>'`. That id is not unknown, it is claimed, and a model following
that advice to re-declare it walks straight into the uniqueness refusal saying so: two
messages, neither actionable.
Both now say what happened, and both point at a new id rather than at waiting. That is the
part worth stating rather than assuming: a still-running node takes "re-submit once that run
reports", but these two belong to a run a landing replan discards, so its remaining nodes
never produce anything to wait for. The glossary entry that enumerated four such states now
names all of them.
**The `pending` message then described a replacement that had not happened.** It said the
node "had not started when it was replaced" -- but every branch of that function is raised as
a validation error, `prepare_replan` returns it as a refusal, and the control tool returns
that before `resolve_node` is ever called. So the decision is never signalled and the old run
is still going as submitted. This is not a matter of the phrasing being early: those two
states reach the function only through the replan overlay, and the function only ever
refuses, so there is no path on which the sentence renders after a replacement. It now states
the node's state in the present and the loss as what replanning would do, which keeps the
advice and its reason -- a replan that does land marks a pending node `skipped`. The
`exception` message claims no replacement and is unchanged. The comment above both branches,
the test that pinned the wording, and the glossary entry carried the same presumption and are
corrected with it.
**The guide the refusal sends the model to prescribed the opposite fix.** That refusal
appends `read_skill("local/subagent-dag-orchestration")` -- `_validation_error`'s docstring
says why: a validation failure is the one moment the graph shape is known to be wrong. The
guide injects by `description`, so its body reaches the model through that call and nowhere
else, which means the sentence the refusal gives and the rule the guide gives are read one
after the other.
They disagreed. The guide reserved "re-do it under a new id" for work that failed, was
cancelled or was skipped, and prescribed the opposite for a node of a run still in flight:
submit again once it reports. Right for a fresh graph, wrong inside a replan, which discards
the replaced run's unfinished nodes -- and `pending` and `exception` are exactly those. At
base the two agreed, because no in-flight node had ever been given the re-do advice; the two
branches added here are what created the disagreement. The guide's own replan section already
said every node of the replaced run but the completed ones needs a new id, so only this one
passage contradicted it. It now carries that inversion, and names the no-outcome-recorded case
it never listed. Its two "of the four" counts are gone rather than corrected to seven, the set
having grown twice already. A test pins the agreement, because nothing did: `test_living_docs`
checks that a cited path exists, not that claims about it hold.
**Two artefacts asserted a closed set with a member outside it.** The state test was named
for the states the replan overlay can carry, and `interrupted` is one of them -- a run left
unfinalized and held by no tool has its nodes reconciled to that value by `dag_resume`, and it
falls to the caller's unknown-id fallback. The name is now about the states the function
answers, which is a set of seven and true, and the comment at the branches says outright that
it is not an enumeration of the overlay. `interrupted` is deliberately left unasserted: it
predates these branches, it is only presentable when the run is not live -- the same condition
that leaves `resolve_dag_node` without a desk, so the replan fails either way -- and pinning
today's return would turn a later branch for it into a test change rather than an addition.
**`await_finalized` had no test that observed it waiting.** Replacing its body with `return`
left the whole DAG suite green, the two tests named after it included -- they drive a stub
that records the call, so they pin where it sits in the sequence and nothing about what it
does there. Its docstring's whole claim is that the successor's validation needs the
predecessor's per-node outcomes on disk, which is exactly what returning early takes away. It
now has a test that drives the real method against a real pending task and asserts the order
of two events. The wait is sampled after a real interval rather than one loop turn, because a
bare `sleep(0)` reads the same whether the call parked or returned.
**Three records corrected.** The replan link's shape was written out twice, once for the
ordinary hand-off and once for the interrupted one, so a field added later for whoever reads
these records would have reached half of them; one builder owns it now, with the ordinary
path still stamping `decided_at` before the submission rather than after. `record_replan`
said all four readers of `graph.json` take their keys out of a raw dict and the reserved key
is inert to every one of them -- there are five, and the fifth is the exception that matters:
`prepare_replan` parses through a model that rejects the key outright, which is why it strips
it first. And the graph cache's own note claimed its stamp check is load-bearing because a
replan's note would otherwise never be seen there; true of the mechanism, irrelevant to that
reader, which returns two title fields both written at init.
**One formatting fix.** `ui-tui/src/domain/dagRun.ts` is one of the files `prettier --check`
reports. That hook is already red across the tree and runs with `pass_filenames: false`, so
it was not made red here -- but this is a file the replan work touched, and leaving it makes
the hook one file harder to bring back to green. Formatting only; the tree's count goes from
30 to 29.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `make test-python` -- 19070 passed, 1 failed, 115 skipped. The one failure is
`test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`, which this branch
does not touch and does not cause; see Risk.
- `make lint-python` -- clean.
- `make check-commits` -- clean, both the commitlint pass and `scripts/check_commit_messages.py`.
- `make check-source-language` -- clean.
- `make check-large-files` -- clean.
- `npm run type-check --prefix ui-tui` -- clean.
- `npm run lint:rpc --prefix ui-tui` -- in sync.
- `npm run lint:i18n --prefix ui-tui` -- generated catalogue up to date.
- `npm test --prefix ui-tui -- dagRun.test` -- 24 passed.
- The five DAG suites plus every suite that reads the guide skill
(`test_living_docs`, `test_agent_loop_injected_skill_ids`, `test_curator_context_engine`,
`test_skill_forge_loader_parity`) -- 579 passed; `test_segments` and
`test_subagent_manager`, the other two readers -- 152 passed.
- `npx prettier --check "ui-tui/src/**/*.{ts,tsx}"` -- 29 files reported, down from 30. The
branch touches exactly one file under `ui-tui/`, and that file is red at `origin/main`
(checked through `--stdin-filepath`, so it resolves the same config) and clean at this head.
Every behaviour or product-text change was reproduced first and then sabotage-verified:
- Driving `_unreadable` across all seven states showed `pending` and `exception` returning
`None` where the other five return a specific message. With the two branches deleted again,
the new test fails with `state 'pending' fell through to the unknown-id fallback`.
- Replacing the body of `await_finalized` with `return` left 438 tests green beforehand.
Against the same mutation, the new test now fails with `returned while the run it was told
to wait for was still going`.
- The tense claim was reproduced by driving the real `prepare_replan` with each live state in
the overlay and printing what the model receives, then driving the control tool with a
refusing `prepare_replan`: `['prepare_replan']` ran and nothing else, against
`['prepare_replan', 'resolve_node', 'emit_replanned', 'await_finalized', 'start_replan']`
for an accepted plan. Restoring the old wording turns the new assertion red.
- The guide disagreement was read off the two texts, then the new agreement test was run
against the guide restored to its pre-fix content: it fails on the premise assertion
(`the fresh-graph rule is the premise`), so it is pinning the guide's wording and not
only the refusal's.
The state test asserts all seven states, the five settled ones included, so a regression that
collapses that function into one message cannot pass by answering only the two added here.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Two refusal messages change, and only in cases that previously produced a wrong one.** A
reference to a `pending` or `exception` node was refused either way; what changes is which
sentence the model reads. The five settled states are untouched and asserted. Nothing else in
this branch changes behaviour: one builder replaces two identical literals, and the rest is
prose and formatting. Rolling back is reverting the branch.
**The one failing test is not this branch's.** Its inputs are byte-identical to the base
(`git diff --stat origin/main...HEAD -- raven/cli/ raven/config/ tests/test_cli_doctor_commands.py`
is empty), and the failure is console width plus path length rather than code: under xdist at
the default width it fails, serially at the default width it passes, and under xdist with
`COLUMNS=200` it passes. xdist inserts a worker directory into the temp path and narrows the
captured console, and between them the path wraps across the substring the assertion looks
for.
**No changelog entry.** The replan feature itself carries none, and the entry describing
which node states are refused already reads "in a run still in flight", which covers both
states added here.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
!474 gives a session an effort tier for the sub-agents raven dispatches, and wires `ui-tui` to it. The web front end had no way to see or change it. This adds one.
**A chip beside the model chip, not a group inside the model picker.** A tier is not a model: the picker is where a reader goes to change what answers them, and the two would be read as one list of choices. The panel says in a footer what no row can -- that a tier moves what raven asks of the sub-agents it *dispatches*, and leaves raven's own effort alone -- because every comparable control in other products means the opposite.
Built like `shell/perm.ts` next door and for its reasons: both nodes are static in `page.html`, the panel is reparented to the body to be positioned at all, and the state is one string. The two chips read as one row of session settings.
**The menu is the server's.** Every `session.set_mode` reply carries the whole catalogue, so one round trip draws the control. A deployment that replaces the catalogue is followed rather than second-guessed -- rows are named by what it declares, and only the built-in ids get a ranked icon, since a replacement's rungs cannot be ranked. `"modes": {}` turns the surface off, and an empty menu hides the chip rather than drawing a control over nothing.
**A click paints from the reply.** The handler clamps and refuses; painting the click first would leave the chip naming a tier the next turn will not run at.
**A draft is the exception, and it belongs to the seam rather than the chip.** A conversation being written has no `session_key`, and writing under the empty one lands on a policy the first turn never reads. So the pick is staged and applied on `session.create`, next to the model staged the same way -- a first turn dispatches sub-agents like any other.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Based on !474, and kept small on purpose
Target was !474's branch while `session.set_mode` existed only there. !474 has
since merged, so this now targets `main` and carries only the web layer. It
follows the server rather than duplicating it -- no tier list, no default, no
ladder order is written on this side.
Per the ask to keep MRs small and focused, the per-instance override (`subagents.instance.set_mode`, with `auto` meaning no override) is **not** here. It is a second MR stacked on this one.
**The regenerated client is gone from this branch, as intended.** !474 regenerated `ui-tui`'s client and not `ui-web`'s, so `npm run gen:check --prefix ui-web` -- the first line of `make lint-ui` -- failed on its head. I raised it there and carried a pure `npm run gen` here only to compile against. It landed on !474 as `102bbc24`, and rebasing dropped mine: `git` recognised it as already applied, and the file here is byte-identical to the one !474 now carries. This MR is four commits of its own work.
## After review
Three P1s, each reproduced on the running page before I touched anything, one
commit each. Two mistakes of my own during that verification are worth recording,
because both nearly produced a wrong answer: I first wrote the replacement
catalogue into `/root/.raven/config.json` while the gateway runs on
`RAVEN_HOME=/root/.raven-preview`, which made P1-1 look like it did not
reproduce; and my first probe for P1-3 wrapped `window.loadTier`, which is not
what `main.tsx` calls -- the control read 0 as well, which is the only reason I
noticed.
**A deployment's own modes were called sub-agent tiers -- `1f348d98`.** Not loose
wording; the opposite of the truth. With `quick`/`thorough` declared, on the page:
```
before after
aria "Sub-agent effort: Quick" aria "Session mode: Quick"
footer "...Raven's own effort is the footer "A profile this deployment
same in every tier." declares... not offered to sub-agents."
```
while `clamp_tier('quick', ('medium','high','max'))` is `None` -- no sub-agent is
touched -- and `quick`'s `max_tool_iterations: 4` moves raven's own cap. The
heading and footer now follow the test the clamp applies: every rung on offer is
one the ladder ranks, or it is a mode catalogue and says so. Every rather than
any, since a mixed catalogue is read case by case and a heading cannot be half
true.
Neither wording claims raven's effort is unchanged any more, though the shipped
catalogue does leave it alone. The reply carries an id, a name and a description
and never the knobs, so a catalogue that names its rungs after the ladder AND
sets a cap is indistinguishable here from the shipped one. The control says the
part it can stand behind.
**And a second round on the same finding -- `021aec54`.** The first fix answered
the naming question at the catalogue's scope and then let the footer inherit that
answer, which is a different claim. `clamp_tier` honours an exact hit in any
vocabulary that spells the rung the same way, so one catalogue answers twice:
```
clamp_tier('high', ('medium','high','max')) -> 'high'
clamp_tier('thorough', ('medium','high','max')) -> None
```
The footer is keyed to the rung in force now; the heading stays keyed to the
catalogue. On the page with `{high, thorough}`:
```
in force heading footer
High Session mode ...is offered to the sub-agents this conversation dispatches
Thorough Session mode ...is not one of the built-in tiers, so it is not offered
```
**A tier staged for an abandoned draft leaked -- `f53444a1`.** Reproduced exactly
as reported:
```
before after
draft one, stage Max Max Max
open another conversation, no send High High
start draft two High High
send draft two -> server tier MAX high
```
**A reconnect left the chip stale -- `f53444a1`.** Measured by counting the reads
in the page, with a control:
```
before after
reopen the SAME id (reconnect does) 0 1
switch to another conversation 1 2 <- control
```
`setCurrent` returns early for an unchanged id, so `onChange` never fired; and
`_session_policies` is a plain in-memory dict with no persistence, so a gateway
restart puts every session back on the catalogue default underneath.
Both go away by doing what the model does -- reset and re-read together in
`startDraft` and `openLiveSession` -- so the `onChange` lane goes rather than
gaining a third caller, and `pendingTier` moves beside `pendingModel` in the file
that resets both. The two assembled-page harnesses gain the step and three cases.
Mutation-checked, nine more ways on top of the original five: always ranking a
catalogue as a tier, `every` weakened to `some`, not writing the heading, a chip
aria that does not distinguish, and each of the two new reset/re-read sites.
```
ui-web vitest 92 files / 1317 tests, type-check, gen:check (161 methods)
ui-tui lint:i18n up to date, lint:rpc in sync, type-check clean
```
One note on your run: `npm run lint:i18n --prefix ui-tui` works here after
`npm ci` in that workspace -- it reports the catalogue up to date. Worth having,
since this MR adds `gui.tier.*` keys and the generated TUI copy goes stale
without regenerating it.
## Verification
On the running page, with !474's server:
```
chip server
boot, no conversation High (shown) high
open the panel 3 rows, tick on High
click Max Max max
reopen the panel tick on Max
draft, before any message High (shown) high
click Medium in the draft Medium high <- staged
send the first message Medium MEDIUM <- applied on create
switch to Max with a session Max max <- written directly
```
No console errors. The screenshot is in the thread below.
```
ui-web vitest 92 files / 1309 tests, type-check, gen:check (161 methods)
ui-tui lint:i18n up to date, lint:rpc in sync, type-check clean
```
Mutation-checked, five ways, each redding a different case: always showing the chip, asking with no conversation, painting the click instead of the reply, not reparenting the panel, and not filtering a menu entry with no id. The last one survived the first pass -- the filter had no test -- and a case was added rather than the filter removed.
## Two things I raised on !474, both since fixed there
- **The per-tier descriptions were not translatable** -- an f-string in
`raven/config/schema.py` with no message id, so any surface rendering them
showed English under a translated heading.
- **They also repeated.** Each read "Sub-agents run at their `<tier>` tier.
Raven's own effort is the same in every mode." -- the first half restating the
name, the second identical on all three, which this panel's footer makes once.
!474 fixed both: `_TIER_TEXTS` says only what differs, and raven translates the
rows it owns. So the last commit here puts them back on the row, where they are
now worth reading -- they had been hidden on the title precisely because of the
two problems above.
```
Medium The least effort a sub-agent is asked for.
High The middle amount of effort, between the other two.
Max The most effort a sub-agent is asked for.
```
`High`'s sentence read "The middle rung, and where every session starts." when
this MR was first opened. `main` has since corrected it -- a config may keep the
built-in rungs and move the default with `defaultMode`, and then that sentence
contradicts the `*` beside another row. `tests/test_acp_modes.py::test_no_rung_claims_a_default_the_config_can_move`
pins it. Nothing on this side names the sentences, so the correction arrives here
by rebasing; the fixtures that had copied the old text are fixed below.
A deployment's own descriptions come through untouched, in whatever language its
author wrote them.
## Rebased onto `main`, and the P2 closed
`main` moved to `ed74b8b1` and took !474's runtime stack with it through
`b09a9d6`, so the four files the merge board named conflicted. !474's branch had
itself been rebased after this one forked, so the shared commits no longer
matched by hash and a `git rebase` walked into the same conflict 29 times.
Resolved by patch-id instead of by hand: of the 29 commits ahead of the old
base, 28 are !474's and already on `main`, and the 5 web commits were replayed
onto `ed74b8b1`. `git range-diff` reports four of the five byte-identical; the
fifth lost one hunk, an unrelated `gui.ws.save_copy` zh string whose escape
`main` had already un-escaped. `HEAD` is now a strict descendant of `origin/main`,
so there is nothing left to merge.
**On the non-mechanical part: nothing here touches `raven/config/schema.py`.**
The commit that introduced the tier sentences is !474's and is on `main`, so
`main`'s wording -- High is "The middle amount of effort, between the other two."
-- and its regression test stand untouched. Confirmed by grep on the rebased
tree, not by inference: the file is not in this MR's diff at all.
**P2, the design canvas -- `8521fddf`.** `demo/130-settings.js` still built its
rows from the retired repeated copy while the server sends one sentence per rung,
so demo mode previewed a line the live UI never receives. The three English
sentences are `_TIER_TEXTS` verbatim now, and the fixture is keyed to `LANG` and
carries the `raven/i18n/zh.py` entries too, since raven translates the rungs it
owns and the canvas can only show the Chinese lines by holding them.
The line lengths that motivated the finding are now reviewable, and they differ:
```
row height
en High The middle amount of effort, between the... 72px <- wraps
en Medium The least effort a sub-agent is asked for. 56px
zh High 居中的投入,介于另外两档之间。 56px
```
Read off the live wire against a gateway on the built-in catalogue, the reply is
the fixture byte for byte, at the same three heights:
```
{"mode":"high","availableModes":[
{"id":"medium","name":"Medium","description":"The least effort a sub-agent is asked for."},
{"id":"high","name":"High","description":"The middle amount of effort, between the other two."},
{"id":"max","name":"Max","description":"The most effort a sub-agent is asked for."}]}
```
`tier.test.ts` had copied the same retired text, which is why its new assertion
could not catch the drift. Its `MENU` is the shipped sentences now, and the case
checks every row against its own sentence rather than one row against a
substring, in both places the text lands. Mutation-checked three ways -- every
row handed the first rung's sentence, the line without the title, the title
without the line -- each reds it.
One defect of my own, caught in the sweep rather than by a gate: I had named the
fixture's builder `tierMenu`, which the live layer also declares. The two are
kept apart only by live's IIFE, and `count-shared-globals.mjs` does not look for
it. Renamed `tierMenuDemo`, matching `tierDemo` and `langPickDemo` beside it.
```
make lint-ui, lint-tui, test-ui, lint-imports all pass
ui-web vitest 92 files / 1328 tests, type-check, gen:check (161 methods)
make test-python 19117 passed, 5 failed
```
The five python failures are pre-existing on `origin/main` and unrelated -- four
NAT64 cases in `tests/test_security_network.py` that depend on how this host
resolves `64:ff9b:1::`, and `test_doctor_answers_where_the_memories_are`. I ran
each on `origin/main` with this branch checked out of the way; both fail there
identically. This MR changes no Python.
## Swept
`mr-review-patterns` pre-submit sweep, over the branch diff.
- **1 (a write location moved)** -- nothing moved; this is a new reader of an existing method.
- **2 (a value with several entry points)** -- the tier has exactly one writer on this side, `absorb`, fed only by a reply. The draft's staged value is the live seam's and is cleared by the read that follows the apply.
- **3d (several lanes through one sink)** -- two lanes reach `load()`: boot, and `session.onChange`. Boot is load-bearing rather than belt-and-braces -- `setCurrent` returns early when the value is unchanged, so a page that boots with no conversation never fires the change, and the chip would stay hidden on exactly the screen where a reader is about to start one. Found in the browser, not by reading.
- **6c (generated artifacts)** -- `ui-tui/src/i18n/messages.generated.ts` regenerated: the catalogue is shared, so adding three `gui.tier.*` keys makes the TUI copy stale and `make lint-tui` fail. Not scope creep; it is this change's own footprint.
- **9 (error handling)** -- a failed read hides the chip rather than naming a tier it cannot vouch for; a failed switch keeps the tier the server last reported and says so; a failed staged apply is announced and then re-read, because the chip is showing the staged tier as though in force.
- **11** -- `tsc --listFiles` resolves 192 files, 0 outside this worktree; `npm ci` in both `ui-web` and `ui-tui`.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 7, 7b, 8, 10.
## Summary
!474 gives a session an effort tier for the sub-agents raven dispatches, and wires `ui-tui` to it. The web front end had no way to see or change it. This adds one.
**A chip beside the model chip, not a group inside the model picker.** A tier is not a model: the picker is where a reader goes to change what answers them, and the two would be read as one list of choices. The panel says in a footer what no row can -- that a tier moves what raven asks of the sub-agents it *dispatches*, and leaves raven's own effort alone -- because every comparable control in other products means the opposite.
Built like `shell/perm.ts` next door and for its reasons: both nodes are static in `page.html`, the panel is reparented to the body to be positioned at all, and the state is one string. The two chips read as one row of session settings.
**The menu is the server's.** Every `session.set_mode` reply carries the whole catalogue, so one round trip draws the control. A deployment that replaces the catalogue is followed rather than second-guessed -- rows are named by what it declares, and only the built-in ids get a ranked icon, since a replacement's rungs cannot be ranked. `"modes": {}` turns the surface off, and an empty menu hides the chip rather than drawing a control over nothing.
**A click paints from the reply.** The handler clamps and refuses; painting the click first would leave the chip naming a tier the next turn will not run at.
**A draft is the exception, and it belongs to the seam rather than the chip.** A conversation being written has no `session_key`, and writing under the empty one lands on a policy the first turn never reads. So the pick is staged and applied on `session.create`, next to the model staged the same way -- a first turn dispatches sub-agents like any other.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Based on !474, and kept small on purpose
Target was !474's branch while `session.set_mode` existed only there. !474 has
since merged, so this now targets `main` and carries only the web layer. It
follows the server rather than duplicating it -- no tier list, no default, no
ladder order is written on this side.
Per the ask to keep MRs small and focused, the per-instance override (`subagents.instance.set_mode`, with `auto` meaning no override) is **not** here. It is a second MR stacked on this one.
**The regenerated client is gone from this branch, as intended.** !474 regenerated `ui-tui`'s client and not `ui-web`'s, so `npm run gen:check --prefix ui-web` -- the first line of `make lint-ui` -- failed on its head. I raised it there and carried a pure `npm run gen` here only to compile against. It landed on !474 as `102bbc24`, and rebasing dropped mine: `git` recognised it as already applied, and the file here is byte-identical to the one !474 now carries. This MR is four commits of its own work.
## After review
Three P1s, each reproduced on the running page before I touched anything, one
commit each. Two mistakes of my own during that verification are worth recording,
because both nearly produced a wrong answer: I first wrote the replacement
catalogue into `/root/.raven/config.json` while the gateway runs on
`RAVEN_HOME=/root/.raven-preview`, which made P1-1 look like it did not
reproduce; and my first probe for P1-3 wrapped `window.loadTier`, which is not
what `main.tsx` calls -- the control read 0 as well, which is the only reason I
noticed.
**A deployment's own modes were called sub-agent tiers -- `1f348d98`.** Not loose
wording; the opposite of the truth. With `quick`/`thorough` declared, on the page:
```
before after
aria "Sub-agent effort: Quick" aria "Session mode: Quick"
footer "...Raven's own effort is the footer "A profile this deployment
same in every tier." declares... not offered to sub-agents."
```
while `clamp_tier('quick', ('medium','high','max'))` is `None` -- no sub-agent is
touched -- and `quick`'s `max_tool_iterations: 4` moves raven's own cap. The
heading and footer now follow the test the clamp applies: every rung on offer is
one the ladder ranks, or it is a mode catalogue and says so. Every rather than
any, since a mixed catalogue is read case by case and a heading cannot be half
true.
Neither wording claims raven's effort is unchanged any more, though the shipped
catalogue does leave it alone. The reply carries an id, a name and a description
and never the knobs, so a catalogue that names its rungs after the ladder AND
sets a cap is indistinguishable here from the shipped one. The control says the
part it can stand behind.
**And a second round on the same finding -- `021aec54`.** The first fix answered
the naming question at the catalogue's scope and then let the footer inherit that
answer, which is a different claim. `clamp_tier` honours an exact hit in any
vocabulary that spells the rung the same way, so one catalogue answers twice:
```
clamp_tier('high', ('medium','high','max')) -> 'high'
clamp_tier('thorough', ('medium','high','max')) -> None
```
The footer is keyed to the rung in force now; the heading stays keyed to the
catalogue. On the page with `{high, thorough}`:
```
in force heading footer
High Session mode ...is offered to the sub-agents this conversation dispatches
Thorough Session mode ...is not one of the built-in tiers, so it is not offered
```
**A tier staged for an abandoned draft leaked -- `f53444a1`.** Reproduced exactly
as reported:
```
before after
draft one, stage Max Max Max
open another conversation, no send High High
start draft two High High
send draft two -> server tier MAX high
```
**A reconnect left the chip stale -- `f53444a1`.** Measured by counting the reads
in the page, with a control:
```
before after
reopen the SAME id (reconnect does) 0 1
switch to another conversation 1 2 <- control
```
`setCurrent` returns early for an unchanged id, so `onChange` never fired; and
`_session_policies` is a plain in-memory dict with no persistence, so a gateway
restart puts every session back on the catalogue default underneath.
Both go away by doing what the model does -- reset and re-read together in
`startDraft` and `openLiveSession` -- so the `onChange` lane goes rather than
gaining a third caller, and `pendingTier` moves beside `pendingModel` in the file
that resets both. The two assembled-page harnesses gain the step and three cases.
Mutation-checked, nine more ways on top of the original five: always ranking a
catalogue as a tier, `every` weakened to `some`, not writing the heading, a chip
aria that does not distinguish, and each of the two new reset/re-read sites.
```
ui-web vitest 92 files / 1317 tests, type-check, gen:check (161 methods)
ui-tui lint:i18n up to date, lint:rpc in sync, type-check clean
```
One note on your run: `npm run lint:i18n --prefix ui-tui` works here after
`npm ci` in that workspace -- it reports the catalogue up to date. Worth having,
since this MR adds `gui.tier.*` keys and the generated TUI copy goes stale
without regenerating it.
## Verification
On the running page, with !474's server:
```
chip server
boot, no conversation High (shown) high
open the panel 3 rows, tick on High
click Max Max max
reopen the panel tick on Max
draft, before any message High (shown) high
click Medium in the draft Medium high <- staged
send the first message Medium MEDIUM <- applied on create
switch to Max with a session Max max <- written directly
```
No console errors. The screenshot is in the thread below.
```
ui-web vitest 92 files / 1309 tests, type-check, gen:check (161 methods)
ui-tui lint:i18n up to date, lint:rpc in sync, type-check clean
```
Mutation-checked, five ways, each redding a different case: always showing the chip, asking with no conversation, painting the click instead of the reply, not reparenting the panel, and not filtering a menu entry with no id. The last one survived the first pass -- the filter had no test -- and a case was added rather than the filter removed.
## Two things I raised on !474, both since fixed there
- **The per-tier descriptions were not translatable** -- an f-string in
`raven/config/schema.py` with no message id, so any surface rendering them
showed English under a translated heading.
- **They also repeated.** Each read "Sub-agents run at their `<tier>` tier.
Raven's own effort is the same in every mode." -- the first half restating the
name, the second identical on all three, which this panel's footer makes once.
!474 fixed both: `_TIER_TEXTS` says only what differs, and raven translates the
rows it owns. So the last commit here puts them back on the row, where they are
now worth reading -- they had been hidden on the title precisely because of the
two problems above.
```
Medium The least effort a sub-agent is asked for.
High The middle amount of effort, between the other two.
Max The most effort a sub-agent is asked for.
```
`High`'s sentence read "The middle rung, and where every session starts." when
this MR was first opened. `main` has since corrected it -- a config may keep the
built-in rungs and move the default with `defaultMode`, and then that sentence
contradicts the `*` beside another row. `tests/test_acp_modes.py::test_no_rung_claims_a_default_the_config_can_move`
pins it. Nothing on this side names the sentences, so the correction arrives here
by rebasing; the fixtures that had copied the old text are fixed below.
A deployment's own descriptions come through untouched, in whatever language its
author wrote them.
## Rebased onto `main`, and the P2 closed
`main` moved to `ed74b8b1` and took !474's runtime stack with it through
`b09a9d6`, so the four files the merge board named conflicted. !474's branch had
itself been rebased after this one forked, so the shared commits no longer
matched by hash and a `git rebase` walked into the same conflict 29 times.
Resolved by patch-id instead of by hand: of the 29 commits ahead of the old
base, 28 are !474's and already on `main`, and the 5 web commits were replayed
onto `ed74b8b1`. `git range-diff` reports four of the five byte-identical; the
fifth lost one hunk, an unrelated `gui.ws.save_copy` zh string whose escape
`main` had already un-escaped. `HEAD` is now a strict descendant of `origin/main`,
so there is nothing left to merge.
**On the non-mechanical part: nothing here touches `raven/config/schema.py`.**
The commit that introduced the tier sentences is !474's and is on `main`, so
`main`'s wording -- High is "The middle amount of effort, between the other two."
-- and its regression test stand untouched. Confirmed by grep on the rebased
tree, not by inference: the file is not in this MR's diff at all.
**P2, the design canvas -- `8521fddf`.** `demo/130-settings.js` still built its
rows from the retired repeated copy while the server sends one sentence per rung,
so demo mode previewed a line the live UI never receives. The three English
sentences are `_TIER_TEXTS` verbatim now, and the fixture is keyed to `LANG` and
carries the `raven/i18n/zh.py` entries too, since raven translates the rungs it
owns and the canvas can only show the Chinese lines by holding them.
The line lengths that motivated the finding are now reviewable, and they differ:
```
row height
en High The middle amount of effort, between the... 72px <- wraps
en Medium The least effort a sub-agent is asked for. 56px
zh High 居中的投入,介于另外两档之间。 56px
```
Read off the live wire against a gateway on the built-in catalogue, the reply is
the fixture byte for byte, at the same three heights:
```
{"mode":"high","availableModes":[
{"id":"medium","name":"Medium","description":"The least effort a sub-agent is asked for."},
{"id":"high","name":"High","description":"The middle amount of effort, between the other two."},
{"id":"max","name":"Max","description":"The most effort a sub-agent is asked for."}]}
```
`tier.test.ts` had copied the same retired text, which is why its new assertion
could not catch the drift. Its `MENU` is the shipped sentences now, and the case
checks every row against its own sentence rather than one row against a
substring, in both places the text lands. Mutation-checked three ways -- every
row handed the first rung's sentence, the line without the title, the title
without the line -- each reds it.
One defect of my own, caught in the sweep rather than by a gate: I had named the
fixture's builder `tierMenu`, which the live layer also declares. The two are
kept apart only by live's IIFE, and `count-shared-globals.mjs` does not look for
it. Renamed `tierMenuDemo`, matching `tierDemo` and `langPickDemo` beside it.
```
make lint-ui, lint-tui, test-ui, lint-imports all pass
ui-web vitest 92 files / 1328 tests, type-check, gen:check (161 methods)
make test-python 19117 passed, 5 failed
```
The five python failures are pre-existing on `origin/main` and unrelated -- four
NAT64 cases in `tests/test_security_network.py` that depend on how this host
resolves `64:ff9b:1::`, and `test_doctor_answers_where_the_memories_are`. I ran
each on `origin/main` with this branch checked out of the way; both fail there
identically. This MR changes no Python.
## Swept
`mr-review-patterns` pre-submit sweep, over the branch diff.
- **1 (a write location moved)** -- nothing moved; this is a new reader of an existing method.
- **2 (a value with several entry points)** -- the tier has exactly one writer on this side, `absorb`, fed only by a reply. The draft's staged value is the live seam's and is cleared by the read that follows the apply.
- **3d (several lanes through one sink)** -- two lanes reach `load()`: boot, and `session.onChange`. Boot is load-bearing rather than belt-and-braces -- `setCurrent` returns early when the value is unchanged, so a page that boots with no conversation never fires the change, and the chip would stay hidden on exactly the screen where a reader is about to start one. Found in the browser, not by reading.
- **6c (generated artifacts)** -- `ui-tui/src/i18n/messages.generated.ts` regenerated: the catalogue is shared, so adding three `gui.tier.*` keys makes the TUI copy stale and `make lint-tui` fail. Not scope creep; it is this change's own footprint.
- **9 (error handling)** -- a failed read hides the chip rather than naming a tier it cannot vouch for; a failed switch keeps the tier the server last reported and says so; a failed staged apply is announced and then re-read, because the chip is showing the staged tier as though in force.
- **11** -- `tsc --listFiles` resolves 192 files, 0 outside this worktree; `npm ci` in both `ui-web` and `ui-tui`.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 7, 7b, 8, 10.
## Summary
Pictures a tool showed the model (page renders from `ppt_build`, template pages from `ppt_template`, review renders, inspected figures) stayed in the transcript for the whole turn. On a 20-page deck one request accumulated 75 to 80 of them across 14 to 19 messages, and OpenRouter refused the request with HTTP 413 `image_too_large` four times over two runs on 2026-09-05 (amber 09:59 and 10:05, red 11:14 and 11:39). The existing recovery stripped pictures from the retried request only, so they built back up and the refusal came back a few calls later.
This MR adds a standing image window to the agent loop (`raven/agent/loop`), host side only; the ppt engine is untouched.
- Before every model call the loop weighs the pictures still live in the transcript. While they fit the budget (`agents.defaults.imageWindowBudgetBytes`, default 12 MB decoded, carried on `RecoveryLimits`; 0 turns the standing pass off and leaves only the refusal ladder) nothing changes. When they do not, every image-bearing message but the newest `_IMAGE_WINDOW_RECENT_MESSAGES` (2) loses its pictures at once. The budget sits well under the refusal line measured on the audit artifacts (about 26.3 MB decoded, not the nominal 30 MB: requests of 26.07 and 26.21 MB passed while 26.46 MB and up were refused) and leaves room for the largest batch seen (21 template pages, 6.06 MB) to land on a full window.
- A withdrawn picture becomes a note, not a bare "elided": it names the tool, the iteration and the caption the tool wrote beside the picture (`[image no longer in context: "Page 14 of 20: ..." from ppt_build at iteration 31. This turn's pictures outgrew their byte budget, so only the 2 newest image-bearing result(s) keep theirs. To see it again, ask ppt_build for it again]`). Provenance is stamped when the picture enters the transcript (`_image_sources`, one entry per picture, caption taken from the text part the tool put in front of it), on both transports (picture inside the tool result, or in the user message the loop attaches when the endpoint cannot carry one there). The key is dropped by the provider allow-list and popped by `_save_turn`; it is never sent and never stored.
- The window is applied in place and only to messages that still carry a picture, so between two calls either nothing changes or one collapse does. A collapse on a budget rather than a slide per batch because each rewrite is a point past which an upstream prefix cache cannot match: the first cut of this window slid one message out per new batch, broke the prefix on 16 of 60 and 19 of 41 calls on the two measured decks, and one deck's cache hit rate fell from 84.5% to 64.7%. Replayed on the same sequences the collapse breaks the prefix 1 and 4 times (peaks 11.08 MB and 11.88 MB); keeping four messages instead of two would still have broken it 14 and 17 times while carrying 8.9 and 16.1 MB.
- A size refusal (413) no longer strips pictures from one retry. It drops the budget and keeps only the newest image-bearing message, and on a second refusal closes the window entirely, both for the rest of the turn; the notes then say the endpoint refused the pictures. `_strip_images` is gone. At a closed window the model sees no picture for the rest of the turn; accepted rather than covered by a per-batch budget because reaching it takes a single batch over the cap on its own, which no measured run came near.
- A picture the user sent is not part of the window (it is the subject of the turn, not a result), except at the final notch of the refusal ladder when nothing else is left to take out. The overflow path (`_emergency_shrink`) reaches those pictures only as a third pass, after result pictures and older tool bodies freed nothing.
- What is filed: on the transport that carries a picture inside the tool message the message outlives the turn, so the withdrawal note is filed with its facts only (which picture, which tool, which round) and not this turn's reason or the "ask again" hint; the live note in the request is unchanged. The provenance key is not filed at all; the tracing `llm.input` artifact does record the request as handed to the provider, before the allow-list, so the entries appear there beside the pictures.
- The overflow path (`_emergency_shrink` -> `_elide_older_images`) keeps its tighter count and its copy-and-return contract and uses the same notes, with the overflow as the reason.
Also in this MR, from a nonblocking review thread on the merged host-seams MR: the streaming entry point guarded `_recovery_limits` with `getattr` defaults while the error handler and three older readers in the same file read it plainly. The attribute is assigned unconditionally in `AgentLoop.__init__` and the mixin has one consumer, so the file now uses the plain read throughout, and the streaming tests' stand-in carries the attribute like the class does.
Two corrections the audit surfaced, for anyone reading the same artifacts: audit artifacts under `llm.input/` are named by the time the response came back, not the time the request went out; and the OpenRouter cap is about 26.3 MB decoded, see above.
Known issue, engine side (not fixed here): on the first validation run the author renamed the published file with `exec` (`mv deck.pptx <chinese title>.pptx`) after `published.json` had recorded `out/deck.pptx`. The record's path no longer exists while its sha256 matches the renamed file. A check that trusts the recorded path would call that deck unpublished; the record should lead with the digest and treat the path as a hint, or the skill should say not to rename after publishing.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Unit tests, on the branch before review (then rebased onto `main` after MR 482 merged, no code change):
```
uv run --frozen --no-sync pytest tests/test_agent_loop_llm_error_patience.py tests/test_read_file_image.py tests/test_agent_loop_stream.py -q
151 passed, 1 skipped
uv run --frozen --no-sync pytest <131 test files that import the agent loop> -q
4328 passed, 2 skipped in 173s
uv run --frozen --no-sync ruff check <changed files> -> All checks passed
uv run --frozen --no-sync python scripts/check_source_language.py <base>..HEAD -> exit 0
```
Live deck runs against OpenRouter `z-ai/glm-5.3-flash`, 20-page Chinese deck, same prompt and driver each time (`hit` = cache_read / (cache_read + input) over the deck agent's session; a `break` is a call whose cache_read fell below a tenth of the previous prompt, and the audit artifacts say whether the earlier messages had changed):
| run | branch state | 413 | hit | breaks: history rewritten / provider-side | wall |
|---|---|---|---|---|---|
| amber, 2026-09-05 | before this MR | 2 | 90.3% | - | - |
| red, 2026-09-05 | before this MR | 2 | 84.5% | - | - |
| red, 2026-09-06 04:45 | first cut (sliding window) | 0 | 64.7% | 12 / 1 | 77 min |
| amber, 2026-09-06 04:45 | first cut (sliding window) | 0 | 81.5% | 4 / 1 | 95 min |
| red, 2026-09-06 08:13 | byte budget (this MR) | 0 | - | 0 / 6 (partial: run lost to a proxy outage after 4 builds, 25 calls) | - |
| amber, 2026-09-06 09:44 | byte budget (this MR), full stack | 0 | 84.9% | 0 / 7 | 89 min |
Peak pictures in one request on the amber run: 11.15 MB decoded over 4 messages with no collapse; the budget never had to fire on that deck, and no request came near the 26 MB refusal line. The two 2026-09-06 04:45 runs are the ones this MR's second commit was measured against: every rewritten break there was a window slide, and the same sequences replayed through the byte budget break the prefix 1 and 4 times.
Full-stack runs on 2026-09-06 17:02 UTC (main 13e21ea7 + this MR + MR 506 + MR 513, through the egress proxy), same prompt and driver, both delivered through the publish tool with `deck/state/published.json` naming the file's digest:
| run | pages | model calls | wall | cache hit | breaks (rewritten / provider) | 413 | empty replies |
|---|---|---|---|---|---|---|---|
| red, direct chat with Raven-PPT | 20 | 87 | 100 min (incl. one review round) | 95.8% | 1 / 1 | 0 | 0 |
| amber, direct chat with Raven-PPT | 20 | 38 | 79 min | 90.3% | 1 / 1 | 0 | 0 |
| red, 8 pages, through the main agent (DAG: Raven-Research-NG then Raven-PPT) | 8 | - | 98 min end to end | - | - | 0 | 0 |
The one rewritten break per run is the single budget collapse (12 MB reached once per 20-page deck). On the main-agent path the DAG completed 2/2, the node's reply carried the `MEDIA:` line, and the main agent answered with `deliver_files` (pptx + pdf, download tokens issued).
Review round (four commits after the runs above, no behaviour change): the three descriptions of the loop's in-turn shrinks now name the image window; the tool-result transport's provenance stamp and the filed form of a withdrawal note are pinned by tests that drive a whole turn; the note's reason openings are shared between composer and parser, with a test that composes every reason and files it (a reworded opening on either side fails it).
```
uv run --frozen --no-sync pytest tests/test_agent_loop_llm_error_patience.py tests/test_agent_loop_context_overflow.py tests/test_read_file_image.py tests/test_agent_loop_stream.py tests/test_rpc_reasoning_render.py -q -> 195 passed, 1 skipped
```
Not covered by the live runs: a request whose newest two image-bearing messages alone exceed the budget (would keep both and rely on the 413 ladder), and the closed-window state after two refusals; both are unit-tested only.
## Risk
Behaviour change, user visible only through the model's behaviour on long picture-heavy turns:
- The model no longer sees renders older than the current window. Once the live pictures exceed 12 MB it keeps the newest two image-bearing results and gets a note per withdrawn picture that says which tool showed which page in which iteration and that asking the tool again brings it back. On the validation decks this collapse happened once (red) and four times (amber) in a run; between collapses every render stays in view.
- After a 413 the window closes for the rest of the turn (newest message only, then none); the notes say so and point at the text beside the pictures.
- The overflow path's placeholder text changed from `[image elided to fit the context window]` to the same note shape with the overflow as the reason.
- `_strip_images` was removed; the 413 branch of the loop is the only caller and now uses the window.
Rollback: revert the branch; there is no data migration. `agents.defaults.imageWindowBudgetBytes` is the knob (0 = no standing pass, only the reactive ladder; a very large value keeps every picture as before), and `_IMAGE_WINDOW_RECENT_MESSAGES` on `AgentLoop` is the kept count. The overflow path (`_emergency_shrink`) sheds the user's own pictures only as a third pass, after result pictures and tool bodies freed nothing.
- [x] Security impact considered (no new input reaches the model; provenance stamps are host-only and never leave the process)
- [x] Backward compatibility considered (one additive, backward-compatible config-schema field, `agents.defaults.imageWindowBudgetBytes`, whose default is the previous constant; no persisted-session change; `_image_sources` is popped before storage)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
A DAG node that reports it could not accomplish its task suspends and asks the agent what
to do. Until now the answer could only be `continue` (send a correction and let the node
retry) or `abandon` (fail it and skip its dependents). Both keep the graph the agent
committed to at dispatch. When the plan itself is what turned out to be wrong, neither
helps: the agent's only recourse was to cancel the run and submit a fresh graph, which
throws away every node that had already succeeded.
This adds a third decision, `replan`. The agent hands `resolve_dag_node` a replacement node
list, the run being answered winds down, and a new run starts from that list, referencing
the wound-down run's completed nodes by id.
**Chained runs, not an in-place splice.** Node ids are claimed per conversation at
`store.init`, and every read-back path takes a run's structure from its `graph.json`.
Splicing would have to claim ids mid-run, rewrite that file into a cumulative graph, and
keep dropped nodes in it so they do not vanish from the record. Chaining instead lands on
the cross-run reference machinery that already exists for naming an earlier run's completed
node, and leaves both runs individually readable.
Decisions a later reader will want the reasons for:
- **A completed node is referenced, never re-declared.** Name it in `depends_on` and read it
with `{{ <id>.output }}`. Its id belongs to the old run permanently, so re-declaring it is
refused.
- **The adjudicated node is given up on.** No attempt budget crosses runs, because carrying
one would require node identity to span ids that must differ.
- **In-flight nodes are cancelled, not drained.** A replan is a statement that the remaining
plan is wrong; letting nodes finish work the new graph does not want spends dispatches on
output nobody reads.
- **A replan ends the adjudication round for every node suspended alongside it**, answered or
not. Several nodes can be waiting for the agent at once, and a sibling's answer can no longer
change a graph that is being replaced. Waiting for one is not merely wasted: on a run bound to
a live turn the wait carries no deadline, and the lane that would answer the sibling is the
same one parked in `resolve_dag_node` waiting for this run to finalize, so both wait without a
bound. Nodes left unanswered are recorded as superseded rather than as having timed out --
they were never asked.
- **The successor passes the same preflight a submitted graph does** -- the confirmation gate
and the hourly dispatch charge included. A replan therefore costs one unit of the same
hourly quota, and if the original graph was confirmed by the user, so is its successor.
- **No replan cap.** The hourly dispatch quota is the only mechanical bound; see Risk.
Persistence keeps the two runs separate. The successor is saved as its own run with its own
directory and `graph.json`; the run it replaces gains a reserved `replan` key on its own
`graph.json` recording the decision, the successor's id, and whether it started. An
interrupted hand-off is recorded as started `false` with a reason, so a reader never sees
nodes pointing at a successor the file does not admit was attempted.
Both front ends learn about the link through a new `dag.run_replanned` wire event. It is
emitted the moment the desk accepts the decision, before the answered run is awaited. That
timing is forced by the two front ends disagreeing: one pins a run's state by id and keeps
it, so a link arriving at any time lands; the other resolves a card through a live index
keyed by run id and drops that entry when the run completes. An event emitted after the
successor starts arrives after that drop and resolves to nothing, while a unit test that
never plays those frames passes -- code that looks done and does nothing. The durable record
still waits for the outcome: a live hint may be optimistic, an audit may not.
Design and the decisions behind it are in `docs/specs/2026-09-04-dag-replan-design.md`,
including a "deliberately out of scope" section.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on the rebased tree, at the head this description is written against.
- `make test-python` -- 18711 passed, 1 failed, 67 skipped, in 188.18s.
The one failure is `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
which this branch does not touch and does not cause; see Risk for how that was established.
- `make lint-python` -- clean (ruff check and ruff format --check).
- `make check-source-language` -- clean.
- `make check-large-files` -- clean.
- `npm run type-check --prefix ui-tui` -- clean.
- `npm test --prefix ui-tui -- dagRun.test` -- 24 passed.
- `npm test --prefix ui-web -- src/features/transcript` -- 130 passed.
- `npm run lint:i18n --prefix ui-tui` -- generated catalogue up to date.
- The four suites exercising the changed code, run together under xdist as CI runs them:
438 passed.
Every new guard was sabotage-verified rather than assumed: the change it exists to catch was
reintroduced, the test was watched to go red with the assertion it was written for, and the
source was restored byte for byte. That includes the three defects found only by reviewing the
branch whole, after every individual task had passed its own review -- a replan landing while
the runner was parked was recorded as an abandonment, a foreground run whose turn had been
released announced its own wind-down as a raw dataclass, and a replan left the round waiting on
the siblings it had just made irrelevant.
The last of those has no deadline in the code under test to end it, so its regression drives the
real wait under `asyncio.timeout` and fails on the clock rather than hanging the suite: without
the guard, `TimeoutError` in 5.98s.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Behaviour change, opt-in.** `resolve_dag_node` gains a `replan` value and a `nodes`
parameter. The two existing decisions are untouched, and a caller that never sends `replan`
sees no change. Rolling back is reverting the branch: nothing migrates, and a `graph.json`
carrying a `replan` key stays readable to every reader of that file, all of which read named
keys rather than iterating.
**A replan chain is bounded only by the hourly dispatch quota.** That was deliberate -- a
count cap would have to guess how many corrections a task deserves. Each hop costs one unit
of the same quota a fresh graph costs, and each writes its own run directory, so a long
chain leaves one directory per hop with no TTL and no reclaim path. That matches how run
directories already accumulate; it is not made worse per run, only reachable more often.
**Known gaps, deliberately not closed here.** The bound foreground lane's silence is now an
explicit check rather than an eviction accident, but has no test -- reaching it needs a
released tray and a foreground turn to release it. The link record is written after the
successor is submitted or refused as invalid, so a cancellation raised inside the submission
still escapes both guards; the remaining window is documented where it happens.
`prepare_replan` refuses a graph that fails validation, but a backend IO error or a
non-object `graph.json` propagates rather than refusing cleanly -- no state is corrupted,
since that runs before the node is answered and the node stays waiting. The successor does
not draw under the tool row that spawned it in the web UI, for the reason given in the spec's
out-of-scope section; the link event still lands, so the replan itself is visible.
**The one failing test is not this branch's.** Established two ways rather than asserted:
every input it reads is byte-identical to the base
(`git diff --stat origin/main...HEAD -- raven/cli/ raven/config/ tests/test_cli_doctor_commands.py`
is empty), and the failure is console width plus path length, not code. Under xdist at the
default width it fails; serially at the default width it passes; under xdist with
`COLUMNS=200` it passes. xdist inserts a worker directory into the temp path and narrows the
captured console, and between them rich wraps the path across the substring the assertion
looks for.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
A DAG node that reports it could not accomplish its task suspends and asks the agent what
to do. Until now the answer could only be `continue` (send a correction and let the node
retry) or `abandon` (fail it and skip its dependents). Both keep the graph the agent
committed to at dispatch. When the plan itself is what turned out to be wrong, neither
helps: the agent's only recourse was to cancel the run and submit a fresh graph, which
throws away every node that had already succeeded.
This adds a third decision, `replan`. The agent hands `resolve_dag_node` a replacement node
list, the run being answered winds down, and a new run starts from that list, referencing
the wound-down run's completed nodes by id.
**Chained runs, not an in-place splice.** Node ids are claimed per conversation at
`store.init`, and every read-back path takes a run's structure from its `graph.json`.
Splicing would have to claim ids mid-run, rewrite that file into a cumulative graph, and
keep dropped nodes in it so they do not vanish from the record. Chaining instead lands on
the cross-run reference machinery that already exists for naming an earlier run's completed
node, and leaves both runs individually readable.
Decisions a later reader will want the reasons for:
- **A completed node is referenced, never re-declared.** Name it in `depends_on` and read it
with `{{ <id>.output }}`. Its id belongs to the old run permanently, so re-declaring it is
refused.
- **The adjudicated node is given up on.** No attempt budget crosses runs, because carrying
one would require node identity to span ids that must differ.
- **In-flight nodes are cancelled, not drained.** A replan is a statement that the remaining
plan is wrong; letting nodes finish work the new graph does not want spends dispatches on
output nobody reads.
- **A replan ends the adjudication round for every node suspended alongside it**, answered or
not. Several nodes can be waiting for the agent at once, and a sibling's answer can no longer
change a graph that is being replaced. Waiting for one is not merely wasted: on a run bound to
a live turn the wait carries no deadline, and the lane that would answer the sibling is the
same one parked in `resolve_dag_node` waiting for this run to finalize, so both wait without a
bound. Nodes left unanswered are recorded as superseded rather than as having timed out --
they were never asked.
- **The successor passes the same preflight a submitted graph does** -- the confirmation gate
and the hourly dispatch charge included. A replan therefore costs one unit of the same
hourly quota, and if the original graph was confirmed by the user, so is its successor.
- **No replan cap.** The hourly dispatch quota is the only mechanical bound; see Risk.
Persistence keeps the two runs separate. The successor is saved as its own run with its own
directory and `graph.json`; the run it replaces gains a reserved `replan` key on its own
`graph.json` recording the decision, the successor's id, and whether it started. An
interrupted hand-off is recorded as started `false` with a reason, so a reader never sees
nodes pointing at a successor the file does not admit was attempted.
Both front ends learn about the link through a new `dag.run_replanned` wire event. It is
emitted the moment the desk accepts the decision, before the answered run is awaited. That
timing is forced by the two front ends disagreeing: one pins a run's state by id and keeps
it, so a link arriving at any time lands; the other resolves a card through a live index
keyed by run id and drops that entry when the run completes. An event emitted after the
successor starts arrives after that drop and resolves to nothing, while a unit test that
never plays those frames passes -- code that looks done and does nothing. The durable record
still waits for the outcome: a live hint may be optimistic, an audit may not.
Design and the decisions behind it are in `docs/specs/2026-09-04-dag-replan-design.md`,
including a "deliberately out of scope" section.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on the rebased tree, at the head this description is written against.
- `make test-python` -- 18711 passed, 1 failed, 67 skipped, in 188.18s.
The one failure is `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
which this branch does not touch and does not cause; see Risk for how that was established.
- `make lint-python` -- clean (ruff check and ruff format --check).
- `make check-source-language` -- clean.
- `make check-large-files` -- clean.
- `npm run type-check --prefix ui-tui` -- clean.
- `npm test --prefix ui-tui -- dagRun.test` -- 24 passed.
- `npm test --prefix ui-web -- src/features/transcript` -- 130 passed.
- `npm run lint:i18n --prefix ui-tui` -- generated catalogue up to date.
- The four suites exercising the changed code, run together under xdist as CI runs them:
438 passed.
Every new guard was sabotage-verified rather than assumed: the change it exists to catch was
reintroduced, the test was watched to go red with the assertion it was written for, and the
source was restored byte for byte. That includes the three defects found only by reviewing the
branch whole, after every individual task had passed its own review -- a replan landing while
the runner was parked was recorded as an abandonment, a foreground run whose turn had been
released announced its own wind-down as a raw dataclass, and a replan left the round waiting on
the siblings it had just made irrelevant.
The last of those has no deadline in the code under test to end it, so its regression drives the
real wait under `asyncio.timeout` and fails on the clock rather than hanging the suite: without
the guard, `TimeoutError` in 5.98s.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Behaviour change, opt-in.** `resolve_dag_node` gains a `replan` value and a `nodes`
parameter. The two existing decisions are untouched, and a caller that never sends `replan`
sees no change. Rolling back is reverting the branch: nothing migrates, and a `graph.json`
carrying a `replan` key stays readable to every reader of that file, all of which read named
keys rather than iterating.
**A replan chain is bounded only by the hourly dispatch quota.** That was deliberate -- a
count cap would have to guess how many corrections a task deserves. Each hop costs one unit
of the same quota a fresh graph costs, and each writes its own run directory, so a long
chain leaves one directory per hop with no TTL and no reclaim path. That matches how run
directories already accumulate; it is not made worse per run, only reachable more often.
**Known gaps, deliberately not closed here.** The bound foreground lane's silence is now an
explicit check rather than an eviction accident, but has no test -- reaching it needs a
released tray and a foreground turn to release it. The link record is written after the
successor is submitted or refused as invalid, so a cancellation raised inside the submission
still escapes both guards; the remaining window is documented where it happens.
`prepare_replan` refuses a graph that fails validation, but a backend IO error or a
non-object `graph.json` propagates rather than refusing cleanly -- no state is corrupted,
since that runs before the node is answered and the node stays waiting. The successor does
not draw under the tool row that spawned it in the web UI, for the reason given in the spec's
out-of-scope section; the link event still lands, so the replan itself is visible.
**The one failing test is not this branch's.** Established two ways rather than asserted:
every input it reads is byte-identical to the base
(`git diff --stat origin/main...HEAD -- raven/cli/ raven/config/ tests/test_cli_doctor_commands.py`
is empty), and the failure is console width plus path length, not code. Under xdist at the
default width it fails; serially at the default width it passes; under xdist with
`COLUMNS=200` it passes. xdist inserts a worker directory into the temp path and narrows the
captured console, and between them rich wraps the path across the substring the assertion
looks for.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Three seams an unattended agent needs, none of them deck-specific.
An outer retry ladder for a model call that comes back retryable after the provider's own seconds-long ladder gave up: `llmErrorRetryDelays` (default 15, 30, 60 seconds; an explicit `[]` turns it off) and `llmRetryAfterOutput`, which stays off so a person watching a stream never sees the words twice and can be turned on for a client that is a machine. One measured run had 62 minutes and 23.8M tokens of work behind it when a 40-second gateway outage ended the turn; another had two hours behind it when a mid-stream disconnect ended it with nothing published. The streaming path takes the same ladder, so a reconnect that fails past the first attempt no longer raises out of the loop.
A call refused for carrying too many image tokens is asked again with the images dropped rather than failing the turn: the newest image-bearing message first, then every one of them.
`read_file` names what a path is when it cannot be read (a URL, a host-like string, a directory), so a model that passed a link where a path belongs is told that instead of "no such file".
## Type
- [x] Feature
## Verification
`uv run pytest tests -q -k "llm_error_patience or agent_loop_stream or filesystem_tools or error_classification or two_tier_ledger or web_providers or dag_adjudication"` -> 180 passed. Full touched surface on this stack: 3603 passed, 9 skipped. `uv run ruff check raven/ tests/test_agent_loop_llm_error_patience.py` clean; pre-commit passed on the commit.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Defaults keep today's behaviour: the ladder is off for a stream that already produced output, and the image-stripping retry only fires on a refusal that names the image budget. `llmErrorRetryDelays: []` restores the old immediate failure. Rollback is reverting this commit; nothing else depends on the two new config rows.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## 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.
Two shapes in the shippable kernel shared one name: the spine's StreamDelta
(a token fragment on its way to an outlet: delta, stream_id, source) and the
provider paper's StreamDelta (a raw model chunk: content, tool_call_delta,
usage, reasoning, finish_reason). providers/streaming.py folds the second
into the first in one function, and a third-party provider author choosing
between two same-named public types with different fields had only the
import path to go on. The paper's chunk is now ChatDelta, everywhere it is
produced or consumed (providers, trajectory replay, the tests); the spine's
deliverable keeps its name. Ledger updated.
Audit ref PAP-08, ruled A (rename on the paper side; the frozen spine is untouched).
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Papers lose two pieces of behaviour that had grown on their shapes:
- ToolCallRequest.to_openai_tool_call, the OpenAI wire serializer (and the
paper's only import json), becomes providers.tool_calls.openai_tool_call;
the loop, the curator segment and the sub-agent backend call the function
- TruncationInfo.as_error, the model-facing refusal sentence, moves to the
tool registry as the private helper that composes the rest of that
sentence; the paper keeps the fact (at_tokens) and nothing else
TurnContext, the carrier the contract-tier ContextEngine.assemble takes,
was a shelf dataclass the paper could only name under TYPE_CHECKING; it now
lives in contracts.context next to AssemblyContext (ledger updated), and
context_engine re-exports it as before.
Knowledge that had leaked into harness code goes back to its owner:
- core.engine_stack.build_local_sessions is the one derivation of the
launch-directory session manager and workdir resolver; raven agent used
to carry a verbatim copy, comment included
- core.plugin_stack.discover_plugins is the one place that scans the four
plugin sources; raven plugins and the rpc ext.list method call it, and
plugin_discovery_sources joins the module's __all__
- routing.classifier.routing_api_key knows that routing runs on OpenRouter;
providers.transcription.transcription_api_key knows that transcription
runs on Groq; core and the gateway manager stop naming either vendor
- cli.update_notice.read_cache is public: the rpc system method reads it
- the everos plugin declares .roots as a host-reachable seam; the onboard
wizard was already reaching it
Audit refs CORE-05, CORE-11, PAP-01, PAP-02, PAP-07, SD-08, SD-15, SD-17.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
Found while investigating the first row of Dizhan's `子智能体功能与显示问题` doc (*回注内容过程中未正常显示,刷新后才会正常显示*). This is not that bug's fix, but it is a real defect on the same wire, and it is the one that explains why "前后端接线没有约定好" was a fair thing to say.
**`turn.started` is not in the `TurnEvent` union — on either side.** It has a schema component, it has a Pydantic model, and neither is reachable from the union that `tests/test_rpc_schema_match.py` walks. The 290-test contract guard has never looked at this event.
So it drifted the first time anyone touched it. `05957452` (judge a dag node) taught `announce_dag_exception` to emit:
```python
mark = {"kind": "dag", "label": run_id, "status": "exception", "run_id": run_id, "node_id": node_id}
```
while `TurnStartedEvent.payload.delegated` still declared `status: enum ["ok","error"]` with `additionalProperties: false`, and `TurnStartedPayload` had **no `delegated` field at all** under `extra="forbid"`. Verified with `jsonschema` against the published contract before changing anything:
```
Additional properties are not allowed ('node_id' was unexpected)
```
That commit did carry `exception` into `TranscriptDelegated` and `SubagentDeliveredEvent` — two of the three places this status lives. The third is the one no test covers.
**It does not crash today**, and I want to be exact about that: `SubscriptionEmitter.emit` pushes a raw dict with no validation, and the page reads only the fields it knows. But the contract test's own docstring says what the cost is — *"both sides declare `additionalProperties: false` / `extra="forbid"`, so a consumer validating against the schema rejects the whole event, not just the unknown field"*. Losing this event loses the boundary that advances the workspace turn counter and draws the delegated row.
## What this does
- `TurnStartedEvent` joins the `TurnEvent` union, in `openrpc.json` and in `raven/rpc/models.py`, so the existing sweep covers it from now on.
- The schema's `delegated.status` gains `exception`; `node_id` is declared.
- `TurnStartedPayload` gains `delegated` as a typed model (`TurnStartedDelegated`), three-valued status included.
- Both generated TypeScript clients regenerated.
- A new test drives **the exact marker `manager.py` builds** through both validators, so the next status or field fails here instead of in a client nobody is watching.
## One thing the union surfaced
`ui-tui` never handled `turn.started`. Its exhaustiveness check said so the moment the variant existed. It draws the delegated row from `subagent.delivered`, which the page deliberately ignores in favour of this event — the two mark different moments: **submitted** versus **started**.
Left as it is, with an explicit `case 'turn.started'` saying why. Moving that surface onto the truer moment changes when the TUI draws the row, which is a product change, not a contract fix.
## Verification
- New test red before the fix, by construction: adding the variant to the union alone reds `test_schema_match_turn_event_discriminated_union` and `..._payload_fields` (schema/pydantic drift), which is how the gap was proved.
- Mutation checks, each reverting one thing:
| reverted | reds |
|---|---|
| `exception` out of the schema enum | 1 |
| `node_id` out of the schema | 1 |
| `delegated` off the Pydantic payload | 2 |
- `uv run pytest -q` — **12900 passed**, 50 skipped, 5 failed; the same five pre-existing on `origin/main` (four `test_security_network.py` NAT64 cases, one `test_doctor_answers_where_the_memories_are`), reproduced on an untouched merge-base worktree.
- `uv run ruff check` / `ruff format --check` on `raven tests scripts` — both clean (both halves of `make lint-python`).
- `ui`: `gen:check` 147 methods, `type-check` clean, `npx vitest run` 89 files / **1225 passed**.
- `ui-tui`: `type-check` clean, `lint:rpc` in sync, `lint:i18n` up to date, `npm test` 138 files / **1990 passed**.
- Worth recording: with `ui-tui/node_modules` symlinked from another checkout the suite reports 82 failed / 59 failed — and reports **the same numbers on an untouched `origin/main`**. It is the symlink, not the branch. Ran `npm ci` in the worktree to get a trustworthy number.
- `scripts/commit_lint` — no errors.
- `git ls-files | grep -c node_modules` — 0.
## Type
- [x] Fix
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear
Widening a contract to match what the runtime already emits: every payload valid before is valid now. No emit site changes, no behaviour changes. The one code change outside the schema and the models is an explicit no-op branch in `ui-tui`. Rollback is a revert.
## Summary
Unit tests were leaking tracing spans into the real `~/.raven/traces`
store. Tracing is on by default and `trace.span()` calls are embedded in
library code (agent loop, subagents, TUI RPC), so any test exercising
those paths emitted spans with fabricated session keys (`session-a`,
`weixin:c`, `tui:default`, ...). Those spans then surfaced as phantom
sessions in `raven trajectory`, while the TUI `/sessions` list (which
reads the real session store) stayed clean.
This PR adds an autouse fixture in `tests/conftest.py` that:
- redirects `RAVEN_TRACING_DIR` to a per-test tmp directory, and
- resets the lazy module-level `TraceStore` cache
(`raven.tracing.spans._store`) around each test, since it pins the
directory resolved at first emit.
Key decisions:
- Only the directory is redirected, not the enabled switch, so the suite
keeps exercising the real emission path with zero behavior change; leaks
land in tmp instead.
- This centralizes the setenv-plus-cache-reset pattern that 8
tracing/trajectory test files already perform manually. Those tests keep
working: their own `monkeypatch.setenv` runs after the fixture and wins,
and they already reset the cache themselves.
- Existing phantom sessions come from archived span logs written before
this fix; the fixture only prevents new leaks. One archive file mixes a
real session with test keys, so cleanup needs line-level filtering and
is left out of scope.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Test-suite hygiene (`test` commit type).
## Verification
- `uv run pytest tests/test_tracing_api.py
tests/test_trajectory_store.py tests/test_trajectory_bundle.py
tests/test_trajectory_replay.py tests/test_trajectory_redact.py
tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py -q`: 308 passed, 1 failed
(`test_viewer_health_true_for_our_viewer`, fails identically on
unmodified `main`, environment-specific)
- `uv run pytest tests/test_agent_loop_run_emit.py
tests/test_subagent_manager.py tests/test_tui_rpc_turn_send.py
tests/test_deep_research_tool.py tests/test_agent_loop_approval.py -q`:
109 passed; the real `~/.raven/traces` log did not grow during the run
- Positive check: running `tests/test_agent_loop_run_emit.py` with
`--basetemp` shows the previously leaked session keys (`cli:c`, `tg:c`,
`weixin:c`) now land in per-test tmp dirs
- `uv run pytest tests/ --ignore=tests/integration -q`: 6837 passed, 11
failed, 20 errors; the same failure set reproduces on unmodified `main`
(environment-specific: cron/tz, everos server, theme, config loader,
viewer health), zero regressions from this change
- `uv run ruff check tests/conftest.py` and `uv run ruff format --check
tests/conftest.py`: both pass
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Docs box left blank: test-only change, no user-facing docs affected.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Test-only change; no production code touched. One known interaction:
`RAVEN_TRACING_DIR` takes precedence over `RAVEN_HOME`, so a future test
that fakes `RAVEN_HOME` and expects traces under it must also set
`RAVEN_TRACING_DIR` itself. Rollback: revert the single commit.
## Related Issues
N/A
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
A delivered artifact could not be opened from the page: the file viewer answered
403 and the transcript drew "Raven is confined to the workspace, so this file
cannot be opened here" over a delivery card it had just rendered.
The viewer's state-directory fence exempts the workspace subtree, on the stated
grounds that the default workspace lives inside raven's home and denying it
would refuse every file the agent itself wrote. Since agent home and the working
directory were split apart, a turn no longer writes there: it writes in
`~/.raven/tmp/<channel>`, a sibling of the workspace, inside the same state root
and outside the carve-out. So the fence denied exactly what the carve-out exists
to allow, one directory over, for every artifact produced since that split.
This exempts the working-directory root alongside the workspace, using the same
containment test in the same direction, so a working-directory root that happens
to sit above raven's home earns no exemption. `config.json`, `oauth/` and
`serve.json` are siblings of both and stay refused, which is what the fence is
for.
Worth noting for a reviewer: the bytes were already reachable. `/files/download`
serves a delivered file by token with no path fence, so this was never a
security boundary for deliveries -- only a viewer that refused to render what
the same page could already download.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_rpc_transport.py tests/test_rpc_files.py tests/test_rpc_knowledge.py tests/test_rpc_console.py -q` -> 123 passed
- `uv run ruff check` and `uv run ruff format --check` on both changed files -> clean
- Both new assertions were mutation-checked, each against its own mutation:
- narrowing the carve-out back to the workspace alone reds
`test_the_turn_working_directory_is_exempt_from_the_state_dir_fence` only (1 failed, 3 passed)
- dropping the containment-direction guard reds
`test_a_working_directory_root_that_contains_the_state_root_earns_no_exemption`
and the pre-existing state-dir test (2 failed, 2 passed)
- Against the real reporting case: the two files that were answering 403
(`~/.raven/tmp/tui/*.md`, `*.pptx`) now resolve, while `~/.raven/config.json`
and `~/.raven/serve.json` still raise PermissionError.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- Widens what the file viewer will render by exactly one subtree: the directory
turns work in. Everything the fence was written to protect (provider keys in
`config.json`, the OAuth token store, `serve.json`) sits beside that subtree,
not inside it, and stays refused -- pinned by the tests above.
- `fs.list` / `fs.reveal` share the function but pass the session's working
directory as the root, which their own containment check already bounds, so
their behaviour is unchanged.
- Rollback is a one-line revert of the exemption tuple.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
PR #360 reports every copy-on-select write as a permanent transcript
line, so a
reading session that drags through the transcript piles up "copied N
characters" rows under the conversation. The confirmation splits by what
the
line is for: the unbounded terse repeats become a transient notice
rendered
above the input box -- one line that replaces itself on every new copy
and
clears after 3 seconds -- while the first copy of a session keeps its
path
caveat in the transcript. The caveat is the answer a user comes looking
for
after a paste comes up empty minutes later, and it cannot pile up
because it
is once per session by construction.
The reporter still owns the per-session caveat tally and now returns
`{ text, firstOfSession }` so the caller can route the caveat to the
transcript and the repeats to the notice. A new `copyNoticeStore` holds
the
single notice; `showCopyNotice` keeps one dismiss timer, clearing any
pending
one before arming the next, so an earlier deadline can never clear a
newer
notice. `/copy` is deliberately untouched: an explicit command's answer
still
belongs in the transcript, and it cannot stack on its own.
## Type
- [x] Fix
## Verification
Run from `ui-tui/` at branch head, in a fresh worktree of `github/main`.
Dependencies came from `npm ci` in `ui-tui/` and in the hermes package;
the
hermes package's own `node_modules` holds only esbuild, so the ink
render
tests run against one react copy (two copies break every hook call).
```
npx vitest run --no-file-parallelism
Test Files 93 passed (93)
Tests 1084 passed | 13 skipped (1097)
npm run type-check
clean, exit 0
npm run lint
22 problems (0 errors, 22 warnings)
npx prettier --check src/app/copyNoticeStore.ts src/__tests__/copyNotice.test.tsx
src/__tests__/clipboard.test.ts src/app/useMainApp.ts
src/components/appLayout.tsx src/lib/clipboard.ts
All matched files use Prettier code style!
python3 -m scripts.check_commit_messages github/main..HEAD
exit 0
```
The 22 lint warnings are the baseline, not new: 22 before the branch and
22
after, none in a file this branch touches. The suite is run with
`--no-file-parallelism` deliberately: the ink render tests fail under
default
worker parallelism at this suite size, and no CI job runs them.
Suites that exercise the changed code directly:
`src/__tests__/copyNotice.test.tsx`
(7 cases), `src/__tests__/clipboard.test.ts` (30 cases, the 3 reporter
cases
updated to the new return shape).
New tests were proved load-bearing rather than assumed:
- Removing the notice render line in `appLayout.tsx` makes the render
test
fail (content and placement above the input box).
- Removing the pending-timer clear in `showCopyNotice` makes the
re-shown-notice test fail: the earlier 3s deadline then clears the newer
notice.
- The dismissed-notice case now shows a notice first, and removing
`dismissCopyNotice`'s atom clear turns it red (review fix).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No doc change. `ui-tui/CONTEXT.md` has no clipboard or selection entry,
and
"copy notice" continues the existing "notice" vocabulary of
`copyResultNotice`
/ `copyOnSelectNotice`, so nothing new is coined.
## Risk
Behaviour change: the per-drag copy confirmation is now transient and
above
the input box instead of a permanent transcript line, and the first copy
of a
session lands one transcript line, exactly as on `main`. Reverting the
branch
restores the #360 behaviour; no data or on-disk format is involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (deepseek-v4-pro) <noreply@anthropic.com>
## Summary
Six defects a review pass over the served page turned up, plus the registry read
underneath one of them.
**The delivery card was measured rather than stated.** A width-derived capacity
hook decided how many tiles fit and whether a description was drawn, so one card
was four different cards across six widths. The cap is a stated count now, the
description always shows, and a tile keeps one preview ratio with a max-height
instead of a growing box. Measured after: a single card is 142px at every width
with a description and 134px without, and a grid preview is a constant 198x124.
The preview itself lost its inset white sheet -- content fills the tile.
**A desk pane re-opened itself.** Clicking a row whose pane was already up
replaced the pane object, re-tiled the grid and re-revealed the workspace to
arrive at exactly the screen that was already there, and `revealWorkspace` ran a
full workspace draw even when the split was already open. Both are no-ops now;
workspace draws on a re-click went from one to zero, and none of it ever
repainted the pane's content -- that was measured before changing anything.
**A dag node header ran past its panel.** The node id is unbounded -- a playbook
names one `daily-ai-digest-36e275-scan-news` -- and with nothing able to shrink,
the flex row pushed the "open run" link off the right edge, where it read as the
card having been cut in half. Measured before: a 320px panel overflowed by 18px
and a 280px one by 58px. The name gives way now, and only the name.
**The file view's action row was `.acts`**, which the transcript already uses for
an answer's icon strip -- 27x27 square buttons. Two text buttons were squeezed
into those squares and their labels overlapped, which reads as mojibake, not as a
layout bug. Renamed to `.binacts`: the buttons measure 186x30 and 107x30 with no
overlap. Second class collision found in this stylesheet, after `.mini`.
**The floating desk covered the settings dialog.** It sits in its own band below
the takeover layer now, verified with `elementFromPoint` at the palette centre
returning the dialog's own panel.
**The instance registry was read once per process.** `_load` cached its records
for the life of the gateway, while sub-agents register from their own `cli`
processes into the same shared file -- so every instance created after startup
was invisible to the panel until a restart. The decisive test was appending a row
from outside a running server and getting zero back. It reloads on a change in
`(mtime_ns, size)`, stamped from the stat taken *before* the read so a writer
landing between the two is seen on the next call rather than stamped as
already-loaded and skipped forever; `_flush` restamps after its own write, so
writing does not cost a reparse. This also closes a silent data loss: `_flush`
writes the whole cached map back, so flushing from a stale cache dropped every
record another process had added in the meantime.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run at this head, on `da0f0124`:
- `uv run --frozen --all-extras pytest -q` -> `11214 passed, 33 skipped, 13 deselected, 2 warnings in 715.40s`, exit 0
- `npm test --prefix ui` -> `58 passed (58) / 686 passed (686)`
- `make lint-ui` -> `generated.ts matches the contract (132 methods)`, then `tsc --noEmit` with no output
- `uv run --frozen --extra dev ruff check` + `ruff format --check` on the two python files -> `All checks passed!`, `2 files already formatted`
- `PYTHONPATH=. python3 scripts/check_commit_messages.py origin/main..HEAD` -> no output, exit 0
The five registry tests were mutation-checked: disabling the reload reds three of
them, and removing the restamp in `_flush` reds the one that pins "our own write
is not a reason to reparse". The two desk-store tests were checked the same way.
`make lint-python` over the whole repo is not clean at this head, and was not
before this branch: the errors are in `raven/agent/tools/deliver.py`,
`raven/cli/tui_commands.py`, `tests/test_channels_outlet.py` and
`tests/test_mcp_client.py`, none of which appears in this diff.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible behaviour changes, all of them on the served page:
- a delivery card is one height per state instead of one per width, and always
carries its description;
- clicking a desk row whose pane is open no longer redraws anything;
- a dag node's name truncates instead of pushing its run link out of view;
- the desk no longer paints over the settings dialog;
- an instance registered by another process appears without a restart.
Rollback: revert the two commits. Nothing is persisted that a rollback would
strand -- the registry change is read-side only, and the css and tsx changes hold
no state.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Known gap, deliberately not fixed here: a spawn's answer is missing from three
instance logs on my own machine (the spawn's prompt is logged as a `user` row
with no `assistant` row beside it), so opening those instances shows a question
that was never answered. Reproduced on disk, not yet diagnosed, and unrelated to
anything in this diff.
## Related Issues
N/A
`_load` cached the records for the life of the process, so the gateway held
whichever rows existed when it started. Sub-agents register from their own
`cli` processes into the same shared file, which made every instance created
after startup invisible to the panel until a restart -- the decisive test was
appending a row from outside a running server and getting zero back.
Reloaded on a change in (mtime_ns, size), stamped from the stat taken before
the read so a writer landing between the two is seen on the next call rather
than stamped as already-loaded and skipped forever. `_flush` restamps after
its own write, so writing does not cost a reparse on the following call.
This also closes a silent data loss: `_flush` writes the whole cached map
back, so flushing from a stale cache dropped every record another process had
added in the meantime.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Two model-facing control tools for runs the model submitted via `run_subagent_dag`:
- `cancel_dag` -- stops the run (running nodes finish their current step, pending nodes are skipped, nothing is announced) and returns the same per-node view as of the cancellation.
- `dag_status` -- without a run_id lists this conversation's in-flight runs and points at the per-run form; with a run_id renders the run's tallies plus, per node, its summary, subagent, inputs, prompt template (head 10 lines plus the full prompt's path when cut), instance, output file, memory file, and raw timestamps. Missing fields render `(none)`.
Both are registered on the loop but hidden from the provider's tool schema (`ToolRegistry.hide_from_schema`) and from the tool_search catalog. The DAG tool's backgrounded acceptance text is their only advertisement, and only when a call path exists: the fold threshold lives on the `ToolSearchController`, and a single `tool_call_available()` predicate -- read by both the strategy's per-turn assembly and the acceptance text -- decides whether `tool_call` actually ships this turn. No path, no advertisement.
Both tools are conversation-scoped: the listing intersects the loop-wide live set with this conversation's session index, and `cancel_dag` verifies the run resolves under this conversation's run history before signalling the cancel, so one chat's model can neither see nor stop another chat's run (which that chat would never be told about, a cancelled run being silent by design). Reads by id were already session-scoped.
The read path (`_reader.read_run`) now carries `task_summary`, `node_summary`, and `memory_file` for every consumer, the `dag.get` RPC surfaces included. The summary fields come from graph.json and are forward-compatible: runs recorded before the dispatch-task-summary merge read back as `(none)`.
Deliberate decision, kept rather than fixed:
- The tool's description and the orchestration guide skill still say the result "comes to you" and not to poll; the acceptance text is the only place the control tools are advertised, per instruction. Both sentences are left as they are.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
Exact commands and results, at the pushed head:
- `uv run pytest tests/` (via the project venv): 11204 passed, 41 skipped, 13 deselected, 0 failed. The suite was also green at each earlier commit of the branch.
- `ruff check` over the changed files: clean.
- `make lint-python`: the 4 remaining errors are pre-existing on origin/main in files this branch does not touch.
- `scripts/check_commit_messages.py origin/main..HEAD`: clean.
- Functional probe (not committed): a real `SubAgentDagTool` with a real CLI backend ran a two-node graph while the probe asserted the acceptance hint, the in-flight listing, mid-run status with live statuses, cancel with the node block, the post-cancel cancelled/skipped state, the no-in-flight text afterwards, and the refusal of a foreign run id.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No security impact: the new fields are read-only additions and the path joins stay behind the existing run id / node id validation; the control tools refuse anything that does not resolve under the caller's own conversation. Backward compatible: the hidden tools are additive to the registry, the reader fields are additive to the payload, older run dirs show `(none)` for the summary fields, and a deploy without progressive disclosure simply never sees the advertisement. Rollback is reverting the branch; the acceptance text reverts with it.
## Related Issues
N/A
## Summary
Two model-facing control tools for runs the model submitted via `run_subagent_dag`:
- `cancel_dag` -- stops the run (running nodes finish their current step, pending nodes are skipped, nothing is announced) and returns the same per-node view as of the cancellation.
- `dag_status` -- without a run_id lists this conversation's in-flight runs and points at the per-run form; with a run_id renders the run's tallies plus, per node, its summary, subagent, inputs, prompt template (head 10 lines plus the full prompt's path when cut), instance, output file, memory file, and raw timestamps. Missing fields render `(none)`.
Both are registered on the loop but hidden from the provider's tool schema (`ToolRegistry.hide_from_schema`) and from the tool_search catalog. The DAG tool's backgrounded acceptance text is their only advertisement, and only when a call path exists: the fold threshold lives on the `ToolSearchController`, and a single `tool_call_available()` predicate -- read by both the strategy's per-turn assembly and the acceptance text -- decides whether `tool_call` actually ships this turn. No path, no advertisement.
Both tools are conversation-scoped: the listing intersects the loop-wide live set with this conversation's session index, and `cancel_dag` verifies the run resolves under this conversation's run history before signalling the cancel, so one chat's model can neither see nor stop another chat's run (which that chat would never be told about, a cancelled run being silent by design). Reads by id were already session-scoped.
The read path (`_reader.read_run`) now carries `task_summary`, `node_summary`, and `memory_file` for every consumer, the `dag.get` RPC surfaces included. The summary fields come from graph.json and are forward-compatible: runs recorded before the dispatch-task-summary merge read back as `(none)`.
Deliberate decision, kept rather than fixed:
- The tool's description and the orchestration guide skill still say the result "comes to you" and not to poll; the acceptance text is the only place the control tools are advertised, per instruction. Both sentences are left as they are.
## Type
- [x] Feature
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
Exact commands and results, at the pushed head:
- `uv run pytest tests/` (via the project venv): 11204 passed, 41 skipped, 13 deselected, 0 failed. The suite was also green at each earlier commit of the branch.
- `ruff check` over the changed files: clean.
- `make lint-python`: the 4 remaining errors are pre-existing on origin/main in files this branch does not touch.
- `scripts/check_commit_messages.py origin/main..HEAD`: clean.
- Functional probe (not committed): a real `SubAgentDagTool` with a real CLI backend ran a two-node graph while the probe asserted the acceptance hint, the in-flight listing, mid-run status with live statuses, cancel with the node block, the post-cancel cancelled/skipped state, the no-in-flight text afterwards, and the refusal of a foreign run id.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No security impact: the new fields are read-only additions and the path joins stay behind the existing run id / node id validation; the control tools refuse anything that does not resolve under the caller's own conversation. Backward compatible: the hidden tools are additive to the registry, the reader fields are additive to the payload, older run dirs show `(none)` for the summary fields, and a deploy without progressive disclosure simply never sees the advertisement. Rollback is reverting the branch; the acceptance text reverts with it.
## Related Issues
N/A
Picks up fd54c282 so the branch is a descendant of main again. Fast-forward
merge needs that, and the rebase GitLab offers instead would flatten the five
merge commits this branch exists to carry -- v0.1.13 stops being an ancestor the
moment they go, which is the whole point of the sync.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
!267 stopped the tracing panel rebuilding what had not changed. It did not make a
rebuild cheap, and one happens on every append, which with any raven running is
continuously. This makes the reader read shards instead.
The store was already sharded and had been all along: rotation only ever writes
`archive/<date>/`, and the store measured here is 38 files. The reader
concatenated all of them into one document and shipped it. So nothing here
deletes anything or changes what is written -- it changes what is read.
Measured on a real 3.2 GB store, 270,335 span records, 187 sessions:
| | before | after |
|---|---|---|
| opening the panel | 3.4s, 171 MB | 0.045s, 57 KB |
| opening one session | included above | 0.13s, 102 KB |
| API view, last 24h | included above | 0.048s, 774 KB |
| resolving a trace id | scan of every session's traces | 0.017s |
### The constraint that shaped it
A span cannot be attributed to a session by looking at the span. On this store
152,059 of 270,344 records carry no `session.id` at all, and none of the ones
that do is in uuid form; attribution runs through an election over the whole
corpus (`buildSessionIdentityIndex`). A per-file index that recorded "this file
holds session X" would therefore be wrong rather than merely partial: a later
rotation can change the election an earlier attribution depended on.
What the election consumes is not spans, it is counts, and counts aggregate. So a
sidecar records the raw (session.id, session.key) pairs it saw plus local
tallies, and the election runs over the merged tallies. `server.js` builds the
identical tallies from spans in memory and calls the same elector, so the two
readers cannot drift into electing differently. `assembleSession` is shared the
same way, so a session cannot come out different depending on which reader asked.
Tallies are deduplicated by span id per file, matching what `dedupeSpans` does to
the whole corpus -- a re-emitted span carries a later endTime and counting both
skews the election. Per file is exact here because a span id does not straddle a
rotation: measured, all 22,998 duplicates sat inside one file.
### What moved off the whole payload
Three views read across every session and each needed somewhere else to go:
- the sidebar filter matched trace ids out of `session.traces`. Trace ids are
resolved through the index now, which is exact and instant.
- the API view aggregates `llm.call` spans across everything, and a quarter of
all spans is one. `/api/llm-calls` windows it, and applies the window to whole
files first so a file that predates it is never opened.
- jumping between a subagent run and its parent turn scanned every session's
traces. It scans the loaded ones, then asks `/api/trace-owner`.
### Three things the plan got wrong
Recorded in the design doc rather than quietly fixed, because each cost real time
to find:
1. **A list row cannot carry a trace count.** `buildTraceGroups` groups by
parent-child linkage, not by trace id, so the count is the number of spans
whose parent is absent from the session -- not decidable one file at a time. A
test with a parent and child split across two files caught the index saying 2
where the reader said 1. Exactness would mean holding every span id and edge,
about 18 MB of sidecar for this store, parsed per list request. The row
carries an exact span count instead, and the card reads "N spans" until the
session's own response brings the trace count.
2. **Changing the indexing logic needs the schema bumped.** A sidecar is
validated against its log's size and mtime, which say nothing about the code
that wrote it. The first dedupe appeared to do nothing because every sidecar
on disk had been built by the previous version.
3. **A NUL byte reached a source file.** `pairKey` joined ids on a literal NUL,
which made `file` report the source as data and made this shell's `grep`
return silent false negatives on it. Replaced with a serialized key.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest -q tests/integration/test_tracing_viewer_e2e.py -m integration`
-- 14 passed. Six are new and compare the sharded reader against `/api/data`
rather than asserting a shape, since a disagreement is silent and the sharded
answer is the wrong one.
- `uv run pytest -q tests/test_cli_tracing_commands.py tests/test_tracing_api.py
tests/test_tracing_compact.py tests/test_no_otel_tracing.py` -- 86 passed.
- `ruff check` and `ruff format --check` on the test file -- clean.
`make check-large-files` -- clean.
- `/api/data`'s payload was hashed against a frozen copy of the real store before
and after each refactor of shared code, and is byte-identical throughout.
- Eight mutations, each failing exactly one test: reading one file per session,
gutting the election, trusting stale sidecars, keeping unattributed llm calls,
answering 200 for an unknown trace, answering 200 for an unknown session, and
the two from !267 that still apply. Two of these tests initially survived their
mutation and were rewritten -- the election one because every fixture span
carried a `session.id` and resolution short-circuits, the sidecar one because
the fixture only corrupted sidecars, which an earlier check rejects, leaving
the size and mtime path untested.
- Driven in a browser against the real store, because nothing under
`raven/tracing/viewer/` is covered by a lint or type gate: 187 session cards,
a click draws skeletons and then 40 span nodes nested to depth 2 with no
missing fields, the API view returns 291 rows for 24 hours and 7,440 for 7 days
as the window changes, a pasted trace id surfaces exactly its session, and the
console is clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- `/api/data` is unchanged and still served, so a rollback of the page alone is
viable. The tests depend on it, deliberately.
- A list row no longer carries `traceCount`, and the session card reads "N spans"
until a session is opened. This is the one visible change to what the panel
says.
- Sidecars are new files under `logs/index/`. A missing, corrupt, stale or
future-schema sidecar rebuilds rather than being skipped, so the worst case is
slowness, not a session vanishing; there is a test for each of those four
cases. Deleting `logs/index/` is always safe.
- A refresh drops loaded sessions and re-reads only the open one, so a long-lived
tab no longer accumulates every session it visited.
## Related Issues
Found while testing this, pre-existing and NOT addressed: `/api/search` is
synchronous and its result cap only stops a scan that reaches the cap, so a term
too rare to match 200 spans reads every artifact in the store -- 106s for a trace
id against 4s for a common word, on merged main, during which nothing else the
viewer serves can be answered. It wants the search index this work makes
possible, and it is why trace ids are resolved through the index here.
N/A
Picks up raven-ppt's second workflow-refresh sync. Named rather than left as
git's default subject, which the push rule rejects.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Import `subagents/raven-ppt` from `origin/feat/ppt`, and carry the fixes that this
MR's five review rounds produced. Six commits on the branch: the original import, then
one re-sync per review round.
The routing is the key decision. This change is an import, not authored code, so its
correctness proof is byte-equality with the upstream branch -- `git diff
origin/feat/ppt -- subagents/raven-ppt` prints nothing, before and after every fix
round. Patching the vendored copy would have destroyed that proof and forked the tree,
so every finding was fixed upstream on `feat/ppt` first and came back through a re-sync.
The import itself carries three upstream workflow commits `main` never received:
`b2ce11a4` (Route A authoring, rendered-page feedback, template defaults, image search,
figure captions, visual layout checks; removal of the fact gate, design pass now
opt-in), `5e2c33ed` (one rendered page per build call, ten bundled light templates),
`fe12f0ac` (prototype-first content routing, prototype clearing on replan, resuming a
prepared project at `ppt_build`).
`main` added nothing to `subagents/raven-ppt` since the fork point, and nothing in this
range sits outside `subagents/raven-ppt/Raven-PPT/`. The launcher layer is untouched:
`run.py`, `install.py`, `config.json`, `subagent.json` and `README.md` keep the host
key inheritance added earlier.
### What the review rounds changed
Six blocking findings in the first round, three in the second, one in the third, one in
the fourth, one in the fifth -- all reproduced independently before being accepted, and
two further defects found while fixing them. One commit per finding on `feat/ppt`:
| Finding | Fix |
|---|---|
| `section` dropped on load | `39d5f74d` |
| CairoSVG native-library failure | `ef5a88d2` |
| prepare resume path | `1f8a2144` |
| outline checks judged the outline that got persisted | `0d32aed2` |
| redirect SSRF | `8bf46922` |
| revised request resumed past | `f5f10538` |
| fact anchoring rule changed (see Risk) | `357e81ba` |
| contracts still advertised the fact index | `6e7fd826` |
| ppt_outline / ppt_build still promised number enforcement | `cedcc244` |
| author prompts promised it, and the verifier required it | `708d1294` |
| existing workspaces kept it, and sync fills only missing files | `bd22b211` |
| generate_image's own key unargued in the auth guard's allowlist | `a970918e` |
Two findings beyond the filed ones, worth recording for what they reveal:
1. `_resume_payload` read `deck_state` without importing it, so resuming a prepared
deck raised `NameError` rather than returning stale data. The pristine upstream
branch's own `ruff check` already reported it (`F821` at `prepare.py:152`); no test
covered the function. Fixed in `1f8a2144`.
2. The skill-claims verifier carried `ok("check_text" in outline_tool, "the skill says
the outline's numbers are checked and nothing checks them")` -- an assertion written
for precisely the failure it was meant to guard -- and a sibling assertion still
*required* the false wording, so the suite went green by enforcing the lie. The
assertion is inverted rather than deleted in `708d1294`, so re-adding the promise
now fails the verifier (verified: `150 claims checked, 1 failed`).
The same withdrawn guarantee survived five different sweeps by failing each on a
different axis: the spec is written in Chinese (wrong language), the code said `fact
index` where the search said `fact gate` (wrong vocabulary), the behaviour spelled out
where the mechanism name was searched (wrong abstraction level), tool descriptions
enumerated but skills and profile templates omitted (wrong surface), and existing
workspaces never re-read the corrected template at all (wrong time -- backward
compatibility). Each axis is now a check in our review catalog.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run with the vendored checkout's own venv (`uv sync --frozen --extra ppt`), from inside
the checkout so `raven` resolves to the tree under test, confirmed with
`python -c "import raven; print(raven.__file__)"`.
- `python -m pytest tests/ppt tests/test_read_file_image.py tests/test_security_untrusted_context.py tests/test_web_image_harvest.py tests/test_workspace_migration_attention_behaviors.py -q`
-> **1147 passed, 2 skipped** at the pushed head, re-run at each new head (after every
rebase) rather than carried forward.
- Baseline, `origin/main`'s copy of the same tree extracted with `git archive` and run
the same way -> **1099 passed, 2 skipped**. Zero failures on both sides, so **0
introduced failures**; +48 tests, of which 8 are new regression tests from the review
rounds.
- `python tests/ppt/_skill_claims.py` -> `150 claims checked, 0 failed`; restoring the
stale promise produces `150 claims checked, 1 failed`.
- The new tests are not theatre: each was written first and watched fail for its own
reason before the fix existed -- the redirect test with both URLs in the request log;
the `section` test with `'' != 'section divider'`; the libcairo test with the
`OSError` escaping `_sniff`; the resume test with the `NameError`; the ordering test
with the checks judging `(8, 9)` while `(None, None)` was persisted; the verifier with
`1 failed` when the promise was reinstated; the workspace-migration test with the
stale sentence still in the file and the prompt.
- `scripts/check_commit_messages.py origin/main..HEAD` -> exit 0. Commit messages have
0 non-ASCII lines.
- **Full vendored suite, both trees, same interpreter** (the method that surfaced the
sixth-round finding): at the pushed head `pytest tests/ -q` gives `95 failed, 7348
passed, 48 skipped`; on `origin/main`'s subtree copy extracted with `git archive` and
run through the same venv it gives `95 failed, 7305 passed, 48 skipped`. The two
failing-ID sets are **identical** (95 = 95), so 0 failures are introduced by this
range; all 95 are environment-dependent on this box and include the
`test_provider_auth_method` guard, which now passes 42/42 at the head. The reviewer's
environment shows the same picture with fewer environment failures (25, of which 24
reproduced on his baseline).
- Every rebase was proved a pure replay: `git range-diff` shows each commit as `=`, and
the two file sets (`main's` new commits vs the MR range) do not intersect at all.
`git merge-tree --write-tree` is unavailable (needs git 2.38, this box has 2.34.1),
so the overlap check replaces it.
- Runtime wiring: `raven.ppt.tools` exposes 13 modules including the new
`generate_image` and `inspect`; `DEFAULT_TEMPLATES` loads 10 entries and every `path`
resolves on disk.
- Launcher smoke: `run.py --help` parses, the vendored CLI reports `Raven v0.1.12`, and
a live job initialised its workspace, auto-selected a bundled template, rendered
template previews through `soffice` and wrote `prepared.pptx`.
- [x] Relevant tests pass locally
- [ ] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Lint is left unchecked, with a measured reason rather than a claim. The host gate does
not cover this tree (`PYTHON_LINT_TARGETS` is `raven tests scripts`). The tree's own
nested spec mandates ruff, and the pristine upstream branch does not pass it: `ruff
format --check` reports 11 files and `ruff check` reports 4 errors on `origin/feat/ppt`
untouched. This range keeps format at the same 11 (each round formatted only the files
it dirtied; upstream's 11 are left alone rather than reformatted into the diff) and
takes `ruff check` from 4 to 3 by removing the `F821`.
## Risk
Behaviour changes for anyone invoking the raven-ppt subagent: the fact gate no longer
runs, the design pass is opt-in, `ppt_build` returns one rendered page per call instead
of the whole deck, and content pages prefer an editable template prototype.
**Fact anchoring is no longer enforced in code, by decision.** The nested
`raven/ppt/AGENTS.md` listed it among the guarantees that live in the tool execution
path, and the citation gate's own contract explained its narrow scope by asserting that
another gate had already made every number on the page real -- false once the gate was
deleted, and false in a load-bearing place. The maintainer chose to change the rule
rather than restore the gate. `357e81ba` lifts it out of the hard invariants and
drops the property-test requirement that named it; the correction then propagates
through every surface that promised it -- the tool descriptions (`6e7fd826`,
`cedcc244`), the always-loaded authoring skill, the bundled agent profile template and
its verifier (`708d1294`), and finally existing workspaces (`bd22b211`), whose
`agent_memory/profile/agent.md` is migrated sentence-by-sentence so a user's own notes
are never touched. The gap is recorded as an accepted decision with the measured reason
the gate was removed (all-caps ordinary words refused; `A100,480p` read as grouped
thousands, refusing three pages of a live deck). Consequence to be explicit about: a
number that appears in no source material is no longer refused, and the review
demonstrated that shape (material stating `42 million`, outline claiming `999 million`).
**Repo weight.** The ten bundled templates total 50.5 MiB and nine exceed the 1 MiB
limit in AGENTS.md section 7; `scripts/check_large_files.py` reports exactly those nine
and zero blocked-extension hits. Before this commit no tracked file under `subagents/`
exceeded 1 MiB, so there is no precedent. The maintainer approved them before the
commit. There is no reclaim policy; moving template assets out of git is not attempted
here.
**Security.** The redirect SSRF is fixed rather than disclosed: `_extract_images` walks
redirects by hand and puts every `Location` through the same validator as the submitted
URL, reporting a refused hop instead of following it. `_reader_get` was left alone on
purpose -- it only ever requests the fixed `r.jina.ai` host, and HTTPX drops
`Authorization` across origins -- rather than widening the diff into a path nobody
reproduced.
**Known gap, unlabelled: the live end-to-end run has not been repeated.** Before the
review, one full live job timed out at 2400s with no deck, having spent most of its
budget probing the BLOCKING `house_page` gate across six scratch projects. The ordering
defect that plausibly caused that loop is `0d32aed2`, and the nested spec's own
invariant 7 (a tool must not refuse into a dead end) describes the failure precisely.
That fix is unit-verified only; the live job has not been re-run, so this is stated as
unresolved rather than fixed.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Rollback is one revert: the range touches nothing outside
`subagents/raven-ppt/Raven-PPT/`.
## Related Issues
N/A
Four commits landed on main while the review was being answered. Three ui-tui
files conflicted, all on the same feature: main had independently implemented
what upstream's #361 did, as `withoutSpentIntro`, and its version is the better
one -- it counts a slash echo as the user having acted and filters every intro
row rather than only row 0. Taken wholesale.
Taking it wholesale dropped something it had no reason to carry, though, and the
suite caught it: upstream also exports `modelSelectCommand` from that file, which
is what keeps `--default` on a selection made through the picker.
`interfaces.ts` still holds the widened `modelPicker: boolean | 'default'` from
the merge, so without it `/model --default` opened the picker and came back with
a session-scoped switch that read as having changed the default. Grafted onto
main's callback.
One behavioural difference the choice leaves, recorded rather than hidden:
upstream dropped the cover for a transcript opening with an assistant row, and
`userHasActed` does not count one. A resumed session normally carries the user's
own rows too, so it needs a transcript whose user rows are gone -- after a
compaction -- to differ. Main's rule is deliberate about which rows count, so it
stands; the owner of that code should know the case exists.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Measure the gap `!272` disclosed, and close the two real holes it turned out to hide.
`!272` found undefended wiring by making `shell()` and `ds()` return a proxy that no-ops one named member. It also said, in its own description, that the `ds()` half could not see call sites reading `window.DS` directly, and named the four. This measures those four by cutting each call instead. Two were undefended.
**`browser` frame subscription.** `hook()` puts the island's frame handler on the source. Every other test in that file calls `store.onFrame(...)` directly, which is what a pushed frame ends up doing -- but only once the handler is there. Cutting `src.onFrame = onFrame` left every test green while the island went deaf to the live layer: frames arrive and nothing repaints. The new test pins the registration, and the `embedded` guard beside it, since a links-shaped source must not be handed the callback.
**`transcript` path shortening.** An edit's detail header names the file through the workspace source's shortener. This one hid for a subtler reason than a missing assertion: the fixture answered `shortPath` with the identity function, so calling it and skipping it produce the same string, and no assertion could tell them apart. The test gives it something that actually shortens. `edit_file` appears nowhere else in that file, so this is also the first coverage of the diff detail header.
The other two -- `model`'s `installed()` and `subagents`' watch registration -- are defended: cutting them fails 18 and 3 tests respectively.
So the tally across both branches, corrected: **9 real holes, all now closed** -- 3 shell verbs, 4 source members reachable through `ds()`, and these 2 that are not.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Tests only; no production file is touched.
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
On `origin/main` at `076d44e0`:
- `npm run --prefix ui type-check`
- `npm test --prefix ui` (58 files, 684 tests)
- `node ui/scripts/count-shared-globals.mjs` (0 / 0 / 18)
Each test was checked by cutting the call it defends:
| mutation | result |
|---|---|
| `browser/store.ts` `src.onFrame = onFrame` cut | fails |
| `browser/store.ts` guard widened to `if (src)` | fails |
| `TranscriptPage.tsx` `shortOr` bypassed to return the raw path | fails |
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Test-only. Rollback is dropping the branch.
## Related Issues
N/A
Two commits landed on main while this branch was being verified.
`SubagentManager.spawn` renamed `label` to `task_summary`, and the dispatch
label and the snapshotted session binding both belong in the call it made.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Every model-authored dispatch now states, in one user-facing line, what it is dispatching.
- `spawn` gains a required `task_summary` and loses its optional `label` from the tool face.
- `run_subagent_dag` gains a required graph-level `task_summary`, and every node a required `node_summary`.
- `PlaybookSpec` gains its own `task_summary`, coexisting with the `description` it already had. They answer different questions: `description` is matched against to decide whether to run the playbook at all, `task_summary` says what running it dispatches.
Key decisions, all of which shaped the diff:
**The obligation lives on the pydantic models**, not only on the hand-written tool schemas, so one declaration binds the DAG tool, playbook files and playbook generation at once. That is why the diff is wide: `DagNodeSpec` is also a playbook's node model, so ~150 raw node dicts and ~24 model constructions across the test suites gained the new field.
**Validation is deliberately asymmetric.** A node's `node_summary` is `str = ""`, blank-tolerant at parse and refused by `validate_and_order` through `_REQUIRED_NON_BLANK`; the graph-level fields use `min_length=1`. The reason is an existing invariant this repo documents at `_graph.py:24-28`: a playbook may ship a node with a field deliberately left for the model to fill, and `load_playbook` can only report that gap if the file loads. The playbook fill workflow was extended to match, so a blank `nodeSummary` is reported as a gap and closed with `fills` rather than dying at dispatch.
**`label` is renamed at three layers and kept at a fourth.** The tool parameter is deleted; the manager API and the on-disk record meta key become `task_summary`; the wire contract keeps `label`, because `SubagentCall.label` is a required field in `rpc-schema/openrpc.json` and `subagent.label` is a span attribute in `raven/tracing/semconv.py`. Only what fills them changed. Spawn records already on disk are read through a three-level fallback (`task_summary` -> legacy `label` -> first line of the prompt), so no existing row degrades.
**Summaries are display text and never enter a sub-agent's prompt.** `manager.py` still dispatches `prompt=task`, and a node still gets its rendered template.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run at the head after the review-fix round, on the same base (`6fdf1d7b`):
- `uv run pytest -q` -> `10839 passed, 51 skipped, 13 deselected, 1 warning in 329.24s`, exit 0
- `cd ui-tui && npx vitest run src/__tests__/dagStatus.test.ts src/__tests__/dagPanel.test.tsx src/__tests__/dagRun.test.ts` -> `3 passed (3) / 84 passed (84)`
- `cd ui-tui && npx tsc --noEmit -p tsconfig.json` -> exit 0, no output
- `cd ui-tui && npm run lint:rpc` -> `OK: generated.ts in sync`
- `cd ui && npm run gen:check` -> `generated.ts matches the contract (132 methods)`
- `PYTHONPATH=. python3 scripts/check_commit_messages.py origin/main..HEAD` -> no output, exit 0 (all 23 subjects and trailers pass)
The single warning is not this branch's: reproduced at this head with
`uv run pytest tests/test_config_raven_loader.py -q`, it is a `DeprecationWarning` raised deliberately by `raven/config/raven.py:1399` about the retired `skill_forge.mass_library_db` field.
This worktree symlinks `ui-tui/node_modules` to the main checkout, so the type-check was proved to have read this worktree's own files rather than another copy:
`npx tsc --noEmit -p tsconfig.json --listFiles | grep -E "dagStatus|dagPanel|dagRun"` returns three paths, all under `.claude/worktrees/feat+dispatch_task_summary/`.
The branch was rebased three times as `main` moved under it. The first rebase (onto `7d239509`) was verified as a pure replay with `git range-diff`: 14 of 15 commits report `=`, and the one marked `!` (the TUI commit) differs only in context -- its own changed line is byte-identical on both sides. The second rebase (onto `6fdf1d7b`) resolved two modify/delete conflicts by letting the deletion win: `main` deleted the packaged builtin playbooks, which this branch had edited to add the new fields, so those edits were dropped. Its `git range-diff` reports 14 of 16 `=` and the same two commits `!` for exactly that reason. The third rebase (onto `01d39e58`, a `ui/`-only frontend fix) has zero file overlap and replays all 24 commits as pure `=`.
One more change landed in the review round: `docs/specs/playbook-spec.md` was translated from Chinese to English (`77ea8fde`) under the project ruling that no file or code may carry Chinese. Structure is 1:1 (430 lines in, 430 out) and ASCII-verified; the semantic hotspots were re-checked after translation.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
`make lint-python` fails at this head with 3 `I001`/unused-import errors, in `raven/agent/tools/deliver.py`, `tests/test_channels_outlet.py` and `tests/test_mcp_client.py`. None of those files appears in `git diff --name-only origin/main...HEAD`; the first two predate this branch and the last was introduced by `3d3c8713`, a commit on an earlier base. They are inherited, not this branch's (one further inherited error was fixed by `6fdf1d7b` on `main` between the two rebases). Its own files are clean under `ruff check` and `ruff format --check`.
## Risk
User-visible behaviour changes:
- The `spawn` tool no longer accepts `label`; it requires `task_summary`. A caller passing the old name is rejected by the schema.
- A stored playbook that predates `taskSummary` loads with its summary backfilled from its `description` in the legacy migration (`store.py`); the field stays required everywhere new content is produced (the generation schema, the executor, the docs). A dag-mode node without `nodeSummary` loads and reports the blank as a fillable gap rather than dying at dispatch.
- Sub-agent rows in the TUI and the panel's dag rows are now named by the summary rather than by a guess taken from the first line of the prompt template. The heuristic remains as the fallback for runs that predate the field.
Rollback: revert the range. Nothing is persisted that a rollback would strand -- `graph.json` and the spawn record meta gain a key that older readers ignore, and both wire additions are optional fields absent from every `required` list.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Known gaps, deliberately not fixed here:
- The graph-level `task_summary` is write-only today. `SubAgentDagSpec.task_summary` is persisted into `graph.json` and read by nobody, and `PlaybookSpec.task_summary` dead-ends into it; only spawn's summary reaches handles, rows, records and announcements. The model is therefore obliged to write a line on every graph dispatch that no surface shows yet. Giving it a display is a separate change; `CONTEXT.md`'s entry states the current reality rather than the intent.
- Fixture summaries in `tests/test_subagent_dag_runner.py` restate the node id ("node a") for 34 of ~146 nodes rather than describing the node. Fixtures only, never asserted on.
- No regression test pins `SpawnTool.parameters` itself -- its required list, property order, `minLength` and description text. The python signature is pinned twelve ways in `tests/test_subagent_third_party.py`; only the JSON schema is unpinned.
- `_reader.py`'s emit of `node_summary` has no unit test. It is covered end to end by the RPC dag-row tests, which read a real `graph.json`.
- `docs/specs/playbook-spec.md` section 11's field index listed neither summary field and still wrote `agent` for `subagent`, and section 9's example YAML carried the same stale key and neither required field. All fixed here; the example is now a valid complete playbook.
Two rounds of base movement falsified claims in this branch's own design spec, and both were corrected the same way (keep the design intent, correct the current-state claim, re-verify the cited line numbers):
- `7d239509` changed `dagNodeToggleKey` so a dag row is expandable when it has a template **or** has started, where the spec said it still keyed off the template alone. All five `file:line` references in that section had shifted and were updated.
- `6fdf1d7b` deleted the packaged builtin playbooks. Three passages describing them as current were rewritten, and two further `file:line` references corrected (`executor.py:493`, `types.py:155`).
- `6fdf1d7b` also added `test_a_user_playbook_in_the_library_registers_the_loader` with an inline playbook fixture written against the pre-change contract. The required `taskSummary` made it fail at the rebased head (`taskSummary Field required`, reproduced); the fixture was updated to carry the field. A repo sweep of the same pattern found every other inline playbook block already carrying `taskSummary` or on an error path that never reaches the field gate.
## Related Issues
N/A