## Summary
Raven's host acts as the user's agent manager: it delegates production
work, including small edits, to the agent whose ownership or description
fits the task -- or, on a turn bound to a Worker Table, to the worker
whose brief covers it -- keeps track of the task and its instance,
routes follow-ups back to that instance, and gathers the results for the
user. Its own tools support briefing, checking and coordination.
- Add the resident `multi-agent-coding` skill for choosing coding
agents, keeping one instance per task, passing results by file,
isolating concurrent edits in worktrees, and handing over work when an
agent exhausts its quota.
- Keep the new host role authoritative in both the DAG skill's resident
description and its full guide. A single task uses `spawn`, or a
one-node graph when only the DAG dispatch path is available.
- Rename the generic sub-agent to `Raven-General`, with `Raven` and
`raven` retained as compatibility aliases. Instance records, handle
locks, live activity, cancellation, preferences and RPC lookups use the
same canonical identity. Historical spawn and DAG readers normalize
names before liveness checks and serialization, so tasks and transcripts
join the current instance roster. Concurrent alias calls preserve both
turns instead of overwriting one conversation snapshot. The instance
registry reads former-name rows under the current name and, on its next
write, saves every loaded row under it; transcripts, direct chats and
stored graphs stay as written.
- Resolve built-in configuration aliases before merging fields:
`Raven-General` wins over `Raven`, then `raven`, regardless of file
order. Discard older rows wholesale with a warning, preventing stale
model, permission or transport settings from leaking into the selected
row.
- Resume the most recently written message state and instance log across
former names. Saved messages take precedence over an empty chat
directory; equal timestamps prefer the current name and then the most
recent former name. Existing files stay in place. Legacy spawn records,
completed DAG manifests and unfinished graphs remain readable through
the current name.
- Emit the agent roster once at the end of `spawn`'s description. The
registry places `run_subagent_dag` and then `spawn` last, including
after late MCP or session tools. The graph tool renders the roster
itself when `spawn` is unavailable. With a Worker Table bound, dispatch
guidance selects worker labels from the live enum; the roster explains
underlying capabilities. The tool descriptions and resident DAG guide
follow the same rule.
- On a turn bound to a Worker Table, such as a Persona session, `spawn`
and the DAG nodes offer worker labels alone, and a generated Persona
never includes the generic agent. The host role on such a turn routes
production work to the worker whose brief covers it, by label, and puts
work no worker covers to the user, who can add a worker or give the
conversation another Harness, instead of doing it itself or naming an
agent outside the enum. Ordinary turns render byte for byte as before. A
Harness that `load_playbook` binds mid-turn takes effect after the
identity was assembled, so that call's result carries the same routing
as this system's trusted note, after the untrusted fence. The coding
skill picks worker labels on such a turn, for its first pick and for a
quota takeover.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Measured at this head on Linux/Python 3.12.13.
- `UV_NO_SYNC=1 uv run --no-sync pytest -q -n 12`: **33,767 passed, 178
skipped, 2 xfailed; 9 failed and 1 error.** Eight of the failures are
bound to this box and fail the same way on current main, measured the
same day: five provider tests that read the box's proxy environment, a
Node.js path case, a LibreOffice conversion, and a fixture that root can
read anyway. The ninth, with its teardown error, is the `remote_runs`
race tracked in #990; that test passed 5 of 5 runs alone, and its file
58 of 58.
- 13 new regression tests for Worker Table routing: 12 fail against the
previous head's source and all pass now; the thirteenth checks that a
Harness loaded mid-turn leaves the next turn's role plain, and passes on
both by design. The end-to-end case drives a real Persona-bound turn:
both enums offer `research-a` alone, dispatching `Raven-General` is
refused, and the role must name neither that agent nor the roster
fallback.
- Nine single-construct mutants, each applied to an isolated copy of the
tree, each fail at least one new test: the role ignoring the table, the
default path not reading the turn's table, the uncovered-work rule
removed, the generic fallback kept in the worker routing, the coding
skill reverted, and the mid-turn note never added, added on every call,
added without a dispatch path, or phrased apart from the role.
- The host identity on ordinary turns is byte-identical to the previous
head in all 16 rendered shapes: a launched sub-agent process or not,
with or without ownership lines, and every combination of the two
dispatch tools.
- Instance registry probe, run with this head and with main on one
synthetic file: reads leave the file byte-identical; one unrelated
`upsert_spawn` saves every former-name row as `Raven-General`, keeping
the more recently updated of two colliding spellings and the later one
in the file on a tie; main then finds none of those rows under `Raven`
or `raven`.
- `uv run --no-sync python scripts/coverage_gate.py --coverage-json
<coverage.json> diff --base-ref origin/main --threshold 90`, over a
coverage run of 225 test files (8,952 passed): **99.40%**, 167/168
executable changed lines covered.
- `UV_NO_SYNC=1 make lint-types lint-imports check-large-files
check-source-language COMMIT_RANGE=origin/main...HEAD`: passed; all 10
import contracts kept.
- `UV_NO_SYNC=1 make check-commits`: both commit-message validators
passed; each also refused a dangling control commit with a malformed
subject.
- `ruff check` and `ruff format --check` over the branch's Python files
passed. `node ui-tui/scripts/gen-i18n.mjs --check` passed after the
rebase onto #1015, which also changed the i18n catalogue.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref
HEAD`: every hook passed except the whole-TUI Prettier hook, which
reports only `newInstancePicker.tsx` and `subagentsHub.tsx`; both are
byte-identical to current main.
- Live-model replay and native Windows/macOS testing were not repeated
for these fixes.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The host delegates work it previously performed itself, including
small scripts. Task-to-instance routing remains prompt-based; a task can
still stay with the host after it has already answered a follow-up
itself.
- In a conversation bound to a Persona or another Harness with workers,
work no worker's brief covers now waits for the user to add a worker or
change the conversation's Harness, rather than being carried out by the
host.
- Old agent spellings remain accepted. The instance registry's first
write after the upgrade, of any row for any session, saves every
former-name row in `subagent_instances.json` as `Raven-General`, and
keeps only the more recently updated row where two spellings of one
instance collide. Builds from before the rename cannot look those rows
up, so reverting the squash commit alone does not restore their instance
bindings: that needs the registry file as it stood before that first
write. Renaming rows back by hand cannot recover a colliding row the
write dropped. Transcripts, direct chats and stored graphs are not
rewritten.
- When multiple generic-agent configuration spellings coexist, only the
newest row contributes overrides. Fields supplied exclusively by an
older row are intentionally discarded.
- Moving the dispatch tools changes the tool-array cache prefix once
after upgrade.
- A plugin participant that removes `spawn` through `select_tools` can
still leave the graph tool pointing at an absent roster, because that
selection occurs after the registry's offer check. No bundled
participant does this.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
On Windows, the file tools took a DOS device name for an ordinary
workspace file:
`write_file` with `path="nul"` sent the content to the NUL device and
answered
success for a file that never existed, `diff` and `file_change`
included. The same
holds for the rest of the reserved set under Windows' naming rules: a
first
extension and trailing spaces are stripped before the device comparison,
so `nul.md`
and `con ` are devices too, and on Windows 10 and earlier the whole set
is reserved
in every directory.
Root cause: `resolve_path` (`raven/agent/tools/filesystem.py:57-76`)
joins the name
onto the workspace and calls `Path.resolve()`. On Windows that is
`ntpath.realpath`,
which maps only a path that is exactly `nul` to `\\.\NUL` and hands
`<workspace>\nul`
back unchanged, so the `allowed_dirs` prefix check then accepts it, and
the file has
no reserved-name check anywhere. CPython tracks the general "device name
inside a
longer path" gap as issue 95486.
Fix: `resolve_path` refuses the reserved shapes #895 names, in every
component
the caller supplies -- a device name with or without a first extension,
the
superscript COM/LPT aliases, a name ending in a dot or a space, and a
colon
stream. The set and the per-component order mirror CPython 3.13's
`ntpath.isreserved`, which Python 3.12 cannot call; Microsoft's naming
rules
list COM/LPT 1-9 only, so `com0.txt` is an ordinary file and stays one.
The
refusal is a `PermissionError`, the same one a path outside the allowed
directories gets, and the guard is gated on `_WINDOWS` (snapshotted from
`os.name == "nt"` at import). Every consumer reaches it through this
single
choke point -- the five file tools, `deliver_files`, the RPC file viewer
and
the turn attachments -- so one check covers them all. A URL argument
keeps its
`web_fetch` hint, and a drive letter written with double slashes stays
inside
the check, since Windows reads it as a local path.
Two review rounds also covered the remote-path layer these tools
dispatch to.
Only the head of an scp spelling -- the machine id or `user@address`,
before the
separator -- can be the device instead of a machine, so `NUL:` and
`com1:x` take
the fence first while `box:raven-work/a.txt` and files named `nul`,
`aux` or
`com1` on that machine reach it. The classification asks the remote-path
parser
whether the spelling is remote, so the two layers read one rule rather
than a
second parser. Off Windows nothing changes: a file called `nul` stays a
legal
name, and the tests cover both sides of the gate.
The branch history carries the commits this change was developed in; the
latest
commit migrates the fixes reviewed on the replacement branch, and the
author's
own commits are preserved as they were.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All commands run with `timeout`, on this branch's head with a clean
tree, against
the repo `.venv`.
- Red first (tree before the fix): inline `timeout 60 .venv/bin/python`
calling
`resolve_path` for `nul` / `nul.md` / `con.md` / `report.md` -> all four
resolved
as ordinary paths (device names accepted); `pytest
tests/test_filesystem_tools.py`
-> ImportError (`_is_device_name` absent).
- Green, gate on (`os.name == "nt"` simulated): same inline script ->
`nul`,
`nul.md` and `con.md` raise `PermissionError`, `report.md` resolves
normally.
- Gate off (POSIX default): same inline script -> all four names resolve
as before.
- File: `timeout 120 .venv/bin/python -m pytest
tests/test_filesystem_tools.py -q
-p no:cacheprovider` -> 54 passed.
- Related subset: `timeout 300 .venv/bin/python -m pytest tests/ -k
"filesystem or
file_tool or fence" -q -p no:cacheprovider` -> 281 passed, 7 skipped.
- Direct consumers of `resolve_path` (5 test files): 288 passed, 1
failed
(`test_a_host_without_libreoffice_says_so`; reproduced identical red on
a clean
tree -> pre-existing environment failure).
- Full suite: `timeout 590 .venv/bin/python -m pytest tests -q
--ignore=tests/manual
-p no:cacheprovider` -> 27973 passed, 128 skipped, 4 failed (a2a interop
/
rpc_files libreoffice / simulation suite / simulation scenario; each
reproduced
identical red on clean `origin/main` -> pre-existing environment
failures, not new
regressions).
- Lint: `timeout 120 uvx ruff@latest check raven/` -> All checks passed;
`uv run ruff format` applied (touches the added lines only), `ruff
check` -> All
checks passed.
- At the current head `6700103ad`, in a worktree cut from this branch,
with the
repo's Python 3.12 environment (`--all-extras`) and an isolated
interpreter
whose site-packages put this worktree's `raven` first (the imported
`raven`
was confirmed by printing its `__file__`):
- `pytest tests/test_filesystem_tools.py -q -n 0` -> 133 passed.
- `pytest` over the eleven files that reach `resolve_path`, the remote
answer
or the node client (`test_filesystem_tools`,
`test_filesystem_write_modes`,
`test_file_search_traversal_guard`, `test_deliver_files_tool`,
`test_rpc_files`, `test_rpc_turn_send`, `test_ops_remote_path`,
`test_permissions_remote_read`, `test_agents_code_tools_plugin`,
`test_remote_file_tools`, `test_node_client`) -> 782 passed, including
the
real-node cases behind the stand-in ssh.
- Red first, latest round: with the previous head's source restored, 37
tests
fail -- every remote reserved-name case for all four tools, plus the
local
control -- and with the fix all 133 pass. Round one's evidence also
holds:
the earlier broad predicate fails the remote-path case, and disabling
the
device check fails the colon spellings.
- The remote cases are parametrized over `read_file`, `write_file`,
`edit_file` and `list_dir`, over scp short forms, `user@host`, absolute
and
relative remote paths and the `scp://` form (`nul`, `aux`, `com1`,
`nul.md`, `nul:hidden` included). Each asserts the remote answer
received
that exact path and that no local directory entry was written; the
control
asserts local reserved shapes are refused with no remote call.
- Gate on, with the real tools: `nul`, `nul.md`, `con.md`, `notes.md.`,
`notes.md ` and `subdir/nul` answer the refusal; `report.md`, `com0.txt`
and `https://example.com/a.md` stay ordinary; gate off, `nul` resolves.
- `ruff format --check` and `ruff check` on both files: clean.
- `ty check raven/agent/tools/filesystem.py`: passes.
- `lint-imports`: 10 contracts kept, 0 broken.
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and
`scripts/check_large_files.py` over `origin/main...HEAD`: exit 0.
- `git diff --check`: clean.
- The real-node cases in `test_remote_file_tools.py` compare the node
subprocess's package digest with the caller's, so both sides must import
this branch: they pass in the isolated interpreter above (25 cases).
Under a
plain `PYTHONPATH` over a checkout whose installed tree differs, they
fail
for that digest reason alone.
- Merge compatibility: a trial merge of this branch onto current `main`
(`2742cf6c0`) completes with no conflict, touching the same two files.
Not run: a real Windows end-to-end pass (development host is macOS, no
Windows
environment available). The refusal is gated on `_WINDOWS` and was
verified at the
logic level on both sides of the gate; the Windows-side behaviour rests
on the
CPython `ntpath` source (read at 3.13) and issue 95486, not on a live
run.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No docs change: no document describes the file tools' path handling at
this level.
## Risk
User-visible change is Windows-only: the file tools now refuse a
reserved name
instead of silently opening the device, and a remote path reaches its
machine
whatever its components are named, including `nul`, `aux` and `com1`.
Off
Windows the gate is off and behaviour is unchanged.
- [x] Security impact considered
The change closes a silent write-to-device hole (content discarded, fake
success
receipt); it adds a refusal, removes no capability, and cannot widen any
path.
- [x] Backward compatibility considered
POSIX filenames like `nul` or `nul.md` stay legal; on Windows such names
never
addressed a real file through these tools, so no working workflow
breaks.
- [x] Rollback path is clear for risky changes
Rollback is a revert of the added commits; the guard is one string check
at one
fence point with no persistent state.
## Related Issues
Fixes#895
---------
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
## Summary
Reported by the owner on 2026-10-20, on the first day with #1007 on
their site: the Ravenx card said
"No agent connected here yet" while the machine's connect form greyed
Claude Code as "already connected
on this machine". Both were telling the truth by different rules. The
card counted connected entries
only (`agents_on_machine(only_enabled=True)`); the form, and
`subagents.add`'s duplicate rule, counted
every entry of the preset on the machine, switched off or not -- and the
owner had just switched
`Claude Code@ravenx` off. So a switched-off entry was counted nowhere on
the card, blocked the form,
and had no way back from the machine's side.
What changes:
- `machines.list` rows carry `agents_off_here`, the entries on the
machine that are switched off
(the connected ones stay in `agents_here`; both empty when the agents
section or the config file
cannot be read). The card line and the sheet field show them marked
*switched off*.
- `subagents.presets` now means by `on_machines` the machines a
*connected* entry runs on, and adds
`off_on_machines` (machine + entry name) for the switched-off ones. Both
additive.
- The connect form keeps greying a preset the machine has connected, but
offers one it has switched
off back under its own entry -- each switched-off entry as a choice of
its own, by name, since a
machine may hold several explicitly named ones: the option says
*switched off*, the working-directory
field is left out (the entry keeps the one it had), and the button reads
**Reconnect**, which runs the
agents page's own `subagents.toggle enabled=true` on that entry -- same
proof ping, no second entry. The
add is offered only while the machine holds nothing of the preset (the
server refuses it otherwise). The
Reconnect goes through the agents page's own `act`, so the row is marked
joining for the length of the
ping: that page draws it pending and cannot press its own Connect
meanwhile, and the form, reading
`joining` too, greys the entry the other way round -- one ping whichever
side pressed. The card line and
the sheet field read *N on this machine* / *Agents on this machine*,
since they list switched-off
entries as well. The
write is guarded like the add (opening generation, drawer still current)
and marked pending so a
form reopened meanwhile does not offer it twice; a refusal stays on the
form in the agent's words.
- Docs: machines guide (en + zh), CHANGELOG, CONTEXT.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest tests/test_rpc_machines.py tests/test_rpc_schema_match.py
tests/test_rpc_registration.py -n 4`: 580 passed; `pytest
tests/test_rpc_subagents.py tests/test_ops_connection_add.py
tests/test_raven_config_tool.py -n 4`: 365 passed. The two extended
cases (`agents_off_here` listed apart; `off_on_machines` carries the
entry name while `on_machines` leaves it out) fail with the two handler
changes stashed.
- `ruff check` / `ruff format --check` on the changed Python files:
clean.
- ui-web: `vitest run src/features/extAgents scripts/gates`: 483 passed
(5 new page cases: the third for two switched-off entries of one preset
on one machine, each reconnectable in turn; the fourth and fifth for a
toggle in flight from either side -- the agents page offers no Connect
while the machine's Reconnect runs, and the form greys the entry and
says why while the agents page's Connect runs -- both fail with the
previous store/form; the switched-off preset is pickable and labelled,
no directory field, Reconnect toggles the existing entry and lands back
on the sheet with the lists re-read; a refused Reconnect stays on the
form in the agent's words -- both fail with
`MachineCards.tsx`/`store.ts` stashed; the card/sheet case extended with
a switched-off entry). `tsc --noEmit`, `eslint` on the changed files,
`gen:check` clean; `ui-tui` `lint:rpc` / `lint:i18n` clean.
- `pytest tests/test_docs_site.py`: 16 passed; `mkdocs build --strict`:
clean.
- Full suite: see the comment on this PR.
- Real page: see the comment on this PR.
## Risk
- [x] Security impact considered: the new fields carry entry names
already shown on the agents page; Reconnect is the existing toggle, with
its proof ping and refusals.
- [x] Backward compatibility considered: `agents_off_here` and
`off_on_machines` are new fields (the page maps both defensively);
`on_machines` narrows to connected entries, which only this page reads.
- [x] Rollback path is clear for risky changes: revert the commit;
nothing stored changes shape.
## Related Issues
N/A (follow-up to #1007, from the owner's report on 2026-10-20)
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
On a Windows host the on-call flow could not run a job: the process
backend's launcher is a `/bin/sh` script (`setsid`, `trap`, `kill -0`,
`stat -c`), so every job stayed RUNNING forever and the spend scan
billed nothing, quietly.
- New `windows` job backend (`oncall_flow/windows_backend.py`): the same
submit / poll / fetch_result / cancel / fetch_progress contract, written
in Python. Liveness uses `raven.utils.pid.pid_alive` (`os.kill(pid, 0)`
terminates a process on Windows). Cancel is a tree kill with `taskkill
/T`. The job is started through a short-lived relay, so it is nobody's
child: stopping the host with `taskkill /T` (which walks parent pids,
whatever the creation flags) no longer kills a running job. Measured: a
20-minute job survived the page being stopped and wrote its result.
- `backends.py`: registers `windows`, and routes a local `process`
campaign to it on Windows, since that is what the agent declares for a
command on the owner's machine.
- A POSIX `remote_dir` (the `/root/raven-ops` submit default, which
never reaches `meta.json`) maps to `~/raven-ops`, so the submit path and
the status path look in the same directory.
- `ledger.py`: skip the directory fsync on Windows (opening a directory
raises EACCES; NTFS journals the rename).
- `tui_commands.py` / `_tui_relay.py`: do not forward SIGINT to the
child on Windows. The console already delivers Ctrl+C to it, and
`Popen.send_signal(SIGINT)` raises ValueError, which took the TUI down.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
On Windows 11, Python 3.13, `uv sync --extra dev`, `PYTHONUTF8=1`:
- `uv run pytest tests/ -k "oncall_flow or tui or acp_commands or
ledger"`
- this branch: 14 failed, 1091 passed, 15 skipped, 18 errors
- `origin/main`: 126 failed, 976 passed, 15 skipped, 18 errors
- no test fails on this branch that passes on `origin/main`; the
remaining failures and the 18 collection errors are identical on both
(POSIX shell tests, missing optional modules).
- `uv run pytest tests/test_agents_oncall_flow_windows_backend.py`: 3
passed, including a job that survives `taskkill /T` of the process that
submitted it.
- `uv run ruff check` and `uv run ruff format --check` on the changed
files: clean.
- [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 describe on-call backends per platform, so none were
changed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Behaviour changes only on Windows (`os.name == "nt"` / `sys.platform ==
"win32"` guards); POSIX hosts take the same code paths as before. A job
started on Windows now outlives the host by design; `cancel` still stops
it. Rollback: revert this commit.
## Related Issues
N/A
---------
Co-authored-by: silverLXT <xiaotian.luo@evermind.ai>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
- Replace outdated WhatsApp bridge recovery guidance with the official
installer recommendation.
- Clarify that Python plugins cannot yet be installed from the market
and remove misleading pip/uv suggestions.
- Add regression coverage for both install hints.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Commands and results:
- `uv run --frozen --python 3.12 --all-extras pytest -q` - 27554 passed,
119 skipped.
- `npm test --prefix ui-web` - 3185 passed on rerun. The first full run
had 3 intermittent failures in 2 unrelated session-state test files;
both files and the full suite passed on rerun.
- `make lint` - passed.
- `make test-tui build check-core-wheel PYTHON_VERSION=3.12` - passed;
TUI had 2111 passing tests and the core wheel smoke test passed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#845
## Summary
Follows #1005, which is now on main; main was merged in after it landed,
so the diff against main is this change alone.
A registered machine whose node is up left the owner with nothing to do:
the card said
"Link up, no agent" and the Agents tab did not mention the machine. The
way to connect
an agent on it (the preset sheet's *Runs on*) is hidden exactly where it
is needed most:
a preset already connected on this computer is withheld from the roster,
and a preset not
installed here shows only install instructions. Measured on the owner's
own setup
(2026-10-19): two machines registered from the page, both reached and
with the node,
and no path on the page to put Claude Code on either.
What changes:
- `machines.list` rows carry `agents_here`, the connected agent entries
that run on the
machine (`agents_on_machine(only_enabled=True)`; a malformed agents
section lists none).
The card says "N connected here: ..." or "No agent connected here yet";
the state line
now reads "Link up, no agent running", so "running now" and "connected
here" are two lines.
- A ready machine's sheet says the next step and offers **Connect an
agent on this machine**:
a form in the same drawer with the preset, its working directory there,
and Connect. It
calls the existing `subagents.add` with `machine`, `remote_cwd` and the
name fixed to
`<preset name>@<machine id>`, so the proof ping and every refusal are
the add's own.
- New read-only `subagents.presets`: the presets a machine's node can
start (acp, cli),
listed whether or not an entry already holds them, with `connected_here`
and
`on_machines` so the form greys the one this machine has and says when
this computer
has it too. Built-in agents, Mirasim shims and openai endpoints are not
listed.
- The Agents tab's "not installed" sheet also offers *Runs on* when ssh
machines are
registered, with a Connect button once a machine is picked: running on a
machine does
not need the agent on this computer.
- New read-only `machines.local_keys`: the private keys this computer
has, as `~/.ssh/<name>`
(ssh's default identities in ssh's order, then any file with a `.pub`
beside it). The
register form fills the key path with the first and offers the rest,
instead of a
placeholder naming `id_ed25519` to an owner whose key is `id_rsa`; with
none found it
says so and points at the password login.
- One preset once per machine, held by the server whichever way the add
arrives: `subagents.add`
without a `name` now refuses a preset the machine already has (judged on
preset + machine, before
the ping), naming the entry there and whether it is connected or
switched off; a named add is a
second entry on purpose (two working directories, say). The page's
connect form leaves the name to
the server's default (`<preset>@<machine id>`) rather than fixing its
own spelling, so the page and
a chat can no longer put one agent on one machine twice between them
(the owner's setup had the two
routes spelling the default differently, 2026-10-19).
Contract (`rpc-schema/openrpc.json`), models, both generated clients and
`i18n/messages.json`
are updated; the offline fixture library answers the two new methods and
the new field, and refuses
the duplicate the way the server does.
Docs: the machines guide (en + zh), CHANGELOG, CONTEXT.
**Fifth round, after the review draft on LivXue's board (four findings,
all reproduced) and the bot's inline note.** `machines.list` read the
agents section for every row and caught only the pydantic error, so a
`config.json` that does not parse at all (a `//` comment, a trailing
comma) failed the whole listing with `internal_error` while the gateway
ran on: `_agents_here` now treats the loader's `ConfigReadError` the
same way (nothing listed; the agents page says why), and the test is a
real unparseable file. The register form proposed `id_ed25519` before
`id_rsa` and called that ssh's order; `ssh -G` lists `id_rsa` first on
OpenSSH 8.9, 9.6 and 9.9, so an owner with both was proposed the key ssh
itself tries second: `DEFAULT_IDENTITIES` follows the measured order, a
test pins it against the ssh of the computer running it, and the guide's
two sentences say so. A row that exists, switched off, with its command
missing here, was offered **Connect on <machine>** from its sheet while
the press sent the row's own `toggle`, which carries no machine: only a
preset not yet on the roster is offered one, as the other *Runs on*
already did. An add still running on a machine was unknown to a form
opened again on that machine, so the preset could be pressed twice (a
second proof prompt, then the duplicate refusal, a toast saying
connected and a form saying not): the adds in flight are kept by the
name each lands under (`mconnectPending`) and the form greys that preset
(*being connected on this machine right now*). The contract's
`subagents.presets` description names the add's default
`<preset>@<machine id>` now, as the bot noted. The branch also carries
#1005's fourth commit (merged) and main up to #1001.
**Sixth round: merged onto #1005's head (`9dbef0874`) and LivXue's F1
fixed.** The merge had three conflicts, all the same shape -- this PR's
addition beside what #1005 changed (the `auth` field in the machine
sheet, `agents_here` in the fixtures, the new register assertions) --
and keeps both sides; the superseded password-used-once code
(`generate_key`, `install_public_key`, `revoke_public_key`,
`forget_key`, the remote scripts) is gone from the diff, so a review of
this PR no longer grades that design. F1: a connect form open across a
write reads `presets` again when the add lands -- whichever opening it
is -- so a preset just connected on that machine reads as taken instead
of inviting a second add the server refuses; the case that pinned the
wrong end state moved with it. F2 (four ui-web files reformatted to the
root prettier style) is withdrawn in 1834c68ee: each file is the #1005
text with this PR's own hunks replayed onto it (a three-way merge of the
base, the base formatted the way the reformat had been, and this
branch's head; ten overlaps resolved by hand, the maintainer edits'
lines included), so what remains in them is this PR's change -- the four
files' lines against #1005 go from 173/211/281/1694 to 137/44/206/590.
Check used: formatting the result with the root config reproduces the
previous head except where that head itself kept hand style, so nothing
but wrapping changed.
Verification, sixth round: related Python `1068 passed` over the twelve
files this PR touches or affects, diff coverage 96.13% (348/362
executable changed lines); full suite `-n 6` 33386 passed, 3 failed --
the LibreOffice case and the two simulation cases this Mac always fails
(run before the F1 commit, whose change is ui-web only); ui-web `vitest
run` 4121 passed (250 files, gates included), `tsc --noEmit` and
`eslint` clean, `gen:check` 247 methods; ui-tui `lint:i18n` and
`lint:rpc` clean; the three range gates over `origin/main..HEAD`.
**Also merged: #1005's c0c822294** (Oncall campaigns run on a password
machine through trunk's askpass; the helper answers a password prompt
only; `--password-stdin` implies `--auth password`) and the three
maintainer edits on this branch (68ea01189, e5884ddf1, dac563aab), all
clean.
**Seventh round: two findings from the review of 91952baed.** (1) A
configless Raven held a kept machine password unscrubbed: `held_secrets`
returned early when `config.json` was missing, before it read
`keys/<id>.password` -- and those live under the Raven home
independently of any config, so a tool printing that file passed the
password to the model verbatim (gloryfromca, inline). An absent config
is now an empty config-credential set rather than the end of the call;
the case is pinned with no config file at all, and the existing "no
config holds nothing to scrub" case still holds for the config's own
credentials. (2) CI shard 3/4 failed on
`tests/test_node_stderr_replay.py::test_a_reason_written_on_stderr_while_the_link_was_down_reaches_the_run_watching_it`
("did not happen in time", then a leftover agent in its teardown) and
`tests/test_subagent_cli_remote.py::test_...` -- both stand-in-machine
timing cases this branch does not touch, the same class as the ones
recorded for #965/#979/#983; 135 passed over those three files locally
in one run, and the job passes on rerun.
Verification: `tests/test_held_secrets_machine_passwords.py` and
`tests/test_security_untrusted_context.py` 42 passed; the other three
files that read the scrubber 223 passed; `ruff check`, `ruff format
--check` and `ty check` clean on the two changed files; the three range
gates over `origin/main..HEAD`.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest tests/test_rpc_machines.py tests/test_ops_connection_add.py
tests/test_rpc_subagents.py tests/test_rpc_schema_match.py
tests/test_rpc_registration.py -n 4`: 768 passed (7 new: `agents_here`
incl. the malformed-section case, `local_keys` order and exclusions at
both layers, `subagents.presets` membership and placement).
- Full suite `pytest -n 6`: see the last comment on this PR for the
count (run at the head).
- `ruff check` / `ruff format --check` on the changed Python files:
clean.
- Duplicate-on-machine refusal: 2 new cases in
`tests/test_rpc_subagents.py` (default-named second add refused before
any ping, naming the entry and its state; named add allowed; another
machine allowed; switched-off entry named), both fail with the handler
change stashed; related groups 928 passed after it.
- ui-web: `vitest run` 4006 passed (250 files, page gates included; 7
new page cases: the card line and the sheet's next step, the connect
form end to end incl. a refusal and the nothing-to-connect case, key
prefill with and without keys, an absent agent connected onto a machine
from its own sheet, and no machine offered when none is registered);
`tsc --noEmit` clean; `eslint` clean on the changed files; `gen:check`
matches the contract.
- ui-tui: `gen:rpc` and `gen:i18n` regenerated; `pytest
tests/test_docs_site.py` 16 passed; `mkdocs build --strict` clean.
- Real machine, isolated gateway (own Raven home and registry copy,
channels off, the branch's node installed in its own directory on the
test machine), real browser: the ready machine's sheet shows the next
step and the button; the form lists 12 startable presets; Connect of
Claude Code on the machine landed in 9 s and the card then reads "1
connected here: Claude Code@<id>"; the register form was prefilled with
this computer's `~/.ssh/id_ed25519` with `id_rsa` as the other choice;
an agent absent here (OpenClaw) connected onto the machine from its own
sheet was refused in 1 s with the agent's own sentence ("the agent's
command was not found on machine ...") shown in place. Gateway stopped
by pid, the node directory and daemon on the machine removed afterwards.
- Previews of the five surfaces were shown to the owner before the
change and approved.
- Fifth round, red before and green after: `machines.list` over a real
`config.json` that is not JSON lists the machine with no agent
(`test_list_lists_no_agent_over_a_config_file_that_does_not_parse_rather_than_failing`;
through the real `Dispatcher` with a scratch home and registry, the
previous handler answered `-32603 internal_error`, this one `[('box',
[])]`); `local_keys` order at both layers, plus
`test_the_default_identities_are_in_the_order_this_computer_s_ssh_offers_them`
against `ssh -G -F /dev/null` (this Mac, OpenSSH 9.9: `id_rsa, id_ecdsa,
id_ecdsa_sk, id_ed25519, id_ed25519_sk, id_xmss, id_dsa`; the same on a
registered Linux machine, OpenSSH 9.6); the page: a configured,
switched-off, missing row gets no machine field and no *Connect on*
(`offers a row that exists no machine...`), and a form opened again on a
machine while an add still runs there greys the preset, keeps the other
one pressable and sends no second add (`greys a preset whose add on the
machine is still running...`) -- both fail with the three page sources
stashed. The six Python files 821 passed, diff coverage of the changed
lines 97.50%; ui-web `vitest run` 4119 passed (page gates 216 included),
`tsc`, `eslint` on the feature, `gen:check` (247 methods), `npm run
build` with both boot goldens; ui-tui `gen:rpc`/`gen:i18n`, `lint:i18n
-- --check`; `ty check` on the changed modules; `pytest
tests/test_docs_site.py tests/test_living_docs.py` 18 passed, `mkdocs
build --strict` clean; the three range gates; full suite (`-n 6`) 33353
passed, 4 failed: the three this Mac always fails (a LibreOffice case,
two simulation cases) and one stand-in-machine timing case in
`tests/test_subagent_cli_remote.py` (the record not yet written when the
test reads it) that passes 3 of 3 runs alone and touches no file this
branch changes.
## Risk
- [x] Security impact considered: `machines.local_keys` returns key
*paths* on this computer, to this computer's own page, never key
material; `subagents.presets` carries no credential; nothing new leaves
the host. The connect form reaches the machine only through the existing
`subagents.add` and its proof ping.
- [x] Backward compatibility considered: `agents_here` is a new required
field on `machines.list` rows (the page maps it defensively); the two
new methods are additive; an older page against this server ignores
both.
- [x] Rollback path is clear for risky changes: revert the commit; no
stored data changes shape.
## Related Issues
N/A (follow-up to #983 and #1005, from the owner's walkthrough on
2026-10-19)
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
Co-authored-by: MiniMax (minimax-m3.1-flash-free) <noreply@minimax.io>
## Summary
An on-call agent's question to its owner never reached the owner when
the agent ran as an ACP sub-agent. `ops_ask_owner` handed the allowed
question back to the model to send with the `message` tool. Over ACP
that text goes into the running turn: the host gathers it into the run's
transcript, and since a sub-agent's result is its last message, the main
session never receives it. In a recorded run the agent asked how the
owner wanted an acceptance standard read, and nobody saw the question.
Nothing kept the question open either. The question trail treated any
later note as an answer, so the loop's own progress note closed it, and
it then closed the campaign around the question.
What changes, all inside the on-call plugin (no host or ACP change):
- **Delivery.** An allowed question is put through the host's existing
`direct_ask` grant on a task of its own, and the tool returns at once so
the loop carries on. In the on-call agent this goes through the
runtime's question broker to the ACP bridge, which sends
`elicitation/create` to a host that declared form support. The host's
existing handling applies: the form is shown for the broker's while, and
the host model may fill an answer only from what the owner already said
this turn. Without the grant, the model-mediated text is returned as
before.
- **Answers.** A non-empty answer is written to the notes as the
owner's, tagged with the question's id. It is logged as `owner_answered`
and pulls the campaign's wake to now. An empty answer (the form timed
out, was dismissed, or was displaced by another question) is logged as
`ask_owner_unanswered` and leaves the question open. The ten-minute wake
the ask already arms then runs the existing no-answer choice: do work
that does not depend on the answer, wait once more, or close. Nothing is
re-sent automatically.
- **Arguments.** `options` (the choices, each with its cost) and a
required `if_unanswered` (the default the loop follows when nobody
answers). The description asks for questions about goals and standards
rather than about how to do the work, written so someone who does not
know the method can answer them.
- **Question state.** Every ask carries an `ask_id`. A question is
closed in three ways:
- the owner speaks after it: an answer to that id, or anything they type
into the window;
- `ops_note` with `settles_question=true`, when the loop goes ahead on
its default;
- it is withdrawn, because a new question replaces it or the campaign
closes.
Notes the loop writes about its own work no longer close a question, and
an answer to an older question does not close a newer one. Asks recorded
before ids existed keep the old reading, so campaigns already on disk
read the same.
- **Closing.** `ops_finish` still refuses while a question is open. It
takes down a form still showing, and the report gets one `decided
without the owner` line per question that was settled on its default and
never answered.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
New tests:
- `tests/test_agents_oncall_flow_policy.py`, the question trail:
- the loop's own note does not close a question with an id, and the
owner speaking does;
- settling on the default closes it and is listed as decided without the
owner, until the owner answers after all;
- an answer to an older question leaves the newer one open.
- `tests/test_agents_oncall_flow_escalation_tools.py`, the tool:
- the tool returns while the grant is still waiting;
- the answer lands in the notes as the owner's and pulls the wake (real
`CronService` behind the grant);
- an empty answer leaves the question open;
- a new question withdraws the previous one;
- settling then closing works and the report says so;
- without the grant, the message-tool text is returned;
- one test runs the real path past the grant: `QuestionBroker` to
`AcpQuestions` to an `elicitation/create` frame, whose answer comes back
as the owner's.
Mutants, each killed:
- never using the grant: 6 failed
- any note closing a question with an id: 3 failed
- an owner note for another question closing it: 1 failed
- close not withdrawing the form: 1 failed
- report omitting the undecided questions: 1 failed
Commands:
- `uv run --no-sync pytest -q -p no:randomly
tests/test_agents_oncall*.py tests/test_acp_*.py tests/test_ask_user*.py
tests/test_subagent_acp.py tests/test_cron_*.py
tests/test_question_broker.py`: 2745 passed, 9 skipped, 1 failed. The
failure is
`tests/test_acp_leftovers.py::test_on_macos_the_watcher_ends_nothing_when_the_agent_does_not_lead_its_group`.
It is intermittent on this machine and fails the same way on a tree
without this change (4 of 5 runs). This change does not touch it.
- `ruff check` and `ruff format --check` on the changed files: clean
- `uv run --no-sync ty check
agents/raven-oncall/plugins/oncall-flow/oncall_flow/`: all checks passed
- `uv run --no-sync lint-imports`: 10 kept, 0 broken
- `scripts/check_commit_messages.py`,
`scripts/check_source_language.py`, `scripts/check_large_files.py` over
`main..HEAD`: all pass
Not run: the full `make test-python` suite, and a run with a real model
and a real host TUI.
- [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
Behaviour changes for the on-call agent:
- The owner sees its questions as a form in the host instead of never
seeing them.
- `ops_ask_owner` requires `if_unanswered`.
- A note the loop writes no longer closes an open question; the loop has
to say `settles_question=true`.
While a question's form is showing, the host's question slot for that
conversation is in use, as with any sub-agent question today.
Rollback is reverting this commit. Campaign files written by it remain
readable by the old code, which ignores the new fields.
## Related Issues
N/A
Co-authored-by: xiaotian.luo <xiaotian.luo@thetahealth.ai>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
Add a Machines tab to the Agent Hub and let owners register an SSH
machine with either a key or a password.
- The Machines tab reuses the existing machine cards, details and
registration form. The hub remembers the last selected module. Machine
details show the login method, and removal explains that the locally
stored password is deleted.
- Password registrations keep a 0600 credential file under the Raven
home's 0700 keys directory. Registration, node installation, file tools,
tunnels and Oncall use the shared SSH askpass transport. Passwords are
excluded from command lines, registry rows and responses, and included
in held-secret scrubbing.
- Password connections authenticate independently, disable inherited
jump hosts, and answer only the registered account's password prompts.
Oncall cannot redirect a stored password to another endpoint. Windows
rejects this mode before creating credentials because its OpenSSH cannot
execute Raven's POSIX helper. Key authentication remains supported as
before.
- Concurrent registrations preserve the successful request's password.
Each probe uses its own temporary 0600 credential file, which is
scrubbed and removed afterwards. Password writes receive a file
identity; cleanup checks ownership under the writer's lock. Successful
registration checks duplicates again and publishes its password with the
registry row under that lock. Both completion orders, RPC cancellation
and CLI aborts are covered.
The RPC contract adds optional `MachineRow.auth` and password
registration parameters. English and Chinese machine documentation, the
runtime context and changelog describe the resulting behavior.
## 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
After rebasing onto the latest main:
```bash
uv run --no-sync pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_ops_transport.py tests/test_cli_ops_connection_commands.py tests/test_rpc_machines.py tests/test_held_secrets_machine_passwords.py tests/test_acp_remote.py tests/test_node_client.py tests/test_rpc_schema_match.py tests/test_rpc_registration.py tests/test_import_cycle_budget.py -q -n 0 --tb=short --cov=raven.ops.connection_add --cov=raven.ops.transport --cov=raven.cli.ops_connection_commands --cov=raven.rpc.methods.machines --cov-report=json:/tmp/pr1005-fix-coverage.json
```
Result: 932 passed, 6 skipped. The skipped cases require zsh, tcsh or
csh, which are absent on this Linux host.
- `uv run --no-sync python scripts/coverage_gate.py --coverage-json
/tmp/pr1005-fix-coverage.json diff --base-ref HEAD^ --threshold 99`:
100% (94/94 executable changed lines) for the concurrency fix.
- `uv run --no-sync pre-commit run --from-ref HEAD^ --to-ref HEAD`:
passed, including formatting, file checks and private-key detection.
- `uv run --no-sync ty check raven/ops/connection_add.py
raven/ops/transport.py raven/cli/ops_connection_commands.py
raven/rpc/methods/machines.py`: passed.
- `uv run --no-sync lint-imports`: all 10 contracts passed.
- `uv run --no-sync python scripts/check_source_language.py
origin/main..HEAD`, `uv run --no-sync python
scripts/check_commit_messages.py origin/main..HEAD`, `make
check-large-files`, and `git diff --check origin/main...HEAD`: passed.
The original RPC failure/cancellation and CLI-abort reproductions failed
before the fix. Additional regressions cover the reverse completion
order, probes with competing passwords, temporary-secret scrubbing,
duplicate registration and failed registry writes. The complete rebased
source was compared with the original PR plus main, and the concurrency
fix retained its patch identity.
## Risk
- [x] Security impact considered: stored and temporary passwords are
owner-readable and scrubbed from tool output. Unknown SSH host keys are
accepted on the first connection, as before; the guides explain
verifying the host from a terminal first on an untrusted network.
Passwords shorter than six characters or containing CR/LF are rejected.
- [x] Backward compatibility considered: key registration remains the
default and `MachineRow.auth` is optional. Password publication and
cleanup now use file locks and atomic replacement; temporary probe files
are removed when the probe ends.
- [x] Rollback path is clear: revert this PR to restore the earlier
registration flow. Removing a machine deletes the password stored under
its id. Existing password rows require migration to key authentication
if reverting the feature.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
Co-authored-by: MiniMax (minimax-m3.1-flash-free) <noreply@minimax.io>
Co-authored-by: Codex <noreply@openai.com>
## Summary
Adds two things to bug reporting, on the Bug Report Receiver and on the
Raven clients that send to it.
**A hello probe.** The receiver answers `GET /v1/hello` with its service
name and protocol version, and Raven asks it before a report starts, so
a person learns that the receiver is down (or that the URL leads to
something else) before spending a redaction review on the report:
- `raven trajectory report-bug` and the trajectory browser's *Report a
bug* probe before collecting anything. On a TTY without `--yes` they ask
whether to continue (default no; declining collects and pins nothing).
With `--yes` they say they are continuing and keep the package if the
upload then fails. Without a TTY and without `--yes` the existing rule
still refuses first.
- The WebUI's *Report a problem* wizard asks the new RPC
`bugreport.probe` when it opens. When the receiver does not answer, the
report does not start: the wizard shows the reason and *Check again*,
and the primary button becomes *Continue anyway*, so going on is the
reader's explicit choice and never a dead end. A start pressed while the
check runs waits for it (at most 8 s) and then checks the form again.
- The probe runs under one deadline for the whole exchange (5 s), does
not follow redirects, and the new requests never echo credentials or
query tokens from a redirect target.
- `/healthz` stays as the operator's liveness check. It was not reused
for the probe because anything alive answers ok there, and it is not
under a base URL's path prefix.
**An upload challenge.** The receiver now takes only uploads that answer
its Upload Challenge: the client gets a challenge from `POST
/v1/challenge` and sends back an HMAC, under a constant built into
Raven, of the challenge and the package's report id, sha256 and size.
Key decisions:
- Shallow by design. The goal is that an HTTP client that is not Raven,
written without reading Raven's source, cannot upload. The constant is
published with the (public) source and is not configurable, so there are
no credentials to manage. The docs say so, with a table of what the gate
stops and what it does not.
- Stateless. Challenges are sealed with a per-process random key, are
valid for 300 s and are not consumed; a restart retires them all.
Replaying a captured upload as it was only re-delivers the same package,
which the receiver already answers as a duplicate; replaying it with
another package fails because the answer is bound to the package.
- Checked from the headers alone, after the existing header checks and
before the daily budget is reserved: a refused upload gets 401
(`unauthorized` or `challenge_expired`) with `WWW-Authenticate:
Raven-Challenge`, writes nothing, and still spends a rate-limit token.
Package checks, rate limits, budgets and timeouts are unchanged.
- The client fetches the challenge inside the upload's existing total
deadline. A 404 there means a receiver older than this Raven; a 401 is
retryable only when the challenge expired.
Uploading has not shipped in a release yet (it is under `Unreleased` in
the CHANGELOG), so no released client breaks. A receiver deployed from
main must be upgraded together with its clients, and a proxy in front of
it must forward all of `/v1/`; the docs and the CHANGELOG entry say so.
Commits, in order: the hello route and the client probe; the challenge
end to end (new `raven/trajectory/receiver_auth.py`, and the Upload
Challenge term in `CONTEXT.md`); the CLI probe; the WebUI probe (RPC,
wizard, i18n, regenerated ui-web and ui-tui bindings); a fix that checks
the form again after the wizard waits on the probe; the docs in both
languages; integration tests against real processes.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run --no-sync pytest tests/test_trajectory_receiver_auth.py
tests/test_trajectory_receiver.py tests/test_trajectory_upload.py
tests/test_rpc_bugreport.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py
tests/test_trajectory_report_session.py tests/test_rpc_schema_match.py
-q --idle-ceiling-strict --cov=raven --cov-branch
--cov-report=json:coverage.json`: 1190 passed.
- `make coverage-diff COVERAGE_BASE_REF=origin/main`: 99.53% of changed
lines (213/214), threshold 90%.
- `uv run --no-sync pytest
tests/integration/test_bug_report_upload_e2e.py
tests/integration/test_web_bugreport_e2e.py -m integration -n 0 -q`: 10
passed, three runs in a row.
- `uv run --no-sync pytest tests/ -q`: 102 failed, 33527 passed. All 102
are in 14 files this PR does not touch (code tools, code flow, subagent
probe and backends, a2a, whatsapp, provider config and rates, security
network, everos, tracing command), and the same 102 fail on the base
commit (checked on a worktree of `main`; the two failure sets are
identical).
- `make lint-python`, `make lint-imports` (10 contracts kept), `deptry
raven`: pass. `make lint-types`: only two `pyflakes.checker` unresolved
imports in
`agents/raven-code/plugins/code-flow/code_flow/tools/diagnostics.py`,
because pyflakes is not installed in the local environment (CI installs
all extras); every changed Python file passes `ty check`.
- `mkdocs build -f docs-site/mkdocs.yml --strict`: pass.
- ui-web: `gen:check`, `lint` (0 errors), `type-check`, `npx vitest run
--maxWorkers=8` (251 files, 4176 tests), `build` + `build.py` +
`check-page` / `check-css` / `check-class-namespace`: pass.
- ui-tui: `lint`, `lint:rpc`, `lint:i18n`, `type-check`, vitest (2242
tests), `build`: pass.
- `make check-source-language check-large-files check-commits`: pass.
- Manual, on real processes: a receiver plus curl (hello and challenge
answer; an upload without an answer, or with a forged one, gets 401 and
nothing is stored); the CLI (an upload while the receiver runs; while it
is down, the warning, continuing and the kept package; declining on a
TTY leaves nothing); a real gateway walked with Playwright in English
and Chinese at 1280 and 360 px (the warning while the receiver is down,
Check again after it starts, a report through to its receipt, no page
errors, no overflow).
- [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:
- With an upload URL configured, `report-bug` and the browser's *Report
a bug* start with a probe of at most 5 s, and ask one more question when
the receiver does not answer. The WebUI wizard shows a warning and
*Continue anyway* in that case.
- The receiver refuses uploads that do not answer the challenge. A
receiver deployed from main must be upgraded together with its clients
(no released client uploads yet). A proxy that only forwarded
`/v1/bugreports` must forward all of `/v1/`.
- No change to package formats, `record.json`, or anything stored on
either side.
Rollback: revert the squash commit; there is nothing to migrate.
- [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) <noreply@anthropic.com>
## Summary
The web composer initially displayed hardcoded `minimax-m3` until a full
provider catalogue finished loading, even when another model was
configured. Read the actual model/provider selection immediately after
the gateway handshake, independently of catalogue building and provider
probes when the gateway supports it.
- Add optional `model.options.include_providers` with its existing
full-catalogue behavior as the default. Advertise selection-only support
through `system.hello.server_capabilities`; older strict gateways
receive their original parameters and share one full catalogue request.
- Show loading, empty and retry states. Permit sending once the
selection arrives, and keep a known selection usable during background
refreshes of the same view. First reads and navigation to another
session or a new draft still wait for that view's selection.
- Allow settings role pickers to use their available rows while the
composer's provider catalogue refreshes. Keep New Task available during
selection loading or failure, retain provider-setup redirects, and clear
catalogue loading state if a gateway call throws synchronously.
- Preserve session bindings, forced default providers and staged draft
picks. Ignore responses superseded by navigation or a local pick, and
prevent slow catalogues from overwriting the selection.
- Update fixtures, generated web/TUI contracts, bilingual messages and
user-facing documentation.
Maintainer follow-up on top of the author's commits (no history
rewritten):
- Restored the design comment in `model_options` that explains why a
catalogue read warms the rate catalogue (the picker's context windows
come from it and nothing else on the page refreshes it), and said why a
selection-only read skips it. The handler and module docstrings now
describe `include_providers`.
- Restored the comment in `loadProviders` that explains why a late
catalogue answer is dropped, now also naming a later refresh of the same
view.
- Reverted the remote CLI test change
(`tests/test_subagent_cli_remote.py`), which was unrelated to this fix.
The final diff no longer touches that file. The race it addressed is
real and still open on main (see Risk), so it should land as its own
change; the original commit remains in this branch's history.
- A draft promoted to a conversation keeps its known selection. The
promotion takes no new view ticket, so the first same-view re-read of
the new conversation (a settings-changing tool result, a provider or
default-model write, a typed id) used to drop the chip to "Loading
model..." and refuse sends until that read answered. The promotion now
hands the draft's selection to the session it minted, but only when that
selection was read under the ticket the promotion began on; a reader who
opened another conversation or a new draft during the create keeps that
view's own selection, and a draft whose selection never arrived or
failed still waits. The README says so.
- Named the provider list as `ui-web/CONTEXT.md` does: the two keys this
change added are now `gui.model.provider_catalogue_loading` and
`gui.model.provider_catalogue_failed` (texts unchanged, generated TUI
catalogue regenerated), and the `ModelSource` comment, the README and
this change's test titles say provider catalogue instead of the bare
word, which the existing `gui.model.catalogue_*` keys use for a vendor's
model list.
## Type
- [x] Fix
- [ ] 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
Maintainer verification on Linux, Python 3.12 (`--all-extras`), Node 26,
in isolated worktrees with their own virtualenv and `npm ci`. "Merged
tree" means this branch merged into the latest main without committing;
it merges cleanly.
Branch head:
- `uv run --frozen --python 3.12 --all-extras pytest
tests/test_rpc_model.py tests/test_rpc_schema_match.py
tests/test_rpc_system.py -q`: 772 passed (238 in
`tests/test_rpc_model.py` after the wording change).
- `npx vitest run --maxWorkers=6 --testTimeout=20000` in `ui-web` (with
`NODE_OPTIONS=--localstorage-file=...`, which this Node version needs):
4004 passed, 0 failed.
- The promotion regression, `src/state/session/runtime.promote.test.ts`
"the model chip across a promotion": eight cases on the real registry,
promotion, chip source and store with only the transport faked, each run
with and without the selection-only capability. The first-re-read case
fails on the previous head (status `loading`, send refused) and passes
with the fix. Removing the hand-off call fails exactly those two cases
(179 of 181 model and promotion tests still pass); removing its ticket
guard fails exactly the two cases where the reader left during the
create.
- `npm run type-check`, `npm run gen:check`, `npm run lint` in `ui-web`:
pass, lint 0 errors and 4 existing warnings in untouched files. `npm run
lint:rpc` and `npm run lint:i18n` in `ui-tui`: pass.
- `scripts/check_commit_messages.py`, `scripts/check_large_files.py`,
`scripts/check_source_language.py` over the branch, and `commitlint
--from origin/main`: pass.
Merged tree, this head on the latest main (as of #985), merged without
committing:
- Full `ui-web` vitest run as above: 4158 passed, 0 failed.
`type-check`, `gen:check` and `lint` pass; `python ui-web/build.py`
passes both boot snapshots (365 and 364 nodes).
- `tests/test_rpc_model.py`, `tests/test_rpc_schema_match.py`,
`tests/test_rpc_system.py`: 788 passed. `ui-tui` `lint`, `lint:rpc`,
`lint:i18n`, `type-check`: pass. `ruff check`, `ruff format --check`,
`lint-imports` (10 contracts kept), `deptry raven`, `ty check`: pass.
Earlier merged-tree runs, before this round's two follow-up fixes (which
change only web code, the README, i18n keys, test titles and one Python
comment):
- Full Python suite on the merge with main as of #1002, `uv run --frozen
--python 3.12 --all-extras pytest -q`: 33222 passed, 102 failed. Rerun
on bare main on the same machine, exactly those 102 test ids fail there
too (this machine's environment), so no failure is introduced by this
branch. An earlier full run of the merge, against main before #1002,
also errored in the remote CLI cancel test; that test file is identical
to main's, and whole-file runs of it on bare main failed 1 of 5 with the
same race (see Risk).
Real page, before this round's fixes, isolated gateways (own RAVEN_HOME,
loopback only), headless Chromium, configured model
`deepseek/deepseek-chat` with a dummy key, recording the chip text and
the page's own `model.options` frames:
- Main's page on main's gateway: the chip reads `minimax-m3`, enabled,
from 198 ms until the full catalogue answers at 986 ms. This is the
reported bug.
- This page on this gateway: "Loading model..." (disabled) until the
selection-only read answers about 100 ms after the handshake; the chip
shows `deepseek-chat` at 593 ms while the 55-row catalogue answers at
1817 ms.
- This page on main's gateway (no capability): only the legacy `{}` read
is sent, no validation error, and the chip goes from "Loading model..."
to the configured model when that read answers (706 ms).
Earlier verification by the author on Windows, before the follow-up
commits: `tests/test_rpc_model.py` and `tests/test_rpc_schema_match.py`
665 passed; the hello/ping/version/dispatcher subset of
`tests/test_rpc_system.py` 26 passed; `ui-web/build.py` boot snapshots
matched; `ui-web` `npm test` 3,278 passed across 215 suites,
`gen:check`, `type-check`, `build` and `lint` passed; `ui-tui`
`lint:rpc` and `lint:i18n` matched.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The new read mode is read-only and returns no provider credentials.
Existing RPC callers (the TUI picker and the ACP config options) omit
the field and keep full provider catalogue responses; web clients
negotiate support before sending it. A failed selection read requires a
retry, while a pending refresh of a known selection, including the first
re-read after a draft becomes a conversation, allows sending. Settings
role pickers and task navigation no longer inherit the composer's
loading restriction.
Known behavior, not changed here:
- Every navigation, including the boot's own switch to the draft view,
waits for that view's selection, by design and as tested. On the real
page this shows "Loading model..." again for about 90 ms right after the
first selection appears. Against an older gateway each such wait lasts
as long as the full provider catalogue read.
- With the remote CLI test change removed,
`test_a_cli_run_left_on_the_machine_when_this_computer_stops_is_picked_up_by_the_next_start`
and its cancel sibling keep main's race: they wait for the pid file,
then read the run record that may not be written yet. A parallel local
run of the three RPC files plus that test file on this branch hit it
once. It is the same flake main has today.
Roll back by reverting this change and rebuilding the served web page;
no configuration migration is required.
## Related Issues
Fixes#819
---------
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
## Summary
Windows hosts can lend granted MCP servers to local and machine-based
ACP agents through authenticated loopback endpoints. Hosts with Unix
sockets retain that transport. Server definitions, upstream credentials,
sandbox policy and disabled-tool enforcement stay on the host.
- Share one connector between the local bridge and node client. Bind TCP
endpoints only to 127.0.0.1 and authenticate with a fresh per-endpoint
token before opening an upstream.
- Read inherited Windows stdin pipes through a daemon worker with
backpressure. Acknowledge each chunk on the event loop before reading
another, so neither the reader buffer nor queued callbacks can grow
without bound.
- Cancel both bridge pumps on exit, allow up to one second for the
endpoint connection to flush, then abort the transport if it still holds
unsent bytes. A peer that stops reading cannot hold failure or
cancellation cleanup indefinitely.
- Resolve this installation's raven.exe, preserve task and session
isolation, hide endpoint credentials from grant representations, and
redact them in bridge diagnostics and session-start journal frames.
Remote dispatches do not receive the host's loopback token.
- Update capability reporting, CLI help, the remote ACP entry's
`machine` docstring, CONTEXT.md and the English/Chinese collaboration
guide. Add Windows CI coverage and exercise both Unix and TCP endpoints
on Linux.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Docker Linux, Debian Bookworm with procps and git, Python 3.12.12,
--init, a native Linux source copy, and a frozen environment: 783
related unit tests and all 3 real-server integration tests passed. The
source and test files were compared with the committed versions before
publication.
```sh
uv sync --frozen --extra dev
uv run --frozen --no-sync pytest tests/test_mcp_transport.py tests/test_mcp_bridge.py tests/test_mcp_endpoint.py tests/test_cli_mcp_commands.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_node_client.py tests/test_acp_journal.py tests/test_subagent_acp_remote.py tests/test_subagent_manager.py tests/test_subagent_mcp_grant.py tests/test_subagent_third_party.py -q -n 4 --dist loadfile --tb=short --cov=raven --cov-report=json:/out/coverage.json --junitxml=/out/units.xml
uv run --frozen --no-sync pytest tests/integration/test_mcp_bridge_e2e.py -m integration -q -n 0 --tb=short --junitxml=/out/integration.xml
```
PR diff coverage is 98.26% (169/172 changed executable lines), above the
unchanged 90% threshold. On the host checkout, `$coverageReport` points
to the JSON exported by that Linux run:
```powershell
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json $coverageReport diff --base-ref origin/main --head HEAD --threshold 90
```
Native Windows, Python 3.13.12, a separate frozen environment and
PYTHONUTF8=1: all 21 bridge unit tests passed; all 8 integration cases
passed, comprising 3 MCP bridge cases and 5 native command-line cases
retained in the Windows CI job.
```powershell
uv run --frozen --python 3.13 --no-sync pytest tests/test_mcp_bridge.py -q -n 0 --tb=short
uv run --frozen --python 3.13 --no-sync pytest tests/integration/test_mcp_bridge_e2e.py tests/integration/test_acp_mirasim_real_process.py -m integration -q -n 0 --tb=short
```
Seven regression cases cover paused input, resuming consumption, closing
a paused worker, a busy event loop, and teardown with pending TCP
writes: while the endpoint stays stalled, while it drains those writes,
and when a second cancel arrives after that drain finished. Aborting the
endpoint after a close that finished was wrong: the selector transport
has already run connection_lost and dropped its loop, and its
_force_close returns early only on _conn_lost, which a drained close
does not raise, so the bridge exited 1 at teardown on Linux and macOS.
The abort now depends on whether the endpoint's write buffer still holds
bytes, since a closing transport empties it before calling
connection_lost. A flag set once the close returned would miss the
second cancel, and that case fails with one. The stalled-endpoint
teardown case pauses the endpoint's reading before the frames are fed:
it used to wait for the socket to stop reading through its own flow
control, which took 1.87 s of the case's 2 s budget on Linux, so a busy
runner timed out before the teardown ran. It is now 0.17 s per case, and
20 consecutive runs under 32 busy loops on 16 cores all passed. The
original teardown and buffering cases fail without the fixes. At this
head, making the stdin worker read again without waiting for its
previous chunk to be delivered fails 3 cases, removing the close
deadline fails 2, and never aborting fails 2; aborting unconditionally
fails both drained cases. These mutations ran on a disposable copy of
the source tree, not on the committed files.
The unreachable-upstream integration test still uses its original
1.5-second deadline. Its Windows fixture bypasses the venv redirector
while preserving the venv, so an inherited stdout handle cannot mask
EOF.
Full-PR pre-commit, commitlint, commit-message, source-language, asset
and whitespace checks passed. The bridge type check passed and all 10
import contracts were kept:
```powershell
uv run --frozen --no-sync pre-commit run --from-ref origin/main --to-ref HEAD
npx --no-install commitlint --from origin/main --to HEAD --config commitlint.config.cjs
uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
uv run --frozen --no-sync python scripts/check_large_files.py origin/main...HEAD
uv run --frozen --no-sync python scripts/check_source_language.py origin/main...HEAD
uv run --frozen --no-sync ty check raven/mcp/bridge.py
uv run --frozen --no-sync lint-imports
git diff --check origin/main...HEAD
```
These are focused local results. Remote dispatch tests use the
repository's SSH stand-in and real node processes, not an external
machine. POSIX-dependent paths are covered on Linux; no full-suite
Windows pass, live LLM run or sandbox VM run is claimed. Existing
Windows path, shell and journal portability outside this MCP change
remains out of scope.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Windows dispatches can now use granted MCP servers. Each fallback
endpoint opens an ephemeral loopback listener with a bounded
authentication handshake and its own random token. Upstream definitions
and credentials remain on the host, and remote dispatches receive no
loopback token.
Input now pauses when a bridge cannot forward requests. During shutdown,
a connection that cannot flush within one second is aborted and its
remaining queued bytes can be discarded. This bounds cleanup when a peer
has stopped reading.
Unix sockets remain the preferred transport, and the Raven node wire
protocol is unchanged. No dependencies, configuration fields or
migrations are added. Reverting the change restores the previous Windows
MCP limitation.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#962
---------
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Rejected tool calls now report the argument path, the expected shape and
what arrived, so the model can correct a misplaced field or a JSON
string instead of repeating the same call. Generic string casting
preserves objects and arrays for validation, and the kernel's
model-facing `ask_user` cast preserves option objects it cannot render
under its accepted field policy.
The validation and compatibility boundaries are:
- Generic validation does not execute schema-supplied `pattern`
expressions. Tool-specific validation, including the DAG parser's
patterns, remains responsible for those checks.
- Suggestions and misplaced-key searches share one budget across an
entire validation, including nested objects: 16 suggestion attempts, 256
candidate comparisons and 256 queued search nodes. Candidates are
limited to 32 names of at most 64 characters per object. Diagnostic
exhaustion suppresses optional hints, while validation continues to
report invalid arguments.
- Displayed keys, paths, individual errors and expected shapes are
bounded at 64, 160, 512 and 300 characters respectively. The rendered
diagnostic body is capped at 3,500 characters. Actual parameter lookup
uses the original keys. The registry keeps the error prefix used by
failure classification.
- Objects with nonempty `patternProperties` leave additional-property
casting and validation to the tool until those rules can be checked
together safely. Explicit properties and required fields are still
checked. This is partial schema support, not an implementation of
`patternProperties`. Array bounds apply only when they are nonnegative
integers other than booleans; malformed bounds remain unchecked.
- `image_search` retains its single-query fallback when `queries` is
empty and `query` is valid. A nonempty batch still wins. The DAG tool
normalizes aliases declared by its parser, including required-field
aliases, and rejects simultaneous alias and canonical names instead of
overwriting either. Node `skills` and `mcps` remain playbook-owned
fields, accepted by the graph parser and rejected at the model-facing
registry boundary.
- Research round-trip questions use the shared public `option_text`
renderer. A choice such as `{"label": "EU only", "id": 1}` reaches the
broker as `EU only`, and a description is retained. The kernel's
model-facing entry continues to reject unknown option fields. These are
separate acceptance policies.
- A closed MCP schema still rejects unknown fields; an open schema
forwards them. This compatibility change is deliberate. A server's
willingness to ignore fields does not change its declared schema.
`const`, `uniqueItems`, valid array bounds and additional-property
constraints without `patternProperties` remain enforced. `pattern`,
`patternProperties`, `anyOf`, `oneOf` and `format` are not fully
implemented by the generic validator. Complete bounded pattern support
and the research renderer's pre-existing fallback for objects with no
label or description remain follow-up work. The research renderer can
still discard unknown fields; this PR does not claim every product cast
is lossless.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
After resolving the test-file conflict with main, on Linux and Python
3.12.13:
```bash
uv run --frozen --no-sync pytest -q -n 0 \
tests/test_subagent_dag_core.py tests/test_subagent_dag_guard.py \
tests/test_subagent_dag_runner.py tests/test_subagent_dag_adjudication.py \
tests/test_subagent_dag_control_tools.py tests/test_subagent_dag_verdict.py \
tests/test_tool_params_cast.py tests/test_tool_registry_execute.py \
tests/test_ask_user_tool.py tests/test_mcp_client.py tests/test_agents_research_tools.py \
tests/test_agents_research_flow_ask_user_surface.py \
tests/test_agents_research_flow_ask_user.py tests/test_agent_tools_web_providers.py \
tests/test_security_untrusted_context.py tests/test_tool_admission.py \
tests/test_tool_refusal_continuation.py tests/test_l3_open_world.py --tb=short \
--cov=raven.agent.tools.params --cov=raven.agent.tools.ask_user \
--cov=raven.agent.tools.registry --cov=raven.agent.tools.web \
--cov=raven.agent.subagent.dag_tool --cov=research_flow.tools.ask_user \
--cov-branch --cov-report=json:coverage.json --cov-report=term
uv run --frozen --no-sync python scripts/coverage_gate.py \
--coverage-json coverage.json diff --base-ref origin/main --head HEAD --threshold 90
```
- 1629 passed, with 17 existing asyncio-marker warnings. HTTP(S) and ALL
proxy variables were unset. Coverage filenames above replace the
absolute local report paths used in the run; the diff gate used the
pinned main revision.
- Diff coverage: 98.08% (306/312 executable changed lines), above the
90% gate. This is coverage of the PR's changed production lines, not a
full-suite measurement.
- Conflict resolution preserves every top-level declaration from main
and all five additional PR regression functions. AST comparison reports
no duplicate declarations. All nine commits replayed; the only
range-diff change is the insertion context of the appended DAG tests.
- Through the real registry and graph parser, a synthetic branching
graph with `nodeSummary`, `promptTemplate` and `dependsOn` retains
`routes`, `select` and `when`, both as a node list and as JSON text.
Alias/canonical collisions and playbook-only `skills`/`mcps` remain
rejected. The probe uses a synthetic home and starts no workers.
- `uv run --frozen --no-sync ruff check raven evolver agents
plugins-dist tests scripts docs-site` and the matching `ruff format
--check`: pass.
- `uv run --frozen --no-sync ty check raven evolver agents plugins-dist
scripts`, `uv run --frozen --no-sync lint-imports` and `uv run --frozen
--no-sync deptry raven`: pass. Import contracts: 10 kept, 0 broken.
- Pre-commit on all changed files, `UV_NO_SYNC=1 make check-large-files
check-source-language COMMIT_RANGE=origin/main...HEAD`, and `uv run
--frozen --no-sync python scripts/check_commit_messages.py
origin/main..HEAD`: pass.
The full repository suite and native Windows checks run in CI for the
new head. The earlier head's full-suite counts, recorded-session replays
and native Windows review are not reused as measurements of this rebase.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no new
documentation in this conflict-resolution round)
## Risk
Closed schemas, including MCP schemas, and kernel `ask_user` option
objects with unknown fields have a stricter acceptance boundary. The
documented aliases and image-search fallback are preserved at their own
tool boundaries. Unsupported pattern rules remain delegated to tools;
this validator is not a complete JSON Schema implementation.
The budgets limit optional diagnostic work and rendered text, not the
total time required to validate arbitrarily large input. A missing-key
hint can be omitted when its search budget is exhausted. Bounded
previews can still contain a fragment of submitted text; length limits
are not a secret-redaction guarantee.
Four nonblocking re-review items remain outside this conflict-only
update: declared node aliases are not yet normalized at the replan
entry; some documentation still describes playbook-owned node fields as
model-facing; malformed MCP `properties: null` remains unsupported; and
the empty-batch fallback does not yet cover JSON-text empty batches or
`ppt_image_search`.
No new dependency, persisted state or migration. Rollback is a revert.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The research, code, oncall and ppt agents keep prompt files in their
workspace that the model reads on every turn:
`agent_memory/profile/soul.md`, `agent_memory/profile/agent.md` and
`TOOLS.md`. They were written only when absent (`seed_once`), so after a
raven upgrade or a config change the model kept reading the text of the
first launch while the gates enforced the current release. A
Raven-Research install seeded before the reader layout still asked the
model for the `## Answer` / `## Findings` / `## Limitations` report
while its shape gate checked the reader layout.
These files are now generated output:
- `write_generated()` in `raven/config/product_render.py` rewrites a
product-owned file from the release and the rendered config on every
launch.
- An operator's own lines go in the sibling `*.local.md` file
(`agent_memory/profile/agent.local.md`, `soul.local.md`,
`TOOLS.local.md`) and are appended after the product text at the next
launch. They must be UTF-8: one in another encoding (an editor's legacy
code page, GBK for example) raises a decode error that names the
`*.local.md` and asks for UTF-8, rather than one naming the generated
file.
- A receipt beside each file (`.<name>.generated.sha256`) records
`<owner> <digest>` for the last text written. A file the caller's own
receipt lines do not name (edited in place, written by another product,
or left by an older release) is backed up to `<name>.bak-<time>-<pid>`
before it is replaced, and the log says which of those it is when the
receipt can tell. A backup is never readable by more accounts than the
original: on POSIX an owner-only copy; on Windows, where a new file
takes its folder's inherited ACL whatever mode it is created with, a
hard link to the file itself, so it keeps the file's security descriptor
and no bytes are written. A Windows volume that cannot hard-link refuses
the backup, and a failed backup leaves the file untouched. While the
target changes, the receipt names both texts, so a failure between the
two writes never leaves a file the next launch cannot recognise.
- `product_text=None` (raven-code's `CODE_CONDUCT=off`) removes only a
file this product wrote; an edited one, or another product's file and
receipt, is left alone.
- The launchers pass `adopt=True`, since their home is the product's own
ACP home, and refuse to start with the file named when a prompt cannot
be written. On a raven without `write_generated` they fall back to
seeding once and log that the file will not be refreshed.
- The ppt engine writes into whatever home its plugin is granted, which
can be a host's or another product's, so it passes `adopt=False`: it
replaces only a seat its own receipt, or the digest of a prompt it has
shipped, shows it wrote. A test fails when a ppt prompt changes without
its digest being added. It marks its identity written only once the
write lands and retries on the next turn otherwise. A seat that fails
does not stop the other seats; the host's template sync waits for the
retry, since it would fill the failed seat and a seat the engine did not
write is never replaced. A seat it leaves alone is logged at DEBUG, not
WARNING: in a host's home those are the host's own, every process, with
nothing to act on. The notice says how to hand a seat back (move the
lines into `*.local.md`, delete the file), which is what a seat edited
in Raven-PPT's own home before this release needs; the docs name that
exception.
- raven-code's earlier per-file receipts and legacy digests are still
honoured, so untouched copies are refreshed without a backup.
- `atomic_replace()` takes a `newline` argument so generated files stay
LF on every platform. It also removes its temp file when the replace
fails, and removes a temp file already present before it writes,
clearing the read-only attribute first: Windows refuses to replace a
read-only target once the temp file has taken its mode, and the
read-only temp file left behind used to fail every later launch even
after the target was made writable again.
- The temp file `atomic_replace()` writes is created no more open than
the target from its first byte. On Windows a new file takes its folder's
inherited ACL and `os.replace` (`MoveFileExW`) moves that descriptor
onto the target, so a prompt kept private in a folder other accounts may
read came back readable by them, `*.local.md` lines included. When the
target exists, the temp file is now made by `CreateFileW` with the
target's DACL as `GetFileSecurityW` reads it, and the save is refused
when that DACL cannot be read. On POSIX it is created with the target's
mode rather than the umask default, closing the span in which the new
text sat in a wider file until the chmod. This holds for every caller
that passes no explicit mode, `config.json` included. The Win32 bindings
behind it are declared once per process, behind a cache: a structure
defined per call left a new ctypes pointer type, about 6 KB, alive for
every save.
Docs: `agents/README.md` (the seed-once contract becomes "Regenerated
prompts", with rollback steps), `docs-site` agent integrations (en and
zh), `CONTEXT-MAP.md`, and `CHANGELOG.md` (an unreleased entry that
promised the old behaviour, plus a Fixed entry).
Tests whose meaning changed: seven existing tests asserted that an
edited prompt is never overwritten; they now assert it is backed up and
regenerated. The raven-code launcher test fixture now pins
`CODE_CONDUCT` and `CODE_CONDUCT_DISCIPLINE` to `on`: a deleted switch
fell back to the developer's `.env`, and two conduct tests on main
already failed with `CODE_CONDUCT_DISCIPLINE=off` for that reason.
Checked and deliberately not changed (documented in `agents/README.md`):
- The processes of one product (one per model binding) share these
files, so a launch can change what an older process still running reads
on its next turn. Closing that needs a per-process snapshot or
in-process injection of the prompt, which is a separate change.
- Backups are never deleted automatically.
- Host workspace templates (`USER.md`, `HEARTBEAT.md` and the rest) are
the user's files and stay write-if-missing.
- A file removed from a release is not removed from an installed
`~/.raven/agents` copy. Nothing loads such a leftover today: modes are
read by label, tools are imported by name, and no release has removed a
skill directory.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run at the head of this branch, rebased on the current main:
- `uv run pytest -q`: 32739 passed, 17 failed, 147 skipped, 2 xfailed.
The same 17 test IDs fail on the current main in a clean worktree with
the same interpreter and the same fetched tokenizer dictionary (proxy
redaction, tokenizer data, network-safety resolution, install script,
document converters, node runtime, trajectory time zone); none is
introduced here.
- `uv run pytest tests/test_agents_code_launcher.py -q` with
`CODE_CONDUCT` and `CODE_CONDUCT_DISCIPLINE` each set to `off` in the
environment, alone and together: 79 passed in all four runs.
- `make lint-python lint-imports lint-types lint-deps`: all pass, 10
import contracts kept, no dependency issues.
- `scripts/check_commit_messages.py`, `scripts/check_source_language.py`
and `scripts/check_large_files.py` over `origin/main..HEAD`, and `git
diff --check`: pass.
- Each fix was reverted on its own and its test went red: the receipt
written after the target, a failed target write, the backup mode, the
ppt `adopt=False` guard, receipts without an owner, an undeletable
earlier receipt, the `*.local.md` read-back from the assembled system
prompt, the temp file a failed replace leaves behind, and the temp
file's mode while it holds the new text.
- Windows review findings:
`test_a_windows_backup_is_the_edited_file_itself_so_its_acl_comes_with_it`
and `test_a_windows_backup_the_volume_cannot_link_is_refused_not_copied`
force the link path on Linux;
`test_a_failed_replace_takes_its_tmp_with_it` and
`test_a_read_only_tmp_a_dead_writer_left_does_not_block_the_replace`
cover the temp file on every platform;
`test_the_tmp_is_never_more_open_than_the_target_while_it_holds_the_new_bytes`
pins the POSIX mode from creation;
`test_a_read_only_prompt_regenerates_once_it_is_writable_again`
(read-only retry) and
`test_a_private_windows_prompt_keeps_its_own_dacl_when_regenerated_and_backed_up`
(a private prompt in a folder every local user may read keeps its own
DACL through regeneration and backup, read back with `icacls /save`) run
on Windows only.
- The `Windows ACP stdio` CI job gains a step that runs
`tests/test_config_product_render.py` and the two temp-file tests
natively. On the Windows runner: 158 passed, 2 skipped (the two
POSIX-mode tests), the DACL, read-only retry and hard-link backup tests
among the passes.
- Diff coverage over `raven/` with the related suites: 94.12%, above the
90% gate.
- Second-round review findings, each test red without its fix:
`test_an_addendum_that_is_not_utf8_is_named_and_nothing_is_written`,
`test_a_local_file_that_is_not_utf8_is_named_when_the_launch_stops` and
`test_an_addendum_that_is_not_utf8_names_itself_and_holds_back_no_other_seat`
(the decode error names the addendum; the ppt engine writes the other
seats and holds the sync);
`test_a_hosts_own_seats_are_left_alone_without_a_warning_in_every_process`
and `test_a_seat_left_alone_says_how_to_hand_it_back` (DEBUG level, and
the notice's instructions);
`test_the_windows_bindings_are_declared_once_not_per_save` (Win32
stand-ins on Linux, two saves load each DLL once).
Windows is covered by the CI step above, not by a local run. The CRLF
fold of an older copy is reasoned, not run. `npx commitlint` is not
installed on the machine this was run on; the Python commit check above
was run instead.
- [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 the first launch after upgrading, each agent rewrites
its prompt files. A file edited in place, or left by an older release
without a receipt, is copied to `<name>.bak-*` and the launcher log
names the copy; an in-place edit stops taking effect until its lines are
moved into `*.local.md`. A `*.local.md` that is not UTF-8 stops the
launch with the file named. In Raven-PPT's own home a seat edited before
this release keeps the edit, and its `*.local.md` is not applied, until
the seat is deleted. A Raven-Research install seeded before the reader
layout switches to it at that launch.
- Security: a backup is never readable by more accounts than the file it
keeps (an owner-only copy on POSIX, a hard link keeping the file's ACL
on Windows), and a replaced file keeps its own mode, and on Windows its
DACL, from the temp file's first byte; receipts hold product names and
digests only; `*.local.md` is operator-owned and carries the same trust
as editing `agent.md` did before.
- Compatibility: a launcher running on a raven without `write_generated`
seeds once and logs it; the ppt engine on such a raven keeps
write-if-missing. On a Windows volume that cannot hard-link (FAT32,
exFAT, some network shares), an edited prompt file stops the launch with
the file named, until its lines move to `*.local.md` and the file is
deleted. On Windows, a save through `atomic_replace()` whose target's
DACL cannot be read is refused rather than made with the folder's ACL.
- Rollback: revert this change, then stop the product's processes,
delete each generated file whose `.<name>.generated.sha256` receipt
still names its current text, and relaunch so the older code seeds its
own. `*.local.md` files, backups and edited files are left as they are.
- [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
Pin the suite's per-test home in the pytest process and in a child
Python process, and run these regressions explicitly in the Windows ACP
job. This prevents a future fixture change from sending test
configuration or SSH aliases into the runner's real profile.
Main already routes the home fixture through `tests._home.point_home`,
which sets both `HOME` and `USERPROFILE`. The rebase keeps that
implementation and every other main fixture unchanged. This PR now adds
only two regression tests and their Windows CI step; it no longer
introduces a separate Windows-only environment assignment.
The tests check `Path.home()`, tilde expansion for `.ssh/config`,
`raven_home()` and the inherited child-process home. Main's existing
guard continues to check both path flavours and environment variables.
All existing Windows ACP steps remain present.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
On the rebased tree, Linux and Python 3.12.13:
```bash
uv run --frozen --no-sync pytest \
tests/test_conftest_home.py tests/test_conftest_no_real_home.py \
tests/test_conftest_idle_ceiling.py tests/test_conftest_utf8_guard.py \
tests/test_ops_connection_add.py tests/test_cli_ops_connection_commands.py \
tests/test_subagent_host_env.py tests/test_sandbox_unit.py -q -n 0 --tb=short
```
243 passed. HTTP(S) and ALL proxy variables were unset for the run.
- The resolved `tests/conftest.py` is byte-identical to main, including
the Codex network and EverOS isolation fixtures.
- The new test file is byte-identical to the original PR. Removing this
PR's one Windows step from the parsed workflow reproduces main's
complete job definitions.
- `uv run --frozen --no-sync ruff check tests/test_conftest_home.py` and
`uv run --frozen --no-sync ruff format --check
tests/test_conftest_home.py`: pass.
- `uv run --frozen --no-sync pre-commit run --files
.github/workflows/ci.yml tests/test_conftest_home.py`: pass.
- `UV_NO_SYNC=1 make check-large-files check-source-language
COMMIT_RANGE=origin/main...HEAD` and `uv run --no-sync python
scripts/check_commit_messages.py origin/main..HEAD`: pass.
Native Windows validation of this rebased combination is provided by the
Windows ACP CI job. The original branch's native Windows measurements
are historical and are not reused as verification of this rebase.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (test-only
change)
## Risk
No product code or test-home fixture changes relative to current main.
The additional Windows step runs the two home regressions before the
existing ACP checks. `APPDATA`, `LOCALAPPDATA` and agents discovered on
PATH retain main's existing behavior.
Rollback removes the added tests and CI step while preserving main's
home isolation.
- [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
- A node the cascade skipped, or a stop cancelled, on the pass that
meets a replan got no `dag_node_updated` frame and no registry row until
the run finalized: that pass breaks at the replan before the sweep could
take it, so a live panel kept drawing the node as running.
- The replan exit now publishes `skipped` and `cancelled` alongside
`not_executed`, through `_publish_terminal` -- the helper #1001
introduced for exactly this stamping. One definition covers every pass,
and the end stamp is hard-assigned there: the helper's docstring
sentence and the exit's comment now say so instead of naming the replan
pass as announced by nobody.
- The first revision of this branch put a second copy of that publish
inside `_apply_replan`, stamped with `setdefault`, which kept an earlier
attempt's end on a node cancelled out of a retry and wrote a duration
that ran backwards (a start after its end). That copy is withdrawn in
favor of the shared helper; the regression test drives the
retry-cancelled-on-the-replan-pass case under a strictly increasing
counter clock, so the ordering it asserts cannot race the real clock's
millisecond resolution.
- #1001's pin test asserted the silence this branch removes; it now
expects the cascade skip's frame, under a name that says the exit
publishes it.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally: `uv run pytest
tests/test_subagent_dag_runner.py
tests/test_subagent_dag_adjudication.py tests/test_subagent_dag_core.py
tests/test_subagent_dag_control_tools.py tests/test_rpc_dag.py -q` ->
916 passed, after rebasing onto #1001
- [x] The three new tests fail on the merge base (no frames for the
settled nodes, and 1020 > 1010 under the counter clock) and pass on this
head
- [x] Relevant lint / type checks pass locally: `ruff check` and `ruff
format --check` on both files; `make lint-types` -> clean
- [x] User-facing docs or screenshots are updated when needed: no
user-facing surface changes; the frames carry statuses consumers already
read at finalization
## Risk
- [x] Security impact considered: announcement only; no value or path
crosses that did not before
- [x] Backward compatibility considered: a replan pass now emits one
extra `dag_node_updated` frame per cascade-skipped or stop-cancelled
node, which is the fix itself; the manifest's end stamps on that pass
are re-assigned rather than kept, so no duration runs backwards
- [x] Rollback path is clear: plain revert restores the silent exit
## Related Issues
N/A (adopts `_publish_terminal` from #1001)
## Summary
A sub-agent DAG node can now decide which of its downstream branches
run. Before this, a background run could not turn on a result: every
node ran, and choosing a path meant the host winding the run down and
starting another.
How it works:
- A node that declares `routes` (route name to condition) is a decision
node; `select` is `"one"` (the default) or `"many"`. Raven's per-node
judge, the existing verdict call, picks the route or routes the node's
answer satisfies. The node's own text never selects a route. A route
that cannot be determined fails the node, with no fallback route.
- A downstream node carries `when`, a guard over `<node>.<route>` and
`<node>.done` atoms joined with `not`, `and`, `or` and parentheses,
evaluated with three-valued logic: a route of a decision node that was
never executed is unknown. Every decision node in a node's `depends_on`
must appear in its `when`; such graphs are refused at submission
otherwise, along with guards that can never hold and a route named
`done` in any letter case. Validation keeps negation parity and the
surrounding boolean expression: a double-negated `done` and a
disjunction with a satisfiable arm are accepted, without expanding
disjunctions into combinations.
- A node that does not run is `not_executed`, with a reason:
`when_false`, `when_unknown` or `upstream_not_executed`. A node whose
dependencies all went unexecuted is not executed either; a failed or
skipped dependency still skips its dependents first.
- A merge node reads a missing upstream as a fixed sentence, `<This task
is not executed and the output is missing, please go on without this
output.>`, written outside every untrusted-content fence, plus a note
listing the inputs that may be missing. A file reference to the files of
a node that may not execute is refused at submission however its path is
spelled: `@nodes/`, an absolute path into the node root, or a workdir
path that lands there, symlinks followed. Windows case, separator and
drive-relative aliases are recognized, and the advice keeps the declared
node ID.
- Node judgement is always on: the `subagentDag.verdictEnabled` switch
is retired. Config migration 14 removes it with a notice, and drops it
again on every later load should an older build sharing the config write
it back. `raven playbook run` now judges its nodes too, on the same
`subagentDag` settings and a pinned `verdictModel`'s own provider; with
nobody there to answer, a node judged not to have accomplished its task
fails on the judge's reason. A host with no judge at all refuses graphs
that declare routes.
Where it shows:
- Run events, the manifest, `dag.get`, `tasks.list` and
`dag.run_completed` carry `reason`, `selected_routes` and
`route_evidence` per node, and `routes`, `select` and `when` from the
graph. The instance registry's DAG-node rows (and `InstanceRow`) carry
the outcome too, so a client that reloads before the run finalizes shows
what a branch decided. `TaskCounts.not_executed` is a new counter.
- TUI: a not-executed node shows a hollow marker and its reason in
words; a decision node shows its selection on the node's second line,
and the guard and route evidence in the detail and in `/dag <node>`. The
Agents Overlay and the live agents strip leave not-executed nodes out,
as the backend's agent lists do.
- Web: the desk's tasks tab names not-executed steps and shows the same
fields.
- Playbooks pass the three fields through, namespace guard atoms with
the run prefix, and keep them through compilation.
- The `run_subagent_dag` schema, the DAG orchestration skill and the
docs site (English and Chinese) describe routes, guards and the merge
rule; CHANGELOG has the entries.
A graph with no `routes` and no `when` behaves exactly as before: the
same judge requests, events, records, summary and finish text.
`route_evidence` is a quote the judge picks from the sub-agent's output;
it is cut at 500 characters, keeps a lone surrogate from a malformed
escape as the escape's own text, and never enters model-facing text
(finish text, `dag_status`, exception reports). When a judge answer does
not report a usable route, the judge is asked again at most twice, each
time with one correction. The shared instance registry drops its cache
when a write fails on the data rather than the disk, so a row the file
cannot hold fails its own write and no other.
Two Windows CI steps run the alias and finish-text regressions; the
latter exposes the installed Git `cat` executable required by the
existing fixture.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Linux, Python 3.12.13, on this revision rebased onto the current main
(`$CHECKS` is a temporary evidence directory):
```sh
uv run --frozen --no-sync pytest -q -n 4
# 23 failed, 33229 passed, 162 skipped, 1 xfailed, 3 errors
uv run --frozen --no-sync pytest $(git diff --name-only origin/main...HEAD -- tests/) -q -n 4 --idle-ceiling-strict --cov=raven --cov-branch --cov-report=json:$CHECKS/coverage.json
# the 20 test files this branch changes: 2622 passed, 1 skipped (a POSIX permission case that does not apply to root)
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json "$CHECKS/coverage.json" diff --base-ref origin/main --head HEAD --threshold 90
# Diff coverage: 99.48% (764/768 executable changed lines), passed the 90.00% threshold
```
The full run's 23 failures and 3 errors are 25 tests. 24 of them fail
the same way on the current main in this environment: the venv lacks
`nltk` and `datrie` (16), a proxy is set in the environment (5), this
box has its own `npm` in `/usr/bin` (1 install-script case), LibreOffice
writes no `.xls` here (1), and the run is root (1). The 25th,
`test_a_cli_run_left_on_the_machine_when_this_computer_stops_is_picked_up_by_the_next_start`,
failed with its teardown in the full run and in one of two runs of its
file, and passed in five runs on its own: it reads the remote-run record
the moment its pid file appears, a race in code this branch does not
change (#840 makes that test wait for both). The four uncovered changed
lines are the gateway's `_verdict_provider` body, whose helper is tested
on its own; a guard atom over a node that did not complete, which the
runner never evaluates because it reads a guard only once every
dependency completed or was not executed; and the cut of an over-long
terminal output.
Ruff check and format, `ty check` over the changed modules, the import
contracts, `deptry raven`, commitlint, and
`scripts/check_commit_messages.py`, `check_large_files.py` and
`check_source_language.py` over this branch's commits pass. ui-web:
`vitest run src/features/tasks/BoardCard.test.tsx scripts/gates` passes
50 files and 244 tests, and `tsc --noEmit` is clean. In Chromium a
not-executed title whose first word is wider than the room beside its
status now breaks that word instead of starting under a blank line, and
every other tasks-board card renders pixel-identical, English and
Chinese, light and dark. Firefox still starts such a title under a blank
line and cuts it without an ellipsis. CI's `TUI checks` covers ui-tui.
Mutation checks: removing any one of these makes its own test fail: the
every-load strip of the retired switch, the quote's escape before the
cut, the registry's cache drop, the node-root check in the tool, the
runner and the replan path, the physical path through a symlink, the
CLI's judge, its settings and its no-answer failure, and the pinned
judge provider. A model reading only the DAG skill's catch-all paragraph
answers that without a catch-all route the judge may pick the nearest
route or fail the node; an earlier wording led it to answer that the
graph always stops.
A live run on `openrouter/z-ai/glm-5.3-flash`, two graphs with synthetic
messages, selected the expected route at each decision node, left the
unselected branch `not_executed` with `when_false`, and put the fixed
sentence outside the fences. Earlier revisions of this change passed the
native Windows selections (aliases, finish text, guards; Windows build
26300, Python 3.13.12). The final revision has not been rerun on native
Windows or macOS.
- [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
Security: sub-agent text stays fenced or out of model-facing text on
every new path. The routes block in the judge request sits after the
last untrusted fence and is labelled as the graph author's; the
missing-output sentence is written outside every fence; `route_evidence`
is bounded and reaches records, events, the registry and the UIs only.
In the TUI, route evidence is drawn through the same path as a node's
error text; neither strips terminal control sequences, which this PR
leaves as it is.
Behaviour changes: a config that set `subagentDag.verdictEnabled: false`
now gets judged nodes; migration 14 removes the key and says so once.
`raven playbook run` judges every node, one more model call per node,
and a node judged not to have accomplished its task fails there instead
of completing. New wire fields are optional except
`TaskCounts.not_executed`, which is always present (0 when nothing
branched). `InstanceRow` gains three optional fields, and a decision
node's registry row now also stores its selection and up to 500
characters of route evidence.
Conditional-artifact validation matches node IDs using the session
namespace's case-insensitive identity on every host, including macOS.
This conservatively rejects case-only spellings even on case-sensitive
filesystems. Separator and drive normalization remain native, and
unconditional file resolution keeps its existing behaviour.
Rollback: revert the squash commit. A config already stamped 14 loads
unchanged on the previous build, since the stamp only gates migrations;
a user who had set `verdictEnabled: false` can set it again there, and a
later build drops it again on load.
## Related Issues
Related, found while building this and not changed here: #998, #999,
#1000. Follow-ups from its review, not changed here: #1008.
## 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
On native Windows, connecting an agent that runs as a process chain
failed every time with `[WinError 32] The process cannot access the file
because it is being used by another process:
'...\raven_subagent_ping_xxxx'`. The Claude Code preset is one such
chain: `npx.cmd`, `cmd.exe`, the node adapter, then `claude.exe`.
`ping_agent` handed the agent a fresh temporary directory to launch in
and removed it when its `with` block ended, which was before the
`finally` that closes the ping's pool and so ends the agent's process
tree. Windows refuses to remove a directory that a live process has as
its working directory, even an empty one, and the broad `except
Exception` turned that removal error into the ping's verdict: an agent
that had answered was reported as not answering a test message. A ping
that timed out was misreported the same way, and each press left its
directory in the temp folder.
`verify_agent`, the handshake behind Test and behind the capability
record a Connect writes once its ping passes, removed its session
directory in the same order. The Claude Agent SDK starts `claude.exe` in
the session's directory, so that check came back `unknown` with `verify
failed: [WinError 32] ...`.
Ending the tree was already right: the Job Object from #951 ends every
process in it, including descendants started later. What was wrong was
when the directory was removed, and what a failed removal was taken to
mean.
- `raven/utils/scratch.py` adds `ScratchDir`, a temporary directory that
is removed only when its caller says the agent has ended. The removal is
tried up to 5 times, 0.2 s apart, while a tree that was just ended
finishes exiting. A directory that still cannot be removed is logged
with its path and left in the temp folder, never raised. It removes
through `TemporaryDirectory.cleanup`, so read-only entries are still
cleared on Windows as before.
- `ping_agent` removes its directory after `pool.close_all()`, and
`verify_agent` after `client.close()`. The CLI test (`run_test`) and the
Kimi Code print-mode ask use `ScratchDir` as an async context manager:
their process has ended inside the block, and a refused removal no
longer replaces the CLI's reply or raises out of the ask.
- The `Windows ACP stdio` CI job runs a new real-process test of both
checks against an agent of the reported shape.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Native Windows 11 (build 26300, Python 3.12) unless marked Linux.
Reproduction with a stand-in agent of the reported shape: a `.cmd`
wrapper starting a Python ACP agent that, on `session/new`, starts a
worker in the session's directory and waits for it before answering.
- `main`: the ping returns `ok=False` with `[WinError 32] ...
raven_subagent_ping_...`; the handshake returns `unknown` with `verify
failed: [WinError 32] ... raven_acp_verify_...`; both directories stay
in `%TEMP%`.
- This branch: the ping returns `ok=True` ("it ran and replied"), the
handshake `ready`, and nothing stays in `%TEMP%`. Over 20 rounds of both
checks, all 40 directories were removed on the first try after the
close.
```text
uv run --frozen --no-sync pytest tests/integration/test_subagent_connect_windows_real_process.py -m integration -q -n 0
```
1 passed. On `main` it fails with `[WinError 32] ...
raven_subagent_ping_...`, the error text in the issue.
New unit tests: 5 in `tests/test_utils_scratch.py`, 3 in
`tests/test_subagent_acp.py`, 4 in `tests/test_subagent_probe.py` (the
CLI one is POSIX-only, like the neighbours whose shell stand-in it
shares) and 1 in `tests/test_subagent_kimi_code.py`. The ping and
handshake ordering tests run the real pool, client and stub agent, with
Windows' refusal stood in on any host by `tests/_windows_dirs.py`: a
removal is refused while an agent the test launched is not yet closed.
With the three changed modules put back to `main`, the six call-site
tests fail, each with the symptom it names (the CLI one on Linux). Each
new construct was then removed on its own, and a test goes red for every
one: removal before the pool close, removal before the client close,
either `None` guard, raising after the last try, a single try, no pause
between tries, and `shutil.rmtree` in place of
`TemporaryDirectory.cleanup`. That last one only shows on Windows, where
a read-only file blocks the removal.
Slices of the suite that reach the changed modules, this branch against
`main` at a71b488e:
- Linux, in Docker (`python3.12-bookworm-slim`,
`--idle-ceiling-strict`), 20 test files plus the new one: 9 failed, 1718
passed, 88 errors on this branch; 8 failed, 1706 passed, 88 errors on
`main`. The errors and eight of the failures are the same ids on both,
in remote-machine and file-permission tests: the container has no `ps`
and runs as root. The ninth,
`test_a_ping_answers_from_the_machine_and_leaves_one_directory`, timed
out once starting the machine's daemon (`did not answer within 20s`)
while the host was under load; run alone it passed 3 of 3 times on both
sides.
- Windows, `tests/test_subagent_acp.py tests/test_subagent_probe.py
tests/test_subagent_kimi_code.py tests/test_subagent_host_env.py
tests/test_acp_windows.py tests/test_rpc_subagents.py
tests/test_subagent_github_copilot.py`: 57 failed, 635 passed, 4 skipped
on this branch; 61 failed, 619 passed, 3 skipped on `main`. No test
fails only on this branch. Four tests that fail on `main` under Windows
pass with this change,
`test_the_roster_and_the_connect_button_read_one_answer` among them.
For anyone reproducing on Windows: the suite isolates the home by
setting `HOME`, which `Path.home()` ignores there in favour of
`USERPROFILE`, so a run reads and writes the real `%USERPROFILE%\.raven`
and tests can see each other's records. The Windows numbers above were
taken with `USERPROFILE` pointed at an empty folder. That gap predates
this change and is not addressed here.
```text
uv run --frozen --no-sync ruff check <the 10 changed Python files>
uv run --frozen --no-sync ruff format --check <the 10 changed Python files>
uv run --frozen --no-sync ty check raven/utils/scratch.py raven/agent/subagent/probe.py raven/agent/subagent/kimi_code.py raven/acp_client/capabilities.py
uv run --frozen --no-sync lint-imports
```
All passed, 10 import contracts kept.
Not measured: the real `@agentclientprotocol/claude-agent-acp` adapter.
The stand-in above takes its place.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The tests box stays unchecked because the slices above carry failures
that `main` carries too. No user-facing text or docs change.
## Risk
- POSIX behaviour is unchanged apart from order: the directory is
removed on the first try, as before, now after the agent has ended
rather than before.
- On Windows a refused removal adds at most about 0.8 s to a check, and
the directory is then left in the temp folder with a warning that names
it. Before this change every such check left its directory there and
failed.
- A check whose agent leaves a process running outside its job, or a CLI
that leaves a background worker, now reports the agent's answer where it
used to report the removal error.
- Rollback: revert the commit. No configuration, schema or stored state
changes.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#969
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
An Ark base (host `*.volces.com`) speaks its own dialect on the Images
generations route: `size` is a "1K"/"2K" resolution tier or an explicit
WxH pair bounded by the selected model's pixel window, and the answer
carries the picture behind `data[].url` rather than `b64_json`. Before
this, every call came back with no bytes and answered "no image
returned".
Nine commits, in order:
1. Take the dialect at all: send the tier where the model family takes
one, and take a `data` entry's picture wherever it is -- inline
`b64_json`, data-URI, or behind its URL, fetched through the guarded
fetch like any other provider URL.
2. Keep the asked-for ratio: an identified model gets an explicit WxH
pair fitted to its own pixel window at the 2K budget, instead of a bare
"2K" tier.
3. Fit the pair to the window exactly: a Seedream 3.0-t2i caps each side
at 2048, so 16:9 there is 2048x1152, not 2560x1440.
4. A refused or unreachable generated-picture URL now answers its own
error ("generated, but the picture URL was refused or could not be
fetched", with the url and detail) instead of "no image returned", so an
orchestrating model does not read a billed generation as "no image" and
pay for the picture twice. Scoped to volces bases at first; items 8 and
9 widen it.
5. An Ark inference endpoint id (`ep-...`) keeps the requested aspect
ratio (an endpoint id spells no family keyword). When the model family
is unknown and the sized call answers HTTP 400, the request is retried
once with no size so the endpoint's default frame stands -- a rejected
request is not a billed generation. Identified families are not retried:
their windows are documented, and a 400 there is a real error.
6. VolcEngine joins the image role. Its own address is Ark's
(`https://ark.cn-beijing.volces.com/api/v3`), so the registry now marks
it `image_api`: the roles card offers it for the image role, the
settings write accepts it, and `raven_config` lists it among the choices
for `tools.media.image.provider`. Before, this dialect was reachable
from settings only through a Custom provider pointed at the Ark address.
7. A call with reference images on an Ark base is refused with "image
editing is not supported on Ark" before anything is sent. It used to
post the multipart edit form to Ark, which has no `/images/edits` route,
and come back as an HTTP error.
8. Item 4's error now answers on every Images API base, not only volces
ones: a gateway that answers in URL form has billed the picture too, and
its refused or unreachable picture URL used to read as "no image
returned" or as a bare transport error.
9. A picture URL whose storage answers the download with an error status
(an expired signature's 403, a 404, a 5xx) gets item 4's error too, with
the status and the start of the response body in its detail. It used to
fall through to the generic HTTP error and read as the generation
request's own `HTTP 403`, whose hint tells the model to retry: the
double payment item 4 exists to prevent.
Deliberately left for a follow-up PR: image editing on an Ark base. Ark
has no `/images/edits` route; image-to-image goes through
`/images/generations` with an `image` field. Wiring that dialect is out
of scope here; until then such a call gets the refusal in item 7.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- `uv run pytest tests/test_media_gen_tool.py` -- 141 passed (127
pre-existing, untouched, + 14 new: 2 on the refused-url path, 5 on the
endpoint-id path, 1 for a generation on `provider: volcengine`, 1 for
the edit refusal, 2 for a gateway's unfetchable picture URL, 3 for a
download answered with an error status).
- `uv run pytest tests/test_rpc_model.py tests/test_rpc_console.py
tests/test_raven_config_tool.py` -- 561 passed: the roles card rows (the
expected list gains `volcengine`), the settings write and `raven_config`
each admit VolcEngine.
- `uv run pytest tests/test_ppt_engine_generate_image_tool.py` -- 13
passed (the deck engine consumes this tool; 154 together).
- `make lint-python` -- clean.
- All offline, httpx MockTransport, no live network. The size arithmetic
is hand-enumerated for every public ratio against every window. The new
refusal test pins the SSRF guard on the download path: replacing
`guarded_fetch` with a bare `client.get` fails it.
- The new tests were watched failing first: the three settings tests
with VolcEngine unmarked, the edit-refusal test without the refusal
(dropping either half of its condition fails 17 and 13 other tests), the
two gateway cases with item 4's error still volces-only, and the three
error-status cases while the download still went through
`raise_for_status()` (they answered `HTTP 403`, `HTTP 404` and `HTTP
500`). The exception is the `provider: volcengine` generation test,
which passed before the flag as well, since the borrowing was already
wired; it fails when VolcEngine's default address leaves Ark or when the
URL download is dropped.
- `uv run --all-extras pytest` on `main` at `a2d391ea4` plus this
branch: 32664 passed, 176 skipped, 3 failed, none introduced: the same
three fail at that base on this machine (a LibreOffice conversion, the
node-directory resolution, a read-permission case that root bypasses).
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
On non-Ark bases only a failure reads differently: a picture URL the
tool cannot fetch answers item 4's error. The ratio pass-through, the
400 retry and the edit refusal are volces-only. VolcEngine now appears
among the image role's providers wherever it is connected. The edit
refusal rests on Ark's documented routes, not on a live call. The video
tool's download has the same shape as item 9 (a completed job whose
content URL answers 403 reads as the request's own `HTTP 403`); that
path predates this PR and is left for a separate change. Rollback is
reverting the squash commit.
## Related Issues
N/A
---------
Co-authored-by: helalove0812-source <helalove0812-source@users.noreply.github.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
## Summary
Fixes#986
The Codex model list (`https://chatgpt.com/backend-api/codex/models`)
was requested with `client_version=0.0.0`. The backend filters the
catalogue by each model's own minimum client version, so every model
gated above `0.0.0` was dropped before Raven saw it: `gpt-6.1-sol`,
`gpt-6-sol` and `gpt-6-luna` were missing from both consumers of
`account_models()`:
- **Add model**: `model.fetch_models` -> `test_provider` ->
`_probe_codex_catalog` (`raven/config/update_providers.py`)
- **Chat model picker**: `model.options` -> `_runtime_models`
(`raven/rpc/methods/model.py`)
The first commit raised the value to the release `0.163.0`. The
follow-up commit replaces that with the split below: the **catalogue**
asks as a discovery sentinel so it sees the whole roster, and
**generation** names the newest published Codex CLI release, resolved at
runtime.
### Evidence
From #986 (live account, read-only GET, 2026-10-16):
| `client_version` | visible models |
|---|---|
| `0.0.0` | 4: `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`,
`gpt-5.6-luna` |
| `0.163.0` | all 7 (adds `gpt-6.1-sol`, `gpt-6-sol`, `gpt-6-luna`) |
| `99.0.0` | the same 7 |
| omitted | HTTP 400 |
Bisected: `gpt-6-sol` / `gpt-6-luna` appear from `0.155.0`,
`gpt-6.1-sol` from `0.159.0`.
Public reports:
- `99.0.0` returned HTTP 200 for two distinct Codex OAuth accounts on
2026-10-08: https://github.com/NousResearch/hermes-agent/issues/135024
(that report shows the `gpt-6-astra` entry; the full 7-model result at
`99.0.0` is #986's own measurement above).
- opencodex discovers the roster with
`CODEX_ROSTER_DISCOVERY_CLIENT_VERSION = "99.0.0"` ("asks as a client
newer than any release so it sees the whole roster"):
`src/codex/model-entitlements.ts:807` in
https://app.unpkg.com/@bitkyc08/opencodex@2.75.0/files/src/codex/model-entitlements.ts
- `0.0.0` returns a frozen legacy list, and any version at or above the
newest gate returns the full catalogue:
https://github.com/NousResearch/hermes-agent/issues/119412
- `gpt-6.1-sol` declares `minimal_client_version: 0.153.0` but is served
only from `0.159.0` (so the declared value cannot be used as the version
to send): https://github.com/farion1231/cc-switch/issues/7797
## Changes
### Catalogue: discovery sentinel (`raven/providers/codex_catalog.py`)
`CLIENT_VERSION = "0.163.0"` -> `DISCOVERY_CLIENT_VERSION = "99.0.0"`.
Any real release, including the newest, hides a model gated above it
until the next release ships. The sentinel lists the account's whole
roster. The comment keeps the #986 gate history (`0.155.0` / `0.159.0`),
cites the public measurements, and records the risk: if the backend ever
starts refusing versions newer than any release, this has to go back to
a real one.
### Generation: newest published release
(`raven/providers/codex_client_version.py`, new)
`resolve()` returns the release to send:
1. in-process cache, 15 minutes (monotonic, the same style as
`codex_catalog`);
2. npm `https://registry.npmjs.org/-/package/@openai/codex/dist-tags`,
the `latest` tag only (currently `0.163.0`; the `alpha` tag, currently
`0.164.0-alpha.3`, is never read);
3. the last good value, persisted as `codex-client-version.json` under
`get_cache_dir()` (atomic replace, the same convention as
`served_models.py`), checked again on read;
4. `FALLBACK_VERSION = "0.163.0"`: a real release, not below the known
generation-side gate `0.159.0`, to be bumped with Codex CLI releases.
Every candidate must be a plain `X.Y.Z` (so no prerelease, no empty
value, no `v` prefix) and no older than `FALLBACK_VERSION`. So `0.0.0`
cannot be returned, and neither can a rolled-back tag older than the
bundled release. Nothing raises to the caller.
### Generation request carries the version
(`raven/providers/openai_codex_provider.py`)
`_build_headers` adds `version: <resolved release>`, and `chat()`
resolves it via `asyncio.to_thread` (an npm round trip at most once per
cache window). `originator: raven` and `User-Agent` are unchanged.
The transport was confirmed from the official source before wiring it
in. At tag `rust-v0.163.0`:
- the built-in OpenAI provider sets `http_headers: {"version":
env!("CARGO_PKG_VERSION")}`: [`codex-rs/model-provider-info/src/lib.rs`
L526-L543](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/model-provider-info/src/lib.rs#L526-L543);
the workspace version at that tag is `0.163.0` ([`codex-rs/Cargo.toml`
L161-L162](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/Cargo.toml#L161-L162));
- `to_api_provider` points ChatGPT-login auth at
`https://chatgpt.com/backend-api/codex` and copies those headers into
the API provider:
[L427-L475](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/model-provider-info/src/lib.rs#L427-L475);
- every request starts from the provider's headers
([`codex-rs/codex-client/src/provider.rs`
L79-L89](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-client/src/provider.rs#L79-L89)),
including `POST /responses`
([`codex-rs/codex-api/src/endpoint/responses.rs`](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-api/src/endpoint/responses.rs)).
cc-switch independently sends the same `version` header on its Codex
OAuth generation path: [`src-tauri/src/proxy/providers/claude.rs`
L932-L933](77c6dc793d/src-tauri/src/proxy/providers/claude.rs (L932-L933)).
### Tests
- `tests/test_providers_codex_catalog.py`: the pinned value is now
`"99.0.0"`. The gate test serves a mock catalogue that filters by client
version and now includes a model gated above the newest release
(`0.170.0`); it checks that the sentinel lists it, that `visibility:
"hide"` entries are still dropped, and that `0.0.0` is not sent.
- `tests/test_providers_codex_client_version.py` (new, 17 cases):
`latest` is used and persisted; one fetch per cache window; prerelease,
empty, missing, `v`-prefixed, two-part, `0.0.0` and older-than-bundled
tags all fall back; offline falls back to the persisted value; a
persisted `0.0.0` is rejected; offline with nothing persisted gives
`FALLBACK_VERSION`; malformed JSON and a 429 fall back quietly;
`FALLBACK_VERSION` is a plain release `>= 0.159.0`.
- `tests/test_openai_codex_provider.py`: `_build_headers` sends
`version`; a turn sends npm's `latest`; a turn with npm unreachable
sends `FALLBACK_VERSION`.
- `tests/conftest.py`: an autouse fixture keeps the npm lookup off the
network (as `_no_openrouter_network` does for OpenRouter), so other
provider tests do not depend on what npm published that day.
## Test plan
- [x] Related tests (`test_providers_codex_client_version`,
`test_providers_codex_catalog`, `test_openai_codex_provider`,
`test_config_update_providers`, `test_rpc_model*`,
`test_providers_first_byte_budget`, `test_providers_chatgpt_token`,
`test_cli_provider_commands`): **586 passed**, with the host's `*_PROXY`
variables unset (with them set, 5 proxy-redaction tests in
`test_config_update_providers.py` fail identically on `main`).
- [x] Full suite (excluding `tests/integration`): 32427 passed, 101
failed. All 101 also fail with this branch's changes stashed (same IDs;
none in providers). They come from this host's environment, for example
a host default model leaking into playbook and sub-agent tests.
- [x] Mutation check: with the catalogue back on a real release and the
`version` header removed, the 5 new or changed assertions fail.
- [x] `ruff check` / `ruff format --check` on the changed files.
## Product trade-off
Because the catalogue now asks as `99.0.0`, it can list a model whose
gate is **above npm's `latest`**. Generation sends the real `latest`, so
such a model may be listed in Add model and the picker and then get a
400 on `/responses` until the next Codex CLI release ships. We chose to
show the account's whole roster over hiding models the account is
offered. The alternative, asking the catalogue as the resolved release,
would keep the two in step but recreate #986 whenever a gate moves ahead
of a release.
## Review follow-up
Two review findings are addressed in the latest commit:
- **Issue references in source (Blocking, inline):** `AGENTS.md` 1.1
forbids comments that reference an issue, and the changed module,
comment and test docstrings cited #986. The citations are removed; the
measured behaviour each one accompanied stays where it was.
- **An unusable cache aborted the turn (P2):** `_remember` resolved
`cache_path()` outside its `try`, and that path went through
`get_cache_dir()`, which creates the directory on the way out; `chat()`
awaited `resolve()` outside its request error handling. A file where the
cache directory belongs (or a refused `mkdir`) therefore raised after a
valid release had been fetched and stopped generation. Path resolution
is now inside the guard, every persistence failure is swallowed, and the
path is built from `raven_home()` directly so resolving it no longer has
a filesystem side effect. Covered by three tests: an unwritable cache
keeps the fetched release, an unwritable cache falls back instead of
raising, and a turn still goes out with the fetched release; all three
fail against the previously reviewed head.
## Known unverified (Open in #986)
- The catalogue sentinel is based on public measurements (#986,
hermes-agent#135024) and community use (opencodex), not on an
OpenAI-documented contract.
- **Not verified with a real account:** signing in to Codex and running
a turn on one of the new models (`gpt-6.1-sol` / `gpt-6-sol` /
`gpt-6-luna`). The `version` header matches what the official CLI sends,
but `originator` is still `raven` rather than `codex_cli_rs`. Whether
the backend accepts a turn from this client on these models still needs
one signed-in run before #986 can be considered fully resolved.
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
## Summary
Raven-Code reports Python syntax errors after file edits but misses
unresolved names and equivalent feedback after shell edits. Add advisory
Pyflakes F821/F822/F823 checks to the existing tool result; optional
F401 notices remain off by default. No additional model call or code
execution is involved.
```text
write_file / edit_file
-> inspect final source, compare with a baseline that can be read and analyzed
-> retain syntax warnings; suppress existing name findings
exec
-> require checkpoint visibility for the working directory
-> read the changed files from the host's write record for the command
-> ask visibility in batches of 256, select at most 8, check up to 4 concurrently
-> append ordered diagnostics, preserving exit status and file metadata
```
Existing syntax failures remain visible after unrelated edits and
identical rewrites. A baseline that cannot be read, parsed or analyzed
is marked unknown; overwriting non-UTF-8 source still checks the known
replacement. Source nested too deeply for the parser or checker, and a
changed file that cannot be read, report diagnostics unavailable for
that file rather than passing as clean. Every check reads a file as the
bytes Python runs: text a write or edit stores is checked as its UTF-8
bytes, the content it replaced included, and a file from disk as its
bytes, each decoded as Python decodes source, by its coding declaration
or as UTF-8. Bytes that do not decode are reported as a syntax error at
the line where decoding stops, so a declaration the written text cannot
satisfy is reported however the file was changed. Noqa comments are read
as Ruff reads them, including after other comment directives and never
inside string literals: a file-level `ruff: noqa` / `flake8: noqa`
counts only on a line of its own, and a marker counts only when codes
follow its colon or, with no colon, whitespace, another comment or the
end of the comment follows it. Unlike Ruff, which takes the first
directive in a comment, every directive in it counts. The seeded tool
guide gives the syntax note's own advice. With no checkpoint or no
visibility verdict, exec diagnostics do not inspect changed file
contents; direct file checks remain available.
Pyflakes is imported when the tool face loads, not by whichever check
first needs it: imported lazily, its cold import fell inside that
check's one-second wait, and on a slow Windows runner the one test that
paid it reported diagnostics unavailable for a plain syntax error.
Private workers bound reads and checks to four active jobs per process.
Saturated capacity rejects new work without queuing, and
timeout/cancellation retains each slot until the actual work finishes.
Name checks are capped at 256 KiB of source and the syntax check at 2
MiB, and a check skipped for size says so in one line. Findings are
capped at eight per file, and exec diagnostic text at 6,000 characters
plus omission notices.
Runtime changes stay inside the Raven-Code code-flow plugin, except for
one fix to `CheckpointService.trackable`, the visibility verdict that
exec diagnostics and the host's exec write record both rely on. On
macOS, git precomposes a file name it reads off the disk before matching
an ignore rule, but takes the paths `trackable` sends to `git
check-ignore --stdin` as written. A file stored with a decomposed (NFD)
name under a `.gitignore` rule written precomposed (NFC) is therefore
left out of the checkpoint, yet main vouches for it, so the write
record's diff carries its text, and exec diagnostics would quote its
source lines to the model. Nor is git's precomposition NFC: it composes
only neighbouring characters, by Unicode 3.2's table, and reorders
nothing, so a name whose combining marks are out of canonical order
comes out as neither the name as given nor its NFC. `trackable` now asks
about each name as given, as NFC and in git's macOS spelling, and
withholds it when any spelling is ignored. Other shared
file/shell/snapshot implementations are unchanged.
Raven-Code has no separate dependency manifest, so Pyflakes uses the
existing root dependencies. It is the only added package; uv normalized
existing lockfile markers without changing other package versions.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- **Before:** on main, Raven-Code's file tools report Python syntax
errors only, and its exec reports nothing about the Python files a
command changed. On macOS, main's `CheckpointService.trackable` vouches
for a file stored as `secret_cafe` + U+0301 + `.py` under the rule
`secret_caf` + U+00E9 + `.py`: the user's own git ignores it and the
checkpoint's staged tree leaves it out, yet its text reaches the exec
write record's stored diff.
- **After:** on macOS 26.6.2 / arm64 with Apple Git 2.54.0, the command
below passes 364 tests on Python 3.12.13 and on 3.14.6. The full default
suite on 3.12.13 has 32283 passed, 169 skipped, 20 failed and 3 errors
over 22 test ids: 21 of them also fail on the exact base in the same
environment, and the other, a remote process-tree cancel test that
missed its deadline under the suite's load, passes when run alone. Tests
cover actual worker overlap, retained capacity after
timeout/cancellation, host-tool isolation, hidden-file quotas,
visibility batching through the host's write-record wiring, baseline
handling, parser-limit failures, the size bounds and their skip notes,
undecodable bytes placed where decoding stops, coding declarations in
written and edited text, the baseline read staying on a worker, the
checker loaded with its module, the file each unavailable note names,
comment directives and their marker boundary, the tool guide's agreement
with the syntax note, portable commands in paths with spaces/non-ASCII
characters, and the checkpoint's verdict on decomposed names and on
names git spells as neither given nor NFC, held against its own staged
tree. Removing any of the three spellings from the query fails the cases
that pin it, as does removing the marker boundary, the parser-limit
report, the unknown-baseline handling, the syntax check past the
name-check bound and the decoding report, checking written text as its
stored bytes, the worker around the baseline read, loading the checker
with its module, or the file name in an unavailable note; restoring the
guide's earlier advice fails its agreement test. git's macOS spelling is
what libiconv's UTF-8-MAC conversion returns, which git precomposes
with: composing neighbours by Unicode 3.2's table reproduced it for all
281,928 names built from every decomposable character's decomposition
(reordered, partly composed, or with a mark added), and across 784,220
further mixed names and pairs no name was spelled outside the three
asked; the same held under Python 3.13 and 3.14. The decomposed-name
check asserts the macOS outcome only where git precomposes names, so it
also passes with `core.precomposeunicode = false` set through
`GIT_CONFIG_GLOBAL`. Across 102 noqa comment variants the reported lines
match Ruff 0.15.12, except the three that hold several directives in one
comment. Through the real `AgentLoop`, code-flow tool face,
`CodeExecutor` and checkpoint, with the working directory under `/tmp`,
under `$TMPDIR` and in a path with spaces and CJK characters, exec
diagnostics report created, modified and decomposed-name files, follow
`working_dir`, report an undecodable file at the line where decoding
stops, a syntax error past 256 KiB and a skip past 2 MiB, and withhold
`.gitignore`d files, including decomposed names and names git spells as
neither given nor NFC; across repeated runs on both interpreters, a file
near the 256 KiB cap is checked in 52-135 ms (117-128 ms against a
baseline), the syntax of a file near 2 MiB in 318-371 ms, and 600
ignored files plus one visible file take 73-90 ms with the event loop
held at most 20 ms. At this head CI passes the unit suite on
Linux/Python 3.12 (32619 tests over four shards), and its two Windows
steps pass the diagnostic files on native Windows/Python 3.13: 122
file/worker tests, and 27 exec diagnostic tests with 17 pre-existing
executor tests deselected; the symlink fixture skips only where the host
cannot create links.
```sh
env -u SERPER_API_KEY -u RAVEN_MIRRORED_SERPER_API_KEY uv run --no-sync pytest tests/test_agents_code_diagnostic_workers.py tests/test_agents_code_tools_plugin.py tests/test_agents_code_flow_exec.py tests/test_agents_code_flow_plugin.py tests/test_agents_code_flow_read_state.py tests/test_agents_code_launcher.py tests/test_workdir_snapshot.py tests/test_shell_command_writes.py tests/test_runtime_checkpoint.py tests/test_trajectory_upload.py::test_blocked_upload_hits_the_deadline -o addopts= -q --tb=short --maxfail=3
uv run --no-sync ruff check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py tests/test_runtime_checkpoint.py tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py tests/test_agents_code_diagnostic_workers.py
uv run --no-sync ty check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py
uv run --no-sync lint-imports
uv run --no-sync ruff format --check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py tests/test_runtime_checkpoint.py tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
```
Native Windows CI commands:
```sh
uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_diagnostic_workers.py tests/test_agents_code_tools_plugin.py -q -n 0 --tb=short
uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_flow_exec.py -k test_exec_ -q -n 0 --tb=short
```
Ruff, format and type checks passed; all 10 import contracts kept; the
commit-message, large-file and source-language checks pass over the
branch. The launcher tests unset inherited search API keys to keep the
expected tool list deterministic.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Scope: Raven-Code's enabled code-flow tool face; installing Pyflakes
does not activate checks in other agents. The change is reversible and
never fixes/removes code or rolls back edits. Static diagnostics can
need judgment for dynamic names, target Python versions, and project
lint configuration; only explicit noqa directives are honored. Passing
diagnostics do not replace tests.
The `trackable` fix reaches every exec write record, not only
Raven-Code: a file whose name, as given, as NFC or in git's macOS
spelling, matches an ignore rule keeps its counts and loses its diff and
removal body. Where git matches another of those spellings, as off macOS
for a decomposed name under a precomposed rule, the checkpoint stores
the file but it is still withheld; its counts remain.
Exec diagnostics now require an active checkpoint. Noninteractive runs
using the default interactive checkpoint policy must explicitly enable
checkpoints to receive this feedback. Visibility is checked in batches
of up to 256 files and stops once eight visible files are found; each
batch holds the event loop while the host resolves its paths, about 130
ms for a full batch on native Windows. Each file-check wait is one
second, and post-command diagnostics have a three-second wait budget;
past it, or when they fail as a whole, they are dropped and the
command's result is kept. These are caller budgets, not hard I/O
deadlines: running OS reads and inherited synchronous host callbacks
cannot be forcibly interrupted. Private worker capacity remains bounded.
Between 256 KiB and 2 MiB only syntax is checked: near 2 MiB that took
0.3-0.4 s and about 190 MiB here, up to four checks run at once, and on
slower hardware such a check can outlast the one-second wait and report
diagnostics unavailable. Python's GIL means concurrency does not promise
a CPU speedup.
Windows CI exercises the diagnostics layer with the real native
DirectExecutor. The existing CodeExecutor environment probe uses POSIX
quoting and already fails on Windows at the base; this PR neither
changes that probe nor claims end-to-end compatibility for it. Symlink
setup is skipped only if the host cannot create the fixture.
Disable `pythonLint` for syntax-only feedback, `execPythonDiagnostics`
for no post-command checks, or `pythonSyntaxNote` for no diagnostics,
under `plugins.config["code-flow"].tools`. The PR can also be reverted
as a unit.
- [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>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
Two follow-ups to #971, one per finding from its review round.
- Keep a DAG result's agent-output provenance when the preflight adds a
downgrade notice. `_with_notices` in `raven/agent/subagent/dag_tool.py`
rebuilt the `ToolResult` from its model and display text, so a
foreground run whose graph drew a notice (a node's `mcps` on an agent
that cannot take injected servers) lost its `agent_output` claim, and
the registry scrubbed values Raven holds out of the nodes' own output.
The notice now goes in through `dataclasses.replace`, as the playbook
capture notice already does, so every other field of the result is kept.
No other place in `raven/` rebuilds a result that can carry the claim:
the registry reads it off the result at its boundary, its local scrub
returns agent output untouched, and the refusal it rebuilds from the
permission gate is Raven's own text.
- Give `test_an_external_agent_reply_reaches_the_main_model_unchanged` a
permission config Windows can find. The suite writes its full-access
config under `HOME`, and `Path.home()` reads `USERPROFILE` on Windows,
so there the test ran under the default mode and its tool call was
refused before the reply could reach the assertions. A shared fixture
points `RAVEN_HOME` at the same config, which outranks both;
`test_a_tools_own_metadata_cannot_claim_provenance_either` uses it in
place of its own inline copy.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Earlier Linux validation, Python 3.12.13, before the portable echo
fixture adjustment below. These Linux suites were not rerun after that
test-only adjustment.
```sh
uv run --frozen --python 3.12 --all-extras pytest -q
# 8 failed, 32417 passed, 176 skipped, 2 xfailed
```
Each failing id was run again by id against a clean archive of the merge
base, through the same interpreter and extras and with the imported
`raven` checked to resolve inside the archive; all 8 fail there too.
Five depend on this machine's proxy settings, and the others on running
as root, the local node toolchain and a LibreOffice conversion.
The new
`test_a_dag_result_keeps_its_provenance_through_a_downgrade_notice` runs
a one-node graph through `ToolRegistry.execute` with a Python CLI agent
that echoes stdin. Before the fix the node's output came back as `the
agent answered [redacted: providers.openrouter.apiKey]` with
`agent_output` false; it passes after. Reverting the fix, or dropping
the final result's own `agent_output=True`, turns it red again.
The Windows case was reproduced on Linux with a scratch pytest plugin,
not committed, that resolves `Path.home()` to a directory the suite
never wrote, as Windows does through `USERPROFILE`. Under it both
`via_meta` cases of the agent-reply test failed on the refusal text
before the change and pass after; without it they pass either way.
Native Windows validation is recorded below.
```sh
uv run --frozen --no-sync pytest tests/test_security_untrusted_context.py tests/test_subagent_dag_runner.py tests/test_subagent_dag_core.py tests/test_subagent_dag_control_tools.py tests/test_subagent_dag_mcp_scope.py tests/test_tool_registry_execute.py -q
# 590 passed
uv run --frozen --no-sync ruff check raven tests
uv run --frozen --no-sync ruff format --check raven tests
uv run --frozen --no-sync ty check raven/agent/subagent/dag_tool.py
uv run --frozen --no-sync lint-imports
# passed; 10 import contracts kept
commitlint --from origin/main --to HEAD --config commitlint.config.cjs
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_source_language.py origin/main...HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_large_files.py origin/main...HEAD
# passed; each gate also rejected a deliberately bad control commit
uv run --frozen --no-sync python -m pre_commit run --from-ref origin/main --to-ref HEAD
# passed
COVERAGE_FILE=$CHECKS/cov.data uv run --frozen --no-sync pytest tests/test_security_untrusted_context.py tests/test_subagent_dag_runner.py -n 0 -q --cov=raven --cov-branch --cov-report=json:$CHECKS/cov.json
# 311 passed
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json $CHECKS/cov.json diff --base-ref origin/main --head HEAD --threshold 90
# 100.00%, 1/1 executable changed lines; passed
```
`$CHECKS` is the temporary result directory used for the run.
Native Windows 11 (build 26300), Python 3.12.13, with `uv sync --frozen
--extra dev --python 3.12` and `PYTHONUTF8=1`. `USERPROFILE`, `HOME`,
temporary files and OAuth-token directories pointed to disposable
directories; the test fixtures still exercised the real Windows home
precedence.
The existing permission fixture fixes both agent-reply cases on Windows:
both fail on the unchanged merge base, and both pass here. Native
validation also exposed the new DAG test's dependency on Unix `cat`
(`FileNotFoundError: [WinError 2]`). It now launches the quoted
`sys.executable` and echoes stdin using Python. The real subprocess,
registry boundary and all original assertions remain in place.
```powershell
uv run --frozen --no-sync pytest tests/test_security_untrusted_context.py::test_an_external_agent_reply_reaches_the_main_model_unchanged tests/test_security_untrusted_context.py::test_a_tools_own_metadata_cannot_claim_provenance_either tests/test_security_untrusted_context.py::test_a_dag_result_keeps_its_provenance_through_a_downgrade_notice -n 0 -q --basetemp "$CHECKS/final-target" --junitxml "$CHECKS/final-target.xml"
# 4 passed, 0 skipped
uv run --frozen --no-sync pytest tests/test_security_untrusted_context.py -n 0 -q --basetemp "$CHECKS/security" --junitxml "$CHECKS/security.xml"
# 36 passed, 2 failed, 0 skipped
```
The two full-file failures are
`test_another_programs_settings_are_redacted_when_a_call_reads_them` and
`test_ravens_own_home_is_not_read_as_another_programs_settings`. Both
also fail by ID on an unchanged merge-base worktree using the same
interpreter, with `raven` verified to import from that worktree. They
concern existing Windows path redaction and are outside this PR's
notice/provenance change.
With only the production `dataclasses.replace` change temporarily
withdrawn, the portable DAG regression fails on `agent_output is True`
and displays the redacted value. Restoring production code restores the
pass. The initial Windows selection was 3 passed / 1 failed because
`cat` could not launch; the final selection is 4 passed. No assertion
was removed, weakened or skipped.
Full Python Ruff check/format (2,371 files), 10 import contracts, the
DAG module's type check, full-PR pre-commit, commitlint,
commit-message/source-language/asset/whitespace gates all passed for the
portable fixture change. The coverage run repeated the four-case
selection with `--cov=raven --cov-branch
--cov-report=json:$CHECKS/native-coverage.json`: 4 passed. The raw diff
gate could not match coverage.py's Windows backslash paths to Git paths.
In a separate report copy, only the 860 file-name keys were converted to
forward slashes; all coverage values, file counts and metadata were
verified unchanged. `uv run --frozen --no-sync python
scripts/coverage_gate.py --coverage-json
$CHECKS/native-coverage-posix-paths.json diff --base-ref origin/main
--head HEAD --threshold 90` then passed at 100.00% (1/1 changed
executable line). The whole repository suite was not rerun natively.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No docs change: the result now matches what the agent integration and
permissions pages already say about content another agent returns.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
With a downgrade notice, a foreground DAG result now reaches the main
model with the nodes' output as the agents returned it, as every other
foreground DAG result already does under the returned-content policy.
The second change is test-only. Rollback is a revert.
## Related Issues
#971
## Summary
The machine registry behind a page. The Agent Hub gets a **Machines**
tab:
- every registered machine as a card, with the state of this computer's
link to it (`NodePool.status`) and its Raven node (live version while a
link is up, else the one recorded on the row), and the register card at
the end;
- **Register a machine**: name, id, address, port, user, private-key
path and work directories; the server reaches the machine once (the same
`connection_add.probe` as `raven ops connection add`), writes the row
and its ssh alias, and a refusal comes back with its kind (unreachable,
login refused, changed host key, timeout, no ssh here, duplicate id,
invalid field, registry file) so the page says in the reader's language
what to do, with the server's sentence under it;
- **Install node** / **Update node**: `node_install.plan` + `install`
run in a background task; `machines.list` reports it on the row
(`install.running/ok/detail`) and the page polls until it ends; the
sheet's *Install into* field is the command's `--dir`;
- **Remove machine** (after a confirmation): refused while an agent
entry names the machine (the entries are listed) or agents run on it
over the link; otherwise the row and the managed `Host <id>` block go,
the link is closed, the node on the machine stays;
- **Test link** (`machines.list refresh=true id=...`) and **Check**
(`machines.doctor`);
- a preset's sheet picks where it runs (*Runs on*) among the machines
with this Raven's node, with the working directory there for acp/cli,
and the connect carries `machine` / `remote_cwd` to `subagents.add`.
Nothing a row or a refusal carries is the way onto the machine: no
address, account or key path (the pool's and the probe's sentences are
scrubbed of them).
Also: `raven ops connection remove <id> [--yes] [--force]` as the
command behind the removal; `install-node` and the page record the node
they put on, or found on, the machine as `node_install` on the row,
which is how a listing says a machine has this Raven's node without
reaching it. New RPC group
`machines.{list,add,install_node,doctor,remove}` in the contract, the
Python models and both generated TS clients. Docs: machines guide
(en/zh) sections for the page and the removal, CHANGELOG, CONTEXT.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest -n 6` (full suite): 32094 passed, 174 skipped, 3 failed -- the
same three that fail on main on this Mac (libreoffice absent, two
simulation tests).
- `pytest tests/test_rpc_machines.py tests/test_ops_connection_add.py
tests/test_cli_ops_connection_commands.py tests/test_update_subagents.py
tests/test_rpc_registration.py tests/test_rpc_schema_match.py
tests/test_docs_site.py tests/test_living_docs.py -n 0`: all green (632
+ 18).
- `scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`:
94.29% of changed lines (the uncovered lines are since covered by one
more CLI test).
- `ruff check`, `ruff format --check`, `ty check` on the touched files,
`lint-imports` (10 kept, 0 broken), `tests/test_import_cycle_budget.py`,
`pre-commit run --files ...`: all pass.
- ui-web: `vitest run` 3959 passed (249 files), including the new
machines-tab tests and the five page gates (fixture shape, i18n
namespace, store shape, class namespace, domain registration); `tsc
--noEmit`; `eslint .` (0 errors, 4 pre-existing warnings in
SubagentsPage); `npm run gen:check`; `npm run build` with the boot
golden OK. ui-tui: `gen:rpc`, `gen:i18n`, `tsc --noEmit`.
- Real machine, from the page of an isolated gateway on this Mac (own
RAVEN_HOME, channels off), against one registered ssh machine:
registered through the form (probe + row + alias, no address shown
afterwards), node installed from the sheet (background task, card
reported the end, `node_install` recorded on the row, node directory
present on the machine), link tested (idle), Claude Code connected onto
the machine from its preset sheet with a working directory (entry
`claude_code@ravenx2` written, agent started there by the node), removal
refused while that entry was connected (the refusal named it), and, once
the entry was disconnected from the Connected tab, removed from the
sheet: the row is gone from the registry, the managed `Host` block is
gone from `~/.ssh/config` with the owner's own lines untouched, and the
node directory is still on the machine.
- The tab, the two sheets, the confirmation, a refused register (type
the id `locked`, `down`, `changed` or `slow`) and a refused removal (the
row agents run on) can all be walked through offline: build the page and
open `ui-web/dist/index.html?stub=1`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- Follow-up commit 3248a83cb, after the Windows review: the fixtures
that set `HOME` around the ssh-alias
helpers set `USERPROFILE` too, through `tests/_home.py`, and a test pins
the Windows reading of `~` with
`ntpath` on every platform (it fails against a `HOME`-only fixture). The
three files: 113 passed on macOS;
native Windows was not run here.
- Follow-up commit e9b150bc6, after the agent review's F1: the suite's
autouse `_no_real_raven_home` sets
`USERPROFILE` beside `HOME` through the same helper, so the two
ssh-alias CLI tests that bring no home of
their own (`store` and `reached` only) stop writing `Host gpu` into the
operator's `~/.ssh/config` on
Windows; `tests/test_conftest_no_real_home.py` pins the Windows reading
of `~` from a test without a home
fixture (red against the `HOME`-only fixture). The Windows reading
emulated on macOS (`os.path.expanduser`
-> `ntpath.expanduser`, outer `USERPROFILE` at an emptied sentinel, over
the three files): the two tests
wrote into the sentinel before, none after. Full suite on this Mac (`-n
6`): 32113 passed, 3 failed, the same three that fail on main here (a
LibreOffice case and two simulation cases). Native Windows was not run
here.
- Merge commit b58a6048d brings in main up to #971, whose family picker
lives in the same ext-agents page
files as the machines tab: five files conflicted (`ExtAgentsPage.tsx`,
its test, `source.ts`, `store.ts`,
`styles.css`), all resolved by keeping both sides. The tab strip counts
cards for the agent tabs
(`entries`, a family counts once) and registry rows for the machines
tab; `connect` carries `model` next to
`machine`/`remote_cwd`; the agent sheet, the machine sheet and the
family picker share the one drawer, so
opening any of the three clears the other two and `sheetDismissed` drops
all three. Checks on the merged
tree: ui-web `vitest run` 3997 passed (250 files), `tsc --noEmit`,
`eslint` on the feature, `gen:check`,
`npm run build` with the boot golden; the offline page (`?stub=1`) shows
the five tabs with their counts
and the machines tab as before; Python: the machines, connection,
contract and subagents files 366 passed,
the full suite (`-n 6`) 32480 passed, 5 failed: the three above plus two
`tests/test_acp_mirasim_uicli.py` cases that fail the same way on a
pristine `origin/main` checkout on this Mac (`mirasim ui-cli agents` did
not answer within 4s).
## Risk
- [x] Security impact considered -- the page never receives an address,
an account or a key path: the row is `connections.shown`-style data, the
probe's and the pool's sentences are scrubbed of the row's host,
user@host and key, and the register form's fields travel once in
`machines.add`. The install's package index stays on the step's stdin as
before. Removal needs a confirmation and is refused while entries or
running agents depend on the machine.
- [x] Backward compatibility considered -- new RPC methods and one new
optional registry field (`node_install`); `install-node` records it as a
warning-only step, every existing row and command keeps working,
`connections.shown` is unchanged.
- [x] Rollback path is clear for risky changes -- revert the commit; the
registry rows keep an extra `node_install` key that nothing else reads.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
Follow-up to LivXue's review note on #957 (the pick-up's binding at
`cli_agent.py:1393`). The machine's daemon kept an agent's stderr in the
task's record (`stderr.log`) but sent it only to the connection holding
the
task when a line was written, and `agent/attach` replayed `frames.jsonl`
alone. So what an agent said only on stderr while no connection held it
never
reached the host:
- **The session id a CLI names only on stderr** (hermes does). The
pick-up
#957 added binds a create's handle to the id in its output; for such a
CLI
it found none, warned "not resumable", and the next turn to the instance
opened a new session.
- **The reason a command failed.** A run picked up after this computer
stopped was reported as `exited 3` where the dispatch would have said
`exited 3: token expired`. This part predates #957.
- **The stderr written while a link was down**, on a run still being
watched, the same way.
The fix is in the node and the host's link to it (`raven/node/`):
- The daemon numbers stderr lines as it numbers frames (`agent/stderr`
carries `n`), and `agent/attach` takes an optional `stderr_after`: the
stderr lines past that one are replayed after the frames, under the lock
that forwards a new line, so none is sent twice or missed at the
handover.
It works the same for a live task, a finished one, and a record a daemon
that never ran the task reads. An attach that does not ask hears no
stderr,
as before; a `stderr_after` that is not a whole number is refused like a
bad `after`.
- The host's `ChannelEndpoint` counts the stderr lines it got
(`stderr_received`). A cli pick-up (`NodePool.attach`, a process that
read
none of them) asks from the first line; an acp pick-up from the line the
run's record kept as the prompt went out (`RemoteRun.stderr_received`,
follow-up commit below); a re-attach after a lost link
(`NodePool._reattach`) asks from the last one it read.
The cli dispatch and pick-up read stderr off the endpoint as before and
now
get all of it, so the reason and the session id are there. An acp
pick-up's
connection drains the same endpoint into the stderr tail it quotes in
its
errors and into its journal, so what the agent wrote during the turn
while
this computer was away reaches them too; the acp run record keeps the
stderr
line count as the prompt goes out, so the earlier prompts' lines are not
read again (follow-up commit below). No protocol bump:
the new fields are optional, and a node runs exactly the host's code
anyway
(protocol and digest are checked at every connection).
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `tests/test_node_stderr_replay.py`, new, 22 tests: the daemon numbers
and
keeps stderr lines; an attach replays exactly the lines past
`stderr_after`
(from a live task, a finished one, and a record a daemon that never ran
it
reads), none when not asked, none from a record with no `stderr.log`,
and
refuses a bad `stderr_after`; the endpoint counts by the node's numbers;
a
re-attach and a pick-up ask from the right line. End to end on the
stand-in machine (real daemon, stand-in ssh): a left cli run's reason on
stderr reaches its pick-up (said before and after this computer
stopped),
a left create that names its session only on stderr is bound to it by
the
pick-up (both orders), and a reason written while the link was down
reaches the run watching it. 18 fail on main (2c2718122); the 4 that
pass
there pin what does not change (no `stderr_after`, past the last line,
past the end, no `stderr.log`).
- Changed assertions: the four attach-parameter assertions in
`tests/test_node_client.py` and the forwarded-stderr one in
`tests/test_node_server.py` include the new fields.
- Full suite: 32065 passed, 173 skipped, 2 xfailed, 3 failed -- the same
3
that fail on main (2c2718122) on this computer when run alone there: a
host
without LibreOffice, and two simulation cases.
- Diff coverage: 100.00% (30/30 executable changed lines; `coverage
json`, then
`scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`).
- `ruff check`, `ruff format --check`, `ty check`, `lint-imports`,
pre-commit on the diff; `scripts/check_commit_messages.py`,
`scripts/check_source_language.py` and `scripts/check_large_files.py` on
`origin/main..HEAD`: clean.
- Docs: CONTEXT.md's Raven node entry, the protocol module's notes, and
the
machines guide's "Disconnects and restarts" section in English and
Chinese
now say the daemon keeps and replays stderr; the changelog has an entry
under Fixed. `tests/test_docs_site.py` and `tests/test_living_docs.py`
pass
(18), `mkdocs build --strict` passes.
- Real machine, ravenx2, an isolated node directory per tree. The host
process that dispatched was killed with SIGKILL and the run picked up by
a
new process; the link was dropped by killing the local ssh. The command
writes `token expired` (or `session slow-A1`) on stderr:
| Probe | main (2c2718122) | this branch |
|---|---|---|
| reason written after the host process was killed | `exited 3` |
`exited 3: token expired` |
| reason written before it was killed | `exited 3` | `exited 3: token
expired` |
| reason written while the link was down | `exited 3` | `exited 3: token
expired` |
| create left before its commit, session id only on stderr | "not
resumable", nothing bound | bound to `slow-A1`, no warning |
The machine was cleaned after: the probe's two daemons ended by pid, its
directory removed.
- The runs above are on main 2c2718122 (#957 merged). The branch was
then
rebased onto 400b30dfa, whose two new commits touch only TUI copy and
i18n; the node, docs and range checks were run again there (238 passed,
1
skipped). It merges cleanly with the open #964 and #965 (`git
merge-tree`).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- Follow-up commit e0468fa88, after the agent review's F1 (an acp
pick-up asked
for the stderr from the agent's first line, across every earlier prompt
of
its process): `RemoteRun.stderr_received`, taken in
`Tracker.prompt_sent`
off the endpoint's count, and passed through `NodePool.attach(...,
stderr_after=...)` by the pick-up; a cli pick-up keeps asking from 0; a
record from before the field reads with 0. Regression on the stand-in
machine
(`test_a_pick_up_reads_the_turn_s_own_stderr_and_not_what_the_prompts_before_it_wrote`):
two turns of 150 stderr lines, a third interrupted after its prompt, the
next start's pick-up -- before the change its tail held 200 lines, 50 of
them the second turn's; after it, the third turn's 150 and nothing else.
Unit tests pin the record, the pick-up's attach arguments and the
default
of 0, and the tracker's wiring. The related files 259 passed; full suite
32067 passed with the three failures this Mac always has, plus one test
whose stand-in `Tracker` lacked the new keyword, fixed in the same
commit.
Diff coverage of the changed lines: see CI.
## Risk
The replayed lines are the agent's own stderr, already kept in the
task's
owner-only record and already sent live to whichever connection held the
task; nothing new leaves the machine. `stderr_after` and `n` are
optional: an
attach without `stderr_after` behaves as before, and a line without a
number
counts on from the last. A cli pick-up replays the whole `stderr.log`,
as it
already replays every frame of the command; an acp pick-up replays the
lines
past the count its record kept as the prompt went out, so the replay is
bounded to the turn, and the connection keeps a bounded tail of it.
Rollback
is reverting the commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Follow-up to #957, for this review note:
https://github.com/EverMind-AI/Raven/pull/957#discussion_r4282448689
---------
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
Connect the coding agents Mirasim runs as Raven ACP sub-agents, with one
bundled preset per agent and no separate adapter download.
- Serve Claude Code, Codex, Kimi Code, Antigravity, Qwen Code, Grok
Build, DSH, Pi and ZCode CLI through `mirasim ui-cli`. The adapter
runs on Raven's interpreter, so a Mirasim preset is not offered on a
registered machine, and a stored row whose interpreter is gone is
pointed at the running one when the config is next read. It withholds
session MCP because ui-cli does not accept per-session servers. The
boot capability backfill asks Mirasim once which agents it has
installed and handshakes only those.
- Read model and effort choices from Mirasim. Offer the own models of
Claude Code, Codex, Kimi Code and ZCode CLI on both their own-account
and Mirasim platform routes. Persist conversation bindings and switch
routes before continued turns. A menu read that fails is tried again
after a short pause rather than kept for the cached copy's lifetime,
an effort the menus in hand do not offer is read again before it is
refused, and a failed menu read still reports the agents installed
since the last one. A connect or test whose handshake could not read
the menus keeps the ones already measured, and connecting an agent
with a model refuses one its measured menu does not offer, as editing
one already did.
- Retain the last model catalog when a refresh fails. Deleting a session
prevents later writes, prompts, loads and route switches, waits for an
already-running store write, and does not wait for unrelated catalog
work. A turn, and its cancel, uses the catalog in hand instead of
queueing behind another session's read.
- Relay questions and tool approvals through ACP. Content returned by
another agent retains that agent's redaction policy, including values
matching Raven's configured credentials. The rule covers Mirasim,
shared sub-agent records and announcements, delegated tool results,
A2A replies, logs, main-agent context, live ACP updates and session
replay. Provenance is decided per result: a tool's declaration admits
it to carrying another agent's content, and each result that does
claims it, so a delegating tool's own errors, receipts and status
lines stay Raven's text under the local scrub, and no result can claim
provenance its tool never declared. Forwarding through `tool_call`
carries a result whole for every tool, so a refusal reached that way
ends the turn as a direct call does. The contract surface version is
incremented for the added provenance fields. Local tool-result
protections, outbound credential handling, permission checks and
untrusted-content fencing retain their existing roles.
- Group unconfigured Mirasim presets into one card. Connect each member
with its selected model in one write. Missing members open the
existing installation and recheck flow, and a member whose handshake
was refused for want of a sign-in is named in the drawer as it is on
its card. A family whose members sit in two sections of the agents
page draws one card in each. Narrow drawers keep the agent name and
place the model and action on a second row.
- Guard command processes and clean up their descendants on
cancellation, including ones a tool starts in a session of its own
while the agent ignores SIGTERM: on Linux the guard adopts them as a
child subreaper, and the process tree is read again before SIGKILL. A
guard that outlasts its drain no longer replaces the command's own
error with a shutdown traceback. Stage oversized prompts within the
full Windows command-line budget, counting the venv launcher's second
launch, refuse a `mirasim` that resolves to a `.bat` or `.cmd` shim,
and preserve percent escapes and UNC authorities in file attachments.
The guard starts without the ACP package, polls its command's exit
quickly at first and then slowly, and the adapter's stderr log carries
no local variables.
- Share the existing ACP stdin reader with the adapter, and update the
integration docs, domain vocabulary, translations and agent-mark
attribution.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Rebased onto current main and reran validation on Linux with Python
3.12.13 and Node 22.23.2. The isolated interpreter resolves this
checkout even when a subprocess clears PYTHONPATH. Existing dependencies
were reused without changing their declarations or lockfile. In the
commands below, `$CHECKS` denotes the temporary result directory used
for the run. Both Python selections use the same
`COVERAGE_FILE=$CHECKS/post-rebase.coverage`.
```sh
uv run --frozen --no-sync pytest tests/test_agent_loop_*.py tests/test_acp_mirasim_*.py tests/test_tool_registry_*.py tests/test_subagent_acp*.py tests/test_subagent_activity.py tests/test_subagent_history.py tests/test_subagent_manager.py tests/test_subagent_probe_state.py tests/test_security_untrusted_context.py tests/test_tool_admission.py tests/test_tool_search.py tests/test_cli_log_file.py tests/test_acp_journal.py tests/test_a2a_client_tool.py tests/test_subagent_mirasim.py tests/test_subagent_probe.py tests/test_subagent_third_party.py tests/test_ui_agent_marks.py tests/test_acp_replay.py tests/test_acp_updates.py tests/test_rpc_console.py tests/test_rpc_system.py -n 0 -x -q --tb=short --show-capture=no --cov=raven --cov-branch --cov-report=json:$CHECKS/post-rebase-coverage.json --cov-report=xml:$CHECKS/post-rebase-coverage.xml --junitxml=$CHECKS/post-rebase-python.xml
# 2871 passed
uv run --frozen --no-sync pytest tests/test_contracts_*.py tests/test_tool_admission.py tests/test_tool_registry_execute.py tests/test_security_untrusted_context.py tests/test_config_loader.py tests/test_raven_config_tool.py tests/test_rpc_subagents.py tests/test_subagent_name_vocabulary.py tests/test_tool_refusal_continuation.py -n 0 -q --tb=short --show-capture=no --cov=raven --cov-branch --cov-append --cov-report=json:$CHECKS/post-rebase-coverage.json --cov-report=xml:$CHECKS/post-rebase-coverage.xml
# 487 passed, 1 skipped (POSIX directory permissions are not enforced for root)
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json $CHECKS/post-rebase-coverage.json diff --base-ref origin/main --head HEAD --threshold 90
# 93.33%, 1594/1708 executable changed lines; passed
```
The full Python suite, `uv run --frozen --python 3.12 --all-extras
pytest -q`: 9 failed, 32315 passed, 176 skipped, 2 xfailed. Each failing
id is then run by id against a clean archive of the merge base, through
the same interpreter and extras and with the imported `raven` checked to
resolve inside the archive; every id that fails here also fails there.
The catalog-only failure and resumed-session deletion regressions failed
before their fixes. Additional tests exercise deletion during catalog
reads, store writes and route lookups. The content-policy tests failed
against the former redaction behavior and now check exact content
through direct calls, tool_call, the main provider, recorded frames,
persisted transcripts and ACP replay. Local file reads and outgoing
credential records remain covered by controls.
In ui-web:
```sh
npm test -- --no-file-parallelism
# 250 files, 3977 tests passed
npm run gen:check
npm run type-check
npm run lint
npm run build
# passed; lint has four warnings in unchanged files
```
Chromium checks used the actual page and styles with synthetic agent
rows. Model selection travels in the connect request; Escape closes only
the picker; missing members reach the download link and Check again. At
390px and 320px the name columns measure 252px and 182px, respectively,
with no horizontal overflow in the drawer. No page errors were reported.
```sh
make check-commits check-large-files check-source-language
# passed
npm run lint:i18n --prefix ui-tui
npm run lint:rpc --prefix ui-tui
# passed
uv run --frozen --no-sync python -m pre_commit run --from-ref origin/main --to-ref HEAD
```
The full-PR pre-commit run passes except prettier (ui-tui), which flags
`src/components/newInstancePicker.tsx` and
`src/components/subagentsHub.tsx`. Both files are byte-identical to
main; running the formatter against their main contents fails too. The
fixes do not touch either file. Commit-scoped hooks for the new changes
pass. Ruff check and format, ty on changed production files, all ten
import contracts, and whitespace checks pass. Every replayed commit
retains its patch, and the PR title and body pass the repository's ASCII
and commit-message grammar checks.
The earlier native Windows verification covers prompt launch limits and
file-URI conversions. This follow-up has no new native Windows, real SMB
or live vendor/provider run.
- [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
Credential authorization and scope belong at the point where access is
granted. Redacting a later reply cannot revoke access the receiving
agent already has. Under this product policy, Raven preserves returned
content unchanged and leaves redaction decisions to the sending agent.
Credentials an agent includes in its reply can therefore remain in
Raven's retained logs and transcripts.
Agent-returned content is preserved according to the sender's policy
across all supported delegation paths. The adapter returns each reply
when the turn settles rather than streaming it. Short prompts use
command-line arguments; oversized prompts use temporary attachments.
Connecting an agent probes it: with a model chosen, on that model's own
route, so the pick a connect carries is proved before the row is stored;
with none, on the agent's default. Compatibility was originally measured
against Mirasim 0.0.465; older CLI versions have not been verified.
A stored Mirasim row whose interpreter no longer exists is rewritten in
the config file, once, by the first Raven to read the config after that
interpreter is gone. A row naming another interpreter that still exists
is left as written, so two installs reading one config do not rewrite it
back and forth.
Rollback is a revert. Configured Mirasim rows then need removal because
their bundled adapter is no longer present, and until they are removed
Raven refuses to load the config at all: an unknown preset name fails
validation, so the host does not start and the file has to be edited by
hand.
## Related Issues
N/A
## Summary
A failed turn's Web row can expand to the provider's full diagnostic
text, up to 8,000 characters, while the existing bounded reason stays
unchanged. The optional `full_detail` field travels through the runner,
lane, RPC event and session marker, so live display and replay expose
the same account. Copy includes the expanded account. Quiet runtime
notices use "Show details" instead of the error label.
Failure details and call-record bodies remove known credential shapes
before the final cap. An unterminated private-key block is removed
through the end of the input, including when an earlier scan or call
record cut away its closing armour. Known cut boundaries also remove
incomplete JWTs, vendor tokens, URL passwords and labelled credential
tails; each of those patterns is searched only from behind the run of
its own value's characters that ends the input and the label in front of
it, so the scan stays linear whatever the text holds and still reads a
label gap of any width. The authorization and JWT patterns avoid
repeated backtracking, and the turn path and outer runner reuse the
computed detail. Attachment and lane reads use the base exception's
instance storage, so a foreign read-only property or throwing getter
cannot replace the scrubbed value or swallow the terminal failure event.
The optional fields are mirrored in the RPC schema and both generated
clients. The design document separates this delivery from the subsequent
Turn Continuation feature; Retry still starts an ordinary turn.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
The automated suites and static/build checks below were re-run after
synchronizing with main, using the existing local dependencies. The
independent behavioral and timing probes were measured before that
synchronization. The last three commits change only
`raven/security/redact.py`, two test files and the design document; on
that final tree the Python suite, the ui-web tests, the type, generation
and lint checks, `ty`, the import contracts, the range gates and
pre-commit were run again, and the ui-web build checks were not, since
none of their inputs changed.
- `uv run --no-sync pytest -q tests/test_agent_loop_failure_text.py
tests/test_llm_call_record.py tests/test_agent_loop_broken_turn.py
tests/test_agent_loop_llm_error_patience.py
tests/test_agent_loop_run_emit.py tests/test_spine_scheduler_lane.py
tests/test_spine_events.py tests/test_rpc_spine.py
tests/test_rpc_schema_match.py tests/test_kernel_budget.py
tests/test_acp_redact.py tests/test_security_untrusted_context.py -x
--tb=short --show-capture=no`: 904 passed.
- From `ui-web`: `npm test -- --no-file-parallelism
src/features/transcript/TranscriptPage.test.tsx
src/state/session/pipeline.events.test.ts
scripts/gates/i18n-keys.test.mjs`: 225 passed.
- From `ui-web`: `npm run type-check`, `npm run gen:check`, `node
../ui-tui/scripts/gen-i18n.mjs --check`, `node
../ui-tui/scripts/gen-rpc-types.mjs --check`, and `node
node_modules/eslint/bin/eslint.js
src/features/transcript/TranscriptPage.tsx
src/features/transcript/TranscriptPage.test.tsx`: passed.
- `uv run --no-sync lint-imports`: 10 contracts kept. `uv run --no-sync
ty check raven evolver agents plugins-dist scripts`: passed. Ruff check
and format check passed on the 20 Python files this PR changes.
- From `ui-web`: `npm run build`, `uv run --no-sync python build.py`,
`node scripts/check-page.mjs`, `node scripts/check-css.mjs`, and `node
scripts/check-class-namespace.mjs`: passed, including both boot
snapshots.
- `UV_NO_SYNC=1 make check-large-files check-source-language
COMMIT_RANGE=origin/main..HEAD`: passed. `PYTHONPATH=. uv run --no-sync
python scripts/check_commit_messages.py origin/main..HEAD`, commitlint
over the same range and `git diff --check origin/main...HEAD`: passed.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref
HEAD`: all applicable hooks passed except the whole-TUI Prettier hook,
which reports `newInstancePicker.tsx` and `subagentsHub.tsx`. Both files
and the formatter config are unchanged from main; an isolated main-file
control with the same locked Prettier version reproduces both failures.
`node ui-tui/node_modules/prettier/bin/prettier.cjs --check
ui-tui/src/i18n/messages.generated.ts`: passed.
- Regression coverage includes truncated private keys, incomplete JWT
and credential tails, terminal-event delivery with foreign exception
attributes, scan reuse and CPU cost, the cut-tail scan's cost on
label-shaped runs and long gaps, its agreement with a whole-text search,
a label gap of any width, the JWT boundary and private-key END rules,
and quiet-notice expansion. The five independent boundary probes passed
before the base synchronization; the committed regression suite above
passed again afterwards.
- On the same 32,267-character synthetic crash input, the queued
event-loop callback delay fell from 15.351 seconds to 0.00951 seconds.
The regression checks use thread CPU time with a 0.5-second ceiling.
- Cut-tail scan: a failed turn whose crash text holds 31,000 spaces
before its last two words took 32.6 seconds while the region came from a
regex search for the last whitespace, and 0.016 seconds now; 64,000
characters of `pwd=` ending in a comma took 10.8 seconds through the
whole-text tail search and 0.003 seconds now, and a 300,000-character
call-record body of either shape takes under 0.3 seconds. These and the
figures below were measured with the machine's load average between 36
and 132. Across 3,728 timed texts, every label or prefix unit repeated
to 64,000 characters behind a cut and to 300,000 past the scan cap, the
slowest measured alone took about 0.2 seconds against about 0.1 seconds
on the base revision, and a text past the cap takes the same time at
twice the size. Searching the whole text again turns six timing cases
red; a smaller name room, a skipped gap or scheme step, or any value
class narrowed below its pattern's turns the property or gap test red,
as does removing the JWT boundary or restoring the END-only private-key
rule. On 12,008 generated texts with gaps up to 5,000 characters, the
output equals the whole-text version's.
- Chromium with synthetic local data: full text retained and HTML
escaped, expanded tooltip removed, internal scrolling and Retry
preserved, neutral notice label displayed, no page errors. No live
vendor call or native Windows rerun is claimed for these fixes.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered: the long text is scrubbed of
recognized credential shapes before persistence and publication. It
remains diagnostic text and may contain hostnames or paths. Model
history and chat-channel replies keep their existing bounded content. A
session export can include the long text. `raven.security.redact` is
also the scrubber for every ACP surface (tool titles, result previews,
permission prompts, replay, error messages) and for the outbound
client's permission log, so two of its rules reach those surfaces too: a
private-key header without END hides the rest of that text, and a JWT
glued to a preceding word character, such as `/verify-eyJ...`, is left
unredacted. Tests pin both.
- [x] Backward compatibility considered: the new fields are optional,
older markers fall back to their bounded reason, and the TUI can ignore
the extra field. Incomplete private-key blocks are conservatively
removed to the end, which can also omit trailing diagnostic text. Custom
runners attach long details in the exception's instance dictionary;
descriptors are ignored.
- [x] Rollback path is clear for risky changes: revert the squash
commit. Older code ignores the optional marker field.
## Related Issues
N/A
---------
Co-authored-by: Codex <noreply@openai.com>
## Summary
The two code notes LivXue left on #957 about `_bind_picked_up` (the
pick-up of a cli create left running on a registered machine), and the
two comments the same review found stale.
- **A stateless run binds nothing at a pick-up.** The gate read `not
run.handle`, which never fires: every run carries a handle (`instance`
or `task_id`), and a stateless entry may declare `idSource: derived`
too, which the dispatch path reads nothing from and binds nothing with.
The pick-up now reads the record's `stateful`, the flag the dispatch
wrote, so a stateless derived run is picked up with no binding and no
"not resumable" warning, as `_attempt` leaves it.
- **A binding a dispatch made while the pick-up waited is kept.** The
pick-up committed without the handle's lock and without a lookup; a
dispatch to the same named instance during the window looked up, found
nothing, created and bound, and the pick-up then overwrote that with the
picked-up create's session, moving the instance back to a thread the
newer turn never saw. `_bind_picked_up` now takes `hold_handle` around a
lookup and the commit, as `run` -> `_run_stateful` does, and keeps any
binding it finds (with no warning: the instance is resumable through
it).
- **The binding is one atomic step, for both id sources, and the pick-up
waits for no turn** (the review's two notes on this PR's first commit).
`InstanceRegistry.bind_if_absent` binds a handle only where nothing is
bound, under the registry's own lock, and returns what the handle is
bound to after; the cli pick-up (`derived`) and
`resume_remote._conclude` (the minted id of the default `provisioned`
entry, which had the same race) both use it. The pick-up takes no
`hold_handle`: the dispatch holds that across its whole turn with no
timeout, and the pick-ups run one after another, so waiting there would
have held back every run picked up after it. The dispatch commits last
whichever way the two land, so the handle ends on its session in every
interleaving.
- **Two comments in `manager.py`** (`announced = True` and the
`finally`) said the kept record was a refused reply's only; since #957 a
refused failure announce keeps it too, and the comments say so now.
CHANGELOG's #957 entry gained the same clause.
Thread links:
https://github.com/EverMind-AI/Raven/pull/957#discussion_r4279888660
(stateless gate),
https://github.com/EverMind-AI/Raven/pull/957#discussion_r4279889284
(lock and lookup),
https://github.com/EverMind-AI/Raven/pull/957#discussion_r4279889891
(comments). The third note on that PR, the stderr replay, is #977.
Follow-up commit, after the review of this PR:
- **A left turn that resumed the session its handle is bound to closes
its row.** `bind_if_absent` found the handle bound to that very id and
wrote nothing, so the `running` the manager put on the row when the turn
began stayed and the instance read as interrupted after a reply that was
announced (the merge base's `commit` rebuilt the row and dropped it). It
now rebuilds a row bound to this very id too, as a binding alone; a row
bound to another id is still that turn's.
- **The pick-up finishes its own record.** `_spawn_record` took the
latest running record of the agent and handle, so a newer turn to the
same named instance, which opens its record as its dispatch starts,
could have the left run's reply written into it and its node closed. The
record the manager named when it left the run (`node_id` in the run's
origin) is taken first; the latest running is the guess only for a run a
host killed outright left unannotated.
Thread links:
https://github.com/EverMind-AI/Raven/pull/979#discussion_r4292200672
(the row),
https://github.com/EverMind-AI/Raven/pull/979#discussion_r4292202696
(the record).
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Each fix has a test that failed first on the tree before it: the pick-up
binds the id its output names; a stateless derived run binds nothing and
warns of nothing; a newer binding is kept; the interleaving itself
against the real `InstanceRegistry` (the pick-up completes while a
dispatch still holds the handle, and the handle ends on the dispatch's
commit); `bind_if_absent` binds once and reads a status row or another
kind as absent; `_conclude` keeps a newer binding for a minted id. The
first three fail on `main`; the last three fail on this PR's first
commit.
- `.venv/bin/python -m pytest -n 6 -q <the 21 test files that touch the
cli backend, hold_handle, the instance registry, the remote run records
or the pick-up>` - 1842 passed; changed-line coverage 100% (23/23,
`scripts/coverage_gate.py diff --base-ref origin/main`). Full suite:
32047 passed, 174 skipped, 2 xfailed in 3 min 50 s; the 3 failures are
the ones `main` has on this machine (a host without LibreOffice, two
simulation records).
- `ruff check` / `ruff format --check`, `ty check` on the two changed
modules, `lint-imports` (10 contracts kept),
`scripts/check_commit_file.py`, `scripts/check_source_language.py`,
`scripts/check_large_files.py`, `pre-commit`: clean.
- Real machine (ravenx2, isolated registry copies and Raven homes, this
branch's node and `main`'s node under their own `node_dir`; the same
script on both trees):
| Probe | `main` | this branch |
|---|---|---|
| F3: a named derived create left running; the next start picks it up; a
dispatch to the same instance runs during the pick-up; then one more
turn | the pick-up overwrote the dispatch's binding with its own
session, and the next turn resumed the old session (`resumed
first-<pid1>`) | the dispatch's binding kept, and the next turn resumed
it (`resumed first-<pid2>`); the pick-up's own session left unbound |
| F2: a stateless derived create left running, picked up by the next
start | picked up ok, and bound the handle to `s-<pid>` | picked up ok,
nothing bound, no warning |
| F1: a provisioned (default) named create left running; a dispatch to
the same instance during the pick-up; then one more turn | `_conclude`
bound the minted id over the dispatch's, and the next turn resumed the
minted session | the dispatch's session kept, and the next turn resumed
it; the minted id left unbound |
| F2T: a dispatch holding the handle for ~25 s while the left run's
command had already ended (this PR's first commit vs this head) | the
pick-up's announce came at +25.4 s, only when the newer turn released
the handle at +25.4 s | the pick-up announced at +5.0 s (as soon as its
command's output was read) while the newer turn ended at +25.4 s; the
handle ended on the newer turn's session |
Docs checked against the code before pushing: the `_bind_picked_up`,
`bind_if_absent` and `_track_on_machine` docstrings, the comment in
`_conclude`, the two `manager.py` comments, CONTEXT.md's Raven node
entry (unchanged: it describes the pick-up without the binding detail),
and the CHANGELOG entry.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- Follow-up commit 1f4fa74ce: the three tests above fail on fc57b7912
(status `running` kept; the newer
record finished) and pass now; `tests/test_resume_remote.py`,
`tests/test_subagent_cli_remote.py`,
`tests/test_subagent_acp_remote.py`, `tests/test_subagent_manager.py`,
`tests/test_remote_runs.py`,
`tests/test_remote_resume.py`: 372 passed. Full suite on the merged
tree: 32061 passed, 173 skipped,
3 failed (the same 3 that fail on main on this computer: LibreOffice and
two simulation cases). Diff
coverage 93.18% (41/44). ruff, ty, lint-imports and the three range
checks on `origin/main..HEAD` clean.
main merged in first (#964, #970, #980), no conflicts.
## Risk
- [x] Security impact considered - none: the pick-up binds strictly less
than before (never for a stateless run, never over a binding already
made), through one step under the registry's own lock.
- [x] Backward compatibility considered - records written before this
change carry `stateful` already (#934); no format change.
- [x] Rollback path is clear for risky changes - a plain revert.
## Related Issues
Follow-up to #957 (the three nonblocking notes of its review).
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
A Raven node daemon that starts after one was killed under a running
agent ends the orphan only when the pid is still the agent the record
names: `_still_ours` wants a process-group leader, born when the record
says, running the recorded command. The command mark read
`basename(argv[0]) in ps -o command=`. On macOS that is false for the
commonest agent command there is: `/usr/bin/python3` is a stub that
execs `Python.app/Contents/MacOS/Python`, so `ps` shows that image as
argv[0] and `python3` nowhere. Measured 2026-10-16 on a macOS machine
reached over ssh (this computer, registered against itself): the daemon
was killed under a `python3 wait.py` agent, the restarted daemon
recorded the task as gone and told the host so, and the agent ran on for
over a minute until the test ended it by pid. Linux is not affected: the
prctl death pact ends the agent with the daemon before anyone looks
(measured the same day on a Linux machine, agent gone in 4.5 s).
The fix: the command is known by the name it was started under *or* by
its positional arguments in the order they were given. The second
commit, after review, replaced "all arguments joined" with that: npm's
`npx` retitles its own process `npm exec <spec>` (measured on macOS, npm
10.9.8), so for the two npx presets this repository ships neither the
name nor `-y <spec>` is in the line, while the package is -- what such a
program keeps is what it was asked to run, and a flag like `-y` is the
first thing it consumes. The name-only match still counts, so nothing
that matched before stops matching. `ps` is asked with `-ww`, as
`raven/utils/processes.py` and the everos server ask it, because procps
cuts the column to `COLUMNS` even into a pipe and the arguments sit at
the end. A bare name that execs into another image still cannot be told
and is left alone; the docstring says so. Marks one and three (group
leader, birth time) are unchanged, so a reused pid is still refused.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- New:
`test_still_ours_knows_the_agent_by_its_arguments_when_argv0_was_exec_d_into_another_image`
fakes `ps` the way macOS prints it (image path first, arguments intact),
the real npx line (`npm exec <spec>`, and another package under it,
refused), another program with the same arguments (refused), the
name-only match (still counts, even with the arguments out of order),
the positional order (counts), and asserts `-ww` on every `ps` call.
`test_on_macos_an_agent_started_through_the_system_stub_is_still_ours`
runs the real stub on macOS through `Daemon.recover()` and is skipped
elsewhere. Both red on main.
- `pytest tests/test_node_server.py -n 0`: 117 passed, 1 skipped (on
macOS the darwin test runs).
- Real machines, same day, with this node installed. The npx case on the
Mac, through the node: the adapter's recorded pid shows `npm exec
@agentclientprotocol/claude-agent-acp@0.81.1`, `_still_ours` is True for
it while the daemon is up; with the daemon killed under it the adapter
leaves by itself about 1 s later (its stdin was the daemon's pipe; the
ACP server exits on EOF), so the next daemon rightly records gone and
nothing is left. The script case: daemon killed under a running script
agent on the macOS machine -> the turn ends in 7.3 s with "the Raven
node on this machine was restarted while the agent ran; nothing could
read the agent's output any more, so it was ended" and the agent process
is gone 7.5 s after the kill (before this change: "...and the agent is
gone" while the agent ran on for over a minute); on the Linux machine ->
unchanged, "...and the agent is gone" in 3.5 s, agent dead in 3.7 s (the
death pact ends it first).
- `ty check raven/node`, `lint-imports`, `ruff`: clean (10 import
contracts kept).
- Full suite (`-n 6`, on a laptop shared with other test runs), first
commit: 32044 passed, 5 failed. Three are this machine's standing
failures (a LibreOffice case, two simulation cases). The other two,
`test_a_blank_line_an_agent_prints_is_forwarded_recorded_and_replayed`
and
`test_a_launch_that_quit_on_an_old_node_is_named_with_both_versions`,
pass 3/3 when run on their own on this branch; a parallel run of the
same node test files on unchanged main trips other timing-sensitive
cases instead, so they are load, not this change, which touches
`_still_ours` alone. After the second commit: 32046 passed, 174 skipped,
2 xfailed, 3 failed -- the three standing ones only.
- [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
The check only ever ends a process that is alive, leads its own group,
started at the recorded time and now also matches the recorded
arguments; the widened mark cannot end anything the old one would have
refused for a reason other than the argv[0] rename. Rollback is
reverting the commit.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
Three follow-ups to #963 (installing a Raven node on a registered
machine),
from LivXue's review of it. Only `raven/node/install.py` and its test
change.
- **An old uv no longer skips the configured index.** #963 hands uv the
index
pip is configured with on the machine through `UV_DEFAULT_INDEX`, which
uv
reads since 0.4.23 (uv's changelog adds it there together with
`--default-index`). A machine's own uv older than that ignores the
variable
and installed from PyPI while the plan named the mirror -- before #963
such a
uv refused the `--default-index` argument instead, loudly. The probe now
reports the found uv's version (`UV_VERSION`, from `uv --version`). With
an
index configured, a uv older than 0.4.23, or one that does not say its
version, is passed over: the pinned uv is fetched under the node dir as
for
a machine with none, and the plan says why ("the machine has uv 0.4.22,
and
only uv 0.4.23 or later installs from the index pip is configured
with").
With nothing to fetch it with, the install says so in one sentence
naming
the version. Without an index configured an old uv is used as before.
- **The port check is an install's, not the look's.** #963 refused an
index
whose port is not a number from 0 to 65535 in `plan()`, which
`install-node`
calls before it reads whether the node is already there and before
`--prune`; neither needs the index, so a machine that had its node and a
bad
port in pip's configuration could not be told so or pruned. The check is
now in `refusal()`, with the same sentence; the look takes the machine
as it
is.
- **The real install test no longer reaches the network.** Its `run`
stand-in stood in for `uv pip install`; since #963 the two steps that
run it
go through `push` when an index is configured, and the `push` stand-in
ran
them for real -- on a computer with a system-wide `pip.conf` the test
installed packages, against the module docstring's promise. The `push`
stand-in now stands in for them too, and the test also runs with an
index
configured, checking both steps are fed it on stdin.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Follow-up commit, after the review of this PR:
- A uv an earlier install fetched under `node_dir/.uv` is used in place
of a
machine uv that would ignore the index. The probe reports that uv on its
own (`NODE_UV`, `NODE_UV_VERSION`) beside the one it found first, and
`plan()` swaps it in when the first is older than 0.4.23 (or silent) and
the fetched one is not; without an index the machine's own uv serves as
before, and one under `node_dir` that is itself too old does not help.
Two
tests failed first: the plan from such a probe (uses the fetched uv, no
`uv` step, 60 MB, no refusal without curl), and the probe under a real
`/bin/sh` reporting both uvs (then the one, then none).
- The machines guide, English and Chinese: the "What lands on the
machine"
row for `uv` names the old-uv case, and the troubleshooting table has a
row
for the sentence an old uv earns. `tests/test_docs_site.py` and
`tests/test_living_docs.py` pass (18), `mkdocs build --strict` passes.
- The docstring of
`test_a_plan_whose_index_port_cannot_be_read_still_describes_itself_and_its_failures`
says the install, not the look, refuses the port. The real install
test's
`uv_version` is pinned to `UV_VERSION` rather than read off this
computer's
uv, so a test host with a uv older than 0.4.23 does not reach astral.sh
through the stand-in that stubs only `pip install`.
- `tests/test_node_install.py` -- 82 passed; with the cli, bundle,
client and
import-cycle files -- 204 passed; `.venv/bin/python -m pytest -n 6` --
31781
passed, 3 failed (the libreoffice and two simulation cases, which fail
the same way on main on this computer); diff coverage against main 100%
(30/30 changed executable lines).
- Real machine (a registered Linux machine; everything under this
check's
own directory, removed after): uv 0.4.22 from uv's release page was put
first on the PATH the check's own runner gives the probe, with an index
configured. Before this commit: the first install passed it over and
fetched uv 0.13.0 under `node_dir` (85 MB planned), and the second look
found 0.4.22 first again, planned to fetch 0.13.0 again (85 MB, an `uv`
step), and with curl and wget taken away was refused with "upgrade uv
there" while 0.13.0 sat under `node_dir`. After: the same first install,
then the second look found the fetched 0.13.0, planned 60 MB with no
`uv`
step, and went ahead without curl or wget.
- `.venv/bin/python -m pytest tests/test_node_install.py` -- 80 passed.
Each
new or changed case failed on main first: with an index configured, the
real install test's packages step really ran `uv pip install` against
the
test's mirror and failed resolving it (now stood in for, both steps fed
the
index on stdin); `plan()` of a machine whose index names a port that is
not
a port now succeeds, `refusal()` gives the sentence, `install()` runs
nothing, and a machine that has this node is found so and pruned; for a
uv
at 0.4.23 and later, older, and silent about its version, with and
without
curl or wget, the plan uses the machine's uv or fetches the pinned one
and
says why, or `refusal()` gives the exact sentence; an old uv still
serves a
machine with no index; under a real `/bin/sh` the probe reports the
version
a stand-in uv prints and nothing for one that prints none.
- `.venv/bin/python -m pytest tests/test_node_install.py
tests/test_cli_ops_connection_commands.py tests/test_node_bundle.py
tests/test_node_client.py tests/test_import_cycle_budget.py -n 6`
-- 202 passed.
- `.venv/bin/python -m pytest -n 6` -- 31780 passed, 3 failed
(`test_rpc_files.py::test_a_host_without_libreoffice_says_so` and the
two
simulation cases, which fail the same way on main on this computer);
diff
coverage against main 100% (26/26 changed executable lines).
- `ruff check`, `ruff format --check`, `ty check raven/node/install.py`
clean; `check_commit_messages.py`, `check_source_language.py` and
`check_large_files.py` on `origin/main..HEAD` clean.
- Real machine (a registered Linux machine whose pip is configured with
an
HTTPS mirror; this check's own node dir, removed after): uv 0.4.22 from
uv's
release page was put where the probe finds a uv, and the install was
given
an index pointed at a port nothing listens on, so whether uv used it
shows.
With main's code the old uv was used and the install succeeded -- uv
went to
PyPI behind the plan. With this change the probe read 0.4.22, the plan
fetched uv 0.13.0 and said why, the packages step failed with
"Connection
refused" (the index was used), and the node dir held uv 0.13.0 after.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The install module's docstring now says an old uv with an index
configured
is passed over; the new `Plan` field and the moved check are documented
where they are. `CONTEXT.md` (the node entry) does not describe uv
versions or
the index and still holds.
## Risk
A machine whose own uv is older than 0.4.23 and whose pip is configured
with
an index now gets the pinned uv fetched under the node dir (about 25 MB,
as
for a machine with no uv), or one sentence asking to upgrade uv when it
has
no curl or wget; every other machine is unchanged. A machine with a bad
port
in pip's configuration can again be told it has the node and be pruned;
an
install there is still refused with the same sentence. The change is to
the
install plan and one probe line; rollback is a plain revert.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Follows the review of #963 (the observations F1, F2 and F3 left on it).
---------
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
`bind_roles_here` writes the four EverOS roles into `os.environ`
directly, records them in `raven_everos.config._BOUND_HERE` and
publishes that record as `RAVEN_EVEROS_BOUND`. `monkeypatch` undoes none
of it: it records only what it changed itself, and `delenv(...,
raising=False)` on a name that is not there records nothing. The everos
backend tests have put the `EVEROS_*` variables back since #489, but not
the record or the set, and the binding is not theirs alone: every
runtime assembled with the memory plugin on binds through the plugin's
start. A run of the whole suite with a watcher on these three things
(2026-10-15) found fourteen files binding -- the design and ppt
launchers, eval hooks, plugin tools, remote file tools, direct chat,
onboarding, the TUI command tests. So one test's binding was the next
test's environment, and which test paid depended on how the suite was
dealt into shards: ten `tests/test_rpc_settings.py` save cases refused
with "decided by the `EVEROS_LLM__*` environment variables" in shard 4/4
of #920 (whose tree predated #489), and nowhere else.
What this does, tests only:
- `tests/_everos_env.py`: `confined_everos_binding()`, a block that puts
the variables (`EVEROS_ROOT` included), the provenance variable and the
contents of the provenance set back when it ends, exception or not; and
`forget_everos_binding(monkeypatch)`, which starts a reader with none of
them and swaps the set rather than clearing it.
- `tests/conftest.py`: one autouse fixture, `_no_leaked_everos_binding`,
around every test, next to the other process-global restores
(`_unbind_the_permission_turn`, `_no_leaked_usage_sink`). It replaces
the everos backend file's own fixture, which covered the variables
alone.
- `tests/test_rpc_settings.py` and `tests/test_config_update_everos.py`:
the two readers of `role_is_env_managed` start with no role of any kind
exported, not only no embedding, through the helper.
- `tests/test_everos_env_confinement.py`: the helper's contract (a
binding made inside the block is undone; what was there before comes
back; so on an exception; the forget half), and one slow test per
representative file that, in a child interpreter started clean and
running under the suite's own conftest, checks that the file leaves no
variable, no record and an empty set behind. Red on the tree before this
change for all three targets (the backend file left the record; the
launcher case left twelve empty role variables, `EVEROS_ROOT` under a
`tmp_path` that is gone, and the record).
The board's own reproduction (the named everos case, then
`tests/test_rpc_settings.py`, one process) does not fail on main any
more because of #489's fixture; it was kept as a check and passes.
Third commit, after review: the block restored the contents of whichever
set the attribute held when it ended. That is the wrong object for a
test that binds and then swaps the attribute with `monkeypatch`, because
`monkeypatch`'s undo runs after an autouse fixture's teardown here
(`_isolate_tracing_state_dir` asks for it and is set up earlier; autouse
fixtures of one conftest are set up in name order): the swapped-in set
got cleaned and the module's own came back with everything bound into it
-- a probe handed the next test twelve keys. No test in the suite binds
before it swaps, so nothing failed, but the helper's docstring claimed
the reverse order. The block now keeps the object it began with and
restores that object's contents and the attribute's binding to it,
whatever the attribute holds by then; the docstring says why, and a test
that binds, swaps with a MonkeyPatch undone only after the block, and
reads a clean set is red before the change.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- A throwaway pytest plugin recording, per test, every change to
`EVEROS_*`, `RAVEN_EVEROS_BOUND` and `_BOUND_HERE`, over the whole suite
(`-n 6`): before this change 63 tests in 16 files changed them (14
binding, 2 clearing); after it, the watcher wrote nothing: no test
changed them (31719 passed, same run).
- `pytest tests/test_everos_env_confinement.py -n 0`: 8 passed, with and
without `CI=1`; the three child-interpreter cases fail on the tree
before this change with the leftovers named above. (The first push had
them print the report after `pytest.main`, which on CI never returns --
the suite's conftest hard-exits the interpreter in `pytest_unconfigure`
when `CI` is set -- so shard 1/4 failed on "the child did not report"
while the targets had passed; `CI=1` reproduces that locally. The child
now writes the report from a `pytest_sessionfinish` plugin into a file
the parent reads.)
- `tests/test_everos_backend.py` 191 passed,
`tests/test_agents_ppt_launcher.py` 61 passed,
`tests/test_rpc_settings.py` 153 passed,
`tests/test_config_update_everos.py` 50 passed, each on its own; the
board's reproduction order 154 passed; the fourteen binding files
followed by every reader in one process, 1261 passed.
- Full suite on the merged tree (`-n 6`): after the third commit, 31720
passed, 173 skipped, 2 xfailed, 3 failed -- the same three that fail on
main on this machine (a LibreOffice case and two simulation cases); the
related group (`test_everos_backend`, `test_rpc_settings`,
`test_config_update_everos`, `test_everos_config`, `test_everos_server`,
the two launcher/eval-hook files) 651 passed.
- `ruff check`/`ruff format`, `scripts/check_source_language.py`,
`scripts/check_large_files.py`, `scripts/check_commit_messages.py`:
pass. No production code changes, so the diff coverage gate has no
changed executable lines to measure.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Tests only. A test that asserted on a binding left by an earlier test
would now see it gone; the full-suite run says none does. Rollback is
reverting the commit.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
The working-directory picker used a loopback URL to decide whether to open
the gateway host's native folder dialog. A headless gateway reached through
VS Code port forwarding, SSH, Docker or WSL can also appear at localhost,
so choosing a folder failed instead of opening the in-page browser.
- The gateway announces `folder-dialog-v1` in `system.hello` when it knows a
native dialog command: macOS and Windows, or Linux with zenity/kdialog on
PATH and `DISPLAY` or `WAYLAND_DISPLAY` set.
- The page offers the native picker only when the gateway announces that
capability and the page is served at a loopback address. Otherwise it
browses the gateway's folders through `fs.dirs`.
- After a reconnect handshake, an open folder menu redraws so its label
follows the new capability list. The staged directory and popover state
are preserved; the label and click action stay in step in both directions.
- Dialog detection lives in a stdlib-only module shared by the handshake
and filesystem handlers, avoiding an import cycle.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Linux, Python 3.12, after rebasing onto current main. Commands below ran
against the final code; build and browser checks used an isolated archive.
- `uv run --no-sync pytest tests/test_rpc_console.py tests/test_rpc_system.py tests/test_import_cycle_budget.py -q -x -n 0 -p no:cacheprovider --basetemp <isolated-directory>`:
233 passed.
- From `ui-web`, `node node_modules/vitest/vitest.mjs run --no-file-parallelism scripts/gates src/app/install.test.ts src/state/workdir.test.ts src/rpc/capabilities.test.ts src/rpc/wsTransport.test.ts src/rpc/fixtureTransport.test.ts src/state/session/registry.test.ts src/state/session/runtime.streams.test.ts`:
54 files, 336 passed, 0 failures or unhandled errors.
- From `ui-web`, `node node_modules/typescript/bin/tsc --noEmit -p tsconfig.json`,
`node node_modules/eslint/bin/eslint.js .` and
`node scripts/gen-rpc-client.mjs --check`: passed; ESLint has 0 errors and
4 existing warnings in unchanged files.
- From `ui-web`, `node node_modules/vite/bin/vite.js build`,
`uv run --no-sync python build.py`, `node scripts/check-page.mjs`,
`node scripts/check-css.mjs` and `node scripts/check-class-namespace.mjs`:
passed, including both boot snapshots.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref HEAD`,
`UV_NO_SYNC=1 make check-large-files check-source-language check-commits`
and `uv run --no-sync lint-imports`: passed; 10 import contracts kept.
- Both new reconnect cases failed before the fix. Removing the redraw or
moving it before the handshake made both cases fail again, without
unhandled errors. The fixed source was restored after each probe.
- Real Chromium against an authenticated, isolated gateway exercised the
actual handshake and filesystem RPC handlers. Headless browsing selected
a folder two levels down; a controlled native-command stand-in returned
the chosen folder. Keeping the menu open across capability loss and gain
updated its label and called `fs.dirs` and `fs.pick_dir`, respectively.
All four scenarios had no page errors. Unrelated RPC answers were fixtures;
interactive macOS/Windows dialogs were not exercised in this run.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Existing wording is reused; no user-facing documentation change is needed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The capability remains an optional string in the existing handshake list;
authentication, directory validation and the RPC schema are unchanged.
Older pages ignore the capability. A newer page with an older gateway uses
the in-page browser. The terminal UI does not consume this capability.
The announcement identifies an available command and, on Linux, a display
environment; it does not verify that a display server is reachable. A remote
desktop reached through a forwarded port can still open its dialog on the
remote screen. Revealing files and opening external applications still use
the existing loopback-address check and are outside this change.
Rollback: revert the squash commit.
## Related Issues
N/A
## Summary
Seven edges of a run on a registered machine, left by the review of #934
and by timing probes on the real machine. Each is a fix the host or the
node makes on its own; nothing changes for an entry without `machine`.
- **A Raven node killed outright no longer leaves agents behind or a
bare `exit -1`.** The next daemon brings every record left at `running`
to `lost` at its start (`Daemon.recover`), ends the agent when its pid
is still the process it was started as (group leader, the recorded
command, and the start mark the launch recorded: Linux's `/proc` start
tick, elsewhere `ps -o lstart`), and writes why; a record without the
mark, or a pid whose mark differs, is left alone and recorded as gone.
`agent/exit` and the attach answer carry that `reason`; the host hands
it on in place of the exit code (`ChannelEndpoint.exited(rc, reason)`),
so a cli run says "the Raven node on this machine was restarted while
the agent ran, and the agent is gone" and a picked-up acp run says the
same. On Linux the agent is also tied to the daemon's life
(`PR_SET_PDEATHSIG`, a SIGTERM). Protocol number unchanged: the field is
optional and old nodes never send it.
- **A failed remote run's error survives a draining-refused announce.**
The manager's two error branches read whether the announce was taken, as
the reply branch does (`announced = taken is not False`), and the acp
backend keeps the record of a prompt that went out and failed, the cli
backend that of a timed-out command, for the caller that reports it. The
next start reads how the task ended off the machine and announces the
error.
- **A cli run picked up after a restart binds its instance to the
session id in its output** (`_bind_picked_up`), as the dispatch's
deferred commit would have; with no id in the output the reply carries
the same "not resumable" warning the dispatch would. A `provisioned` id
or a stateless run binds nothing.
- **A cancel while the machine's link is known dead returns at once.**
`_cancel_turn` reads `ChannelEndpoint.offline` (parked, or the link not
alive), marks the session unsettled and leaves the held `session/cancel`
for the next link, instead of waiting the settle budget for a settlement
that cannot arrive. In the gap before the heartbeat notices nothing
changes.
- **An openai row's tunnel gives up a taken local port for another.**
The port is checked again just before ssh starts (`_still_free`), and
ssh's own "Address already in use" / "Could not request local
forwarding" ends in another try (`_TUNNEL_TRIES` = 3) rather than in a
request sent to whoever took the port; each attempt reads only what ssh
wrote in its own run of the log.
- **A run record that is not JSON, or not UTF-8, is set aside once**
(`<name>.json.unreadable-<ts>`), named in the log that once, instead of
being warned about at every start; a record a later version wrote is
left alone as before. (The first revision read the record as text and
let a `UnicodeDecodeError` out of the whole scan, found by the Windows
review; the record is read as bytes now and decoded by `json.loads`, so
a decoding failure is set aside like a JSON one, and one bad record
never stops the others from being read.)
- **A path written as remote that names no registered machine** is
refused in one sentence for `write_file` and `edit_file` too, never
taken for a relative path here. This has been the case since the debug
switch went (#934); a regression test pins it.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Every fix has a test that failed on the old code first.
- `.venv/bin/python -m pytest -n 6 -q tests/test_node_server.py
tests/test_node_client.py tests/test_remote_runs.py
tests/test_subagent_manager.py tests/test_subagent_cli_remote.py
tests/test_remote_file_tools.py tests/test_subagent_acp_remote.py
tests/test_resume_remote.py tests/test_remote_resume.py
tests/test_subagent_acp.py` - all green on macOS (the Linux-only pact
test skipped there); the last run of the four fast files 331 passed, cli
remote 52, remote file tools 24, the acp remote recovery tests 3
- Full suite: 31577 passed, 234 skipped, 2 xfailed in 6 min 14 s; the 3
failures are the ones `main` has on this machine (a host without
LibreOffice, two simulation records). Changed-line coverage: 98.18% of
165 executable changed lines (`scripts/coverage_gate.py diff --base-ref
origin/main`); the 3 uncovered lines are the Linux-only `prctl` import
block, which CI's Linux shards run.
- `ruff check` / `ruff format --check`, `ty check` on the changed
modules, `lint-imports` (10 contracts kept),
`scripts/check_commit_file.py`, `scripts/check_source_language.py`,
`scripts/check_large_files.py`: clean.
- Real machine (ravenx2, an isolated registry copy and Raven home per
tree; the node of each tree installed under its own `node_dir`; the same
probe script on this branch and on `main`):
| Probe | `main` | this branch |
|---|---|---|
| P1 `kill -9` the daemon under a running cli turn | 4.9 s after the
kill: `CLI agent 'x' exited -1`; the loop the daemon had started was
still running (1 left) | 5.1 s: `CLI agent 'x': the Raven node on this
machine was restarted while the agent ran, and the agent is gone`; 0
left; a new daemon pid |
| P2 an acp prompt that fails after it went out, `reported_by_caller` |
the prompt failed (`exit 5`); no record left | record kept; the next
start announced the error with `exit 5` and removed the record |
| P3 cancel while the link is known dead; the cancel on the next link |
the cancel returned after 2.35-2.46 s, held until the link was back (a 2
s backoff in the probe; up to the 5 s budget in production); it landed
on the next link (task frames 3->4) | 0.00 s; landed the same way (3->4
within 0.1 s of the restore) |
| P4 the chosen local tunnel port is taken by a listener | the tunnel
used the taken port; the request timed out against the listener that
held it | the next port; HTTP 200 through the machine |
| P6 a derived-id cli create left running, picked up by the next start |
picked up ok, no binding (`commits=[]`) | picked up ok, the handle bound
to `edge-123` |
After the merge of `main` (which brought #947's MCP streams, #953's
host-death sweep and #963's install fixes into the same files): the
related groups (node server/client/bridge, remote runs, resume, cli
remote, acp remote, manager, remote file tools, acp client, import-cycle
budget) 1006 passed; diff coverage 97.30% of 185 changed lines (the 5
uncovered are the Linux-only `prctl` lines, run by CI's Linux shards);
the real-machine probes re-run on the merged tree: 8/8 PASS (P1 5.2 s, 0
orphans; P2 record kept and the error announced; P3 0.00 s and the
cancel landed on the next link; P4 the next port, HTTP 200; P6 bound to
`edge-123`).
Docs checked against the code before pushing: CONTEXT.md's Raven node
entry (records of failures, set-aside records, the daemon's recovery and
the `reason`), the module docstrings of `remote.tunnel`,
`remote_runs.pending`, `Daemon.recover`, `_still_ours`, `_death_pact`,
`ChannelEndpoint.exited/offline`, `_bind_picked_up`,
`_track_on_machine`, the `agent/exit` comment in `protocol.py`, and the
CHANGELOG entry.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered - the daemon ends only a pid that is
still the process it started: group leader of its own group, running the
recorded command, and started when the record says (`born`, written at
the launch); a reused pid fails the last mark even for the same program
and is left alone, the record then saying the agent is gone. No new
network surface; the `reason` is the node's fixed sentence, never user
or agent text.
- [x] Backward compatibility considered - `agent/exit`'s `reason` is
optional, protocol number unchanged; a host on this branch reads an old
node's exits as before, an old host ignores the field. Records written
before this branch read unchanged.
- [x] Rollback path is clear for risky changes - a plain revert; nothing
is migrated.
## Related Issues
Follow-up to #934 (the two non-blocking notes of its review) and to the
timing probes run on #921/#922/#934.
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
The web page can now import a Trajectory Export, a Bug Report Package or
a trajectory report and read it as a read-only conversation, transcript
and trajectory both. It is meant for developers reading a bug report
they received, and for looking at a conversation from another machine.
It builds on #948 (export package v1, the trajectory view on by default,
and the conversation menu's availability predicate).
- **Import store** (`raven/trajectory/imported_package.py`,
`imported.py`). Three kinds are accepted: a `raven_trajectory_export` v1
export, a `bug_report_package` v1, and a `raven trajectory report`
tarball. A file that is not gzip is "not a package Raven can import", an
unknown version asks for an update, anything else is "damaged or
unsafe". Packages are unpacked member by member on `package_check`'s
bounded layer, with one budget shared by both layers: 100 MiB per
package, 1 GiB unpacked for an export and 256 MiB for the report kinds,
100k members; traversal, absolute names, backslashes, symlinks, hard
links, devices, FIFOs, sparse members, repeats, directories with data
and oversized extended headers are refused, and every file is created
with `open(..., "xb")`. The package's session record is held to 32 MiB
and 50,000 records before anything reads it (the import and every open
load it whole), or the package is refused as `transcript_too_large`. The
result is normalized into one trace store: export v2 shells stay as they
are, report v1 model inputs become v2 shells that resolve to exactly the
original payload (so long conversations read whole), and a pointer that
maps to nothing in the package becomes null and reads as not recorded.
Each import lives in `<raven home>/imports/<uuid>/` with a `meta.json`
(source file name, import time, title, kind, sha256); it is unpacked
under `.staging/` and renamed into place, removed whole on failure or
cancel, and stale staging is swept at startup. Default titles: an export
takes the original conversation's title or its first user input, a bug
report the first line of its description or its report id, a trajectory
report the original title or its id. One import runs at a time on a
dedicated worker thread that owns the slot; there is no queue, a closed
page does not free the slot early, and gateway shutdown stops and waits
for it.
- **RPC and server-side guard.** New `imported.upload` (base64, under
the same 100 MiB limit as `fs.upload`) answers `imported` or `duplicate`
(by sha256), and imports another copy with `force`. New error codes:
-32029 `imported_read_only`, -32030 `imported_package_invalid`
(`data.reason` carries a stable refusal code), -32031 `imported_busy`.
An Imported Conversation's key is `imported:<uuid>`. `session.list`
appends imported rows when asked for the `imported` channel (never in
the archived list); `session.resume`, `session.title` and
`session.delete` read and write `imports/` directly and never touch the
SessionManager. A dispatcher guard allows only a vetted list of read
methods on an imported key (any of the four session parameter names, or
`channel: imported`) and refuses every other method with -32029,
including methods added later. The SessionManager refuses to save or
fork an imported key and `/file` answers 404 for one, so an imported
conversation never lands in `<workspace>/sessions/`. The trajectory
methods read an import from its own trace store; the indexer registry
gains an LRU cap (four foreign stores), idle eviction covers every
indexer, and deleting an import drops its indexer.
- **Web page.** "Import conversation" in the left menu picks a file and
uploads it; while it runs the button shows the file name and is
disabled, every refusal has its own message, and a repeated package
offers "Open existing" or "Import anyway" (the confirm dialog gains an
optional second action). An "Imported" group below Recent (hidden when
empty) lists the imports with only Rename (inline) and Delete, and the
source file name in the tooltip; search mode matches, and "delete all"
in settings leaves imports alone. An open import is read-only: no input
box (and no transcript mask left behind for it), no title editing in the
header, no Branch, the conversation menu hidden with its slot kept, no
working-directory tag. Sub-agent panes, DAG runs, attachments, delivered
files and generated images show as unavailable without sending requests
the server would refuse; a package without a transcript says so and the
trajectory view still opens; `[REDACTED:...]` placeholders are shown as
they are.
- **Docs and tests.** The webui page (English and Chinese) gains "Import
a conversation"; `CONTEXT.md` (Imported Conversation) and
`ui-web/CONTEXT.md` define the term. Unit tests cover every refusal of
the unpacker, normalization, meta and titles, duplicates and `force`,
runner admission and cleanup, the guard (checked against every
registered method), and the imported branches of `session.*` and
`trajectory.*`; vitest covers the import entry, the rail and the
read-only mode. A new integration test imports packages made by the real
writers into a second raven home and reads them back, and covers
duplicates, rename, delete, refused writes, and damaged or hostile
packages (an oversized upload and a decompression bomb built at the
shipped limits).
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- The branch merges the current `main` (merge commits, no conflicts; the
generated RPC bindings and i18n catalogue still match their sources);
everything below ran on the merged tree unless noted.
- `uv run pytest tests/ -q` (full suite): 10 failed / 31918 passed / 188
skipped. All 10 (proxy environment, IPv6 prefix resolution, node
runtime) also fail on `main` on this machine; none is introduced by this
branch.
- `uv run pytest -m integration
tests/integration/test_imported_conversation_e2e.py
tests/integration/test_web_traj_export_e2e.py
tests/integration/test_web_bugreport_e2e.py -q`: 16 passed.
- Changed-line coverage over the feature's tests (before the merge),
`scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`:
97.75% (955/977).
- `uv run ruff check`, `uv run ruff format --check`, `make
lint-imports`, `make lint-types`: pass.
- ui-web (the merge touches no frontend, i18n or RPC contract file):
`npm run gen:check` (240 methods), `npm run lint`, `npm run type-check`,
`npx vitest run` (248 files / 3923 passed), `npm run build` and `python3
ui-web/build.py` (both boot snapshots match), `check-page.mjs`,
`check-css.mjs`, `check-class-namespace.mjs`: pass.
- ui-tui: `npm run lint`, `npm run lint:rpc`, `npm run lint:i18n`, `npm
run type-check`, `npm test` (144 files / 2111 passed), `npm run build`:
pass.
- `uv run --group docs mkdocs build -f docs-site/mkdocs.yml --strict`:
pass.
- `make check-source-language check-large-files check-commits`: pass.
- Headless Chromium against a real gateway (`raven web --foreground` on
a fresh raven home, at 1280 and 360 px): imported a real export and a
real bug report through the page, opened both read-only, read a
122-message model input to its end in the trajectory view, used both
duplicate choices, renamed and reloaded, deleted, and uploaded a text
file; no page errors. The same flow on the built page with offline
fixtures.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- `imported.upload` takes untrusted archives. The unpacker is bounded
and refuses unsafe members, the guard is an allow-list, and the
SessionManager refuses imported keys as a backstop; the import directory
is under the raven home, which `fs.*` and `/file` already refuse to
serve.
- An export is not redacted, so importing someone else's export gives
you its raw contents; the docs say so.
- Two processes sharing one raven home (for example `raven serve` and
`raven web`) do not see each other's import slot, so importing the same
package in both at once can leave two copies; the extra one can be
deleted.
- Rollback: revert the squash commit. Imported data stays in `<raven
home>/imports/`, which older versions ignore and which can be removed by
hand.
- [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) <noreply@anthropic.com>
## Summary
A page of `read_file` is cut to whole lines within its 128k-character
budget. A file whose first line is over the budget by itself (a minified
script, a one-line JSON, a long CSV row) left nothing within it: the
page came back empty, and its footer said to continue at the very line
it had just not shown, so the reader went round for ever. Measured
before the change: `(Showing lines 1-0 of 1. Use offset=1 to continue.)`
for a single 200k-character line, and `(Showing lines 2-1 of 3. Use
offset=2 to continue.)` once a shorter first line had filled page one.
Such a line is now shown by its head, as much as the budget holds,
followed by a note that says how long the line is, how much of it is
shown, and that `offset` moves by lines and cannot reach the rest:
`grep` tells whether a piece is in it, and a shell command that cuts by
bytes (such as `cut -c`) shows another stretch. The paging footer then
points at the next line, so paging moves on. A first line that just fits
(the line break the budget counts put it over) is shown whole, without a
note. Pages that fit are unchanged.
The node runs the same tool for a file on a registered machine, so the
remote read reads the same; one of the new tests goes through the real
node behind the stand-in ssh.
Raven-Code's `read_file` (the code-flow plugin) cuts every line to 2000
characters. It had its own way round the empty page: whenever trunk
answered with no numbered line it re-read the whole file itself, and
otherwise it cut the lines after trunk had counted the page, so a dozen
10k-character lines filled a page. Trunk's read now offers a hook,
`_cut_line`, applied to each line before the page's budget counts it
(trunk's own is a no-op); the plugin cuts on it, so minified lines share
a page, each cut once, and its whole-file re-read is removed. Its cut
after the read now runs only for a page a registered machine's node
answered (the node runs trunk's tool, without the plugin's hook); a page
read here was cut on the hook and is not looked at again. The first head
told a cut line apart by its ending, so a line whose own text ends like
the mark came back whole (both reviewers reproduced it); whether a line
was cut is now decided by where the read ran, never by its text.
Changed: `raven/agent/tools/filesystem.py` (the trim loop and the hook
in `ReadFileTool`),
`agents/raven-code/plugins/code-flow/code_flow/tools/filesystem.py` (the
plugin's read), tests in `tests/test_filesystem_tools.py`,
`tests/test_remote_file_tools.py` and
`tests/test_agents_code_tools_plugin.py`.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- The six new tests fail on `origin/main` (the four about the page with
the empty pages quoted above; the two about the hook with a dozen lines
per page) and pass after the change: `pytest
tests/test_filesystem_tools.py tests/test_remote_file_tools.py
tests/test_agents_code_tools_plugin.py -k "longer_than_a_page or
just_fills_the_page or going_round or cut_per_line or minified_lines"`.
- Second commit:
`test_a_line_whose_own_text_ends_like_the_mark_is_cut_like_any_other`
fails on the first head (the line comes back whole) and passes now;
`test_a_page_a_registered_machine_s_node_answered_is_cut_after_the_read`
pins the pass after the read for a page a node answered, through a
stand-in pool.
- `pytest tests/test_agents_code_tools_plugin.py
tests/test_filesystem_tools.py tests/test_remote_file_tools.py
tests/test_node_server.py tests/test_read_file_image.py
tests/test_tools_workdir.py tests/test_tool_registry_execute.py -n 4`:
356 passed.
- `scripts/coverage_gate.py diff --base-ref origin/main`: 100% of the 11
changed executable lines.
- `ruff check`, `ruff format --check`, `ty check` on both changed
modules: clean.
- `scripts/check_commit_messages.py`,
`scripts/check_source_language.py`, `scripts/check_large_files.py` over
`origin/main..HEAD`: clean.
- Full suite (`pytest -n 6`), run again at the second commit: 31623
passed, 233 skipped; the 3 failures are the ones main has on this
machine (a LibreOffice-less host, two simulation cases), unrelated to
this change.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (checked
CONTEXT.md, docs-site and the plugin's own text: nothing describes the
page footer or the plugin's cut; both tools' descriptions still hold)
## Risk
- [x] Security impact considered: nothing new is read, and the note
names no path.
- [x] Backward compatibility considered: a page that fits is unchanged,
and the existing paging tests still hold; the hook is a no-op unless a
subclass overrides it. In Raven-Code the page of a file with minified
lines holds more lines than before (the cut lands before the budget) and
the one mark reads as it did.
- [x] Rollback path is clear for risky changes: revert the one commit.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
Three fixes to installing a Raven node on a registered machine
(`raven ops connection install-node`), all in `raven/node/install.py`.
The
first two are nonblocking notes LivXue left on #920; the third is an
older
problem with the version a node names itself by.
- **The index's sign-in stays off every command line.** The probe reads
the
package index pip is configured with on the machine, and the install
handed it to uv as `--default-index <url>` inside the step's command.
pip
takes a sign-in inside that URL (`https://user:password@host/simple`),
and
the command was in this computer's ssh argv, the machine's `sh -c` argv
and
uv's argv; `/proc/<pid>/cmdline` there is readable by every account on
the
machine. The index now travels on the stdin of the two steps that run
`uv pip install` (`packages`, `search`) and is read into
`UV_DEFAULT_INDEX`,
the variable uv reads as `--default-index`; a process's environment is
readable only by its own user. A step that finds no line on stdin fails
rather than install from PyPI behind the owner's back. With no index
configured nothing changes: no stdin, uv's default.
- **A port that is not a port is one sentence, not a traceback.**
`_shown_index`, which drops the sign-in from the URL for every sentence,
read `urlsplit(url).port`, which raises `ValueError` for a port that is
not
a number or is past 65535; `install-node` catches only `InstallError`,
so
the person saw a traceback. The display now cuts the sign-in from the
text
after the authority's last `@` (as `urlsplit` finds it) and never reads
`.port`, and the look at the machine refuses such an index before
anything
is installed: "the package index pip is configured with on machine ...
has
a port that is not a number from 0 to 65535 (<url without sign-in>);
correct index-url in pip's configuration there, or PIP_INDEX_URL". An
empty
port is the scheme's default (RFC 3986) and goes ahead.
- **A node names its own version.** A node runs this code from `lib/`,
not as
an installed distribution, so `importlib.metadata` found no `raven`
there:
`raven.__version__` fell back to `0.0.0+unknown`, and with it the
socket,
lock and pid the daemon keeps under `run/` (`bundle.install_name()`) and
the version the node reports at the handshake, which the machine listing
shows -- while the node's directory is named by the host's version. The
`path` step now also writes a distribution record,
`lib/raven-<version>.dist-info/METADATA`, with the version the directory
is named by, so the node reads the same version and names itself as the
host named it. It sits outside `lib/raven`, so the digest is unchanged.
This needs no change to `raven/node/server.py` or
`raven/node/bundle.py`.
A node installed before this keeps its old names until it is
reinstalled;
any change to the code changes its digest and asks for a reinstall
anyway.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `.venv/bin/python -m pytest tests/test_node_install.py` -- 69 passed.
Each
new or changed case failed on main first (12 failed there): no step
command names the index, its host or its sign-in, and `install()` feeds
the
whole URL as one line on stdin to exactly the `packages` and `search`
steps (the `code` step still gets the tarball); under a real `/bin/sh`
with
a stand-in uv that records its argv and its `UV_DEFAULT_INDEX`, the
packages
step and both tries of the search package (the machine's index, then
beside
the public one) see the index in their environment and never in argv,
and
with nothing on stdin the packages step fails before uv runs;
`_shown_index` drops the sign-in for a port that is not a number, one
past
65535, an `@` inside the password and an IPv6 host, without raising;
`plan()` refuses an index whose port is not a number or is past 65535
with
the exact sentence above and runs nothing after the look, while a
numeric
port, no port and an empty port go ahead; a plan holding such an index
still describes itself and its failures; the `path` step passes the
version the install name begins with; and the one real install on this
computer (a uv virtualenv of this interpreter, this code unpacked into
it)
now has the node report `raven.__version__` and `bundle.install_name()`
equal to this computer's install name under `-I`.
- `.venv/bin/python -m pytest tests/test_node_install.py
tests/test_cli_ops_connection_commands.py tests/test_node_bundle.py
tests/test_node_client.py tests/test_node_server.py
tests/test_node_relay.py tests/test_subagent_acp_remote.py
tests/test_import_cycle_budget.py -n 6`
-- 334 passed.
- `scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`
--
100% (16/16 changed executable lines). `ty check raven/node/install.py`,
`ruff check` and `ruff format --check` clean;
`check_commit_messages.py`,
`check_source_language.py` and `check_large_files.py` on
`origin/main..HEAD` clean.
- `.venv/bin/python -m pytest -n 6` on this tree -- 31716 passed, 172
skipped,
2 xfailed, 3 failed:
`test_rpc_files.py::test_a_host_without_libreoffice_says_so`,
`test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
and
`test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`,
which fail the same way on main on this machine.
- Real machine (a registered Linux machine whose pip is configured with
an
HTTPS mirror, installed into a node directory of this check's own and
removed after): the machine's mirror URL was given a made-up sign-in, a
node
was installed, and the process lines on the machine and on this computer
were sampled every 0.3 s while it ran. With main's code: the sign-in was
in
a process line in 22 of 46 samples, in `sh` and `uv` on the machine and
in
`ssh` here; the node reported version `0.0.0+unknown` at the handshake
and
its `run/` held `0.0.0+unknown-<digest>.lock`, `.pid` and `.sock`. With
this change: 0 of 68 samples; the node installed, answered the handshake
with this code's digest and version `0.2.4`, its `run/` held
`0.2.4-<digest>.*`, and its own `raven.__version__` and install name
matched
its directory. With the index pointed at a port nothing listens on, the
install failed at the `packages` step with "Connection refused" -- uv
took
the index from its environment and did not fall back to PyPI -- and the
sentence held no sign-in. Nothing of this check was left on the machine.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing text changes beyond the new refusal sentence; the
install's
module docstring and the `Plan.index` field say where the index travels
and
what the version record is for. `CONTEXT.md` (the node is installed "in
a
directory named by the code's version and digest") was checked and still
holds.
## Risk
The index now reaches uv only through its environment, which only the
machine user can read; nothing else about the install changes. uv has
read
`UV_DEFAULT_INDEX` since it gained `--default-index`, so a machine's uv
that understood the flag understands the variable. A machine whose pip
configuration names a port that is not a number now gets one sentence
instead of an install that would fail at the packages step. The version
record is a few lines beside the code, outside the digested package, so
a
node of this code reports the same digest. Rollback is a plain revert; a
node
installed with the record keeps working with older code, which does not
read
it.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Follows the nonblocking notes on #920 (the install's package index on
the command line, and the traceback for a port that is not a number).
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
- Every node of a sub-agent DAG ran `exec` on the host however
`tools.sandbox` was configured: `run_dag` grew a `sandbox` seam that no
production caller ever fed, so the `raven_loop` node backend built its
`ExecTool` on `DirectExecutor` -- silently, exactly what
`docs/sandbox/usage.md` promises never happens, on the path most likely
to process untrusted input in parallel (#796).
- The dormant seam becomes a factory. `run_dag`'s parameter is now
`sandbox_factory`, called once per node with the graph's workdir; the
executor enters before the node's backend runs and exits after the
node's bookkeeping, so a node's VM lives exactly as long as the node.
One VM per node is the spawn paths' own rule (manager.py: "each subagent
runs its own sandbox VM"), and the graph's semaphore already bounds how
many boot at once. With no factory handed over, a node backend still
receives `None`, byte-for-byte today's behavior.
- `SubagentManager.sandbox_executor_for(workspace)` is the builder both
dispatch routes share: the one sandbox config, owned-id set, home mount
and sandbox dir a spawn's executor gets. The two inline spawn build
sites now call it too, so the routes cannot drift apart.
`SubAgentDagTool` takes it as `sandbox_for` and bridges it into
`run_dag`; all four construction sites (both wiring, both playbook) pass
the manager's builder.
- Verified on real infrastructure as well as in tests:
`sandbox_executor_for` under `backend: boxlite` starts a VM where `uname
-s` is `Linux` and `pwd` is the mounted `/workspace` (macOS arm64 host,
boxlite 0.9.5) -- the reproduction from the issue, now answering what it
should.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally: `uv run pytest
tests/test_subagent_dag_runner.py tests/test_subagent_dag_core.py
tests/test_subagent_manager.py tests/test_playbook_stint.py
tests/test_subagent_dag_control_tools.py tests/test_subagent_dag_live.py
tests/test_rpc_dag.py tests/test_agent_playbook_delegate.py -q` -> 948
passed; `uv run pytest tests/test_cli_playbook_commands.py
tests/test_harness_curator_hosting.py tests/test_subagent_third_party.py
tests/test_cli_subagent_setup.py -q` -> 408 passed
- [x] New tests failed first: the runner-level factory test raised
`TypeError` (`run_dag() got an unexpected keyword argument
'sandbox_factory'`) and the tool-level test raised `TypeError` on
`sandbox_for` before their implementations landed; the no-factory test
pins today's ladder and passes on both sides
- [x] Relevant lint / type checks pass locally: `ruff check` and `ruff
format --check` on all eight changed files -> clean
- [x] User-facing docs or screenshots are updated when needed: no
user-facing surface changes; the fix makes behavior match what
`docs/sandbox/usage.md` already promises
## Risk
- [x] Security impact considered: this is the security fix -- a
prompt-injected command in a DAG node now runs inside the configured VM
instead of a host shell. The factory only selects between executors the
spawn paths already build; it adds no new privilege
- [x] Backward compatibility considered: no `sandbox_for` handed over
(tests, offline CLI paths, old hosts) leaves every node backend
receiving `executor=None`, exactly as before -- pinned by test; the
`run_dag` parameter rename has no production caller passing the old name
- [x] Rollback path is clear: plain revert; node exec returns to the
host exactly as it was
## Related Issues
Fixes#796
## Summary
Adds MCP lending for remote ACP agents on top of the machine and
recovery
services already merged in #920, #922 and #934. The branch includes
current
main and its default-on registered-machine behavior.
What this does: an acp entry on a registered machine is handed the MCP
servers its row grants, the way an entry on this computer is, and the
servers themselves stay here with their definitions and keys.
- The agent on the machine runs the node's own bridge as a stdio MCP
server (`python -I -m raven.node --mcp --dir <node dir> --task <task>
--lend <dispatch> --server <name>`, `raven/node/bridge.py`): two byte
pumps around a connection to the daemon's socket, no MCP parsed, no
credential held, the standard library only.
- The daemon carries the bridge's frames as a *stream* to the host
holding the task (`mcp/open`, `mcp/frame`, `mcp/close`; protocol 6,
`raven/node/protocol.py`, `raven/node/server.py`). The daemon tells
which
task a bridge is by the process that connected -- the peer pid off the
socket (`SO_PEERCRED` on Linux, `LOCAL_PEERPID` on macOS), walked up the
parent chain to the agent the daemon started, which the bridge is under
and no other task's process is; the kernel supplies that pid and a peer
cannot forge it. `mcp/open` carries only `{task, lend, server}`, and the
task it names must be the one the connection is a process of. Two tasks
on
one machine run as one user, so no name or file a bridge could present
would tell them apart; the connecting process does. One stream per
bridge, at most 16 per task; a frame
travels in pieces of at most 256 KiB characters, the last marked
(`protocol.pieces`), up to the 32 MiB the host's own bridge allows; the
daemon relays and keeps nothing. A stream ends with either end, the
host's link or the task, and the other end is told.
- The host opens the endpoints for a machine row exactly as for a row
here
(`McpEndpoints`: disabled tools withheld on the wire, stdio upstreams in
the host's sandbox, HTTP auth added here), binds them to the machine,
dispatch and acquired agent task
(`NodePool.lend`/`unlend`) before handing out bridge stanzas. On
`mcp/open`
the host checks the daemon-authenticated task against that binding
before
connecting; it rechecks the grant and link after the socket opens. An
unlend, replacement grant or replaced link cannot authorize that pending
connection. The host then pumps the frames both ways
(`raven/node/client.py`).
`node/hello` names the bridge; a node serving without a daemon
(`--stdio`)
names none, and the dispatch then goes without MCP and says so.
- The reply closes with the servers lent and the machine's node, or with
why none were. Remote lending requires Unix-socket support on the host:
on Windows it is withheld before endpoint setup, the task continues, and
the reply explains why. The roster's "injectable MCP" matches that
support
(`session_mcp_delivered`). The cli lane on a machine still
withholds its servers (the next change); the openai lane has no tools.
Not in this change: the cli lane's MCP file on the machine; a stream
that
survives the link going (a bridge sees its server end, the agent reports
the call failed, and the next dispatch works again); MCP for a run
picked
up after this computer restarted (#934): it reports its calls fail.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Follow-up fix 05eaba67a, after the c9de53947 review:
- The nine tests the Windows review named now pin the host fact through
one
fixture, `unix_socket_host` (`tests/conftest.py`), which sets
`raven.mcp.bridge.unix_sockets_available` to true and re-points every
`raven.*` module that imported it by name; their bodies are unchanged.
- Found complete, not just the nine: the whole suite was run with
`asyncio.start_unix_server` and `asyncio.open_unix_connection` deleted
before collection (a pytest plugin, controller and xdist workers), at
the
merge base `6b938a426` and at `c9de53947`, and the two failure sets
compared. 17 node ids failed at the head and not at the base: the nine,
and eight this change added that run the transport for real (the bridge
module, and two lending tests through the stand-in machine). Those eight
are guarded by host capability instead of pinned: the bridge module
skips
when `sys.platform == "win32" or not unix_sockets_available()`, the two
lending tests carry the existing `skipif(not unix_sockets_available())`.
After the fix the same run fails the same 66 node ids at the head as at
the base: nothing this change adds or touches fails on a host without
unix sockets.
- A bridge whose daemon side goes ends as streams end. The host can
close a
stream while a frame of the agent's is on its way; the daemon writes
`mcp/close` and hangs up, and the frame meets the closed socket, or the
read side is reset first. That exited 1 with `BrokenPipeError` or
`ConnectionResetError`; a connection-level end is now exit 0 with
nothing
said, a frame past the cap still exits 1 with its reason, both pumps are
awaited before the socket closes, and a daemon gone before the stream
opens is one sentence, not a traceback. Four deterministic cases with a
stand-in connection fail on `c9de53947` and pass here.
- The bridge test's stand-in agent outlives its bridge, as an agent
outlives
one of its MCP servers, so the later parts of
`test_a_stream_the_host_closes_ends_the_bridge_and_a_bridge_of_no_task_or_of_another_s_never_begins`
no longer race its exit: 1 failure in 80 runs on `c9de53947`, 0 in 80
here.
- The focused set (node, MCP, remote, manager and roster files) -- 935
passed; `.venv/bin/python -m pytest -n 6` -- 31602 passed, 3 failed
(`test_rpc_files.py::test_a_host_without_libreoffice_says_so` and the
two
simulation cases, which fail the same way on main on this computer);
diff coverage against main 97.67% (420/430). Real machine, node
reinstalled with this tree in a directory of the check's own: a stdlib
ACP
agent's bridge reached a host-held server and 1 MiB and 8 MiB results
crossed whole, bridge exit 0; nothing was left on the machine.
Follow-up fix c9de53947, after the same-user token finding:
- The daemon no longer uses a token. `agent/launch` mints and writes
none,
`mcp.token` and the `hmac` check are gone, and `Daemon.open_stream`
identifies the bridge by the connecting process instead (`_peer_pid` +
`Daemon.task_of`). The same-user path the reviewer kept open -- a peer
reading another task's `mcp.token` and opening its stream -- is closed,
because identity is the connection the kernel reports, not a readable
secret.
- Tests, each failing on the unfixed tree first: a bridge placed under
task
B that names task A is refused (`the connection is a process of task
'agent@box-2', not 'agent@box-1'`), as are a process under no task, an
unplaced connection, and a task the daemon does not run
(`tests/test_node_server.py`); a real-OS test launches an agent, takes
its
real child, and asserts the child resolves to the task while the test's
own
process resolves to none (runs on Linux in CI); `_peer_pid` is checked
against a real socketpair; the in-process and subprocess bridge tests
now
identify by the connecting process, and a bridge this test spawns
itself,
or another task's agent spawns, never opens the stream.
- Windows withholding now covers a row on this computer too, not only a
machine row: `session_mcp_delivered` drops the `machine and` guard and
answers no whenever `unix_sockets_available()` is false, so a local acp
row is no longer advertised as injectable and no longer raises at
dispatch
on a host without the transport; `_mcp_endpoints` yields nothing before
opening an endpoint and `_mcp_note` explains it. The two tests the
Windows
review named now guard on `unix_sockets_available()`, and the
withholding
test is parameterized over a machine row and a local row.
- `scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`
over the node/MCP/remote suite -- 97.63% changed-line coverage
(412/422).
`ruff`, `ty` on the changed modules, and the import-cycle budget pass.
- Real machine (ravenx2, this head, node reinstalled, digest
fdbe132e76f0):
a stdlib ACP agent's bridge reached a host-held MCP server and a 1 MiB
and
an 8 MiB tool result crossed whole (`CALL_OK`, bridge exit 0), so the
connecting-process identity admits the legitimate bridge end to end on
real Linux; the cross-task refusal on Linux is the real-OS test above,
which CI runs there.
Earlier review fixes (4dc5b3e1f, the task-to-grant binding). Its
host-side
binding of each dispatch's endpoints to the acquired agent task is kept;
the
daemon-side token this run verified was since replaced by the
connecting-process
identity above (c9de53947), so the token-named tests and reproduction
below no
longer describe the current tree.
- `uv run --no-sync pytest tests/test_node_client.py
tests/test_node_server.py tests/test_node_bridge.py
tests/test_node_relay.py tests/test_node_bundle.py
tests/test_node_install.py tests/test_subagent_acp_remote.py
tests/test_subagent_cli_remote.py tests/test_acp_per_session_mcp.py
tests/test_subagent_acp_mcp_lifecycle.py tests/test_mcp_endpoint.py
tests/test_subagent_mcp_grant.py tests/test_mcp_bridge.py
tests/test_acp_remote.py tests/test_remote_file_tools.py
tests/test_subagent_probe.py tests/test_subagent_acp.py
tests/test_import_cycle_budget.py tests/test_resume_remote.py
tests/test_remote_resume.py tests/test_subagent_manager.py
tests/test_subagent_third_party.py -n 4 --idle-ceiling-strict
--cov=raven --cov-branch --cov-report=json:<coverage-json> --cov-report=
--tb=short` -- 1495 passed and one minimal-node stdio response test
failed;
strict idle accounting also flagged the assembly test. Both cases pass
together under `-n 0 --idle-ceiling-strict` (2 passed). No assertions or
timing limits were weakened. The new authorization, revocation and host
compatibility tests all pass.
- The five focused cases failed on the unfixed implementation first: a
different authenticated task selecting another grant, a stream with no
task, each missing Unix socket API, and an astral Unicode chunk over the
node's byte limit. Regressions also cover revocation, grant replacement
and link replacement while an endpoint connection is opening, and a real
remote turn continuing when both host Unix socket APIs are absent.
- `uv run --no-sync python scripts/coverage_gate.py --coverage-json
<coverage-json> diff --base-ref origin/main --threshold 90`
-- 97.94% (381/389 changed executable lines); this fix alone is 100%
(40/40). Python lint, type, dependency
and import checks pass; all 10 import contracts hold. The scope checks
for commit messages, source language and file sizes pass. Both RPC
generators pass `--check` after integrating current main.
- A real Linux node with two concurrent tasks and a host loopback
endpoint:
before, the attacker's own task token plus the victim's public grant
names returns the victim endpoint's marker; after, it returns no data
and the endpoint is never reached. Its own grant works, unknown and
revoked grants fail, and the same attack remains denied after the relay
is killed and an ordinary ping reattaches both tasks. A full chunk of
262144 astral characters was lost/corrupted before and arrives intact
after. The final documented source tree was reinstalled and checked
again.
- Real ACP dispatch through the node's bridge reaches a host-held stdio
MCP tool and returns its marker; its grant is removed when the turn
ends.
With the host Unix socket APIs removed to simulate Windows, the remote
agent still completes, receives no MCP, explains the host limitation,
and the host MCP ledger records no extra call. This is not a native
Windows run. Dedicated test tasks, host endpoints and bridge processes
are cleaned up.
- CONTEXT.md, module/field docstrings, both collaboration guides, the
external design notes and this description were checked against the
implementation. Main's no-debug-switch behavior and full-turn recovery
documentation are retained.
Full combined-tree verification: `uv run --no-sync pytest -n 4
--tb=short
--cov=raven --cov-branch --cov-report=json:<full-coverage-json>
--cov-report=`
returned 31594 passed, 230 skipped, 2 xfailed and 4 failed. Each failure
reproduces on current main in a separate checkout: host CLI color
rendering,
LibreOffice detection and the two simulation cases. No other test fails.
The minimal-node response test that failed in the focused parallel
selection
passes in this full run. Diff coverage: 97.94% (381/389 executable
changed lines).
Earlier author verification:
- `uv run pytest tests/test_node_bridge.py tests/test_node_server.py
tests/test_node_client.py tests/test_node_relay.py
tests/test_node_bundle.py tests/test_node_install.py
tests/test_subagent_acp_remote.py tests/test_subagent_cli_remote.py
tests/test_acp_per_session_mcp.py
tests/test_subagent_acp_mcp_lifecycle.py tests/test_mcp_endpoint.py
tests/test_subagent_mcp_grant.py tests/test_mcp_bridge.py
tests/test_acp_remote.py tests/test_remote_file_tools.py
tests/test_subagent_probe.py tests/test_subagent_acp.py
tests/test_import_cycle_budget.py tests/test_resume_remote.py
tests/test_remote_resume.py tests/test_subagent_manager.py`
-- 1182 passed. Covered: on the daemon, `node/hello` naming the bridge
and a stdio node naming none, the token written owner-only beside the
record, a stream opened with the task's token and refused with another
or for a task not running, refused with no host holding the task,
refused past 16 per task, one per bridge connection, the pieces of a
frame crossing both ways as they are and a stranger carrying nothing,
and every way a stream ends (the bridge closing, the host closing, the
bridge's connection ending, the host's link ending, the agent ending)
with the other end told; the bridge as a process against a real daemon
over its socket: a frame to the host and one back whole, a large frame
each way in pieces, the agent closing its stdin ending the stream and
the bridge leaving clean, the host closing the stream ending the bridge,
a wrong token and a missing daemon each refused on stderr with exit 1;
the stand-in machine with the real daemon and the real bridge: an acp
stub there that connects to its `mcpServers` and calls a tool reaches a
stdio server here and answers with its result, the stanza handed to it
naming the node's bridge, the task, the dispatch and the server and
nothing of the server's definition or socket, the ledger here showing
one call, no bridge outliving the dispatch; the reply's note and the
roster predicate for a machine row.
- `uv run pytest` on this tree -- 31288 passed, 230 skipped, 2 xfailed,
4 failed:
`test_rpc_files.py::test_a_host_without_libreoffice_says_so`,
`test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`,
`test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`
and
`test_subagent_kimi_code.py::test_an_ask_that_runs_out_takes_what_its_kimi_started`,
which fail
the same way on main on this machine.
- Real machine (a registered Linux machine with Claude Code signed in,
the node reinstalled with the code before and after):
A28, before (the
code of #934's head and its node): the turn closed with "MCP servers
'probe' were not lent", Claude Code said no tool of that name was
connected, and the server here saw no call; after: `PROBE_OK:r2-lend`
in 9.4 s, the server here recorded the call, and the turn closed with
"lent to acp agent ... through the Raven node on machine ...". A34:
after
the turn the machine's process list shows no bridge, a grep of its node
directory finds nothing of the server's command or of this computer's
socket directory, and no endpoint socket is left here. A29: with the
tool switched off here, Claude Code answered UNAVAILABLE and the server
saw no call. A30: a 40 s tool call under way, the bridge visible in the
machine's process list, then cancelled: 3 s later no bridge there and
no socket here. A31: the relay ssh killed during a 20 s call: the turn
ended 4.1 s later with "CALL_FAILED ... Connection closed", and the next
dispatch reached the server again in 7.6 s. A32: five calls in one turn
all reached the server and came back; an 8 MiB answer: the server here
produced it, and a plain ACP agent on the machine (a stdlib stub that
speaks the stanza's bridge directly) received it whole through the node
-- 1 MiB in 1.3 s, 8 MiB in 3.5 s, the bridge exiting 0 -- while Claude
Code itself closed the server on that answer and reported the call
failed: the agent's own cap on a tool result, not the link's.
- `ruff`, the commit-message and PR-body checks -- clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
The English and Chinese collaboration guides describe lending,
task-bound authorization,
Windows withholding, and the existing CLI/restart limitations.
## Risk
Registered-machine support is enabled by configuration, without the
removed
trial environment switch. An ACP entry on a machine receives its granted
MCP servers on a Unix-socket-capable host; the host's normal MCP policy
still
applies. This intentionally exposes those tools to the selected remote
agent.
The server definition, credentials and endpoint paths remain on the
host.
The daemon identifies a bridge's task by the connecting process (the
peer
pid the kernel reports, walked to the agent it started), not by any
token or
name the bridge presents, so a peer task sharing the OS account cannot
open
another task's stream; the host then authorizes that task against the
dispatch/server grant. A system that reports no peer pid opens no
stream.
On Windows hosts remote lending is withheld explicitly, without aborting
the
remote task. Protocol 6 remains the MCP wire version; host and node must
also
have the same code digest, so updated nodes must be reinstalled.
Rollback is
a revert; the machine then carries no stream and receives no bridge
stanza.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#934 (merged); #920 and #922 (merged).
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Codex <noreply@openai.com>
## Summary
Raven-Code and Raven-Research could not be disconnected: the web sheet
and the onboarding rows hid Disconnect for any `vendored` row, and the
TUI filed them as un-added presets ("is only a preset - press Enter to
add it"). The rule keyed on how a row is stored, not on whether it is
the built-in loop, so Raven-Design and Raven-Oncall, which an install
can register as config rows, could be disconnected while the other two
could not.
What changes:
- Web: every row but the built-in loop can be disconnected, from the
sheet and from the onboarding rows. This reverses the rule #751
introduced for the onboarding walk (Raven's shipped specialists were
never disconnected); a reader can now take one of Raven's own agents off
the roster, the way the server already allowed.
- TUI: a discovered agent is filed with the configured agents (`[on
]`/`[off]`, not `[new]`), space switches it, 't' tests it by `source:
"vendored"` (it sent `"preset"`, which the server answers with "no
preset sub-agent"), and Enter opens the edit form (it opened an add
form, which the server refused as an unknown preset).
- Onboarding step: Raven's own agents are grouped and counted by
ownership (`isOwnRow`), not by `vendored`, so a specialist an install
registered as a config row no longer counts as an external agent or
marks the step done.
- Server, switch rows. Measured before this change: after
`subagents.toggle` switched a discovered folder off, `subagents.list`
reported it as `configured: true, vendored: false, own: false`, because
any config row of its name made it a config row, the switch row
included. The TUI then offered a delete, which dropped the switch row
and put the agent back on the roster past the enable gate, and a Test by
`source: "config"` was handed the switch row, whose command is empty. An
edit was written onto the switch row and never reached the table, and a
rename moved the switch off the folder, which also re-enabled the agent.
Now:
- `subagents.list` keeps a switched-off folder discovered. A switch row
is told apart by `_is_switch_row`, the predicate `subagents.toggle`
already uses; a real override (an `install.py` row, a hand edit) still
lists as config.
- `subagents.update` on a folder whose stored row is only the switch
stores the folder's entry with the change and keeps it off, refuses a
rename there, and writes nothing for an edit that changes nothing (a
form saves every field, and a stored copy would outlive the manifest it
was taken from).
- `subagents.remove` of a folder's row that is off leaves the switch row
behind, so the agent stays off; removing a switch row removes nothing;
an override that is on is dropped whole as before.
- `CONTEXT.md` (Discovered agent) and `ui-tui/CONTEXT.md` (Subagents
Overlay) describe the switched-off and edited states.
Existing assertions that encoded the #751 rule were flipped, not
deleted: the onboarding row of a shipped specialist had no control (two
tests), and its sheet offered Test only. They now expect Disconnect.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Measured on `origin/main` 916761ed4; the branch is rebased onto the
current main before it is pushed.
- `uv run --frozen --python 3.12 --all-extras pytest -q` (proxy
variables unset): 31691 passed, 164 skipped, 2 xfailed, 4 failed. The
four are environment-dependent on this box and unrelated to the change:
`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
`test_knowledge_parser_excel.py::test_a_legacy_workbook_is_converted_and_read`,
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(fails as root), and
`test_cli_agent_commands.py::test_an_empty_message_file_is_a_usage_error`
(the CLI's boxed error message is cut short under the longer xdist temp
path). Run on their own with `-n 2`, the same four give 3 failed / 1
passed both on `origin/main` (extracted with `git archive`) and on this
branch.
- The six test files that drive `subagents.update`, `subagents.remove`
or `subagents.toggle`: 590 passed.
- New server tests (8), on a real `agents/` tree: a switched-off folder
still lists as discovered; a written override still lists as config; an
edit while off lands and stays off; a rename while off is refused; an
edit that changes nothing stores nothing, on or off; removing an off
override keeps it off; removing an override that is on drops it whole;
removing a switch row removes nothing. The six that cover new behaviour
were red before their fix; the other two guard what had to stay as it
was. Six single-construct mutants of the server change were each killed
by at least one of them (switch rows ignored by update, the no-op skip
dropped, remove always dropping the row, remove treating a switch row as
an override, an edit while off turning the agent on, remove keeping a
"no" for a row that is on).
- `ui-web`: `npx tsc --noEmit -p tsconfig.json` clean; `npx eslint
src/features/extAgents/` clean; `NODE_OPTIONS=--localstorage-file=<file>
npx vitest run --no-file-parallelism`: 246 files, 3872 tests passed, no
unhandled errors (the second test root under `scripts/gates`, including
the import-direction gate, is part of that run). The wizard grouping and
`isFound` were each reverted on their own, and the new tests went red.
- `ui-tui`: `npx tsc --noEmit -p tsconfig.json` clean; eslint on the
changed files clean; `src/__tests__/subagentsHub.test.tsx` 110 passed.
The full suite (`npx vitest run`): 2092 passed, 13 skipped, 11 failed.
Nine are in four files that fail on this box because the suite resolves
`@hermes/ink` to an older local build that has no `dumpScreen`, and none
of them imports the code this branch changes; the other two (the
`subagentsHub` test "'d' then 'n' does not trap the overlay" and an
`agentsOverlayComposer` steer test) failed under load and pass 5 of 5
when their files run alone.
- The sheet's Disconnect / Connect round trip for Raven-Research was
clicked through in Chrome on the offline stub data; the change was not
driven against a running Raven gateway.
- `ruff check` and `ruff format --check` clean;
`scripts/check_source_language.py`, `scripts/check_large_files.py` and
`scripts/check_commit_messages.py` over `origin/main..HEAD` exit 0, each
beside a control that fails; `commitlint` passes each commit message.
- [x] Relevant tests pass locally (the four Python failures above are
this box's; run alone, they give the same result on `origin/main` as on
this branch)
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
(`CONTEXT.md` and `ui-tui/CONTEXT.md`; no user documentation states the
old rule)
## Risk
- [x] Security impact considered: an edit to a switched-off folder now
stores the folder's entry in the config file. A discovered entry carries
no `env` and no key (checked for the five that ship), and credentials
stay in each folder's own `.env`, so nothing secret is copied.
- [x] Backward compatibility considered: the wire shape is unchanged. A
switched-off folder now lists as `vendored: true, configured: false`,
which is what the `vendored` field description already promised, and
which the web client already draws as a discovered row that is off. Rows
an older install wrote stay readable: a switch row, an override and a
stale definition are all shapes the table merge already handles.
- [x] Rollback path is clear for risky changes: revert the squash
commit. Config rows written meanwhile (switch rows, overrides of a
folder) remain valid for the previous code.
Checked and deliberately left as they are:
- `raven onboard`'s prune of rows that shadow a folder lists a switch
row as one of them, flagged "removing it would re-enable this agent". It
asks first and backs up the list, so this change leaves that flow alone.
- A stored definition whose launcher is gone or whose kind changed still
lists as config, while the table merge uses the folder.
`subagents.toggle` treats it as an override too; separating the two is a
separate change.
- An edit turns a discovered agent's row into an override, so the last
test result, kept per source, is not shown again until the agent is
tested.
- The TUI edit form still lets a discovered agent's name be typed; the
server refuses the rename and the form shows its message.
- `/subagents test <name>` in the TUI always sends `source: "config"`,
so it cannot test a discovered agent; the slash command has only a name
to go on.
- The wire `own` flag is false for a config override of a discovered
folder unless its acp handshake named raven. The web falls back to its
agent catalogue, which names four of the five specialists, so an edited
Raven-PPT may show as an external agent there.
## Related Issues
N/A
## Summary
Follow-ups to the web bug report wizard from #948, after trying it.
- **Decisions page lists the values in full, and only them.** The left
column showed each value masked (`544e***5100`) with its category,
count, decision and links under it. The reader decides on the value
itself, so the list now holds the values and nothing else, each in full
and wrapping rather than cut. `bugreport.status` carries a new `value`
field beside `masked_sample` for each item while the report waits on the
decisions; no other phase carries one. A confirmed item (a private key)
keeps no value of its own, since it is replaced whatever the reader
says, so it shows its replacement. The picked value's category, count,
decision and links, and a confirmed item's acknowledgement, move to the
right column's header; a redacted value is struck through in the list.
- **More room.** The wizard's dialog grows from min(640px, 94vw) x
min(560px, 88vh) to min(960px, 94vw) x min(720px, 90vh), close to the
settings dialog, and the decisions page's two columns fill it instead of
a fixed 360px.
- **Clipped fields.** The severity select and the file name and reporter
fields inherited the page-wide field rule's fixed 32px height and
monospace face, which cut off part of their text. The wizard's sheet now
sizes and sets them.
- **Completeness off the page.** The upload page no longer shows the
completeness verdict. It stays in both JSON files of the report
(`record.json` and the package's `bugreport.json`), for command-line and
web reports alike, and a new test pins that for both paths.
Why some web reports come out `unreplayable` is not addressed here; it
is tracked separately.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/ -q` (full suite): 57 failed / 31566 passed / 177
skipped. The 57 are the same set, one for one, as on the tree #948
merged, where each also fails on `main` (environment-specific on this
machine, pre-existing); none is new.
- `uv run pytest tests/test_rpc_*.py tests/test_trajectory_*.py
tests/test_cli_trajectory_commands.py -q`: 4423 passed.
- `uv run pytest -m integration
tests/integration/test_web_bugreport_e2e.py
tests/integration/test_web_traj_export_e2e.py
tests/integration/test_bug_report_upload_e2e.py -q`: 10 passed.
- `uv run ruff check`, `uv run ruff format --check`, `uv run ty check`
on the changed Python: pass.
- ui-web: `npm run gen:check` (239 methods), `npm run lint`, `npm run
type-check`, `npx vitest run` (246 files / 3869 passed), `npm run build`
and `python3 ui-web/build.py` (both boot snapshots match),
`check-page.mjs`, `check-css.mjs`, `check-class-namespace.mjs`: pass.
- ui-tui: `npm run lint:rpc`, `npm run lint:i18n`: pass.
- `make check-source-language check-large-files check-commits`: pass.
- Headless Chromium on the built page (offline fixtures), at 1440 and
390 px: the dialog is 960 x 720 at 1440 px and 367 x 684 at 390 px; at
both widths the select and both text fields are 38px tall in the body
face at 14px, the decisions list shows only the full values, the right
header shows the facts and the acknowledgement, and both columns stay
inside the dialog.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- `bugreport.status` now sends the values being decided in full while a
report is in the decisions phase. They already reached the page through
`bugreport.item`'s contexts; the status is not polled in that phase,
travels only between the local gateway and its page, and carries no
value in any other phase. A private key is never sent, only its
replacement.
- `BugReportItem` gains a required `value` field. The only client is
this page, regenerated in the same change.
- Rollback: revert 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) <noreply@anthropic.com>
## Summary
On macOS an ACP agent outlives a Raven host that dies without closing it (killed, crashed, OOM-killed). The agent runs in a session of its own, so it gets none of the host's signals, and only `AcpClient.close` ends it. #942 closed this on Linux with a parent-death wrapper and a launch-record sweep. On macOS both were no-ops. This PR brings both layers to macOS.
**1. The agent ends with its host (`raven/acp_client/leftovers.py`, `_DARWIN_BINDING`).** macOS has no `PR_SET_PDEATHSIG`. Instead, the exec wrapper double-forks a small watcher before it execs the agent, then reaps the middle child.
- The watcher is adopted by launchd, so the agent has no child it did not start.
- It stays in the agent's process group, closes every descriptor it inherited (so it holds none of the agent's pipes), and changes to `/`.
- It waits on the host's exit with kqueue (`EVFILT_PROC` / `NOTE_EXIT`), then ends the whole group. An `npx` launcher's grandchild goes with it, which the Linux signal does not reach.
- If the host is already gone when the watch is set, registration fails with `ESRCH`, and that counts as an exit.
- It ends the group only while the agent leads its own group, which every launch does. Any other failure leaves the agent as it would have been.
- `close()` ends the watcher along with the rest of the group.
- Cost: about 4 MiB RSS per launched agent.
**2. The sweep at the next launch runs on macOS.** This is the backstop for when the watcher itself is gone. The decision logic is unchanged; each `/proc` read has a macOS equivalent:
- process start time: `sysctl KERN_PROC_PID` (`kinfo_proc.p_starttime`, in microseconds). It reads any process, including launchd and zombies; `proc_pidinfo` refuses launchd with EPERM.
- group members: `proc_listpids(PROC_PGRP_ONLY)`
- launch mark: `sysctl KERN_PROCARGS2`. EINVAL (gone, zombie, or another user's process) counts as no mark.
- boot identity: `kern.bootsessionuuid` and `kern.boottime`. macOS has no PID namespaces, so the namespace is a fixed value.
macOS hides the environment of its own platform binaries (`/bin/sh`, `/bin/sleep`). Only a group member that is not one can show the mark, such as the agent's node or python process, or the watcher. What cannot be read still leaves a group alone.
**Linux is unchanged.** The Linux wrapper string is byte-identical to main's `_WRAPPER`. `_start_ticks` is renamed to `_start_time`, which now dispatches by platform. `CONTEXT.md` (Leftover agent, Launch mark) is updated to match.
**Windows lifetime handling is provided by #951.** This PR adds the macOS wrapper and sweep; these helpers remain a no-op on Windows.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Before rebasing onto the merged Windows lifetime change, on macOS 26.6.2, arm64, Python 3.12 (project venv):
- `uv run pytest tests/test_acp_leftovers.py tests/test_subagent_host_env.py tests/test_acp_client_teardown.py tests/test_acp_client_launch.py -q -p no:cacheprovider -m "slow or not slow"` -> 117 passed, 9 skipped (Linux-only mechanisms).
- Every other `tests/test_*acp*.py` and `tests/test_*subagent*.py` file, run one file at a time -> all pass except `tests/test_subagent_dag_runner.py`. On this Mac that file hangs at the same two points with this branch and with main's `leftovers.py`:
- after `TestBackgroundRun::test_a_run_that_ignores_cancellation_fails_named_instead_of_hanging_loop_close` fails;
- with that test deselected, after `TestBackgroundRun::test_the_failure_path_reaps_a_subagent_child_left_running` (21 passed in both runs).
It is unrelated to this change; Linux CI covers that file.
- Red/green with a stand-in host (`AcpClient.launch`, then `kill -9` of the host). The stand-in agent ignores SIGTERM, never reads stdin, and starts a child of its own.
- main: 3 s later the agent is alive with ppid 1, and its child is alive.
- this branch: 3 s later both are gone.
- Sweep backstop: kill the watcher, then `kill -9` the host. The agent stays (ppid 1). The next host's launch ends the agent and its child.
- `uv run ruff format --check` and `uv run ruff check` on the changed files -> clean. `make check-source-language` and `make check-large-files` -> clean.
New macOS tests cover:
- a killed host ending the agent and what it started;
- the watcher holding none of the agent's pipes and being the only member left after the agent exits;
- the watcher ending nothing when the agent does not lead its group;
- the exec keeping the agent's pid and argv;
- SIGPIPE and SIGXFSZ reaching the agent at their defaults;
- the start-time, member, environment and boot readers (including an empty argv entry and a platform binary).
Most existing Linux tests now run on macOS too.
After rebasing onto the merged Windows lifetime change, on Linux / Python 3.12:
- The only manual conflict resolution is in `CONTEXT.md`: retain both platform descriptions, scope the record sweep to Linux and macOS, and remove the stale sentence that macOS only has explicit teardown.
- The macOS implementation and its tests are byte-identical to the approved revision. The Windows implementation and its tests are byte-identical to main; the shared client and environment-test logic also match main, with only the macOS comments/docstring added.
- `uv run --no-sync pytest tests/test_acp_leftovers.py tests/test_acp_windows.py tests/test_acp_client_launch.py tests/test_acp_client_teardown.py tests/test_subagent_host_env.py tests/test_subagent_acp.py tests/test_living_docs.py -q -x` -> 468 passed, 10 macOS-only tests skipped.
- `uv run --no-sync ty check raven/acp_client` and `uv run --no-sync lint-imports` -> passed; all 10 import contracts kept.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref HEAD` -> passed for every applicable hook.
- `make check-large-files check-source-language check-commits` with the existing environment and `UV_NO_SYNC=1` -> passed.
Native macOS and Windows tests were not repeated after this documentation-only conflict resolution. The current-head Windows re-review before the rebase reported 65 passed and 79 platform-specific skips.
- [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 macOS an ACP agent is now SIGKILLed with its whole process group when its host exits without closing it. On Linux the parent-death signal ends the direct child; the launch-record sweep handles surviving marked descendants. An agent that relied on outliving its host no longer does.
- Each launched agent on macOS carries one extra idle process (about 4 MiB) in its group until the group is closed or the host exits.
- The sweep only acts on groups recorded by a dead host in the same boot, whose leader start time matches and which still hold a member carrying that host's mark. A recycled pid or group number is left alone.
- Rollback: revert this commit. Record files a macOS host left under `acp-launches/` are then inert, because the sweep is a no-op on macOS again.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#928 (macOS); #951 provides the Windows lifetime handling.
## Summary
A gateway, and the supervisor `raven web` leaves running beside it, held
memory from startup on for things they never use or may never be asked
to use. Two of them are no longer kept, and three are loaded on first
use. On a key-less gateway with a warm home and no terminal, as `raven
web` runs it, PSS 90 seconds after start goes from 257.2 MiB to 211.8
MiB, and the supervisor's from 77.3 MiB to 35.2 MiB. Nothing on the
wire, on disk or in the page changes shape.
- **The supervisor no longer imports the command table** (77.3 to 35.2
MiB). It only restarts its gateway, but it reached its loop through
typer and the table. `raven/cli/entry.py` now hands the argv that `raven
web` and `system.upgrade` start it with, `web --supervise --port N` with
N in ASCII digits, to `serve_commands.supervise_from_argv`, which calls
`_web` with the arguments the `web` command passes; a refusal ends the
process with the code the command would have exited with. Any other argv
is parsed by the table as before. Two process-wide settings stay ahead
of the fast path in the entry point: the TLS switch, as before, and,
moved there from the table's import, the switch of a Windows process's
stdout and stderr to UTF-8 with `PYTHONIOENCODING` set for its children.
The table's own setup, the saved language and the config migration
notices, is skipped with it: the supervisor prints no translated text
and never reads the config.
- **Two tokenizer copies left by litellm's import are freed** (25.3
MiB). `litellm.utils` keeps the dict it parses from the bundled
Anthropic tokenizer beside the string it re-serializes from it, and only
the string is read: the Claude tokenizer is built from it. cl100k's
registered encoding keeps a Python dict of its ranks beside the copy
tiktoken's core encodes with; tiktoken reads the Python one only to
pickle an encoding outside the registry, since a registered one pickles
by name. `import_litellm` now drops the dict, only while the string is
there, and the Python ranks. A failure is logged at debug level and
leaves the import standing.
- **A process whose terminal cannot be asked for its colours finds the
console's host modules on its first console command** (6.2 MiB).
Registering the console feature imported every CLI module to find the
ones that host console commands. `cli_socket.register_cli` now also
accepts a function, run once on the first `console_hosts()`. That covers
a process with no terminal, as the gateway `raven web` detaches has
none, and Windows, SSH, screen or tmux, and CI, which
`_theme._can_probe` rules out. Where the terminal can be asked, as from
`raven tui`, the host modules are still found at registration:
`raven.cli._styles` asks the terminal for its colours as it is imported,
and that question has to come before the Ink screen starts.
- **The RPC models build each validator on first use** (6.0 MiB).
`_Strict`, the base every model in `raven/rpc/models.py` derives from,
sets `defer_build=True`. The reason is a comment rather than the
docstring, because pydantic copies the docstring into the JSON schema.
- **Loading the deck engine's plugin no longer loads python-pptx** (7.9
MiB). `plugins-dist/ppt-engine/raven_ppt/services/state.py` imported the
template service, and with it python-pptx, so a gateway with the plugin
installed held it even with the plugin's config slice off, which is the
default. The service is now imported where a deck is read. With the
slice enabled, python-pptx is still loaded by the check that decks can
be made.
The upgrade regression tests also use the native launcher filename
(`raven.exe` on Windows, `raven` elsewhere), so the complete
relaunch-argv and supervisor-handoff assertions run on both platforms.
This follow-up changes test expectations only.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
The original author's Linux performance and suite measurements below
were recorded before the Windows test-fixture follow-up and rebase. The
seven original patches remain equivalent after rebasing; the Windows
measurements below are from the final tree. No new memory or
live-provider measurements are claimed.
- **Memory:** an isolated gateway with a key-less config and
`memory.backend` null, started without a terminal on an exported copy of
the base commit and of this head, each on its own home warmed by an
earlier start, base and head runs alternating; PSS from
`/proc/self/smaps_rollup` 90 seconds after start. The base read 257.2
MiB and this head 211.8 MiB, each within 0.1 MiB from run to run. The
figure on each change above is what taking that change back out of this
head, alone, puts back; the four add up to the difference. The
supervisor's figures are its PSS under `raven web` started on each tree.
- **Behaviour, base against this head on the same trees:**
- Token ids and counts over the repo's docs, the `raven/agent` sources
and the message catalogs, through raven's two estimators, cl100k
directly and `litellm.token_counter` for Claude, GPT, GLM, DeepSeek and
Gemini model names, with decoding, copying and pickling the encoding:
identical.
- The console: the same host modules, found at registration on the base
and on the first lookup here. On a pseudo-terminal the colour query is
written during registration on both.
- Every model in `raven/rpc/models.py`: validation and serialization
schemas, fields, and the outcome of validating the same probe payloads,
identical. On the base all but eight were built at import, here none.
Sixteen threads using every model for the first time at once: no error,
one set of answers.
- The deck engine's plugin imports without python-pptx here; on the base
it loads it.
- `raven web` end to end: it starts and serves the page; after a SIGKILL
of the gateway the supervisor brings it back on the same port with
`RAVEN_SERVE_PORT_STRICT=1`; `raven web --stop` leaves no process and no
`web.json`; `web.log` carries the same lines, and the gateway's
environment is the same key by key.
- A streamed turn and a tool-calling turn on glm-5.3-flash through a
live config's LiteLLMProvider: the same reply, the same tool call, the
same prompt usage, and the same Raven estimate.
- **New tests, against the base code:** of the 33 new or changed cases,
29 fail there. Four pass there by design: the token counts, a near-miss
argv that goes to the table, a process whose terminal can be asked
finding the host modules at registration, and the streams left alone off
Windows. All 33 pass here.
- **Mutation:** each construct was removed or bent one at a time, with
the backup outside the tree, and each mutant failed the tests written
for it:
- the supervisor: no fast path, `isdigit` as the port check, extra
arguments accepted, a refusal swallowed, every refusal ending with code
1, the port ignored;
- the Windows streams: no switch, the switch after the fast path, no
`PYTHONIOENCODING`, the switch off Windows too, strict errors, no guard
around the switch;
- the tokenizer copies: none freed, the dict dropped without its string,
the string dropped too, the ranks kept (in this process and in a fresh
one), no guard around the freeing;
- the console: the finder run on every lookup, a reset keeping a finder
that never ran, lazy everywhere, eager everywhere (in this process and
in a fresh one), registration importing one of the finder's modules;
- the validators built at import; the template service imported with the
state module.
- **Directly affected and neighbouring files:** `uv run --frozen
--python 3.12 --all-extras pytest -q -p no:cacheprovider
--idle-ceiling-strict` over the seven changed test files and
`tests/test_ppt_engine_state.py`, `tests/test_ppt_engine_prepare.py`,
`tests/test_rpc_console.py`, `tests/test_cli_tui_commands.py`,
`tests/test_cli_gateway_commands.py`,
`tests/test_rpc_contract_shapes.py`, `tests/test_cli_smoke.py`,
`tests/test_updates_upgrade.py` and `tests/test_security_tls.py`. Result
at this head: 1522 passed.
- **Full suite at this head:** `uv run --frozen --python 3.12
--all-extras pytest -q -p no:cacheprovider` (repo addopts: `-n 4`,
integration and e2e deselected; proxy variables unset). Result: 3
failed, 31663 passed, 164 skipped, 2 xfailed. The three are this box's
environment and fail the same way on an exported copy of the base
commit:
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
`tests/test_knowledge_parser_excel.py::test_a_legacy_workbook_is_converted_and_read`
(no LibreOffice) and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(run as root).
- **Exported trees:** the same suite on exported copies of the base
commit and of this head, compared case by case: every case they share
has the same outcome, apart from two timing-sensitive cases that failed
in the base run and pass in this head's run and on repeated runs of both
trees:
`tests/test_subagent_acp.py::test_an_interrupted_first_turn_still_binds_its_session`
and
`tests/test_subagent_cli_remote.py::test_a_cancel_ends_the_agent_s_whole_process_tree_on_the_machine`.
- **Diff coverage:** `uv run --frozen --python 3.12 python
scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`
over the neighbouring run's coverage. Result: 100.00%, 50 of 50
executable changed lines. The gate measures `raven/`;
`tests/test_ppt_engine_*.py` executes both imports moved in the deck
engine.
- **Lint and gates:** `make lint-python lint-imports lint-deps
lint-types check-large-files check-source-language`, and `commitlint
--from origin/main --to HEAD --config commitlint.config.cjs` plus
`scripts/check_commit_messages.py origin/main..HEAD`. Result: all exit
0; import contracts 10 kept, 0 broken.
**Native Windows follow-up (2026-10-15):** Windows 10.0.26300, Python
3.13.12, `PYTHONUTF8=1`, isolated Raven/pytest homes and a dedicated
worktree. Setup: `uv sync --frozen --python 3.13 --all-packages --extra
dev`. Imports were verified against the tested worktree. The same frozen
sync was repeated after the rebase picked up the memory-plugin
dependency update.
- Before the fix, `uv run --frozen --no-sync pytest
tests/test_rpc_system.py -n 0 --tb=short` returned **3 failed, 40
passed**. The gateway-hosted handoff, standalone handoff and dev-flag
regression each expected `raven` where native Windows correctly selected
`raven.exe`.
- After the fix, `uv run --frozen --no-sync pytest
tests/test_rpc_system.py
tests/test_cli_serve_commands.py::TestTheSupervisorStartsWithoutTheCommandTable
tests/test_cli_system_ca.py -n 0 --idle-ceiling-strict --tb=short`
returned **66 passed, 4 skipped**.
- On the final rebased tree, the following command returned **631
passed, 4 skipped**, exit 0 with the idle ceiling enforced. The four
skips require the Linux certificate store; none are counted as Windows
passes. JUnit output paths are omitted from these commands.
```powershell
uv run --frozen --no-sync pytest tests/test_rpc_system.py tests/test_cli_serve_commands.py::TestTheSupervisorStartsWithoutTheCommandTable tests/test_cli_system_ca.py tests/test_litellm_setup.py tests/test_ppt_engine_plugin.py::test_loading_the_plugin_leaves_python_pptx_for_the_first_deck tests/test_ppt_engine_state.py tests/test_rpc_cli_dispatch.py tests/test_rpc_schema_match.py -n 0 --idle-ceiling-strict --tb=short
```
- `uv run --frozen --no-sync ruff check raven evolver agents
plugins-dist tests scripts docs-site` and the matching `ruff format
--check`: passed (2,337 files formatted).
- `uv run --frozen --no-sync lint-imports`: 10 contracts kept. `uv run
--frozen --no-sync ty check raven/cli/_console_feature.py
raven/cli/commands.py raven/cli/entry.py raven/cli/serve_commands.py
raven/providers/litellm_setup.py raven/rpc/cli_socket.py
raven/rpc/models.py
plugins-dist/ppt-engine/raven_ppt/services/state.py`: passed.
- `uv run --frozen --no-sync pre-commit run --from-ref origin/main
--to-ref HEAD`, `node node_modules/@commitlint/cli/cli.js --from
origin/main --to HEAD --config commitlint.config.cjs`, `uv run --frozen
--no-sync python scripts/check_commit_messages.py origin/main..HEAD`,
`uv run --frozen --no-sync python scripts/check_large_files.py
origin/main...HEAD`, `uv run --frozen --no-sync python
scripts/check_source_language.py origin/main...HEAD`, and `git diff
--check origin/main...HEAD`: passed.
The test correction retains the complete executable path, argv,
credentials, delayed shutdown and supervisor-handoff assertions, without
adding a skip. Upgrade spawning and the supervisor loop are substituted
in these tests. No real upgrade or resident restart, live provider call,
Windows memory measurement, full Windows suite or new Linux/macOS run
was performed by this follow-up.
- [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 change, because no command, flag, setting or file
format does.
## Risk
User-visible behaviour changes:
- **The first console command in a process whose terminal cannot be
asked** imports the finder's modules then, once, on the event loop and
under the console's dispatch lock, instead of at startup: about 0.1 to
0.2 seconds on this box. A CLI module that fails to import then fails
each console command, where before it failed the process's startup.
- **Each RPC model builds its validator the first time it is used**, so
a method's first call pays for its own models, and a model whose fields
pydantic cannot build a validator for fails there rather than when
`raven.rpc.models` is imported.
- **An unhandled exception in the supervisor** reaches `web.log` as
Python's plain traceback rather than typer's formatted one.
- **The deck engine's template service is imported at the first deck
read** instead of when the plugin loads. A python-pptx that cannot be
imported therefore no longer stops the plugin from loading: with its
config slice enabled, the check that decks can be made withholds the
deck tools, and the turn hook's note on deck state, which logs an
unreadable state at debug level and goes on, meets the import error
there.
- **Code in the same process that reads the private `_mergeable_ranks`
off the registered cl100k encoding**, as the extension example in
tiktoken's README does, gets an `AttributeError` once raven has imported
litellm. In raven, its plugins and the locked dependencies, only
tiktoken's educational module does.
Left as today:
- **Any other supervisor argv**, for example one typed by hand with
`--port=N` or the flags reordered, goes through the command table and
keeps today's memory.
- **Freeing the tokenizer copies relies on litellm's and tiktoken's
internals.** The tests read each copy where it lives, check in a fresh
interpreter that litellm's own import registers the encoding whose ranks
are freed, and pin the token counts, so a release that moves a copy,
starts reading one or stops registering the encoding fails them.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Rollback is a revert. Nothing written to disk or sent over the wire
changes.
## Related Issues
N/A
## Summary
EverOS 1.4.2 shipped today. It fixes what a memory server that stays up
for
days runs into: a LanceDB index reader leaked file descriptors until
searches
took seconds, an interactive search queued behind the cascade's
background
embedding (vector search p50 46 s under three concurrent writers, 0.60 s
now),
and a cascade pass sent one embedding request per entry instead of one
per
file. The memory plugin's exact pin moves from
`everos[multimodal]==1.4.1` to
`==1.4.2`, and the plugin's own version from `1.4.0` to `1.4.2` -- the
same
number as the EverOS it ships. Both EverOS releases declare the same 36
requirements, so nothing else in the lock follows everos down.
**No adapter change.** Every internal everos symbol the adapter reaches
is
present in 1.4.2 with the same signature, the package layout churn
underneath
included: `infra.persistence.lancedb.tables` became
`infra.persistence.records` and `infra.persistence.backends` became
`lancedb.LanceIndexBackend`, but the adapter imports `episode_repo` and
`agent_skill_repo` from the `lancedb` package, which re-exports both the
way
it did before.
**The derived index repairs itself, once.** 1.4.2 makes a table's
primary key
`(app_id, project_id, id)` rather than `id` alone, and the first full
cascade
pass after the upgrade re-reconciles every indexed markdown file against
the
index, re-embedding only the rows that are missing and recording that it
ran
in `.index/.index_reconcile_version`. A healthy root pays one read pass
and no
embedding; markdown is the source either way and was never affected by
the bug
this fixes. The two roots EverOS says need `everos cascade rebuild` by
hand are
a Milvus derived index and a root where reflection already ran across
projects;
raven writes one project into a LanceDB root and reaches neither, though
a user
who pointed raven at a root of their own might.
**The plugin version now equals the EverOS it pins.** The only precedent
was
plugin `1.2.0` pinning EverOS `1.2.3` and plugin `1.4.0` pinning EverOS
`1.4.1`: the plugin tracked EverOS major.minor and kept its patch for
itself,
and nothing said so anywhere. The result reads as a version one release
behind
the thing it ships, so step 5 of the upgrade SOP now says to hold the
two
equal, and this upgrade skips `1.4.1` to close the gap. That step also
named a
test that no longer exists for the literal assertion
(`test_bundled_shadows_lower_priority_source`); it is
`TestPackageSurface::test_imports_clean`, and the step now lists all
three
files that carry the version rather than the manifest alone.
Recorded in `docs/memory-plugin-architecture.md` section 7.5, which the
upgrade
SOP in section 7.2 asks for.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other (external dependency upgrade)
## Verification
```
uv run --frozen --python 3.12 --all-extras pytest -q \
tests/test_everos_plugin_discovery.py tests/test_everos_backend.py \
tests/test_everos_backend_contract.py tests/test_everos_http_adapter.py \
tests/test_everos_config.py tests/test_everos_server.py \
tests/test_everos_discover.py tests/test_memory_backend_protocol.py \
tests/test_memory_backend_contract.py tests/test_cli_plugin_commands.py \
tests/test_config_update_everos.py tests/test_dependency_constraints.py \
tests/test_release_plugin_list.py tests/test_skill_router_everos_source.py \
tests/test_agent_loop_everos_pipeline.py
-> 567 passed, 1 skipped (the skip is Linux-only inotify)
uv run --frozen --python 3.12 --all-extras pytest -q \
tests/test_everos_plugin_discovery.py tests/test_cli_plugin_commands.py \
tests/test_release_plugin_list.py tests/test_plugin_manifest.py \
tests/test_plugin_discover.py tests/test_everos_discover.py
-> 91 passed (re-run after the plugin version moved to 1.4.2)
make lint-types -> all checks passed
make lint-python lint-imports lint-deps -> clean, 10 import contracts kept
make check-source-language check-large-files COMMIT_RANGE=github/main..HEAD -> clean
```
Against a copy of a real 55 MB store (568 episodes, seven LanceDB
tables)
written under 1.2.x and last served by 1.4.1, booted on a scratch root:
- 1.4.2 opens it with no schema complaint, `/health` answers
`version 1.4.2` with `cascade.healthy true`, and the reconcile pass
writes
`.index/.index_reconcile_version` with no error in 441 log lines.
- The same keyword search (`POST /api/v2/memory/search`, the body the
adapter
sends) returns the same five episode ids in the same order under 1.4.1
and
under 1.4.2; BM25 scores drift in the third decimal, as they did on the
1.2.3 to 1.4.1 move.
- Raven's own `installed_everos_version()` reads 1.4.2, and every
internal
symbol the adapter imports resolves with the signature it had.
- [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 change: memory searches stop queueing behind background
writes,
and a long-lived server stops leaking file descriptors. An existing
index pays
one read pass on the first start after the upgrade.
Rollback is `git revert`. The reconcile pass only re-embeds rows the old
primary key had lost, and `lancedb` does not move, so 1.4.1 reads an
index
1.4.2 has written. The new `.index/.index_reconcile_version` file is
ignored by
1.4.1; a re-upgrade later would skip the pass it records, which is the
intent.
Not exercised here: a Milvus derived index (raven configures LanceDB), a
multi-project root, and a real embedding or LLM round trip (the scratch
root
ran without provider keys, so the checks above are the keyword leg and
the
cascade's own reconcile).
- [x] 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
Windows ACP agents could survive when their Raven host exited without
closing its connections. Each local Windows ACP connection now owns an
unnamed, non-inheritable Job Object with
`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`, so host death and explicit close
end the agent's entire process tree.
A small isolated Python launcher waits for the host to assign the job
before starting the configured agent. Host death before assignment
produces EOF and starts no agent. The launcher releases its copies of
the pipes after spawning, preserving stdout EOF and the agent's exit
status. Separate connections have separate jobs.
This addresses the Windows portion of #928. The macOS portion remains
open. No dependency or configuration changes.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Native Windows 11 build 26300, Python 3.13.12, `PYTHONUTF8=1`.
Production import paths were checked for both the feature and baseline
checkouts.
```text
uv run --frozen --no-sync pytest tests/integration/test_acp_windows_real_process.py -m integration -n 0 -q --tb=short
```
Result: **11 passed**. Covers killed hosts, immediate exit, repeated
close, descendants surviving their launcher, nested jobs, host death
before and after job assignment, independent connections, .cmd shims,
argument/cwd/environment preservation, and stdout EOF. The killed-host
test fails on main with `launcher survived kill` and passes with the
fix.
```text
uv run --frozen --no-sync pytest tests/test_acp_windows.py tests/test_acp_client_teardown.py tests/test_subagent_host_env.py -n 0 -q --tb=short
```
Result: **55 passed**. A coverage run of this selection measured **94%**
for the new module, excluding native binding declarations and error
translation, which the Windows integration tests exercise.
The broader regression command below omits only its JUnit output-file
argument:
```text
uv run --frozen --no-sync pytest tests/test_subagent_acp.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_acp_leftovers.py tests/test_acp_protocol.py tests/test_acp_remote.py tests/test_acp_journal.py tests/test_acp_client_teardown.py tests/test_acp_windows.py tests/test_subagent_host_env.py -n 4 -q --tb=short --idle-ceiling-strict
```
Result: **491 passed, 86 skipped, 38 failed**. Main, without the new
unit-test file: **470 passed, 86 skipped, 38 failed**. The parallel runs
differed in one failing test each; isolated runs reproduced both
assertions on both checkouts. Every feature failure therefore reproduced
on main. These include POSIX socket/permission/shebang assumptions,
newline byte counts, and capability snapshot state. This is not a
full-suite pass or a native Linux/macOS validation.
```text
uv run --frozen --no-sync ruff check raven evolver agents plugins-dist tests scripts docs-site
uv run --frozen --no-sync ruff format --check raven evolver agents plugins-dist tests scripts docs-site
uv run --frozen --no-sync ty check raven/acp_client/client.py raven/acp_client/windows.py
uv run --frozen --no-sync lint-imports
```
All passed: 2,337 files formatted and 10 import contracts kept.
```text
uv run --frozen --no-sync pre-commit run --from-ref origin/main --to-ref HEAD
node node_modules/@commitlint/cli/cli.js --from origin/main --to HEAD --config commitlint.config.cjs
uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
uv run --frozen --no-sync python scripts/check_large_files.py origin/main...HEAD
uv run --frozen --no-sync python scripts/check_source_language.py origin/main...HEAD
git diff --check origin/main...HEAD
```
All applicable checks passed. The Python repository gates were run
directly because `make` is unavailable on this host.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The tests checkbox remains unchecked because of the disclosed baseline
failures. The existing glossary entry was updated; no user-facing
command or setting changed.
## Risk
- Each live Windows ACP connection adds one Python helper process.
- Job setup failure refuses the launch. Missing programs fail before
spawning; an existing program that cannot execute reports its error on
stderr and exits 127 through the helper.
- Job handles are unnamed and non-inheritable; closing one connection
does not end another connection's processes. Setup failure and
cancellation release acquired handles and the subprocess transport.
- Reverting this change restores the previous lifecycle. No persistent
state migration is required.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#928 (Windows portion; macOS remains open)
Co-authored-by: Codex <noreply@openai.com>
## Summary
The web page gains two things a conversation could only get from the
terminal before: exporting the selected turns as a download, and
reporting a problem through the bug report pipeline. The trajectory view
is now on for everyone.
- **Trajectory view without `--dev` (R0).** `raven`, `raven web`, `raven
serve` and `raven gateway` no longer take `--dev`; the trajectory policy
starts enabled. `raven tui --dev` (running the TUI from source) is
unchanged.
- **Turn selection.** From this version each turn's opening user message
records its trace id (the Turn Trace Mark, never sent to the model).
`raven/trajectory/selection.py` lists a session's main-line turns,
closes a selection over the sub-agent and delegated traces it
dispatched, collects their spans, and cuts the session record down to
the selected turns; older records are matched conservatively and an
unmatched turn stays in the trajectory only.
- **Export.** The Trajectory Export package v1 (`schema:
raven_trajectory_export`, `format_version: 1`) is the input contract of
the coming `web-traj-import`; it is defined in `CONTEXT.md` and pinned
by tests. It holds the raw spans, artifacts and v2 message blobs of the
selected traces plus the cut session record, unredacted. Exports run as
background jobs (at most two) and the browser downloads them from the
same-origin `/trajectory/export/download` route with a one-time token.
New RPCs: `trajectory.turns`, `trajectory.export`,
`trajectory.export_status`, `trajectory.export_cancel`.
- **Bug reports.** `freeze_export` is split into staging and finishing
so a report can be prepared from selected turns; the CLI's behaviour is
unchanged. A Report Session holds a web report in the gateway between
page requests: at most two at once, all blocking I/O on worker threads,
a cancel checked after every step (a report cancelled while packaging is
never sent), a failed or uploaded report releases its slot and keeps its
last status for ten minutes, and an idle one is cancelled after thirty
minutes. Seven `bugreport.*` RPCs, the `bugreport-v1` capability
(announced only while the receiver URL is valid), and error codes -32026
/ -32027 / -32028. Every decision made on the web page, defaults and
bulk buttons included, is remembered in the redaction history with `web`
as its source, unlike the CLI's bulk flags.
- **Web page.** A three-dot conversation menu in the header's corner
(the desk launcher moves one slot in) opens the new `export` wizard.
Export: pick turns, name the file under an "unredacted" warning, follow
the job, download once automatically with a link to download again.
Report a problem: pick turns, describe the problem, decide the uncertain
values in two columns (hits highlighted at code points), upload, and get
a receipt. Closing before the upload starts discards the report being
prepared; once the upload starts the report is saved on the machine, a
failure marked retryable offers a retry, and the saved report can be
sent later from the command line by its id. Every answer is checked
against the wizard's epoch and the job or report it was asked about, and
a write step whose answer is lost is settled from the report's status
instead of being sent again. Layouts were measured at 360 and 390 px in
English and Chinese.
- **Docs and tests.** The webui and trajectory-debugging pages (English
and Chinese) describe both flows. Two integration tests drive them end
to end: the export through the real download route, and the bug report
against a real receiver process, including a stopped receiver, a retry,
the redaction history's replay and a cancel at each step.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- The branch merges the current `main` (one merge commit, no conflicts);
everything below ran on the merged tree.
- `uv run pytest tests/ -q` (full suite): 57 failed / 31491 passed / 177
skipped. Every one of the 57 also fails on the current `main` on this
machine (environment-specific, pre-existing); none is introduced by this
branch.
- `uv run pytest -m integration
tests/integration/test_web_traj_export_e2e.py
tests/integration/test_web_bugreport_e2e.py
tests/integration/test_bug_report_upload_e2e.py -q`: 10 passed (three
consecutive runs of the two new files).
- `uv run ruff check`, `uv run ruff format --check`, `uv run ty check`
on the changed Python: pass.
- ui-web: `npm run gen:check` (239 methods), `npm run lint`, `npm run
type-check`, `npx vitest run` (246 files / 3868 passed), `npm run build`
and `python3 ui-web/build.py` (both boot snapshots match),
`check-page.mjs`, `check-css.mjs`, `check-class-namespace.mjs`: pass.
- ui-tui: `npm run lint:rpc`, `npm run lint:i18n`: pass.
- `uv run --group docs mkdocs build -f docs-site/mkdocs.yml --strict`:
pass.
- `make check-source-language check-large-files check-commits`: pass.
- Headless Chromium on the built page (offline fixtures): both flows
walked to the download and to the receipt; the header corner measured in
five layouts (desk panel open and closed, workspace panel open, shell
mode, narrow split) and the wizard at 360 and 390 px in both languages.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- A process started with the old `--dev` flag that runs `system.upgrade`
relaunches itself with `--dev`, which the new version refuses; the user
runs `raven web` once by hand. This was accepted as the cost of dropping
the flag.
- The trajectory view is on by default: each open page calls the light,
in-memory `trajectory.state` every five seconds, and the index is built
only when the view is opened. No switch to turn it off is added here;
the policy keeps a replaceable source for a settings entry later.
- The export is the raw trajectory and may contain secrets. The page
says so in a warning; the download is served only on the same origin,
behind the session guard, by an unguessable one-time token, and no path
ever reaches the page.
- Rollback: revert the squash commit. Nothing is migrated; the
`trace_id` field already written into session records is ignored by
older versions.
- [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) <noreply@anthropic.com>
## Summary
Registered machines are now available without a debug environment
switch.
`RAVEN_DEBUG_MACHINES` previously defaulted to off: it kept
machine-backed
agents out of the dispatch table, refused node/installer access, hid
remote
preset destinations, and treated file paths locally while off. It was a
trial feature gate, not a verbose-logging option. At the owner's
request,
this PR removes the variable and all of those checks. Normal startup and
restart recovery use the configured machine entries; even a leftover
value
of `0` is ignored. Machine registration, SSH authentication, file
permission
prompts, and concurrency limits still apply.
Fourth change in the series that lets a Raven dispatch work to the
machines in its machine registry. #920, #921 (merged through #922) and
#922 are on main; this change stands on main alone now, and the diff is
its own.
What this does: a turn running on a registered machine survives this
computer stopping, and the next start picks it up and reports it.
- While a turn runs on a machine, this computer remembers what the
machine does not know (`raven/acp_client/remote_runs.py`): one
owner-only file per run under `<raven home>/machines/runs/`, with the
machine's registry id, the task id its daemon runs the agent under, the
agent, the session key, the instance handle, the dispatch id, the ACP
session, the id of the prompt whose answer is awaited, the ids this
side has used, how many of the agent's frames were read here, the
agent's answer to `initialize` and the connection's launch key. Kept
current after every frame the connection has dealt with, removed when
the turn ends here. No address is in it.
- When this process stops -- the gateway, `serve`, the TUI, the page
stack -- the
agents on machines stay with their daemons
(`remote.leave_agents_running()` before the drain): a cancelled turn
on a machine sends no `session/cancel`, closing its connection ends the
endpoint only, and the manager leaves the dispatch's record open rather
than finishing it as cancelled. A hard kill or `/restart` leaves the
same record, written as the turn ran.
- At the next start -- the gateway once its generation is bound; the
`serve`, TUI and page stacks once --
`raven/agent/subagent/resume_remote.py`
picks every run up: `task/list` on the machine, `agent/attach` from the
frame last read (`NodePool.attach`), the connection adopted into the
pool with request ids carried on past the other process's
(`AcpConnectionPool.adopt`, `AcpClient.continue_ids_from`), the
prompt's answer awaited (`AcpClient.await_response`), the reply built
as a turn ended here is -- the partial notice when the agent stopped
early, the machine note saying it was picked up after this computer
restarted -- then the dispatch's record finished, the registry row and
the node claim closed, and the result announced into the conversation
that asked, as the manager announces a turn that ended here
(`raven/acp_client/remote_resume.py`). A machine that cannot be asked
keeps its record for a later start; a run the machine no longer has,
one whose agent ended while this computer was away, one whose agent
left the agent table, and one whose turn says nothing are announced as
errors that say so. The adopted agent process serves later dispatches
of its entry, as one started here would.
- Seams: `AcpClient.request(sent=)` hears the id of what goes out;
`ChannelEndpoint.watchers` hear the frames the connection has dealt
with (`consumed`, called by the read loop); `ChannelEndpoint.stays`
reads the leaving flag.
- A cli entry's run on a machine is recorded while it runs (kind `cli`,
no ACP part) and left the same way, the manager reading the dispatch
as left; the entry picks it up (`CliAgentBackend.pick_up`): the daemon
replays the command's whole output from its first line, the exit code
ends it, and the reply closes with the machine note.
- The record carries the task as the model wrote it, and -- once the
manager has read the run as left -- the dispatch's origin and summary
(`remote_runs.annotate`): the announce after a restart names the
instance, node and tool call as the announce here does and quotes the
task as authored, never the rendered prompt on disk; a host killed
outright gets an origin made up from the spawn record and the run.
- The record goes last, once the outcome has reached its conversation:
a conclusion that fails, a stop under it, or an announce the scheduler
refuses (`_announce_result` says so now) leaves the record, its claim
released, for the next start to try again.
- A run that returned here keeps its record the same way, until the
manager's announce of the reply was taken: the manager dispatches with
`reported_by_caller=True`, the backend then leaves the record behind
with the reply instead of removing it as it returns, and the manager
removes it after the announce (`remote_runs.forget_dispatch`) -- or,
when the draining scheduler refused the announce, annotates it with
the dispatch's origin and summary for the next start to report. A host
killed between the agent's answer and the announce therefore still has
the way back to the run. A caller that takes the reply as its own
result (a graph node, a probe, a direct chat) dispatches without the
keyword, and the record goes as it did. The record's frame count stops
at the prompt: the turn's own frames, the chunks before the answer as
much as the answer, are never checkpointed, so a pick-up replays the
turn whole and the reply it reports is complete; a record that had
moved past the answer would have resumed after it and waited forever.
Not in this change: a run from the DAG lane has no spawn record to
finish; it is announced from the origin the manager added to its record
when it was left, or, for a host killed outright, from the run's record
alone. The Tasks page reads the finished record on its next load rather
than live.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Machine availability and restart checks after removing the trial switch:
- New default-behavior regressions were run before the removal: 8
failed,
with the enabled-value control passing. After removal, all 9 passed,
including ACP/CLI recovery through the real AgentRegistry with the
variable absent or set to `0`.
- `uv run --no-sync pytest tests/test_acp_remote.py
tests/test_node_client.py tests/test_node_server.py
tests/test_node_install.py tests/test_ops_remote_path.py
tests/test_permissions_remote_read.py tests/test_remote_file_tools.py
tests/test_deliver_files_tool.py tests/test_raven_config_tool.py
tests/test_rpc_subagents.py tests/test_shell_machine_channel.py
tests/test_subagent_acp_remote.py tests/test_subagent_cli_remote.py
tests/test_resume_remote.py tests/test_remote_resume.py
tests/test_remote_runs.py tests/test_subagent_manager.py
tests/test_cli_tui_commands.py tests/test_rpc_schema_match.py
tests/test_config_schema.py -n 4 --idle-ceiling-strict --cov=raven
--cov-branch --cov-report=json:<coverage-json> --cov-report= --tb=short`
-- 1799 passed on the combined tree, including the latest published
result-retention fix. An earlier run had a missing stdio response in the
minimal-node dependency test and an idle-gate hit; both passed a focused
recheck, and this final complete selection passed with the strict gate.
- `uv run --no-sync python scripts/coverage_gate.py --coverage-json
<coverage-json> diff --base-ref origin/main --threshold 90`
-- 92.92% (656/706 changed executable lines) for this PR; the
gate-removal
commit alone covers 2/2 new executable lines (the remainder deletes
gates
and updates descriptions).
- `UV_NO_SYNC=1 make lint-python lint-imports lint-deps lint-types`, the
commit/source-language/large-file scope gates and `git diff --check`
pass.
Both RPC generators' `--check` runs pass; `npm test --
scripts/gates/fixture-shape.test.mjs`
from `ui-web` passes all five tests.
- Real Linux machine, isolated node installations, separate dispatch and
restart processes: before removal, a task started with the trial switch
on was reported as an absent agent and its recovery record deleted when
restarted without it. After removal, both absent and old `0` settings
recover the full CLI result and read its output file by address. The
absent-variable case kills the relay before host shutdown. The combined
final tree was reinstalled and both scenarios repeated successfully.
- With the variable absent, 12 further timing/boundary probes pass:
early
CLI exit and blank lines, relay loss before heartbeat with normal-call
recovery, tunnel loss, ACP/CLI/OpenAI cancellation during disconnection,
11 launches admitting 8 and refusing 3, occupied tunnel port, and an
unwritable prompt file. Three attachment, POSIX-command and IPv6 checks
also pass; Windows command parsing is simulated, not native Windows.
No test task or tunnel remains; the dedicated node directories are
removed.
- CONTEXT.md, configuration and RPC descriptions, transport/path
docstrings,
both collaboration guides and the owner's design notes were checked
against the code. The guides explain the former trial switch and normal
startup without it. The existing SSH, permission and limit tests
continue
to exercise their checks with no test-only switch setup.
- `env -u RAVEN_DEBUG_MACHINES uv run --no-sync pytest -n 4 --tb=short
--cov=raven --cov-branch --cov-report=json:<full-coverage-json>
--cov-report=`
-- 31345 passed, 230 skipped, 2 xfailed, 5 failed. A separate
current-main
checkout reproduces four failures: CLI color rendering on this host,
LibreOffice detection, and the two simulation cases. The remaining
failure
was the direct-chat test stub rejecting `reported_by_caller` from the
latest result-retention change; the published wrapper fix now forwards
only keywords declared by its fake backend. The full
suite was not rerun for that test-only correction. Final direct-chat and
manager recheck: 277 passed with strict idle accounting. Full-PR
changed-line coverage from this
run is 96.18% (679/706).
Earlier verification:
- `uv run pytest tests/test_remote_runs.py tests/test_remote_resume.py
tests/test_resume_remote.py tests/test_acp_client_resume.py
tests/test_node_client.py tests/test_subagent_acp_remote.py
tests/test_subagent_cli_remote.py tests/test_cli_tui_commands.py
tests/test_subagent_manager.py tests/test_rpc_bootstrap.py
tests/test_cli_gateway_commands.py tests/test_acp_client_launch.py
tests/test_subagent_acp.py tests/test_scope_canon.py
tests/test_l4_entrances.py`
-- all passed (605 passed). Covered: the record written owner-only, kept
current
per frame and per prompt, removed when the turn ends here and kept when
this process leaves; a dispatch left at shutdown neither finished nor
announced by the manager; an endpoint ended while leaving leaves the
agent with the daemon (real daemon); a task picked up from the frame
last read, with the watchers hearing each frame; a pick-up the machine
refuses or cannot carry; an answer awaited for a request another
process sent, ids carried on, no `session/cancel` while leaving; the
reply read off replayed frames with the other sessions' frames
ignored, a turn cut short marked partial, an unreachable machine
keeping the record, a run the machine no longer has, a prompt never
sent, an agent that ended while this computer was away, an answer
waited out, a turn that said nothing, a pick-up beside a live
connection closing its own; the manager-side conclusion: record
finished and announced, an error announced and the record failed, an
unreachable machine keeping the record, an agent off the table, a
failure inside one pick-up not stopping the next, a run with no
conversation, the once-per-process scheduling; a cli run recorded
while it runs and left at shutdown, picked up whole on the real daemon
behind the stand-in ssh, its pick-up's errors said (a non-zero exit, a
machine that no longer has it, a link down, this computer leaving), a
cancel that is not a leave ending the command with no record left; the
TUI's stop saying the agents stay before the cancel and its start
scheduling the pick-up; the record annotated with the dispatch's
origin and summary when the manager reads it as left, the announce
quoting the task as authored and naming instance, node and tool call,
with and without the manager's fields; the record outliving a refused
announce and a failed conclusion, claim released; a cli record read
without an ACP session, an older record read with defaults; the record
moving with the frames before the prompt and not past it, a dispatch's
record forgotten by the manager's id with its claim, the manager
dispatching with `reported_by_caller` and forgetting the record after
an announce that was taken and annotating it after one that was
refused; on the real daemon behind the stand-in ssh, an acp reply and
a cli output returned with the record kept and the host "stopped"
before the announce, the next start reading the same reply again
whole, and a dispatch without the keyword leaving no record. End to end
on the real
daemon behind the stand-in ssh: a turn dispatched, this process
"stopped" the way the gateway stops, the agent still running on the
daemon, then a fresh pick-up reading its answer, finishing the record
and announcing it, with the agent's process the pool's connection
again.
- `uv run pytest` on this tree, at an earlier revision of this change --
29270 passed, 121 skipped, 3 failed:
`test_rpc_files.py::test_a_host_without_libreoffice_says_so`,
`test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
and
`test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`,
which fail the same way on main on this machine; diff coverage of this
change against its base: 97.45% (153 of 157 executable changed lines),
and 94.67% for the four changes against main; `lint-imports` 10 kept,
0 broken; `ty` clean.
- Real machine (a registered Linux machine with Claude Code signed in,
node reinstalled with this tree): process A dispatched a 25 s task,
saw the prompt out after 2.4 s and the record keep up with the frames
(6, then 10), then stopped the way the gateway stops 5.4 s after the
dispatch, leaving the record and the agent running there; process B,
started fresh, found the record and the running task, picked it up
in 2.4 s, announced the agent's reply to the conversation with the
machine note, finished the record, removed the run's record, held the
agent's process as the pool's connection, and closing the pool ended
the agent on the machine. This revision, the cli lane with the code
before and after, the node reinstalled for each: a cli entry
`sh -c 'echo $$ > pid.txt; sleep 20; echo done; cat'` was dispatched
and the host stopped the gateway's way 2.7 s later. Before: no
record, the command left running on the machine, and the next start
found nothing to pick up. After: the record kept with the task as
authored and the manager's origin, the command running on, and the
next start picked it up in 16.8 s (the sleep), announcing `done` and
`hi` with the instance, node and tool call and the machine note. The
same with the link killed before the stop: recorded, left, picked up.
With the machine's daemon ended between the stop and the pick-up, it
ended its groups on its way out, the task's record there said exit
-9, and the pick-up announced that as the run's error in 0.1 s,
leaving nothing on the machine.
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and `scripts/check_large_files.py` on the branch range, `commitlint`,
`ruff` -- all clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
The English and Chinese agent-collaboration guides explain normal
startup,
registered-machine setup and recovery, and the removed trial switch.
## Risk
Configured machine entries are available by default; entries without a
`machine` remain local. A remote-looking file path is resolved against
the
registry even without an environment variable; use an explicit local
path
such as `./a:b` for a local filename containing a colon. A formerly
hidden
machine entry is now available for dispatch, and an old variable set to
`0`
no longer disables it. Stopping Raven no longer cancels a turn
running on a machine; it goes on there until the agent finishes or is
cancelled, and its answer arrives in the conversation after the next
start, as a sub-agent result that triggers a turn. One record per run in
the raven home, owner-only, removed when the run is concluded; a machine
that cannot be reached keeps it, so a run is reported at most once and
never lost quietly. The adopted connection answers requests with ids
past the ones the stopped process used, so a replayed frame resolves
nothing sent after the restart. Rollback is a plain revert; a record
left
behind is then an inert file.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#920 and #922 (merged); #921 was carried by #922.
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Codex <noreply@openai.com>
## Summary
RPC browser-origin checks and URL plaintext checks each implemented the
same loopback IP classification. Both now use
`security.hosts.is_loopback_ip`, which reuses the existing `as_ip`
parser.
The callers retain their name policies: RPC accepts `localhost`
alongside loopback IPs; URL plaintext checks also allow
`localhost.localdomain` and trailing-dot aliases. Origin/Host matching
and malformed-origin refusals remain in the RPC layer. Regression cases
exercise both accepted and refused hosts through the real sign-in
handler.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Linux, Python 3.12.13, with existing dependencies matching the lockfile
for the affected modules and check tools:
```bash
uv run --no-sync pytest tests/test_security_hosts.py tests/test_security_urls.py tests/test_rpc_transport.py tests/test_security_network.py tests/test_security_web_ssrf.py tests/test_browser_policy.py tests/test_market.py tests/test_rpc_skillhub.py tests/test_skill_hub_policy.py tests/test_skill_hub_client.py tests/test_cli_serve_commands.py -q
```
726 passed; one supervisor test timed out waiting for its child to write
the state file. Its isolated rerun passed:
```bash
uv run --no-sync pytest tests/test_cli_serve_commands.py::TestTheSupervisorCleansUpOnTheSignalThatStopsIt::test_sigterm_removes_the_state_file -q -n 0
```
The expanded URL/RPC boundary cases passed before the production
refactor (60 passed). A separate comparison of the original and shared
predicates found no differences across 6,535 host strings and 39,214
origins, including legacy addresses, aliases, mapped IPv6 and malformed
brackets.
These checks passed:
```bash
uv run --no-sync ruff check raven/security/hosts.py raven/security/urls.py raven/rpc/transports/ws.py tests/test_security_hosts.py tests/test_security_urls.py tests/test_rpc_transport.py
uv run --no-sync ruff format --check raven/security/hosts.py raven/security/urls.py raven/rpc/transports/ws.py tests/test_security_hosts.py tests/test_security_urls.py tests/test_rpc_transport.py
uv run --no-sync ty check raven/security raven/rpc/transports
uv run --no-sync lint-imports
uv run --no-sync pre-commit run --files raven/security/hosts.py raven/security/urls.py raven/rpc/transports/ws.py tests/test_security_hosts.py tests/test_security_urls.py tests/test_rpc_transport.py
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing documentation change is needed for this refactor. The
full repository suite and native Windows/macOS runs were not performed.
The supervisor timeout was not compared against an unmodified main
checkout.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The change touches authentication and URL trust predicates. It retains
each caller's local-name rules and the standard library's IP
classification, including acceptance of IPv4-mapped loopback on Python
3.12.13. No DNS resolution, listeners, credentials or configuration are
added. Reverting this refactor restores the previous separate checks
without a data migration.
## Related Issues
#939
## Summary
`SessionManager.save()` lost the turns that follow an undo or a clear
whose own save failed, and brought the cut turn back.
`save()` appends `messages[_persisted_count:]`, and rewrites the file
only while the list is shorter than `_persisted_count`.
`Session.undo_last_turn()` and `Session.clear()` cut the list in memory
and leave the write to their callers. When that write fails, the file
keeps the cut messages and `_persisted_count` keeps its old value. Once
new messages take the list back to that count, the next save appends
past it: the file keeps the cut messages, and the ones that replaced
them are never written. Past the old count, the file ends up holding the
cut messages followed by the tail of the new ones.
Where such a failed save comes from:
- `session.undo` (the TUI's `/undo` and `/retry`) and `session.clear`
save right after the cut and only log a failure.
- `/new` saves after `clear()` and raises on a failure before it
invalidates the session, so the cleared copy stays cached.
So a `/retry` after an undo whose save failed loses the turn it sent
again on the next reload, and the undone turn comes back. The bounded
session cache from #942 read that state as saved too, since its clean
check compares the message count and a fingerprint of the other saved
fields, so such a session could leave the cache and be reloaded from the
stale file.
`Session.truncations` already counts every cut: both methods bump it,
and the episodic annotator reads it for the same reason, since a cut is
invisible to indices once the list has grown back.
`Session._persisted_truncations` holds that count as of the last time
this copy read the file or wrote it successfully. Three readers treat a
difference as unsaved:
- `save()` rewrites the file atomically, however far the list has grown
back.
- The cache's clean check keeps the session cached.
- `flush()`, which `session.close` calls, saves it.
`session.close`'s docstring names the new case. Nothing on the wire or
on disk changes shape.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- **New tests, against the unfixed code:** six of the seven new cases
failed there, each reading back the file as the cut left it, for example
`['q1', 'a1', 'q2', 'a2']` where the retried answer belonged. The
seventh,
`test_once_a_cut_is_on_disk_a_save_keeps_what_another_writer_appended`,
passes there by design: it holds the append path for concurrent writers
once a cut is on disk. All seven pass with the fix.
- **Mutation:** each construct was removed or moved one at a time, with
the backup outside the tree, and each mutant failed the tests written
for it: `save()` ignoring the cut (4 failed), the counter never recorded
(1, the concurrent-writer case), the clean check ignoring the cut (1),
`flush()` ignoring it (1), and the counter recorded before the write
instead of after it (6).
- **Directly affected and neighbouring files:** `uv run --frozen
--python 3.12 --all-extras pytest -q -p no:cacheprovider
--idle-ceiling-strict` over `tests/test_session_manager.py`,
`tests/test_rpc_session.py`, `tests/test_rpc_schema_match.py`,
`tests/test_rpc_session_init_bundle.py`,
`tests/test_rpc_session_naming.py`,
`tests/test_session_{export,project_grouping,title}.py`,
`tests/test_defer_manager.py` and
`tests/test_agent_loop_{episodic_annotate,empty_recovery}.py`. Result at
this head: 1003 passed.
- **Full suite at this head:** `uv run --frozen --python 3.12
--all-extras pytest -q -p no:cacheprovider` (repo addopts: `-n 4`,
integration and e2e deselected). Result: 8 failed, 31091 passed, 164
skipped, 2 xfailed. The failures are this box's environment, none
introduced: five in `tests/test_config_update_providers.py` follow the
shell's proxy variables (that file passes 193 of 193 with them unset),
and
`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
`test_knowledge_parser_excel.py::test_a_legacy_workbook_is_converted_and_read`
(no LibreOffice) and
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(run as root) fail the same way on an exported copy of the base commit.
- **Diff coverage:** the seven executable changed lines in
`raven/session/manager.py` are all executed by
`tests/test_session_manager.py` and `tests/test_rpc_session.py`.
- **Lint and gates:** `make lint-python lint-imports lint-deps
lint-types check-large-files check-source-language check-commits`.
Result: all seven exit 0; import contracts 10 kept, 0 broken.
- [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 change, because no command, flag, setting or file
format does.
## Risk
User-visible behaviour changes:
- **A save after a cut whose own save failed now rewrites the file.** A
rewrite writes this copy's messages only, so turns another process
appended to the same session since this copy last read it are dropped,
as they already are when a cut is saved on the first try. Before this
change that save appended: it kept those turns, and left the cut
messages in place of the new ones.
- **`session.close` writes a pending cut.** `flush()` used to skip a
session whose list was not longer than the saved count.
- **A session with a pending cut stays in the bounded cache** until a
save succeeds. The limit is soft, as it already is for any session with
unsaved changes.
Left as today:
- `session.undo` and `session.clear` still return success when their own
save fails, and only log it. The cut now reaches the disk with the next
successful save, and is lost if the process ends first.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Rollback is a revert. Session files are written in the same format as
before, and the new counter is never written to disk.
## Related Issues
#942 (its Risk section disclosed the cache half of this)
## Summary
A follow-up to #927, which merged before this was pushed. Its test
`test_an_ask_that_runs_out_takes_what_its_kimi_started` cut the Kimi
Code ask's timeout to 0.3s and then read the `worker.pid` its stand-in
`kimi` writes. The timeout runs from the spawn, so wherever the stand-in
starts slower than that, the ask's `finally` ended the process group
before the stand-in had noted its worker, and reading `worker.pid`
raised `FileNotFoundError`. The review on #927 reproduced it
deterministically on macOS; on Linux the stand-in's start crossed 0.3s
here only at low priority beside busy loops.
The test now cancels the ask once the stand-in is up rather than waiting
on the clock: it waits for `ask.pid`, which the stand-in writes only
after noting its worker, checks the worker is alive, cancels, and
asserts the worker went with the group. Cancel and timeout end the ask
through the same `finally`, and the timeout path keeps its own tests in
the file, the 1.0s POSIX one and the Windows-branch one. Test-only: no
production file changes.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
Linux, Python 3.12, on main d106a5c6e:
- `uv run --frozen --python 3.12 --all-extras pytest
tests/test_subagent_kimi_code.py tests/test_subagent_third_party.py -q`:
348 passed.
- The race, forced: with the stand-in made to wait 0.5s before starting
its worker (a scratch edit to `_through_kimi`, not part of this change),
main's test fails with `FileNotFoundError` on `worker.pid`, the failure
reported on #927, and the new test passes.
- Against the fix: making the POSIX branch of `kimi_code._end_tree` kill
the leader alone (`proc.kill()` in place of `os.killpg`) turns the new
test red, and only it (1 failed, 347 passed over the two files).
- `ruff check` and `ruff format --check` on the changed file: clean.
`make lint-types` leaves `tests/` out, so no type check covers this
change.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Test-only. One test is rewritten under a new name; no production file
changes, so reverting the commit is the whole rollback.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#927
## Summary
Third of four changes that let a Raven dispatch work to the machines in
its machine registry. #920 is merged; this branch is opened against main
ahead of #921, so the diff here includes #921's commits as well: review
from "read, write and deliver files on a registered machine by address"
on (the commits before it are #921's, carried here until it merges).
What this does:
- The file tools take a path on a registered machine as it is written
for scp -- `user@host:/path`, or `scp://user@host:port//path` when the
port is not 22 -- and answer it through the machine's daemon
(`raven/agent/tools/remote_files.py`, hooked from `filesystem.py` and
`file_search.py`): `read_file`, `list_dir`, `find` and `grep` run
Raven's own tools there and bring back the answer, so a read of fifty
lines of a large file moves those fifty lines; `write_file` and
`edit_file` write there, with the digest of that agent's own last read
-- the conversation's, or its sub-agent run's -- as the expected
state, so a file changed since it read it is refused and nothing is
written, and another agent's read does not stand in for its own. The
path is resolved against the registry
only, never this computer's ssh config, so one path names one machine
on any computer; one that matches no row is refused, not guessed.
- What is shown back as an address is only what the tool says about
paths -- its errors, its headers and footers, a write's account, a
diff's two header lines; a read's numbered lines, a search's matches
and context, and a diff's body come back as they are, so the model
edits against the bytes the file holds. The shell's refusal of typed
`ssh` to a registered machine (`raven/agent/tools/shell.py`,
`machine_exec.py`) reads the program in any spelling -- a path, a
backslash, and on a Windows host `ssh.exe`, `SSH.EXE` or a whole
`C:\...\ssh.exe`, with the backslashes the shell there keeps and
without the quotes it takes off (a quoted piece and a bare one next to
it making one word), so a quoted destination or port is matched like a
bare one -- and, with the lane on, names the file tools. `scp`, `sftp`
and `rsync` to a registered machine stay what they are on main: a copy
starts nothing there and passes exec's own question like any command,
and the file tools cannot carry a directory, a binary file or a large
one, so the copy stays the route for those. A drive-relative or
extended Windows path (`C:file`, `\\?\C:\...`, UNC) is this
computer's, not a machine nobody registered.
- Permissions (`raven/permissions/`): a path inside the directories
Raven's agents work in on that machine -- its session directory, its
`remoteCwd`, the row's listed `paths` -- is read without asking;
elsewhere a read asks once per machine and directory for the session.
A write there asks wherever it falls, as a write here does, and its
grant is for the one file, apart from any read. The daemon checks the
roots again on the machine, links included.
- `deliver_files` fetches one file by its address, whole and checked,
under a 20 MB cap, into `<workspace>/pulled/<machine>/<key>/<name>`,
the key a digest of the file's path on the machine, so two paths never
share a landing: not two files of one name from two directories, and
not two names this computer's filesystem reads as one (`Report.txt`
and `report.txt`, a trailing dot). The name beside the key is written
as one this computer keeps (a backslash, what Windows reserves in a
name, control characters and the percent sign itself as
percent-codes), and a landing that would not resolve under the
machine's delivery directory is refused before anything is made; a
bigger file is named with its size and read there instead. Only a file
under the directories this Raven's agents work in
on that machine is fetched: the tool asks nothing, and a read some
conversation was allowed is no evidence for this one, so a file
elsewhere is refused and read there instead. Nothing reclaims
`pulled/`: a delivery is opened from its landing for as long as its
record lasts, and a bound by size or age is left out of this change on
purpose.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_remote_file_tools.py
tests/test_permissions_remote_read.py tests/test_deliver_files_tool.py
tests/test_shell_machine_channel.py tests/test_ops_remote_path.py
tests/test_permissions_gate.py tests/test_import_cycle_budget.py
tests/test_node_server.py tests/test_node_client.py
tests/test_subagent_acp_remote.py tests/test_acp_remote.py
tests/test_cli_ops_connection_commands.py`
-- all passed on this tree (703 in the run that covered the first
eight groups, the node's own suite and the real-node cases among them).
Covered: each tool on a remote path answers as its local tool would,
through a stood-in link and a real daemon; a path outside the roots is
refused on both sides; a write with a stale digest is refused and
writes nothing; the address form on what the tool says about paths,
and a read's lines, a grep's matches and a diff's body untouched; the
shell's refusal of typed ssh to a registered machine, by host, by
alias, in a pipeline, as `ssh.exe` and `SSH.EXE`, and with a whole
Windows path or a quoted destination or port when the host is Windows,
a copy with scp, sftp or rsync not refused, and the file tools named
only with the lane on; a fetched name holding the
other platform's separators lands as one name under the machine's
directory and nothing lands elsewhere, and a landing that would
resolve outside fetches nothing; a Windows path form read here with the
lane on; the read
permission inside the roots and the question elsewhere, remembered per
machine and directory, a write asked wherever it falls and its grant
kept per file and apart from a read; a read's digest kept per agent,
so another agent's read lets no stale overwrite through and an agent
that never read the file expects nothing; a delivery fetched whole
under a key of its path (two files of one name, two names a
filesystem reads as one, and the percent-code pair all land apart),
refused over the cap and refused outside the roots whatever was read
before.
- `uv run pytest` on this tree after the merge with main -- 31210
passed,
231 skipped, 2 xfailed, 4 failed, every one of the four in a test that
needs what this machine lacks (`test_rpc_files.py`, the two simulation
cases and the kimi-code case that fail the same way on main here); the
groups above also pass under `--idle-ceiling-strict`, CI's idle ceiling.
- Diff coverage of this change against main after the merge: 95.27% (805
of
845 executable changed lines), against the 90% gate. The node suite,
the remote-path tests and the real-node cases among the groups above run
on the merged tree.
- Real machines (two registered Linux machines): fifty lines from the
middle of a 5 MB file read through the daemon in 30 to 35 ms, byte for
byte what this computer reads; list, find and grep answered; a write
and an edit landed as the local tools would, and a write after the file
changed was refused; a path outside the roots refused; a file written
by an agent there fetched back by address. The shell's refusals are
covered by the tests above.
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and `scripts/check_large_files.py` on the branch range, `commitlint`,
`ruff` -- all clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
User docs follow once the lane is no longer debug-only.
## Risk
Behind the debug lane, as the two changes before it. With it on, a
remote
path reaches the machine only through its daemon, inside the roots each
call names and under the read and write questions above; the shell
cannot
run a command on a registered machine by address, and a copy to or from
it
with scp, sftp or rsync is the plain shell's behind exec's own question,
as
on main. A write refused for a stale
digest writes nothing. A delivery fetches at most 20 MB per file into
the
workspace, and only from the directories the agents work in on the
machine. Rollback is a plain revert.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#920 (merged); depends on #921.
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
Follow-ups to the review threads left on four merged pull requests:
#909, #912, #915 and #923. Each is a defect the review named, reproduced
before any change, and repaired with a test that fails against the old
code. This also addresses the Ollama spelling issue raised in this PR's
review.
**A cache-only window lookup no longer skips a model LiteLLM answers
from its table** (from #909). The gate that keeps metadata lookups off a
model's own server skipped `get_model_info` for any id carrying an
Ollama segment, including ids LiteLLM answers offline: `ollama/Llama3`,
`litellm_proxy/ollama/llama3` and `github/ollama/llama3` were sized on
the 200000-token fallback where main read 8192. The gate now puts
LiteLLM's own precondition to LiteLLM, keyed on the caller's id, and
answers cautiously only for an id with an Ollama segment when the
installed release does not ship that check.
**A window the model's own server reported is reused inside the turn**
(the second item of #909). A caller allowed to fetch resolved a local
model's window by asking its server and threw the answer away; the next
caller, which may not fetch, answered the fallback for the same model on
every iteration, for the life of the process. The answer is now kept
under the id the request goes out under, so `ollama/`, `ollama_chat/`
and the stored `ollama-chat/` spelling share one entry. The table is
consulted before the memo, so a row LiteLLM ships still outranks a
previous ask; only a real figure is stored, so a server that was down is
asked again.
**A measurement taken while the boot verify ran is no longer
overwritten** (from #915). The boot read a row before its handshake and
wrote its verdict from that read, so a Test recorded during the
handshake was replaced by a late timeout, refusal or pass. It reads the
row again immediately before the write and leaves a newer measurement in
place. The comparison is on `measured_at_ms`, so a modes relearn does
not stop the write. Four docstrings that described the replaced rule are
corrected.
**The Windows environment capture's memo is pinned, and its docstring
names the second failure mode** (from #912).
**A key is written under the spelling the loaders read** (from #923).
Below the top level pydantic reads the camelCase alias whenever it is
present, null or not, so preferring a non-null spelling sent a write to
a key the schema ignores, and `load_config` and the live readers then
disagreed. Only the top level drops a null block; below it the first
spelling present is the one read, and every caller now states which case
it is in.
**A write aimed at a wildcard map entry reaches that entry** (the
follow-up #923's review asked for). Below the top level the spelling
helper fell back to another spelling of a key, which is right for a
schema field and wrong for a map entry: with only
`tools.mcpServers.fooBar` present, a write to
`tools.mcpServers.foo_bar.enabled` selected `fooBar`, disabling a server
the caller never named. The catalog knows which segments a path binds,
so a bound segment is now matched as written. `providers` keeps the
tolerant rule, because its runtime reader folds those spellings through
`names_same_provider`.
**Configured Ollama models reach the metadata driver under its accepted
spelling.** The wizard and model picker store Ollama ids as
`ollama-chat/<model>`, while LiteLLM expects `ollama_chat/`. The window
and output-ceiling lookups now translate that endpoint prefix using the
provider registry before consulting the candidate list. The memo and
no-fetch prefilters use the same registry normalization. The `ollama/`
completion prefix is preserved because LiteLLM keys its offline table
rows under it; non-Ollama prefixes are unchanged.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Latest review fix (Linux, Python 3.12.13, LiteLLM 1.85.0; proxy
variables unset; consumer tests rechecked after rebase onto current
main):
- New and strengthened regression cases ran before the fix: 6 failed /
108 passed, covering the memo spelling, both no-fetch metadata lookups,
the conservative guard fallback, and an id produced by `stored_model_id`
that could not reach the daemon.
- `uv run --no-sync pytest tests/test_provider_rates.py -q -n 0
--tb=short`: 114 passed after the fix.
- `uv run --no-sync pytest -q --tb=short <consumer-test-files>
--cov=raven.providers.rates --cov-branch
--cov-report=json:<coverage-json>`: 1312 passed, 1 skipped. The
selection contains 16 test modules importing `raven.providers.rates`,
plus `test_provider_registry_lookup.py` and
`test_provider_wire_model.py`. The skip is the permission test that
cannot deny a root process with `chmod 000`; existing Pydantic warnings
remain.
- Applying the repository's `parse_changed_lines` and
`calculate_diff_coverage` to the fix commit after rebase yields 100%
(13/13 executable changed lines). This is coverage of this fix, not a
new full-PR coverage or full-suite ratchet result.
- Six independent in-memory mutants were caught: raw memo prefilter, raw
endpoint guard, raw shared predicate, omitted window spelling
conversion, omitted ceiling spelling conversion, and replacing only the
endpoint conversion with `wire_model` (which loses the `ollama/` table
rows). The worktree was not rewritten by the mutation checks.
- `UV_NO_SYNC=1 make lint-python lint-imports lint-deps lint-types`:
passed after rebase; 2268 Python files formatted, 10 import contracts
kept, no dependency issues. Both commit-message validators and the
source-language and large-file gates also passed. `uv run --no-sync ty
check raven/providers/rates.py tests/test_provider_rates.py` also
passed.
- Against a loopback stand-in daemon, the actual stored
`ollama-chat/qwen2.5` id makes no request in cache-only mode before a
fetch. One allowed `/api/show` request learns 8192, after which the
cache-only lookup and `ModelBinding.context_window` both return 8192
without another request, and the output limit is 4096.
- The daemon-path parameter cases clear LiteLLM's own id-keyed cache so
alias cases cannot inherit a previous case's successful response.
Earlier author verification, before this review fix:
Commands recorded at the original PR revision and main baseline, with
proxy variables unset:
```
uv run --frozen --python 3.12 --all-extras pytest -n 4 -q
```
3 failed, 29796 passed, 158 skipped, 2 xfailed. A same-day run of the
original main control gives the same 3 failed with 29771 passed, so the
failure set is identical and the 25 extra passes are the tests added
here. The three are environment-local:
`test_resolve_node_dir_answers_each_case_it_exists_for` (npm on PATH),
`test_a_legacy_workbook_is_converted_and_read` (LibreOffice), and
`test_what_cannot_be_read_names_nothing` (load-dependent).
Focused runs on the changed files:
- `tests/test_provider_rates.py` 110 passed
- `tests/test_config_self_surface.py` `tests/test_rpc_settings.py`
`tests/test_config_update.py` `tests/test_raven_config_tool.py`
`tests/test_rpc_console.py` 805 passed
- `tests/test_subagent_host_env.py` 30 passed
Gates: `ruff check`, `ruff format --check`, `ty check`, `lint-imports`,
`deptry`, `scripts/check_commit_messages.py origin/main..HEAD`,
`scripts/check_source_language.py origin/main..HEAD` and
`scripts/check_large_files.py origin/main..HEAD` all pass. `pre-commit
run --all-files` fails two hooks on three files this branch does not
touch; the same three fail the same way at the base, so they are
pre-existing.
Every new test was checked by reverting the fix: six single-construct
mutants over the two repaired rules, each restored and compared after
running. Two survived the first pass and both were findings rather than
tests to tighten. The guard that refused a zeroed window was unreachable
(the one caller already has a window), so the parameter is required
instead of optional. And the memo originally ranked above LiteLLM's own
table, so a previous ask could have overridden a row a caller could have
read offline; the table now comes first.
Reproduced end to end against a stand-in server on a loopback port: one
`/api/show` request answers 8192, `ollama/qwen2.5` read with
`allow_fetch=False` answers 8192 with no second request, and
`ModelBinding.context_window` on that model answers 8192 where it read
the fallback before.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No stored config changes shape or meaning. The alias-spelling fix
changes where a write lands when a file carries both spellings of one
key, which is the file that did not load correctly before. The wildcard
fix changes where a write lands when two map entries differ only by
spelling; both are left as written, where the old code silently edited
the neighbour.
The window memo is process-wide and holds context-window and optional
output-limit counts per model, cleared by the same
`reset_openrouter_cache` the catalogue uses. Stored `ollama-chat/` ids
can now make a metadata request to the configured daemon when fetch is
allowed; cache-only callers continue to reuse local data. Other
hyphenated provider prefixes are outside this fix. Roll back by
reverting the merged change; the memo is not persisted.
## Related Issues
#909, #912, #915, #923