## Summary
A failed turn's Web row can expand to the provider's full diagnostic
text, up to 8,000 characters, while the existing bounded reason stays
unchanged. The optional `full_detail` field travels through the runner,
lane, RPC event and session marker, so live display and replay expose
the same account. Copy includes the expanded account. Quiet runtime
notices use "Show details" instead of the error label.
Failure details and call-record bodies remove known credential shapes
before the final cap. An unterminated private-key block is removed
through the end of the input, including when an earlier scan or call
record cut away its closing armour. Known cut boundaries also remove
incomplete JWTs, vendor tokens, URL passwords and labelled credential
tails; each of those patterns is searched only from behind the run of
its own value's characters that ends the input and the label in front of
it, so the scan stays linear whatever the text holds and still reads a
label gap of any width. The authorization and JWT patterns avoid
repeated backtracking, and the turn path and outer runner reuse the
computed detail. Attachment and lane reads use the base exception's
instance storage, so a foreign read-only property or throwing getter
cannot replace the scrubbed value or swallow the terminal failure event.
The optional fields are mirrored in the RPC schema and both generated
clients. The design document separates this delivery from the subsequent
Turn Continuation feature; Retry still starts an ordinary turn.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
The automated suites and static/build checks below were re-run after
synchronizing with main, using the existing local dependencies. The
independent behavioral and timing probes were measured before that
synchronization. The last three commits change only
`raven/security/redact.py`, two test files and the design document; on
that final tree the Python suite, the ui-web tests, the type, generation
and lint checks, `ty`, the import contracts, the range gates and
pre-commit were run again, and the ui-web build checks were not, since
none of their inputs changed.
- `uv run --no-sync pytest -q tests/test_agent_loop_failure_text.py
tests/test_llm_call_record.py tests/test_agent_loop_broken_turn.py
tests/test_agent_loop_llm_error_patience.py
tests/test_agent_loop_run_emit.py tests/test_spine_scheduler_lane.py
tests/test_spine_events.py tests/test_rpc_spine.py
tests/test_rpc_schema_match.py tests/test_kernel_budget.py
tests/test_acp_redact.py tests/test_security_untrusted_context.py -x
--tb=short --show-capture=no`: 904 passed.
- From `ui-web`: `npm test -- --no-file-parallelism
src/features/transcript/TranscriptPage.test.tsx
src/state/session/pipeline.events.test.ts
scripts/gates/i18n-keys.test.mjs`: 225 passed.
- From `ui-web`: `npm run type-check`, `npm run gen:check`, `node
../ui-tui/scripts/gen-i18n.mjs --check`, `node
../ui-tui/scripts/gen-rpc-types.mjs --check`, and `node
node_modules/eslint/bin/eslint.js
src/features/transcript/TranscriptPage.tsx
src/features/transcript/TranscriptPage.test.tsx`: passed.
- `uv run --no-sync lint-imports`: 10 contracts kept. `uv run --no-sync
ty check raven evolver agents plugins-dist scripts`: passed. Ruff check
and format check passed on the 20 Python files this PR changes.
- From `ui-web`: `npm run build`, `uv run --no-sync python build.py`,
`node scripts/check-page.mjs`, `node scripts/check-css.mjs`, and `node
scripts/check-class-namespace.mjs`: passed, including both boot
snapshots.
- `UV_NO_SYNC=1 make check-large-files check-source-language
COMMIT_RANGE=origin/main..HEAD`: passed. `PYTHONPATH=. uv run --no-sync
python scripts/check_commit_messages.py origin/main..HEAD`, commitlint
over the same range and `git diff --check origin/main...HEAD`: passed.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref
HEAD`: all applicable hooks passed except the whole-TUI Prettier hook,
which reports `newInstancePicker.tsx` and `subagentsHub.tsx`. Both files
and the formatter config are unchanged from main; an isolated main-file
control with the same locked Prettier version reproduces both failures.
`node ui-tui/node_modules/prettier/bin/prettier.cjs --check
ui-tui/src/i18n/messages.generated.ts`: passed.
- Regression coverage includes truncated private keys, incomplete JWT
and credential tails, terminal-event delivery with foreign exception
attributes, scan reuse and CPU cost, the cut-tail scan's cost on
label-shaped runs and long gaps, its agreement with a whole-text search,
a label gap of any width, the JWT boundary and private-key END rules,
and quiet-notice expansion. The five independent boundary probes passed
before the base synchronization; the committed regression suite above
passed again afterwards.
- On the same 32,267-character synthetic crash input, the queued
event-loop callback delay fell from 15.351 seconds to 0.00951 seconds.
The regression checks use thread CPU time with a 0.5-second ceiling.
- Cut-tail scan: a failed turn whose crash text holds 31,000 spaces
before its last two words took 32.6 seconds while the region came from a
regex search for the last whitespace, and 0.016 seconds now; 64,000
characters of `pwd=` ending in a comma took 10.8 seconds through the
whole-text tail search and 0.003 seconds now, and a 300,000-character
call-record body of either shape takes under 0.3 seconds. These and the
figures below were measured with the machine's load average between 36
and 132. Across 3,728 timed texts, every label or prefix unit repeated
to 64,000 characters behind a cut and to 300,000 past the scan cap, the
slowest measured alone took about 0.2 seconds against about 0.1 seconds
on the base revision, and a text past the cap takes the same time at
twice the size. Searching the whole text again turns six timing cases
red; a smaller name room, a skipped gap or scheme step, or any value
class narrowed below its pattern's turns the property or gap test red,
as does removing the JWT boundary or restoring the END-only private-key
rule. On 12,008 generated texts with gaps up to 5,000 characters, the
output equals the whole-text version's.
- Chromium with synthetic local data: full text retained and HTML
escaped, expanded tooltip removed, internal scrolling and Retry
preserved, neutral notice label displayed, no page errors. No live
vendor call or native Windows rerun is claimed for these fixes.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered: the long text is scrubbed of
recognized credential shapes before persistence and publication. It
remains diagnostic text and may contain hostnames or paths. Model
history and chat-channel replies keep their existing bounded content. A
session export can include the long text. `raven.security.redact` is
also the scrubber for every ACP surface (tool titles, result previews,
permission prompts, replay, error messages) and for the outbound
client's permission log, so two of its rules reach those surfaces too: a
private-key header without END hides the rest of that text, and a JWT
glued to a preceding word character, such as `/verify-eyJ...`, is left
unredacted. Tests pin both.
- [x] Backward compatibility considered: the new fields are optional,
older markers fall back to their bounded reason, and the TUI can ignore
the extra field. Incomplete private-key blocks are conservatively
removed to the end, which can also omit trailing diagnostic text. Custom
runners attach long details in the exception's instance dictionary;
descriptors are ignored.
- [x] Rollback path is clear for risky changes: revert the squash
commit. Older code ignores the optional marker field.
## Related Issues
N/A
---------
Co-authored-by: Codex <noreply@openai.com>
## Summary
Adds `everos-cloud-memory`, a separately distributed memory plugin for
EverOS Cloud, and wires the host so a second memory plugin is a
first-class choice.
The plugin (`plugins-dist/everos-cloud-memory`) is a thin REST client
over httpx: one API key (the config slice
`plugins.config.everos-cloud-memory.api_key`, or
`EVEROS_CLOUD_API_KEY`), owner ids from the host's `ServiceLocator`
(never from the slice), every add in `agent` mode, and a flush only when
a caller marks the conversation over (`metadata.flush` /
`metadata.is_final`: the sub-agent handoff and the importer's final
batch) and once at stop. It ships its own onboard screen (env or on-file
key used without a prompt; 401 / 403 / unreachable get their own
sentences with Re-enter or Skip), `delete` answers False (the cloud
deletes by scope, nothing calls it), and `health()` classifies seven
answers for `raven doctor` and the settings card.
Host changes, each guarded so `memory.backend` `everos` and `null`
behave exactly as before:
- `raven onboard` step 4 asks "Which memory backend?" when more than one
plugin contributes a screen (preselects the current backend, `Off`
clears it, cancel exits 1 and writes nothing); with one plugin the step
is byte-identical to today.
- The memory page reads whichever backend `memory.backend` names: the
cloud slice's key goes out as a Bearer header and the `/health` probe is
skipped for the cloud; a missing distribution is named in the page's
note.
- `settings.everos` reports `reason: "other_backend"` for any non-EverOS
backend, so the Model page hides the three EverOS-only roles (embedding
stays: knowledge bases use that pin); `settings.everosSet` refuses those
three sections for another backend; `settings.set` admits
`plugins.config.<id>.<field>` against the plugin's manifest through the
same admission door channels use; new `settings.everosCloud` feeds the
card (key source, endpoint, health).
- Provider-key and main-model saves no longer restart the local EverOS
when another backend is active.
- ui-web: an EverOS Cloud card (status chip, key row, endpoint) and the
`settings.everosCloud` data behind it. No page mounts the card: it drew
on Model settings until the owner ruled that a memory backend's endpoint
and credential answer neither question that page asks, and where it
belongs is the Memory section's to say once that section has a design.
Until then the key is entered through `raven onboard` or
`EVEROS_CLOUD_API_KEY`. The fixture gate pins the four optional fields
the offline library never sends.
- Gates: the plugin boundary test scans both memory plugins, coverage
and the release workflow build the second wheel, deptry's ignore list
names the plugin beside `raven_everos`, and a conftest fixture keeps the
second plugin out of entry-point discovery for the existing onboarding
tests (they describe a one-plugin install).
A second topic rides along, because it is what makes the hosted backend
reachable from an agent product at all. Every product under `agents/`
pinned its memory at the stock EverOS address and only `raven-design`
read the host's, so the other four addressed whatever answered on 18791
-- the wizard moves a managed server when the port is taken, and a
server the user runs themselves is wherever they put it.
`inherit_memory_backend` in `raven/config/product_render.py` now carries
`memory.backend`, the endpoint, and (only when the product holds none
itself) the credential from the host into every render, beside the host
denials and plugin opt-outs that already travel there; `raven-design`'s
private copy is deleted and the five product configs stop naming an
address. Identity never travels, which is what keeps five products apart
inside one store. `memory.backend: null` travels like any other value,
because that null is how an operator turns long-term memory off and a
product that kept writing would be the one surface ignoring them; the
product's own default stands only when the host carries no key at all.
Which store memories live in is not a product's choice either: the host
reads a sub-agent's memories back through its own backend, so a product
writing anywhere else left that record empty with nothing reporting it.
`owned` is forced off whenever the local backend is in force, because a
product infers ownership from a slice naming no root -- the shape all
five ship -- and so answered a host that was merely not serving by
starting a second server against a root of its own, stranding every
memory written so far.
Decisions worth a reviewer's eye: the fake cloud
(`tests/_everos_cloud_fake.py`) honours or refuses every field the
backend can send and serves both an in-process transport and an HTTP
face for the real-host acceptance; the live tests
(`tests/integration/test_everos_cloud_real_cloud.py`) skip without
`EVEROS_CLOUD_API_KEY`; run with a real key on 2026-10-09 all six pass
against api.evermind.ai (round trip, get by session, empty flush, 401
wording, probe with and without a key, and extraction without a flush
within two minutes), so the documentation and the service agree on
everything the plugin sends. Design, acceptance cases and plan are under
`docs/specs/2026-10-08-everos-cloud-memory-*.md` and `docs/plans/`.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Rebased onto main `182dacac0` on 2026-10-13. What that rebase and the
four commits on top were verified with:
- Full suite, `uv run --frozen --python 3.12 --extra dev pytest -q` ->
**29748 passed, 8 failed** in 4m10s. All eight fail identically with
these four commits' sources reverted in-tree at the same base, so none
of them is this branch's: the two `test_the_products_tool_face_*` cases
in the code and oncall launchers (an extra `web_search` in the visible
tool set), `test_agent_loop_token_budget`,
`test_rpc_files::test_a_host_without_libreoffice_says_so`,
`test_ppt_engine_image_search`, `test_shell_background`, and the two
`test_simulation_*` cases.
- Real-host before and after for the inheritance, driving the launcher
the host spawns (`agents/raven-research/run.py`) against an isolated
`RAVEN_HOME` whose EverOS address is `19701`, not the stock port.
Before: the product rendered `base_url: http://localhost:18791` with no
`owned` key, ignored the host, and started an EverOS of its own -- an
orphaned `everos server start --root <its own state root>/everos`
holding 18791, which is the stranding this change exists to stop. After:
it rendered `{"base_url": "http://localhost:19701", "owned": false}` and
said so itself, "the EverOS you manage is not running at
http://localhost:19701 ... Raven does not start or stop it", with `ps`
and `lsof` confirming nothing was started. On the cloud the product
rendered `memory.backend: everos-cloud` with the host's key and left the
out-of-force local slice untouched, and `raven doctor` over that
rendered config answered `everos-cloud: ok https://api.evermind.ai`, so
the credential reached the service. Identity stayed `raven-research-ng`
throughout, and a fingerprint of the operator's own EverOS root was
identical before and after.
- The first CI round on this head found one that the local gates did
not: `tests/test_import_cycle_budget.py`. `inherit_memory_backend` read
the backend-to-distribution pairing from `raven.core.plugin_stack`, and
that edge from `raven.config` into `raven.core` -- which imports
`raven.config` back -- took mutual pairs from 13 to 14 and packages
inside a cycle from 18 to 22. `make lint-imports` keeps ten contracts
and none of them covers that pair, so it was green throughout. The
pairing now lives in `raven/config/raven.py` beside the two fields it
joins (`MemoryConfig.backend` names a contribution,
`PluginsConfig.config` is keyed by the distribution), which `raven.core`
may import and which imports nothing back; `plugin_stack` re-exports the
two names its own callers read from it. An intermediate commit put it in
`raven.contracts` instead, which broke the cycle but took the papers
ceiling from 3700 to 3719 lines -- `tests/test_kernel_budget.py` says a
new paper is a reviewed change to that ceiling, so it moved again rather
than raising it.
- The review round on this head raised one non-blocking finding, fixed
rather than carried forward: the inheritance read `memory.backend` with
`.get()`, which collapses an explicit `null` into an absent key, so a
host with long-term memory off left every packaged agent on its own
shipped backend and still writing. Reproduced by calling the function
directly before the change and after, now read on presence, and pinned
by a case whose mutation (restoring the `.get()`) turns it and nothing
else red.
- One ordering problem found while checking the above, pre-existing and
not fixed here: `tests/test_rpc_settings.py` run before
`tests/test_cli_onboard_commands.py` leaves
`raven.home._current_config_path` pointing at a dead tmp config, so the
onboard cases write somewhere else. With main's own copies of both files
and main's conftest in the tree it is 57 failures; with this branch's,
19. Which cases turn red changes run to run as xdist distributes them
differently.
- `cd ui-web && npx vitest run` -> 876 files, 3728 passed, 0 failed;
`npm run lint` -> 0 errors (4 warnings, all in files this change does
not touch); `npm run gen:check` -> in sync (228 methods); `npm run
type-check` -> clean; `cd ui-tui && npm run lint:i18n && npm run
lint:rpc` -> in sync
- `make lint-python` / `lint-imports` (10 contracts kept) / `lint-types`
/ `lint-deps` -> all pass; `uv lock --check` -> exit 0 with both sides'
new packages present; `scripts/check_source_language.py` and
`scripts/check_large_files.py` on `github/main..HEAD` -> exit 0;
commitlint over every commit -> ok
- Semantic-conflict audit of the rebase, beyond what the suite answers:
21 of the branch's 66 files are also in main's 499, and every one of
main's changes in them is additive and elsewhere in the file. The one
that could have broken silently is main's new `vision.model` /
`vision.provider` simple keys meeting this branch's new
`plugins.config.<id>.<field>` branch in `settings_set`; nothing in the
suite exercises `vision.*` through that method, so it was run directly
-> `{'applied': True}` and `{"model": "..."}` on disk. The subtraction
decisions were re-checked against the new base: no new caller of a
memory backend's `delete`, main's new onboard cases are about TLS and
not the memory step, `inherit_everos_address` exists nowhere, and
`DEFAULT_EVEROS_BASE_URL` is still defined.
- Mutation runs on the new code, restored afterwards: dropping `owned:
false`, letting the host's credential overwrite the product's own, not
writing the host's backend name, and carrying every memory slice instead
of the one in force each turn their own cases red; making the cloud card
render nothing turns 4 of its 5 new cases red and leaves the fifth
("draws nothing when not selected") green.
From the earlier round, on base `6d509a8c5`:
- `uv run --frozen --python 3.12 --extra dev pytest -p no:cacheprovider
-q tests/test_everos_cloud_fake.py tests/test_everos_cloud_backend.py
tests/test_everos_cloud_backend_contract.py
tests/test_everos_cloud_onboard.py tests/test_everos_cloud_discover.py
tests/test_cli_onboard_commands.py tests/test_rpc_memory.py
tests/test_rpc_settings.py tests/test_plugin_boundary.py
tests/test_rpc_schema_match.py tests/test_rpc_registration.py
tests/test_release_plugin_list.py
tests/integration/test_everos_cloud_real_cloud.py` -> 1001 passed, 6
skipped (the six live tests, no key)
- `cd ui-web && npx vitest run` -> 214 files, 3211 passed; `npm run
lint` -> 0 errors (4 warnings, all in files this change does not touch);
`npm run gen:check` -> in sync (207 methods); `cd ui-tui && npm run
lint:rpc && npm run lint:i18n` -> in sync
- `make lint` (ruff, ruff format, ui tsc, deptry) -> ok; `make
lint-types` -> All checks passed; `make build-ui` -> boot snapshots
match; `scripts/check_large_files.py` and
`scripts/check_source_language.py` on `6d509a8c5..HEAD` -> exit 0;
commitlint and `scripts/check_commit_messages.py` on each commit -> ok
- Mutation runs per change (restored afterwards, `git diff` clean): a
host import of the plugin turns the boundary test red; `import
raven_everos` in the plugin turns the import-isolation test red;
removing the chooser's cancel exit, the Bearer header, the restart
guard, the slice-admission guard, the Roles filter and the fake's two
fixes each turn their own test red
- Real-host acceptance (64 cases,
`docs/specs/2026-10-08-everos-cloud-memory-acceptance.md`) run against a
fake EverOS Cloud: the wizard in tmux (chooser, key typed / from env /
on file, 401 / 403 / unreachable wording, back, Off, Ctrl-C,
non-interactive, base-tree transcript byte-identical with one plugin),
`raven agent` turns (user and agent-track recall, agent-mode adds, 4 s
recall bound, a 300 KB message dropped with a warning, a sub-agent trace
stored under its own ids, flushed and read back, one exit flush per
unflushed session), `raven import run` (3 adds then one flush; a hung
flush retried 4x and the exit sweep defeated), `raven doctor` under
seven cloud conditions (seven sentences, exit 2 only for the five
faults) and with the distribution hidden, and the web page through
playwright-cli (memory page counts and the fake's episode, empty and
refused stores, the Model page hiding the three EverOS-only roles while
the embedding row stays, the cloud card rotating a key and showing the
401 wording, three refused settings.set frames over the gateway
WebSocket, the local everos / null / mem0 backends drawing the page as
before, and a provider-key save that restarts the local EverOS on the
base tree and does not on this branch). Evidence and the per-case
verdicts are kept outside the repo. The live service was reached with a
real key after the acceptance run: six tests, six passes, the service's
replies archived with the evidence.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible changes: the wizard's step 4 chooser (only when two memory
plugins are installed); Model settings hides the three EverOS-only role
rows when `memory.backend` is not `everos`/`null` and draws no cloud
card; the memory page sends a Bearer header for the cloud backend.
Two behaviour changes for agent products, both on the `agents/` lane
only. An agent product now follows the host's `memory.backend` and
endpoint instead of its own, which is a fix for the four products that
never followed the host and a change for `raven-design`, which followed
the endpoint but not the backend. And a product no longer starts an
EverOS server of its own: where it used to answer a host that was not
serving by starting one against an empty root of its own, it now reports
long-term memory as unavailable, which is what the host does. Rollback
for this part is the one commit; the product configs it edits are
shipped files, not user config. The plugin is not installed by default
(its wheel is built by the release workflow; nothing changes for an
install without it). Rollback: revert the squash commit; the config
schema gains no new key (the slice is a plugin slice), so an older raven
reads a config written by this one.
Credentials: the cloud key is written only by `set_plugin_config_fields`
into the plugin's slice; the settings page's key row goes through
`settings.set` with a manifest-declared field, and
`settings.everosCloud` reports `api_key_set` / `key_source`, never the
value.
## Related Issues
N/A
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
A third playbook mode. A `mode: stint` playbook declares roles instead
of nodes, and the driver compiles one sub-agent graph per round, so a
stint is not a sibling of a `dag` run but a layer over it: one fan-out
is one graph, and many rounds are one graph each. Thirty rounds is
thirty graphs on the shared dispatch path, which is what makes the
validation, the dispatch budget, the approval gate and the detached-run
bookkeeping the ones already there rather than a second set.
The stint is a file. Nothing depends on the process that started it
still being alive: a gateway restart, a machine restart, or a `raven
playbook stints resume` all pick it up, and the resume is node-granular,
so a round that died with two roles done re-runs the third.
**One noun, singular and plural.** The mode is `mode: stint`; one run of
such a
playbook is a stint, with its own id, checkout and record; the plural is
the
command family and the RPC namespace. `round` keeps its own meaning as
the unit
inside -- one pass of every role -- and `stage` as one role's turn in
it, so
"the stint is on round 7 of 30" says three different things with three
different
words. The whole surface sits under `raven playbook`: `stints` answers
what has
run on this machine, `stint` acts on one project's layout and the
backlog its
roles share.
**Handover is files, not a conversation.** Every role opens a fresh
conversation each round, which is a decision rather than a limitation:
which instance serves which role changes, processes restart, transcripts
get compacted. What a role learned this round reaches the next one only
by being written down. That makes the journal the contract -- an
append-only file, windowed by recent rounds and by characters, because a
forty-round journal would otherwise fill the prompt it exists to inform.
**The boundary is three layers.** `owns` and `appends` are declared in
the playbook, rendered into the role's prompt from the same declaration
the enforcement reads, measured by the role's own checks, and undone
afterwards with the file the role wrote kept under `violations/`.
Declaring without telling is a trap; telling without undoing is a
suggestion; and the undo reads the stage's own commits as well as the
worktree, because a role that commits a stray write disappears from the
working tree and a boundary any role can step around by committing is
not one. Nothing refuses a write before it lands: a charter narrows a
role's tools only where the playbook declares a `playbook:` block, and
`owns` is not derived into one, so the shipped playbook's roles have no
tool gate and the undo is the boundary rather than its backstop.
Two shapes the boundary cannot hold are refused where they are written
rather than left to surface as violations in round four:
- **Two roles that can run at once where either is enforced.** They
share one checkout, so the first judged is graded against the difference
the whole tree shows and quarantines the other's work. Observed before
it was refused: two roles with disjoint `owns`, each writing only what
it owned, and the first judged came back as `dev-a wrote 1 path(s) it
may not write: src/b/work.py`, with that file gone. The message names
both ways out, because which one is right is the author's call. What
would make it work is a checkout per concurrent role, which is a merge
problem, not a validation rule.
- **`enforce.read: hard`.** It reaches the guard text, which then tells
the role that reads outside its paths are refused at the tool gate, and
no gate refuses one. The wording stays in `rounds_prompt` for whoever
wires the gate; until then the grade is not offered.
**Checks come before any model's opinion.** `verify[]` runs real
commands, and a failure goes back to the role that caused it with the
failure text, up to `maxHandbacks`. When that budget runs out the round
records the failure and carries on rather than failing the node: a
failed node skips every role downstream, and a failed build is exactly
what the reviewer downstream has to see.
**One approval, and it names what it is approving.** The whole stint is
confirmed once, at the start, and the text states the round budget and
every command the stint may run -- a playbook is a distribution unit, so
a file somebody handed you does not get to run shell thirty times on one
unexamined yes. Every round is charged against the hourly dispatch
budget like any graph; a round the budget turns down pauses the stint
rather than failing it, and `stints resume` takes it up once the
allowance recovers. From the CLI the same approval is put to the
terminal, and with no terminal to ask at the run is refused rather than
approved on nobody's behalf.
A stint works a checkout of its own, cut from the project's head, so
hours of its commits do not collide with the conversation that started
it. `stop.maxRounds` defaults to 10 and is capped at 99. `stop.until`
lets a role end a stint early by reporting a marker on a line of its own
-- a whole line, so a role quoting the marker mid-sentence does not end
the plan -- and only a terminal role is told the marker, because a role
that knows how to stop the stint has a reason to reach for it.
**Surfaces.** `raven playbook stints
list/get/extend/pause/stop/resume/sweep/answer`, where `resume` and
`extend` are relayed to the raven serving the page when one is up, so a
round runs in the process that owns the conversation;
`playbooks.stints.*` RPC methods, the read-only ones reading the record
off disk so opening the page does not cost what a dispatch costs; a
Stint tab on the playbook page showing the roles, what each owns, the
checks with their full commands, and what carries between rounds; and a
Runs tab listing every stint with its standing, how far into its budget
it is, each round's checks and what was undone, with pause, stop and
resume.
`raven playbook stint` lays a project out for one. The shipped playbook
is `rounds`: a planner, a builder and a verifier, on any project that
has a specification. `init` writes `.stint/`: a guard file per role, the
shared prose, and a link to the project's own specification, chosen by
two sieves -- the file name first, then how much of the document says
something is required, so an empty `SPEC.md` stub does not send thirty
rounds off a blank page. `task`, `ask` and `confirm` work the backlog
the roles share.
New package `raven/stint/` carries the parts a stint needs that are not
the playbook: the record, its checkout, the ownership grades, the
journal window and the check runner. `CONTEXT.md`, `CHANGELOG.md` and
the two `docs-site` repo-layout tables gain their rows; `README.md` is
not touched.
Three unrelated changes ride along. Two are the same shape -- a web
change that does not show:
- `index.html` went out with no caching header, so browsers fell back to
heuristic freshness and served a rebuilt page from cache without asking,
which reads exactly like a server that never picked the change up.
`no-cache` keeps the entry and revalidates; the ETag still saves the
transfer.
- `make ui` is one target for the two-step page build, because running
only vite leaves the served one-file page unchanged with nothing to say
so.
The third is `raven agent` (`raven/cli/agent_commands.py`):
`--message-file` reads the prompt from a file, `--permission-mode` picks
the tier for the run, and `--no-markdown` prints a soft-wrapped `Text`
rather than a markdown render; 92 lines of tests in
`tests/test_cli_agent_commands.py`.
Designed and deliberately not built, so a reviewer knows where the edges
are: a checkout per concurrent role with each role merging itself in
when it is judged (`docs/plans/2026-09-18-stint-acceptance.md`), and the
backlog-writing round zero. `raven playbook stint confirm` records a
person's word on the plan and nothing in the rounds path reads the flag
yet, which that document also says.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run ruff check --no-cache raven evolver agents plugins-dist tests scripts
uv run ruff format --check --no-cache raven evolver agents plugins-dist tests scripts
uv run lint-imports
make lint-types
make lint-ui
make lint-tui
uv run pytest -q
uv run python scripts/check_commit_messages.py main..HEAD
uv run python scripts/check_source_language.py main..HEAD
uv run python scripts/check_large_files.py main..HEAD
```
Ruff clean over 2,004 files. Import contracts: 10 kept, 0 broken. `ty`
clean, which caught one real defect on the way in: `StintStore.list`
shadowed the builtin for every annotation after it in the class body, so
`-> list[StintRecord]` on it and on `live()` resolved to the method. The
UI gates include the generated-file drift checks (`gen:check`,
`lint:rpc`, `lint:i18n`) and both type-checks; eslint reports 23
warnings and 0 errors, none of them in a file this branch touches. `make
lint-bridge` was not run: this checkout has no `bridge/node_modules`,
and nothing here touches `bridge/`.
Suite: the whole `uv run pytest -q` runs in CI as four shards, and every
shard is green at this head, with the import-cycle budget (44 modules,
the same as `main`), the coverage gate and the three content gates over
the commit range. Locally the suites this branch touches are run per
change; the full run is CI's.
Behaviour, driven rather than asserted:
- A stray write by a concurrent role was reproduced end to end before
the validation refused the shape: `dev-b's own file still there after
dev-a was judged: False`, `violations recorded against dev-a: ['dev-a
wrote 1 path(s) it may not write: src/b/work.py']`.
- The check runner's timeout kills the process group, not just the
direct child. Proved as a regression guard: red with `process.kill()`,
green with the group teardown.
- The round budget refuses rather than wrapping: extending a real stint
past the ceiling answered `that would give it a budget of 104, and 99 is
the most any stint may have`, and the file was not written.
- The spec picker's two sieves, over a real project: `KEPT docs/PRD.md |
weight 12`, `dropped SPEC.md | len 12 | weight 0`, `dropped notes.md |
len 868 | weight 0`.
- Only a terminal role is told the stop marker: `planner=False
builder=False verifier=True` on the shipped example.
- The shipped example is discoverable with no user layer: `listed:
['rounds']`, `origin: builtin`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Additive. `mode: stint` is a new value; `dag` and `prompt` playbooks
load, validate, dispatch and report exactly as before, and the sections
the new mode reads are withheld from the generator's emit schema, so no
generated playbook can reach them. That withholding is pinned by a test
that fails when a section is added to the spec without being added to
the refusal.
Nothing outside the new mode changes behaviour: `spawn` and the DAG path
keep the per-session in-memory dispatch window they have on `main`.
A plan runs shell from `verify[]`. It is gated on the approval, the
approval text lists every command, and a playbook carrying `verify`
cannot be generated -- only written by hand or shipped. The builtin
layer ships exactly one playbook, `rounds`, pinned by name in a test,
for that reason: withheld from the generator and not shipped either, the
mode would be reachable only by transcribing YAML out of prose.
Rollback is a revert of the merge commit. A plan's on-disk record is
under the sub-agent history root and is read by nothing else; nothing
else's on-disk 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: Ethan Wang <ethan.wang@evermind.ai>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
EverOS's four memory roles -- llm, embedding, rerank and multimodal --
lived in
`~/.everos/raven/everos.toml`, a file raven wrote and EverOS read once
at startup.
Three defects followed from that arrangement and none was fixable in
place:
- a model changed on the settings page did not take effect until
something
unrelated restarted the service, with nothing on screen saying so;
- the rerank section needs a request shape (`deepinfra` / `vllm` /
`dashscope`)
that only the wizard's own vendor table knew, so reranking configured
from the
settings page posted to the wrong path against DeepInfra and
SiliconFlow;
- an EverOS root the user manages is read-only to raven, so those users
had no
way to configure a role at all.
raven now records a **pin** per role -- a model and the vendor serving
it, never a
credential -- and resolves the address and key from that vendor at the
moment they
are needed. Rotating a key is one edit, and every role on that vendor
follows.
The values reach EverOS as `EVEROS_*` variables, emitted on every spawn
and bound
into raven's own process so the in-process multimodal tool reads the
same models
the service does. `everos.toml` keeps its runtime knobs, which EverOS
merges per
key; raven writes only `[api]` there now.
**A save applies itself.** The spawn precheck runs before anything is
stopped, so a
restart that cannot succeed leaves the old server serving; a stop that
does not
finish never falls through to the spawn, which would otherwise adopt the
old
server and report success for a configuration that never took. The
outcome
reaches every session waiting on it as `memory.health` -- success
included, since
that frame is the only thing that clears the standing banner.
**Upgrades migrate themselves.** An install upgrading into this still
has its roles
in the file. The migration runs on the first memory start: it names the
vendor
from the address and the key, creates the provider row when raven
carries none,
and leaves a role it cannot name unset with a notice rather than
guessing. It is
idempotent and never edits `everos.toml`. Measured against the real
shape on a
maintainer's machine, where two of the four roles point at DeepInfra, a
vendor
raven carries no provider spec for.
Key decisions, recorded in
`docs/specs/2026-09-21-everos-role-config-design.md`:
- the pin holds no credential, so nothing on the settings wire carries
one in
either direction;
- an operator who exports `EVEROS_<ROLE>__*` still outranks raven, and
the slot
says so rather than accepting a save that would never take effect;
- the rerank request shape comes from the vendor table where it is
known, and is
recorded on the role only for a self-hosted endpoint no table can answer
for;
- the migration is scheduled from the plugin, not from raven's config
migrations,
because the host may know this plugin only through the plugin contract.
Rebased onto `main` after #613, which settles the lint and contract
drift the
branch replay left behind. This branch briefly carried its own partial
fix for
that; it is dropped, and #613's is the one in force.
## Type
- [x] Refactor
## Verification
```
uv run --all-extras pytest -q
# 24517 passed, 4 failed, 111 skipped -- the 4 are pre-existing, confirmed by
# checking out the branch base in the same environment and re-running them there
uv run pytest <the 28 files that reference the changed modules> -q
# 1516 passed, 1 skipped
npm --prefix ui-web test # 2496 passed, 191 files
npm --prefix ui-web run gen:check # generated.ts matches the contract (192 methods)
npm --prefix ui-tui run lint:rpc # in sync
npm --prefix ui-tui run lint:i18n # catalogue up to date
uv run ruff check raven/ plugins-dist/ tests/ # All checks passed
uv run ruff format --check raven/ plugins-dist/ tests/ # 1835 files already formatted
make check-large-files # exit 0
```
A real gateway was started on a fixture built from a maintainer's own
config in
the pre-upgrade shape. The migration moved all four roles, created the
`deepinfra` provider row, resolved reranking to `/v1/inference` rather
than the
chat endpoint, and left `everos.toml` byte-identical (sha256 unchanged).
That run
is also what found the defect described in the next section.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The remaining real-host acceptance cases in
`docs/specs/2026-09-21-everos-role-config-acceptance.md` have not been
run yet;
they are the next step and will be reported on this PR.
## Risk
User-visible changes:
- the four role slots on the settings page now show the vendor as stored
rather
than deriving it from an address, and offer every vendor that can serve
the
role;
- a save restarts the memory service, which takes a few seconds and
reports its
outcome in the standing banner;
- a role whose endpoint comes from exported `EVEROS_*` variables is
read-only,
and so are all four on a root the user manages;
- reranking on a self-hosted endpoint asks for its request shape once.
Rollback: revert the branch. The migration only ever adds to raven's
config and
never edits `everos.toml`, so an install that has migrated still has its
original
file and falls back to it.
One defect worth naming, because it was invisible to every unit test: an
embedding role with no width pinned emitted
`EVEROS_EMBEDDING__DIMENSIONS=""`,
which EverOS's own settings model refuses as an integer -- the server
exited
before serving anything. Fixed, and the case that catches it now builds
EverOS's
real `Settings` from the emitted environment in a subprocess, which is
the layer
that owns the fact.
- [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-opus-5) <noreply@anthropic.com>
## Summary
The settings dialog's Model page answered two questions at once -- which
accounts this install holds, and which model each job runs on -- and it
listed the connected providers only, so the fifty-odd vendors Raven
supports were reachable through a dropdown inside an "add" form and
nowhere else. This splits the page in two, gives every model a kind, and
merges the two model pickers into one.
**Model providers** is a two-column page. The left column is every
provider `model.options` returns (fifty-five on a stock registry,
`hosted_vllm` and `custom` among them) with a search box and six filters
-- connected, direct vendors, aggregators, browser sign-in, local --
connected rows first and each carrying its vendor mark. The right column
is that provider's connection, beside the list rather than paged into.
**Model settings** keeps the roles card alone, and each of its eleven
slots offers its own kind: the embedding slot lists embedding models,
image lists image models, and a chat model appears in neither.
**Adding a model** is a popover under its button. It fetches the
vendor's list, groups a gateway's ids by vendor, counts the kinds
present over the current search result and filters to the one pressed,
and writes one model per click rather than collecting ticks for a
confirming press. An id the vendor does not list is typed into the same
box with a chip saying what kind it is.
**One picker.** `components/ModelPicker` (164 lines, the roles card's)
is deleted; the roles card opens the composer's. What an opening lists
is now an `Offer`: a kind, the providers the caller allows, a title, the
pair it marks, and what a pick means.
### Two decisions worth reading
**The kind narrows each provider's column, never the provider list.** A
tester reported that a provider with a working key but no model list
built vanished from the composer's picker, and the model the chip named
-- set by onboarding, never "added" -- was in no column to be marked. So
a provider with nothing of the offered kind is listed with a count of
zero and a column that says so plus a row to type an id into; and the
model a slot or the conversation currently holds is listed in its
provider's column even when that column does not carry it. Verified on a
real host: with `agents.defaults.model` set to an id absent from
`providers.deepseek.models`, the picker opens on DeepSeek and lists it
first, marked, and writes nothing.
**One classifier, in Python.** `registry_data.kind_of` files a model by
what it writes, and `ModelLabel.kind` carries that answer to the page;
nothing in TypeScript derives a kind from capabilities or modalities.
The one exception is the chip on a typed id, which guesses from the name
-- a translation of `inferred_tags`, with a nine-row table asserted on
both sides so the copy cannot drift.
### Backend
Two read-only, additive fields on `model.options`: `ModelLabel.kind` and
`ModelOptionProvider.gateway` (the registry's `is_gateway`, which no
client can derive from a slug). No new method, no new config key.
Contract first: `openrpc.json`, then pydantic, then the handlers, then
`npm run gen`.
### Not in this change
The three navigation entries the prototype also adds (channels, cron,
memory); the prototype's OAuth pane, which tells the reader to run a CLI
command -- the browser device flow stays; backend enforcement of kinds,
which remains a filter the page applies; the onboarding wizard, which
keeps rendering `providers/Providers.tsx` untouched; the TUI.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Rebased onto `refactor/ui_web_architecture` at 6062b3678 and re-run
after the rebase.
```
uv run pytest tests/test_rpc_model.py tests/test_provider_registry_data.py tests/test_rpc_schema_match.py -q
630 passed in 12.44s
(cd ui-web && npx vitest run)
Test Files 186 passed (186)
Tests 2552 passed (2552)
(cd ui-web && npx tsc --noEmit && npm run gen:check && npm run build && python3 build.py)
generated.ts matches the contract (189 methods)
boot-snapshot: OK (250 nodes match golden)
boot-snapshot: OK (251 nodes match golden)
make check-source-language; make check-large-files; npm run lint:i18n --prefix ui-tui
i18n: generated catalogue is up to date
uv run ruff check raven tests
All checks passed!
```
Mutation checks on the two new backend fields: commenting out the
`"gateway"` line fails `test_options_rows_carry_the_gateway_flag` on
`KeyError: 'gateway'`; commenting out the `"kind"` key fails
`test_model_labels_carry_a_kind` on `KeyError: 'kind'`. Restored, `git
diff` clean.
Driven on a real host (`raven serve` on its own home and port 18899,
real keys for DeepSeek / OpenRouter / Gemini, a real browser):
- Model providers draws 55 rows in two columns of 286px and 462px, the
three connected ones first with a status dot, DeepSeek carrying the
default badge, 54 vendor marks and one lettered tile (`custom`).
- The embedding slot's picker lists all three connected providers with
counts 1 / 0 / 0 and exactly one model. It is at the body, not inside
the dialog, at z-index 46 over the veil's 40.
- The add-model popover against OpenRouter's live catalogue: 534 models,
kind tabs reading all 534 / text 445 / image 52 / embedding 33 / audio
4, five vendor groups, the four seeded models checked. Typing
`my-team/bge-custom` offers it with an "embedding" chip, which is what
`inferred_tags` answers for that name.
- The composer's chip lists the same three providers with OpenRouter
counted 1: its embedding, reranker and image models are not offered for
chat.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Composer users see two changes: embedding and reranker models leave the
model chip's picker, and typing an id there now adds it to the provider
before switching. Settings users learn two navigation entries where
there was one; `settingsTab.id` values written elsewhere still land on a
model page, since the roles page keeps the id `model`.
A model the registry classifies wrongly -- an embedding model with no
`embedding` tag whose name the two patterns miss -- is invisible to the
embedding slot until an overlay states its kind. The add-model popover's
chip is the way to state it.
Rollback: the two wire fields are additive and optional on the reader's
side; the section split is a data change in `SECTIONS`; the deleted
picker is one `git revert` away.
One gate pin moved: `fixture-shape`'s `UNSENT` list loses its six
`model_labels` entries, because the offline fixtures now send them (a
page that filters by kind needs a kind offline too). The gate's own
message asks for exactly this.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rebuilds the web settings dialog on the v0.2 prototype -- eight sections
(general, usage, models, skills, tools, plugins, archive, about) in
place of
the thirteen tabs -- as a `features/settings/` domain in the shape this
branch
gates, and adds the backend the pages need so every control reads a real
value and writes to the real place.
Backend (one commit, one test per method, each checked by a mutation
run):
- `settings.usage` takes `from`/`to` and answers a per-day series;
- `session.list {archived}` and a lazy auto-archive pass inside the list
(`sessions.autoArchiveAfterDays`: one appended record per stale unpinned
session, none on the next list);
- `skills.manage inspect` carries the file list, `always` and the
install
stamp; `skills.manage open` opens a skill file on the gateway host;
RPC-driven installs are stamped `trigger: "rpc"`;
- `model.add_models` (one write for a batch), `model.set_fields`
(address,
Azure deployment and API version, header patches), `model.oauth_login`
(device flow for the page, URL + code); `model.options` gains `key_url`
and
the redacted `extra_headers`;
- `plug.retry`, `plug.revoke`, `plug.configure`;
- `skillForge.blocklist` is read live, so a switch takes effect on the
next
turn; reload-only keys return a `warning` the toast repeats.
Frontend (one commit): the domain files, the prototype's stylesheet
under the
`settings-` prefix in `styles.css`, a shared props-only
`components/ModelPicker`,
`gui.settings.*` in both locales, the old page and its 295 orphan keys
deleted, offline fixtures for the new methods, and gate pins moved with
the
tree (`check-class-namespace` counts, two import pins, the unsent-field
list).
Then a `fix(ui-web)` commit with nine faults only the real host showed
(each
with a test), a `test(*)` commit pinning `toolGroups.json` to the tools
the
loop registers, and a docs commit correcting two on-disk section names
in
the acceptance cases.
Design record, acceptance cases and plan:
`docs/specs/2026-09-17-web-settings-page-design.md`,
`docs/specs/2026-09-17-web-settings-page-acceptance.md`,
`docs/plans/2026-09-17-web-settings-page.md`.
Reviewer notes:
- The base is this refactor branch; the six `fix(...)` commits at the
bottom
are PR #453 (still open against main) and will fall out once it merges.
- A trial merge of this branch with `main` shows three conflicts, none
from
this branch's files except one line: main's #464 rewrote
`raven/skill_hub/hub.py::install` and no longer calls
`write_install_meta`
there, so the `trigger="rpc"` stamp this branch adds collides; take
main's
version and re-add the stamp only if a `write_install_meta` call
remains.
`ui-web/build.py` and `ui-web/src/live/120-settings.js` are this
branch's
base against main, not this PR.
- `tools.media.<kind>` takes the whole `{model, quality}` object and no
null,
so a media role is cleared by writing an empty model; the design said
null.
- The dialog opens on the section the shared slot names (`usage`), as
before;
the prototype opens on general. Left as is: `state/settings.ts` is
shell.
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
Commands run on the rebased branch (base:
`refactor/ui_web_architecture`):
- `cd ui-web && npm run type-check` -- clean.
- `cd ui-web && npx vitest run` -- 175 files, 2536 tests passed, 0
failed,
0 skipped (includes the seven convention gates).
- `cd ui-web && npm run lint` -- 0 errors (7 pre-existing warnings in
other
domains).
- `cd ui-web && npm run build && python3 build.py` -- both boot goldens
unchanged (298 / 285 nodes).
- `uv run pytest tests/test_rpc_model.py tests/test_rpc_schema_match.py
tests/test_settings_tool_groups.py tests/test_rpc_skills.py
tests/test_rpc_settings.py tests/test_rpc_console.py
tests/test_rpc_session.py
tests/test_rpc_plughub.py tests/test_providers_oauth_login.py
tests/test_skill_forge_blocklist_live.py -q` -- 935 passed.
- `scripts/check_source_language.py` and `scripts/check_large_files.py`
over
the branch -- exit 0.
- Real-host acceptance: a temp `RAVEN_HOME`, `raven serve --port 18899`,
the
built page driven by playwright-cli; 46 of the acceptance cases passed
with
every write read back from `config.json` or the session files, 1 partial
(the offline stub page: boots with no console error, the dialog was not
driven), 9 not run (real OAuth accounts, EverOS plugin install, catalog
credential rewrites, three probes needing extra LLM turns). The record
with
commands, jq expectations and snapshots is kept outside the repo.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- New RPCs only add methods and optional fields; existing methods keep
their
shapes (`model.options` gains two optional fields). The settings dialog
is
replaced whole; the previous one had no consumers outside the dialog.
- `skillForge.blocklist` is now read per turn instead of at start; a
switch
in the dialog changes the next turn's skills without a reload.
- Rollback: revert the frontend commit to restore the previous dialog;
the
backend commit can stay, nothing else calls the new methods.
- [x] Security impact considered (the settings whitelist still excludes
the
containment controls; header values and keys are redacted on every read)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
N/A
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Summary
Raven speaks the Agent2Agent protocol, version 1.0, in both directions.
The host
agent is the peer: nothing here makes a sub-agent addressable from
outside, and a
raven launched as a sub-agent refuses to serve the face at all, because
it is
already reached over ACP by the host that started it.
Inbound is an aiohttp face carrying the two cards and a JSON-RPC
endpoint. It
mounts on the gateway when `a2a.server.enabled` is set, and `raven a2a
serve` runs
it standalone for a headless deployment, where running the command is
itself the
opt-in. Outbound is a single tool, `a2a_send`, that takes a card URL and
a message;
it enters the tool list only when `a2a.peers` is non-empty, so a host
with nowhere
to send a message does not carry the schema. The two switches are
deliberately
independent: calling out and being called are separate deployments.
Onboarding mints `a2a.server.token` and stops there. The face ships
closed:
finishing an unrelated install is not consent to open a second network
surface, so
`raven a2a enable` is what opens it, and it is the only writer of that
flag.
Enabling mints a missing token in the same command, because a face
switched on with
an empty token answers every caller with a 401 and reads as a broken
deployment
rather than the closed door it is. `raven a2a disable` closes it again
and keeps the
token, so reopening does not re-issue a credential callers already hold.
The wizard
never writes the flag at all, not even as false, so a repeat onboard
leaves a face
the operator opened by hand alone. A config nobody onboarded, and any
`A2aConfig()`
assembled in process, stays inert.
What that opens is narrower than a network face. The app carrying it
binds loopback
at both call sites, hardcoded rather than read from config, and every
request is
checked against a freshly minted 256-bit bearer token. The minting write
is also
what fixes `config.json` to owner-only, from the temporary file's first
byte rather
than with a chmod afterwards; a later enable or disable adds no secret
material, so
it leaves whatever mode the operator chose. Nothing else narrows that
file and it
already held provider API keys, so the obligation predates this work and
is merely
discharged here.
There are two cards because the protocol splits one description across
two
authentication states. The public card answers an unauthenticated GET,
and has to:
a caller reads it to learn which scheme to authenticate with, so
requiring the
credential first would be circular. It therefore names no installed
agent. The
extended card is a `GetExtendedAgentCard` RPC riding the same bearer
check as every
other method, and is the only one of the two that may say what this host
can
actually do.
On that extended card the sub-agent roster rides
`capabilities.extensions`, not
`skills`. A skill is the protocol's word for something an agent can be
asked to do,
and a peer cannot ask for one named sub-agent: it can only send a
message to this
host, which then decides what to dispatch. One skill per sub-agent would
advertise
call targets that do not exist. What a peer can genuinely request is the
orchestration, so that is a single skill, and the roster moves to the
protocol's
own extension point under a versioned URI. That is the only place a
conformant card
may carry a payload the spec does not define, because `AgentCard` is a
closed set
of fourteen protobuf fields: a custom top-level key is rejected by a
strict parser
and silently dropped by a lenient one. The entry declares `required`
false, so a
reader that has never heard of the URI ignores it and still talks to
this host.
Both cards derive `supportedInterfaces[].url` from the origin the caller
arrived
on. One face answers under every name that routes to it, and a URL fixed
when the
face is mounted is right for at most one of them. This matters more than
it looks:
a caller that finds an interface off the card's own origin must refuse
it, since a
card fetched from a trusted origin would otherwise redirect the
credential
elsewhere, and a relative URL reads as off-origin to that check.
## Type
- [x] Feature
## Verification
- `make test-python` at this head: 23729 passed, 112 skipped, 1 failed,
in 288 s.
The one failure is
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
which fails with the same assertion on `origin/main` by itself; this
branch changes
no install or node file.
- `uv run --frozen --all-extras pytest
tests/integration/test_a2a_protocol_e2e.py -q`:
6 passed. That directory sits outside the default pytest scope, so it is
run by
hand rather than reached by the line above.
- `make lint-imports`: 10 contracts kept, 0 broken. `make lint-types`:
all checks
passed.
- `uv run ruff check raven/ tests/`: clean. `ruff format --check`:
clean.
- `make check-commits` over all 68 commits, `make
check-source-language`,
`make check-large-files`: all exit 0.
- Live, over a real network boundary rather than in process: a raven in
a Docker
container and a raven on the host, each running this branch, called each
other in
both directions. Nineteen assertions per direction covering both cards,
the four
refusal paths, and a completed turn. The container publishes its face on
a
different port than it binds, so the card has to name the port the
caller used and
not the socket the server opened; both cards did, in both directions.
That run
predates the default-off change described above, which touches no file
under
`raven/a2a/` or `raven/a2a_client/`: both packages are byte-identical to
the head
it ran against.
- Reverting each fix turns its own tests red, checked one fix at a time
rather than
all together, including the interface-URL fix mutated out inside the
running
container.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour changes for an operator who runs `raven onboard` after this
lands: a
token is minted into `a2a.server.token`, and `config.json` is narrowed
to
owner-only. No listening face is opened. Opening one takes `raven a2a
enable` and a
gateway restart, so the second network surface only ever exists because
somebody
typed for it.
Rolling an opened face back is `raven a2a disable` and a restart. The
token stays in
place and is never rotated, so callers already holding it keep working
when the face
is reopened, and a later onboard will not reopen it by itself. Nothing
else in the
install changes.
Costs and limits, stated rather than left to be discovered:
- A gateway that serves A2A imports `a2a-sdk`, measured at roughly 570
ms and 391
modules on top of the gateway's own stack, sqlalchemy and the
OpenTelemetry api
among them. It is paid once at mount, not per request, and an operator
who
switches the face off pays none of it. Moving it to the first request is
recorded
as deferred in the design note rather than done here.
- `a2a_send` adds 157 tokens to the tool array of every turn, measured
off a
captured provider call, and only on a host with a peer configured.
- The task store is in memory and unbounded, and inbound concurrency is
not capped.
A local face behind a bearer token is the deployment this is written
for; a
host exposed more widely should bound both first.
- Pulling in `a2a-sdk` brings the OpenTelemetry api into the gateway's
import
graph. This is a trade accepted for the SDK's protocol types and
handler, not an
adoption of OpenTelemetry by this project.
Checked during review and deliberately not fixed here: config validation
accepts an
agent row with an empty or whitespace name, which would reach the
extended card's
roster as an empty entry. It is not introduced by this work, the
previous shape
carried the same value, and closing it belongs with the agent schema
rather than
with the card.
- [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-opus-5) <noreply@anthropic.com>
## Summary
Stands up a bilingual MkDocs site under `docs-site/`, published to
GitHub Pages
by a workflow that builds on every pull request and deploys only from
`main`.
Fourteen topics ship in English and Chinese: the quick start,
self-hosting,
Docker, the WebUI, the sandbox manual, the runtime architecture, the
command
reference, the repository layout, the developer workflow, the
proactivity design
and reference pair, the self-evolution map and the tracing API.
This pull request is additive. Both READMEs keep their prose and gain
one link
to the site in the header row; trimming them is deliberately a second
pull
request, so the site can be confirmed live before anything depends on
it.
Key decisions:
- **`docs-site/`, not `docs/`.** `docs/README.md` defines `docs/` as
design
notes and dated records, and `docs/plans/` is an archive explicitly not
held
to today's layout. A user manual has the opposite lifecycle.
- **Full bilingual parity**, via the `mkdocs-static-i18n` suffix
structure
(`page.md` beside `page.zh.md`). Parity decays immediately without a
guard, so
a test fails when a page has no twin.
- **Anchors are pinned on the Chinese side.** A CJK heading slugifies to
nothing, so Markdown numbers it `_1`, `_2`, and inserting one heading
renumbers every anchor below it, silently breaking links readers already
hold.
Each Chinese heading therefore states the anchor its English twin gets
for
free: 133 heading anchors, identical across the two languages, none
positional.
- **A left rail, not a top bar.** The header carries the brand, the
search box
and the navigation tree down the left; the table of contents on the
right is
one continuous polyline clipped to the headings currently on screen.
- **No template overrides.** Material customises through
`theme.custom_dir` with
Jinja partials, those partials are `.html`, and
`scripts/check_large_files.py`
holds `.html` in `BLOCKED_ASSET_EXTENSIONS`. The skin is therefore one
stylesheet remapping Material's own custom properties, plus one script
for the
table-of-contents rail. The brand mark is a `data:` URI for the same
reason.
- **An owner-signed `docs-site/` exemption zone** in AGENTS.md section
1.3. The
i18n config carries the Chinese navigation labels, and `mkdocs.yml` is
not
`*.md`, so the blanket suffix exemption does not reach it. A contract
test
holds the AGENTS.md list and `EXEMPT_PREFIXES` equal, so both moved
together.
- **The site never links out to a file it does not host.** Documents
that stay
in the repository are named as plain paths rather than linked, and a
guard
fails a page that links to an external webpage or a repository-relative
path.
Two defects found and closed here rather than after publication. The
Chinese
site rendered an English sidebar: navigation labels live in
`mkdocs.yml`, not in
any page, so comparing the two languages' Markdown finds nothing and
only the
rendered output shows it. And a control could be present, sized,
animated and
answer `querySelector` while being unclickable, because a popup Material
sized
for a top bar landed outside the viewport once the header became a rail.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All commands run at the pushed head, rebased onto `origin/main`.
```
make check-large-files exit 0
make check-source-language exit 0
make docs-build exit 0, 0 errors
docs-site/site/index.html and docs-site/site/zh/index.html both present
mkdocs_static_i18n: Translated 17 navigation elements to zh
uv run pytest tests/test_docs_site.py tests/test_source_language_check.py \
tests/test_readme_scope_canon.py tests/test_docker_runtime.py \
tests/test_living_docs.py 44 passed
uv run pytest tests/integration/test_docs_site_controls_e2e.py 13 passed
pre-commit run --files <changed files> all hooks pass
git diff --check clean
```
Anchor parity was measured on the built HTML rather than assumed: 14
page pairs,
133 heading anchors compared at h2 through h6, every one identical
between the
two languages and none positional.
The controls are hit-tested rather than queried.
`document.elementFromPoint` at
the exact point a reader clicks must return the control itself, which is
the
only check that catches an off-viewport popup; the language switcher,
the search
panel, the repository link and the table-of-contents rail each pass it.
The brand lockup is measured, not eyeballed. A failing test was written
first
and reported the wordmark sitting 4.00px below the mark's centre line;
it is
0.00px after the fix, and a 4x screenshot puts the residual optical
offset at
0.25px.
Every guard this branch adds was confirmed to fail first. The
brand-class guard
was mutated from both sides in turn: renaming `.em-eyebrow` in the
stylesheet
turned it red, renaming `class="em-standfirst"` in `index.md` turned it
red, and
it is green again with both restored. The anchor guard was shown to
catch both
failure modes, a missing anchor and a wrong one.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
No behaviour change to any shipped code path. Nothing imports
`docs-site/`, the
new Makefile targets are additive, and the only change outside
`docs-site/` and
its tests is one link added to each README's header row.
Rollback is deleting the branch: the site does not exist until Pages is
enabled
with `Source: GitHub Actions`, and every other change is inert without
it.
Disclosed residue, checked and deliberately not changed:
- The README header now links to `https://evermind-ai.github.io/Raven/`,
which
404s until Pages is enabled. It is the same URL the Documentation
section
already carries.
- The `deploy` job is skipped on pull requests by design, so a green
check here
does not prove deployment works. The first real evidence is the `deploy`
job's
own conclusion on the `main` run after merge.
- GitHub Pages is not enabled on this repository. Measured: `GET
/repos/.../pages`
returns 404. Under `Deploy from a branch` the uploaded artifact is
silently
ignored while the workflow still reports success, so the source must be
set to
`GitHub Actions`.
- `tests/integration/` is excluded by `norecursedirs`, so the browser
suite is a
local guard and never runs in CI.
- The self-hosting page's Makefile target, docker path and port claims
are
unguarded. They were equally unguarded in the README they came from, and
the
owner ruled against adding a guard for them.
- The self-evolution SOP and the benchmark contract stay in the
repository and
are named as plain paths from the pages that reference them. The SOP is
a
translation of an upstream project's internal document and carries
redaction
placeholders, which is a publication decision rather than a formatting
one.
- `docs/plans/` still shows the pre-restyle `mkdocs.yml`. CONTEXT.md
defines that
directory as an archive of the tree as it stood, with an explicit rule
against
updating an old plan to match a later change.
- The Chinese pages drop the brand's italic serif accent word. Cormorant
Garamond
carries no CJK glyphs, so it would fall back to another face without any
sign.
- The code font is Material's default Roboto Mono. The brand names four
typefaces and no monospace, so none was invented for it.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5[1m]) <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
A sub-agent whose whole output budget goes to reasoning returns an empty turn, and nothing
downstream can tell that apart from a run that simply had nothing to say. The observed case
spent sixteen minutes on six generations, each cut at the model's ceiling, with no tool call
and nothing on disk. The node was recorded `completed`, because the turn returned normally,
so the DAG never saw the cuts at all.
This carries that one fact from the run to the thing that judges it.
**Re-measured on the current base, because the target moved under this.** A change landed
meanwhile that attacks the same incident from the other side: the plain-empty retry now asks
a different question each time by lowering the reasoning effort, and a spent ladder ends the
turn as an error naming the budgets it burned rather than as the canned no-answer line. That
covers the lane running the shared agent loop, and on it this branch now adds the typed fact
and the category rather than the only account of what happened.
It does not cover the built-in sub-agent lane, which has no empty-response ladder at all. A
single cut response with no tool call leaves the raw content as the answer; an empty string
is not `None`, so the guard that raises for "nothing to hand back" does not fire, the run
logs that it completed successfully, and the reply is empty with nothing saying why.
Both lanes were re-measured through the real DAG runner on this branch, with the judge stubbed
to pass so the raw status could be read. A node whose run was cut at the ceiling ends
`completed`, `crashed` False, with an empty answer, and carries this fact. So the verdict is
still the only thing that can catch it, and on the built-in lane this fact is the only signal
that anything went wrong.
**Where the fact comes from.** Whichever lane holds it. A run this process hosts reads the
response flag directly, and reports before the no-answer raise so a run that ends with
nothing carries the reason too. A run behind ACP reports it the way the protocol already
provides for: `stopReason: max_tokens`. Raven serving the agent side sends that for a turn
whose generation stopped at the ceiling, refined from `end_turn` only -- `cancelled` and
`refusal` already say why the turn ended and the ceiling does not overwrite them -- and
driving the agent side it reads that value.
Using the protocol's field rather than a private metadata key is what makes the feature
work for agents other than Raven: any conforming agent already reports a ceiling hit this
way. It also keeps the Response Meta boundary intact -- that table is the agent's own
record, which the canonical term says the host decides nothing from.
**Why the session carries it inside a Raven agent.** A turn that spent its budget reasoning
persists no assistant row at all, so the message-seated observer stash has nowhere to land.
The slot is stamped with the index the turn's rows start at, which is how a reader tells this
turn's fact from an earlier one's, and every turn either writes it or clears it. The index
alone would not be enough: it is only monotonic until a history reset or an undo moves it
back, and an old marker could then sit at an index a later turn's own start satisfies -- so
that turn would be reported as cut, which is a wrong fact rather than a missing one. Writing
or clearing on every turn is what makes the slot turn-scoped.
**Why the response flag rather than the finish reason, in-process.** The flag is the union of
two pieces of evidence, and an upstream can answer a ceiling hit with a success claim
instead. One live trace in the investigated session reported `tool_calls` at exactly 16384
output tokens.
**What the judge is told.** The fact reaches both verdict calls -- the ordinary one and the
crashed-node one, since a run can crash because it was cut and naming why is that call's job
-- and `output_limit` joins the verdict categories, so the report the orchestrator
adjudicates on says what happened instead of falling to `other`.
It is stated outside the untrusted fence because it is read off the run's transport rather
than out of the answer the sub-agent composed. It does not claim to be a measurement made
here: for a delegated agent it is that agent's own report of why its turn ended, and the
wording says so, because an unfenced fact an agent can assert about itself is one the judge
should know the source of.
The instruction is deliberately neutral about what arrived. The trigger proves the run was
cut and says nothing about what the task owed, so an instruction presuming a short answer
would mislead on a turn cut after delivering one. It says the cut does not excuse work that
is not there, and leaves the judging to the material.
**Meaning of the signal.** The run's last generation was cut. A round that was cut and then
answered in full does not carry it. It is absent wherever a transport cannot report it --
the OpenAI-compatible agent protocol exposes no finish reason at all -- so absence reads as
"not known to have been cut", never "ran to completion".
**One fix found on the way, and it is the sharper half.** The verdict fail-open exists so an
unavailable judgement cannot fail a node, and it was swallowing `TypeError` from the call
itself. A judge whose signature drifts from the runner therefore marked every node
accomplished -- the verdict system switched off with nothing anywhere failing. Adding the
keyword above reproduced exactly that: the production judge had a strict signature, so a run
reported two nodes completed and zero failed while the traceback was logged. Raising is not
enough, because the raise is caught further out and the node stays `completed`; the node now
fails and says the judge could not be called.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands and results, in a worktree cut from the target branch:
- `uv run --all-extras pytest` -- 20821 passed, 170 skipped, 1 failed.
The one failure is `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
which is inherited and terminal-width dependent, not introduced here. Proven both ways at
the current base: it fails identically there, and it passes on this branch under
`COLUMNS=200`. 0 introduced.
- The touched suites, re-run after the rebase onto the current base -- 842 passed, 0 failed.
The agent loop is touched, so the loop, ACP, verdict, runner, manager, truncation, budget
and living-docs suites were run rather than the changed files alone.
- Node-level attribution measured through the real DAG runner, with a real built-in backend
whose every generation is cut at the ceiling and the judge stubbed to pass: both nodes end
`completed`, `crashed` False, output empty, and both carry the fact to the judge.
- `uv run ruff check raven/ tests/` -- All checks passed.
- `uv run ruff format --check raven/ tests/` -- 1538 files already formatted.
- `uv run python scripts/check_commit_messages.py` over the range -- exit 0.
- `make check-source-language` -- exit 0.
- `uv run --all-extras pytest tests/test_kernel_budget.py` -- 5 passed. This gate caught a
real defect during development: a new constant put the papers tree one line over its
reviewed ceiling, so the constant moved rather than the ceiling being bumped. The switch
to the protocol stop reason later removed that constant entirely.
Each new test was watched failing before the code that satisfies it, including the two
findings from the pre-submit sweep and both review blockers. The stop-reason rework was
driven red first: five tests, covering the refinement, the earlier-turn scoping, the refusal
to overwrite a more specific reason, the client reading the protocol field, and Response
Meta alone never recording the fact.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Behaviour changes a reader should know about.** Three.
A cut reply from a Raven agent behind ACP now carries the `[raven]` notice the client already
appends for any non-`end_turn` stop reason, naming `max_tokens`. That is the documented
purpose of that notice, and it is an improvement here: the original incident's reply said
nothing at all about having been cut. It is new visible text on that path.
A DAG node whose judge cannot be called now fails instead of passing. That is the point of
that fix, and it converts a silent, total loss of the verdict gate into a loud per-node
failure. If a judge implementation outside this repo has a strict signature, its nodes will
fail rather than silently pass; the error text names the cause.
A judged node can now be reported under a new category. Anything switching on the category
set sees one more member; unknown categories already fold to `other` on the read side, so an
older reader degrades rather than breaks.
**Rollback.** Revert the commits; nothing migrates and nothing persists beyond one
per-session metadata key that is overwritten each turn and ignored when absent.
**Deliberately not fixed, with reasons.** The OpenAI-compatible agent backend exposes no
finish reason, so it reports nothing and its nodes keep today's behaviour -- the signal is
either reported or absent, never inferred.
The built-in sub-agent lane treating an empty answer as an answer -- assigning the raw
content, so `""` sails past the `is None` guard written to raise for exactly this -- is a
defect of its own, older than this branch and reachable without it. Naming it here rather
than widening the diff into that loop under a branch about reporting. A host-side heuristic over the transcript shape
was considered and rejected: it cannot separate "hit the ceiling" from "returned empty",
which is the distinction the change exists to make.
**Checked and deliberately not changed.** The archived plan document carries the older
category list; the living-document rule makes it correct about its own date, so the spec was
updated and the plan was left alone.
## Related Issues
N/A
## Summary
A sub-agent whose whole output budget goes to reasoning returns an empty turn, and nothing
downstream can tell that apart from a run that simply had nothing to say. The observed case
spent sixteen minutes on six generations, each cut at the model's ceiling, with no tool call
and nothing on disk. The node was recorded `completed`, because the turn returned normally,
so the DAG never saw the cuts at all.
This carries that one fact from the run to the thing that judges it.
**Re-measured on the current base, because the target moved under this.** A change landed
meanwhile that attacks the same incident from the other side: the plain-empty retry now asks
a different question each time by lowering the reasoning effort, and a spent ladder ends the
turn as an error naming the budgets it burned rather than as the canned no-answer line. That
covers the lane running the shared agent loop, and on it this branch now adds the typed fact
and the category rather than the only account of what happened.
It does not cover the built-in sub-agent lane, which has no empty-response ladder at all. A
single cut response with no tool call leaves the raw content as the answer; an empty string
is not `None`, so the guard that raises for "nothing to hand back" does not fire, the run
logs that it completed successfully, and the reply is empty with nothing saying why.
Both lanes were re-measured through the real DAG runner on this branch, with the judge stubbed
to pass so the raw status could be read. A node whose run was cut at the ceiling ends
`completed`, `crashed` False, with an empty answer, and carries this fact. So the verdict is
still the only thing that can catch it, and on the built-in lane this fact is the only signal
that anything went wrong.
**Where the fact comes from.** Whichever lane holds it. A run this process hosts reads the
response flag directly, and reports before the no-answer raise so a run that ends with
nothing carries the reason too. A run behind ACP reports it the way the protocol already
provides for: `stopReason: max_tokens`. Raven serving the agent side sends that for a turn
whose generation stopped at the ceiling, refined from `end_turn` only -- `cancelled` and
`refusal` already say why the turn ended and the ceiling does not overwrite them -- and
driving the agent side it reads that value.
Using the protocol's field rather than a private metadata key is what makes the feature
work for agents other than Raven: any conforming agent already reports a ceiling hit this
way. It also keeps the Response Meta boundary intact -- that table is the agent's own
record, which the canonical term says the host decides nothing from.
**Why the session carries it inside a Raven agent.** A turn that spent its budget reasoning
persists no assistant row at all, so the message-seated observer stash has nowhere to land.
The slot is stamped with the index the turn's rows start at, which is how a reader tells this
turn's fact from an earlier one's, and every turn either writes it or clears it. The index
alone would not be enough: it is only monotonic until a history reset or an undo moves it
back, and an old marker could then sit at an index a later turn's own start satisfies -- so
that turn would be reported as cut, which is a wrong fact rather than a missing one. Writing
or clearing on every turn is what makes the slot turn-scoped.
**Why the response flag rather than the finish reason, in-process.** The flag is the union of
two pieces of evidence, and an upstream can answer a ceiling hit with a success claim
instead. One live trace in the investigated session reported `tool_calls` at exactly 16384
output tokens.
**What the judge is told.** The fact reaches both verdict calls -- the ordinary one and the
crashed-node one, since a run can crash because it was cut and naming why is that call's job
-- and `output_limit` joins the verdict categories, so the report the orchestrator
adjudicates on says what happened instead of falling to `other`.
It is stated outside the untrusted fence because it is read off the run's transport rather
than out of the answer the sub-agent composed. It does not claim to be a measurement made
here: for a delegated agent it is that agent's own report of why its turn ended, and the
wording says so, because an unfenced fact an agent can assert about itself is one the judge
should know the source of.
The instruction is deliberately neutral about what arrived. The trigger proves the run was
cut and says nothing about what the task owed, so an instruction presuming a short answer
would mislead on a turn cut after delivering one. It says the cut does not excuse work that
is not there, and leaves the judging to the material.
**Meaning of the signal.** The run's last generation was cut. A round that was cut and then
answered in full does not carry it. It is absent wherever a transport cannot report it --
the OpenAI-compatible agent protocol exposes no finish reason at all -- so absence reads as
"not known to have been cut", never "ran to completion".
**One fix found on the way, and it is the sharper half.** The verdict fail-open exists so an
unavailable judgement cannot fail a node, and it was swallowing `TypeError` from the call
itself. A judge whose signature drifts from the runner therefore marked every node
accomplished -- the verdict system switched off with nothing anywhere failing. Adding the
keyword above reproduced exactly that: the production judge had a strict signature, so a run
reported two nodes completed and zero failed while the traceback was logged. Raising is not
enough, because the raise is caught further out and the node stays `completed`; the node now
fails and says the judge could not be called.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands and results, in a worktree cut from the target branch:
- `uv run --all-extras pytest` -- 20821 passed, 170 skipped, 1 failed.
The one failure is `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
which is inherited and terminal-width dependent, not introduced here. Proven both ways at
the current base: it fails identically there, and it passes on this branch under
`COLUMNS=200`. 0 introduced.
- The touched suites, re-run after the rebase onto the current base -- 842 passed, 0 failed.
The agent loop is touched, so the loop, ACP, verdict, runner, manager, truncation, budget
and living-docs suites were run rather than the changed files alone.
- Node-level attribution measured through the real DAG runner, with a real built-in backend
whose every generation is cut at the ceiling and the judge stubbed to pass: both nodes end
`completed`, `crashed` False, output empty, and both carry the fact to the judge.
- `uv run ruff check raven/ tests/` -- All checks passed.
- `uv run ruff format --check raven/ tests/` -- 1538 files already formatted.
- `uv run python scripts/check_commit_messages.py` over the range -- exit 0.
- `make check-source-language` -- exit 0.
- `uv run --all-extras pytest tests/test_kernel_budget.py` -- 5 passed. This gate caught a
real defect during development: a new constant put the papers tree one line over its
reviewed ceiling, so the constant moved rather than the ceiling being bumped. The switch
to the protocol stop reason later removed that constant entirely.
Each new test was watched failing before the code that satisfies it, including the two
findings from the pre-submit sweep and both review blockers. The stop-reason rework was
driven red first: five tests, covering the refinement, the earlier-turn scoping, the refusal
to overwrite a more specific reason, the client reading the protocol field, and Response
Meta alone never recording the fact.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Behaviour changes a reader should know about.** Three.
A cut reply from a Raven agent behind ACP now carries the `[raven]` notice the client already
appends for any non-`end_turn` stop reason, naming `max_tokens`. That is the documented
purpose of that notice, and it is an improvement here: the original incident's reply said
nothing at all about having been cut. It is new visible text on that path.
A DAG node whose judge cannot be called now fails instead of passing. That is the point of
that fix, and it converts a silent, total loss of the verdict gate into a loud per-node
failure. If a judge implementation outside this repo has a strict signature, its nodes will
fail rather than silently pass; the error text names the cause.
A judged node can now be reported under a new category. Anything switching on the category
set sees one more member; unknown categories already fold to `other` on the read side, so an
older reader degrades rather than breaks.
**Rollback.** Revert the commits; nothing migrates and nothing persists beyond one
per-session metadata key that is overwritten each turn and ignored when absent.
**Deliberately not fixed, with reasons.** The OpenAI-compatible agent backend exposes no
finish reason, so it reports nothing and its nodes keep today's behaviour -- the signal is
either reported or absent, never inferred.
The built-in sub-agent lane treating an empty answer as an answer -- assigning the raw
content, so `""` sails past the `is None` guard written to raise for exactly this -- is a
defect of its own, older than this branch and reachable without it. Naming it here rather
than widening the diff into that loop under a branch about reporting. A host-side heuristic over the transcript shape
was considered and rejected: it cannot separate "hit the ceiling" from "returned empty",
which is the distinction the change exists to make.
**Checked and deliberately not changed.** The archived plan document carries the older
category list; the living-document rule makes it correct about its own date, so the spec was
updated and the plan was left alone.
## Related Issues
N/A
## Summary
Empty-Response Recovery now descends the reasoning effort on each retry and FAILs
when no rung is left. That answers two of the three things this branch was opened
for: the retry is no longer the same bytes, and a turn that produces nothing ends
as an error naming the budgets it spent instead of a canned reply that reads as an
answer.
What the descent cannot do is tell the model anything, and it buys nothing at all
where the ceiling went on a payload rather than on thinking: no effort rung shrinks
a write, and a model that does no reasoning is unaffected by the rung it is given.
`Tool.truncation_hint` carries the right advice for that case but rides a refused
tool call, and a turn cut before any call produced none. So a retry after a turn cut
at the ceiling additionally carries `OUTPUT_LIMIT_NUDGE`, once per turn.
Every sentence in it is held to what the trigger proves, which is only that an empty
turn hit the ceiling. Two earlier claims were cut for failing that test:
- "the reasoning alone spent the whole budget" -- true of a reasoning model, false of
one whose answer simply ran long, and the trigger cannot tell them apart.
- an instruction to emit a tool call -- a plain question arrives here too, so the text
now names an answer and a call as equally valid recoveries.
The gate reads `response.truncated` rather than `finish_reason`. That is the field the
contract provides for "stopped at the ceiling", and it says an upstream may claim
success instead. The two agree today, so this changes no behaviour; it stops the
repository holding one fact under two names, an open sibling change having already
chosen the contract's field for the same question.
Three rules, three regression guards, each shown to fail under a mutation of the rule
it holds:
| rule | mutation that breaks it |
|---|---|
| fires only on a turn cut at the ceiling | drop the condition; an uncut empty turn is told it was cut |
| the synthetic assistant sits before the nudge | skip the placeholder; a bare tool-then-user pair reaches the provider |
| said once per turn, not once per retry | ignore the flag; the advice accumulates |
The second is the one worth naming. Driven through a turn with no tool call, nothing
precedes the nudge that could be a tool result, so that assertion passes whether or
not the placeholder is written -- coverage-shaped and empty. It is driven instead with
a tool result last and the post-tool nudge switched off, so RETRY is reached directly
and the mutation is visible.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Regression batch, same selection and interpreter on both sides, baseline taken at this
branch's own merge base:
python -m pytest tests/ -q -p no:randomly --tb=no \
-k "loop or provider or rates or truncation or compaction or budget or overflow or context"
-> base: 2 failed, 3 errors, 3056 passed
-> branch: 2 failed, 3 errors, 3061 passed
The failing and erroring ID sets are identical on both sides, so zero introduced. All
five are ppt-engine tests that do not run from a worktree checkout. The pass count
rises by exactly the five tests this branch adds.
Targeted:
python -m pytest tests/test_agent_loop_empty_recovery.py -q -p no:randomly
-> 53 passed
Each guard was verified by running the mutation of its own rule and watching that test,
and only that test, go red; the tree was restored and re-run green afterwards.
Gates:
ruff check raven/ tests/ -> All checks passed
ruff format --check -> already formatted
scripts/check_commit_messages.py -> exit 0
scripts/check_source_language.py -> exit 0
Not run: the web and TUI suites, which this change does not touch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
A turn that ends empty at the ceiling now sees one extra synthetic user message in the
request that follows. It is marked `_recovery_synthetic`, so the existing
strip-before-persistence step drops it, and a test asserts it reaches neither the
returned messages nor the session record.
The nudge is prompt text and ships as product, so the risk is a model taking the wrong
advice from it. It asks the model to keep the turn short, which is always available;
offers an answer and a tool call as equally valid, so it cannot push an answer-only turn
at a tool; and its batching clause is conditional on there having been a payload too
large to finish.
Rollback is a single revert. No data, schema, config or wire-format changes.
Two things checked and deliberately left:
- A non-thinking empty turn that follows tool calls takes the NUDGE branch and receives
`POST_TOOL_NUDGE`, which does not mention the ceiling. Covering it needs a second
injection site for a narrower shape.
- An open sibling change adds a near-twin of this branch's always-cut provider fixture to
the same test file. Whichever lands second should collapse the two rather than keep both.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Empty-Response Recovery now descends the reasoning effort on each retry and FAILs
when no rung is left. That answers two of the three things this branch was opened
for: the retry is no longer the same bytes, and a turn that produces nothing ends
as an error naming the budgets it spent instead of a canned reply that reads as an
answer.
What the descent cannot do is tell the model anything, and it buys nothing at all
where the ceiling went on a payload rather than on thinking: no effort rung shrinks
a write, and a model that does no reasoning is unaffected by the rung it is given.
`Tool.truncation_hint` carries the right advice for that case but rides a refused
tool call, and a turn cut before any call produced none. So a retry after a turn cut
at the ceiling additionally carries `OUTPUT_LIMIT_NUDGE`, once per turn.
Every sentence in it is held to what the trigger proves, which is only that an empty
turn hit the ceiling. Two earlier claims were cut for failing that test:
- "the reasoning alone spent the whole budget" -- true of a reasoning model, false of
one whose answer simply ran long, and the trigger cannot tell them apart.
- an instruction to emit a tool call -- a plain question arrives here too, so the text
now names an answer and a call as equally valid recoveries.
The gate reads `response.truncated` rather than `finish_reason`. That is the field the
contract provides for "stopped at the ceiling", and it says an upstream may claim
success instead. The two agree today, so this changes no behaviour; it stops the
repository holding one fact under two names, an open sibling change having already
chosen the contract's field for the same question.
Three rules, three regression guards, each shown to fail under a mutation of the rule
it holds:
| rule | mutation that breaks it |
|---|---|
| fires only on a turn cut at the ceiling | drop the condition; an uncut empty turn is told it was cut |
| the synthetic assistant sits before the nudge | skip the placeholder; a bare tool-then-user pair reaches the provider |
| said once per turn, not once per retry | ignore the flag; the advice accumulates |
The second is the one worth naming. Driven through a turn with no tool call, nothing
precedes the nudge that could be a tool result, so that assertion passes whether or
not the placeholder is written -- coverage-shaped and empty. It is driven instead with
a tool result last and the post-tool nudge switched off, so RETRY is reached directly
and the mutation is visible.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Regression batch, same selection and interpreter on both sides, baseline taken at this
branch's own merge base:
python -m pytest tests/ -q -p no:randomly --tb=no \
-k "loop or provider or rates or truncation or compaction or budget or overflow or context"
-> base: 2 failed, 3 errors, 3056 passed
-> branch: 2 failed, 3 errors, 3061 passed
The failing and erroring ID sets are identical on both sides, so zero introduced. All
five are ppt-engine tests that do not run from a worktree checkout. The pass count
rises by exactly the five tests this branch adds.
Targeted:
python -m pytest tests/test_agent_loop_empty_recovery.py -q -p no:randomly
-> 53 passed
Each guard was verified by running the mutation of its own rule and watching that test,
and only that test, go red; the tree was restored and re-run green afterwards.
Gates:
ruff check raven/ tests/ -> All checks passed
ruff format --check -> already formatted
scripts/check_commit_messages.py -> exit 0
scripts/check_source_language.py -> exit 0
Not run: the web and TUI suites, which this change does not touch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
A turn that ends empty at the ceiling now sees one extra synthetic user message in the
request that follows. It is marked `_recovery_synthetic`, so the existing
strip-before-persistence step drops it, and a test asserts it reaches neither the
returned messages nor the session record.
The nudge is prompt text and ships as product, so the risk is a model taking the wrong
advice from it. It asks the model to keep the turn short, which is always available;
offers an answer and a tool call as equally valid, so it cannot push an answer-only turn
at a tool; and its batching clause is conditional on there having been a payload too
large to finish.
Rollback is a single revert. No data, schema, config or wire-format changes.
Two things checked and deliberately left:
- A non-thinking empty turn that follows tool calls takes the NUDGE branch and receives
`POST_TOOL_NUDGE`, which does not mention the ceiling. Covering it needs a second
injection site for a narrower shape.
- An open sibling change adds a near-twin of this branch's always-cut provider fixture to
the same test file. Whichever lands second should collapse the two rather than keep both.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
An agent loop appends one message per turn and re-records the whole conversation each
time. `persist_artifact` deduplicates whole payloads by sha1, which cannot see that turn
N+1 differs from turn N by one appended message, so `llm.input` grew at roughly
4.3 GiB/day on the host this was measured on. Two commits, the second depending on the
first.
**1. Stop restating the message list.** `_llm_input_payload` split the flat list into
three views for the viewer and kept the raw list alongside them, so the same turns were
serialized twice per artifact. `historyMessages` had no reader anywhere in the tree - its
only two mentions were the docstring describing it and the line writing it - because the
viewer stopped using the split and says so at `ui/app.js:1441` while the writer was never
brought along. Over 1,806 recorded artifacts: 8.665 GiB before, 5.007 GiB after, a 42.2%
saving of 3.658 GiB.
**2. Address each message by its content sha1.** `llm.input` is now written as
`audit.artifact.v2`: each message is stored once under
`audit-artifacts/_messages/<sha1[:2]>/<sha1>.json` and the artifact carries a
`{"$msg": sha1}` reference in its place, with `systemPrompt` and `prompt` aliasing their
own element rather than restating its text. On the largest recorded artifact that is
32.906 MiB down to 0.063 MiB. Over a 1,733-artifact snapshot, 106,247 message occurrences
carried 6,454 distinct contents - a 93.9% reuse rate whole-payload addressing cannot
reach.
Key decisions and why:
- **`raven/tracing/artifact_v2.py` is the format's single authority** because the bundled
viewer mirrors it in JavaScript. A cross-language test asserts both resolvers return
byte-identical JSON for one shell. Its fixture carries non-string content deliberately:
Python's default JSON separators carry spaces and JavaScript's do not, so `coerce_text`
pins `separators=(",", ":")` to match `JSON.stringify`.
- **Message blobs sit beside `_blobs/`, never inside it.** `compact` removes any blob in
`_blobs/` whose link count is 1, and a message blob's is permanently 1 because a shell
references it from JSON text rather than by hard link. Inside `_blobs/` the whole corpus
would be swept on the next `raven tracing compact`. The sibling layout is not free,
which the first review round established: `_iter_day_dirs` skipped only `_blobs/`, and
`_messages/<sha1[:2]>/<sha1>.json` has exactly the shape of `<kind>/<day>/<file>`, so
the walk read the message store as an artifact tree. `compact` now names both
content-addressed stores in `_CONTENT_STORES` and walks neither. Its "no referenced
artifact is removed, pure convergence" invariant is untouched; what changed is which
directories it considers artifacts at all.
- **Two resolution points, both at boundaries that already reformat**: `bundle` when
packing a trajectory, and `readArtifact` in the viewer's `server.js`. Consequence:
replay, cassette minimization and the viewer's UI read v1 shapes and needed no change.
Their suites pass unmodified, which the Verification below asserts rather than claims.
- **Key order is preserved, not sorted.** Sorting lets two orderings share a blob, but
resolution then hands back a reordered copy, and the text fields carry that order inside
a serialized string, so the exact round trip - the invariant the design rests on - is
lost. Over 406,357 occurrences, sorting changed the distinct count by zero. The design
document records this as a first choice rejected by implementation, with the numbers.
- **`llm.input.artifact_bytes` now measures the shell**, and `llm.request_bytes` is the
request-size signal. That attribute is `main`'s, not this branch's: an earlier revision
added `llm.input.content_bytes` for the same reason, and the rebase below found `main`
had landed a better-specified measurement of the same fact. See Rebase.
The design document is `docs/specs/2026-09-10-llm-input-message-addressing-design.md` and
the plan `docs/plans/2026-09-10-llm-input-message-addressing.md`. Both carried a claim the
first review falsified - that a sibling directory left `compact` unchanged - and both now
record what review established instead; the plan additionally records why its own green
`test_tracing_compact.py` run was not evidence, that suite having no `_messages/` tree in
any fixture.
**Review round 1** (chandler.zhang, one blocking finding, fixed in `fix(tracing): keep
compact out of the message store`): reproduced independently before fixing - one addressed
message aged past `FRESH_SECONDS` gave `scanned=1`, the message at `st_nlink == 2`, and a
new `_blobs/f3/f3c1153f5fe09fae848cada6617f0ebbada69851.json`; after the fix the same
script reports `scanned=0`, `st_nlink == 1`, no `_blobs` entry. The regression sits in
`test_tracing_compact.py` and was verified load-bearing by restoring the old condition and
watching it redden. A second test pins the stale-tmp half of the same walk, so a future
widening of the exclusion cannot silently start deleting inside the message store.
## Rebase onto `main` at `9c531c232`
Not a pure replay. `main` moved 36 commits and `855d12185 fix(providers): honour the
declared output ceiling` extended the same function this branch rewrites, so three
conflicts were resolved by hand and two of this branch's own claims changed as a result.
**The substantive one: a duplicate fact, resolved in `main`'s favour.** `main` added
`_request_attrs` - `llm.request_bytes`, `llm.request_images`, `llm.request_image_bytes` -
whose docstring gives the same reason this branch had added `llm.input.content_bytes`:
the request's size should be greppable without opening the artifact. Keeping both would
have left one fact under two names with different definitions. `main`'s is the better
one and landed first: it counts `{"messages": ..., "tools": ...}` with the separators an
HTTP client uses rather than messages alone with Python's, streams through `iterencode`
so a 20 MB request is measured without a second copy in memory, and reports decoded
image bytes beside the total. It reads `bound["messages"]` rather than the artifact, so
addressing the messages does not move it. `content_bytes` and its helper are gone.
**`main` also added two keys to the `llm.input` payload**, `request` and `generation`.
They are carried in the shell verbatim. Neither holds message content - three integers
and the parameters the provider resolved - so referencing them would cost an indirection
and save nothing. Measured on the largest real artifact in the local store (1200
messages, 3.45 MiB): the shell is 134.8 KiB without them and 135.0 KiB with, a cost of
192 bytes, 0.005% of the original. The frozen key-set test accepts them explicitly rather
than by widening.
Note that `git merge-tree` reported those two keys as an automatic merge. They collide
semantically, not textually, and only the frozen key-set test surfaced it - which is the
argument for that test existing.
Three smaller consequences, all in this branch's own text:
- The `llm.call` row in `docs/TRACING_STANDARD_API.md` is merged rather than chosen: it
keeps every attribute `main` added and describes `llm.input` as `audit.artifact.v2`.
- `test_llm_call_records_the_resolved_size` became
`test_the_request_size_signal_survives_the_shell`, asserting the relationship
(`llm.request_bytes` carries the conversation, `artifact_bytes` is smaller) rather than
the presence of a now-deleted attribute.
- The first commit's own frozen key set needed the two new keys too. Git's auto-merge
kept that commit's test and `main`'s code, each correct alone and red together; it was
caught by running each commit separately, not the branch head, where the second commit
replaces that test and hides it.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Ran in a worktree whose imports were confirmed to resolve to the worktree, not the main
checkout (`python -c "import raven; print(raven.__file__)"`).
Targeted suites at the rebased head:
```
python -m pytest tests/test_tracing_api.py tests/test_tracing_artifact_v2.py \
tests/test_trajectory_bundle.py tests/test_trajectory_replay.py \
tests/test_trajectory_cassette.py tests/test_trajectory_regressions.py \
tests/test_tracing_compact.py tests/test_living_docs.py \
tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py \
tests/test_agent_loop_truncation_paths.py tests/test_no_otel_tracing.py
-> 258 passed
python -m pytest tests/integration/test_tracing_viewer_e2e.py -m integration -n0
-> 19 passed (spawns the real Node viewer and drives it over HTTP)
lint-imports
-> Contracts: 9 kept, 0 broken
```
At the rebased head those are **288 passed** and **19 passed**, with
`test_context_scent.py` now included (`main` added two cases for its own `CONTEXT.md`
text). Each commit was also run on its own, since a rebase can leave a commit red while
the head is green: **133**, **169**, **171** passed.
Full suite before the rebase: `28 failed, 20325 passed, 140 skipped`. All 28 are
pre-existing, established by A/B rather than inference:
- Zero file overlap between this branch's twelve files and any ppt / office /
`plugins-dist` path.
- The failures name `plugins-dist/ppt-engine/...` under the **main checkout**, which is
where `plugins-dist` is installed editable, so a worktree's engine tests run against
whatever that checkout currently holds.
- Reverting this branch to a pristine tree and re-running the six files that held the
failures gave the same 26. The two the file list did not cover
(`test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
`test_ppt_engine_assembly.py::test_the_image_generator_answers_configured_from_the_live_host_section`)
were run separately on the pristine tree and failed there too.
- `comm -13` over the two sorted failing-ID sets is empty. 0 introduced.
Gates:
```
ruff check raven/ tests/ -> All checks passed
ruff format --check raven/ tests/ -> 1522 files already formatted
scripts/check_commit_messages.py -> exit 0
scripts/check_source_language.py -> exit 0
scripts/check_large_files.py -> exit 0
```
Tests were observed failing before each implementation step. Two were then found unable
to fail and strengthened: the cross-language resolver test was verified by deliberately
diverging the JavaScript side (it named the exact bytes of the multimodal `prompt` field),
and the recorded-round-trip test gained `assert v2.is_v2(payload)`, without which it
passed on v1 payloads that `resolve_payload` returns untouched.
End-to-end on real data: six real recorded conversations of 989-999 messages each, replayed
through `semconv.llm_call`, round-tripped exactly with span attributes present -
23.80 MiB of content behind 729.3 KiB of shells, and every message blob at link count 1.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Format change with a discriminator.** A v1 artifact has no `artifactFormat` key and is
read by the old path, permanently. Existing artifacts are never rewritten: their content
would stop hashing to the name recorded in `artifact_sha1`, which is the integrity check
`_blob_is_intact` enforces.
**Behaviour changes worth naming.** Two rules differ from v1 on purpose, both recorded in
the payload builder's docstring and pinned by tests. The system field takes the first
system message where v1 took the first non-empty one, because a reference has no notion of
emptiness. `messages` is always a list where v1 passed a non-list argument through; the
extractors always hand it a real call's list, so the branch is unreachable in practice.
**Degradation.** A message whose blob cannot be written is inlined in the shell, so one
filesystem failure costs that message its sharing rather than the record. A blob that is
gone becomes a labelled placeholder at its own index - never dropped, because consumers
compare message-list length and position. `cassette.minimize` already refuses a bundle
that is not fully replayable, so a placeholder propagates correctly.
**Blast radius.** A message blob is shared: on the measured corpus each distinct message
was referenced about 16 times, and the system prompt far more. Losing one blob affects
every artifact referencing it, where before it affected one record. This is the cost of
content addressing and was accepted deliberately; the read path does not verify blobs,
matching `readArtifact`'s existing behaviour, and verification belongs to `compact` or a
future verify command.
**Rollback.** Revert both commits. Shells already on disk become unreadable to the
reverted code (it has no resolver), so a rollback after real traffic wants either the
`_messages/` tree kept and shells resolved out of band, or the affected date directories
deleted - `llm.input` artifacts are diagnostics, and `raven trajectory pin` is what marks
the ones that are corpus.
**Security.** A reference's sha1 is rejected unless it is 40 lowercase hex characters
before any path is built from it, on both the Python and the JavaScript side, with a test
per side driving `../../../etc/passwd`. `isSafeArtifactPath` remains the second line. No
new network surface and no credential handling.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Checked and deliberately not fixed
- **No reclaim path for `_messages/`.** The corpus grows about 65 MiB/day against the
4.3 GiB/day it replaces. Its natural trigger is the deletion of a referencing artifact -
the retention tooling `raven/trajectory/store.py` already reserves a place for - and
adding it now would mean teaching `compact` to delete, discarding the invariant this
design was shaped to preserve. Recorded in the design document's non-goals and in
`CONTEXT.md`'s Message Blob entry.
- **Only `llm.input` is addressed.** Every other artifact kind together held 65 MiB in the
same `du` run, under 1% of what `llm.input` held, so no generic chunked-artifact layer
was built. The write API is generic enough to be reused later without a format change.
- **The read path does not verify blob integrity.** `_repair_blob` can restore a torn blob
only because the write path still holds the content; a reader does not, and re-hashing
every message per render is not affordable. `readArtifact` performs no verification
today either.
- **`CONTEXT.md`'s Trajectory Pin promise was widened rather than left alone.** It said
purge tooling must never delete a pinned attempt's spans or the artifacts they reference.
A v2 shell holds no messages of its own, so that promise had silently stopped covering
what a pinned trajectory needs - deleting a message blob destroys it while leaving the
artifact file in place. Now stated explicitly.
- **`artifact_v2.blob_path` was renamed to `message_path`.** `store._blob_path` already
exists for the other store; same name, different store is what a reader cannot
disambiguate.
## Related Issues
N/A
## Summary
An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed!573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.
- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.
What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.
## Review round 1 (2026-09-09, on !600, superseded by this MR)
- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.
## Review round 2 (2026-09-10)
- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.
## Review round 3 (2026-09-10)
- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.
## Review round 4 (2026-09-10)
- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
tests/test_agents_oncall_flow_escalation_tools.py -q # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents # clean
uv run lint-imports # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit # in sync, clean
```
New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).
Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)
## Risk
- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.
A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.
## Related
Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
## Summary
An on-call agent submits a job, arms a wake and ends its turn saying so; the wake runs a later turn on the session on its own clock. Over ACP that turn's `end_turn` read as "finished" to the caller: a DAG judging its node spent every continuation on "still watching, wake at 13:13" while the job ran fine (ar-r4, 2026-09-08), and the main agent re-dispatched the work by hand. ACP has no stop reason for "waiting". Replaces the closed!573: **no DAG code changes**, no new node status. The node is `running` because a turn is genuinely in flight.
- **The signal.** The loop-hooks paper gains one key the ACP layer reads for itself: `acp_meta["raven.holdTurn"]` (`{"untilMs", "why"}`). oncall-flow files it at the send fire when the window's campaign is claimed, not concluded, and has one pending wake -- read the same way the owner's answer pulls that wake forward. No campaign, a wake that stood down, or a concluded campaign files nothing and the turn ends as before.
- **The hold** (`raven/acp/methods.py`). A turn that ended `end_turn` with the key filed is not answered. One `tool_call` stands for the wait (its title names the campaign and the next look), with a `tool_call_update` heartbeat every `HOLD_HEARTBEAT_S` (60 s) so a client that clocks liveness by frames sees the agent alive while its model sleeps. The turn slot is reopened with no id to correlate on, so whichever turn ends next on the session -- the wake's, a steer's -- settles it, and the handler decides again from that turn's stash. A wake that arms again keeps the hold; a turn ending with nothing pending answers `end_turn`; a cancel answers `cancelled` as before. The key itself is not passed to the client.
- **Steer.** `_raven/session/steer` is served and advertised under `agentCapabilities._meta` as `raven.steer` (the names raven's own client already uses). Accepted while a prompt is open on the session, held or running: the text is shown on the wire as the person's own line, then sent with `turn.send`'s new `busy: "inject"`. Answers `injected` / `no_turn`.
- **Wire.** `turn.send` gains the optional `busy` param (`const "inject"`): an ordinary send on an idle lane, `BusyPolicy.INJECT` into the running turn otherwise -- the merge a channel's mid-turn message already gets (`gateway_commands.py`). No slot is bound for an injected message; the running turn keeps the lane's. `openrpc.json` and both generated clients moved together.
What raven's client side already does, unchanged: the DAG stall watcher resets on any frame (the heartbeat keeps it quiet, and a stopped heartbeat raises the existing stall notice after ten minutes); a sub-agent process that dies fails the request and the node takes its ordinary path; the pool's `_responsive` treats a prompt in flight as busy.
## Review round 1 (2026-09-09, on !600, superseded by this MR)
- **`busy: inject` reads the scheduler's lane state too.** `is_turn_active` knows only the turns `turn.send` started; an armed wake is submitted to the scheduler directly (`make_on_session_wake`) and never binds that map, so a steer during a running wake queued a second turn and answered `injected`. `turn.send` now asks `Scheduler.has_inflight(lane)` as well, and merges (`BusyPolicy.INJECT`) when either record says the lane is running. Pinned: `test_busy_inject_merges_into_a_wake_the_real_scheduler_is_running` -- the reviewer's reproduction on the real `Scheduler`, a turn submitted the way `make_on_session_wake` submits one; with the lane check bypassed it reads `pending=1, inject_mailbox=0`, with it `(1, 0)` in the mailbox and the running turn drains the text.
- Branch renamed to snake_case and both commits carry the `Co-authored-by: Claude (<model-id>)` trailer, per AGENTS.md §2–3; that is why this MR replaces !600 rather than continuing it.
## Review round 2 (2026-09-10)
- **A wake re-armed during its own run survives the writeback.** `CronService._writeback_locked` reloaded the store after the run and, for a one-shot with `delete_after_run`, overwrote the id with the finished run's state and removed it -- but the turn the wake ran had just called `schedule_wake` under the same key, so the id now named the *next* look. It vanished, and the held prompt had nothing left to settle it. A stored job under the fired id whose `at` schedule the run never had is treated as the new wake it is: claim cleared, run recorded, schedule kept, not deleted. Pinned on the real service: `test_a_wake_re_armed_during_its_own_run_survives_the_writeback` (reads `[]` without the fix, the reviewer's state) and the unchanged one-shot deletion beside it. Cron, proactive, sentinel and on-call suites: 968 passed.
## Review round 3 (2026-09-10)
- **An undrained inject stays visible and cancellable.** `busy: inject` dropped the scheduler's handle; when the host turn ended past its last drain, the spine's fallback ran the text as a turn nothing owned -- `turn.cancel` a no-op, no `message.start`. The handle is now kept per lane under an id minted for the text; `turn.cancel` / `session.interrupt` reach it when the active slot is empty (mailbox, queued fallback, or running); and when the fallback turn starts, the RPC sink (`on_turn_start`, wired from bootstrap) binds the lane to it and opens it on the wire with the person's words. `turn.send` answers the inject's own id. Pinned through `build_rpc_spine` with the reviewer's shape (a loop that drains once, an inject after it): `test_an_undrained_inject_runs_as_a_turn_the_surface_can_see_and_cancel` and `test_a_pending_inject_can_be_cancelled_before_it_merges_or_falls_back`; both read the reviewer's state (`turn_ids` empty, cancel finding nothing) with the fix bypassed.
- **Line ceiling.** The contract comment is five lines; `raven/contracts` is 2,519 against 2,520, one line of headroom on the current `main` (2,514).
- Non-blocking items taken: `SchedulerDrainingError` on the inject path exits as `turn_failed`; the title is announced before the hold; the steer constants sit below the cancel constant's docstring; three edges pinned (a held prompt settled by a wake turn's uncorrelated ending through `send_frame`, the hold key never in the client's `_meta`, `raven.toolName` on the wait row).
- Focused suite (reviewer's list plus the touched files): 948 passed on Python 3.12.
## Review round 4 (2026-09-10)
- **Every pending inject is kept, per lane and per id.** One replaceable record per lane kept only the newest steer; two steers after the host's last drain fall back in turn, and the first started unowned while a cancel took out the second. The record is now `lane -> {inject id: (handle, text)}` in arrival order: each fallback promotes its own handle, and a cancel with no active turn reaches the oldest pending one -- the one the spine runs next. Pinned: `test_two_undrained_injects_each_get_their_own_turn_promoted_and_cancelled` (both promoted with their own ids and `message.start`, cancelled one after the other; runner saw all three turns). Focused suite: 949 passed.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_acp_methods.py tests/test_acp_protocol.py tests/test_rpc_turn_send.py \
tests/test_rpc_schema_match.py tests/test_acp_updates.py tests/test_acp_server.py -q # 766 passed
uv run pytest tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_actions.py \
tests/test_agents_oncall_flow_budget.py tests/test_agents_oncall_flow_readings.py \
tests/test_agents_oncall_flow_escalation_tools.py -q # 99 passed
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents # clean
uv run lint-imports # 9 kept, 0 broken
cd ui-tui && npm run lint:rpc && npx tsc --noEmit; cd ui-web && npm run gen:check && npx tsc --noEmit # in sync, clean
```
New tests: `TestHeldTurn` (held across an armed wake, held again on a re-arm, heartbeat on the wait call, cancel while held, a non-`end_turn` stop is not held; every frame validated against the ACP schema), `TestSteer` (advertised, `no_turn` when idle, a held prompt takes the words as a turn with `busy: inject`, refusals), `busy: inject` on a busy and an idle lane in `test_rpc_turn_send.py`, and the plugin's hold stamping through the real `CronService` grant (filed with a pending wake; not filed without one, after the wake stands down, or once the campaign concluded).
Not done: no end-to-end run of a real on-call wake through a held prompt yet -- unit tests only.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (the hold is invisible to a person except as a "waiting for ..." tool row)
## Risk
- [x] Backward compatibility considered: a turn that files no `raven.holdTurn` is answered exactly as before; `busy` is optional and absent from every existing caller; the steer method and capability are additive.
- [x] Rollback path is clear: revert the two commits.
A held prompt holds one `max_concurrent_subagents` slot (default 8) for the wait's duration on the caller's side; raised in config if it bites.
## Related
Replaces !573 (closed). Follows !518 (stall notice) and !520 (unprompted-turn route; a wake that runs under a held prompt no longer takes it for DAG nodes).
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
Ruff carried no complexity rule, so nothing bounded the number of paths through
a function. This adds `C901` with a ceiling chosen to stop the untestable and
nothing else.
**What the number means.** Cyclomatic complexity is the count of linearly
independent paths through a function, which makes it the floor on how many cases
a suite needs to walk them all. A body with a hundred of them has paths nobody
will ever write a case for, and those paths are first executed in production.
That is the failure this rule prevents; it is not a style preference.
Two properties of the metric matter for reading the numbers below. A nested
function's score is counted into its enclosing function as well as reported on
its own, so an outer function with no branches of its own scores one more than
the inner function it holds. And Ruff reports `C901` only when the score is
*greater* than `max-complexity`, so a function at exactly 40 passes a ceiling of
40 and needs no suppression.
**Where 40 comes from.** The measured distribution, not McCabe's recommendation
of 10:
| max-complexity | functions flagged |
|---|---|
| 10 | 253 |
| 25 | 26 |
| 30 | 17 |
| **40** | **9** |
| 50 | 5 |
Ten would flag 253 functions and be switched off within the week. Forty is not a
claim that 39 is fine -- it is where a function stops being complex and starts
being untestable. Tightening later means lowering the number, which is a
reviewed edit to `pyproject.toml`.
**The nine over the ceiling.** Each carries a `noqa: C901` naming its actual
score. Seven are in `raven/`, two in the oncall-flow plugin under `agents/`:
```
100 raven/agent/loop/turn_path.py _run_agent_loop
87 raven/cli/gateway_commands.py register
86 raven/cli/gateway_commands.py gateway
69 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
68 raven/cli/gateway_commands.py run
54 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
47 raven/agent/loop/turn_path.py _process_message
46 raven/config/loader.py _migrate_config
41 raven/agent/loop/turn_path.py _run_turn
```
A tenth suppression sits on `benchmarks/proactivity_eval/runners/_common/longrun_adapters.py`
(`tick_to`, 41). `benchmarks/` is outside `PYTHON_LINT_TARGETS` and so outside
CI, but inside what the pre-commit Ruff hook sees on a changed file -- marking it
means the gate does not ambush whoever next edits that adapter.
**Nine entries, fewer distinct problems.** In `gateway_commands.py` the three
are nested inside each other at indent 0, 4 and 8: `run` at 68 is the body,
`gateway` adds its own branches on top, and `register` contributes about one. In
`turn_path.py` the three are sibling methods, but `_run_turn` holds ten nested
callbacks (`on_token`, `on_tool`, `on_progress` and so on) which is most of its
41. The one that is a large body by itself is `_run_agent_loop`: 1134 lines with
only two nested functions, so its 100 is its own.
Per-function rather than per-file, on purpose: a whole-file ignore on
`gateway_commands.py` would let a new 80-path function in the same file through,
while these entries do not. The score is in the comment so the debt is visible
where the code is, not parked in a config file.
Nothing has to be refactored to land this. Normal work is undisturbed unless
someone writes a forty-one-path function.
**Why the PLR09xx rules are left out.** They count arguments (230 occurrences
here), branches (125), statements (78) and returns (81). All four are proxies
for what `C901` measures directly, so adding them would report one fact four
times and bury the signal under 230 argument-count warnings.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: a lint gate plus the `noqa` entries that let it land green. No runtime
code changes; every production edit is an end-of-line comment.
## Verification
Verified against the lint roster read out of the Makefile
(`PYTHON_LINT_TARGETS = raven evolver agents plugins-dist tests scripts`) rather
than a chosen subset, and then against the whole tree. The first revision of
this MR checked only `raven/` and went red in CI on the two `agents/` functions;
that is what the roster-wide check exists to prevent.
```
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
raven evolver agents plugins-dist tests scripts
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache .
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
--extend-select RUF100 raven evolver agents plugins-dist tests scripts
(no unused C901 directive)
$ uv run --frozen --python 3.12 --extra dev ruff format --check \
raven evolver agents plugins-dist tests scripts
1886 files already formatted
$ uv run --frozen --python 3.12 pytest tests/ -q -k "turn_path or gateway or loader or console or config_precedence"
511 passed, 19 skipped
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The 19 skips are pre-existing and environmental: `test_provider_resolution_invariants.py`
skips its gateway-only cases when no gateway is configured.
Checked in the failing direction, since a gate never seen red is not known to
work. A fresh forty-branch function appended to `config/loader.py` is reported,
and the `noqa` on `_migrate_config` in the same file keeps holding rather than
being swallowed by it:
```
raven/config/loader.py:1088:5: C901 `_probe_over_ceiling` is too complex (41 > 40)
Found 1 error.
```
The probe was reverted. Note for the reviewer: reverting that file also reverted
its `noqa`, which the roster-wide check caught immediately.
One entry was removed after review rather than kept: `settings_usage` scores
exactly 40, which a ceiling of 40 does not flag, so its suppression was dead.
`--extend-select RUF100` reports such a directive as unused, and keeping it would
have defeated the documented tightening path -- lowering the number later would
have left that function exempt with nothing to show it.
The production diff is comment-only and can be read as such:
```
- async def _run_agent_loop(
+ async def _run_agent_loop( # noqa: C901 (cc 100: pre-existing, above the ceiling)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No behaviour change: every production edit is an end-of-line comment, and the
diff can be verified as such. The risk this carries is a false sense of
coverage, which is why the rationale in `pyproject.toml` states what the ceiling
does not mean. Two limits of the metric are worth a reviewer knowing: it does
not see nesting depth (five sequential `if`s and five nested ones both score 6),
and in Ruff's implementation boolean operators, ternaries and comprehension
conditions do not count at all. It is a filter for the untestable, not a
readability score.
Rollback is reverting the commits. Loosening instead of reverting is a one-line
change to `max-complexity`, which is the intended escape if the gate turns out
to obstruct real work.
## Related Issues
N/A
## Summary
Ruff carried no complexity rule, so nothing bounded the number of paths through
a function. This adds `C901` with a ceiling chosen to stop the untestable and
nothing else.
**What the number means.** Cyclomatic complexity is the count of linearly
independent paths through a function, which makes it the floor on how many cases
a suite needs to walk them all. A body with a hundred of them has paths nobody
will ever write a case for, and those paths are first executed in production.
That is the failure this rule prevents; it is not a style preference.
Two properties of the metric matter for reading the numbers below. A nested
function's score is counted into its enclosing function as well as reported on
its own, so an outer function with no branches of its own scores one more than
the inner function it holds. And Ruff reports `C901` only when the score is
*greater* than `max-complexity`, so a function at exactly 40 passes a ceiling of
40 and needs no suppression.
**Where 40 comes from.** The measured distribution, not McCabe's recommendation
of 10:
| max-complexity | functions flagged |
|---|---|
| 10 | 253 |
| 25 | 26 |
| 30 | 17 |
| **40** | **9** |
| 50 | 5 |
Ten would flag 253 functions and be switched off within the week. Forty is not a
claim that 39 is fine -- it is where a function stops being complex and starts
being untestable. Tightening later means lowering the number, which is a
reviewed edit to `pyproject.toml`.
**The nine over the ceiling.** Each carries a `noqa: C901` naming its actual
score. Seven are in `raven/`, two in the oncall-flow plugin under `agents/`:
```
100 raven/agent/loop/turn_path.py _run_agent_loop
87 raven/cli/gateway_commands.py register
86 raven/cli/gateway_commands.py gateway
69 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
68 raven/cli/gateway_commands.py run
54 agents/raven-oncall/.../oncall_flow/tools/ops.py execute
47 raven/agent/loop/turn_path.py _process_message
46 raven/config/loader.py _migrate_config
41 raven/agent/loop/turn_path.py _run_turn
```
A tenth suppression sits on `benchmarks/proactivity_eval/runners/_common/longrun_adapters.py`
(`tick_to`, 41). `benchmarks/` is outside `PYTHON_LINT_TARGETS` and so outside
CI, but inside what the pre-commit Ruff hook sees on a changed file -- marking it
means the gate does not ambush whoever next edits that adapter.
**Nine entries, fewer distinct problems.** In `gateway_commands.py` the three
are nested inside each other at indent 0, 4 and 8: `run` at 68 is the body,
`gateway` adds its own branches on top, and `register` contributes about one. In
`turn_path.py` the three are sibling methods, but `_run_turn` holds ten nested
callbacks (`on_token`, `on_tool`, `on_progress` and so on) which is most of its
41. The one that is a large body by itself is `_run_agent_loop`: 1134 lines with
only two nested functions, so its 100 is its own.
Per-function rather than per-file, on purpose: a whole-file ignore on
`gateway_commands.py` would let a new 80-path function in the same file through,
while these entries do not. The score is in the comment so the debt is visible
where the code is, not parked in a config file.
Nothing has to be refactored to land this. Normal work is undisturbed unless
someone writes a forty-one-path function.
**Why the PLR09xx rules are left out.** They count arguments (230 occurrences
here), branches (125), statements (78) and returns (81). All four are proxies
for what `C901` measures directly, so adding them would report one fact four
times and bury the signal under 230 argument-count warnings.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: a lint gate plus the `noqa` entries that let it land green. No runtime
code changes; every production edit is an end-of-line comment.
## Verification
Verified against the lint roster read out of the Makefile
(`PYTHON_LINT_TARGETS = raven evolver agents plugins-dist tests scripts`) rather
than a chosen subset, and then against the whole tree. The first revision of
this MR checked only `raven/` and went red in CI on the two `agents/` functions;
that is what the roster-wide check exists to prevent.
```
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
raven evolver agents plugins-dist tests scripts
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache .
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
--extend-select RUF100 raven evolver agents plugins-dist tests scripts
(no unused C901 directive)
$ uv run --frozen --python 3.12 --extra dev ruff format --check \
raven evolver agents plugins-dist tests scripts
1886 files already formatted
$ uv run --frozen --python 3.12 pytest tests/ -q -k "turn_path or gateway or loader or console or config_precedence"
511 passed, 19 skipped
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The 19 skips are pre-existing and environmental: `test_provider_resolution_invariants.py`
skips its gateway-only cases when no gateway is configured.
Checked in the failing direction, since a gate never seen red is not known to
work. A fresh forty-branch function appended to `config/loader.py` is reported,
and the `noqa` on `_migrate_config` in the same file keeps holding rather than
being swallowed by it:
```
raven/config/loader.py:1088:5: C901 `_probe_over_ceiling` is too complex (41 > 40)
Found 1 error.
```
The probe was reverted. Note for the reviewer: reverting that file also reverted
its `noqa`, which the roster-wide check caught immediately.
One entry was removed after review rather than kept: `settings_usage` scores
exactly 40, which a ceiling of 40 does not flag, so its suppression was dead.
`--extend-select RUF100` reports such a directive as unused, and keeping it would
have defeated the documented tightening path -- lowering the number later would
have left that function exempt with nothing to show it.
The production diff is comment-only and can be read as such:
```
- async def _run_agent_loop(
+ async def _run_agent_loop( # noqa: C901 (cc 100: pre-existing, above the ceiling)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No behaviour change: every production edit is an end-of-line comment, and the
diff can be verified as such. The risk this carries is a false sense of
coverage, which is why the rationale in `pyproject.toml` states what the ceiling
does not mean. Two limits of the metric are worth a reviewer knowing: it does
not see nesting depth (five sequential `if`s and five nested ones both score 6),
and in Ruff's implementation boolean operators, ternaries and comprehension
conditions do not count at all. It is a filter for the untestable, not a
readability score.
Rollback is reverting the commits. Loosening instead of reverting is a one-line
change to `max-complexity`, which is the intended escape if the gate turns out
to obstruct real work.
## Related Issues
N/A
## Summary
`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.
The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.
Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.
Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.
This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
tests/test_permissions_gate.py tests/test_acp_server.py \
tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s
$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s
$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
raven/acp/server.py raven/agent/tools/shell.py
All checks passed!
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.
Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.
Effect on the dependency graph:
```
permissions -> agent edges 1 -> 0
mutually importing pairs 14 -> 13
packages in an import cycle 22 -> 22 (unchanged)
```
The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.
No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.
## Related Issues
N/A
## Summary
`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.
The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.
Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.
Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.
This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
tests/test_permissions_gate.py tests/test_acp_server.py \
tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s
$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s
$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
raven/acp/server.py raven/agent/tools/shell.py
All checks passed!
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.
Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.
Effect on the dependency graph:
```
permissions -> agent edges 1 -> 0
mutually importing pairs 14 -> 13
packages in an import cycle 22 -> 22 (unchanged)
```
The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.
No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.
## Related Issues
N/A
## Summary
When a DAG node fails, the sub-agent's report opens a turn in the user's own conversation (origin `SUBAGENT`). The asker already bound in that turn whenever a surface was watching the conversation, so the person could answer `ask_user` there and pick "continue". The approval responder, however, bound only for `USER` turns, so the `resolve_dag_node` call that acts on that answer was refused in the same turn as "this turn is not interactive". The run ended on the person's own decision: the node could be neither continued nor abandoned from the TUI or the WebUI.
The fix binds the approval responder on the gate the asker already used: a `USER` turn always, a `SUBAGENT` relay when its conversation has a live watcher, every other origin never. One expression, shared by both bindings, in `RpcTurnRunner.run`.
The gateway's channel runner (`GatewayTurnRunner`) is deliberately left as it is: a channel session has no watched-signal to gate on, and widening there would turn an abandoned-channel question from an instant decline into a stall, as its own comment says.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_rpc_spine.py tests/test_agent_loop_approval.py tests/test_shell_approval.py tests/test_permissions*.py -q`: 361 passed. Two new cases: a `SUBAGENT` turn in a watched conversation reaches the responder and the gated tool runs; the same turn with nobody watching is still refused as not interactive.
- Reverse check: with the spine change reverted, the watched-relay case fails on the gated tool not running.
- `make lint-python`: clean.
- `uv run --all-extras pytest -q` (before rebase): 20150 passed, 4 failed, 165 skipped. The 4 failures (`test_agent_loop_token_budget`, `test_agents_code_launcher`, `test_agents_oncall_launcher`, `test_ppt_engine_image_search`) fail identically with this change reverted and again on the rebased head; none of them imports `raven.rpc.spine`. Pre-existing on `main`.
End to end, no permission override in the config, host started from this branch, port owner start time checked against the last code change:
| Frontend | Flow | Result |
|---|---|---|
| TUI (`raven tui --dev`) | run a playbook whose carried server is down -> node fails -> host calls `resolve_dag_node continue` -> approval overlay "Approve this action: resolve_dag_node {...}" -> key 1 -> tool runs -> attempt-2 dispatched | pass (before the fix the same step ended in "This call requires user approval (ask tier), but this turn is not interactive") |
| WebUI (`raven serve`) | same flow -> approval sheet "Approve this action: resolve_dag_node {...}" -> "Allow once" -> tool runs (the model chose abandon this time, so no second attempt; the point under test is that the approval reaches the person and the gated tool executes) | pass |
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs exist for the approval gate)
## Risk
- Permission semantics: an ask-tier tool called in a sub-agent relay turn now reaches the person watching the conversation instead of being refused. It still fails closed with nobody watching (`has_subscribers` false), on timeout, and on every other origin. This is the same reachability rule the asker has had since the relay widening; approval was the one binding that had not followed it.
- Backward compatibility: `USER` and `CRON` turns are unchanged. The channel gateway runner is unchanged.
- Rollback: revert the squash commit; no data or config involved.
## Related Issues
N/A
## Summary
When a DAG node fails, the sub-agent's report opens a turn in the user's own conversation (origin `SUBAGENT`). The asker already bound in that turn whenever a surface was watching the conversation, so the person could answer `ask_user` there and pick "continue". The approval responder, however, bound only for `USER` turns, so the `resolve_dag_node` call that acts on that answer was refused in the same turn as "this turn is not interactive". The run ended on the person's own decision: the node could be neither continued nor abandoned from the TUI or the WebUI.
The fix binds the approval responder on the gate the asker already used: a `USER` turn always, a `SUBAGENT` relay when its conversation has a live watcher, every other origin never. One expression, shared by both bindings, in `RpcTurnRunner.run`.
The gateway's channel runner (`GatewayTurnRunner`) is deliberately left as it is: a channel session has no watched-signal to gate on, and widening there would turn an abandoned-channel question from an instant decline into a stall, as its own comment says.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_rpc_spine.py tests/test_agent_loop_approval.py tests/test_shell_approval.py tests/test_permissions*.py -q`: 361 passed. Two new cases: a `SUBAGENT` turn in a watched conversation reaches the responder and the gated tool runs; the same turn with nobody watching is still refused as not interactive.
- Reverse check: with the spine change reverted, the watched-relay case fails on the gated tool not running.
- `make lint-python`: clean.
- `uv run --all-extras pytest -q` (before rebase): 20150 passed, 4 failed, 165 skipped. The 4 failures (`test_agent_loop_token_budget`, `test_agents_code_launcher`, `test_agents_oncall_launcher`, `test_ppt_engine_image_search`) fail identically with this change reverted and again on the rebased head; none of them imports `raven.rpc.spine`. Pre-existing on `main`.
End to end, no permission override in the config, host started from this branch, port owner start time checked against the last code change:
| Frontend | Flow | Result |
|---|---|---|
| TUI (`raven tui --dev`) | run a playbook whose carried server is down -> node fails -> host calls `resolve_dag_node continue` -> approval overlay "Approve this action: resolve_dag_node {...}" -> key 1 -> tool runs -> attempt-2 dispatched | pass (before the fix the same step ended in "This call requires user approval (ask tier), but this turn is not interactive") |
| WebUI (`raven serve`) | same flow -> approval sheet "Approve this action: resolve_dag_node {...}" -> "Allow once" -> tool runs (the model chose abandon this time, so no second attempt; the point under test is that the approval reaches the person and the gated tool executes) | pass |
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs exist for the approval gate)
## Risk
- Permission semantics: an ask-tier tool called in a sub-agent relay turn now reaches the person watching the conversation instead of being refused. It still fails closed with nobody watching (`has_subscribers` false), on timeout, and on every other origin. This is the same reachability rule the asker has had since the relay widening; approval was the one binding that had not followed it.
- Backward compatibility: `USER` and `CRON` turns are unchanged. The channel gateway runner is unchanged.
- Rollback: revert the squash commit; no data or config involved.
## Related Issues
N/A
## Summary
These are aggregate ceilings on how far import cycles reach, not a proof that no
cycle was deepened: an edge added between two members of the existing component
leaves every total unmoved, and that case is left to the contracts and to review.
The module docstring says so too.
`acyclic_siblings` is the import-linter contract that would forbid import cycles
among raven's top-level subpackages outright. It is not in `pyproject.toml`
because it is BROKEN: **18 of the 40 top-level subpackages sit in a single
strongly connected component**. Added as a gate it would paint CI red on arrival
and be switched off within the week.
This states the same rule as a budget instead of an absolute. Three ceilings, set
to what the tree measures today, and they may only go down:
```
PACKAGES_IN_CYCLES_CEILING = 18
MUTUAL_PAIRS_CEILING = 13
MODULES_IN_CYCLES_CEILING = 42
```
This branch carries the vocabulary refactor (MR 610) underneath it, because the
ceilings are the numbers that hold once that lands. If 610 merges first this
becomes a single-commit change; either way the ceilings match the tree the guard
runs against.
A change that draws a package or a module into a cycle for the first time, or
makes a new pair import each other, fails here. An edge added between two
members of the existing component does not: every total stays put, and that
case is left to the contracts and to review. Unpicking one lowers a ceiling,
which is a reviewed edit to the test file rather than a drive-by -- the same
shape `tests/test_kernel_budget.py` already uses, and for the same reason its
docstring gives.
Three numbers, because each is blind where another sees. Mutual pairs (a imports
b and b imports a) are the edges people actually add, and the failure message
names them. A cycle three packages long shows up in no pair at all, so a
component measure carries the general case.
The third exists because the package measure is an artifact of granularity as
much as of design. Collapsing a package to one node turns "config's writer
reaches agent, which reaches config's loader" into a cycle even where no module
imports itself back; measured per module, 42 of 635 modules sit in a cycle
rather than 18 of 40 packages. The two answer different questions -- whether a
package can be lifted out on its own, and whether a reader has a real knot to
walk around -- and they move independently: the refactor underneath took the
package count from 22 to 18 while moving the module count by three.
The numbers were still moving while this was written. `agent <-> permissions`
became the fourteenth mutual pair during the drafting, on a `permissions`
package that had just arrived. Nothing reported it, because nothing was
watching -- which is the case for pinning them.
`grimp` becomes an explicit dev dependency rather than staying a transitive one
through import-linter, since a test now imports it directly.
This changes no production code and unpicks no cycle. It fixes the number in
place so that the unpicking, when it happens, is not undone by the next branch.
### Both graph options are chosen, not defaulted
`exclude_type_checking_imports` is read out of `[tool.importlinter]` rather than
hardcoded, so the guard measures the same graph the contracts are checked
against. Without it, `gateway` counts as cyclic on a type-checking-only import
and the module count moves by three -- the guard would have been ratcheting a
graph no contract enforces.
`cache_dir=None` because grimp's default is a shared `.grimp_cache` that
outlives a branch switch. A guard whose job is to report the graph of the
checked-out tree must not serve one an earlier revision left behind: a stale hit
turns it red or green for reasons absent from the diff. Building fresh costs
about a second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: an architecture guard, in the shape of a budget. Closest to `test`, which
is the commit type used.
## Verification
```
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py -q
4 passed in 1.06s
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py \
tests/test_kernel_closure.py tests/test_kernel_budget.py -q
10 passed in 1.51s
$ uv run --frozen --python 3.12 lint-imports
Contracts: 8 kept, 0 broken.
$ uv run --frozen --python 3.12 --extra dev ruff check tests/test_import_cycle_budget.py
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check tests/test_import_cycle_budget.py
1 file already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Checked in the failing direction once per ceiling, since a gate that has never
been seen red is not known to work.
Making `utils` import the subagent presets trips the two package ceilings and
leaves the module count untouched -- which is the granularity point above, seen
from the failing side:
```
AssertionError: 23 subpackages are inside an import cycle, over the ceiling of 18
AssertionError: 15 pairs of subpackages import each other, over the ceiling of 13
```
Making `utils.text` and `importer.skills.hermes` import each other is a real
module-level cycle, and trips the third:
```
AssertionError: 45 modules are inside an import cycle, over the ceiling of 42
```
Both probes were reverted; the diff carries only the guard, the ceilings and the
dependency line.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No runtime behaviour change. The guard reads the import graph and asserts three
counts; it adds about a second to the suite. All three ceilings are met on
arrival,
so nothing that exists today is blocked. Rollback is reverting the one commit.
The known limit of a count-based ratchet is the one the coverage ratchet already
carries: a change that closes one cycle and opens another leaves the totals
unmoved and passes. Naming the pairs in the failure message is what makes that
visible in review when it matters.
## Related Issues
N/A
## Summary
These are aggregate ceilings on how far import cycles reach, not a proof that no
cycle was deepened: an edge added between two members of the existing component
leaves every total unmoved, and that case is left to the contracts and to review.
The module docstring says so too.
`acyclic_siblings` is the import-linter contract that would forbid import cycles
among raven's top-level subpackages outright. It is not in `pyproject.toml`
because it is BROKEN: **18 of the 40 top-level subpackages sit in a single
strongly connected component**. Added as a gate it would paint CI red on arrival
and be switched off within the week.
This states the same rule as a budget instead of an absolute. Three ceilings, set
to what the tree measures today, and they may only go down:
```
PACKAGES_IN_CYCLES_CEILING = 18
MUTUAL_PAIRS_CEILING = 13
MODULES_IN_CYCLES_CEILING = 42
```
This branch carries the vocabulary refactor (MR 610) underneath it, because the
ceilings are the numbers that hold once that lands. If 610 merges first this
becomes a single-commit change; either way the ceilings match the tree the guard
runs against.
A change that draws a package or a module into a cycle for the first time, or
makes a new pair import each other, fails here. An edge added between two
members of the existing component does not: every total stays put, and that
case is left to the contracts and to review. Unpicking one lowers a ceiling,
which is a reviewed edit to the test file rather than a drive-by -- the same
shape `tests/test_kernel_budget.py` already uses, and for the same reason its
docstring gives.
Three numbers, because each is blind where another sees. Mutual pairs (a imports
b and b imports a) are the edges people actually add, and the failure message
names them. A cycle three packages long shows up in no pair at all, so a
component measure carries the general case.
The third exists because the package measure is an artifact of granularity as
much as of design. Collapsing a package to one node turns "config's writer
reaches agent, which reaches config's loader" into a cycle even where no module
imports itself back; measured per module, 42 of 635 modules sit in a cycle
rather than 18 of 40 packages. The two answer different questions -- whether a
package can be lifted out on its own, and whether a reader has a real knot to
walk around -- and they move independently: the refactor underneath took the
package count from 22 to 18 while moving the module count by three.
The numbers were still moving while this was written. `agent <-> permissions`
became the fourteenth mutual pair during the drafting, on a `permissions`
package that had just arrived. Nothing reported it, because nothing was
watching -- which is the case for pinning them.
`grimp` becomes an explicit dev dependency rather than staying a transitive one
through import-linter, since a test now imports it directly.
This changes no production code and unpicks no cycle. It fixes the number in
place so that the unpicking, when it happens, is not undone by the next branch.
### Both graph options are chosen, not defaulted
`exclude_type_checking_imports` is read out of `[tool.importlinter]` rather than
hardcoded, so the guard measures the same graph the contracts are checked
against. Without it, `gateway` counts as cyclic on a type-checking-only import
and the module count moves by three -- the guard would have been ratcheting a
graph no contract enforces.
`cache_dir=None` because grimp's default is a shared `.grimp_cache` that
outlives a branch switch. A guard whose job is to report the graph of the
checked-out tree must not serve one an earlier revision left behind: a stale hit
turns it red or green for reasons absent from the diff. Building fresh costs
about a second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: an architecture guard, in the shape of a budget. Closest to `test`, which
is the commit type used.
## Verification
```
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py -q
4 passed in 1.06s
$ uv run --frozen --python 3.12 pytest tests/test_import_cycle_budget.py \
tests/test_kernel_closure.py tests/test_kernel_budget.py -q
10 passed in 1.51s
$ uv run --frozen --python 3.12 lint-imports
Contracts: 8 kept, 0 broken.
$ uv run --frozen --python 3.12 --extra dev ruff check tests/test_import_cycle_budget.py
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check tests/test_import_cycle_budget.py
1 file already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Checked in the failing direction once per ceiling, since a gate that has never
been seen red is not known to work.
Making `utils` import the subagent presets trips the two package ceilings and
leaves the module count untouched -- which is the granularity point above, seen
from the failing side:
```
AssertionError: 23 subpackages are inside an import cycle, over the ceiling of 18
AssertionError: 15 pairs of subpackages import each other, over the ceiling of 13
```
Making `utils.text` and `importer.skills.hermes` import each other is a real
module-level cycle, and trips the third:
```
AssertionError: 45 modules are inside an import cycle, over the ceiling of 42
```
Both probes were reverted; the diff carries only the guard, the ceilings and the
dependency line.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No runtime behaviour change. The guard reads the import graph and asserts three
counts; it adds about a second to the suite. All three ceilings are met on
arrival,
so nothing that exists today is blocked. Rollback is reverting the one commit.
The known limit of a count-based ratchet is the one the coverage ratchet already
carries: a change that closes one cycle and opens another leaves the totals
unmoved and passes. Naming the pairs in the failure message is what makes that
visible in review when it matters.
## Related Issues
N/A
## Summary
`raven.config` and `raven.agent` imported each other. config validated sub-agent
declarations against tables living in `raven.agent.subagent`; the agent package
reads config for its shapes and paths. Both sides deferred their import into a
function body to keep module init off the cycle, which is what kept it invisible
to everything except a graph walk.
The validation needs the **vocabulary**, not the behaviour: which names are
legal, never what those names run. Only membership was ever read at the two call
sites -- `command`, `description`, `kind` and `readyTimeoutMs` were not. So the
names move down to `raven/config/agent_names.py` and the tables stay where they
are:
- **config owns what is legal** -- `BUILTIN_AGENT_NAMES`, `LEGACY_AGENT_ALIASES`,
`THIRD_PARTY_PRESET_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`.
Pure data and pure string functions, no IO.
- **`raven.agent.subagent` owns what it does** -- the preset table with its
commands, transports and timeouts is untouched.
`builtin_agents` re-exports the moved names, so its eight consumers (`registry`,
`rpc.methods.subagents`, `manager`, `spawn_tool`,
`context_engine.segments.identity`) are not touched at all.
### Why the check did not move up instead
Moving the validation later, rather than moving the data down, would also break
the cycle and would cost nothing in cohesion. It was rejected because the check
is deliberately at parse time. It runs as a `@model_validator(mode="after")` on
all three sub-agent transports, on both paths that build a model from a dict
(`load_config` reading the file, and `update_subagents` validating before an
atomic write). Its own docstring names what it catches: a hand-edited
`preset: "hermes"` on an unrelated entry, which would otherwise both dodge the
reserved-name guard and hide the real Hermes preset from the Presets group.
An invalid row would become constructible, and every later reader would treat it
as valid.
### The cost, and the pin
The split spells one name set in two places. A preset added to
`THIRD_PARTY_SUBAGENT_PRESETS` without its key added to the vocabulary would ship
and then be refused by the schema meant to accept it, with nothing reporting the
mismatch. `tests/test_subagent_name_vocabulary.py` pins both sets equal in both
directions, and does the same for the seed table against the reserved names.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest \
tests/test_subagent_name_vocabulary.py tests/test_subagent_builtin_agents.py \
tests/test_update_subagents.py tests/test_subagent_registry.py \
tests/test_subagent_acp.py tests/test_rpc_subagents.py tests/test_kernel_closure.py -q
350 passed in 13.91s
$ uv run --frozen --python 3.12 --extra dev ruff check <the five changed files>
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check <the five changed files>
5 files already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Both the contract run and the test run above were repeated after rebasing onto
the current main, since this one touches production code.
Every call site of every moved symbol was enumerated before the edit
(`BUILTIN_AGENT_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`,
`GENERIC_AGENT`, `LEGACY_AGENT_ALIASES`, `THIRD_PARTY_SUBAGENT_PRESETS`) and the
re-export is what keeps them all valid.
Effect on the dependency graph, measured before and after:
```
config -> agent edges 2 -> 0
packages in an import cycle 22 -> 19 (out of 40)
mutually importing pairs 14 -> 13
```
The three packages that leave the cycle were only ever pulled in through this
one pair.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No behaviour change: the same names, the same validation, the same failure
messages. The reserved-name guard and the preset provenance check both still run
at parse time on all three transports. Backward compatibility is why
`builtin_agents` re-exports rather than relocating its public surface, and why
`LEGACY_AGENT_ALIASES` moves intact -- stored records under the old lowercase
name still resolve.
Rollback is reverting the one commit. The risk this leaves behind is the
two-spellings drift, which is why the equality pin ships in the same commit
rather than as a follow-up.
## Related Issues
N/A
## Summary
`raven.config` and `raven.agent` imported each other. config validated sub-agent
declarations against tables living in `raven.agent.subagent`; the agent package
reads config for its shapes and paths. Both sides deferred their import into a
function body to keep module init off the cycle, which is what kept it invisible
to everything except a graph walk.
The validation needs the **vocabulary**, not the behaviour: which names are
legal, never what those names run. Only membership was ever read at the two call
sites -- `command`, `description`, `kind` and `readyTimeoutMs` were not. So the
names move down to `raven/config/agent_names.py` and the tables stay where they
are:
- **config owns what is legal** -- `BUILTIN_AGENT_NAMES`, `LEGACY_AGENT_ALIASES`,
`THIRD_PARTY_PRESET_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`.
Pure data and pure string functions, no IO.
- **`raven.agent.subagent` owns what it does** -- the preset table with its
commands, transports and timeouts is untouched.
`builtin_agents` re-exports the moved names, so its eight consumers (`registry`,
`rpc.methods.subagents`, `manager`, `spawn_tool`,
`context_engine.segments.identity`) are not touched at all.
### Why the check did not move up instead
Moving the validation later, rather than moving the data down, would also break
the cycle and would cost nothing in cohesion. It was rejected because the check
is deliberately at parse time. It runs as a `@model_validator(mode="after")` on
all three sub-agent transports, on both paths that build a model from a dict
(`load_config` reading the file, and `update_subagents` validating before an
atomic write). Its own docstring names what it catches: a hand-edited
`preset: "hermes"` on an unrelated entry, which would otherwise both dodge the
reserved-name guard and hide the real Hermes preset from the Presets group.
An invalid row would become constructible, and every later reader would treat it
as valid.
### The cost, and the pin
The split spells one name set in two places. A preset added to
`THIRD_PARTY_SUBAGENT_PRESETS` without its key added to the vocabulary would ship
and then be refused by the schema meant to accept it, with nothing reporting the
mismatch. `tests/test_subagent_name_vocabulary.py` pins both sets equal in both
directions, and does the same for the seed table against the reserved names.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest \
tests/test_subagent_name_vocabulary.py tests/test_subagent_builtin_agents.py \
tests/test_update_subagents.py tests/test_subagent_registry.py \
tests/test_subagent_acp.py tests/test_rpc_subagents.py tests/test_kernel_closure.py -q
350 passed in 13.91s
$ uv run --frozen --python 3.12 --extra dev ruff check <the five changed files>
All checks passed!
$ uv run --frozen --python 3.12 --extra dev ruff format --check <the five changed files>
5 files already formatted
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Both the contract run and the test run above were repeated after rebasing onto
the current main, since this one touches production code.
Every call site of every moved symbol was enumerated before the edit
(`BUILTIN_AGENT_NAMES`, `canonical_agent_name`, `is_builtin_agent_name`,
`GENERIC_AGENT`, `LEGACY_AGENT_ALIASES`, `THIRD_PARTY_SUBAGENT_PRESETS`) and the
re-export is what keeps them all valid.
Effect on the dependency graph, measured before and after:
```
config -> agent edges 2 -> 0
packages in an import cycle 22 -> 19 (out of 40)
mutually importing pairs 14 -> 13
```
The three packages that leave the cycle were only ever pulled in through this
one pair.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No behaviour change: the same names, the same validation, the same failure
messages. The reserved-name guard and the preset provenance check both still run
at parse time on all three transports. Backward compatibility is why
`builtin_agents` re-exports rather than relocating its public surface, and why
`LEGACY_AGENT_ALIASES` moves intact -- stored records under the old lowercase
name still resolve.
Rollback is reverting the one commit. The risk this leaves behind is the
two-spellings drift, which is why the equality pin ships in the same commit
rather than as a follow-up.
## Related Issues
N/A
## Summary
Raven-Code gains a product-owned coding tool set and engineering guidance. The code-flow plugin supplies read_file, write_file, edit_file, list_dir, glob, todo, and exec through the host's existing plugin interfaces. It adds long-line read limits, explicit non-overlapping occurrence edits, Python syntax feedback, brace globbing with visible partial/error results, persistent checklists, and execution timeout/output reporting. All implementation changes are under agents/raven-code; raven/, other agent implementations, and both UIs have no diff.
Read-before-edit checks use records isolated by Raven-Code runtime and conversation. A successful read or full write establishes a record; appending to unseen or stale existing content does not grant editing permission. Fresh ACP sessions have distinct keys and separate records/checklists. Resuming an existing session restores its plan, and session deletion clears its product state. Tool binding covers user and subagent turns, including runs with flow guidance disabled.
Repository AGENTS.md, CLAUDE.md, and CONTEXT.md enter system context through Raven-Code's existing before_iteration hook. User queries, persisted transcripts, and /new and /help command handling stay intact. Each candidate is resolved and read only if it remains inside the resolved working directory, including absolute names, parent traversal, and symlink targets. Contained aliases are read once. The hook preserves the host system prefix, replaces its own addition on repeated iterations, and sizes it against the remaining prompt allowance with tools, pending checklist restoration, and the active model's reply ceiling counted. Truncation is explicit. The product uses existing hook and observer interfaces; no shared runtime extension or new command interception is added. The launcher seeds model-specific coding conduct, independently switchable engineering discipline, the product identity, and tool guidance. Untouched managed prompt copies refresh across upgrades while operator edits are preserved. Workspace and execution settings follow host configuration, including when rendering an already rendered configuration. One-shot CLI hosting defaults permissions to full because it cannot answer approval prompts; explicit permission configuration wins, and ACP hosting keeps the host default.
Completion verification gates and the code-verifier plugin are outside this change.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- `uv run --frozen --python 3.12 --extra dev pytest tests/test_agents_code*.py tests/test_agent_hook*.py tests/test_context_engine_factory.py tests/test_kernel_budget.py tests/test_agents_research_tools.py tests/test_contracts_two_tier_ledger.py tests/test_l4_entrances.py tests/test_core_runtime_swap.py tests/test_acp_methods.py tests/test_context_scent.py tests/test_skill_hub_policy.py -q --tb=short`: 723 passed after rebasing onto current main. Coverage includes real ACP session creation and product-state isolation, real AgentLoop command dispatch and model-visible message roles, repository containment, user/subagent and concurrent-session binding, append behavior, permission propagation, tool schemas, prompt migration, and runtime contracts. Ordinary text mentioning /new reaches the provider; only the host's exact command form takes its existing command branch. Hook tests cover repeated/deep-copied contexts, token limits, host-prefix preservation, and checklist failure isolation.
- `make lint-python`: passed, including Ruff formatting across 1,899 Python files.
- `uv run --frozen --python 3.12 lint-imports`: 9 contracts kept, 0 broken.
- `make check-large-files check-source-language`, `git diff --check origin/main...HEAD`, and `uv run --frozen --python 3.12 python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- The title and description pass the repository's canonical PR checkers. No frontend sources, generated RPC artifacts, or dependency lockfiles changed. Rebase comparison preserves all eight commits; the only file touched by both the feature and intervening main changes is CONTEXT.md, in separate domain entries. Tests for main's updated skill policy are included above.
Earlier full-suite validation, before the final read-state, repository-instruction, and hook changes, used `uv run --frozen --python 3.12 --extra dev pytest -q --tb=short`. Clean main reported 20,241 passed, 6 failed, 20 errors, and 212 skipped. The candidate reported 20,392 passed, 7 failed, 20 errors, and 212 skipped on each of two runs. Both checkouts used Python 3.12.13 and identical versions of all 212 installed distributions. The 6 cron failures and 20 cron errors had identical test IDs. The additional failure differed between candidate runs:
- `test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`: an intermittent `KeyError: served_url` in unchanged research tooling. The module passed all 82 tests separately on both checkouts and in the final targeted run. A controlled main-only DNS response reproduces the symptom; the original failure's cause remains unconfirmed.
- `test_doctor_answers_where_the_memories_are`: the temporary-directory path caused terminal wrapping inside `mem-root`, breaking the unchanged assertion. The original test reproduces on main with a 30-character `--basetemp`; shorter paths pass on both checkouts.
The full suite was not rerun after the final read-state, repository-instruction, and hook changes, and is not claimed green. Validation ran on Linux; no macOS/Windows execution, live-model run, or prompt-cache cost measurement was performed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The workspace fence remains opt-in and uses the host's path enforcement. Read-before-edit is session-local editing discipline, not a file lock or an atomic concurrency guarantee. Runtime restart requires a fresh read. Full overwrite retains its existing behavior; reading before overwrite remains model guidance rather than a new hard restriction. The exec replacement is offered only when the configured sandbox backend is none; otherwise the host's exec remains active.
Automatic repository-instruction loading always enforces containment, independently of the optional file-tool workspace fence. Injection runs after host history selection and does not evict transcript messages to make room. If even the truncation/concurrency notice cannot fit beside the reply allowance, the turn reports insufficient context instead of making a model call. The added repository text is not promoted into the host's stable cache prefix. New tasks use new session IDs. The host's in-place /new command retains its session key and clears the transcript without clearing separate Raven-Code todo/read state. This existing command behavior is preserved; the product does not add refusal messages or a reset callback. Resuming a session intentionally retains its plan, and deleting it removes its saved plan. Large exec output is retained under the agent home's exec-output directory without a new TTL or count cap; files can be removed manually. Operator-edited prompt copies may require manual updates.
Set plugins.config.code-flow.tools.enabled to false to restore the host tool set. CODE_PROJECT_FILES=off disables repository instruction loading; CODE_CONDUCT=off and CODE_CONDUCT_DISCIPLINE=off control guidance independently. Reverting the change restores the previous product behavior.
## Related Issues
N/A
## Summary
Raven-Code gains a product-owned coding tool set and engineering guidance. The code-flow plugin supplies read_file, write_file, edit_file, list_dir, glob, todo, and exec through the host's existing plugin interfaces. It adds long-line read limits, explicit non-overlapping occurrence edits, Python syntax feedback, brace globbing with visible partial/error results, persistent checklists, and execution timeout/output reporting. All implementation changes are under agents/raven-code; raven/, other agent implementations, and both UIs have no diff.
Read-before-edit checks use records isolated by Raven-Code runtime and conversation. A successful read or full write establishes a record; appending to unseen or stale existing content does not grant editing permission. Fresh ACP sessions have distinct keys and separate records/checklists. Resuming an existing session restores its plan, and session deletion clears its product state. Tool binding covers user and subagent turns, including runs with flow guidance disabled.
Repository AGENTS.md, CLAUDE.md, and CONTEXT.md enter system context through Raven-Code's existing before_iteration hook. User queries, persisted transcripts, and /new and /help command handling stay intact. Each candidate is resolved and read only if it remains inside the resolved working directory, including absolute names, parent traversal, and symlink targets. Contained aliases are read once. The hook preserves the host system prefix, replaces its own addition on repeated iterations, and sizes it against the remaining prompt allowance with tools, pending checklist restoration, and the active model's reply ceiling counted. Truncation is explicit. The product uses existing hook and observer interfaces; no shared runtime extension or new command interception is added. The launcher seeds model-specific coding conduct, independently switchable engineering discipline, the product identity, and tool guidance. Untouched managed prompt copies refresh across upgrades while operator edits are preserved. Workspace and execution settings follow host configuration, including when rendering an already rendered configuration. One-shot CLI hosting defaults permissions to full because it cannot answer approval prompts; explicit permission configuration wins, and ACP hosting keeps the host default.
Completion verification gates and the code-verifier plugin are outside this change.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- `uv run --frozen --python 3.12 --extra dev pytest tests/test_agents_code*.py tests/test_agent_hook*.py tests/test_context_engine_factory.py tests/test_kernel_budget.py tests/test_agents_research_tools.py tests/test_contracts_two_tier_ledger.py tests/test_l4_entrances.py tests/test_core_runtime_swap.py tests/test_acp_methods.py tests/test_context_scent.py tests/test_skill_hub_policy.py -q --tb=short`: 723 passed after rebasing onto current main. Coverage includes real ACP session creation and product-state isolation, real AgentLoop command dispatch and model-visible message roles, repository containment, user/subagent and concurrent-session binding, append behavior, permission propagation, tool schemas, prompt migration, and runtime contracts. Ordinary text mentioning /new reaches the provider; only the host's exact command form takes its existing command branch. Hook tests cover repeated/deep-copied contexts, token limits, host-prefix preservation, and checklist failure isolation.
- `make lint-python`: passed, including Ruff formatting across 1,899 Python files.
- `uv run --frozen --python 3.12 lint-imports`: 9 contracts kept, 0 broken.
- `make check-large-files check-source-language`, `git diff --check origin/main...HEAD`, and `uv run --frozen --python 3.12 python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- The title and description pass the repository's canonical PR checkers. No frontend sources, generated RPC artifacts, or dependency lockfiles changed. Rebase comparison preserves all eight commits; the only file touched by both the feature and intervening main changes is CONTEXT.md, in separate domain entries. Tests for main's updated skill policy are included above.
Earlier full-suite validation, before the final read-state, repository-instruction, and hook changes, used `uv run --frozen --python 3.12 --extra dev pytest -q --tb=short`. Clean main reported 20,241 passed, 6 failed, 20 errors, and 212 skipped. The candidate reported 20,392 passed, 7 failed, 20 errors, and 212 skipped on each of two runs. Both checkouts used Python 3.12.13 and identical versions of all 212 installed distributions. The 6 cron failures and 20 cron errors had identical test IDs. The additional failure differed between candidate runs:
- `test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`: an intermittent `KeyError: served_url` in unchanged research tooling. The module passed all 82 tests separately on both checkouts and in the final targeted run. A controlled main-only DNS response reproduces the symptom; the original failure's cause remains unconfirmed.
- `test_doctor_answers_where_the_memories_are`: the temporary-directory path caused terminal wrapping inside `mem-root`, breaking the unchanged assertion. The original test reproduces on main with a 30-character `--basetemp`; shorter paths pass on both checkouts.
The full suite was not rerun after the final read-state, repository-instruction, and hook changes, and is not claimed green. Validation ran on Linux; no macOS/Windows execution, live-model run, or prompt-cache cost measurement was performed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The workspace fence remains opt-in and uses the host's path enforcement. Read-before-edit is session-local editing discipline, not a file lock or an atomic concurrency guarantee. Runtime restart requires a fresh read. Full overwrite retains its existing behavior; reading before overwrite remains model guidance rather than a new hard restriction. The exec replacement is offered only when the configured sandbox backend is none; otherwise the host's exec remains active.
Automatic repository-instruction loading always enforces containment, independently of the optional file-tool workspace fence. Injection runs after host history selection and does not evict transcript messages to make room. If even the truncation/concurrency notice cannot fit beside the reply allowance, the turn reports insufficient context instead of making a model call. The added repository text is not promoted into the host's stable cache prefix. New tasks use new session IDs. The host's in-place /new command retains its session key and clears the transcript without clearing separate Raven-Code todo/read state. This existing command behavior is preserved; the product does not add refusal messages or a reset callback. Resuming a session intentionally retains its plan, and deleting it removes its saved plan. Large exec output is retained under the agent home's exec-output directory without a new TTL or count cap; files can be removed manually. Operator-edited prompt copies may require manual updates.
Set plugins.config.code-flow.tools.enabled to false to restore the host tool set. CODE_PROJECT_FILES=off disables repository instruction loading; CODE_CONDUCT=off and CODE_CONDUCT_DISCIPLINE=off control guidance independently. Reverting the change restores the previous product behavior.
## Related Issues
N/A
## Summary
The decisions below together stop a deck losing its typography on a cloned template page. A
page-by-page audit of 120 rendered pages put the current output at 1.48 visible defects per
page against 0.29 for the era it is compared to, and named these as the causes a reader
notices first.
- **D45 / D55 - the author is told what a box holds, before and after.** A template box is
drawn for the template's own copy: 219 of 351 heading-class boxes across the ten bundled
templates cannot hold 40 Latin characters at their own type size, median capacity 19. The
page roster now states each page's tightest copy box and its largest matched row as a
range in both scripts, with the growth direction; the end-of-program report still names
what did not fit. Both are validated against the templates' own copy at 993 inside the
conservative bound, 121 between the bounds, 2 past it, the two being 0.031in decorative
brackets.
- **D49 - copy that lands somewhere else is refused, not warned about.** A bottom or
centre-anchored box grows backwards, so a two-line replacement in a 0.98in box at the top
of the page puts its first line above the slide edge. `displaced_copy` is BLOCKING when
the displaced strip leaves the canvas or lands on another frame's copy; downward growth
and shrinking frames stay warnings. Calibrated at 42 `overset_copy` and 0
`displaced_copy` over the ten templates. Also: a build that lost pages is no longer
charged the whole-deck cap and no longer reads as finished, and the delivered file,
`published.json` and `blocking.json` are read back so all three describe the same bytes.
- **D50 - a cloned page can have a region cleared.** Drawing a chart into a cloned page
needs the space emptied first, and there was no supported way to do it, so a live deck
hand-rolled two sweeps that kept every connector and every shape under 1.0x0.7in and drew
two charts on top of them. `clear_region` removes what lies in a box, reports what it
removed and what still overlaps, and keeps the card the template drew the chart in. The
0.5 share threshold is measured: what belongs inside scores 0.58 to 1.00, the rest of the
page 0.05 to 0.42, and nothing falls between.
- **D54 - the copy route reaches the shape the key names completely.** `_all_shapes` walks
z-order back to front, so a title sorts last precisely because it is drawn on top, and
first-match-wins reached it only after every group member beneath it. Two pages of one
delivered deck silently lost their titles. Exact matches now win wherever they sit;
eligibility is unchanged, verified by replaying 1979 real copy-route calls over 211
template pages for 7212 resolutions and 6 target changes.
- **D59 - a region says which of its two readings it is.** `clear_region` accepted four bare
numbers and guessed corners against size, but the two forms are indistinguishable for
ordinary positive coordinates: a size `(1, 1, 4, 3)` was read as the corners
`(1, 1)-(4, 3)`, so a shape at `(4.2, 3.2)` was absent from `shapes_in` and `clear_region`
neither removed nor named it, which is the silent underlay D50 exists to end. The guess is
gone. A region must be a box that names its own reading (`Box.corners`, `Box.at`,
`page_box`) and four bare numbers raise, printing both candidate rectangles and the
constructor for each. Reporting instead of refusing separates nothing, because the size
reading always contains the corner reading. The same range stops the documentation asking
for what the code now refuses: the house brief shipped four bare sizes and the draw-a-page
ask sent the author to lay content out inside one using box-only helpers, so all four
fields are corners now and the skill-claims test enforces that the skill and the brief name
the same keys, at 2218 claims and 0 failures.
## Type
- [x] Fix
- [x] Feature
## Verification
- `subagents/raven-ppt/Raven-PPT/.venv/bin/python -m pytest` over the touched files plus the
gate registry, layering, skill-claims and contract tests: 415 passed, exit 0. Full ppt
sweep `tests/ -k ppt`: 3661 passed, 1 skipped, exit 0. The repo venv has no python-pptx
and would skip these files silently, so they were run against the engine venv.
- `ruff check` and `ruff format --check` clean; `make check-large-files` exit 0.
- D50's 0.5 share threshold re-verified byte-identical after D59's refusal landed: the empty
band is still 0.4206 to 0.5795, the cards score 0.967 to 1.000 against 0.421 to 0.693, and
the survivor at 0.4206 is still named in `left_standing`. D59's own regression, a size
whose width and height both exceed its origin, is `DID NOT RAISE` on the parent and passes
here; 250 passed across nine template and skill files and 193 across five gate files, both
exit 0.
- Every calibration above re-measured on this tip rather than carried over from its branch,
and the invariant that the ten templates writing their own copy into their own boxes
reports nothing still holds at 211 pages and 2084 text-carrying boxes.
- End to end on the page that prompted the work: the delivered program's slide 6 with its
two hand-rolled sweeps replaced by one `clear_region` call, through the real script
backend, removes 25 shapes, renders both line charts without overlap, keeps the template
decoration, and puts the replaced title in the top slot instead of the arrow-group label
it used to reach.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
One severity rose: `displaced_copy` is BLOCKING. It is calibrated to zero findings on the
templates' own copy and fires on 1 of 25 delivered decks, on the page this work was reported
for. The move it asks for is one anchor attribute, which is why it is a refusal rather than
a warning. Rolling back is per decision - each D entry is one commit range.
Integration risk found and fixed here rather than in either branch: D49 reaching upward from
`services/measure` into `services/template` closed an import cycle with D55's
`house -> capacity -> fit` path and made every engine entry point unimportable. Neither
branch could see it alone. The upward reach is deferred to its call site.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The decisions below together stop a deck losing its typography on a cloned template page. A
page-by-page audit of 120 rendered pages put the current output at 1.48 visible defects per
page against 0.29 for the era it is compared to, and named these as the causes a reader
notices first.
- **D45 / D55 - the author is told what a box holds, before and after.** A template box is
drawn for the template's own copy: 219 of 351 heading-class boxes across the ten bundled
templates cannot hold 40 Latin characters at their own type size, median capacity 19. The
page roster now states each page's tightest copy box and its largest matched row as a
range in both scripts, with the growth direction; the end-of-program report still names
what did not fit. Both are validated against the templates' own copy at 993 inside the
conservative bound, 121 between the bounds, 2 past it, the two being 0.031in decorative
brackets.
- **D49 - copy that lands somewhere else is refused, not warned about.** A bottom or
centre-anchored box grows backwards, so a two-line replacement in a 0.98in box at the top
of the page puts its first line above the slide edge. `displaced_copy` is BLOCKING when
the displaced strip leaves the canvas or lands on another frame's copy; downward growth
and shrinking frames stay warnings. Calibrated at 42 `overset_copy` and 0
`displaced_copy` over the ten templates. Also: a build that lost pages is no longer
charged the whole-deck cap and no longer reads as finished, and the delivered file,
`published.json` and `blocking.json` are read back so all three describe the same bytes.
- **D50 - a cloned page can have a region cleared.** Drawing a chart into a cloned page
needs the space emptied first, and there was no supported way to do it, so a live deck
hand-rolled two sweeps that kept every connector and every shape under 1.0x0.7in and drew
two charts on top of them. `clear_region` removes what lies in a box, reports what it
removed and what still overlaps, and keeps the card the template drew the chart in. The
0.5 share threshold is measured: what belongs inside scores 0.58 to 1.00, the rest of the
page 0.05 to 0.42, and nothing falls between.
- **D54 - the copy route reaches the shape the key names completely.** `_all_shapes` walks
z-order back to front, so a title sorts last precisely because it is drawn on top, and
first-match-wins reached it only after every group member beneath it. Two pages of one
delivered deck silently lost their titles. Exact matches now win wherever they sit;
eligibility is unchanged, verified by replaying 1979 real copy-route calls over 211
template pages for 7212 resolutions and 6 target changes.
- **D59 - a region says which of its two readings it is.** `clear_region` accepted four bare
numbers and guessed corners against size, but the two forms are indistinguishable for
ordinary positive coordinates: a size `(1, 1, 4, 3)` was read as the corners
`(1, 1)-(4, 3)`, so a shape at `(4.2, 3.2)` was absent from `shapes_in` and `clear_region`
neither removed nor named it, which is the silent underlay D50 exists to end. The guess is
gone. A region must be a box that names its own reading (`Box.corners`, `Box.at`,
`page_box`) and four bare numbers raise, printing both candidate rectangles and the
constructor for each. Reporting instead of refusing separates nothing, because the size
reading always contains the corner reading. The same range stops the documentation asking
for what the code now refuses: the house brief shipped four bare sizes and the draw-a-page
ask sent the author to lay content out inside one using box-only helpers, so all four
fields are corners now and the skill-claims test enforces that the skill and the brief name
the same keys, at 2218 claims and 0 failures.
## Type
- [x] Fix
- [x] Feature
## Verification
- `subagents/raven-ppt/Raven-PPT/.venv/bin/python -m pytest` over the touched files plus the
gate registry, layering, skill-claims and contract tests: 415 passed, exit 0. Full ppt
sweep `tests/ -k ppt`: 3661 passed, 1 skipped, exit 0. The repo venv has no python-pptx
and would skip these files silently, so they were run against the engine venv.
- `ruff check` and `ruff format --check` clean; `make check-large-files` exit 0.
- D50's 0.5 share threshold re-verified byte-identical after D59's refusal landed: the empty
band is still 0.4206 to 0.5795, the cards score 0.967 to 1.000 against 0.421 to 0.693, and
the survivor at 0.4206 is still named in `left_standing`. D59's own regression, a size
whose width and height both exceed its origin, is `DID NOT RAISE` on the parent and passes
here; 250 passed across nine template and skill files and 193 across five gate files, both
exit 0.
- Every calibration above re-measured on this tip rather than carried over from its branch,
and the invariant that the ten templates writing their own copy into their own boxes
reports nothing still holds at 211 pages and 2084 text-carrying boxes.
- End to end on the page that prompted the work: the delivered program's slide 6 with its
two hand-rolled sweeps replaced by one `clear_region` call, through the real script
backend, removes 25 shapes, renders both line charts without overlap, keeps the template
decoration, and puts the replaced title in the top slot instead of the arrow-group label
it used to reach.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
One severity rose: `displaced_copy` is BLOCKING. It is calibrated to zero findings on the
templates' own copy and fires on 1 of 25 delivered decks, on the page this work was reported
for. The move it asks for is one anchor attribute, which is why it is a refusal rather than
a warning. Rolling back is per decision - each D entry is one commit range.
Integration risk found and fixed here rather than in either branch: D49 reaching upward from
`services/measure` into `services/template` closed an import cycle with D55's
`house -> capacity -> fit` path and made every engine entry point unimportable. Neither
branch could see it alone. The upward reach is deferred to its call site.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Three reader-facing changes to the TUI transcript and the instance strip.
**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.
The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.
Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.
**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.
**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.
`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on a worktree at this branch's tip, against the current main tip:
- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0
No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Three user-visible changes, all inside the terminal UI:
- a tool call that returned something now opens to a capped preview instead of
staying shut. A reader who prefers it shut clicks once, and that decision
holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
has one column less for its name.
- the status ticker shows a different set of glyphs and words.
No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.
- [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
The three DAG control tools -- `cancel_dag`, `dag_status`, `resolve_dag_node` -- are
withheld from the provider schema on purpose, so the per-turn tool list carries nothing a
conversation that never starts a graph has any use for. The consequence is that the only
thing a model ever reads about them is another tool's result text, and that text retold
their arguments by hand in three separate places. The retellings had drifted: the
exception report spelled `decision`, the foreground report named no arguments at all, and
the orchestration guide gave a third wording. A model working from a JSON example in prose
rather than from a declared field reached for `action` instead of `decision` three runs in
a row and lost a call each time.
Each advertisement now carries the tool's own definition, generated from the registry, in
the same shape a visible tool gets. Three decisions worth naming:
- `ToolRegistry.hidden_definition` follows the same snapshot-or-live rule `get_definitions`
already uses, and refuses a tool that is *not* hidden -- a visible tool is already in the
array, so re-advertising it is the duplication this exists to end, and that is now
structurally impossible rather than a convention.
- `resolve_dag_node` authors `to_schema` to declare its shape dynamic. Its node schema
carries a `subagent` enum built from the hot-appliable agent table, so the snapshot taken
at wiring time would advertise the roster as it stood when the loop was built.
- The replan field's node shape is referenced, not inlined. `run_subagent_dag` is not
schema-hidden, so pointing at that shape costs 455 tokens where inlining it cost 1251.
The pointer names both routes rather than asserting residency: the tool list, or
`tool_search` for the graph tool when the list does not carry it, because
`DEFAULT_ALWAYS_VISIBLE` deliberately omits `run_subagent_dag` and above the compaction
threshold it is cataloged rather than offered. It travels in `description` rather than
`$comment`, which JSON Schema defines as a note to developers that implementations must
not present -- a normalizing provider would be entitled to drop it and leave the field
an empty object. A test pins both the route and the key.
The orchestration guide keeps what the three decisions mean and drops how to spell them, so
the field names now live only where they are generated. That guide's body reaches the model
only when it calls `read_skill`, while the report always arrives, so the authoritative copy
moved from the on-demand surface to the unconditional one.
The three tools remain absent from the provider schema. Nothing about the per-turn tool
list changes, and a conversation that never starts a graph pays nothing.
Deliberately not changed, having been considered:
- The two one-field tools are advertised in full even though the prose above them already
spells their only argument, which makes their 211 tokens largely redundant. Left for a
follow-up rather than special-cased here.
- The exception report keeps its two hand-written invocations beside the generated schema.
The foreground path wrapped that report and appended the definition a second time; it no
longer does, and a test pins the count at one.
They carry the concrete run and node ids and the judgement about when replanning is the
right answer, which a schema cannot express. A test reads the field names back out of
those invocations and requires each to be one the tool still declares, so the two halves
cannot drift apart silently.
- The CLI playbook path builds a graph tool without a renderer, matching its existing
omission of the reachability predicate: there is no model on that path to advertise to.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest` over the dag, registry, tool-search, wiring, subagent, playbook and skill
selection: 3282 passed, 5 skipped. The five skips are pre-existing and environmental
(they document that an effective uid overriding the write bit is answered yes).
- Six mutants, each killed by the test written for it:
`hidden_definition` returning nothing kills 3; removing the node-shape reference kills 2;
dropping the `to_schema` declaration kills 1; silencing the graph tool's accessor kills
2; stopping the report from appending the schema kills 1; flipping the node-shape
pointer to `$comment` kills 1.
- `lint-imports`: 8 contracts kept, 0 broken. The GitLab pipeline does not run this.
- `ruff check` and `ruff format --check` over every changed Python file: clean.
- `scripts/check_commit_messages.py`, `scripts/check_source_language.py` and
`scripts/check_large_files.py` over the branch range: all pass. The pipeline runs none of
these three.
- Rendered the finished text at each of the three code sites and read it as the model
receives it. That is what caught two defects the diff did not show: a missing separator
that ran a JSON object straight into the next sentence, and the `$comment` field above.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Model-facing text changes on three paths, and the orchestration guide loses its copy of the
argument shapes. A model that had learned the old prose still finds every field name, since
the generated schema names them all. No wire shape, no stored payload and no provider tool
list changes, so there is nothing for an existing client to renegotiate.
`hidden_definition` exposes only tools their owner hid from the schema, and only to the text
that already names them. It refuses everything else, so it cannot be used to read out a
schema the caller was not already entitled to call.
Rollback is a revert: the advertisement is additive text plus one new module, and the paths
that consume it degrade to their previous wording when the renderer is absent -- which is
the state a tool built without a loop is already in, and is covered by tests.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The three DAG control tools -- `cancel_dag`, `dag_status`, `resolve_dag_node` -- are
withheld from the provider schema on purpose, so the per-turn tool list carries nothing a
conversation that never starts a graph has any use for. The consequence is that the only
thing a model ever reads about them is another tool's result text, and that text retold
their arguments by hand in three separate places. The retellings had drifted: the
exception report spelled `decision`, the foreground report named no arguments at all, and
the orchestration guide gave a third wording. A model working from a JSON example in prose
rather than from a declared field reached for `action` instead of `decision` three runs in
a row and lost a call each time.
Each advertisement now carries the tool's own definition, generated from the registry, in
the same shape a visible tool gets. Three decisions worth naming:
- `ToolRegistry.hidden_definition` follows the same snapshot-or-live rule `get_definitions`
already uses, and refuses a tool that is *not* hidden -- a visible tool is already in the
array, so re-advertising it is the duplication this exists to end, and that is now
structurally impossible rather than a convention.
- `resolve_dag_node` authors `to_schema` to declare its shape dynamic. Its node schema
carries a `subagent` enum built from the hot-appliable agent table, so the snapshot taken
at wiring time would advertise the roster as it stood when the loop was built.
- The replan field's node shape is referenced, not inlined. `run_subagent_dag` is not
schema-hidden, so pointing at that shape costs 455 tokens where inlining it cost 1251.
The pointer names both routes rather than asserting residency: the tool list, or
`tool_search` for the graph tool when the list does not carry it, because
`DEFAULT_ALWAYS_VISIBLE` deliberately omits `run_subagent_dag` and above the compaction
threshold it is cataloged rather than offered. It travels in `description` rather than
`$comment`, which JSON Schema defines as a note to developers that implementations must
not present -- a normalizing provider would be entitled to drop it and leave the field
an empty object. A test pins both the route and the key.
The orchestration guide keeps what the three decisions mean and drops how to spell them, so
the field names now live only where they are generated. That guide's body reaches the model
only when it calls `read_skill`, while the report always arrives, so the authoritative copy
moved from the on-demand surface to the unconditional one.
The three tools remain absent from the provider schema. Nothing about the per-turn tool
list changes, and a conversation that never starts a graph pays nothing.
Deliberately not changed, having been considered:
- The two one-field tools are advertised in full even though the prose above them already
spells their only argument, which makes their 211 tokens largely redundant. Left for a
follow-up rather than special-cased here.
- The exception report keeps its two hand-written invocations beside the generated schema.
The foreground path wrapped that report and appended the definition a second time; it no
longer does, and a test pins the count at one.
They carry the concrete run and node ids and the judgement about when replanning is the
right answer, which a schema cannot express. A test reads the field names back out of
those invocations and requires each to be one the tool still declares, so the two halves
cannot drift apart silently.
- The CLI playbook path builds a graph tool without a renderer, matching its existing
omission of the reachability predicate: there is no model on that path to advertise to.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest` over the dag, registry, tool-search, wiring, subagent, playbook and skill
selection: 3282 passed, 5 skipped. The five skips are pre-existing and environmental
(they document that an effective uid overriding the write bit is answered yes).
- Six mutants, each killed by the test written for it:
`hidden_definition` returning nothing kills 3; removing the node-shape reference kills 2;
dropping the `to_schema` declaration kills 1; silencing the graph tool's accessor kills
2; stopping the report from appending the schema kills 1; flipping the node-shape
pointer to `$comment` kills 1.
- `lint-imports`: 8 contracts kept, 0 broken. The GitLab pipeline does not run this.
- `ruff check` and `ruff format --check` over every changed Python file: clean.
- `scripts/check_commit_messages.py`, `scripts/check_source_language.py` and
`scripts/check_large_files.py` over the branch range: all pass. The pipeline runs none of
these three.
- Rendered the finished text at each of the three code sites and read it as the model
receives it. That is what caught two defects the diff did not show: a missing separator
that ran a JSON object straight into the next sentence, and the `$comment` field above.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Model-facing text changes on three paths, and the orchestration guide loses its copy of the
argument shapes. A model that had learned the old prose still finds every field name, since
the generated schema names them all. No wire shape, no stored payload and no provider tool
list changes, so there is nothing for an existing client to renegotiate.
`hidden_definition` exposes only tools their owner hid from the schema, and only to the text
that already names them. It refuses everything else, so it cannot be used to read out a
schema the caller was not already entitled to call.
Rollback is a revert: the advertisement is additive text plus one new module, and the paths
that consume it degrade to their previous wording when the renderer is absent -- which is
the state a tool built without a loop is already in, and is covered by tests.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
`exec` gains two lanes, and the on-call plugin's own exec retires onto them.
- `machine=<registered id>` runs a short look on a registered machine through the connection registry (capped at 60 s, killed on both ends; longer work is a job). Looked up through the registry's `load()`; the refusal for an unknown id lists the machines the way `shown()` renders them, no address.
- `run_in_background` runs long mechanical work on this computer under a managed log. The two lanes never combine, which closes the accounting bypass where jobs were driven over raw ssh past the ledger.
- The local machine-lane command runs in its own session and the cap kills the whole group (TERM, grace, KILL); platform-aware, with `taskkill /T /F` where `os.killpg` does not exist.
- `raven connection add` keeps an ssh alias so transfers need no address in prompts.
- `ops_exec` retires onto trunk exec; a cap kill routes by the command's shape (transfers to the background lane, jobs to `ops_submit`).
Stacked on `fix/oncall-flow-submit-and-launcher`: until that merges, this MR shows its six commits too; after it merges the diff reduces to the seven commits of this branch.
## Type
- [x] Feature
## Verification
```
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents # clean
uv run pytest tests/test_shell_*.py tests/test_cli_ops_connection_commands.py tests/test_agents_oncall_flow_case_dict_tools.py tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_tools.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agent_loop_token_budget.py -q # 386 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD # clean
```
Field check: four launcher shapes run on the GPU machine's real shell on 2026-09-03 (self-detaching command refused, non-zero rc recorded, group kill leaves nothing behind).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
`exec` accepts two new optional parameters; `ops_exec` is gone from the on-call tool set (the model-facing text no longer names it). The machine lane hands the model no address or credential. Rollback is a revert of the squash commit.
## Related Issues
Split from !476 (closed), retargeted at main. Merge after `fix/oncall-flow-submit-and-launcher`.
## 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
On-call plugin (`agents/raven-oncall/plugins/oncall-flow`) fixes from the autoresearch runs 10 and 11 on a shared 2xA800 machine. Nothing outside the plugin and its tests.
- `ops_submit` reads machine occupancy across every sibling campaign before buying a round: two campaigns each pinned device 0 within two minutes and the second died of CUDA OOM.
- Check and reservation are one step under an advisory lock at the ops home (the host's portable file lock, so a Windows-hosted agent can submit); a fresh handle-less record counts as the machine's reservation for ten minutes, then it is the crash orphan it always was. The in-flight window is reproduced in a test and refuses.
- A trial whose idem_key is already a live sibling campaign's job is refused: the same measurement was bought twice under two names.
- The launcher writes the missing `result.json` when a job writes none, and a piped job reports the failing stage rather than the tee.
- A local exec cap kill routes over-cap work to `ops_submit` instead of leaving the model to retry by hand.
Review round 2 (2026-09-07): the launcher could publish success while a self-detached child was still running (a command ending in `nohup ... &` returned as soon as the shell did). The fix was sitting in a downstream MR; it is folded in here so this MR is whole:
Jobs stay in launcher custody and are admitted by declared resources. Design: `docs/specs/2026-09-03-resource-admission-design.md`; the launcher plan: `docs/plans/2026-09-03-launcher-custody-and-detached-jobs.md`.
- The launcher runs the child in its own process group; a command that detaches itself (nohup/setsid/&) is refused with the reason written to `result.json`; kills reach the whole tree; `ops_kill` says when it killed a live process. Measured 2026-09-03: three jobs escaped custody and were recorded as finished in ten seconds.
- Admission is by declared resources against the machine's capacity: `ops_declare` takes `gpus_per_job` on a GPU row (`cores_per_job`, optional memory, on a CPU row), refuses a declaration over capacity or a template that pins its own `CUDA_VISIBLE_DEVICES`; the system assigns device ids, exports `CUDA_VISIBLE_DEVICES`, records them in the ledger and shows them in `ops_tune_status`; spend is width x duration. Rows without capacity information keep the job-count gate; campaigns declared before this count as one unit.
- The host registry reader gains `capacity()` and the doctor lines beside it (a GPU row that cannot be counted is told; `concurrency` beside a capacity is reported as not read); the plugin carries its parity copy.
## Type
- [x] Fix
## Verification
```
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents # clean
uv run pytest tests/test_agents_oncall_flow_*.py tests/test_agents_oncall_launcher.py tests/test_shell_*.py tests/test_cli_ops_connection_commands.py tests/test_ops_connections.py -q # 1070 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
Ledger records gain `reserved_at` and `resources_held`; records without them read as before. `ops_declare` on a GPU row now requires `gpus_per_job`; a registry row for a GPU machine should carry `gpus: N` (inferred from `device: "N x ..."` otherwise). Rollback is a revert of the squash commit.
## Related Issues
Split from !475 (closed), retargeted at main. `feat/exec-machine-and-background-lanes` (!521) builds on this branch and should merge after it. !523 was folded into this MR and closed.
## Summary
The second reader's effort now travels in the OpenRouter request body. litellm forwards `reasoning_effort` only for models its own table flags as reasoning-capable and drops it for the rest, `glm-5.3-flash` among them, so the configured effort never reached the model and every page was read at its default thinking: 100 to 350 seconds a page, about 6700 output tokens. At the gateway's own low effort a page reads in 13 to 29 seconds with the same findings (measured page by page on a delivered 15-page deck). Readings run sixteen pages at a time with a 120s per-page timeout, and a build names the pages it just drew before the backlog. On the same task the reading dropped from 20 minutes over five rounds to under a minute over three.
Every finding goes into `review/ledger.json` and stays open until a re-reading of its page no longer sees it, or the author dismisses it by id with a reason (`ppt_review(project, dismiss=[{"id": "p14-a1b2c3", "reason": "..."}])`). Each build reply lists what is open, the kinds that cost a reader something first. The defect this answers: a live run's reader named a paragraph buried under an illustration on page 14, nothing answered it, and the deck was delivered three builds later with the paragraph still buried, because the reply that named it had scrolled past. A `figure` entry cannot be dismissed as "the template's own picture": template illustrations are placeholders and have to depict the page. The reader is also told what the user ruled out, so it stops asking for fixes the brief forbids.
Delivery is verified against the publish record (`state/published.json`, sha256 per file) and gets a PDF preview beside the deck, because the web surface previews PDFs and images but not pptx. A turn that published nothing is sent back twice before it may end; a turn that published a deck without naming the file in its reply is sent back once. `ppt_fetch` takes a list of urls and fetches them together.
The decisions and their measurements are written up as D24-D30 in `plugins-dist/ppt-engine/docs/ppt-raven-design.md`.
Stacked on !481 (the engine port) -- review that first.
## Type
- [x] Feature
## Verification
`uv run pytest tests -q -k "ppt_engine or agents_ppt_launcher or vendored or hatch_build or contribution_ledger or runtime_binding"` -> 3603 passed, 9 skipped on the stack. Two end-to-end web-gateway runs of a 15-page deck on this code (2026-09-03 and 2026-09-04) delivered with a PDF beside the pptx; the second read 28 pages in 54 seconds where the first spent 20 minutes on 23. `uv run ruff check` / `ruff format --check` clean; `python3 scripts/check_vendored_subagents.py` passes.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
`readerEffort` defaults to `low` in the shipped deck config; setting it to `""` restores the provider's own default. The ledger only reports -- it refuses no build and no delivery. The two turn-end guards re-sample at most twice and once respectively, under the loop's own rollback cap, so a stuck model costs a few extra calls rather than a hung turn. Rollback is reverting this commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The second reader's effort now travels in the OpenRouter request body. litellm forwards `reasoning_effort` only for models its own table flags as reasoning-capable and drops it for the rest, `glm-5.3-flash` among them, so the configured effort never reached the model and every page was read at its default thinking: 100 to 350 seconds a page, about 6700 output tokens. At the gateway's own low effort a page reads in 13 to 29 seconds with the same findings (measured page by page on a delivered 15-page deck). Readings run sixteen pages at a time with a 120s per-page timeout, and a build names the pages it just drew before the backlog. On the same task the reading dropped from 20 minutes over five rounds to under a minute over three.
Every finding goes into `review/ledger.json` and stays open until a re-reading of its page no longer sees it, or the author dismisses it by id with a reason (`ppt_review(project, dismiss=[{"id": "p14-a1b2c3", "reason": "..."}])`). Each build reply lists what is open, the kinds that cost a reader something first. The defect this answers: a live run's reader named a paragraph buried under an illustration on page 14, nothing answered it, and the deck was delivered three builds later with the paragraph still buried, because the reply that named it had scrolled past. A `figure` entry cannot be dismissed as "the template's own picture": template illustrations are placeholders and have to depict the page. The reader is also told what the user ruled out, so it stops asking for fixes the brief forbids.
Delivery is verified against the publish record (`state/published.json`, sha256 per file) and gets a PDF preview beside the deck, because the web surface previews PDFs and images but not pptx. A turn that published nothing is sent back twice before it may end; a turn that published a deck without naming the file in its reply is sent back once. `ppt_fetch` takes a list of urls and fetches them together.
The decisions and their measurements are written up as D24-D30 in `plugins-dist/ppt-engine/docs/ppt-raven-design.md`.
Stacked on !481 (the engine port) -- review that first.
## Type
- [x] Feature
## Verification
`uv run pytest tests -q -k "ppt_engine or agents_ppt_launcher or vendored or hatch_build or contribution_ledger or runtime_binding"` -> 3603 passed, 9 skipped on the stack. Two end-to-end web-gateway runs of a 15-page deck on this code (2026-09-03 and 2026-09-04) delivered with a PDF beside the pptx; the second read 28 pages in 54 seconds where the first spent 20 minutes on 23. `uv run ruff check` / `ruff format --check` clean; `python3 scripts/check_vendored_subagents.py` passes.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
`readerEffort` defaults to `low` in the shipped deck config; setting it to `""` restores the provider's own default. The ledger only reports -- it refuses no build and no delivery. The two turn-end guards re-sample at most twice and once respectively, under the loop's own rollback cap, so a stuck model costs a few extra calls rather than a hung turn. Rollback is reverting this commit.
- [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
The host held three machine-shaped things about a sub-agent, and all three are gone:
1. a per-node `machine` key reserved in the DAG tool's node `inputs`, which a node on a
flagged agent was rejected without;
2. a pre-dispatch check on both the graph and the spawn path that read the owner's
connection registry and refused the call while it held no usable row;
3. a `runsOnMachines` manifest and config flag naming which agent that check applied to.
Where a job runs is now settled inside the agent that runs it. That agent already reads
the same registry through its own `ops_connections` tool, and on an empty one it answers
with the seven things `raven ops connection add` asks for and tells the model to hand
that to the owner rather than look for a way onto a box. Nothing was lost from the ask
itself; only its timing moved.
The host keeps the registry: `raven/ops/connections.py`, the
`raven ops connection add/list/doctor` CLI, and the `RAVEN_CONNECTIONS` handoff that
points a sub-agent at the owner's store instead of a copy of it.
**One half of the flag was never about machines.** Watch-work steering reads the same
flag to answer a different question, which roster row owns run-and-watch work, so
deleting it outright would have silently taken that feature with it. That half is renamed
to `ownsWatchedWork`, and the declaration rides the agent table: `AgentRow` and
`AgentMeta` carry `owns_watched_work`, read off the validated config at admission, and
`oncall_agent` reads the metas the loop already holds. Nothing reopens config or a
folder's manifest, so the spelling question is answered once, at the one door, rather than
by a second reader free to disagree with the table being dispatched against.
A row or a manifest written before the rename still loads. `Base` sets
`populate_by_name`, so both `runsOnMachines` and `runs_on_machines` were valid, and the
validation alias carries both alongside the two new spellings. Without that the rename is
invisible: the model ignores the unknown key and the field defaults to `False`, which
cannot be told apart from the owner turning the steering off.
The on-call roster description gains one sentence asking the caller to name the machine
in the owner's own words. It is phrased that way on purpose: the calling agent has no
tool that can enumerate registered machines, so a sentence asking it to pick a
registered id would ask for something it has no means to do.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
- `ruff check raven/ tests/` -- All checks passed
- `ruff format --check` on every touched Python file -- already formatted
- `python3 scripts/check_vendored_subagents.py` -- clean, with `subagents/TREE_HASHES`
re-recorded for `raven-oncall` in this commit
- `python3 scripts/check_commit_messages.py origin/main..HEAD` -- clean
- `pytest tests/ -k "spawn or organ or watch_work or subagent or dag or config_schema or
ops_connection or registry"` -- 2318 passed, 16 skipped
- `pytest` on the directly changed suites (`test_watch_work.py`,
`test_agents_oncall_launcher.py`, `test_agents_code_launcher.py`,
`test_subagent_third_party.py`, `test_config_schema.py`, `test_ops_connections.py`,
`test_cli_ops_connection_commands.py`, `test_subagent_manager.py`) -- 495 passed
- The legacy spellings were reproduced both ways: against `origin/main` both
`runsOnMachines` and `runs_on_machines` set the flag on both third-party classes; each
of the four spellings now reaches the dispensed row and is named by `oncall_agent`,
driven through `discover_vendored_rows` and `_row_for` rather than through a stand-in.
- The new dispatch test was proved load-bearing by re-inserting an equivalent registry
gate into the spawn path and watching it go red, then restoring the file.
Rebased onto the current `main`, which had moved 21 commits. Four conflicts, all in
files this branch already rewrites: the two modules it deletes (`main` had only renamed
`vendored_folder` to `product_folder` inside them, so the deletion stands), the ppt
launcher test (`main`'s engine-delta assertion kept, with only the flag rename applied),
and the two `CONTEXT.md` entries (this branch's text, carrying `main`'s de-vendored
vocabulary). One follow-up commit repoints the admission test at
`discover_product_rows`, which is what `main` renamed the discovery helper to.
Pre-existing failures, captured as failing IDs and diffed against `origin/main` in a
separate checkout through the same interpreter, at the rebased head: 7 on each side,
identical, so 0 introduced. They come from the separately distributed `everos-memory` and
`raven_ppt` packages being absent, along with 69 collection errors from the same cause. All 16 come from the
separately distributed `everos-memory` package being absent, and the 60 collection errors
under `tests/test_ppt_engine_*` from the same environment lacking the ppt extras. The one
failure only `origin/main` shows is `test_the_folder_ships_exactly_one_roster_manifest`,
which trips on stray `subagents-backup-*.json` files in that checkout rather than on
either tree. `tests/test_agents_ppt_launcher.py` fails identically on both sides.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour changes, all deliberate:
- A graph or a spawn naming the on-call agent now dispatches on an installation with no
machine registered. The owner is still asked for one, by the sub-agent, one sub-agent
run later. That run is the cost of the change.
- The `machine` key in a node's `inputs` is no longer reserved, so a graph that sets it
is now passing an ordinary input rather than choosing a machine.
- No node prompt is appended the machine's facts any more. A node that needs to size work
to a box learns about it from the sub-agent that runs it, not from the graph.
`demos/oncall_heat2d` narrated the old refusal step by step, including a verbatim
transcript of it; its README is rewritten to the chain that now runs. The cold-start half
of that transcript has not been re-recorded live, and the README says so.
Two docstrings under `subagents/raven-oncall/Raven-Oncall/` are patched deliberately, and
`subagents/TREE_HASHES` is re-recorded for it: they are the vendored fork's own copies of
a claim this change makes false, and that source is where a reader of the on-call agent
would look for it.
- [x] Security impact considered -- the removal narrows what the host reads and what
reaches a prompt; no address or credential ever crossed into an agent's view, and that
split is enforced on the sub-agent side, which is untouched.
- [x] Backward compatibility considered -- covered by the legacy validation alias above.
- [x] Rollback path is clear for risky changes -- revert the commit; the registry file
format, the CLI and the sub-agent's own tools are unchanged, so nothing on disk needs
migrating in either direction.
Checked and deliberately not changed: `ThirdPartyOpenAISubagentConfig` never carried the
flag and still does not, so an OpenAI-kind roster row cannot be the watch-work
specialist. That gap predates this branch and closing it would widen the diff into an
unrelated transport.
## Related Issues
N/A