The release builds everos-cloud-memory's wheel and attaches it, but no
installer and no upgrade named it, so the only way in was `uv tool install
--with`, which the next `raven upgrade` undoes: uv replaces the tool's
requirement set with what the command names, and the upgrade names the
release's plugin list alone. A user who picked the cloud backend was told to
install a plugin that had no install path.
The live-service gate that kept it out is met: the six key-gated tests in
tests/integration/test_everos_cloud_real_cloud.py ran against api.evermind.ai
on 2026-10-09. So the distribution joins the list a complete install is made
of -- release.yml, publish_beta.py for the beta channel, both installers'
local-clone lists, and the Docker image's three plugin defaults. Installed is
not selected: memory.backend still decides, doctor and the gateway build only
the backend it names, and the one visible change is that `raven onboard` asks
which memory backend to use rather than taking the only one installed.
The rung that drops the product engines kept only everos-memory. That rung
exists so long-term memory outlives a native build a platform refuses, so on
such a machine every upgrade uninstalled the cloud backend from under a host
configured to use it. install.sh, install.ps1 and the upgrade helper now keep
both memory distributions, and the contract test reads which those are off the
backend/distribution pairing rather than naming one by hand.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
The Mirasim adapter keeps one WebSocket connection to the Mirasim host
already running on the machine. It replaces the per-request `mirasim
ui-cli` processes and streams the host's session snapshots through ACP.
- Find the host through `RAVEN_MIRASIM_HOST` (`unix:<path>`, or a
loopback port as `<port>`, `127.0.0.1:<port>`, `localhost:<port>` or
`[::1]:<port>`, connected to as named), else the remote host's Unix
socket (Linux and macOS), else the desktop app's loopback port and its
token file. Tokens travel in headers. The adapter never requests
`ready` or `getConfig`, whose answers contain settings and
credentials. The WebSocket upgrade is bounded by the connect timeout.
- Stream text, thoughts, tools, sub-agents, plans, delivered files,
usage and accepted steers. Reconnect with backoff, resubscribe
sessions, and take a fresh snapshot when patches have a sequence gap.
- Live patches carry no segments; only settled history turns do. Within
one patch a call already shown settles before the text after it, and
a new call follows the text before it. A snapshot taken whole, on
subscribing, after a gap or when a queued turn is dispatched, puts its
calls before its text, so the answer after a call stays one message.
History replays in its segments' order, using the host's UTF-16
offsets.
- Support new, load with complete history replay, resume without
replay, list, close and delete. A turn running in the app while a
session loads is forwarded after the replay. Lists cover this agent's
conversations in the given directory, ones begun in Mirasim included.
Delete also removes the Mirasim conversation. A conversation the host
refuses to continue, deleted or not one of its own, is started again
once, with a note saying why. A list or history request the host
fails is refused at once with its reason, and history paging stops if
the host hands back a page it already gave.
- Cancel running tasks with `stop` and queued prompts with `recall`.
Prompts accepted after timeout remain tracked for cleanup and session
persistence. Failed or unconfirmed steers are recalled; if they
started their own task, that task is stopped by id. A prompt still in
the host's queue when the connection comes back is recognised from
the queue the host lists on resubscribe.
- Relay approvals and questions of turns Raven started through ACP
permission and elicitation requests; questions in turns Mirasim starts
are left to the app. Claude receives inline images; other agents get
an image linked as a local file as its path, and refuse inline ones.
Claude, Codex, DSH, Pi and ZCode support steering. Turns started in
Mirasim are forwarded while the adapter holds their session.
- Refuse queued prompts after session close or adapter shutdown. Every
local ACP agent whose tree a Windows Job or POSIX process group owns
gets an EOF grace that ends as soon as the agent exits. An agent may
ask for a longer one under `agentCapabilities._meta` as
`raven.shutdownGraceS`, granted up to five seconds; the Mirasim
adapter asks for five, so a first prompt the host accepts late is
still stopped. A close cancelled during the grace still releases the
connection. PID-only cleanup keeps the launcher alive for the
process-tree walk.
- The question of which agents Mirasim has runs in the environment the
presets' adapters get: the login shell's on Linux and macOS, Raven's
own on Windows. With no host reachable it lists none, and the boot
handshakes no Mirasim preset except a row that sets
`RAVEN_MIRASIM_HOST` or `MIRASIM_HOME` in its own `env`.
`readyTimeoutMs` is 150000, above the adapter's own connect and menu
limits.
The old `uicli.py` and `guard.py` transport is removed. Existing binding
files remain readable. The agent-integration documentation is updated
in English and Chinese. The Windows ACP job exercises the loopback
transport, real preset subprocesses and teardown. The live suite claims
a slot directory of its own by a lock, sweeps only that slot, and checks
the model each turn ran on.
`scripts/check_mirasim_frames.py` checks a host bundle for the frames
and fields the adapter uses. Run against the bundle that last worked, it
also reports each of those names that now occurs fewer times, which is
how a frame renamed in one of several places shows.
Protocol details verified against the host bundles 0.0.537, 0.0.547 and
0.0.558: `listSessions` filters by workdir, `getHistory` pages
backward, any prompt can set the session's route, there is no
unsubscribe frame, a request whose handler throws is answered with an
error carrying its `reqId` as `clientRef`, and live patches never carry
`segments`. Deleting a Mirasim conversation leaves the underlying
agent's transcript files intact.
## 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
Final local verification ran on Linux with Python 3.12.13 at the head
of this branch. Temporary report paths are abbreviated as `$CHECKS`.
```sh
PYTHONDONTWRITEBYTECODE=1 uv run --frozen --no-sync pytest \
tests/test_acp_mirasim_catalog.py tests/test_acp_mirasim_host.py \
tests/test_acp_mirasim_input.py tests/test_acp_mirasim_interactions.py \
tests/test_acp_mirasim_server.py tests/test_acp_mirasim_store.py \
tests/test_acp_mirasim_stream.py tests/test_check_mirasim_frames.py \
tests/test_subagent_mirasim.py tests/test_acp_client_teardown.py \
tests/test_acp_windows.py tests/test_acp_client_launch.py \
tests/test_acp_client_resume.py tests/test_subagent_probe.py \
tests/test_subagent_third_party.py tests/test_subagent_acp.py \
tests/test_acp_protocol.py \
-n 0 -q --tb=short --idle-ceiling-strict -p no:cacheprovider \
--cov=raven --cov-branch \
--cov-report=json:$CHECKS/coverage.json \
--junitxml=$CHECKS/regression.xml
# 1060 passed; no failures, errors, skips, or strict-idle violations
uv run --frozen --no-sync python scripts/coverage_gate.py \
--coverage-json $CHECKS/coverage.json \
diff --base-ref origin/main --threshold 90
# 99.20%: 1362 of 1373 executable changed lines
UV_NO_SYNC=1 make lint-python lint-types
# Ruff check/format: 2384 files; ty passes
uv run --frozen --no-sync lint-imports
# 10 contracts kept
uv run --frozen --no-sync deptry raven
# No dependency issues
uv run --frozen --no-sync pre-commit run --files <changed files>
# All applicable hooks pass
UV_NO_SYNC=1 make check-commits check-large-files check-source-language
# commitlint, commit messages, assets and source language pass
git diff --check origin/main...HEAD
# Exit 0
UV_PROJECT_ENVIRONMENT=$CHECKS/docsenv uv run --frozen --group docs \
--no-dev mkdocs build -f docs-site/mkdocs.yml --strict -d $CHECKS/site
# Built
for v in 0.0.537 0.0.547 0.0.558; do
uv run --frozen --no-sync python scripts/check_mirasim_frames.py \
~/.mirasim-remote/servers/$v/server.cjs \
--against ~/.mirasim-remote/servers/0.0.537/server.cjs
done
# Each: 13 sent frames, 11 read frames and 64 fields present,
# none fewer than in 0.0.537
PYTHONDONTWRITEBYTECODE=1 uv run --frozen --no-sync pytest \
tests/integration/test_acp_mirasim_real_llm.py \
-m integration -n 0 -q -p no:cacheprovider -rA --tb=short
# 10 passed in 346 s against the Mirasim host 0.0.537 running
# on this machine; every turn ran on glm-5.3-flash
```
Each new regression test was observed failing before its repair: the
refused unknown conversation, the reconnect with a prompt still queued,
the tool that ran while the connection was down, the turn running in
the app during a load, the repeated history page, the failed list and
history, the upgrade that never answers, the descendant holding the
agent's stdout, the close cancelled during the grace, the first prompt
the host accepts after the grace has passed, the empty agent list with
no host, the ready budget, and the frame check's count drop. The
stand-in host now hands frames to its dispatcher concurrently, as the
host does; removing the adapter's late recall makes three tests fail.
The frame check reports, against 0.0.537, copies with the dispatcher's
`stop` case renamed (6 occurrences, then 5), the six patch frames
renamed, and `coalesceMs` renamed; presence alone passed all three.
The local pass used the loopback stand-in host and real subprocess
tests; the live-model suite then ran against the Mirasim host already
running on the machine, across claude, codex, pi and zcode. Native
Windows and macOS were not run for this revision; the Windows ACP CI
job runs the four adapter test files natively.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
- Mirasim presets need a reachable host. Preset discovery still checks
for `mirasim` on the login PATH; a desktop-only install without that
executable does not offer the rows. The adapter's old `--executable`
argument is removed.
- The adapter is one more client of the user's own host: Raven's turns
show live in the Mirasim app and on paired phones, queue behind the
user's own turns on the same conversation, and end if the desktop app
closes or the host restarts. Turns the user starts in Mirasim on a
conversation Raven holds are forwarded to Raven as turns nobody
prompted.
- Removing an ACP instance now deletes its Mirasim conversation as well.
Loading a session replays its complete history. The host has no
unsubscribe operation.
- The desktop token is sent to the configured loopback endpoint, as
with `ui-cli --port`; discovery relies on the local token file and
port.
- Every local ACP agent's EOF grace now ends when the agent exits
rather than when its pipes close; an agent can ask for up to five
seconds. An unreachable host, abrupt parent death, or an adapter that
cannot finish within its grace can still prevent cancellation of work
owned by the shared host.
- Known limit: a queued prompt the host dispatches while the connection
is down is not recognised as this adapter's after it reconnects; it
is given up after 60 seconds and its turn runs on, forwarded as one
nobody prompted.
- Rollback: revert the squash commit to restore the per-request
transport. No binding migration is required. Conversations already
deleted from Mirasim are not restored by reverting code.
## Related Issues
N/A
## 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>
<img width="2318" height="1448" alt="image"
src="https://github.com/user-attachments/assets/bca71d69-4972-420c-b14e-c8cf74a17de9"
/>
## Summary
Everything a knowledge base could not read, and the pieces it cut them
into
saying what they are.
**Reading a PDF.** A PDF records glyphs at coordinates; whether they are
a
heading, a table cell or a running footer is inferred from how they
look. There
are now two readers. The geometric one infers structure from type size
and
position and needs nothing but the file. The other asks deepdoc's
models, ported
into `raven/knowledge/parser/deepdoc`: a layout model that says what
each region
is, a detector and recognizer that read a page carrying no text at all,
and a
table-structure model that rebuilds a grid from a picture of one.
Detecting boxes around text the file already spells
out exactly costs an inference pass per page to learn less, and
recognising it
costs accuracy.
The layout graph answers with a shape its own postprocessing
raises on, and its classes are DocLayout-YOLO's order rather than the
list
Both were established by running the model, and the label order is
pinned by a test.
**Tables go in as tables.** `<table>` is the only shape that keeps what
a grid
states -- which column a cell stood under, which cells are merged, which
row is
the header -- and it is the shape a model reads a table in, which is
what these
chunks are for. PDF, Word and PowerPoint all state their merges exactly,
and
they now survive as `colspan` and `rowspan`. The flat form this replaces
had to
repeat a header standing over two columns across both of them, because
there was
nowhere to record a span; it had no callers left afterwards and is gone.
Two
deviations from upstream, both about what the string is for: every
cell's text
is escaped, where upstream interpolates it raw and a cell holding a `<`
produces
markup that is no longer a table, and the span attributes are written
only where
there is a span, where upstream emits `<td >` for every ordinary cell.
**A picture of where each chunk came from.** A chunk is a few hundred
words with
a page number on it, which is enough to cite and not enough to answer
whether
the parser read the page correctly. So every PDF chunk that knows where
it sits
carries one image: the regions it covers, cropped out of the rendered
pages and
stacked. here they are already structured in the parser's element spans,
so
the markers would only put text nobody wrote into the thing being
embedded.
The panel draws a chunk's tables as tables, parsed and
rebuilt as elements rather than injected: a person can rewrite any piece
from
that same panel, so what comes back from the store is user input however
it got
there.
**The page that reads them.** Upstream retired the knowledge page while
this
branch was out; it is rebuilt against the new architecture, and the half
that
never existed is the one a reader needs -- what a document actually
became once
it was cut and embedded. Documents sit in one-level folders and arrive
by four
routes: a file, a folder, a URL, a written note. Adding and indexing are
two
calls on the contract and nothing drains that queue on its own, so a
page that
stopped after the first left every upload saying Queued for good.
Opening a file takes the whole page: the document on the left, the
pieces the
index holds of it on the right. The left half is the file drawn as its
own
pages rather than framed by the browser's PDF viewer, which reads where
to open
once and answers to nothing afterwards -- and which nothing can be drawn
on.
Pages are rendered once and kept, and the region a piece was cut from is
washed
over the page it came from, placed in fractions of the page so the
picture's
own scale never enters the arithmetic. Clicking a piece takes the file
there;
double-clicking opens it for rewriting.
The pieces can be searched, filtered by state, turned on and off,
deleted,
rewritten and added to, one at a time or in a batch. Every one of those
was
already on the contract with no reader for it. A base's settings are
back and
fuller: how many pieces a search returns, how documents are cut, and how
much
prose comes with a table or a figure. The embedding model is a picker
while the
base holds no pieces and a stated fact once it does -- moving it then is
the
collection made again at the new width and every document re-cut, which
is not
a thing a panel does by being saved.
**An agent can read them.** The retrieval engine was there and nothing
could
reach it: no agent had a tool that opened a library. A reader now points
a
conversation at bases from the composer, the way they pin a working
directory,
and the selection rides in the same place -- the session's metadata,
bound
around the turn.
The tool takes a query and never a base. The scope is the reader's
choice, so a
model cannot reach material nobody offered it, and it is withheld where
nothing
was picked rather than offered and refused. A hit says which document
and page
it came from, because a hit a reader cannot place is a hit they cannot
check --
and the passages are pressable in the transcript, walking into the base,
the
document, the folder it is filed under and then the piece. A citation a
reader
cannot follow is a claim they have to take on trust, and the whole point
of
searching their own material is that they can go and look.
**The word segmenter and the resources.** `raven.core.Tokenizer` is
Infinity's
`rag_tokenizer`, ported: a forward and backward maximum match over a
dictionary
trie, with stemming and lemmatisation on the latin path. XGBoost is not
carried
over. None of the data lives in git -- the dictionary, the NLTK corpora
and the
ONNX graphs run to about a hundred megabytes, so `make fetch-resources`
on an
install and an optional Docker layer behind `RAVEN_RESOURCES` both point
at one
script. A checkout that could not reach the network still works, and
every
feature that reads this data says so when asked.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on macOS against Python 3.12, with the deepdoc weights fetched (the
model
tests skip without them):
```
uv run pytest 27450 passed, 111 skipped, 3 failed
npm run test --prefix ui-web 3276 passed
npm run test --prefix ui-tui 2106 passed
npm run type-check --prefix ui-web clean (tsc)
npm run lint --prefix ui-web clean (4 pre-existing hook warnings)
make lint-python clean (ruff check + format)
make lint-types clean (ty)
make lint-imports 10 contracts kept, 0 broken
make check-source-language clean
make check-large-files clean
make build-ui built, both boot snapshots match
node ui-web/scripts/check-css.mjs clean
node ui-web/scripts/check-class-namespace.mjs clean
```
The three Python failures are not this branch's and were each confirmed
on the
base alone: one asks a host without LibreOffice to refuse a render and
this host
has LibreOffice installed, and two simulation cases fail on an
unmodified
checkout of the base commit.
The RPC contract was regenerated for both consumers and both match it
(`npm run gen --prefix ui-web`, `npm run gen:rpc --prefix ui-tui`, then
`gen:check`). The page's boot snapshots and region goldens were
refreshed where
the composer bar gained a button, and each records that button and
nothing else.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
A PDF's tables, and a Word or PowerPoint file's, are now indexed as HTML
rather
than as header-prefixed lines. Chunk text changes shape for those
documents, so
a base indexed before this and searched after it holds both forms until
its
documents are reindexed; retrieval keeps working either way, because
both forms
are text. The same applies to how much prose a table or a figure carries
with
it: the setting now reaches as far as it says, where before it stopped
at the
nearest paragraph, so a chunk cut before this keeps the narrower context
until
its document is rebuilt. Rolling back is reverting the branch and
reindexing.
The deepdoc models are optional. An install that never ran `make
fetch-resources` reads PDFs geometrically, exactly as before, and says
so when
the models are asked for by name. Nothing here reaches the network at
request
time.
Chunk crops and rendered pages are written at index time and on first
view, both
under the state directory rather than in the repository, and both are
deleted
with their document. A page is immutable for the life of its document
id, so
the route serving them caches; the document route does not. All three
routes
take ids and no path, and the two image routes answer under the
strictest
sandbox in the tree.
What an agent may search is the reader's choice and nothing else. The
tool takes
no base argument, so a model cannot name one, and it is absent from the
schema
entirely for a conversation that named none -- a lane nobody pointed at
a base
is unchanged by this branch. The bases a session carries are stored
beside its
working directory and travel no further.
- [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
raven-research reports were written for a grader: fixed `## Answer` /
`## Findings` / `## Limitations` headings, HTTP codes beside links, and
a
chat reply that drifted from the file saved with `write_file`. This
branch
ships them in a reader layout and closes the gaps that product runs on
DeepSeek showed between the brief, the reply and the saved file.
Reader layout (`finalShape.reportLayout = "reader"`, on for
raven-research):
- The report opens with the answer as a blockquote, with no label or
bold
lead-in. Anything the brief asks the report to open with (a retrieval
date, the kinds of sources) follows in the blockquote. Delivery facts
the
brief asks back (path, counts) go on its last line, which the chat reply
keeps and the saved file leaves out.
- The body sits under its own `##` headings, using the brief's section
names word for word, numbering included, when it gives them. The last
section names what could not be verified (`## Limitations` in English;
the reply's language otherwise, with no English word in that heading).
The shape gate reads the last `##` section as the limits when no word it
knows names them, since no word list covers every language, and when
only the first heading has such a word with no body above it (a body
heading on export limits is body, not limits). The audit reads it the
same way and counts a body written as prose under the answer.
- Prose cites through markdown links, with no fetch status beside them.
A
brief that asks for link checks gets one table before the limits,
listing
every cited URL as fetched, with its status, marked blocked where the
site blocked the fetch.
- The layout is derived from the deep clause, so the evidence rules stay
one text. The shape gate, its reminder, rewrite prompt and interrupted
fallback, and `scripts/research_report_audit.py` read it as the same
three parts. A test pins the audit's limits matcher to the gate's.
Chat and file are one text: at turn end the delivered reply is written
over
the report file the turn wrote. Which file that is:
- A markdown file the turn wrote whole, or appended to or edited when
the
turn wrote it whole first or it still holds exactly what an earlier turn
of the session left in it. The session record keeps the sha256 the
session left in each report file, checked at turn start before any tool
runs. Any other file (a log the user keeps, a report the user changed
between turns) holds someone else's text, so it is never the report. A
later turn that only edits a report nobody else touched still syncs it.
- Whose `##` headings are at least half the reply's. On the
reader-layout
product runs a report draft shared 75-100% of its headings with the
reply, and a notes file saved beside the report shared none, so a notes
file or a source index is never overwritten, alone or beside the report.
- Of several such files, the one the reply names; when it names none or
more than one, every file is left alone.
The file keeps its `#` title when the reply has none. It is also left
alone
when the reply is not a report, or when the reply is under 80% of the
file's length, so a summary reply never replaces the report. The path is
read from the first line of the tool's result only, matched against the
tool's whole fixed wording, and the file tools now
refuse a path that carries a line break or other control character: they
echo the path into their results, so such a path could forge a second
result line naming a file outside the workspace.
Length and counts, measured rather than estimated:
- Every markdown write or edit gets a `[report length: ...]` line on its
tool result, carrying:
- CJK characters and other words, with prose and tables apart;
- the same counts per `##` section;
- the number of distinct URLs cited, extracted the way the research
trail extracts them.
- The report checks a brief's length against that line, and takes any
count it states (sources included) from it.
- `write_file` now reports bytes. Its success line said "N bytes" and
counted characters, so a Chinese report was sized at about a third of
its real length.
Fetch status and the research trail:
- The research fetch tool reports the target's own status from the Jina
reader's header instead of the reader's 200, and marks a CAPTCHA wall as
`blocked`.
- The trail counts such pages as refused by the site, not as read, per
fetch: a page refused once and read on a retry counts as read. When a
thin page is re-read at another address, each address keeps its own
status: the stub its own, each fallback the one in its own header.
- The trail drops click-tracking parameters (`utm_*`, `srsltid`,
`gclid`,
`fbclid`, `msclkid`) before matching a citation.
- Its `<details>` folds are now plain labelled lists, since a terminal
shows the tags raw.
- `scripts/research_report_audit.py` reads the refused-page clause and
note. It also reads the reviewer verdict when the trail names the
reviewing model. That second break predates this branch: a model id
carries `/` and `-`, so the verdict read as missing on every product
trail.
Other:
- The research reviewer now runs on DeepSeek in thinking mode. That
provider refuses a named `tool_choice` with HTTP 400, so every review
failed open and each report shipped unreviewed. The gate retries with
`tool_choice=auto`.
- `measuredGuidance` is off in the shipped config. Its numbers were
measured on a short-answer benchmark and pull a long report toward a
terse answer.
- The appendix twin's guard names the twin's lead over the frozen dr@3.5
record instead of requiring the two to be equal: 4 added and 5 changed
definitions, with `ResearchTrail` compared member by member so its
untouched members stay pinned. The record itself is unchanged from
`main`.
- The product label moves to the `-reader` suffix. Its digest was
re-stamped several times on this branch only; `main` never shipped an
intermediate digest.
Checked and deliberately not changed here:
- The main agent's own `web_fetch` (`raven/agent/tools/web.py`) also
reads through Jina and still reports the reader's 200 for a target
error. It is a separate module, not a twin of the research tool, so it
needs its own change.
- `fetch_result_ok` is unchanged, so a page the site refused still
releases the fetch gate, counts toward the evidence floor and enters the
conversation memo as a source. Changing it would move when the gate
releases.
- The report sync writes the file directly, not through `write_file`, so
it
emits no file-change event and a client's diff panel does not show it.
raven-research runs with no write approval, so no approval is bypassed.
- Every CAPTCHA flag in 36 local fetches that carried a reader warning
was
on a page of 862 characters or fewer. Target errors appear on pages of
up to 18k characters, and each one checked was a real error page. No
false positive was found.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run after rebasing onto the current `origin/main`. The range-diff
against
the pre-rebase branch is `=` for all 15 commits.
- `uv run pytest tests/test_agents_research_*.py
tests/test_research_*.py tests/test_filesystem_write_modes.py
tests/test_agent_tools_web_fetch.py tests/test_history_trimmer.py
tests/test_context_engine*.py -q`: 1070 passed.
- Full suite before the rebase, `uv run pytest tests -q`: 27745 passed,
118 skipped, 12 failed. None of the 12 were introduced by this branch:
- 11 fail identically in clean worktrees of `origin/main` and of the
branch head. They are environment-bound: proxy redaction, NAT64
addresses, the node path.
- `test_agents_ppt_launcher` passes in the clean branch worktree and
failed only because of an uncommitted local edit to
`agents/raven-ppt/subagent.json`.
- Mutation checks: each of these, reverted alone, turns its new tests
red:
- the target-status override;
- the refused-page split;
- the ledger classification;
- choosing the named report file (3 tests fail with `paths[-1]`);
- the audit's refused clause;
- the audit's ` via ` terminator.
- After the second review round:
`uv run pytest tests/test_agents_research_*.py tests/test_research_*.py
tests/test_filesystem_write_modes.py tests/test_filesystem_tools.py
tests/test_deliver_files_tool.py tests/test_rpc_files.py
tests/test_rpc_turn_send.py tests/test_tool_registry_execute.py
tests/test_tools_workdir.py tests/test_agent_tools_web_fetch.py -q`:
1238 passed. Each fix, reverted alone, turns its new test red: the
control-character refusal, the first-line read, the append rule, the
last-section limits (gate and audit apart), the fallback verdicts, and
the URL count, the per-fetch refusal, the draft-heading filter and the
session-wide edit rule. The twin guard fails on an undeclared definition
and on a
stale lead entry.
- After the third review round, on the rebased head:
`uv run pytest tests/test_agents_research_*.py tests/test_research_*.py
tests/test_filesystem_write_modes.py tests/test_filesystem_tools.py
tests/test_deliver_files_tool.py tests/test_rpc_files.py
tests/test_rpc_turn_send.py tests/test_tool_registry_execute.py
tests/test_tools_workdir.py tests/test_agent_tools_web_fetch.py
tests/test_history_trimmer.py -q`:
1278 passed. Mutants each turn the new tests red: the unanchored
unchanged-file match; the control-character guard narrowed to LF, or to
`Cc` only; each of the four success lines reworded in the real tools;
a twin-only change to an untouched `ResearchTrail` default.
- After the fourth review round, same command: 1288 passed. Mutants each
turn the new tests red: held files taken without the digest check, the
digest never recorded, held files ignored, the first-heading rule
reverted in the gate and in the audit apart, the gate's body-above
condition dropped, and the audit's prose-body count dropped.
- `make lint-python`, `make lint-imports`, `make lint-deps`,
`make lint-types`: all pass.
- `scripts/check_commit_messages.py origin/main..HEAD`,
`scripts/check_source_language.py origin/main...HEAD`,
`make check-large-files`: all exit 0.
- Product runs through the TUI host, on reports about personal agents,
AI
glasses, AI coding agents, office agents and edge AI:
- The saved file equals the reply, less the delivery line, with its
title kept.
- The stated length and source count match the `[report length]` line.
- The link-check table has one row per counted URL.
- A Gartner 403 and an HBS 405 behind a CAPTCHA came through with their
real status.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes:
- raven-research replies and saved reports change form: an answer
blockquote, no fixed headings, no HTTP codes beside links, and a single
link-check table.
- The report file a research turn wrote is overwritten with the
delivered
reply at turn end, except in the cases above.
- `read_file`, `write_file`, `edit_file`, `list_dir`, `deliver_files`
and
the RPC file reads refuse a path containing a line break or other
control
character (they share `resolve_path`).
Existing installs keep the contract they seeded into
`agent_memory/profile/agent.md`. The new layout reaches them only after
that file is deleted; until then the gate still accepts the old
three-heading replies. The changelog says so.
Not covered by this branch:
- The research subagent pins `contextWindowTokens` to 65536. On a host
model with a 1M window, the budget note reaches 80-136% early and cuts
research short. Left as is on purpose; it is a separate decision.
- Post-delivery behaviour of the host agent is unchanged. It may recount
or edit the report after delivery.
Rollback: revert the squash commit. To keep the code but drop the
layout,
set `finalShape.reportLayout` to `"sections"` in
`agents/raven-research/config.json`.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: userName20260323 <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
- The missing-boxlite advice told users to run `pip install
'raven[sandbox]'`, which is wrong twice over: the `raven` name on
package indexes resolves to an unrelated project, and a global pip
install bypasses the uv environment raven actually runs in (#640).
- Added `boxlite_install_hint()` to `raven.sandbox`: it resolves the
pinned boxlite requirement from the installed distribution metadata
(falling back to the bare name when metadata is absent) and renders a
copy-pasteable command targeting the running interpreter, e.g. `uv pip
install --python /path/to/venv/bin/python boxlite==0.9.5`.
- The onboarding screen keeps its translatable line in the zh catalog
and prints the command on its own untranslatable line;
`build_executor`'s ImportError message uses the same hint.
- The two init-failure messages that fire after the boxlite import
already succeeded no longer suggest a reinstall; they keep the platform
bullets naming the actual causes.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Commands run on macOS, Python 3.12, on top of a clean checkout of main:
- `uv run pytest tests/test_sandbox_unit.py
tests/test_cli_onboard_commands.py tests/test_i18n_boundary.py
tests/test_i18n_prompts.py -q` -> 467 passed. The new tests
(TestBoxliteInstallHint, TestInitFailureAdvice, one TestBuildExecutor
case, one onboard screen case) were each watched failing before the fix.
- `uv run --frozen --python 3.12 --all-extras pytest -q` -> 27002
passed, 109 skipped, 21 failed. The 21 failures reproduce identically on
unmodified main (verified by stashing this change):
`test_agents_research_tools.py` (13),
`test_agents_research_verbatim_sink.py` (5),
`test_simulation_scenario.py` and `test_simulation_suite.py` (2),
`test_rpc_files.py::test_a_host_without_libreoffice_says_so` (1,
LibreOffice not installed locally). None touch the changed modules.
- `uv run ruff check` and `ruff format --check` on the six touched files
-> clean.
- `make lint-imports` -> 10 kept, 0 broken.
- `make check-source-language` -> pass.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
- User-visible change: three messages read differently (the onboarding
hint, the build_executor ImportError, two executor init-failure
messages). No API, config, or behavior change beyond the wording. The
hint assumes uv on PATH, which every documented install path already
requires.
- Rollback is a straight revert of this commit.
## Related Issues
Fixes#640
## Summary
Add a self-contained git-story-film skill for turning repository history
into animated product stories, including the drawing engine, production
helpers, and a complete Raven example.
- Provide English instructions and a Chinese README while preserving the
Chinese film variant and bilingual captions.
- Fix bundled example script paths and bring the Python helpers into
compliance with Ruff.
- Keep the bundled storyboard as a text-only reference with all 24 shots
and bilingual captions. No pre-rendered images are bundled; the studio
draws storyboard frames from code.
- Allow only the required example HTML and localized source data through
the repository gates. Keep the 1 MiB limit; standalone images, generated
exports, neighboring paths, and unsupported assets remain blocked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
- `uv run pre-commit run --from-ref origin/main --to-ref HEAD`: all
applicable hooks passed after rebasing onto the latest upstream main.
- `make lint-python`: passed, including format checks for 2,147 files.
- `make lint-types`: passed.
- `make lint-imports lint-deps`: passed; all 10 import contracts held.
- `uv run ruff format --check skills/git-story-film`: passed.
- `uv run ruff check skills/git-story-film`: passed.
- `uv run pytest tests/test_large_file_check.py
tests/test_source_language_check.py -q -o addopts=''
--idle-ceiling-strict`: 50 passed.
- `make check-large-files check-source-language`: passed on the complete
committed PR diff.
Full CI, browser playback, and MP4 rendering have not been verified
locally.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
The skill is an optional development tool and does not change Raven
runtime behavior. Repository policy exceptions are limited to documented
paths; other assets and oversized files remain blocked. Roll back by
reverting this change, including the skill and its matching gate
exceptions.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Co-authored-by: Codex <noreply@openai.com>
## Summary
Starting a gateway started LibreOffice. Fifteen seconds after every boot
the
template picker's covers were drawn on the host: ten conversions, three
at a
time, for a gallery most readers never open. On macOS those are three
icons
in the Dock on a start that was asked to do nothing of the kind.
The covers only depend on the templates the engine ships, so the release
renders them once instead of every installation rendering them again.
`scripts/bake_deck_template_covers.py` walks the template directory and
every
phrasebook beside it, writes one JPEG per template per language into
`raven_ppt/assets/templates/covers/`, and the ppt-engine wheel carries
that
directory. `deck_templates.shipped_cover` reads it before anything is
started, `cached_cover` and `cover_for` answer from it, and the warm-up
introduced in #624 then finds nothing missing and starts nothing. Twenty
covers, 398 KB.
The warm-up itself is unchanged, and so is the rendering path:
`shipped_cover`
answers None rather than raising, so a template dropped into the
directory by
hand, a language added after the build, and an install from source all
still
draw their own. Both the bake and the release gate read the directory
rather
than a list, so a new template or a new language is a new file and not a
code
change.
Two packaging lines were measured rather than assumed. Hatch reads the
ignore
file at the built project's root, and the rule lives at the repository
root,
so the `include` list alone ships the covers today; adding a
`.gitignore`
under `plugins-dist/ppt-engine` drops them to zero, which is what
`artifacts`
is there for. Both states were built and inspected.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run --frozen --python 3.12 --extra dev pytest
tests/test_rpc_deck_templates.py
tests/test_rpc_console.py tests/test_cli_serve_commands.py
tests/test_cli_gateway_commands.py
tests/test_ppt_engine_default_templates.py
tests/test_ppt_engine_templates.py -q`
-> 417 passed.
- Reverse check: with the two `shipped_cover` short circuits removed,
the two
new cases fail on the symptom they name (`a cover the wheel carries must
not
be drawn again`) -> 2 failed, 28 passed.
- End to end on one build, the only variable being whether the covers
are in
the package. Covers hidden: `drawing 10 missing cover(s)` and three
`soffice`
processes. Covers shipped: no log line, nothing queued, no `soffice`.
Run
against an empty RAVEN_HOME, in both `zh` and `en`.
- `scripts/bake_deck_template_covers.py` against the real package -> 20
covers,
398 KB; the `en` set carries English copy, checked by opening one.
- `uv build --wheel plugins-dist/ppt-engine` four times across the
include and
artifacts combinations -> 20 covers in the wheel, 0 without `artifacts`
when
a project-local `.gitignore` exists.
- `ruff check` and `ruff format --check` on the changed Python -> clean.
`scripts/check_source_language.py` and `scripts/check_large_files.py`
over
`github/main..HEAD` -> exit 0. `commitlint` on the commit -> exit 0.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- Nothing a reader sees changes: the picker shows the same pictures,
drawn by
the build rather than by their machine.
- The release job gains an apt install of `libreoffice-impress` and one
bake
step. If the bake fails the release fails there, rather than publishing
a
wheel whose covers are silently absent; the ppt-engine gate asserts one
cover
per template per language in the built wheel.
- An install from source has no baked covers and behaves exactly as it
does
today, rendering them once at boot.
- Rollback: revert the squash commit. Nothing is stored, cached or
migrated,
and a host with the old wheel keeps drawing its own covers.
- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
The channels section of the settings dialog drew a hashed letter tile
for every
entrance. It now draws each app's own icon, in the list row and in the
picked
channel's header, and every entrance is named in both of the web UI's
locales.
**Icons.** `ui-web/src/assets/channels/` holds eleven files:
- Nine are the icons the vendors publish on their App Store listings
(China
storefront for Feishu, DingTalk, WeCom, WeChat and QQ; US for Slack,
Telegram, Discord and WhatsApp), resampled from the 512px artwork to
96x96
PNG. For the five Chinese apps the listing is where a colour icon was
found:
the permissively licensed icon sets checked (lobe-icons,
`@cherrystudio/ui`,
SVG Logos, Simple Icons and the brand sets on Iconify) carry them only
as
single-colour glyphs.
- `matrix.svg` and `mochat.svg` are the files matrix.org and MoChat
serve as
their own marks, copied byte for byte.
- Mail is a protocol rather than a brand, so it gets a neutral envelope
drawn
in the component.
`scripts/refresh_channel_marks.py` names the listing or URL behind every
file and
regenerates the directory; `LICENSES/README.md` records the basis for
showing
them (the vendors' marks, identifying the row they sit on, as with
AMD's).
`ChannelMark` is keyed by channel id, never by the row's name, and falls
back to
the letter tile for an id with no mark and for a file that fails to
load. The
asset digest helper moves out of `ProviderMark.tsx` into
`lib/assetStamp.ts` so
both marks share it and a refreshed icon is not served from cache.
**Names.** Six brands bypassed the message catalogue with one verbatim
spelling,
and `gui.chan.mochat` held the Chinese name in its English slot. Every
entrance
now has a `gui.chan.<id>` entry in both locales (Slack, QQ, Telegram,
Discord,
WhatsApp and Matrix keep their Latin names in Chinese, as their own
Chinese
builds do), the verbatim path is gone (`ConnChannel.key` is required),
and the
English name is MoChat. The adapter's `display_name`, which the CLI
prints, and
the two channels docs pages also say MoChat. The TUI's generated
catalogue is
regenerated.
**Guards.** `tests/test_ui_channel_marks.py` holds the mark table equal
to the
adapters, the shipped files and the refresh script, and the PNGs to
96x96.
`catalogue.test.ts` holds every entrance to both locales and to English
in the
English slot. `tests/test_channels_display_names.py` holds the CLI and
the web UI
to one English name per channel.
`scripts/gates/channel-mark-css.test.mjs` reads
the expected box off `.pmtile`'s own rule, since the mark stands in for
that
per-container-sized tile.
**Also in this PR.** `.pre-commit-config.yaml` adds `channels/` to the
end-of-file fixer's exclude beside `providers/` and `agents/`:
matrix.org writes
`matrix.svg` without a trailing newline, and appending one would end the
byte-for-byte copy.
**Existing tests whose meaning changed.** `test_channels_mochat.py` now
expects
the MoChat display name; `source.test.ts` now expects every row, a brand
included, to be named through the message catalogue; the
`ConnectionsPage`
fixtures move from `name:` to `key:` (the stand-in translator hands a
key back
as its text, so no query changed); the DOM snapshot shows the mark in
place of
`.pmtile`.
**Deliberately unchanged.** Adapter docstrings, log lines and class
names keep
"Mochat" (identifiers and developer text, not a name a reader is shown).
The
TUI draws no channel list, so it gets no icons. The refresh script needs
the
network and is run by hand; neither CI nor the build runs it.
**Weight.** Eleven files, about 66 KB, copied into `dist/assets` and the
wheel.
Nine commits: the feature, then one per finding of the pre-submit sweep.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Suites ran before the last commit, which changes only
`.pre-commit-config.yaml`
and was checked with pre-commit.
- `npx vitest run --no-file-parallelism` in `ui-web/` (with
`NODE_OPTIONS=--localstorage-file=<file>`, needed under node 26): 202
files,
2790 tests, 2788 passed, 2 failed. The two are the "when storage
refuses"
cases in `src/features/desk/palette.test.ts` and `store.test.ts`, which
fail at
every revision under this machine's node 26 and pass under CI's node 22;
this
branch touches neither.
- `npm run gen:check`, `npm run lint` (0 errors, the 4 existing
warnings),
`npm run type-check` in `ui-web/`: pass. `npm run type-check` and
`node scripts/gen-i18n.mjs --check` in `ui-tui/`: pass.
- `npm run build`, `python3 ui-web/build.py`, `check-page.mjs`,
`check-css.mjs`,
`check-class-namespace.mjs`: all OK.
- `uv run pytest -q` with all extras: 25778 passed, 114 skipped, 1
failed:
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
which fails the same way on a checkout without this branch (this machine
has
npm on four PATH entries, which defeats its no-npm case).
- `ruff check` and `ruff format --check` over the Makefile's lint
targets: clean.
`lint-imports`: 10 kept, 0 broken. `ty check` on the changed modules:
clean.
- `uv run --isolated --frozen --group docs mkdocs build -f
docs-site/mkdocs.yml --strict`:
exit 0; both channels pages render MoChat.
- `pre-commit run --from-ref origin/main --to-ref HEAD`: every hook
passes except
prettier (ui-tui), which flags only
`src/__tests__/instanceModeCommand.test.ts`,
unchanged here (last touched by #669); CI's pre-commit job skips that
hook,
having no `node_modules`.
- `scripts/check_commit_messages.py origin/main..HEAD` and commitlint:
pass.
- Red first and mutants: every new case failed before its
implementation.
Mutants, each reverted with the tree clean after: no `onError` fallback,
a
failure kept as a boolean, marks keyed by name, the asset digest
dropped, `qq`
dropped from the table, the English name set back to "Mochat",
`.channel-mark`
resized, and a slot-specific `.pmtile` box. Each turned the tests
written for it
red: 1, 1, 3, 1, 3 Python guards, the display-name guard, and the CSS
gate twice.
- Browser, headless Chrome over the built page with `?stub=1`: all
twelve rows
draw a 38x38 mark with its file loaded and the digest in its URL, and no
letter
tile is left. The letter tile measures the same 38x38 with an 11px
radius in
both slots. English reads Feishu, Email, WeChat, WhatsApp, Telegram,
Discord,
MoChat, WeCom, Slack, DingTalk, QQ, Matrix. After Settings > General >
Chinese,
MoChat shows its Chinese name and the six brands keep their Latin names.
Matrix's mark follows the theme switch on a light OS.
- `raven channels list` from this tree: `mochat | MoChat`.
- `scripts/refresh_channel_marks.py` run twice: the second run
reproduced every
PNG byte for byte, and the two SVGs are `cmp`-identical to a separate
fetch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible: the channels section shows app icons where it showed
letter tiles,
and MoChat's English name changes from its Chinese name (web UI) and
from
"Mochat" (CLI). The other eleven names read as before. No config, RPC or
stored
data changes; `ConnChannel.name` was internal to `ui-web`. Rollback is
reverting
the squash commit.
- [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-5[1m]) <noreply@anthropic.com>
## Summary
The one-line installers are served from `main` and install the latest
published release, so an ending on `raven web` (PR #476) shipped against
v0.1.13, which has no `web`: since 2026-09-17 every `curl
raven.evermind.ai/install.sh | sh` has ended in `No such command 'web'`
with exit code 2. This PR fixes that class of failure and the upgrade
defect behind the next release.
- **Probe rule.** Every `raven <sub>` call in `install.sh` and
`install.ps1` is preceded by `raven <sub> --help`. When the probe fails
the install ends on the one command every release has (`raven`), and
neither the stop nor the page's own exit code becomes the script's.
`RAVEN_NO_LAUNCH=1` skips the launch (CI, Dockerfiles); the PATH hint
the launch displaced is back.
- **The release says what it ships.** `release.yml` writes
`raven-plugins.txt`, one `name @ url` line per plugin wheel it just
built, beside the wheel and the constraints. Both installers derive
every URL from the release page redirect and hand the list to `uv tool
install --with-requirements`. No GitHub API call, no grepping asset
names out of its JSON. A release without a list (0.1.13 and older)
installs raven alone, as it effectively did before.
- **Upgrade keeps the plugins.** uv replaces a tool's requirement set
with what one command names, so the old helper (`raven[channels]` only)
uninstalled every plugin the installer had put in. The helper now
installs from the same list, descends one loss at a time (engines, then
the memory plugin, then the channel extras), and refuses to run without
the list rather than install raven alone. `raven upgrade` on an
up-to-date install whose list names a plugin it lacks reinstalls the
version with its plugins. The helper also moves a beta wheel URL's
deploy token into the request header (urllib reads `user:token@host` as
a host name) and copies it onto the list's URLs for uv.
- **Gates.** CI installs the latest release with the PR's scripts,
piped, on ubuntu and windows whenever an installer changes. The release
job installs itself from `dist/` with `install.sh` before the draft is
created and asserts the three plugin packages and `web` on the result.
The beta publisher builds and lists the same three plugin wheels. A
contract test holds the release workflow, the beta publisher, both
installers (remote list and local clone mode) and the helper to one
plugin list.
Decisions, for the reviewer: the plugins are not published to PyPI and
no names are reserved there; the list carries direct URLs, so no plugin
is ever resolved by name against an index. The LibreOffice and chromium
steps in the scripts are unchanged. The three hosted-memory plugins
(mem0, zep, memos) are built and uploaded as before but stay off the
default list.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All installs below ran piped (`cat install.sh | sh`) in isolated
directories (own HOME, UV_TOOL_DIR, UV_TOOL_BIN_DIR, UV_CACHE_DIR,
RAVEN_HOME) with `RAVEN_MINIMAL=1`.
- `main`'s `install.sh` against the live latest release (v0.1.13): exit
2, `No such command 'web'`. This branch's `install.sh`, same
environment: exit 0, `Raven installed. Open a new terminal ... then run:
raven`; `raven --version` prints 0.1.13. With `RAVEN_NO_LAUNCH=1`: exit
0.
- A local release directory built by `scripts/publish_beta.py` (`_build`
at 0.1.14b1: raven wheel, three plugin wheels, constraints, list): this
branch's `install.sh` with `RAVEN_WHEEL_URL=file://...` installs raven
0.1.14b1, `python -c "import raven_everos, raven_design, raven_ppt"`
succeeds in the tool venv, and the uv receipt lists raven plus the three
plugins.
- The release workflow's two new step bodies (`Write the plugin list`,
`Install the release from dist with install.sh`) extracted and run
locally against that build: exit 0; removing one plugin wheel makes the
list step exit 1.
- The script's ending against the 0.1.14b1 install: `raven web --help`
exit 0, `raven web --stop` exit 0 with nothing to stop, `raven web
--foreground --port 18999` answers `GET /` with HTTP 200 after about 20
seconds.
- `uv run raven upgrade` and `uv run raven upgrade --check` from the
checkout against live GitHub: `Raven 0.1.13 is up to date.`, exit 0.
- `uv run pytest tests/integration/test_cli_upgrade_real_uv.py`: 2
passed. The test now installs the old fixture `--with` a companion wheel
and asserts the companion survives the upgrade; against `main`'s helper
the same test fails on that assertion.
- `uv run pytest tests/test_install_script.py
tests/test_release_plugin_list.py tests/test_updates_upgrade.py
tests/test_publish_beta.py tests/test_cli_smoke.py`: all pass (37 + 6 +
188 on the last run of each).
- `uv run pytest` (full suite, before the last installer rewrite): 23543
passed, 121 skipped, 4 failed. The 4 (`test_agents_oncall_launcher`,
`test_agents_code_launcher`, `test_agent_loop_token_budget`,
`test_ppt_engine_image_search`) fail identically on plain `github/main`
in a separate worktree.
- `uv run ruff check` and `uv run ruff format --check` on every touched
Python file: clean. `sh -n install.sh`, `bash -n install.sh`: clean.
Both workflow files parse.
- Not run here: the new CI job's Windows leg and the release gate inside
GitHub Actions (this PR is their first run). `install.ps1` has no local
PowerShell to execute it; its changes mirror `install.sh` and are pinned
by the text tests.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes: the installers no longer fail on a release without
`web`; they print the plugins they install and a warning when a release
carries none; `raven upgrade` refuses to proceed when the target
release's plugin list cannot be fetched (previously it would install
raven alone and drop the plugins), and repairs an up-to-date install
that lacks listed plugins. The beta channel's next publish carries the
three plugin wheels and the list; a beta upgrade to a build published
before this change will refuse for lack of a list, and rerunning the
beta installer is the remedy.
Rollback: revert the commit. Releases published with `raven-plugins.txt`
keep working with the old scripts, which ignore the file.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
A pull request whose base is not the default branch carries, in its
`BASE..HEAD` range, every commit the default branch has gained since the
two
diverged. Both commit linters read that range, so they re-read history
that
already passed this gate when it landed and that nobody can rewrite now.
#529 is the case that surfaced it: merging `main` into
`refactor/ui_web_architecture` puts 38 `main` commits in range, one of
which
(`b01534d0`, #471) carries a `Co-authored-by` trailer with a non-ASCII
name.
The gate reports that PR red for a message it did not write. The same
will
happen to every future catch-up merge.
`scripts/check_commit_messages.py` now takes several revision arguments
and
passes them to `git log`, so a caret exclusion works. Commitlint has no
equivalent flag, so the workflow iterates the same revision list and
lints one
message at a time. On a pull request the workflow excludes the
repository's
default branch; a push to the default branch is unchanged and still
lints what
it pushed.
This does not touch the offending commit on `main` and does not relax a
rule:
a commit that a PR actually introduces is linted exactly as before.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
`uv run pytest tests/test_check_commit_messages.py
tests/test_commit_lint.py -q`
-- 15 passed. Three of those cases are new and cover a repo where the
default
branch carries a rejected message and the feature branch merges it in:
the
range fails without an exclusion, passes with one, and still fails when
the
bad commit is the branch's own.
Mutation check on the new cases: replacing `_commit_messages(args)` with
`_commit_messages(args[:1])`, which is the behaviour before this change,
turns
`test_excluding_the_default_branch_skips_the_history_it_carries` red and
leaves
the other three green. The pin fails when the fix is removed.
Against the real history behind #529, with the checker run directly:
- `check_commit_messages.py "bc74bf73..a0666244c"` -- exit 1, naming
`b01534d02` exactly as CI does.
- the same range plus `^github/main` -- exit 0.
The workflow's new loop was run as written against both ranges: 0
commits to
lint on the catch-up range, and a planted `Update stuff.` commit on a
feature
branch still sets the failure flag.
`make lint-python` -- clean. `scripts/check_source_language.py` over the
branch
-- exit 0; the test's non-ASCII message is built from an escape, so the
file
itself stays ASCII.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Commitlint now starts once per commit instead of once per range, so a PR
with
many commits spends a second or so more in this job. The exclusion only
ever
removes commits that are already on the default branch, so nothing a PR
introduces escapes either linter.
Rollback is reverting this PR; the previous behaviour is one range
argument and
one commitlint invocation.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A. Unblocks the `commit messages` check on #529.
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
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
Nothing in this repo could see a signature change reach its callers.
Ruff reads one file at a time, the import contracts read edges rather
than calls, and the suite only covers lines it executes. The consequence
was concrete: a required `sandbox_home` argument added to
`BoxliteExecutor` reached `plugins-dist/design-engine`'s render path
with CI green, and a reviewer -- not a gate -- found it.
`ty` answers that question. This adds it as a pinned dev dependency, a
`make lint-types` target and a CI step, with **110 of its 133 rules
live**: nine switched off with their measured backlog recorded beside
each, fourteen shipped disabled upstream and untouched.
Getting there meant clearing 81 diagnostics. This PR folds what were
three stacked PRs (#422 and #423, now closed); each rule's story is a
commit of its own.
### 1. The gate, at 108 rules (`chore(*): gate call correctness...`)
21 diagnostics to clear, five of them real:
| Where | What |
|---|---|
| `evolver/orchestrator/production.py` | `design_of` annotated as taking
two parameters while its docstring, its only implementation and its one
call site all use three |
| `raven/cli/provider_commands.py` | `dict[str, callable]` -- the
builtin function, not a type, so the annotation asserted nothing |
| `raven/config/schema.py` | `Config` is a `BaseSettings` but declared
`env_prefix` / `env_nested_delimiter` through pydantic's `ConfigDict`,
which does not carry those keys |
| `raven/spine/delivery.py` | `StreamDelta.conversation_id` is optional
and was used as a `dict[str, str]` key; a delta without one stored a
`None` entry the close path then read as "no open stream", losing that
stream's done marker |
| `research_flow/support/harness_text.py` | a predicate table typed its
matchers as `object`, so nothing checked they are callable |
The rest were unproven invariants and annotations wider than the code:
three late-bound callables asserted where a comment used to carry the
claim, one closure binding the callable it guarded instead of re-reading
it, four `hasattr` probes that now check what the call actually needs,
and a contextmanager yielding the value it just set.
### 2. `unresolved-import` (`fix(*): resolve the imports the type gate
could not`)
21 diagnostics; three were stale module paths nothing had run into:
- `HarnessNode.current_core_version()` read `raven.__core_version__`, a
module that exists neither here nor in the wheel
`scripts/build_core_wheel.py` produces. The read sat inside `try/except
ImportError`, so the except branch was the only branch and **every node
`store.py` saved recorded `core_version="unknown"`**. It reads
`raven.__version__` now and returns `0.1.13`.
- `raven/agent/loop/wiring.py` imported `SkillForgeRouterConfig` from
`raven.config.schema`; it lives in `raven.config.raven`. Under
`TYPE_CHECKING`, so the annotation simply meant nothing.
- three scripts imported `raven.context_engine.base` and
`raven.memory_engine.base`, neither of which exists. **Two failed at
module import** -- running them was not possible.
The other eighteen were the environment: the three agent products keep
their plugin package beside them, so their roots are declared in
`[tool.ty.environment]`; `lxml` ships a compiled `etree` with no type
information, so `lxml-stubs` is a dev dependency (real types rather than
five silenced lines); `uno` and `com.sun.star.*` are suppressed per
line, since that worker runs inside LibreOffice's own interpreter.
### 3. `invalid-return-type` (`fix(*): make the declared return types
true`)
39 diagnostics, and **one stale annotation held eight of them**:
`run_turn` and the `_run_turn` behind it were declared `-> LoopOutcome`
while all three of their returns build a `TurnOutcome` -- a different
dataclass with no field in common. Nothing broke, because the spine
worker reads what it actually gets and `LoopOutcome` never leaves
`_run_agent_loop`. The annotation was the only thing wrong.
The other 31: nine annotations narrower than the code (five `return
tuple(<genexpr>)` typed as fixed-arity tuples, an inner `one()` still
declaring the two-tuple it returned before a third element was added,
`image_block`'s TypedDict), five declarations refusing a value the
function returns (four tool `execute` overrides saying `-> str` while
returning `ToolResult`), seven invariants that lived in a `# type:
ignore` comment, and ten honest widenings.
### 4. What the gates then caught in this PR's own work
- The qq factory guard passed locally only because an earlier test had
left an event loop behind. Reproduced the CI state
(`asyncio.set_event_loop(None)`), then made the test async so the loop
is its own.
- `invalid-return-type`, while still disabled, hid a regression
introduced here: the qq factory returning the class instead of an
instance. Found by diffing the rule histogram, which is why that rule is
on now.
- The diff-coverage gate named four lines in `raven/routing/cache.py` --
the asserts this work had just added, sitting inside a `try` whose
`except Exception` would have swallowed the `AssertionError` and served
the stale cache. `_do_refresh` returns its data now; the asserts, their
noqa and the swallowing all go with it.
`child_scope`, `QQChannel.start()` and `BenchmarkCache` had no tests at
all and have them now. Every one was mutation-checked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `make lint-types` -> All checks passed; 81 diagnostics cleared across
the three rule sets
- Gate proven live three times, once per rule: a missing argument, an
import of a module that does not exist, and a function returning a str
under `-> int` each turn it red, and removing the probe turns it green
- `uv run ruff check` + `ruff format --check` over all six trees ->
clean
- `uv run lint-imports` -> 10 kept, 0 broken; `deptry raven` (all
extras) -> no issues; `uv lock --check` -> resolved
- `make check-source-language` -> exit 0; `commitlint` -> exit 0
- `make coverage` locally: **22050 passed, 45 skipped, 4 failed**; diff
coverage 92.59%
- All four failures are **pre-existing on `main`**, checked by a real
checkout in the same environment where they fail identically: two
`test_the_products_tool_face_*` launcher tests,
`test_a_ceiling_as_large_as_the_window_still_leaves_room_for_history`
(`reserved_tools = 6044 > 6_000`), and
`test_a_missing_key_is_said_once_rather_than_per_query`
(environment-dependent: it asserts `SERPER_API_KEY` is absent)
- Rule counts measured with both `--extra dev` and `--all-extras` --
identical, so this gate's verdict does not depend on which optional
packages are installed
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Behaviour changes are confined to the fixes listed above, and each
replaces an error path with a correct one: nodes are stamped with the
real raven version instead of `"unknown"`, two scripts that could not
start now start, the stream bookkeeping no longer stores a `None` key,
and a cache refresh returns what it fetched. Everything else is a
declaration moved to match what the function already returned.
`tests/` is out of the gate's scope (113 diagnostics under the same
rules). Tests are executed, so a broken call there is already loud; this
gate is for code CI does not run. Bringing them in is sized, separate
work.
Rollback: revert the whole PR to drop the gate and its fixes together,
or delete the `[tool.ty]` block, the `lint-types` target and its CI step
to keep the fixes and drop only the gate.
- [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
Takes the provider registry from 24 specs to 55 and gives the web UI a
brand mark for every provider and model family.
<img width="1998" height="1356" alt="image"
src="https://github.com/user-attachments/assets/dd909dd3-c742-45d0-a94d-61ccb1e30a0e"
/>
Four groups of providers are added: Western labs and inference hosts
(xAI, Mistral, Together AI, Fireworks AI, Perplexity, Cerebras, Hugging
Face, Poe), CN vendors (Xiaomi MiMo, Baichuan, Baidu Cloud, StepFun,
LongCat, ModelScope, Qiniu), resale gateways (302.AI, DMXAPI, BurnCloud,
ocoolai, PPIO, Lanyun, AlayaNew, SophNet, TokenHub, Xirang, PH8, AIOnly,
AMD GPU Cloud) and self-hosted servers (GPUStack, OpenVINO Model
Server). BigModel, Zhipu's CN platform, joins Z.ai, and the two Zhipu
platforms fold into a single row in the provider rail.
LiteLLM routes nine of them from a key plus a prefixed id. The other
twenty-one speak OpenAI's API with no driver of their own, so each
borrows OpenAI's driver and is told apart by its address, the way
SiliconFlow already was.
On the web UI side the provider rail gains name and connection-state
filtering, drops the generic Custom row, and keeps its scrollbar off the
connection dots. Provider marks move from Lobe Icons to the vendors' own
colour marks, and LICENSES/README.md records the new attribution.
Three decisions worth a reviewer's attention:
- The two "read-only exec allowlist and approval grants" commits from
the source branch are left out, because that work is already on main.
This was verified by symbol rather than by commit subject: every def and
class the commits add is already present.
- The README prose edits are dropped. They updated a "Providers and
Gateways" paragraph that main no longer carries after the readme
restructure, so the text had no correct place to land. Only prose was
affected; no code was lost.
- The LICENSES/README.md conflicts were resolved by merging both sides
rather than taking one. The new Cherry Studio attribution entry and the
DMXAPI resampling note are kept, while main's sub-agent mark count
(fourteen, including this project's own raven.svg) is kept over the
incoming "thirteen", because fourteen is what the tree holds.
Three fixes landed on this branch after review, beyond the provider work
itself:
- Poe ships no default and no shortlist. Its ids were the maker's
spelling, and only the outer "poe/" comes off on the way out, so the
shipped default reached Poe as a model it does not have. Routing is
unchanged and a real bot id still works.
- The upgrade marker path is read from raven.home rather than through
raven.config, whose package imports pydantic. The handoff writes that
marker from the tool environment it is replacing, which has no such
dependency, so `raven upgrade` aborted before the helper was spawned.
This one is a pre-existing bug on main, merged in here rather than left
to a separate PR.
- Two pre-existing CI gates are repaired: check-page counted two inline
script blocks where page.html has carried three since the asset digest
was added, and a doctor test asserted a path that rich folds at a column
decided by the tmp directory's length. Both were failing on main as well
as here.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Ran the provider, catalogue, resolution, RPC, onboarding, doctor and
upgrade suites together: 1240 passed, 103 skipped, no errors. An earlier
run of these reported a collection error in
tests/test_cli_onboard_commands.py for a missing raven_everos; that was
an incomplete local environment, resolved by the uv sync that builds
plugins-dist, and not a property of this branch.
ui-web vitest: 104 files, 1704 tests, all pass. ui-tui: lint, lint:rpc,
lint:i18n, type-check, build all clean and 2072 tests pass.
The page gate was run end to end from a clean build: npm build,
build.py, then check-page, count-shared-globals and check-css, all three
green.
Ran `make check-large-files`: passes, nothing over the limit. The
largest touched file is 340 KB. `uv run ruff check` and `ruff format
--check`: clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes: the onboarding catalog and the settings page list
55 providers instead of 24, the provider rail gains a filter, the
generic Custom row is gone, and provider marks are now the vendors' own
colour marks.
Security: the twenty-one providers that borrow OpenAI's LiteLLM driver
inherit its built-in default endpoint, api.openai.com. A spec that kept
its own address to itself would post someone else's key there, so a test
sweep asserts every borrowed-driver provider either hands LiteLLM its
own default or is reached by address.
Backward compatibility: existing provider configuration keeps its names
and fields, so current configs continue to resolve.
Rollback: revert the squash commit. No migration or config rewrite is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
The unit job takes twelve minutes on one runner. The first cut of this
PR took the production waits out of the tests, which made the suite a
quarter faster on a laptop and moved CI by 14 s (pytest 720.95 s on
main, 706.57 s here): the runner is three to four times slower than a
laptop on CPU-bound tests, and two of the twelve minutes are the four
xdist workers importing every test module. So the PR now attacks the
wall clock from every side that CI's own numbers pointed at.
- `ci(*)`: the unit job runs as four shards. pytest gains `--shard K/N`
in `tests/conftest.py`, decided in `pytest_ignore_collect` so a shard
never imports the other shards' files; test files are dealt round-robin
over their sorted list so the slow families that sort together (the ppt
engine's) are spread out. Each shard writes coverage data and no report;
a `coverage` job downloads the four data files, combines them, writes
`coverage.json` and `coverage.xml`, and runs the gates that used to
follow the tests.
- `perf(ppt-engine)`: `menu()` caches its reading of a template, capped
at eight entries. One bind reads the bound template and then every other
bundled template for the borrow offer; with ten templates bundled, every
bind evicted what the next one needed and re-measured all of them with
freetype. The cap is 32 and a hit moves its entry to the back. On this
PR's first CI run the template-tool file alone was 257 s of the
over-ceiling list, its tests 10 to 26 s each.
- `test(*)`: an autouse fixture collapses the provider chat retry
ladder, the loop's LLM-error ladder and the memory store backoff to a
millisecond per step, and the steer hook grace to one poll. It keeps
each tuple's length because both ladders count attempts with `len()`;
the steps are a millisecond rather than zero because the store pipeline
waits with `wait_for(stopping.wait(), timeout=delay)`, and a zero
timeout cancels that wait before it runs. A test that proves a timing
property opts out with the new `production_timing` marker. Ten tests
spent 257 s of the suite's worker time in those waits; none asserted on
the time.
- `test(*)`: a wall-clock ceiling. Setup plus call over 2 s on a test
marked neither `slow` nor `production_timing` is listed at the end of
the run; `--wall-clock-ceiling-strict` fails an otherwise green session
on it. Warning only here; CI flips to strict once the remaining tail is
marked.
- `test(*)`: every test created two numbered temp directories, and
pytest picks each number by scanning the base temp dir; the fake home is
now a sibling of `tmp_path`. `MPLCONFIGDIR` points at a git-ignored dir
in the checkout, because the fake home changed per test and matplotlib
rebuilt its font list from the system fonts on every run.
- `refactor(agent)`: the outer LLM-error retry ladder default `(15, 30,
60)` lived in three places; it is one constant in
`raven/config/schema.py` now, read by both `RecoveryLimits` and
`_ladder`. Behaviour unchanged.
- `test(updates)`: the first sharded run turned up an order dependency.
`beta_channel` binds `ReleaseInfo` from `raven.updates.upgrade` at
import, the update-notice tests stand a fake in for that module through
`sys.modules`, and `_refresh` imports `beta_channel` lazily; a worker
that imported `beta_channel` for the first time inside that test got an
`ImportError` swallowed as a failed refresh. The test module now imports
`beta_channel` at the top.
- `ci(*)`: the PR diff gate named every `.py` under `plugins-dist` as
production code while coverage measures only `raven` and `raven_everos`,
so a change to the ppt or design engine could never appear in the report
and the gate refused every such PR on sight; the first sharded run hit
it on `menu.py`. The pathspec now names `plugins-dist/everos-memory`,
and a test holds every production pathspec to a package some `--cov`
flag in the Makefile measures.
- Two slow tests were not waits: the sandbox second-cancel test
cancelled one tick too early (two pending cancels coalesce into one
`CancelledError`) and now waits, under a one second timeout, for the
kill to land; the two thousand-session dispatch tests wrote a span per
refused enqueue through a store that opens its file per span, so tracing
is off for them. Follow-up on the product side: `raven/tracing/store.py`
should reuse its handle.
The suite has 30 upper-bound assertions of the form `assert elapsed <
X`; shortened delays can only make those looser.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Whole suite, `uv run --frozen --all-extras pytest -q` (macOS, 4
workers), 22051 passed / 43 skipped each time:
| tree | wall clock | unmarked tests over 2 s |
|---|---|---|
| main before this branch | 372.82 s | (no ceiling yet) |
| after the waits were taken out | 279.65 s | 63 |
| this branch | 224.25 s | 39 |
The shards partition the suite exactly (`uv run --frozen --all-extras
pytest --collect-only -q -n 0 --shard K/4`, K = 1..4):
| whole | shard 1 | shard 2 | shard 3 | shard 4 | union | ids in two
shards |
|---|---|---|---|---|---|---|
| 22095 | 5058 | 5555 | 5955 | 5527 | 22095 | 0 |
196 / 195 / 194 / 194 test files per shard. A shard collects in 7 s
where the whole suite takes 23 s on the same machine. `--ignore` still
works under `--shard`: with four `--ignore` flags on shard 1, the
ignored file that shard owns is gone from its collection (5034 ids
against 5058).
Combining loses nothing. Two small runs with `--cov=raven
--cov=raven_everos --cov-branch --cov-report=` and `COVERAGE_FILE` set,
then `make coverage-combine COVERAGE_DATA_DIR=<dir>`, against one `make
coverage` of the whole suite on main:
| report | files | statements | branches |
|---|---|---|---|
| one run of the whole suite | 704 | 82634 | 25548 |
| two shards combined | 704 | 82636 | 25548 |
Same file set; the two extra statements are the new constant and its
import. A source package's never-imported files reach the combined
report through the shard that imported it, as they reached the single
run.
The menu cache, the three files that bind templates (`uv run --frozen
--all-extras pytest -q tests/test_ppt_engine_template_tool.py
tests/test_ppt_engine_outline_checks.py
tests/test_ppt_engine_default_templates.py`): 101 s of worker time in
the last profile, now `196 passed in 11.84s` with no test over 2.9 s.
The files that call `menu()` directly: `219 passed in 8.06s`.
The font cache, the formula render test at `-n 0`: 8.91 s cold, 0.69 s
on the next run. Seven home-sensitive files: `484 passed in 5.30s`.
Ceiling guard, both modes, with the ceiling forced low so it has
something to list:
```
uv run --frozen --all-extras pytest -q -n 0 --wall-clock-ceiling=0.01 tests/test_import_cycle_budget.py tests/test_updates_install_guard.py
uv run --frozen --all-extras pytest -q -n 2 --wall-clock-ceiling=0.01 --wall-clock-ceiling-strict tests/test_updates_install_guard.py
```
First: 28 passed, five listed, exit 0. Second: 24 passed, four listed,
exit 1 (the controller flips the status; workers do not).
`make lint-python` clean, `make lint-imports` passes. The CI run on this
PR is the measurement that matters: four `unit` shards and one `coverage
gates` job.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none: CI
plumbing, a cache cap, test setup)
## Risk
- The coverage gates now run in a job after the four shards. A red shard
skips the gates, a deliberate trade: combining three of four data files
would report a coverage drop that is not one, and the PR is red either
way. The gate scripts and their thresholds are unchanged.
- The diff gate no longer sees `plugins-dist/ppt-engine` or
`plugins-dist/design-engine` at all, as it could never judge them;
measuring them (`--cov=raven_ppt --cov=raven_design`, a new ratchet
baseline) is the follow-up that would bring them under the gate.
- `--shard` is opt-in; a plain `pytest` run collects everything as
before. Shard data artifacts are kept one day, the combined reports 30
days as before.
- No product behaviour change: the ladder default is the same tuple read
from one place; the menu cap only changes how long the cache keeps
entries.
- Test-only risk: a test that implicitly relied on a production-length
retry delay would see different timing. The full suite passed with the
fixture on, and a single test can opt out with `production_timing`.
- Rollback: revert the PR. The unit job goes back to one runner with the
gates inline; both markers are additive.
- [x] Security impact considered (no security surface touched)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
This branch folds four merge requests and one unpushed commit into one, so that `main`
takes one review, one approval and one merge instead of four, and so the eight-file
overlap between them is resolved once. It carries, in this order:
- **!602** `feat/ppt_deliver_to_named_path` -- `ppt_build` takes `deliver_to`; every
publish writes the deck under `out/` and copies the same measured bytes to the path
the user named, recording it with `role: "delivery"`. The PDF preview rides along only
where its own `.pdf` name is free: a file already at that stem is the user's and is
left alone, and the reply says the preview stayed under `out/`.
- **!628** `feat/ppt_copy_route_and_page_isolation` -- `adapt` is removed, so cloning a
template page and writing into it with `replace_text` is the only route; a page whose
block raises loses only itself and the pages after it still build; a draft counts
against the tier's build cap and one is released at it.
- **!632** `feat/ship_templates_and_soffice_dep` -- the ten bundled deck templates are
tracked in git with per-file sha256 pins, so a fresh clone can build a deck; the
LibreOffice dependency is declared and resolved through one resolver.
- **!642** `fix/ppt_copy_route_and_clone_typography` -- a copy-route lookup that finds
nothing names the near miss before the inventory; a text frame with no paragraph at
all can be written into; a cloned page's title size is said; `row_type_drift` compares
the same structural slot across a run's units.
- **D57's other-page clause, rewired.** D57 gave five refusals a "did you mean" hint,
and one of them also answered "the string you named is on page N of this template".
That clause needs the file a page was cloned out of, and the only refusal holding it
was `adapt`'s, which !628 removed. It is restored by reading `PPT_TEMPLATE_SOURCE`,
which the runner already sets in the author's own process and which this module
already reads for `bundled()`; the two helpers behind the clause are unchanged.
- **D60** `read the ground under each word, not across the whole box` -- the `unreadable`
contrast gate also measures the render's own word boxes, as extra regions through the
same guards, so a two-line block crossed by a narrow bright ridge can no longer elect
the dark ground and read as legible.
Decisions the union forced, none of which drops a behaviour:
- The publish record is built !602's way, with its delivery `role`, and written the way
D49 requires -- read back off the file, atomic, and refused rather than silent when
the record cannot be written.
- `clear_region`, `shapes_in`, `page_box` and the refusal of a bare four-number region
survive `adapt`'s removal; so do `_heading_rows` and its helpers, which the row
reading loads even though the call they were written for is gone.
- The author-facing guidance names !628's single route and keeps D59's rule that a
region must declare which reading it is.
**The decision log carries a numbering collision, on purpose.** It is a set union with
no wording changed, and the numbers are left exactly as each branch wrote them, so a
reviewer meets this rather than discovers it:
- !602 and !628 each wrote a **D37** and a **D38**, about different decisions.
- !628's **D45** is not `main`'s D45; they are unrelated entries under one number.
- !628's **D42** is `main`'s **D45** word for word, so the merged log carries one
decision under two numbers.
Renumbering touches every cross-reference in the log, and doing that inside a
seventy-commit fold immediately before a merge is how a silent break gets in. The
numbering is being fixed on a separate branch, which carries a script and a test that
fails when a citation points at nothing.
## Type
- [x] Feature
- [x] Fix
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on an interpreter carrying `python-pptx`, with `PYTHONPATH` at this worktree and its
`plugins-dist/ppt-engine`, confirmed from a neutral working directory that `raven` and
`raven_ppt` resolve out of the worktree and not the host repo.
- `make test-python` (the whole suite, as CI runs it) -- 20826 passed, 49 skipped, and
26 failures this machine produces on any branch: it has no `/usr/share/zoneinfo`, so
every cron timezone case raises `ValueError: unknown timezone 'Asia/Shanghai'`. Checked
out plain `origin/main` in a clean worktree and ran the same two files: the same 6
failed and 20 errors, the ids identical character for character. Nothing on this branch
touches cron or timezones. The stale `test_trunks_executor_would_have_dropped_that_output`
that failed on the previous revision is retired on the new base and its replacement,
`test_trunks_executor_preserves_output_on_timeout`, was run on its own and passes.
The 6 failures and 20 errors are all cron timezone tests failing identically on plain
`main` in a clean worktree, on a host with no `/usr/share/zoneinfo`.
- `make check-commits` -- exit 0.
- `make check-source-language` -- exit 0.
- `make check-large-files` -- exit 0.
- `make lint-imports` -- exit 0, 9 contracts kept, 0 broken.
- `ruff check` and `ruff format --check` over the 80 changed Python files -- exit 0.
- `pytest tests/test_ppt_engine_templates.py tests/test_utils_office.py
tests/test_cli_doctor_commands.py` -- 97 passed; the ten templates are tracked and
satisfy their pins, and the soffice resolver finds the local binary.
- The delivery contract, the record read-back, the page isolation and the near miss were
each run as a measurement rather than asserted; the `unreadable` gate was run through
the real LibreOffice render chain on a delivered 12-page deck and reports BLOCKING on
page 12 under one word at 1.6:1.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes: `ppt_build` gains `deliver_to` and delivers outside `out/`;
`adapt` is gone from the author-facing template module, so a program calling it fails to
import -- `title=` and `subtitle=` have no replacement and the heading is named by the
words the template put there; a draft now counts against the tier's build cap; three
gates that nothing measured against being wrong no longer refuse; and the ten templates
are now bytes in the repository rather than a private registry fetch.
Two pieces here are about not destroying something the user has. The delivery
refuses to write its `.pdf` where a file the user already owns sits at the same
stem, rather than replacing it; and the large-file roster moved out of the manifest
inside the tree being checked and into the gate's own source, so a change can no
longer grant itself the exception the gate exists to withhold.
Rollback is per piece: each of the five sources is a contiguous run of commits on this
branch, in the order listed above, so any one of them can be reverted as a range without
touching the others.
- [x] Backward compatibility considered
- [x] Security impact considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
`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
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
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
## What
Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.
## Why
On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:
- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
from three classes outside the falsified list" (the falsified list named 18 specific
hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".
The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.
## The three rules
1. The owner's words and scope go into every node's brief as written; the orchestrator's
own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
*not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.
## Checks
- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
`tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
adds later in the same file.
## What
Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.
## Why
On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:
- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
from three classes outside the falsified list" (the falsified list named 18 specific
hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".
The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.
## The three rules
1. The owner's words and scope go into every node's brief as written; the orchestrator's
own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
*not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.
## Checks
- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
`tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
adds later in the same file.
## Summary
The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.
It comes back as a section of the card, not a third verb on the row:
- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.
No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.
**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:
- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.
This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.
**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)
**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.
**Checked and deliberately not changed, for the reviewer:**
- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:
- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.
```
npm run test --prefix ui-web 101 files, 1550 passed
npm run test --prefix ui-tui 141 files, 2017 passed, 13 skipped
npm run gen:check --prefix ui-web generated client matches the contract (162 methods)
npm run type-check --prefix ui-web clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui 23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py pass over the branch
make build-ui dist rebuilt and served
```
The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.
- [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 cover this card; screenshots taken during verification, not shipped)
## Risk
User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.
- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.
It comes back as a section of the card, not a third verb on the row:
- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.
No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.
**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:
- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.
This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.
**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)
**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.
**Checked and deliberately not changed, for the reviewer:**
- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:
- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.
```
npm run test --prefix ui-web 101 files, 1550 passed
npm run test --prefix ui-tui 141 files, 2017 passed, 13 skipped
npm run gen:check --prefix ui-web generated client matches the contract (162 methods)
npm run type-check --prefix ui-web clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui 23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py pass over the branch
make build-ui dist rebuilt and served
```
The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.
- [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 cover this card; screenshots taken during verification, not shipped)
## Risk
User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.
- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.
Key decisions:
- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
`use_skill` and the segment builder's post-gate hydrate refuse exactly what
they refused before. Reading is the weaker case because it installs nothing
and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
products rather than being one, so reporting the root refused a skill for
mentioning XDG at all. The reported path now runs down to the segment naming
the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.
`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.
- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
3 skipped. The three skips are pre-existing and environment-bound (two
`chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
note `these instructions reference paths outside Raven (~/.config/mcporter,
~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.
- [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, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.
The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.
The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.
Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.
## Related Issues
N/A
## Summary
The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.
Key decisions:
- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
`use_skill` and the segment builder's post-gate hydrate refuse exactly what
they refused before. Reading is the weaker case because it installs nothing
and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
products rather than being one, so reporting the root refused a skill for
mentioning XDG at all. The reported path now runs down to the segment naming
the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.
`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.
- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
3 skipped. The three skips are pre-existing and environment-bound (two
`chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
note `these instructions reference paths outside Raven (~/.config/mcporter,
~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.
- [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, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.
The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.
The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.
Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.
## Related Issues
N/A
## Summary
Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.
**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.
**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.
**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.
**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.
The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.
Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Branch and base run in separate worktrees, both at the same base, same interpreter.
- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
`unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
need `--localstorage-file` for `localStorage` to exist on this box at all, and with
it the store no longer refuses, so the refusal each asserts does not happen. Both
reproduce on the base, and neither file imports anything this change touches. A
second environment settles it: review ran the same head and reported 1,536 tests
passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
`check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
`lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
`renamed` call, a missing export, a missing harness verb, and the pre-edit title.
The ordering one is driven through the real `rpc.onReconnect` rather than
`openLiveSession`, because the ordering is between the two and a test that calls the
inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
editor gone, button back, zero title calls, no page error. Reconnect with the editor
open, forced by closing the socket from the page: before, `Cannot read properties of
null (reading 'textContent')` with the input stranded and no session reload; after,
heading restored, editor gone, reload done, no page error. Reconnect with a name
typed into an open editor: heading and rail row both settle on the committed name,
no page error. That probe renamed a real conversation, so its title was put back and
the stored metadata checked byte-identical afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible, all of it in the same direction: a title that used to vanish stays put.
- Ending an editor on a conversation switch commits what was typed, which is what
leaving the field already did. It cannot reach a different conversation than the one
it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
only case that changes is a name being generated, where the heading is empty and the
row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
shape or a schema.
Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.
## Related Issues
N/A
## Summary
Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.
**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.
**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.
**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.
**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.
The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.
Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Branch and base run in separate worktrees, both at the same base, same interpreter.
- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
`unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
need `--localstorage-file` for `localStorage` to exist on this box at all, and with
it the store no longer refuses, so the refusal each asserts does not happen. Both
reproduce on the base, and neither file imports anything this change touches. A
second environment settles it: review ran the same head and reported 1,536 tests
passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
`check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
`lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
`renamed` call, a missing export, a missing harness verb, and the pre-edit title.
The ordering one is driven through the real `rpc.onReconnect` rather than
`openLiveSession`, because the ordering is between the two and a test that calls the
inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
editor gone, button back, zero title calls, no page error. Reconnect with the editor
open, forced by closing the socket from the page: before, `Cannot read properties of
null (reading 'textContent')` with the input stranded and no session reload; after,
heading restored, editor gone, reload done, no page error. Reconnect with a name
typed into an open editor: heading and rail row both settle on the committed name,
no page error. That probe renamed a real conversation, so its title was put back and
the stored metadata checked byte-identical afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible, all of it in the same direction: a title that used to vanish stays put.
- Ending an editor on a conversation switch commits what was typed, which is what
leaving the field already did. It cannot reach a different conversation than the one
it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
only case that changes is a name being generated, where the heading is empty and the
row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
shape or a schema.
Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.
## Related Issues
N/A
## Summary
The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.
This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.
Key decisions:
- Memory is more than an adapter over the context engine. Two decisions that
sat in the shell move onto the role that owns them: which history slice is
even a candidate (it turns on whether the engine archives for itself), and
how much of the window a prompt may occupy (that window's own arithmetic).
organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
A live model switch rebuilds the provider and the window, and trajectory
replay rebinds loop.tools after the constructor returns. The context engine
is the exception and is bound directly: nothing rebinds it, and a
generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
contract tier: a replacement loop may name its own strategy points, so these
four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
list cannot move which message gets marked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.
- Captured on this branch and twice on its parent commit. Raw diffs contain
only wrap_untrusted fence nonces, which are random per invocation; capturing
the parent twice shows those are the sole variance. After normalising them
all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
default set, the two decisions Memory took over, both Action paths, the
callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.
The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.
This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.
Key decisions:
- Memory is more than an adapter over the context engine. Two decisions that
sat in the shell move onto the role that owns them: which history slice is
even a candidate (it turns on whether the engine archives for itself), and
how much of the window a prompt may occupy (that window's own arithmetic).
organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
A live model switch rebuilds the provider and the window, and trajectory
replay rebinds loop.tools after the constructor returns. The context engine
is the exception and is bound directly: nothing rebinds it, and a
generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
contract tier: a replacement loop may name its own strategy points, so these
four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
list cannot move which message gets marked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.
- Captured on this branch and twice on its parent commit. Raw diffs contain
only wrap_untrusted fence nonces, which are random per invocation; capturing
the parent twice shows those are the sole variance. After normalising them
all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
default set, the two decisions Memory took over, both Action paths, the
callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.
The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.
Key decisions:
- **Templates are real code, fire-tested before templating.** The eleven
files under raven/templates/agents_scaffold/ pass ruff and py_compile
like any source, ride the wheel, and their content was proven live
before landing: discovery, handshake, and plugin tool/hook injection
all green on a hand-assembled probe in a disposable home. A dedicated
spike also proved the placement is invisible to the import-linter
contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
target is the raven home's agents/ tree, discovery's first root: a
scaffolded folder is on the roster without any registration.
--register mirrors the generated install.py through the same pinned
write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
manifest, re-parses the plugin manifest, compiles every generated
file, and really scans discovery; smoke spawns the launcher for one
initialize frame. Three smoke outcomes are told apart: GREEN, the
launcher's loud no-key refusal (fail-closed design, passed through
verbatim), and FAILED with the scene preserved. Display names are
fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
renders schemas/subagent.schema.json (a discriminated union on kind)
and schemas/raven-plugin.schema.json from the pydantic models; a
contract family holds the on-disk files byte-equal to a fresh render
and validates every real manifest on the tree against them. Editors
get instant validation with two settings lines, documented in the
guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
the from-zero developer guide (gold standard: a developer who never
read the source reaches a green handshake in ten minutes); CONTEXT.md
renames the category entry to Discovered agent -- agent the thing,
harness the mechanism, subagent the protocol seat -- with product
absorbed into Avoid; the charter gains the scaffold entry and the
engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
project in the working directory (pip install -e territory); --here
lands it on the plugins-dist shelf. The launcher adopts the official
ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
is missing; the doctor reports that row as disabled by design with
the install cure printed. No plugins/ directory ships beside an
engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
hostile lenses (filesystem edges of a command that writes into real
raven homes; template quality as the file set every future agent
copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
pin an enabled row that cannot start, the name fence ignored the
discovered tree, one installed engine wheel rode the host's and every
sibling's turns through a fixed tool name, and crash residue was
discovered as a hidden live agent. All fourteen close in a
dedicated hardening commit, each with a regression test built from the review's own
reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
Nothing under raven/contracts/ or the agent loop changed. The branch
carries exactly two narrow runtime fixes exposed by the review:
discovery now skips dot-directories (crash residue is never an
agent), and the config schema gains an engine round-trip field
(declared as a field-level neutral seam; merge and readiness
semantics untouched).
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- Every commit landed through a full-suite rehearsal on a clean bench
before touching the branch; tails over the original base's 19953
passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
every step a pure addition, +65 tests net. The branch diff is
fingerprint-stable across the rebase (git patch-id --stable verified
pairwise across two clean rebases); the branch closes at 20094 passed
/ 137 skipped / exit 0 on the current main base, +80 tests net over
whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
end: one command scaffolds into ~/.raven/agents, the four-segment
card runs all green, and a genuine LLM turn has the agent's own model
call its own scaffolded hello tool through the permission gate and
relay the exact output; the probe was then removed without touching
the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
four doctor lines, readiness ready, and a live ACP initialize
handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
tampered file each turn the family red); all six subagent manifests
and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
make check-large-files, make check-source-language: green at every
step; wheel build carries all seventeen template files and none of
schemas/.
- [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
New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.
## Related Issues
N/A
## Summary
raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.
Key decisions:
- **Templates are real code, fire-tested before templating.** The eleven
files under raven/templates/agents_scaffold/ pass ruff and py_compile
like any source, ride the wheel, and their content was proven live
before landing: discovery, handshake, and plugin tool/hook injection
all green on a hand-assembled probe in a disposable home. A dedicated
spike also proved the placement is invisible to the import-linter
contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
target is the raven home's agents/ tree, discovery's first root: a
scaffolded folder is on the roster without any registration.
--register mirrors the generated install.py through the same pinned
write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
manifest, re-parses the plugin manifest, compiles every generated
file, and really scans discovery; smoke spawns the launcher for one
initialize frame. Three smoke outcomes are told apart: GREEN, the
launcher's loud no-key refusal (fail-closed design, passed through
verbatim), and FAILED with the scene preserved. Display names are
fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
renders schemas/subagent.schema.json (a discriminated union on kind)
and schemas/raven-plugin.schema.json from the pydantic models; a
contract family holds the on-disk files byte-equal to a fresh render
and validates every real manifest on the tree against them. Editors
get instant validation with two settings lines, documented in the
guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
the from-zero developer guide (gold standard: a developer who never
read the source reaches a green handshake in ten minutes); CONTEXT.md
renames the category entry to Discovered agent -- agent the thing,
harness the mechanism, subagent the protocol seat -- with product
absorbed into Avoid; the charter gains the scaffold entry and the
engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
project in the working directory (pip install -e territory); --here
lands it on the plugins-dist shelf. The launcher adopts the official
ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
is missing; the doctor reports that row as disabled by design with
the install cure printed. No plugins/ directory ships beside an
engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
hostile lenses (filesystem edges of a command that writes into real
raven homes; template quality as the file set every future agent
copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
pin an enabled row that cannot start, the name fence ignored the
discovered tree, one installed engine wheel rode the host's and every
sibling's turns through a fixed tool name, and crash residue was
discovered as a hidden live agent. All fourteen close in a
dedicated hardening commit, each with a regression test built from the review's own
reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
Nothing under raven/contracts/ or the agent loop changed. The branch
carries exactly two narrow runtime fixes exposed by the review:
discovery now skips dot-directories (crash residue is never an
agent), and the config schema gains an engine round-trip field
(declared as a field-level neutral seam; merge and readiness
semantics untouched).
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- Every commit landed through a full-suite rehearsal on a clean bench
before touching the branch; tails over the original base's 19953
passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
every step a pure addition, +65 tests net. The branch diff is
fingerprint-stable across the rebase (git patch-id --stable verified
pairwise across two clean rebases); the branch closes at 20094 passed
/ 137 skipped / exit 0 on the current main base, +80 tests net over
whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
end: one command scaffolds into ~/.raven/agents, the four-segment
card runs all green, and a genuine LLM turn has the agent's own model
call its own scaffolded hello tool through the permission gate and
relay the exact output; the probe was then removed without touching
the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
four doctor lines, readiness ready, and a live ACP initialize
handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
tampered file each turn the family red); all six subagent manifests
and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
make check-large-files, make check-source-language: green at every
step; wheel build carries all seventeen template files and none of
schemas/.
- [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
New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.
## Related Issues
N/A
## Change description
> ## Summary
>
> Expand provider and model metadata across the backend, RPC contract, TUI, and web UI. Providers now expose curated catalogs, homepages, native endpoints, and capability metadata. The web settings flow supports catalog browsing and manual model management, provider branding, homepage links, and green-only connected status indicators. MiniMax CN and NVIDIA onboarding remain available through their built-in provider flows.
>
> {width="478" height="324"}
>
> {width="501" height="338"}
>
> ## Type
>
> - [ ] Fix
> - [x] Feature
> - [ ] Docs
> - [ ] CI / tooling
> - [ ] Refactor
> - [ ] Other
>
> ## Verification
>
> - [x] Relevant tests pass locally
> - [ ] Relevant lint / type checks pass locally
> - [ ] User-facing docs or screenshots are updated when needed
>
> Exact commands and results:
>
> - `uv run pytest tests/test_provider_catalog.py tests/test_provider_registry_data.py tests/test_rpc_model.py tests/test_providers_factory.py -x` - 234 passed, 4 skipped
> - `npm test -- --run src/shell/provider-mark.test.tsx src/features/model/ModelPicker.test.tsx src/features/onboard/OnboardPage.test.tsx src/features/settings/SettingsPage.test.tsx` - 133 passed
> - `git diff --check` - passed
>
> The full web type-check was not marked as passing because the current test tree contains unrelated existing TypeScript errors in `SettingsPage.test.tsx`.
>
> ## Risk
>
> Provider registry data and model-selection behavior change across backend and frontend surfaces. Existing provider IDs and stored configuration remain supported. The change can be rolled back by reverting this merge request.
>
> - [ ] Security impact considered
> - [x] Backward compatibility considered
> - [x] Rollback path is clear for risky changes
>
> ## Related Issues
>
> N/A
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others
## Checklists
### Development
- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass
### Security
- [ ] Security impact of change has been considered
- [ ] Code follows company security practices and guidelines
### Code review
- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [x] Merge request linked to JIRA ticket when applicable
## Summary
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
Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.
1. A sub-agent's result relay into a page session ran on the gateway spine while the
page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
at once: the same tool calls were drawn twice and the result delivered twice, and
`turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
`raven.gateway.submit_router.route_submit` hands turns whose conversation carries
the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
The sub-agent manager and the deep-research submit both take the routed callable;
a gateway without a page keeps the gateway submit unchanged.
2. The watch-work judgement (one model call on a turn's first look) was paid on relay
and sentinel turns, whose "last user message" is the runtime's re-injected report,
and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
reads as no request, and the judgement is cut at 60 seconds and treated as no
verdict. CRON and heartbeat turns are deliberately still judged: their text is the
owner's own instruction.
3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
was mid-conversation with rendered to the main agent as "no turns yet"; the model
read that as free and spawned onto it. The handoff now reads the manager's live
direct turns (`live_direct_turns`) and renders an answering instance with the time
it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
behind such a turn no longer writes `running` before it holds the handle lock (it
stays the `pending` it was announced as), and no longer takes over the instance's
live view: `activity.watching_instance` registers only when the slot is free and
pops only what it registered, so the direct chat's steps stay on screen and the
spawn's appear once it runs.
4. When reasoning ran to the model's output ceiling with no content and the
empty-response recovery fed it back as a prefill, the continuation opened on the
rest of the cut thought and that fragment streamed and was stored as the head of the
answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
whitespace and ends at the first sentence or line boundary within 200 characters;
`ContinuationGate` holds streamed deltas until the same rule can decide, so what the
reader sees matches what the session stores. Only a continuation after
ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.
Decisions worth knowing:
- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
`RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
importing `raven.rpc`, so a test holds the two equal instead of one importing the
other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
moved (after the handle lock). The page's spawn card reads identity from `pending`
and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
source-language gate reads the literal marks as non-English source.
Review round 1 (all findings non-blocking, all taken):
- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
method, the rpc spine and the submit router call it, and the router test pins the
identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
`DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
The enclosing handler already kept the turn alive, but left the verdict unset, so a
failing judgement was paid again on every path-touching tool call; the comment that
claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
whole (no case, so no mid-sentence signal); the comment and a test now say that the
CJK stops end an admitted fragment rather than open one.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
-> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
-> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests -> clean
uv run lint-imports -> 9 kept, 0 broken
make check-source-language -> exit 0
scripts/check_commit_messages.py origin/main..HEAD -> exit 0
```
Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.
Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
Handoff Block)
## Risk
- A relay into a page session now waits behind the page's running turn on that session
instead of running beside it. That is the intended serialisation; the cost is latency
on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
that turn only; before, the same turn hung. No configuration knob: the bound is a
class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
continuation whose intended answer begins with a lowercase word and a full stop within
200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.
- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
page mount is unaffected)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.
1. A sub-agent's result relay into a page session ran on the gateway spine while the
page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
at once: the same tool calls were drawn twice and the result delivered twice, and
`turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
`raven.gateway.submit_router.route_submit` hands turns whose conversation carries
the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
The sub-agent manager and the deep-research submit both take the routed callable;
a gateway without a page keeps the gateway submit unchanged.
2. The watch-work judgement (one model call on a turn's first look) was paid on relay
and sentinel turns, whose "last user message" is the runtime's re-injected report,
and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
reads as no request, and the judgement is cut at 60 seconds and treated as no
verdict. CRON and heartbeat turns are deliberately still judged: their text is the
owner's own instruction.
3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
was mid-conversation with rendered to the main agent as "no turns yet"; the model
read that as free and spawned onto it. The handoff now reads the manager's live
direct turns (`live_direct_turns`) and renders an answering instance with the time
it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
behind such a turn no longer writes `running` before it holds the handle lock (it
stays the `pending` it was announced as), and no longer takes over the instance's
live view: `activity.watching_instance` registers only when the slot is free and
pops only what it registered, so the direct chat's steps stay on screen and the
spawn's appear once it runs.
4. When reasoning ran to the model's output ceiling with no content and the
empty-response recovery fed it back as a prefill, the continuation opened on the
rest of the cut thought and that fragment streamed and was stored as the head of the
answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
whitespace and ends at the first sentence or line boundary within 200 characters;
`ContinuationGate` holds streamed deltas until the same rule can decide, so what the
reader sees matches what the session stores. Only a continuation after
ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.
Decisions worth knowing:
- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
`RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
importing `raven.rpc`, so a test holds the two equal instead of one importing the
other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
moved (after the handle lock). The page's spawn card reads identity from `pending`
and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
source-language gate reads the literal marks as non-English source.
Review round 1 (all findings non-blocking, all taken):
- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
method, the rpc spine and the submit router call it, and the router test pins the
identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
`DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
The enclosing handler already kept the turn alive, but left the verdict unset, so a
failing judgement was paid again on every path-touching tool call; the comment that
claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
whole (no case, so no mid-sentence signal); the comment and a test now say that the
CJK stops end an admitted fragment rather than open one.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
-> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
-> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests -> clean
uv run lint-imports -> 9 kept, 0 broken
make check-source-language -> exit 0
scripts/check_commit_messages.py origin/main..HEAD -> exit 0
```
Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.
Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
Handoff Block)
## Risk
- A relay into a page session now waits behind the page's running turn on that session
instead of running beside it. That is the intended serialisation; the cost is latency
on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
that turn only; before, the same turn hung. No configuration knob: the bound is a
class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
continuation whose intended answer begins with a lowercase word and a full stop within
200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.
- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
page mount is unaffected)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Change description
Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.
Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.
Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.
Validation:
- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others
## Related issues (if there is)
N/A
## Checklists
### Development
- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass
### Security
- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines
### Code review
- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [ ] Merge request linked to JIRA ticket when applicable
No related JIRA ticket was supplied.
## Change description
Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.
Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.
Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.
Validation:
- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others
## Related issues (if there is)
N/A
## Checklists
### Development
- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass
### Security
- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines
### Code review
- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [ ] Merge request linked to JIRA ticket when applicable
No related JIRA ticket was supplied.
## Summary
Retires the vendored fork tree (`subagents/`, ~7,500 files) and makes `agents/` the one home for the five agent products. The products were already thin launchers that render a config and exec the installed raven's own `raven acp`; this PR removes the frozen fork checkouts they replaced, migrates every consumer, and keeps the A/B verification power as byte snapshots.
Key decisions:
- **A side becomes a record.** The fork trees are deleted; the files the parity guards compare against live on as byte snapshots under `tests/fixtures/vendored_fork/` (added to ruff's exclude so a record can never be reformatted). The research flow's oracle is the fork's frozen measurement (`research_parity_probe.json`), a constant by construction.
- **Config floors v6 and v7.** Stored roster rows that pointed into the retired tree are migrated in place (floor six): rows whose folder maps to a shipped product are re-aimed at `agents/`, fork-era rows that cannot be re-aimed are left untouched and reported, unparseable rows get a fix-by-hand notice. Verdict-driven, path-root anchored, with a stamped sidecar so each pass runs once.
- **The research product reclaims its name (floor seven).** The `-NG` suffix existed only to coexist with the fork's own row, so it retires with the fork: registered `Raven-Research-NG` rows rename to `Raven-Research` on load; if a fork-era row still holds the name, the advisory repeats and the stamp holds at floor six, so the rename completes on a later load once the name frees (never two rows under one name). Display name only -- the machine id `raven-research-ng` (state root, ACP home, everos identity, the `RESEARCH_NG_*` variables) is a stable key and stays. The v6 name gate maps the research folder to None (never re-aim): the fork's research rows were cli-kind on a different flow, and after the rename a name match would select exactly the rows the gate exists to refuse.
- **Guards retire with their subject.** The vendored-invariant and vendored-subagents guard suites, their Makefile/pre-commit/CI hooks, and the fork-era install stage in `install.sh` are removed. The external-consumer tripwire now derives the promised surface from the five product installers and the charter's uninstall recipe (`add_third_party_subagent` and `remove_third_party_subagent` today) instead of restating a list that goes stale; the fork-era pin count (eight names) retired with its consumers, and `get_third_party_subagents` stays only as a courtesy to fork-era installer copies already carried into raven homes.
- **Wheel and sdist slim down.** The wheel force-includes `agents/` file-by-file from the git index (filled-in `.env` files are refused). The sdist shrinks 93.2 MB -> 2.76 MB (-97%).
- **Docs speak one era.** AGENTS.md, CONTEXT.md, README, CHANGELOG, the demo READMEs, and the RPC field descriptions (models.py -> openrpc.json -> both generated clients) describe the product tree in the present and the fork in the past.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
- Controlled A/B on a clean bench, same machine and env fingerprint, at the current pair: base 19,938 passed / 137 skipped / 0 failed vs branch 19,796 / 137 / 0, skip roster identical line by line. The -142 delta equals the collection delta and reconciles file by file: -159 across the twelve retired or trimmed test files, +9 floor-six migration tests, +8 floor-seven tests. The branch diff is fingerprint-stable across rebases (`git patch-id --stable` verified pairwise), so the reconciliation transfers to later bases. A second fingerprint (dev worktree env) shows 19,555 / 148 / 2 at the final tip; the 2 are `test_design_engine_rendering_outcome` renders hitting a local playwright-home quirk -- on the clean bench both sides skip them identically ("no system chromium"), and the branch does not touch that file.
- `uv run pytest tests/integration/test_research_subagent_smoke.py -m integration`: 2 passed (the smoke now drives the migrated product launcher end to end).
- `make lint-python` (ruff check + format), `make lint-imports` (tail line: `Contracts: 9 kept, 0 broken.` -- the ninth contract landed on main mid-branch), `make check-large-files`: all green.
- `npm run lint:rpc --prefix ui-tui` and `npm run gen:check --prefix ui-web`: generated clients in sync with `rpc-schema/openrpc.json`.
- `bash -n install.sh`: clean.
- Wheel built from the branch, installed into a clean venv: onboarding discovers the five products, and a filled-in `.env` placed in the tree fails the build (secrets refusal probed).
- Real-config upgrade rehearsal on a genuine floor-5 home config (owner present): the migration stamped the sidecar to 6, rewrote nothing (the five product rows were already registered against `agents/`; the one fork-era orphan row got its advisory notice and was left untouched), a second load was silent, and the upgraded config served a live probe plus one full one-shot agent turn. The floor-seven rehearsal on the same config renamed its one transition row (a one-line diff against the byte backup), stamped seven, was silent on the second load, and left the machine ids and the row's command untouched.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- User-visible: on first load of a pre-v6 config, roster rows pointing into the retired tree are re-aimed at the product tree, with a one-line `Migrated` notice per changed row and a cleanup hint for the stale on-disk copy. Rows the migration cannot decide are reported, never rewritten. The floor-seven rename tells once per changed row too; only a blocked rename repeats its advisory, deliberately, until the blocking row is gone. While the block holds, the roster shows the discovered `Raven-Research` row beside the stored `Raven-Research-NG` row -- same launcher, same state root, no state split -- and converges to one row once the name frees.
- Rollback: revert the squash commit. The fork trees return from git history, and a config the migration already re-aimed keeps working on both sides of the revert: the wheel carries `agents/` before and after (that packaging landed separately), so no config rollback is needed. Rows the migration could not decide were never rewritten, and the version sidecar is additive.
- Packaging: a wheel built from an sdist (what a combined `uv build` does) carries no agent products by design -- the sdist has no `.git` for the hook's tracked-files read; the hook warns loudly, and release.yml builds the wheel directly from the checkout and asserts the products are present. Release artifacts are unaffected; do not publish a combined-build wheel.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
BREAKING CHANGE: the `subagents/` source tree is gone. Installs never consumed it directly (the wheel carries `raven/agents`), but any local tooling that read `subagents/` paths must move to `agents/` or the snapshots under `tests/fixtures/vendored_fork/`.
## Summary
- Add LM Studio, NVIDIA NIM, and separate MiniMax Global and MiniMax CN provider paths across configuration, routing, onboarding, and model discovery.
- Add bundled provider icons and accessible connected or disconnected status indicators to provider lists.
- Add provider homepage metadata to the RPC contract and link provider names in Settings, onboarding, and the model picker.
- Preserve the latest main branch per-model protocol metadata while mapping provider UI rows.
{width=876 height=600}
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- [ ] `uv run pytest tests/test_provider_catalog.py tests/test_rpc_model.py tests/test_rpc_schema_match.py tests/test_rpc_contract_shapes.py -x` - 534 passed, 4 skipped.
* `npm test` from `ui-web/` - 1,378 passed.
* `npm run type-check`, `npm run gen:check`, and `npm run build` from `ui-web/` - passed.
* `npm run type-check` and `npm run lint:rpc` from `ui-tui/` - passed.
* `.venv/bin/ruff check raven/providers/registry.py raven/rpc/methods/model.py raven/rpc/models.py tests/test_provider_catalog.py tests/test_rpc_model.py` - passed.
* `make check-source-language check-large-files` - passed.
* `git diff --check origin/main...HEAD` - passed.
* Visually verified the assembled Settings and onboarding provider lists; repository rules prohibit committing standalone screenshots.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The RPC homepage field is optional, and existing provider configuration remains compatible. Provider routing changes are covered by focused resolution, factory, and RPC tests. Roll back by reverting this feature commit.
## Related Issues
N/A
## Summary
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
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
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 on-call agent advertises Medium/High/Max session modes over ACP.
- `agents/raven-oncall/modes/{medium,max}.json` are overlays over the shipped config (reasoning effort off / max); `config.json` itself is the High baseline. Rendered through the same `render.mode_catalogue` the research agent uses. The rung ids are the ones the host's session tier is spelled in (`TIER_LADDER`), so the tier maps onto them directly.
- How the effort reaches the model call is the trunk's own mechanism, not this branch's: `AcpModeConfig.reasoningEffort` (landed on main in c25036dc) is dispensed to `SessionPolicy.reasoning_effort` and applied to every call a session in that mode makes. The product renderer lifts an overlay's `agents.defaults.reasoningEffort` onto the mode entry as that knob, so a product declares the effort where it declares its other defaults and the loop never reads the hook overlay for it. The generation-slice machinery earlier revisions of this MR carried is gone.
- Two documentation lines corrected: `agents/README.md` modes inventory; `_llm_call_stream`'s contract.
No DAG node field and no spawn parameter.
## 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_config_product_render.py tests/test_agents_oncall_launcher.py tests/test_acp_modes.py tests/test_agents_research_launcher.py tests/test_acp_methods.py -q # 228 passed
uv run lint-imports # 8 contracts kept
uv run python scripts/check_commit_messages.py origin/main..HEAD # clean
```
Field check: a real ACP handshake with the on-call process on 2026-09-04 returned `currentModeId: high` and the three-rung menu; `set_mode medium` accepted, `set_mode ultra` refused as unknown.
- [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
A product that declares no effort in its overlays renders the same entry as before. Rollback is a revert of the squash commit.
## Related Issues
Replaces !522 (closed): same feature, branch renamed to the snake_case form AGENTS.md 2.1 requires.
## Summary
The on-call agent advertises Medium/High/Max session modes over ACP.
- `agents/raven-oncall/modes/{medium,max}.json` are overlays over the shipped config (reasoning effort off / max); `config.json` itself is the High baseline. Rendered through the same `render.mode_catalogue` the research agent uses. The rung ids are the ones the host's session tier is spelled in (`TIER_LADDER`), so the tier maps onto them directly.
- How the effort reaches the model call is the trunk's own mechanism, not this branch's: `AcpModeConfig.reasoningEffort` (landed on main in c25036dc) is dispensed to `SessionPolicy.reasoning_effort` and applied to every call a session in that mode makes. The product renderer lifts an overlay's `agents.defaults.reasoningEffort` onto the mode entry as that knob, so a product declares the effort where it declares its other defaults and the loop never reads the hook overlay for it. The generation-slice machinery earlier revisions of this MR carried is gone.
- Two documentation lines corrected: `agents/README.md` modes inventory; `_llm_call_stream`'s contract.
No DAG node field and no spawn parameter.
## 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_config_product_render.py tests/test_agents_oncall_launcher.py tests/test_acp_modes.py tests/test_agents_research_launcher.py tests/test_acp_methods.py -q # 228 passed
uv run lint-imports # 8 contracts kept
uv run python scripts/check_commit_messages.py origin/main..HEAD # clean
```
Field check: a real ACP handshake with the on-call process on 2026-09-04 returned `currentModeId: high` and the three-rung menu; `set_mode medium` accepted, `set_mode ultra` refused as unknown.
- [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
A product that declares no effort in its overlays renders the same entry as before. Rollback is a revert of the squash commit.
## Related Issues
Replaces !522 (closed): same feature, branch renamed to the snake_case form AGENTS.md 2.1 requires.
## Summary
`SubagentManager._require_addressable` has two refusals, and both are written for the person who pressed the button:
```
'X' is disabled or no longer configured, so it cannot be addressed.
Any records it already has remain on disk.
'X' is stateless, so each turn would start a fresh conversation with no memory
of this one. Spawn it with a task instead.
```
Both were raised as bare `RuntimeError`, and the dispatcher renders anything but an `RpcError` as `internal_error` with the text buried in `data.traceback_tail`. The panel draws `s.startFail.why`, which was `e.message` -- so it drew the string `internal_error`, and the one failure on this path a caller could act on was the one nobody could read.
Measured on the running page, before and after, against a stateless agent:
```
before message internal_error code -32603 detail null
after message config_validation_error code -32011 detail "Cannot create a new
instance: 'Raven-Research-NG' is stateless, so each turn would start a fresh
conversation with no memory of this one. Spawn it with a task instead."
```
Three parts, because the layers are three:
- **`NotAddressableError`**, new, in `direct_chat.py`. A type rather than a message match, because the surface has to tell a refusal from a fault and `raven.agent` cannot import `raven.rpc` to do it there -- the "inner layers know no surface" contract. It subclasses `RuntimeError`, so this narrows what a raise MEANS without narrowing what it is.
- **`instances_create`** translates it to `ConfigValidationError`, the class the two refusals below it in the same file already use, for the same reason: the request was refused, nothing broke.
- **The web store** reads `data.detail` before `message`, because `message` is the wire CODE. Without this half the card would have moved from `internal_error` to `config_validation_error` and been no better.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## How narrow this is, stated plainly
The panel already hides the `+` for exactly these two cases -- `addressable()` is `enabled && stateful` -- so an ordinary click cannot reach the refusal. What reaches it is:
- a roster gone stale under an open page: an agent disabled in config, or an auto-verify recording a snapshot and `refresh_agents()` flipping `stateful` while the browser still holds the old roster;
- the TUI's own `subagents.instance.create` call, which takes a typed agent name and consults no such guard.
I first "reproduced" this by calling the DataSource method directly from the console, which bypassed a button that would not have been there. That made the defect look like an everyday one, and it is not. The value here is that when it does happen the reader gets the way out instead of a code.
## A contract change, with one caller
The exception type at this boundary went from `RuntimeError` to an `RpcError`. `instances_create`'s only caller is the dispatcher, which handles `RpcError` first -- that is the point of the change. The existing roster-refusal test now pins the new contract instead of the old one, and a second test pins that the narrowing stays narrow: a manager raising anything else is still an internal error, because dressing a fault as a validation error would tell the reader to fix a request that was never wrong.
## Verification
```
make lint-python All checks passed
make lint-imports 8 contracts kept, 0 broken
make lint-ui gen:check 162 methods, type-check
make lint-tui lint, lint:rpc, lint:i18n, type-check
make test-ui 1349 tests passed
make test-python 19278 passed, 5 failed
```
The five python failures are pre-existing on `origin/main` and unrelated -- four NAT64 cases in `tests/test_security_network.py` that depend on how this host resolves that prefix, and `test_doctor_answers_where_the_memories_are`. I ran the full suite on the base tree to get that number rather than assuming it.
One run of mine also failed `test_agents_research_tools.py::test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`. It did not reproduce on a second full run of the same tree, and it passes alone and with its own file, so it is a flake sensitive to xdist distribution -- named here rather than quietly dropped, since my change adds four tests and therefore changes how work is distributed.
Mutation-checked four ways: the store back to reading `message`, the store without its fallback, the rpc layer not translating, and the manager back to `RuntimeError`. Each reds a different case. Worth recording that my first harness evaluated the test command in the argument list, so it ran *before* each patch was applied and reported four clean passes -- the giveaway was that every mutation "passed", which is the same shape of mistake as a probe whose control never fires.
## Out of scope, and worth its own change
**The TUI shows the code too.** `ui-tui/src/rpc/errors.ts` builds its message as `` `[rpc ${code}] ${message}` `` and never reads the detail, so the TUI moves from `[rpc -32603] internal_error` to `[rpc -32011] config_validation_error` and is no better off. Fixing it is one line and would change the text of every RPC error in that surface, which is not this MR's blast radius to take.
**The bigger one, which this is not.** A capability probe that fails records nothing: `probe.py`'s auto-verify calls `store.record(result)` only when `status == "ready"`, so an agent whose launch failed keeps `probe_status: "unknown"` and an empty `probe_detail` -- while the reason it measured goes to the log alone. The external-agents surface already has the slot and already renders it well for other failure classes: on this machine `Raven-Design` and `Raven-PPT` read `attention` with "the design-engine engine wheel is not installed in this raven's environment -- install it where raven is installed, then ...", whereas `Raven-Research-NG`, which exits 1 at launch for want of a search key, reads `unknown` with nothing. That is a real defect with a built surface waiting for it, and it is a separate change.
## Swept
`mr-review-patterns` pre-submit sweep, over the branch diff.
- **1 (a write location moved)** -- nothing moved; two raises changed type and one call site gained a translation.
- **2 (a value with several entry points)** -- `_require_addressable` has two callers, `create_instance` and `chat`. Only the create path is translated here: `chat` is reached through `turn.send` and its refusal surfaces as a turn error in the transcript, a different surface with its own rendering. Named rather than half-done.
- **3d (several lanes through one sink)** -- the client's `startFail` has one writer; the detail-before-message order is pinned by two cases, one per branch.
- **4** -- failing test IDs diffed against the base by running the full suite on both trees, not counts. 0 introduced; the flake above is named.
- **9 (error handling)** -- the whole change is error handling. The fallback chain keeps a rejection with no detail readable, which the second client test pins.
- **11** -- `npm ci` in both `ui-web` and `ui-tui`; this worktree was fresh.
Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.