## 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
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
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
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
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
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
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
Adds `everos-cloud-memory`, a separately distributed memory plugin for
EverOS Cloud, and wires the host so a second memory plugin is a
first-class choice.
The plugin (`plugins-dist/everos-cloud-memory`) is a thin REST client
over httpx: one API key (the config slice
`plugins.config.everos-cloud-memory.api_key`, or
`EVEROS_CLOUD_API_KEY`), owner ids from the host's `ServiceLocator`
(never from the slice), every add in `agent` mode, and a flush only when
a caller marks the conversation over (`metadata.flush` /
`metadata.is_final`: the sub-agent handoff and the importer's final
batch) and once at stop. It ships its own onboard screen (env or on-file
key used without a prompt; 401 / 403 / unreachable get their own
sentences with Re-enter or Skip), `delete` answers False (the cloud
deletes by scope, nothing calls it), and `health()` classifies seven
answers for `raven doctor` and the settings card.
Host changes, each guarded so `memory.backend` `everos` and `null`
behave exactly as before:
- `raven onboard` step 4 asks "Which memory backend?" when more than one
plugin contributes a screen (preselects the current backend, `Off`
clears it, cancel exits 1 and writes nothing); with one plugin the step
is byte-identical to today.
- The memory page reads whichever backend `memory.backend` names: the
cloud slice's key goes out as a Bearer header and the `/health` probe is
skipped for the cloud; a missing distribution is named in the page's
note.
- `settings.everos` reports `reason: "other_backend"` for any non-EverOS
backend, so the Model page hides the three EverOS-only roles (embedding
stays: knowledge bases use that pin); `settings.everosSet` refuses those
three sections for another backend; `settings.set` admits
`plugins.config.<id>.<field>` against the plugin's manifest through the
same admission door channels use; new `settings.everosCloud` feeds the
card (key source, endpoint, health).
- Provider-key and main-model saves no longer restart the local EverOS
when another backend is active.
- ui-web: an EverOS Cloud card (status chip, key row, endpoint) and the
`settings.everosCloud` data behind it. No page mounts the card: it drew
on Model settings until the owner ruled that a memory backend's endpoint
and credential answer neither question that page asks, and where it
belongs is the Memory section's to say once that section has a design.
Until then the key is entered through `raven onboard` or
`EVEROS_CLOUD_API_KEY`. The fixture gate pins the four optional fields
the offline library never sends.
- Gates: the plugin boundary test scans both memory plugins, coverage
and the release workflow build the second wheel, deptry's ignore list
names the plugin beside `raven_everos`, and a conftest fixture keeps the
second plugin out of entry-point discovery for the existing onboarding
tests (they describe a one-plugin install).
A second topic rides along, because it is what makes the hosted backend
reachable from an agent product at all. Every product under `agents/`
pinned its memory at the stock EverOS address and only `raven-design`
read the host's, so the other four addressed whatever answered on 18791
-- the wizard moves a managed server when the port is taken, and a
server the user runs themselves is wherever they put it.
`inherit_memory_backend` in `raven/config/product_render.py` now carries
`memory.backend`, the endpoint, and (only when the product holds none
itself) the credential from the host into every render, beside the host
denials and plugin opt-outs that already travel there; `raven-design`'s
private copy is deleted and the five product configs stop naming an
address. Identity never travels, which is what keeps five products apart
inside one store. `memory.backend: null` travels like any other value,
because that null is how an operator turns long-term memory off and a
product that kept writing would be the one surface ignoring them; the
product's own default stands only when the host carries no key at all.
Which store memories live in is not a product's choice either: the host
reads a sub-agent's memories back through its own backend, so a product
writing anywhere else left that record empty with nothing reporting it.
`owned` is forced off whenever the local backend is in force, because a
product infers ownership from a slice naming no root -- the shape all
five ship -- and so answered a host that was merely not serving by
starting a second server against a root of its own, stranding every
memory written so far.
Decisions worth a reviewer's eye: the fake cloud
(`tests/_everos_cloud_fake.py`) honours or refuses every field the
backend can send and serves both an in-process transport and an HTTP
face for the real-host acceptance; the live tests
(`tests/integration/test_everos_cloud_real_cloud.py`) skip without
`EVEROS_CLOUD_API_KEY`; run with a real key on 2026-10-09 all six pass
against api.evermind.ai (round trip, get by session, empty flush, 401
wording, probe with and without a key, and extraction without a flush
within two minutes), so the documentation and the service agree on
everything the plugin sends. Design, acceptance cases and plan are under
`docs/specs/2026-10-08-everos-cloud-memory-*.md` and `docs/plans/`.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Rebased onto main `182dacac0` on 2026-10-13. What that rebase and the
four commits on top were verified with:
- Full suite, `uv run --frozen --python 3.12 --extra dev pytest -q` ->
**29748 passed, 8 failed** in 4m10s. All eight fail identically with
these four commits' sources reverted in-tree at the same base, so none
of them is this branch's: the two `test_the_products_tool_face_*` cases
in the code and oncall launchers (an extra `web_search` in the visible
tool set), `test_agent_loop_token_budget`,
`test_rpc_files::test_a_host_without_libreoffice_says_so`,
`test_ppt_engine_image_search`, `test_shell_background`, and the two
`test_simulation_*` cases.
- Real-host before and after for the inheritance, driving the launcher
the host spawns (`agents/raven-research/run.py`) against an isolated
`RAVEN_HOME` whose EverOS address is `19701`, not the stock port.
Before: the product rendered `base_url: http://localhost:18791` with no
`owned` key, ignored the host, and started an EverOS of its own -- an
orphaned `everos server start --root <its own state root>/everos`
holding 18791, which is the stranding this change exists to stop. After:
it rendered `{"base_url": "http://localhost:19701", "owned": false}` and
said so itself, "the EverOS you manage is not running at
http://localhost:19701 ... Raven does not start or stop it", with `ps`
and `lsof` confirming nothing was started. On the cloud the product
rendered `memory.backend: everos-cloud` with the host's key and left the
out-of-force local slice untouched, and `raven doctor` over that
rendered config answered `everos-cloud: ok https://api.evermind.ai`, so
the credential reached the service. Identity stayed `raven-research-ng`
throughout, and a fingerprint of the operator's own EverOS root was
identical before and after.
- The first CI round on this head found one that the local gates did
not: `tests/test_import_cycle_budget.py`. `inherit_memory_backend` read
the backend-to-distribution pairing from `raven.core.plugin_stack`, and
that edge from `raven.config` into `raven.core` -- which imports
`raven.config` back -- took mutual pairs from 13 to 14 and packages
inside a cycle from 18 to 22. `make lint-imports` keeps ten contracts
and none of them covers that pair, so it was green throughout. The
pairing now lives in `raven/config/raven.py` beside the two fields it
joins (`MemoryConfig.backend` names a contribution,
`PluginsConfig.config` is keyed by the distribution), which `raven.core`
may import and which imports nothing back; `plugin_stack` re-exports the
two names its own callers read from it. An intermediate commit put it in
`raven.contracts` instead, which broke the cycle but took the papers
ceiling from 3700 to 3719 lines -- `tests/test_kernel_budget.py` says a
new paper is a reviewed change to that ceiling, so it moved again rather
than raising it.
- The review round on this head raised one non-blocking finding, fixed
rather than carried forward: the inheritance read `memory.backend` with
`.get()`, which collapses an explicit `null` into an absent key, so a
host with long-term memory off left every packaged agent on its own
shipped backend and still writing. Reproduced by calling the function
directly before the change and after, now read on presence, and pinned
by a case whose mutation (restoring the `.get()`) turns it and nothing
else red.
- One ordering problem found while checking the above, pre-existing and
not fixed here: `tests/test_rpc_settings.py` run before
`tests/test_cli_onboard_commands.py` leaves
`raven.home._current_config_path` pointing at a dead tmp config, so the
onboard cases write somewhere else. With main's own copies of both files
and main's conftest in the tree it is 57 failures; with this branch's,
19. Which cases turn red changes run to run as xdist distributes them
differently.
- `cd ui-web && npx vitest run` -> 876 files, 3728 passed, 0 failed;
`npm run lint` -> 0 errors (4 warnings, all in files this change does
not touch); `npm run gen:check` -> in sync (228 methods); `npm run
type-check` -> clean; `cd ui-tui && npm run lint:i18n && npm run
lint:rpc` -> in sync
- `make lint-python` / `lint-imports` (10 contracts kept) / `lint-types`
/ `lint-deps` -> all pass; `uv lock --check` -> exit 0 with both sides'
new packages present; `scripts/check_source_language.py` and
`scripts/check_large_files.py` on `github/main..HEAD` -> exit 0;
commitlint over every commit -> ok
- Semantic-conflict audit of the rebase, beyond what the suite answers:
21 of the branch's 66 files are also in main's 499, and every one of
main's changes in them is additive and elsewhere in the file. The one
that could have broken silently is main's new `vision.model` /
`vision.provider` simple keys meeting this branch's new
`plugins.config.<id>.<field>` branch in `settings_set`; nothing in the
suite exercises `vision.*` through that method, so it was run directly
-> `{'applied': True}` and `{"model": "..."}` on disk. The subtraction
decisions were re-checked against the new base: no new caller of a
memory backend's `delete`, main's new onboard cases are about TLS and
not the memory step, `inherit_everos_address` exists nowhere, and
`DEFAULT_EVEROS_BASE_URL` is still defined.
- Mutation runs on the new code, restored afterwards: dropping `owned:
false`, letting the host's credential overwrite the product's own, not
writing the host's backend name, and carrying every memory slice instead
of the one in force each turn their own cases red; making the cloud card
render nothing turns 4 of its 5 new cases red and leaves the fifth
("draws nothing when not selected") green.
From the earlier round, on base `6d509a8c5`:
- `uv run --frozen --python 3.12 --extra dev pytest -p no:cacheprovider
-q tests/test_everos_cloud_fake.py tests/test_everos_cloud_backend.py
tests/test_everos_cloud_backend_contract.py
tests/test_everos_cloud_onboard.py tests/test_everos_cloud_discover.py
tests/test_cli_onboard_commands.py tests/test_rpc_memory.py
tests/test_rpc_settings.py tests/test_plugin_boundary.py
tests/test_rpc_schema_match.py tests/test_rpc_registration.py
tests/test_release_plugin_list.py
tests/integration/test_everos_cloud_real_cloud.py` -> 1001 passed, 6
skipped (the six live tests, no key)
- `cd ui-web && npx vitest run` -> 214 files, 3211 passed; `npm run
lint` -> 0 errors (4 warnings, all in files this change does not touch);
`npm run gen:check` -> in sync (207 methods); `cd ui-tui && npm run
lint:rpc && npm run lint:i18n` -> in sync
- `make lint` (ruff, ruff format, ui tsc, deptry) -> ok; `make
lint-types` -> All checks passed; `make build-ui` -> boot snapshots
match; `scripts/check_large_files.py` and
`scripts/check_source_language.py` on `6d509a8c5..HEAD` -> exit 0;
commitlint and `scripts/check_commit_messages.py` on each commit -> ok
- Mutation runs per change (restored afterwards, `git diff` clean): a
host import of the plugin turns the boundary test red; `import
raven_everos` in the plugin turns the import-isolation test red;
removing the chooser's cancel exit, the Bearer header, the restart
guard, the slice-admission guard, the Roles filter and the fake's two
fixes each turn their own test red
- Real-host acceptance (64 cases,
`docs/specs/2026-10-08-everos-cloud-memory-acceptance.md`) run against a
fake EverOS Cloud: the wizard in tmux (chooser, key typed / from env /
on file, 401 / 403 / unreachable wording, back, Off, Ctrl-C,
non-interactive, base-tree transcript byte-identical with one plugin),
`raven agent` turns (user and agent-track recall, agent-mode adds, 4 s
recall bound, a 300 KB message dropped with a warning, a sub-agent trace
stored under its own ids, flushed and read back, one exit flush per
unflushed session), `raven import run` (3 adds then one flush; a hung
flush retried 4x and the exit sweep defeated), `raven doctor` under
seven cloud conditions (seven sentences, exit 2 only for the five
faults) and with the distribution hidden, and the web page through
playwright-cli (memory page counts and the fake's episode, empty and
refused stores, the Model page hiding the three EverOS-only roles while
the embedding row stays, the cloud card rotating a key and showing the
401 wording, three refused settings.set frames over the gateway
WebSocket, the local everos / null / mem0 backends drawing the page as
before, and a provider-key save that restarts the local EverOS on the
base tree and does not on this branch). Evidence and the per-case
verdicts are kept outside the repo. The live service was reached with a
real key after the acceptance run: six tests, six passes, the service's
replies archived with the evidence.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible changes: the wizard's step 4 chooser (only when two memory
plugins are installed); Model settings hides the three EverOS-only role
rows when `memory.backend` is not `everos`/`null` and draws no cloud
card; the memory page sends a Bearer header for the cloud backend.
Two behaviour changes for agent products, both on the `agents/` lane
only. An agent product now follows the host's `memory.backend` and
endpoint instead of its own, which is a fix for the four products that
never followed the host and a change for `raven-design`, which followed
the endpoint but not the backend. And a product no longer starts an
EverOS server of its own: where it used to answer a host that was not
serving by starting one against an empty root of its own, it now reports
long-term memory as unavailable, which is what the host does. Rollback
for this part is the one commit; the product configs it edits are
shipped files, not user config. The plugin is not installed by default
(its wheel is built by the release workflow; nothing changes for an
install without it). Rollback: revert the squash commit; the config
schema gains no new key (the slice is a plugin slice), so an older raven
reads a config written by this one.
Credentials: the cloud key is written only by `set_plugin_config_fields`
into the plugin's slice; the settings page's key row goes through
`settings.set` with a manifest-declared field, and
`settings.everosCloud` reports `api_key_set` / `key_source`, never the
value.
## Related Issues
N/A
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
Bundled ACP agents could fail to start on Windows when rendering
configuration, reading stdin, or replacing the launcher process. Closing
an ACP connection could also fail before releasing its process and
transport because Windows has no os.killpg.
- Keep all five bundled Windows launchers alive until their ACP child
exits, forward the exit status, and apply the same behavior to new
scaffolded launchers. POSIX retains exec.
- Preserve live rendered configurations with the cross-platform PID
probe, retain POSIX file permissions, and preserve seed-file line
endings.
- Read Windows stdin pipes through a daemon feeder with PeekNamedPipe
and reads bounded by the available bytes.
- End the live launcher's Windows process tree with bounded taskkill
before releasing the transport. Leave an already-exited launcher's PID
alone.
- Preserve a completed session/new reply when EOF shutdown cancels its
optional model-menu lookup. The first LiteLLM import can exceed the
five-second grace even after #909 removed the metadata-network delay.
Active-connection cancellation and cancellation during required session
setup still propagate.
- Run real stdio handshakes, all five launchers, command registration,
and native teardown cases in Windows CI. The handshake now also runs
with a fresh bytecode cache.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Native Windows build 10.0.26300, Python 3.13.12, PYTHONUTF8=1. The final
tree is based on the fetched main revision; all eight patches replayed
unchanged. The last upstream update adds bug-report upload/receiver code
and has no file overlap with this PR. The 19-case selection below was
rerun on the final tree; the broader selection and controls predate that
last unrelated update. Tests used isolated user/Raven homes, frozen
dependencies, and verified imports from the tested checkout. Run-owned
--basetemp and --junitxml output paths are omitted from the selections
below.
- `uv run --frozen --no-sync pytest
tests/test_acp_server.py::TestFrameLoop::test_session_creation_answers_when_eof_cancels_the_catalogue
tests/test_acp_methods.py::TestConfigOptions::test_session_creation_preserves_cancellation_outside_shutdown_metadata
tests/integration/test_acp_stdio_smoke.py
tests/test_cli_agents_commands.py::test_register_pins_the_resolved_row_into_the_host_roster
tests/test_subagent_acp.py::test_close_without_killpg_ends_the_tree_through_taskkill
tests/test_subagent_acp.py::test_close_without_killpg_kills_nothing_by_the_pid_of_an_exited_launcher
-m 'integration or not integration' -n 0 --tb=short`: **19 passed, no
skips** after the final rebase. This includes both EOF timings,
cancellation controls, both bytecode-cache states, all five real
launchers, and real taskkill. One non-failing idle-ceiling warning was
reported.
- `uv run --frozen --no-sync pytest tests/test_acp_server.py
tests/test_acp_methods.py tests/test_acp_updates.py
tests/test_acp_config_options.py tests/test_cli_acp_commands.py
tests/test_config_product_render.py tests/test_utils_pid.py
tests/test_agents_code_launcher.py tests/test_agents_design_launcher.py
tests/test_agents_oncall_launcher.py tests/test_agents_ppt_launcher.py
tests/test_agents_research_launcher.py tests/test_cli_agents_commands.py
tests/test_subagent_acp.py tests/test_rpc_bootstrap.py
tests/test_subagent_host_env.py tests/test_subagent_probe.py -n 0
--tb=short`: **1284 passed, 58 failed, 10 skipped, 4 errors**. The same
selection on the rebased PR immediately before the EOF fix returned
**1280 passed, the identical 58 failing and 4 error test IDs, and 10
skipped**. No new failure/error IDs from the EOF fix.
- All 62 failure/error IDs were also selected on main: 56 failed, 4
errored, and 2 passed. Those two passed in isolation on this PR too, and
failed in the complete selection both before and after the EOF fix. The
remaining failures include Windows path, shell/command, and
symlink-privilege cases. The attempted complete main selection stalled
in the pre-existing Windows stdin tests and was terminated; no complete
main-suite result is claimed.
- Before the EOF fix, `uv run --frozen --no-sync pytest
tests/integration/test_acp_stdio_smoke.py::test_a_whole_handshake_runs_in_one_process[cold_imports]
-m integration -n 0 --tb=short` failed with response IDs [1, 3]. A
separate stack-capture probe measured 6.76 seconds in the first LiteLLM
import; the handler awaited model.options while its worker imported
LiteLLM and its dependencies.
- `uv run --frozen --no-sync pytest
tests/test_acp_server.py::TestFrameLoop::test_session_creation_answers_when_eof_cancels_the_catalogue
tests/test_acp_methods.py::TestConfigOptions::test_session_creation_preserves_cancellation_outside_shutdown_metadata
-n 0 --tb=short`: before the fix, 2 failed and 2 passed. Both EOF cases
failed with the missing session reply. They pass with the fix and are
included in the broader post-rebase selection above. Warm/cold real
handshakes plus these four cases also passed as a six-case selection.
- A mutant that treats every connection as closing makes the
ordinary-cancellation control fail. Cancellation during required session
setup still propagates.
- `uv run --frozen --no-sync ruff check raven evolver agents
plugins-dist tests scripts docs-site` and the corresponding `ruff format
--check`: passed; 2266 files already formatted.
- `uv run --frozen --no-sync lint-imports`: 10 contracts kept. `uv run
--frozen --no-sync ty check raven/acp/methods.py raven/acp/updates.py
raven/acp_client/client.py raven/cli/acp_commands.py
raven/config/product_render.py`: passed.
- `uv run --frozen --no-sync pre-commit run --from-ref origin/main
--to-ref HEAD`: every applicable hook passed. The two final docstring
edits also passed their file-scoped pre-commit run.
- `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 PR body passed the repository body checker and an explicit ASCII
scan.
The broader Windows selection remains red, so the relevant-tests
checkbox is unchecked. This revision has no new Linux or full repository
run, live LLM workload, rendering workload, or ACL audit. POSIX-only
skips are not counted as Windows passes.
- [ ] 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
At EOF, a completed session/new can omit optional configOptions when
shutdown cancels a slow lookup; the sessionId and session modes are
retained. Active connections keep their existing model-menu behavior.
The handler grace remains five seconds.
Windows keeps the launcher present while its server runs, and connection
close waits up to five seconds for taskkill. Idle Windows pipe input
polls every 10 ms. Redirected files and text streams retain their
existing reader path. POSIX retains exec and 0600 permissions; Windows
rendered files inherit directory ACLs.
There is no configuration-format change. Previously generated agent
folders retain their existing launchers; the scaffold change applies to
new folders. Revert this PR to roll back the launcher, stdin,
process-cleanup and EOF-response changes.
## Related Issues
#909
## Summary
A page reached through a port forward could not sign in. The gateway
accepted a browser `Origin` only when it named the port the gateway
bound, and VS Code and `ssh -L` pick another local port whenever the
remote one is taken on the browser's machine, so every
`POST /auth/exchange` answered `403 bad origin` and every `/rpc`
upgrade was refused with it. The sign-in page reported an expired link
over a refusal it cannot see, and re-running `raven web` minted one
more link into the same refusal. Measured on 2026-10-13: 13 refusals
in six minutes, each from a page at `127.0.0.1:18793` against a
gateway on 18792, all within a minute of their nonce being minted. The
same check had already forced the container's nginx to rewrite `Origin`
for every request it proxies.
`_origin_ok` now also accepts an `Origin` that asks the request's own
origin (`Origin` equals `Host`) on a loopback name. That is what a
browser sends through a forward, since a forwarder relays `Host`
unchanged. It still refuses a page another local server shows, because
cookies and SameSite ignore the port and that origin names a port this
page does not ask; and it still refuses DNS rebinding, where a name
resolving to 127.0.0.1 asks its own origin and the two agree. The
bound-port allowlist stays for the container's nginx, which forwards
`Host` without a port.
Three smaller changes ride with it:
- The session cookie is named for the port the browser reached rather
than the port bound, so two gateways that both bound 18792 no longer
share one jar entry when one browser reaches them through different
forwards. A `Host` without a port keeps the bound port, which is what
the container's auto-login sets.
- `handle_auth_exchange` answers with the reason it refused, and the
sign-in page shows that text rather than calling every failure an
expired link.
- `_open` prints the sign-in link every time, and before handing it to
a browser. `webbrowser.open` returns True whenever it ran something:
VS Code's `browser.sh` exits 0 whatever happened, and a machine with
no display hands the URL to a console browser that has no JavaScript
and never redeems the nonce. The old fallback was unreachable, so the
link was never printed at all.
The standalone serve test now uses a real aiohttp `Application` while
replacing only `AppRunner` and `TCPSite`. It selects temporary UI
locations for both an absent page and a built page, and checks that the
response revalidation hook is registered only for the built page. This
removes dependence on whether the checkout contains a UI build.
This PR also retains the reviewed Windows test guards and separate
`RAVEN_HOME` directories for real-upgrade fixtures.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Linux fixture follow-up (Python 3.12.13; the three-file suite and diff
coverage were rechecked after rebasing onto the current main):
- Before the fix, parameterizing `TestTheSignInLink` over an absent page
and a built page produced 4 passed / 1 failed. Only the built-page case
failed, with the same missing `on_response_prepare` as CI.
- `uv run --no-sync pytest -q -n 0
tests/test_cli_serve_commands.py::TestTheSignInLink`: 5 passed after the
fix.
- `uv run --no-sync pytest -q tests/test_rpc_transport.py
tests/test_cli_serve_commands.py tests/test_docker_runtime.py
--cov=raven.rpc.transports.ws --cov=raven.cli.serve_commands
--cov-report=json:<coverage-json>`: 234 passed. `<coverage-json>`
denotes the local coverage output file.
- `uv run --no-sync python scripts/coverage_gate.py --coverage-json
<coverage-json> diff --base-ref origin/main`: 100.00% (32/32 executable
changed lines), passing the 90% threshold. This measures diff coverage,
not the full-suite ratchet.
- A temporary test plugin removed the response hook without changing the
checkout. The built-page case failed its hook assertion and the
absent-page control passed (1 failed / 1 passed).
- `uv run --no-sync ruff check tests/test_cli_serve_commands.py
raven/cli/serve_commands.py`, `uv run --no-sync ruff format --check
tests/test_cli_serve_commands.py raven/cli/serve_commands.py`, and `uv
run --no-sync ty check raven/cli/serve_commands.py
tests/test_cli_serve_commands.py`: passed.
- `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; type checks passed). Both commit-message
validators and the repository source-language and large-file gates also
passed.
- The earlier description incorrectly called this an unrelated CI
failure. It was introduced by this PR's standalone-serve test, and the
CI build made that incomplete fixture fail. The fixture follow-up was
validated on Linux; the native Windows and full-suite measurements below
are earlier verification. CI must validate the pushed revision.
Native Windows follow-up (build 10.0.26300):
- Parallel real-upgrade cases now get separate `RAVEN_HOME` directories,
isolating both upgrade markers and downloaded wheels. A scratch barrier
forced both helpers to finish writing the same partial-wheel name before
rename: the original fixture produced 1 failed / 1 passed with
`Distribution not found` in the shared cache; the identical probe with
isolated homes produced 2 passed on Python 3.13.12. The ordinary run had
passed before the forced overlap, so this result identifies a race
rather than a consistently failing upgrade.
- Captured upgrade diagnostics tolerate localized Windows error bytes
and include stderr on a missing success message. Version and
companion-package assertions remain strict.
- Three reported unit-test constraints were reproduced. Symlink setup
now skips only Windows privilege error 1314; other errors propagate and
confinement still runs when a link can be created. Owner-only mode bits
and two SIGTERM-handler tests are explicitly POSIX-only. A native
subprocess probe confirmed that Windows Popen.terminate does not execute
the Python SIGTERM handler.
- `PYTHONUTF8=1`; `uv run --frozen --no-sync pytest
tests/test_rpc_transport.py tests/test_cli_serve_commands.py
tests/test_docker_runtime.py::test_container_bootstraps_the_browser_after_the_engine_is_ready
-n 0 -x --tb=short`: 195 passed, 30 skipped on Python 3.13.12.
Twenty-six skips were already POSIX-specific; four now identify the
reported mode/signal/symlink preconditions. The skipped checks are not
Windows equivalents.
- `PYTHONUTF8=1`, `UV_PYTHON=3.12`, and an isolated caller `RAVEN_HOME`;
`uv run --no-project --python 3.12 --with 'pytest>=8,<10' --with
pytest-asyncio --with pytest-xdist pytest --noconftest
tests/integration/test_cli_upgrade_real_uv.py -q --tb=short -n 4`: 3
passed, covering two real uv upgrade variants and the workflow contract.
- Whole-PR pre-commit, full Python-target Ruff check/format, all ten
import contracts, changed-production type checks, commitlint and
repository commit/asset/source-language gates passed.
Earlier author verification before this Windows follow-up:
- `uv run --frozen --python 3.12 --all-extras pytest -q
tests/test_rpc_transport.py tests/test_cli_serve_commands.py
tests/test_docker_runtime.py` -> `233 passed`.
- The same three files plus every `tests/test_rpc_*.py` and
`tests/test_cli_smoke.py` -> `3121 passed` on the first revision, before
the fixture follow-up.
- The earlier full suite, under `--cov=raven --cov-branch` -> `8 failed,
29791 passed, 158 skipped`, then `scripts/coverage_gate.py diff
--base-ref origin/main --threshold 90` -> `100.00% (32/32 executable
changed lines)`, passed. All eight failures are local baselines: five
proxy tests (`tests/test_config_update_providers.py`) that fail whenever
the shell carries this box's proxy;
`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
(node/npm resolution on this box);
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(fails as root); and
`test_knowledge_parser_excel.py::test_a_legacy_workbook_is_converted_and_read`.
The last three were replayed in an unmodified baseline worktree and fail
there too (`3 failed`).
- The tests were written before the code and watched fail on it, each
for its own reason: the forwarded origin as `403: bad origin`, the
port-forward cookie case as `two sign-ins wrote one jar entry:
['raven_session_18792']`, the launcher cases on empty output. Against
`main`'s two source files the three test files now fail 18 tests.
- Eleven mutants, one construct each, all killed, with both files
restored and compared byte for byte: the forwarded rule off, Origin
equal to Host dropped, the loopback test dropped, the `localhost` branch
removed, either parse left unguarded, the cookie keyed to the bound
port, the two refusals given one text, the link not printed, the link
printed after the browser, and `raven serve --open` bypassing `_open`.
- `ruff check` and `ruff format --check` clean; `lint-imports` reports
`10 kept, 0 broken`.
- `scripts/check_source_language.py origin/main...HEAD` and
`scripts/check_large_files.py origin/main...HEAD` both exit 0.
- Real browser, end to end, against an isolated `raven serve` on its own
`RAVEN_HOME` reached through a TCP forwarder: the tab signed in and
landed on `/`, the cookie it kept was `raven_session_<forwarded port>`,
and an RPC call over a socket opened from that page was answered (server
log: `serve: ws client connected`, `system.hello`). A direct tab on the
bound port signed in too. With `fetch` stubbed, the page rendered each
of the four answers it can receive (refused address, used or expired
link, other status, no answer) with the matching text.
## Risk
- Security impact considered. The change widens one check: an `Origin`
that equals the request's `Host` on a loopback name. The cross-origin
local-page and DNS-rebinding cases remain refused, and both are covered
by tests. What it accepts that the old rule did not is a page whose
origin is exactly the address it asked for -- which only something
serving that address can show, and a file the agent produced arrives
with the CSP `sandbox` directive and so has an opaque origin.
- Backward compatibility: a tab signed in directly on the bound port
keeps its cookie name and stays signed in. A tab reaching the gateway
through a forward had no working session before, so there is nothing to
migrate. The container's auto-login cookie is unchanged, and a test
derives the entrypoint's name from `cookie_name` so the two cannot
drift.
- Rollback: revert the commit. Nothing is written outside the process
except the cookie already in the browser, and no config or format
changed.
- A `Host` that does not parse (`127.0.0.1:99999`, `127.0.0.1:abc`,
`[::1`) is answered 401 on `/rpc`, as on `main`, and an Origin equal to
such a Host is answered 403. Without the guard both would be a 500,
since the cookie's name is read before any credential is checked.
- Not fixed here: the page's own "this tab's sign-in expired" notice
(main page, i18n `gui.auth.stale`) still names the remedy correctly but
not the cause, so a tab that reaches the gateway by a non-loopback
address still reports a sign-in failure it cannot act on. Also
unmeasured: a real VS Code forward and a real container (both request
shapes were reproduced instead).
## Related Issues
N/A
## Summary
Bug Report Packages can now leave the machine and be received on the
other end.
**Receiver.** `raven trajectory receiver --save-dir DIR` runs a
standalone aiohttp
service that takes packages in, checks them in a stream without
extracting
anything (bounded decompression with a per-header cap, sparse members
refused,
member rules, manifest hashes, the `needs_review` / `risk_accepted`
invariant),
stores the original bytes under `<save-dir>/<UTC day>/` next to a
receipt
sidecar, and answers idempotently by report id (same bytes: the stored
receipt;
different bytes: 409). The sidecar is written before the package is
renamed into
place, so a package in a date directory is always a committed one; a
damaged
sidecar is rebuilt from the package. There is no authentication by
design: abuse
is bounded by a per-address token bucket, a concurrency cap, daily byte
and
package budgets, a free-disk reserve and idle/total timeouts, and the
budget is
settled by what the commit task actually did, not by the HTTP outcome.
`X-Forwarded-For` is believed only behind a `--trusted-proxy` network.
**Upload module.** `raven/trajectory/upload.py` carries no user
interface, so the
CLI, the interactive browser and a future web page call the same
functions. The
destination is one string: `DEFAULT_UPLOAD_URL` as shipped (empty here,
meaning
no upload) overridden by `RAVEN_BUGREPORT_URL` (set it empty to switch
uploading
off). A URL must be https or http on this machine unless
`RAVEN_BUGREPORT_ALLOW_HTTP=1`. The whole exchange runs under one
deadline that
cancels the request, the response is read as raw bytes under a cap
(compressed
answers refused), a receipt counts only when every field agrees with the
request, and the outcome is written into `record.json.upload`.
**Wiring.** `report-bug` and the browser's *Report a bug* resolve the
URL before
any side effect, disclose `Will upload to <origin>` on the confirmation
page,
upload once the package lands, and on failure keep the package and name
the
retry command. The browser's *Bug reports* screen gains an *Upload*
action and
`raven trajectory upload-bug-report REPORT_ID` sends a filed report
again.
Docs: a "Send and receive bug reports" section on the trajectory
debugging page
(en + zh), two CONTEXT.md terms (Bug Report Receiver, Upload Receipt),
CHANGELOG.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_trajectory_package_check.py
tests/test_trajectory_receiver.py tests/test_trajectory_upload.py
tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py tests/test_trajectory_bugreport.py
tests/test_docs_site.py -q` -> all pass (about 480 new tests across
them)
- `uv run pytest tests/integration/test_bug_report_upload_e2e.py -q -o
addopts=""` -> 3 passed (a real receiver process, a real `report-bug`
run, a real retry, SIGTERM shutdown)
- `uv run pytest tests/ -q -p no:cacheprovider` -> 28620 passed, 52
failed, 144 skipped; the 52 failures are pre-existing on this machine
(network/proxy/NAT64-dependent tests) and identical to the `main`
baseline
- `uv run ruff check . && uv run ruff format --check .` -> clean
- `make lint-imports` -> 10 contracts kept; `make
check-source-language`, `make check-large-files` -> pass
- `make docs-build` (mkdocs `--strict`) -> pass
- Manual: receiver + `report-bug --yes` (201), repeat (200), different
content under the same id (409), the interactive browser driven through
a pty, failure with the receiver down and retry with
`upload-bug-report`, a 128 MiB upload refused with 413 after ~2 MB both
directly and through an nginx container (`client_max_body_size`). The
nginx-to-receiver hop itself could not be exercised on this machine
(rootless docker cannot reach host services).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- Off by default: with `RAVEN_BUGREPORT_URL` unset and the shipped
default empty, `report-bug` and the browser behave exactly as before;
the receiver is a separate process nobody runs by accident.
- The receiver authenticates nobody on purpose; the docs require a TLS
proxy for anything beyond loopback and say not to expose the port
publicly. Packages are redacted for credentials, not anonymized, so
`--save-dir` is sensitive.
- Rollback: unset the variable and stop the receiver. The new
`record.json.upload` fields are optional and older readers ignore them;
the receiver's on-disk layout is plain files by day.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
System-store upgrades passed both certificate-variable names to uv,
causing a deprecation warning on releases that warn even when the
replacement variable is present. Ask the uv used for installation for
its version and add `UV_NATIVE_TLS` only for releases before 0.11 or
when the version cannot be read. Explicit user settings remain intact.
- Keep certificate-store handoff in a fresh private directory, remove it
from the helper's import path after loading, and test both properties.
- Pin ordinary sub-agent connection failures as `network_error`,
distinct from certificate refusals.
- Let `security.tls.system_ca_in_use()` own the query of the actual
injected SSL factory. Upgrade and integration fixtures use the public
switch rather than duplicating its implementation.
- Cover a timed-out `uv --version` in the real helper orchestration. The
existing 30-second timeout falls back to the legacy certificate
variables so installation and relaunch can continue. Removing the
`SubprocessError` catch now fails this test.
This completes review follow-ups to the system-store change. The timeout
follow-up adds coverage without changing the existing fallback or its
duration.
## 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
Linux, Python 3.12, after rebasing onto current main:
```text
uv run --frozen --all-extras pytest tests/test_security_tls.py tests/test_updates_upgrade.py tests/test_updates_install_guard.py tests/test_cli_subagent_setup.py tests/test_cli_system_ca.py tests/test_cli_onboard_commands.py tests/test_cli_provider_commands.py tests/test_config_update_providers.py -q -x --tb=short
uv run --frozen --all-extras pytest tests/integration/test_cli_upgrade_real_uv.py -o addopts= -n 0 -q --tb=short
```
Results: 894 passed and 3 passed, respectively. The real upgrades cover
library roots and handed-over system roots. Two existing idle-ceiling
warnings were reported by the integration tests.
Native Windows, Python 3.13:
```text
uv run --frozen --extra dev pytest tests/test_updates_upgrade.py -k older_than_system_certs -n 0 -q -x --tb=short
```
Result: 6 passed, including `subprocess.TimeoutExpired`. An isolated
mutation removing `subprocess.SubprocessError` from the version probe's
catch failed exactly the timeout case; the production source was then
restored and checked against Git.
Additional checks passed:
```text
uv run --frozen --extra dev pre-commit run --from-ref origin/main --to-ref HEAD
uv run --frozen --all-extras ty check raven/security/tls.py raven/updates/upgrade.py
uv run --frozen --all-extras lint-imports
uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD
commitlint --from origin/main --to HEAD
uv run --frozen python scripts/check_source_language.py origin/main..HEAD
uv run --frozen python scripts/check_large_files.py origin/main..HEAD
git diff --check origin/main...HEAD
```
Import-linter kept all 10 contracts. The full repository suite and
native macOS were not rerun for this follow-up. No user-facing
documentation change is needed for the additional timeout test. Existing
integration fixtures can use the user's upgrade cache, and some helper
tests reach GitHub before exercising a fallback; these predate this
follow-up.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
An older or unrecognized uv still receives both certificate-variable
names, preserving compatibility behind a TLS-inspecting proxy. An
explicit legacy setting may still produce uv's own warning. The version
query is bounded, and its failure does not prevent an upgrade attempt.
No certificate verification is disabled.
Rollback: revert the squash commit, restoring the previous warning and
unpinned handoff behavior.
## Related Issues
#878, #637
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
The engine half of Personas. A stored Playbook could hold a worker table
and a turn could generate one, but nothing let a person describe the
assistant they wanted, keep it, and come back to it.
**Schema v2** separates three concepts. A reusable artifact carries a
**Harness**, a **Workflow**, or both: the Harness is the durable worker
table bound into a turn, the Workflow is the DAG compiled from one
accepted successful run, and a **Run Record** is the per-execution
evidence, kept beside the artifact and never loaded as one. Schema v1
keeps loading through the `dag` and `prompt` modes.
**A Harness gains a coordinator.** `_SeatPlaybook` carries the four
Harness roles and `CoordinatorPlaybook` / `SubPlaybook` are the two
seats that wear them, so the main seat gets the surface a worker already
had rather than a parallel one. A workers-only payload is normalized on
the way in, so Personas written before this keep loading. Two demands
are contract rather than prose: a named missing-input gate must be a
generated `intake` on the coordinator, and a boundary depending on
tool-call arguments must be a `judge` on the seat making the call. Host
Raven is excluded from the persona roster at the candidate layer.
**Binding needs no new process.** `bind_charter_for_turn` is the
counterpart of `bind_delegate_for_turn`, so `load_playbook` activates a
stored Persona's main seat in the same call that activates its workers.
What a session binds is a snapshot rather than a name to look up later,
carried in the session's own metadata, so editing or deleting the
library entry does not rewrite or break a conversation already running
on it.
**RPC**: `session.create` takes a Harness to open on,
`session.set_harness` reports / binds / unbinds, and `playbooks.list`
grows a `coordinator` flag.
## Scope change
This PR was the whole feature; it is now **the backend only**. The
persona page and the shell wiring are being reworked and will follow in
their own PR, which is why they are not here. The two `rpc/generated.ts`
files stay with this one because the `ui rpc contract` gate reads them
against `openrpc.json`.
Nothing here has a caller yet: the RPC surface grows, a Playbook gains a
shape, and no existing path changes behaviour.
This also supersedes #568, now closed -- every file it added is here.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
ruff check / ruff format clean (1782 files)
pytest (full) 27643 passed, 8 failed
coverage_gate diff 91.34% (threshold 90)
gen-rpc-client --check matches the contract (209 methods)
commitlint / commit messages / source language / large files
```
The 8 failures are environmental and fail the same way on plain `main`:
five proxy-credential redaction tests, the node-dir resolver, the
subagent read test, and one runtime-checkpoint timing test that passes
three times out of three when run on its own.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Review history carried over
Both blocking threads raised against the earlier combined branch were
answered and closed before the split: the refinement poll that accepted
the draft it started on, and the staged Persona that outlived the draft
it was made for. Both fixes live in the page, so they travel with the
frontend PR.
LivXue's three non-blocking notes are in this half. One is addressed
here: `default_generation_mode`'s `persona` value never reached the
guard that mints one, and the field now says so instead of describing
itself as a fallback that would. The behaviour is deliberate and
unchanged -- read as a default it had a reader typing "hi" spend a model
call on a Harness. The other two (the missing `error=` on a cancelled
capture's run record, and the `set_preselected` path no producer ever
writes) are left for a follow-up; the second one also needs
`CONTEXT.md`'s discovery contract corrected with it.
## Risk
No behaviour change for a turn that asks for nothing. Rollback is a
revert of the merge commit; stored v1 Playbooks keep loading.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Co-authored-by: yao pengfei <yaopengfei@evermind.ai>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Behind a TLS-inspecting corporate proxy, or against a company-hosted
gateway signed by a private CA, `raven onboard` failed with
`CERTIFICATE_VERIFY_FAILED` even with the corporate root installed in
the operating system (#637). httpx, LiteLLM and the OpenAI SDK verify
against certifi's bundled roots unless told otherwise, so the
operating-system store was never consulted on the paths that reach a
model. aiohttp, urllib and websockets read OpenSSL's defaults instead,
so one process trusted two different sets of roots depending on which
client made the call.
What changes:
- `raven/security/tls.py` (new): `use_system_ca()` injects truststore,
so every TLS context built afterwards is verified by the operating
system (CryptoAPI on Windows, the Security framework on macOS, OpenSSL's
default paths on Linux). A bundle a caller loads into a context is still
honoured: on Linux it joins the store, on macOS its roots become extra
anchors, on Windows it is tried when the system roots fail. So every
root trusted before stays trusted. `RAVEN_NO_SYSTEM_CA=1` opts out,
parsed like `RAVEN_NO_UPDATE_CHECK`.
- `raven/cli/entry.py` (new) is now the entry of both the console script
and `python -m raven`, the form the web supervisor starts its gateway
with. It switches trust before importing the CLI, because the CLI's
imports reach aiohttp (through the sub-agent backends), and aiohttp
builds its default context when it is imported. `raven/cli/commands.py`
no longer starts the CLI when run as a script, which skipped the switch;
pointing it at the entry would not have helped, since by then its own
imports have built aiohttp's context.
- The provider probe names a certificate that fails verification
`certificate_untrusted` instead of `network_error`. It checks for that
ahead of the proxy branch: through a proxy that answered the tunnel, a
refused certificate used to be reported as `proxy_unreachable`. The
Codex check (its backend's list of the account's models), MiniMax's
token renewal (which reported `oauth_token_missing`) and the sub-agent
key prompt's probe name it too. LiteLLM's Copilot token exchange and its
ChatGPT renewal drop the handshake error before Raven sees it, so those
still read as the credential.
- The three surfaces that read the probe say so. `raven onboard` and
`raven provider test` no longer send the reader to check the network,
proxy or VPN; their hints name the three causes: a CA to add to the
system certificate store; macOS and Windows refusing a certificate by
their own rules even when `SSL_CERT_FILE` trusts its CA, which
`RAVEN_NO_SYSTEM_CA=1` turns off; and an expired certificate, or one for
another host, which is the server's to fix. `raven onboard` offers the
menu a network error gets (re-entering the key cannot fix a
certificate); the web Settings page has its own line, in English and
Chinese, in `i18n/messages.json` and the TUI's catalogue generated from
it.
- The RPC contract's description of the model catalogue's `status`
(`rpc-schema/openrpc.json` and both generated clients) now lists the
probe's real words. It named `unauthorized`, which the probe never
returns (a 401 or 403 is `invalid_key`), and missed `proxy_unreachable`
as well as the new status.
- The Codex provider no longer retries a request whose certificate
failed verification with verification turned off (`verify=False`). The
second attempt carried the ChatGPT OAuth bearer token and the whole
conversation to whoever presented the certificate (a captive portal, a
hostile network, a proxy that re-signs TLS), and on a network like the
one in #637 it is what would keep Codex working unverified while every
other provider fails. The retry dates from the initial import;
`_request_codex` loses the `verify` parameter that existed only to carry
it.
- `raven upgrade` and the page's Update verify against the same store as
the release lookup. The upgrade helper runs on the base interpreter,
outside the tool environment that holds truststore, and fetched the
release lists with urllib's default context; uv fetched the rest with
its bundled roots. When the spawning process itself verifies against the
system store, it now copies truststore into a fresh temporary directory
and hands the helper its path, as it hands over the marker path; one
that opted out, or never went through `cli.entry`, hands over nothing
and needs no truststore to say so. The helper loads the copy before its
first download and deletes it, and gives `UV_SYSTEM_CERTS` (and
`UV_NATIVE_TLS`, which older uv reads) to uv's own calls only, so the
Raven it relaunches inherits neither. A copy, because
`inject_into_ssl()` imports requests and urllib3 wherever it finds them,
and the tool environment's belong to what uv is about to rewrite.
- Quick Start, in both languages, gains a section on corporate proxies
and private CAs: WSL2 does not see the Windows store, and the EverOS
memory server and Node-based agents run as separate programs that need
`SSL_CERT_FILE` and `NODE_EXTRA_CA_CERTS` in the shell profile.
`SSL_CERT_FILE` must name a complete bundle that exists, since httpx
refuses to start with a missing one:
`/etc/ssl/certs/ca-certificates.crt` on Debian, Ubuntu and WSL, and one
built from `/etc/ssl/cert.pem` on macOS. A note says macOS and Windows
apply their own certificate policy and names `RAVEN_NO_SYSTEM_CA=1` as
the way back.
The LiteLLM warning in the issue ("Failed to fetch remote model cost map
... CERTIFICATE_VERIFY_FAILED", with `SSL_CERT_FILE` exported) is not
LiteLLM building its own store. That fetch is a plain `httpx.get`, which
reads `SSL_CERT_FILE`, and the variable replaces the whole trusted set:
with a corporate-only PEM the gateway verifies while
raw.githubusercontent.com, signed by a public root, no longer does.
Measured with a private CA: corporate-only PEM, warning; certifi plus
the corporate root, remote fetch succeeds.
Not covered, by construction: the EverOS server is a separate `everos`
executable and Node-based agents are not Python, so an injection in this
process cannot reach them. The new docs section gives them their
environment variables.
`uv.lock`: adding truststore re-resolved the lock (uv 0.11.25, revision
3 kept). Besides the truststore entries, five packages' dependency edges
lose a marker: matrix-nio, h2, aiohttp-socks, aiologic and culsans. Each
dropped marker is implied by the only path that reaches its package
(matrix-nio, and through it h2 and aiohttp-socks, only where
`sys_platform != 'win32'`; culsans and aiologic only below Python 3.13),
so the resolved set is unchanged on every platform. uv 0.12.23 produces
the same edges and also rewrites the lock to revision 5, so it was not
used; both versions accept the committed lock under `uv lock --locked`.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Red first, on the base: the end-to-end `raven provider test custom`
against a gateway whose root only the stand-in system store holds exits
1 with `network_error ... unable to get local issuer certificate` under
both launch forms, and its opted-out twin prints "Check network /
firewall / VPN settings"; the probe test returns `network_error`, and
through a CONNECT proxy `proxy_unreachable`; the onboarding menu offers
`rekey` for a certificate failure; the web note falls to
`probe_unknown`; and the Codex test's endpoint receives `Bearer
tok-secret`, with the captured log line `SSL certificate verification
failed for Codex API; retrying with verify=False`.
Mutations, each applied and then restored byte for byte:
- the entry no longer switching trust: both end-to-end trust cases fail;
- the switch moved after the CLI import: only
`test_trust_is_settled_before_the_cli_builds_a_context` fails;
- the classifier accepting any `ssl.SSLError`: the plain-HTTP case
fails;
- the certificate check placed after the proxy branch: the proxy case
fails.
Review round two, red first at the round-one head: against an endpoint
signed by a root no store holds, the Codex check returned
`network_error`, MiniMax's token renewal `oauth_token_missing` and the
sub-agent key probe `network_error`; both hint tests failed on the
missing opt-out; the guard scan found `raven/cli/commands.py`; and the
upgrade tests found nothing handed over. Round-two mutations, each
applied and then restored byte for byte:
- the classifier matching `CERTIFICATE_VERIFY_FAILED` in the message:
the new macOS and Windows cases fail (282 of 282 stayed green before
them);
- 17 single-construct mutants of the upgrade hand-over (not switching,
not putting the copy on the path, keeping it, hiding a failed load,
leaving the path in the environment, not telling uv, overwriting a uv
setting the user made, dropping the older uv name, telling uv without a
copy, uv not given its environment, passing on an inherited path,
importing truststore instead of reading whether this process switched,
handing over without that check, handing over always, handing over no
copy, and keeping a copy no helper started, at each spawn site): each
fails at least one test;
- the copy failure's warning and its cleanup: each fails the
copy-failure test.
Commands and results, at the head after rebasing onto `main`. The
commits `main` gained since round one touch none of this branch's lines:
`git range-diff` shows every commit unchanged, and the aggregate
patch-id is the same before and after.
- The touched Python test files (`tests/test_security_tls.py`,
`tests/test_cli_system_ca.py`, `tests/test_config_update_providers.py`,
`tests/test_cli_onboard_commands.py`,
`tests/test_cli_provider_commands.py`,
`tests/test_cli_subagent_setup.py`, `tests/test_updates_upgrade.py`,
`tests/test_openai_codex_provider.py`), the Codex provider's neighbours
(`tests/test_providers_first_byte_budget.py`,
`tests/test_provider_protocol.py`) and the i18n tests, in full: 1010
passed.
- Full suite with branch coverage, `pytest -q -p no:randomly --cov=raven
--cov=raven_everos --cov-branch` on the all-extras environment with the
box proxy variables unset: 2 failed, 27750 passed, 119 skipped. Both
failures fail the same way on a clean tree of the new merge base under
the same interpreter, so neither is introduced; they are local to this
box (an `npm` on its PATH, and running as root):
-
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
-
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
- `scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`
over that run: 100.00% (57/57 executable changed lines).
- `tests/integration/test_cli_upgrade_real_uv.py`, which CI runs only in
the Windows self-upgrade job (`--noconftest`): 3 passed locally. Its
fixture calls the handoff without `cli.entry`; the `system store`
variant switches first, as `cli.entry` does, so that job runs the whole
hand-over on Windows, and the fixture prints what it handed over so
neither variant passes without its branch running.
- `ruff check`, `ruff format --check`, `ty check` over the changed
modules, `lint-imports` (10 contracts kept), `deptry raven`: clean.
- Repository gates over `origin/main...HEAD`:
`check_source_language.py`, `check_large_files.py` and
`check_commit_messages.py` exit 0.
- Generated files on the rebased tree, where `main` had also changed the
RPC schema, the message catalogue and their generated copies:
`gen-i18n.mjs --check` and `gen-rpc-types.mjs --check` (ui-tui) and
`gen-rpc-client.mjs --check` (ui-web) exit 0.
- Round two changes no file under `ui-web`, `ui-tui` or `rpc-schema`;
these were measured at round one:
- ui-web, `node node_modules/vitest/vitest.mjs run
src/features/settings/SetupBodies.test.tsx
scripts/gates/i18n-keys.test.mjs`: 33 passed; `scripts/gates`: 46 files,
205 passed; `tsc --noEmit` clean, its `--listFiles` resolving the edited
files inside this tree; ESLint clean on the three files.
- ui-tui, the steps of TUI checks: ESLint 0 errors; `lint:rpc` and
`lint:i18n` pass; `tsc --noEmit` clean; the build passes; `vitest run`
has 9 failures in 4 files (renderer and typing-burst tests), the same 9
that fail on a clean worktree of the merge base on this box, so none is
introduced.
- RPC contract: `node scripts/gen-rpc-client.mjs --check` (ui-web) and
`node scripts/gen-rpc-types.mjs --check` (ui-tui) exit 0, each generated
file differing from the base by the one description line; the 9 Python
test files that read the schema, 798 passed.
- Docs: `mkdocs build --strict` clean, with the new paragraphs on the
English and Chinese pages; `tests/test_docs_site.py` and
`tests/test_living_docs.py` pass in the full suite.
The end-to-end cases run on Linux only. They stand the system store in
with OpenSSL's directory store through `SSL_CERT_DIR`, and name a bundle
of public roots in `SSL_CERT_FILE` so that httpx cannot pass by reading
`SSL_CERT_DIR` itself. Verification on macOS and Windows was read from
truststore 0.10.4's source, not run. The upgrade helper's tests share
the limit: on Linux truststore and the standard library read the same
store, so they show the hand-over (the copy loads on the base
interpreter under `-I` before the first download, and uv alone is told),
not the Keychain difference it exists for.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- Every Raven process started as `raven` or `python -m raven` now trusts
the operating system's roots in addition to what each library bundles.
For those processes `SSL_CERT_FILE` adds to the trusted set instead of
replacing it; someone using it to narrow trust to one private root keeps
that root but also trusts the system store.
- On macOS and Windows the system verifier applies its own certificate
policy as well. A private certificate that OpenSSL accepted from
`SSL_CERT_FILE` can be refused there if it breaks that policy;
`RAVEN_NO_SYSTEM_CA=1` restores OpenSSL's verification.
- On macOS and Windows truststore also verifies the client's chain on
server-side contexts, refusing a client that sends none. Raven builds no
server-side TLS context: it serves plain HTTP on localhost.
- Upgrades verify their downloads the way the release lookup does: on
macOS that includes Apple's certificate policy, which the helper's
OpenSSL did not apply. uv is told to use the system store only for the
upgrade's own calls, and a `UV_SYSTEM_CERTS` or `UV_NATIVE_TLS` the user
set is kept.
- Behind a proxy that re-signs TLS, Codex requests now fail with the
certificate error instead of continuing unverified. Trusting the proxy's
root, in the system store or in a complete bundle named by
`SSL_CERT_FILE`, is the remedy.
- Startup: about 100 ms warm and 270 ms cold, measured on Linux, mostly
truststore importing urllib3 and requests to patch their references.
- Rollback: `RAVEN_NO_SYSTEM_CA=1` restores the previous trust per
process, and an upgrade started under it hands its helper and uv
nothing; the Codex change has no switch, by design. Reverting the squash
commit removes both.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#637
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Follow-ups to #839 in the browser driver, the browser tools and the
real-browser tests.
**The touch note survives the end of an owner's binding (regression from
#839).** #839 had the driver tell the tools' `_acted` store whenever it
dropped an owner's tab binding, and the store then deleted that owner's
last-act stamp. The readback promises `note: the user interacted with
the browser since your last action` until the owner acts again, and the
end of a binding is not the end of the owner: `Browser.release()` has no
production caller, so the listener fired only on a reap after
`OWNER_IDLE_S`, on the owner's tab closing and on the browser closing.
When the reader closed an agent's tab from the panel, or the binding
idled out, the agent's next read lost the note. The listener is removed
and the driver's owner removal is back to its pre-#839 form;
`_ACTED_MAX` still bounds the store.
**A host missing a system library is told so.** The driver now answers
`Chromium is installed but cannot start here: the system library
libatk-1.0.so.0 is missing. Installing system libraries needs root, so
it is the user's step: on Debian or Ubuntu, <python> -m playwright
install-deps chromium`. Before, on x64 the loader's refusal came back as
Playwright's whole launch log, after a throwaway relaunch that could not
help; where Playwright's own dependency check runs (its linux-arm64
Chromium builds), its report suggests `playwright install-deps`, which
the driver read as "Chromium is not installed". The message says whose
step it is because tool results reach the model too.
**Only failures a fresh profile cannot fix skip the throwaway
relaunch.** The relaunch was gated on the substring "profile", and every
Playwright launch failure quotes the command line,
`--user-data-dir=<home>/.raven/browser-profile` included, so every
failure relaunched and logged "profile is busy". Every failure is still
retried once except a missing system library, Playwright's host check
and a missing executable, and the warning says the launch failed rather
than that the profile is busy. Matching Chromium's lock words instead
would be narrower and wrong under another locale: with
`LANG=zh_CN.UTF-8` a second headful launch on a held profile prints its
line in Chinese, Playwright's English rewrite of it does not fire, and
the error says only "Target page, context or browser has been closed".
**The profile path is read at launch.** `PROFILE_DIR` was computed at
import, before `tests/conftest.py` gives each test its own HOME, so the
real-browser tests used the developer's own `~/.raven/browser-profile`,
with parallel workers opening it at once; the cookie
`test_browser_real_web.py` sets turned up in a developer's own cookie
jar. `_profile_dir()` now resolves the path on each launch.
**The real-browser suites skip on a host that cannot load Chromium.**
`tests/_browser_cache.py` gains `chromium_launch_failure()`: one bare
headless launch per process, with Playwright alone. When it fails for a
missing system library, both
`tests/integration/test_browser_*real_web.py` modules skip with the
library named: the twelve `libatk-1.0.so.0` launch failures reported on
#839 become twelve skips. Any other launch failure, such as an older
build left in the cache or a timeout under load, is not a reason to
skip, and the suites fail on it as before.
`docs/browser-and-desktop.md` said a second process would get a
throwaway profile. The headless shell takes no profile lock, so a second
headless Chromium opens the same profile; the sentence now says so.
Not in this PR:
- `url_for` still predicts the landing page before the permission
prompt, so whatever moves while a person decides moves the call (the
binding-generation idea in the #600 discussion).
- Two headless Ravens share one profile with no lock; documented above,
not changed.
-
`tests/integration/test_browser_tools_real_web.py::test_two_owners_two_tabs_and_neither_takes_the_other`
hung in 2 of 73 runs of both real-browser files on main's tree -- both
times with one profile shared by every worker, never in the 24 runs with
a profile per test -- and in none of 78 runs on this branch or 240 runs
of that test alone. The cause is unknown, and counts this small cannot
credit any change here with a fix. One of the first 45 branch runs, made
before the profile change, also failed one test outright; it was not
seen again and is not explained.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Python 3.12, the repo environment with all extras, run from this tree.
- `python -m pytest tests/test_browser_driver.py
tests/test_browser_tools.py tests/test_browser_cache.py -q`: 129 passed.
With `raven/browser/driver.py` and `raven/agent/tools/browser.py` taken
from origin/main, 15 of them fail: the touch-note test for a reader's
close and for an idle binding, the launch-time profile test, the four
host-library cases, the empty-message retry, and the seven probe tests,
which call a helper main lacks.
- Each guarded construct was mutated on its own (14 mutations, among
them: no stamp after a close, a stamp pruned on a tab close, each of the
three no-retry clauses dropped, the host-library check moved after the
not-installed one, the profile path fixed at import, the probe skipping
on any failure, the probe launching on the caller's loop); each turns at
least one test red.
- Full suite, `python -m pytest -q`: 27482 passed, 116 skipped, 2
failed. Both failures are local to this box and touch nothing this
branch changes:
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
(an npm elsewhere on PATH leaks past the fixture) and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(the suite runs as root, which reads the file the test makes
unreadable).
- `python -m pytest tests/integration/test_browser_real_web.py
tests/integration/test_browser_tools_real_web.py -q` with a real
Chromium: 12 passed in each of 3 runs. A guard around `_profile_dir()`
logged 39 resolutions, none under the real home, and no file under
`~/.raven/browser-profile` changed during the runs.
- Report shapes: the host-library fixtures follow real launches against
a binary built to need an absent library, with Playwright's dependency
check both skipped (the loader's refusal) and forced (both of its Linux
reports). Two headless launches on one profile: the second starts. Two
headful launches on one profile under `xvfb-run`: with
`LANG=en_US.UTF-8` the error says the profile "is already in use"; with
`LANG=zh_CN.UTF-8` it carries none of Chromium's English lock words.
- `ruff check`, `ruff format --check`, `lint-imports` (10 kept), `ty
check raven`, `scripts/check_source_language.py`,
`scripts/check_large_files.py`: all pass.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible: the touch note is reported again after the reader closes
an agent's tab or the binding idles out; a launch that fails for a
missing system library reads as one line naming it, with no throwaway
relaunch; every other launch failure still gets one throwaway relaunch,
under a different warning.
- [x] Security impact considered: the new message names a root command,
and it is worded as the user's step because tool results reach the
model.
- [x] Backward compatibility considered: `Browser.on_owner_released`
(added in #839) and the module constant `PROFILE_DIR` are removed; `git
grep` finds no reader of either outside the two files changed here.
- [x] Rollback path is clear for risky changes: revert the squash
commit; nothing persisted changes shape.
## Related Issues
Follows up #839; refs #600.
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Fixes the three defects #600 reports in the browser tools, and the test
fixture that failed six real-browser tests on Linux.
**A permission key could name a site the call would not act on.** The
acting tools write the site into the call before the gate reads it, and
took it from `url_for(owner)`, which fell back to the front tab for an
owner with no live binding. When another owner held that tab, the call
opened a blank tab of its own instead: a person approved `bank.test` for
a key press that landed on `about:blank`, and banked a grant that any
later click, type or press on `bank.test` presents, since the three
verbs share one key per site.
`url_for` now reports the page `_page_for` will bind, through one rule
both use (`_landing`): the owner's live tab, else the front tab unless
another live owner holds it, else nothing. In the last case the call
opens a tab of its own, which no site describes yet, so no site is
written and the grant is keyed on the call itself.
The issue offered two directions, and neither is taken as written. An
empty answer for every unbound owner fixes the reported case but breaks
one that worked: with the front tab the reader's own, the call lands on
it while the prompt names no site, and its per-call grant can then be
presented by an identical call on whatever front tab comes next.
Resolving the site after binding would make `cast_params` asynchronous,
and that hook is part of the contract every tool shares.
**`_BrowserTool._acted` was never pruned.** Keyed by `run:<uid>`, it
kept one entry per delegated run for the life of the process: 50,000
runs left 50,000 entries and 6.6 MiB after `gc.collect()`. The driver
now ends every binding through one `_drop_owners` (a reap, a release,
the owner's tab closing, the browser closing) and tells a listener the
tools register on their first stamp. The map also keeps only the 512
owners that acted most recently, for owners whose binding is never
dropped. The same 50,000 runs now leave 512 entries.
**`browser_tabs` did not say that close refuses a tab nobody holds.**
Such a tab is the user's and may hold a login they were asked to
finish, and the listing marks it neither `yours` nor `held`. The
description now says so, as does the browser guide in both languages.
**`test_browser_real_web.py` aimed Playwright at the macOS cache on
every platform.** The suite redirects `HOME`, and Playwright resolves
its cache from the home directory, so the fixture points it back at the
login's cache, but only at `~/Library/Caches`. The look-up now lives in
`tests/_browser_cache.py`, shared by both real-browser suites, and
mirrors playwright-core's `registryDirectory`: XDG_CACHE_HOME on Linux,
LOCALAPPDATA on Windows, `PLAYWRIGHT_BROWSERS_PATH=0` for an install
inside the package, and a relative path. Both suites skipped only when
the package was missing, so a missing browser failed them; they now
check for the browser. The driver called that failure "not installed"
even when the browser sat where the process did not look; the message
now quotes the path it looked for and names PLAYWRIGHT_BROWSERS_PATH,
on one line.
Known gaps, left as they are:
- `url_for` is a prediction made before the prompt. Anything that moves
while a person decides (the reader switches tabs, another owner takes
the front tab, the binding idles past ten minutes) moves the call with
it. Closing that needs the gate to see the binding the call will use;
the issue thread sketches one shape.
- The skip checks for a Chromium directory, not the revision this
Playwright needs. A cache holding only an older build still fails the
launch, and the message then names the path it looked for.
- `browser_tabs` stamps an owner after closing that owner's own tab;
that stamp leaves through the cap rather than through a release.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run with the project environment's interpreter (all extras installed):
- `python -m pytest` over `tests/test_browser_cache.py`,
`tests/test_browser_driver.py`, `tests/test_browser_tools.py`,
`tests/test_browser_policy.py`,
`tests/integration/test_browser_real_web.py` and
`tests/integration/test_browser_tools_real_web.py`: 172 passed. CI
does not collect `tests/integration/`, so those two files ran here
only.
With PLAYWRIGHT_BROWSERS_PATH pointed at a directory that does not
exist, all 12 skip with the new reason instead of failing.
- The `url_for` table, one case per branch of the landing rule, fails
against main in the two cases where another owner holds the front
tab, and against the empty-answer direction in the three where the
front tab is free.
- Deleting each of the 22 constructs that carry this change, one at a
time, turns at least one test red.
- `python -m pytest -q -p no:randomly`: 27132 passed, 7 failed, 116
skipped. The same 7 IDs fail on a complete tree of origin/main: five
provider-proxy tests that read this machine's proxy settings, and two
Node-runtime tests that depend on its node install and on root
ignoring permission bits.
- `ruff check` and `ruff format --check` on the changed files,
`lint-imports` (10 kept, 0 broken), and `ty check raven evolver agents
plugins-dist scripts` (the `make lint-types` set): all pass.
- `scripts/check_source_language.py` and `scripts/check_large_files.py`
over origin/main...HEAD, and `scripts/check_commit_messages.py` and
commitlint over origin/main..HEAD: all pass.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
An acting call that would open a tab of its own is no longer keyed on
the front tab's site: its prompt names no site, and a session grant for
it covers only an identical call, so that state prompts more often. A
call landing on the user's front tab keeps the site key it had. The
browser-unavailable message the panel shows is reworded; nothing parses
it. No config, schema or stored state changes, and reverting the squash
commit restores the previous behaviour.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#600
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Adds `experimental/`, a first version of worker RSI: a Curator that
shapes a
Raven worker's harness from the task, the materials handed to it and
feedback,
the way a new employee is trained.
The worker is a harness-of-harnesses. A root Raven harness faces the
user and
calls child harnesses, each a full Raven agent hosted over ACP, through
the
nodes of its playbooks. Every harness has the same four strategy facets
(memory, planning, capability, action). The Curator reads the actual
harnesses
and generates code and config on those facets at both levels: the root
candidate sets the playbooks and writes per-node requirements, each
child is
curated against the requirements of its nodes, and the set is checked on
copies and activated together.
Layout:
- `curator/`: staged generation (understand, select, design, implement,
repair), two-level composition, harness contracts, and `raven_adapter/`,
the only layer that touches a worker's Raven runtime
- `analyst/`: turns an evaluator's words and execution records into
observable behavior requirements
- `iteration/`: the generic loop (onboarding curation, then trial,
review and
curation each round) and a CLI for a human evaluator
- `simulation/`: a simulated travel agency that runs the loop, plus one
showcase case (`simulation/cases/s0925c/`: case notes, the exported
transcript split by phase, and the round 1 and round 3 decks)
- `docs/design.md` (structure, curation flow, composition sequence, the
Raven
connection) and `docs/rsi-iteration.md` (the loop and the Analyst)
Key decisions:
- No change under `raven/`, and `raven/` does not import
`experimental/`.
Generated artifacts land on Raven's existing extension points. The few
Raven
internals the adapter reads are listed in `docs/design.md` section 5.4.
- The Curator explores a read-only source snapshot; the caller names the
evaluation side to withhold from it, so the generic layers name no
scenario.
- The single-layer owner analysis is kept only to reproduce the showcase
case
and is marked for removal; the two-layer Analyst is the default.
- The two decks are `.pptx` files of about 230 KB each. They pass
`check-large-files`; flagging them in case they count as report assets
under AGENTS.md section 7, in which case they can move out of git behind
a
link.
- One follow-up for Raven 0.2.2: playbooks in prompt and rounds modes
ship no
fixed nodes, so node requirements are read from dag playbooks only.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
On the branch rebased onto the latest `main`:
- `uv run pytest tests/test_harness_curator_*.py tests/test_analyst_*.py
tests/test_iteration_*.py tests/test_simulation_*.py -q`: 368 passed
- `uv run pytest -m integration
tests/integration/test_harness_curator_*.py --deselect
tests/integration/test_harness_curator_real_llm.py -q`
(offline, stub providers): 57 passed
- `uv run pytest -q` (whole suite, with the host proxy variables unset
and
`PYTHONTZPATH` set): 26692 passed, 2 failed. One was an order-dependent
test
of this PR and is fixed here; the other,
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`,
fails only because the machine runs as root and is unrelated.
- `uv run ruff check` and `uv run ruff format --check` on the touched
files:
clean
- `scripts/check_large_files.py origin/main..HEAD`,
`scripts/check_source_language.py origin/main..HEAD`,
`scripts/check_commit_messages.py origin/main..HEAD` and
`npx commitlint --from origin/main --to HEAD`: all exit 0
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
No user-visible change for Raven: `experimental/` is not imported by
`raven/` and is not packaged in the wheel (`packages = ["raven"]`).
`CONTEXT.md` gains one glossary entry. The Curator's exploration offers
a
shell only under an OS sandbox executor. Rollback is a revert of the
squash
commit; nothing else depends on `experimental/`.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Yuqi Yang <yiqiyang524@gmail.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
Two fixes to the documentation site.
**The contents rail went dark between headings.** The right-hand table
of contents lit an entry only while its heading was inside the viewport.
Partway through a section longer than the screen every heading sits
above or below it, so nothing was lit, the gold stretch collapsed to
zero height, and the column stopped following the reader. On the built
site before this change, 18 of 28 English pages had such stretches: 114
of 1264 scroll positions sampled every 120px. `sync()` in
`docs-site/docs/javascripts/toc-progress.js` now falls back to the
nearest heading above when none is in view and lights that entry alone.
The lit stretch and the column follow read the same list, so both pick
it up with no further change. Above the first heading nothing is lit,
since no section has begun there. The design spec states the rule, and
the rail's section comment in `evermind.css`, which still credited
Material with marking the section, now names what does.
**The tab icon differed from raven.evermind.ai.** The site drew its own
simplified EverMind mark, a single heavy lemniscate without the rings.
raven.evermind.ai links one 192px PNG of the full mark for its light,
dark and apple-touch icons alike. `theme.favicon` in
`docs-site/mkdocs.yml` now inlines that PNG byte for byte as a data URI,
since AGENTS.md section 7 keeps image files out of `docs-site/`. For
whoever refreshes it: that site's CDN answers any `Accept` naming
`image/avif` with a lossy AVIF re-encode (5178 bytes), and only a plain
`Accept: */*` returns the original PNG (5184 bytes). The comment above
the value says so.
Checked and deliberately left alone:
- The mark at the top of the navigation rail (`--em-mark` in
`evermind.css`) is a separate drawing and still the simplified one. This
change is the tab icon only.
- raven.evermind.ai also sets an apple-touch icon. Material emits no
such link, and adding one needs a template override, which is an `.html`
file that section 7 blocks.
- The favicon's identity is verified by the measurements below rather
than pinned by a test: a pinned hash would only detect change, and
comparing against the live site would put the network in the suite.
- `tests/integration/` is outside every CI job (`norecursedirs`), so the
e2e results below are local runs.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run --frozen --extra browser --group docs pytest
tests/integration/test_docs_site_controls_e2e.py
tests/integration/test_docs_site_search_e2e.py -n 0 -q`: 63 passed.
- `uv run --frozen --extra browser --group docs pytest
tests/test_docs_site.py -q`: 16 passed.
- The new
`test_table_of_contents_keeps_the_section_above_lit_between_headings`
computes, from the Sandbox page's own layout, every stretch between two
headings (or after the last) with none on screen, and checks the middle
of each. Against the unfixed script it fails (`at 1354px: assert [] ==
[2]`), and with the fix it passes.
- A sweep of every built page in headless Chrome at 1440x900, one sample
every 120px, checking the rule at each position: 0 violations over 1264
English, 1145 Chinese and 21 Overview positions after the change, and
wherever an entry is lit, the first one sits inside the contents column.
The unfixed script gives 114 violations over the same English positions.
- Favicon: each of the 63 built HTML files carries exactly one icon
link, and its decoded bytes match the PNG raven.evermind.ai links
(sha256 `4a5051e1781fac64...`). Drawn in Chrome at 16, 32 and 192px, the
docs icon and that PNG differ in 0 pixels.
- `mkdocs build --strict`, `scripts/check_source_language.py
origin/main...HEAD`, `scripts/check_large_files.py origin/main...HEAD`,
`scripts/check_commit_messages.py origin/main..HEAD`, commitlint,
`pre-commit run --from-ref origin/main --to-ref HEAD`, ruff and `git
diff --check`: all pass.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The last box is left blank because nothing needed it: no documentation
page describes the rail or the icon, and the design spec is updated in
this change.
## Risk
- Between headings, the entry of the section above now stays lit and the
contents column keeps it in view. While any heading is on screen the
behaviour is unchanged.
- The tab icon changes to the full mark. Each page's head now carries
about 6.9 KB of base64 for it, against about 0.6 KB for the previous
SVG.
- The new code relies on no browser API newer than
`Array.prototype.includes` (2016).
- The two halves touch disjoint files, so either can be reverted on its
own.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The inlined PNG was read chunk by chunk: standard chunks plus three
ImageMagick timestamps, and nothing after IEND. Inlining it adds no
third-party request, which hotlinking the CDN copy would have.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Retires the built-in `deep_research` tool: the MiroThinker HTTP tool,
its
unconfigured stand-in of the same name, the async channel manager, the
`raven deep-research` command group, `tools.deepResearch` /
`DeepResearchToolConfig`, the loop's registration / mid-session
promotion /
broker and submit wiring, the `inline_tool_stream` flag (its only
consumer
was the tool's stream callback) and the `delivered_sink` plumbing from
#705
(its only writer was that callback). The WebUI settings page loses the
row
and its MiroThinker key panel, the ACP command menu loses
`deep-research`,
and the three transcript i18n keys go (readers fall back to the raw
name).
Research keeps two surfaces: the Raven-Research agent and the
MiroThinker
sub-agent preset; neither shared code with the tool.
`TurnRequest.deliver_text`
stays as a spine contract with its own tests, although nothing in-tree
produces it any more; the comments that used deep research as its
example
now name the sub-agent relay.
Config: a load-time migration (floor 10) drops `tools.deepResearch` /
`tools.deep_research`, one notice per spelling it finds, silent and
idempotent when nothing changes (it
re-runs on every load for configs parked by the research rename, and
`load_raven_config` calls it a third time without writing the stamp). A
`deep_research` entry in `tools.disabledTools` is left as written: that
list
is the general name denylist and a plugin tool may carry the name
(plugin
tools register last so one can shadow a built-in), so dropping the entry
would put such a tool back on offer. The first revision stripped it; the
review caught that and the strip is gone.
Kept on purpose (see the grep gate below): the MiroThinker sub-agent
preset
and its fixtures, `agents/raven-research/**`, the four trajectory
cassettes
that recorded the tool's schema (the replay serves the recording's own
tool
list), `benchmarks/skill_evals/queries.jsonl`, and the frozen
vendored-fork
fixtures, and the `deep_research` deny rows in the five
`agents/*/config.json`
files (the same denylist argument as the migration; the launcher parity
tests
are unchanged).
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
- `uv run ruff check raven/ tests/` and `uv run ruff format --check
raven/ tests/`: clean.
- `uv run pytest -q` (whole suite, with coverage, at the rebased head):
25840 passed, 109 skipped; `python scripts/coverage_gate.py ratchet
--tolerance 0.05`: line 90.10% vs baseline 87.30%, branch 83.73% vs
79.43%, passed.
- `uv run pytest tests/test_config_loader.py
tests/test_config_update_tools.py tests/test_agent_loop_run_emit.py
tests/test_cli_one_shot_spine.py tests/test_rpc_bootstrap.py
tests/test_rpc_spine.py tests/test_rpc_turn_send.py
tests/test_turn_wire_shape_conformance.py tests/test_core_cron_stack.py
tests/test_cli_gateway_commands.py tests/test_cli_smoke.py
tests/test_acp_methods.py tests/test_rpc_console.py
tests/test_tool_registry_timeout.py tests/test_question_broker.py
tests/test_provider_auth_method.py tests/test_agents_ppt_launcher.py
tests/test_agents_design_launcher.py
tests/test_agents_research_launcher.py tests/test_tool_capabilities.py
tests/test_l4_entrances.py tests/test_settings_tool_groups.py
tests/test_trajectory_regressions.py tests/test_living_docs.py
tests/test_cli_onboard_commands.py tests/test_cli_theme.py -q`: 1500
passed.
- Mutation check on the migration: with the `_migrate_config` dispatch
neutered, three of the four new `tests/test_config_loader.py` cases
fail; with the `_persist_migrations` dispatch neutered,
`test_the_deep_research_section_also_leaves_the_file_on_disk` fails;
with the pre-review stripping behaviour restored, all four fail.
Restored: 74 passed.
- `npm test --prefix ui-web` (208 files, 2884 tests), `npm run lint
--prefix ui-web`, `npm run type-check --prefix ui-web`, `npm run
gen:check --prefix ui-web`: pass.
- `npm run lint:i18n --prefix ui-tui`, `npm run type-check --prefix
ui-tui`, `npm test --prefix ui-tui` (144 files, 2106 tests): pass;
`messages.generated.ts` regenerated with `npm run gen:i18n`.
- Grep gate: `grep -rniE 'deep[ _-]?research' .` (excluding
node_modules, .venv, dist) hits only the kept surfaces listed above plus
CHANGELOG history.
- Real machine, isolated `RAVEN_HOME` whose config carried
`tools.deepResearch` and `disabledTools: ["deep_research", "exec"]` with
a version-9 stamp: `raven agent -m "..."` printed the `Config updated:`
notice for `tools.deepResearch` once, answered, and left the file
without that section, `disabledTools` unchanged (`["deep_research",
"exec"]`), stamp 10; `raven deep-research` answers `No such command`;
the served WebUI (`raven serve`) Settings > Tools page lists 36 rows
with no `deep_research` and `exec` still off, and `ext.list` carries no
`deep_research`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- User-visible: the `deep_research` tool, the settings row and `raven
deep-research` are gone; a config that still carries the section loses
it once at load with a notice; a `deep_research` entry in
`tools.disabledTools` stays as written. Reports the tool wrote under
`<workspace>/deep_research/` stay on disk. Archived transcripts that
recorded a `deep_research` call replay with the generic icon and the raw
tool name instead of the `researched` verb.
- Coverage: the two deleted modules were well covered, but the live
totals sit several points above the committed baseline, so the ratchet
passes with room to spare (measured locally, see Verification).
- Rollback: revert the PR; the migration is additive on the stamp, so a
reverted build reads a migrated config unchanged (the section it would
have read is simply absent).
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#156 (its deep-research half no longer applies; tracing half unaffected)
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
A host deny rule bound the host's own tool calls and nothing it
dispatched.
The host answered every `session/request_permission` from an ACP
sub-agent
with the most permissive option (`raven/acp_client/permissions.py`), and
a
product launcher rendered its own config without the host's permissions
(Raven-Code pins `mode: ask` and carries no rules). Measured end to end
before this change: with `permissions.tools.exec {"curl *": "deny"}` and
`tools.exec.extraDenyPatterns ["\\bcurl\\b"]` on the host, a curl handed
to
Raven-Code asked the host, was answered "Allow for this session", and
hit a
loopback sink.
Refusals now travel, on both sides, because a refusal needs nobody to
answer:
- **Launcher side.** `product_render.write_rendered` merges the host's
`deny`
entries of `permissions.tools` and `tools.exec.extraDenyPatterns` into
every
product render (strictest wins; a product exec tier written as one
string
becomes the `*` fallback beside the host's patterns; a pattern that does
not
compile is left behind, as the host's own live reader leaves it). Every
launcher and the scaffold end in that call, and a test pins that. This
is
the half that matters for raven's own products: a call their own gate
allows never produces a request the host could refuse.
- **Host side.** The approver reads the command a request names
(`toolCall.rawInput.command`, as sent and unquoted, and every codex
`commandActions` entry) against the host's builtin deny list with
`extraDenyPatterns` and its `deny` rules, read live, and answers a match
with the agent's reject option (cancel only when none was offered). A
check
that raises refuses. A parse error is not a refusal. This also covers
third-party agents, for what they ask about.
- **Server side.** Raven's own ACP broker now sends a shell call's
command as
`rawInput.command` (redacted like the title), so a raven host can read
it.
- **Logs.** Both approver log lines (the INFO refusal, and the DEBUG
approval, which logged the agent's own title) go through the ACP
redactor,
since the command is the sub-agent's to author and the log is retained.
The
redactor moves from `raven/acp/redact.py` to `raven/security/redact.py`
(content unchanged but one docstring paragraph), because
`raven.acp_client`
may not import `raven.acp`, and one table beats a second copy.
Deliberately not changed: the ask tier and the mode. What no deny rule
names
is still approved, as before; routing the ask tier to the host's human
is a
separate decision. A rule added on the host reaches an already running
raven
product at its next launch (the host-side check is live, the render is
not).
Agents launched with a never-ask setting never send a request, so only
their
own configuration binds them. Docs (permissions, protocol backends, both
languages) and the `Unattended Approval` entry in `CONTEXT.md` say this.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Head 703c7ceaf, rebased onto main 3a463d6cd (`git range-diff` shows both
commits `=` against the reviewed 4f8e0af95; the head is linear again,
the two
"Update branch" merge commits are gone). At this head: the six focused
suites
480 passed, the e2e 2 passed, `git diff --check` clean, `make
lint-imports`
10 kept. The full suite was run at the same two commits on earlier
bases:
25878 passed / 109 skipped at ca5e5dc15 (shown below), 25881 passed /
110
skipped at 4f8e0af95, diff coverage 100% at both. Main's newer commits
touch
`CONTEXT.md` in a different entry and none of the other files here:
```
uv run pytest -q tests/test_subagent_acp.py tests/test_acp_redact.py tests/test_acp_permissions.py tests/test_acp_server.py tests/test_config_product_render.py tests/test_agents_code_launcher.py
480 passed
uv run pytest -q -n0 -m integration tests/integration/test_subagent_host_deny_e2e.py
2 passed (control run hits the sink; denied run does not, reply names the deny rule)
COLORTERM=truecolor make coverage (fresh worktree at ca5e5dc15)
25878 passed, 109 skipped in 619s
COVERAGE_BASE_REF=origin/main make coverage-diff
Diff coverage: 100.00% (120/120 executable changed lines)
uv run --frozen --python 3.12 --extra dev ruff check raven evolver agents plugins-dist tests scripts -> All checks passed
uv run --frozen --python 3.12 --extra dev ruff format --check raven evolver agents plugins-dist tests scripts -> 2084 files already formatted
make lint-imports -> 10 kept, 0 broken
make lint-deps && make lint-types -> no issues / All checks passed
git diff --check origin/main...HEAD -> clean
PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD -> exit 0
make check-commits; make check-pr-title; COMMIT_RANGE=origin/main...HEAD make check-large-files -> pass
```
Revert-to-red, one production file at a time restored to origin/main
(the
focused suites plus the e2e where it applies; measured on the first
commit
before the rebases, which touched none of these files):
| reverted | unit | e2e |
|---|---|---|
| raven/config/product_render.py | 12 failed | 1 failed (sink not hit:
the host approver refused it, reply "User denied this action"; only the
wording assertion fails) |
| raven/acp_client/permissions.py | 2 failed, 14 errors | - |
| raven/acp/permissions.py | 2 failed | - |
| all three | 15 failed, 14 errors | 2 errors |
The first row is the two halves covering each other: with the launcher
half
reverted the host half still stops the command. For the second commit,
each
log line's redaction reverted alone turns
`test_the_logged_refusal_and_approval_carry_no_credential` red (1 failed
each).
- [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: an ACP sub-agent (Raven products, Claude Code, codex) now
has a
command refused when it matches the host's deny rules or the builtin
catastrophe list, where it used to run. Hosts with no deny rules see no
difference except the builtin list. Rollback: revert this 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
Three follow-ups from running the web cold-start import against a real
EverOS with the maintainer's full `~/.claude` (19 memory-file sources,
about 1,150 distinct messages).
- **Import batches drop from 50 to 10 messages.** With a slower
extraction model (`qwen/qwen3.8-flash` via OpenRouter) a 50-message
batch took 2.4 to 7.4 minutes and six of seven memory-file sources died
on the six-minute bulk budget; the same batches took about 75 s on
`claude-sonnet-4-5`. Ten is the maintainer's call: a batch that finishes
well inside the budget on any model matters more than the fixed cost of
about 7 s that every add carries on the EverOS side (which is also why
it is not one message per add). Under the slow model the worst measured
per-message cost puts a batch of ten at about a quarter of the budget.
The 30k-character bound is unchanged.
- **A refused batch is retried with backoff before its source fails.** A
batch the memory service refused failed its source at once, and the next
source started at once; against the real service one two-minute
rate-limit window at the extraction provider (OpenRouter 429, which
EverOS retries only twice sub-second) took five sources down in 70 s,
each one's first batch running into the same wall, and a parse failure
on one model answer or one slow answer past the budget cost a source
each the same way. A refused batch is now sent again after 30 s, 60 s
and 120 s before the source counts as failed, whether the backend
returned False or raised; the wait polls the stop file every second so a
stop lands inside it.
- **A finished import with failures can be dismissed.** The rail row
showed the failure count and a retry but no close, so a run whose
failures did not clear stayed in the rail indefinitely. The close is now
offered on any finish; it hides that run by signature, and the failed
entries stay in the state file so a retry from the wizard or the CLI
still picks up exactly those.
The batch size takes part in the EverOS message id, so a run imported
under the 50-message batch is not deduplicated against a re-import under
10. No installation has completed a real-size import under either limit,
so nothing on disk depends on the old id.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_importer_orchestrator.py
tests/integration/test_import_e2e.py tests/test_everos_backend.py
tests/test_rpc_import_sync.py tests/test_cli_import_commands.py
tests/test_importer_phases.py tests/test_importer_state.py -q`: 313
passed. The batching tests now pin 120 messages to twelve batches of 10
and 160 messages to sixteen, `is_final` only on the last. New retry
tests: a batch refused twice lands on the third send with the recorded
waits, one refused every time fails after the last wait with `after 4
attempts` in the error, a raised store error is retried the same way, a
stop during a wait ends the run with the source unmarked, and `_pause`
returns as soon as the stop file appears (286 passed over the importer /
RPC / CLI / EverOS backend suites).
- `uv run ruff check` and `ruff format --check` on the touched files:
clean.
- ui-web `npm test`: 2550 passed across 190 files; `npm run type-check`
clean; `npm run lint` 0 errors (5 pre-existing warnings).
- Reverse checks: with `_BATCH_MSG_LIMIT` set back to 50 the batching
tests fail; with the retry loop reduced to a single send the retry tests
fail; with the stop check removed from the wait the stop test fails;
with the close restored to clean finishes only, the row test "offers a
retry, and a dismiss that takes the row down" fails.
- Real host: the 50-message failure mode was measured on a live gateway
(isolated `RAVEN_HOME`, throwaway EverOS on :18893, the maintainer's
real `~/.claude`): 6 of 7 sources timed out at exactly 360 s under
`qwen3.8-flash`. Reruns on the same host at batch 10 without the retry:
one 429 window took five sources, one 10-message batch still ran past
the budget. A rerun with the retry is in progress and will be reported
on this PR.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible: imports make five times as many EverOS calls, each
smaller; a source now checkpoints, and a stop lands, every 10 messages
instead of 50. A refused batch costs up to 210 s of waiting before its
source is given up on. The rail's finished-with-failures row gains a
close button.
The state file format and the RPC contract are unchanged. Rollback:
revert the squash commit; no data migration is involved.
- [x] Security impact considered (no new inputs, credentials or
endpoints)
- [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-fable-5-1) <noreply@anthropic.com>
## Summary
The onboarding wizard's data-sync step started a full cold-start import
and closed; nothing on the page showed the run again, a gateway restart
lost it silently, and the web path never landed the profile mirror or
the skills the CLI does. This PR closes all of that in one piece,
backend first.
Backend (`raven.importer`, `import.*` RPC):
- The two post-import phases move out of the CLI into
`raven/importer/phases.py` and run per platform on both paths. Hermes
keeps its `USER.md` entries and skills tree; Claude Code now contributes
the memory files it marks as being about the user (`metadata.type` of
`user` or `feedback`, deduplicated on the text) and the skills under
`~/.claude/skills` through a new `ClaudeCodeSkillSource`. The installer
lands each platform under `skills/<platform>/` and reports progress per
copy.
- `import.run` records the tier and platforms it was asked for in the
state file's `meta`; `import.status` returns them together with a `phase
{kind, current, total}` object while a phase is in flight (both
nullable, additive fields on the contract). A client that finds a run
stopped short can start the same request again without having remembered
it.
- A stop is honoured between the batches of one source, not only between
sources. The interrupted source keeps no entry and is sent whole next
time.
- The CLI keeps its own bar labels and TTY-aware provider; its
skills-only path and scan preview count every platform's skills.
- The store budget fix measured on 2026-09-20 rides along, folded from a
PR first opened against main and closed in favour of this one at the
maintainer's request (everything lands on the architecture branch): an
import write is tagged `bulk` and the EverOS backend gives it the
extraction budget instead of the per-message estimate, and the import
batch drops from 100 to 50 messages. Without it every real-size source
dies on the shipped 10 s store timeout, which is exactly what the new
row would then report.
Frontend (`ui-web`):
- A new `importSync` domain draws one row in the rail's foot, above
Settings, from `import.status` alone. States: scanning, the message pass
with its settled share, the phase in flight with its own count, paused
(nothing running, counts short of the total), finished (with how many
did not make it). It polls only while a run is on, stops a run with its
close button, and asks for the recorded request again when a paused or
partly failed row is clicked. A finished row is dismissed per run and
stays dismissed across reloads.
- The wizard's sync step imports memory files only (the store used to
start a full import silently). The maintainer's call: conversations take
many hours and are not offered from the web at all; the full tier stays
a CLI option (`raven import run --tier full`). The step shows each
agent's memory-file, conversation and skill counts so the reader knows
what is there.
- Found during acceptance and fixed here: the row's first status read
sat with the seam installers, before the socket connects, and was
refused as not connected; it now runs in the boot sequence after the
connection is up and again on reconnect.
Deliberately not in this PR: a way to force the "did not make it" state
in the real host (covered by unit tests and the offline fixture), and
the CLI tier labels (`minutes` / `hours`), which measurement has since
put at tens of minutes and many hours respectively.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Backend:
uv run pytest tests/test_rpc_schema_match.py
tests/test_rpc_import_sync.py tests/test_importer_state.py
tests/test_importer_orchestrator.py tests/test_importer_phases.py
tests/test_importer_claude_code_skills.py
tests/test_importer_hermes_skills.py
tests/test_importer_hermes_user_md.py tests/test_cli_import_commands.py
tests/test_cli_onboard_commands.py tests/integration/test_import_e2e.py
-q
908 passed
Reverse check: with `state.py`, `orchestrator.py`,
`skills/installer.py`, `import_sync.py` and `models.py` reverted and the
tests kept, 14 tests fail (the new state, orchestrator, installer,
phases and rpc cases); restored, all pass.
Frontend:
npm test --prefix ui-web 188 files, 2570 passed (gates included)
npm run gen:check --prefix ui-web generated.ts matches the contract (189
methods)
npm run type-check --prefix ui-web clean
npm run lint --prefix ui-web 0 errors (5 pre-existing warnings in
unrelated files)
npm run lint:i18n --prefix ui-tui generated catalogue is up to date
Reverse check: with the importSync store and page, the onboard store and
page and the import fixture reverted, 5 tests fail and the two
importSync test files no longer import; restored byte for byte, 48 pass.
Gates: ruff check and format on every changed Python file, commitlint
and `check_commit_messages.py` over the branch,
`check_source_language.py` over the branch, `make check-large-files` --
all pass.
Acceptance in the real host, driven with playwright-cli against `raven
web --foreground` from this checkout, an isolated `RAVEN_HOME`, an empty
EverOS root on its own port with real LLM and embedding credentials, and
a synthetic Claude Code home (global CLAUDE.md, one project memory
directory holding user, feedback and project memories, two real small
conversations, one skill):
- Wizard step 4 lists Claude Code with its counts and a switch, opencode
and codex as unsupported; the tier rows default to memory files and
their counts follow the switch. Start closes the wizard and the rail row
appears at once: "Syncing data 0%" -> 50% -> "Building your profile 1/2"
-> "Memory import finished" in 30s. On disk: two entries in
`user_memory/profile/user.md` (the project-typed memory correctly
absent), `skills/claude_code/demo-skill/`.
- Dismiss hides the row; a reload keeps it hidden.
- A full import stopped 5s in shows "Sync paused 75%" 8s later with a
clickable row; the gateway log has `import cancelled inside
.../<conversation>` and the state file has no entry for it.
- Killing the gateway, restarting it, re-authenticating and reloading
shows "Sync paused 75%" again from the state file. Clicking the row runs
"Syncing data 75%" to "Memory import finished" in 31s; the conversation
is then `submitted`.
- The CLI path over the same home (`raven import run --platform
claude_code --tier memory_files --yes`) shows the two phase bars
(`Mirroring profile [2/2]`, `Installing skills [1/1]`) and reports
`Profile: 2 entries into user.md`, `Skills: 1 installed`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (new copy
is in `i18n/messages.json`; no docs page describes the wizard yet)
After folding the store budget commits, on the branch head: `uv run
pytest` over the importer, EverOS backend, RPC and CLI import suites
plus `tests/integration/test_import_e2e.py`: 1095 passed; `ruff check`
clean; commitlint, `check_commit_messages`, `check_large_files`,
`check_source_language` and pre-commit green over the 8-commit range.
## Risk
The batch size takes part in the EverOS message id an import write
carries, so a run imported under the 100-message batch would not be
deduplicated against a re-import under 50; no import of real size had
completed under the old budget, so nothing on disk depends on the old
id.
User-visible: the rail gains a row while an import exists on disk; the
wizard's sync step imports memory files only where it used to start a
full import silently (conversations remain a CLI-only import);
`import.status` gains three optional fields. The CLI's skills-only path
now offers every platform's skills, and its scan line reads `Skills: N
importable` rather than `Hermes skills`.
The `import.status` additions are optional in the contract, so an older
client reading the new gateway is unaffected. A client that stores
nothing new: `localStorage` holds only the dismissed run's signature.
Rollback: revert the squash commit; no data migration is involved. The
state file's new `meta` keys are ignored by older code.
- [x] Security impact considered (no new inputs, credentials or
endpoints; the profile mirror reads the same files the importer already
reads)
- [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-fable-5-1) <noreply@anthropic.com>
Wire capability-controlled generated Harness parameters and participant functions through generation, validation, Charter transport, and both worker execution lanes. Preserve the standalone kernel boundary and retain follow-up hardening in #603.
## Summary
The browser existed on every side except the model's: `raven/browser`
drives a
Chromium the panel streams over CDP, and `browser.*` RPC gives the
reader hands
on it, but `raven/agent/tools/` had no browser tool at all -- a model
asked to
open a page had nothing to call. This registers eight `browser_*` tools
over
that same driver, with no MCP hop, so the page the model drives is the
page the
panel shows and a human can take the keyboard mid-task.
Desktop control reuses `macos-mcp` through the MCP client that was
already
there; the only new code for it is a market catalog entry.
What the tools add beyond the driver:
- **Reading back.** Every acting call returns the page as it is
afterwards
(url, title, the actionable refs, the visible text), so the next call
can be
aimed without a separate read. `browser_screenshot` is the one that
costs an
image and is asked for on purpose; it goes out as an image block.
- **Who is acting.** Each call names an owner -- the sub-agent run in
flight,
else the conversation -- and the driver binds that owner to a tab. Two
agents
work in two tabs, neither can activate or close the other's, and a popup
a
click opens becomes the opener's tab. A reader's own clicks carry no
owner:
they are stamped, and the owner's next readback says the user touched
the
browser, once.
- **Permissions.** Reading and navigating default to allow, on the
`web_fetch`
reasoning (opening a page is a GET the agent could already make, and
`raven.browser.policy` refuses what a GET must not reach). Clicking,
typing
and pressing ask, keyed by site rather than by ref, so one approval
covers a
site for the conversation.
- **Config.** `tools.browser.headfulOnAgentUse` pops the shared browser
out
into a real window on the model's first use. Off by default: a server
has no
desktop to pop into.
The tool surface grew, so the `reserved_tools` tripwire moved:
descriptions
were trimmed first (~1270 to ~1090 tokens) and the bound raised from
6000 to
7400 against a measured 7115, with the trade written beside it. The
schemas are
only present where the browser extra is installed; without playwright
the tools
report themselves unconfigured and never reach the request.
No ui-web changes are in this PR. The web UI side of this work (a
browser pane
in the desk, a per-tab miniature, docking) is written against surfaces
that
`refactor/ui_web_architecture` removes, so it waits for that branch to
land.
## Type
- [x] Feature
## Verification
- `uv run pytest tests/ -q` -> 23755 passed, 121 skipped, 1 failed. The
failure
is
`test_cli_onboard_commands::test_clearing_does_not_disturb_a_key_the_user_exported_themselves`,
which reads the developer's own shell environment and fails the same way
on
an unmodified `main` in this checkout.
- `uv run pytest tests/integration/test_browser_tools_real_web.py -q` ->
6
passed against a real Chromium and a local form: fill and submit, a
screenshot arriving as an image block, two owners in two tabs with
neither
able to take the other's, a read leaving the front tab where the last
actor
put it, a `target=_blank` popup landing its opener on the new tab, and a
scripted model driving `AgentLoop`'s default tools end to end -- the
gate
asking once for the site, the grant covering the click that follows, and
the
panel's `browser.frame` returning the page the model left.
- `uv run ruff check raven tests`, `uv run ruff format --check raven
tests`,
`uv run lint-imports`, `make check-source-language`, `make
check-large-files`
-> clean.
- Desktop side exercised by hand through raven's own MCP client, over
stdio and
over streamable-http with a bearer token: launch Calculator, read its
accessibility tree, click 2 + 3 =, read the result back. Screenshots
arrive
as image blocks.
Not verified: the desktop flow was driven by a script rather than by a
model in
the loop; sub-agents that run in their own process (the ACP and cli
lanes) have
their own `Browser` singleton and are not given these tools; Windows and
Linux
desktop executors were not chosen.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Notes. The acting verbs sit on the ask tier by default and a grant is
scoped to
a site and a conversation, so an approved click on one host does not
carry to
another. Navigation goes through the existing outbound policy. The
desktop MCP
server runs locally under `uvx` and needs macOS Accessibility and Screen
Recording grants, which the operating system asks for itself; the
catalog entry
is opt-in like every other market entry. Nothing here changes an
existing
default: without the browser extra the tools are absent, and with it the
only
new always-on cost is the tool schema.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
The one-line installers are served from `main` and install the latest
published release, so an ending on `raven web` (PR #476) shipped against
v0.1.13, which has no `web`: since 2026-09-17 every `curl
raven.evermind.ai/install.sh | sh` has ended in `No such command 'web'`
with exit code 2. This PR fixes that class of failure and the upgrade
defect behind the next release.
- **Probe rule.** Every `raven <sub>` call in `install.sh` and
`install.ps1` is preceded by `raven <sub> --help`. When the probe fails
the install ends on the one command every release has (`raven`), and
neither the stop nor the page's own exit code becomes the script's.
`RAVEN_NO_LAUNCH=1` skips the launch (CI, Dockerfiles); the PATH hint
the launch displaced is back.
- **The release says what it ships.** `release.yml` writes
`raven-plugins.txt`, one `name @ url` line per plugin wheel it just
built, beside the wheel and the constraints. Both installers derive
every URL from the release page redirect and hand the list to `uv tool
install --with-requirements`. No GitHub API call, no grepping asset
names out of its JSON. A release without a list (0.1.13 and older)
installs raven alone, as it effectively did before.
- **Upgrade keeps the plugins.** uv replaces a tool's requirement set
with what one command names, so the old helper (`raven[channels]` only)
uninstalled every plugin the installer had put in. The helper now
installs from the same list, descends one loss at a time (engines, then
the memory plugin, then the channel extras), and refuses to run without
the list rather than install raven alone. `raven upgrade` on an
up-to-date install whose list names a plugin it lacks reinstalls the
version with its plugins. The helper also moves a beta wheel URL's
deploy token into the request header (urllib reads `user:token@host` as
a host name) and copies it onto the list's URLs for uv.
- **Gates.** CI installs the latest release with the PR's scripts,
piped, on ubuntu and windows whenever an installer changes. The release
job installs itself from `dist/` with `install.sh` before the draft is
created and asserts the three plugin packages and `web` on the result.
The beta publisher builds and lists the same three plugin wheels. A
contract test holds the release workflow, the beta publisher, both
installers (remote list and local clone mode) and the helper to one
plugin list.
Decisions, for the reviewer: the plugins are not published to PyPI and
no names are reserved there; the list carries direct URLs, so no plugin
is ever resolved by name against an index. The LibreOffice and chromium
steps in the scripts are unchanged. The three hosted-memory plugins
(mem0, zep, memos) are built and uploaded as before but stay off the
default list.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All installs below ran piped (`cat install.sh | sh`) in isolated
directories (own HOME, UV_TOOL_DIR, UV_TOOL_BIN_DIR, UV_CACHE_DIR,
RAVEN_HOME) with `RAVEN_MINIMAL=1`.
- `main`'s `install.sh` against the live latest release (v0.1.13): exit
2, `No such command 'web'`. This branch's `install.sh`, same
environment: exit 0, `Raven installed. Open a new terminal ... then run:
raven`; `raven --version` prints 0.1.13. With `RAVEN_NO_LAUNCH=1`: exit
0.
- A local release directory built by `scripts/publish_beta.py` (`_build`
at 0.1.14b1: raven wheel, three plugin wheels, constraints, list): this
branch's `install.sh` with `RAVEN_WHEEL_URL=file://...` installs raven
0.1.14b1, `python -c "import raven_everos, raven_design, raven_ppt"`
succeeds in the tool venv, and the uv receipt lists raven plus the three
plugins.
- The release workflow's two new step bodies (`Write the plugin list`,
`Install the release from dist with install.sh`) extracted and run
locally against that build: exit 0; removing one plugin wheel makes the
list step exit 1.
- The script's ending against the 0.1.14b1 install: `raven web --help`
exit 0, `raven web --stop` exit 0 with nothing to stop, `raven web
--foreground --port 18999` answers `GET /` with HTTP 200 after about 20
seconds.
- `uv run raven upgrade` and `uv run raven upgrade --check` from the
checkout against live GitHub: `Raven 0.1.13 is up to date.`, exit 0.
- `uv run pytest tests/integration/test_cli_upgrade_real_uv.py`: 2
passed. The test now installs the old fixture `--with` a companion wheel
and asserts the companion survives the upgrade; against `main`'s helper
the same test fails on that assertion.
- `uv run pytest tests/test_install_script.py
tests/test_release_plugin_list.py tests/test_updates_upgrade.py
tests/test_publish_beta.py tests/test_cli_smoke.py`: all pass (37 + 6 +
188 on the last run of each).
- `uv run pytest` (full suite, before the last installer rewrite): 23543
passed, 121 skipped, 4 failed. The 4 (`test_agents_oncall_launcher`,
`test_agents_code_launcher`, `test_agent_loop_token_budget`,
`test_ppt_engine_image_search`) fail identically on plain `github/main`
in a separate worktree.
- `uv run ruff check` and `uv run ruff format --check` on every touched
Python file: clean. `sh -n install.sh`, `bash -n install.sh`: clean.
Both workflow files parse.
- Not run here: the new CI job's Windows leg and the release gate inside
GitHub Actions (this PR is their first run). `install.ps1` has no local
PowerShell to execute it; its changes mirror `install.sh` and are pinned
by the text tests.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes: the installers no longer fail on a release without
`web`; they print the plugins they install and a warning when a release
carries none; `raven upgrade` refuses to proceed when the target
release's plugin list cannot be fetched (previously it would install
raven alone and drop the plugins), and repairs an up-to-date install
that lacks listed plugins. The beta channel's next publish carries the
three plugin wheels and the list; a beta upgrade to a build published
before this change will refuse for lack of a list, and rerunning the
beta installer is the remedy.
Rollback: revert the commit. Releases published with `raven-plugins.txt`
keep working with the old scripts, which ignore the file.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
- Gather every active `ParticipantHook` seat for a phase and pass the
complete registration-ordered roster to the Memory, Planning,
Capability, and Action roles in one delegated call.
- Preserve default composition, diagnostic trails, nested product axes,
addendum replacement, and outbound transformation behavior.
- Isolate participant factory and axes discovery failures, and always
clear phase roster state.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
- `uv run ruff check --no-cache raven plugins-dist agents tests` -
passed.
- `uv run ruff format --check raven/agent/hook/composite.py
raven/agent/hook/participant.py tests/test_participant_hook.py
tests/integration/test_participant_roster_e2e.py` - 4 files already
formatted.
- `uv run lint-imports` - 10 contracts kept, 0 broken.
- `uv run pytest -q tests/test_participant_hook.py
tests/test_agent_hook_contract.py tests/test_core_stacks.py
tests/integration/test_participant_roster_e2e.py
tests/integration/test_subagent_charter_e2e.py
tests/integration/test_agent_playbook_e2e.py` - 124 passed after
rebasing onto the latest `main`.
- The full default suite was also compared against the same-HEAD
baseline in the same environment. Error counts were identical; one
existing research test fluctuated under parallel execution and passed in
isolation.
- Documentation and screenshots are not applicable because this refactor
has no user-facing UI or configuration change.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The grouped role decision runs at the last active participant position.
An interleaved non-participant hook before that position therefore runs
before the grouped decision; a regression test pins this ordering. A
failing participant factory is omitted from the roster without blocking
the remaining participants. Rollback is a revert of this PR.
## Related Issues
N/A
---------
Co-authored-by: yao pengfei <yaopengfei@shanda.com>
## Summary
Raven speaks the Agent2Agent protocol, version 1.0, in both directions.
The host
agent is the peer: nothing here makes a sub-agent addressable from
outside, and a
raven launched as a sub-agent refuses to serve the face at all, because
it is
already reached over ACP by the host that started it.
Inbound is an aiohttp face carrying the two cards and a JSON-RPC
endpoint. It
mounts on the gateway when `a2a.server.enabled` is set, and `raven a2a
serve` runs
it standalone for a headless deployment, where running the command is
itself the
opt-in. Outbound is a single tool, `a2a_send`, that takes a card URL and
a message;
it enters the tool list only when `a2a.peers` is non-empty, so a host
with nowhere
to send a message does not carry the schema. The two switches are
deliberately
independent: calling out and being called are separate deployments.
Onboarding mints `a2a.server.token` and stops there. The face ships
closed:
finishing an unrelated install is not consent to open a second network
surface, so
`raven a2a enable` is what opens it, and it is the only writer of that
flag.
Enabling mints a missing token in the same command, because a face
switched on with
an empty token answers every caller with a 401 and reads as a broken
deployment
rather than the closed door it is. `raven a2a disable` closes it again
and keeps the
token, so reopening does not re-issue a credential callers already hold.
The wizard
never writes the flag at all, not even as false, so a repeat onboard
leaves a face
the operator opened by hand alone. A config nobody onboarded, and any
`A2aConfig()`
assembled in process, stays inert.
What that opens is narrower than a network face. The app carrying it
binds loopback
at both call sites, hardcoded rather than read from config, and every
request is
checked against a freshly minted 256-bit bearer token. The minting write
is also
what fixes `config.json` to owner-only, from the temporary file's first
byte rather
than with a chmod afterwards; a later enable or disable adds no secret
material, so
it leaves whatever mode the operator chose. Nothing else narrows that
file and it
already held provider API keys, so the obligation predates this work and
is merely
discharged here.
There are two cards because the protocol splits one description across
two
authentication states. The public card answers an unauthenticated GET,
and has to:
a caller reads it to learn which scheme to authenticate with, so
requiring the
credential first would be circular. It therefore names no installed
agent. The
extended card is a `GetExtendedAgentCard` RPC riding the same bearer
check as every
other method, and is the only one of the two that may say what this host
can
actually do.
On that extended card the sub-agent roster rides
`capabilities.extensions`, not
`skills`. A skill is the protocol's word for something an agent can be
asked to do,
and a peer cannot ask for one named sub-agent: it can only send a
message to this
host, which then decides what to dispatch. One skill per sub-agent would
advertise
call targets that do not exist. What a peer can genuinely request is the
orchestration, so that is a single skill, and the roster moves to the
protocol's
own extension point under a versioned URI. That is the only place a
conformant card
may carry a payload the spec does not define, because `AgentCard` is a
closed set
of fourteen protobuf fields: a custom top-level key is rejected by a
strict parser
and silently dropped by a lenient one. The entry declares `required`
false, so a
reader that has never heard of the URI ignores it and still talks to
this host.
Both cards derive `supportedInterfaces[].url` from the origin the caller
arrived
on. One face answers under every name that routes to it, and a URL fixed
when the
face is mounted is right for at most one of them. This matters more than
it looks:
a caller that finds an interface off the card's own origin must refuse
it, since a
card fetched from a trusted origin would otherwise redirect the
credential
elsewhere, and a relative URL reads as off-origin to that check.
## Type
- [x] Feature
## Verification
- `make test-python` at this head: 23729 passed, 112 skipped, 1 failed,
in 288 s.
The one failure is
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
which fails with the same assertion on `origin/main` by itself; this
branch changes
no install or node file.
- `uv run --frozen --all-extras pytest
tests/integration/test_a2a_protocol_e2e.py -q`:
6 passed. That directory sits outside the default pytest scope, so it is
run by
hand rather than reached by the line above.
- `make lint-imports`: 10 contracts kept, 0 broken. `make lint-types`:
all checks
passed.
- `uv run ruff check raven/ tests/`: clean. `ruff format --check`:
clean.
- `make check-commits` over all 68 commits, `make
check-source-language`,
`make check-large-files`: all exit 0.
- Live, over a real network boundary rather than in process: a raven in
a Docker
container and a raven on the host, each running this branch, called each
other in
both directions. Nineteen assertions per direction covering both cards,
the four
refusal paths, and a completed turn. The container publishes its face on
a
different port than it binds, so the card has to name the port the
caller used and
not the socket the server opened; both cards did, in both directions.
That run
predates the default-off change described above, which touches no file
under
`raven/a2a/` or `raven/a2a_client/`: both packages are byte-identical to
the head
it ran against.
- Reverting each fix turns its own tests red, checked one fix at a time
rather than
all together, including the interface-URL fix mutated out inside the
running
container.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour changes for an operator who runs `raven onboard` after this
lands: a
token is minted into `a2a.server.token`, and `config.json` is narrowed
to
owner-only. No listening face is opened. Opening one takes `raven a2a
enable` and a
gateway restart, so the second network surface only ever exists because
somebody
typed for it.
Rolling an opened face back is `raven a2a disable` and a restart. The
token stays in
place and is never rotated, so callers already holding it keep working
when the face
is reopened, and a later onboard will not reopen it by itself. Nothing
else in the
install changes.
Costs and limits, stated rather than left to be discovered:
- A gateway that serves A2A imports `a2a-sdk`, measured at roughly 570
ms and 391
modules on top of the gateway's own stack, sqlalchemy and the
OpenTelemetry api
among them. It is paid once at mount, not per request, and an operator
who
switches the face off pays none of it. Moving it to the first request is
recorded
as deferred in the design note rather than done here.
- `a2a_send` adds 157 tokens to the tool array of every turn, measured
off a
captured provider call, and only on a host with a peer configured.
- The task store is in memory and unbounded, and inbound concurrency is
not capped.
A local face behind a bearer token is the deployment this is written
for; a
host exposed more widely should bound both first.
- Pulling in `a2a-sdk` brings the OpenTelemetry api into the gateway's
import
graph. This is a trade accepted for the SDK's protocol types and
handler, not an
adoption of OpenTelemetry by this project.
Checked during review and deliberately not fixed here: config validation
accepts an
agent row with an empty or whitespace name, which would reach the
extended card's
roster as an empty entry. It is not introduced by this work, the
previous shape
carried the same value, and closing it belongs with the agent schema
rather than
with the card.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
The search dialog stacked two controls in one corner and seated neither
on
the line the query is typed on.
The theme places its clear button at a fixed distance from the form's
top,
an offset that centres the button only in a form of the theme's own
height.
This dialog's form is taller, with two consequences from the one cause:
the
button sat 10px above the magnifier and the text beside it, and it
landed in
the same corner as the chip naming the key that opens search,
overlapping it
by 21px.
The button is centred against the form box and against its own container
now, so it follows whatever height the form takes rather than assuming
one.
The chip is confined to the closed state, where it is still true: a
reader
already inside the dialog has nothing to press that key for, and the
field
left in the rail keeps its chip and is unchanged in both states.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Clicking always reached the button, overlap and all, so a guard written
around the click would have passed while the fault was plainly visible
in a
screenshot. The guard measures the boxes instead: the chip and the
button
must not intersect, and the button's centre must be within a pixel of
the
magnifier's. Run against the unchanged site it reports a 21px overlap
and a
10px drift, which is how the fault was confirmed before it was fixed.
Measured in a real browser at 1560x820, vertical centres in the open
dialog:
| element | before | after |
| --- | --- | --- |
| form box | 195 | 195 |
| magnifier | 195 | 195 |
| query text | 194.5 | 194.5 |
| clear button | 185 | 194.5 |
- `uv run pytest tests/integration/test_docs_site_controls_e2e.py
tests/integration/test_docs_site_search_e2e.py` -> 30 passed
- `make lint-python`, `make lint-imports`, `make lint-deps`, `make
lint-types`
-> exit 0, against an environment synced the way CI installs
- `pre-commit run --from-ref origin/main --to-ref HEAD`, `make
check-commits`,
`make check-source-language`, `make check-large-files` -> exit 0
- `mkdocs build --strict` -> built
- captured the rail at rest, the rail while the dialog is open, and the
dialog itself: the rail is identical in both states and the dialog's
corner holds one control
## Risk
User-visible and confined to the open search dialog above the desktop
breakpoint: the clear button moves down onto the centre line, and the
key
chip no longer appears while the dialog is open. Narrow viewports keep
the
theme's own full-screen search untouched.
Rollback: revert the commit. The change is two rules in one stylesheet,
and
either can be dropped on its own.
## Related Issues
N/A
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
Chinese runs no spaces, so the indexed text carried no word boundary at
all.
The search separator broke on whitespace and hyphens, which left each
Chinese
run as a single token, and a reader who typed a word rather than a whole
heading found nothing.
Two things had to line up, and neither works without the other:
- the build segments the text with jieba, which marks every boundary
with a
zero-width space. jieba was reaching the build only as a transitive
dependency of another group, so it was absent wherever the docs group
was
installed on its own, which is every build that ships. It is declared
now.
- the separator breaks on that mark. The whitespace class the theme
defaults
to does not cover it, so the marks stayed buried inside the token.
The guard for this passed while the site was broken, which is worth
saying
plainly. It took its query from the page's own heading, boundary marks
and
all, and a query carrying those marks matches the stored token exactly.
No
reader can type that string. The query strips the marks now, and a
second
guard searches a word taken from the middle of a title, which can only
be
found if the run was indexed as words rather than kept whole.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Measured on a site built inside an environment holding only the docs
group,
served locally and driven in a real browser, searching the Chinese site.
Repeated three times with identical counts:
| query | before | after |
| --- | --- | --- |
| a word from the middle of a heading | 0 | 36 |
| a single-word heading | 5 | 12 |
| another single-word heading | 5 | 10 |
| a compound the segmenter splits | 5 | 0 |
The same measurement against the published site reproduced the "before"
column exactly, which is what says the local environment matches the one
that builds it.
- `uv run pytest tests/integration/test_docs_site_search_e2e.py
tests/integration/test_docs_site_controls_e2e.py
tests/test_docs_site.py` -> 34 passed
- both new guards were mutation-tested: with the separator reverted, the
build guard reports that the separator does not break on the boundary
and
the browser guard finds nothing for its word
- `make lint-python`, `make lint-imports`, `make lint-deps`, `make
lint-types`
-> exit 0, run against an environment synced the way CI installs, not
the
working one
- `make check-commits`, `make check-source-language`, `make
check-large-files`,
and `pre-commit run --from-ref origin/main --to-ref HEAD` -> exit 0
- `mkdocs build --strict` -> built, 146 of 146 Chinese entries carry
word
boundaries
## Risk
User-visible: Chinese search returns results for ordinary words where it
returned none. One case gets worse: a compound the segmenter splits into
parts is no longer found, because the theme does not segment the query,
so a
run that is not itself a word no longer matches any token. A custom
segmenter dictionary would recover those; it is not in this change.
Rollback: revert the commit. The two halves are one line of mkdocs.yml
and
one dependency entry, and dropping either one restores the previous
behaviour on its own.
## Related Issues
N/A
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
The documentation site built one search index for both languages, so a
reader on
the English pages was offered Chinese ones: results they cannot read,
behind
links that leave the language they chose. A build hook now splits the
merged
index in two and points the Chinese pages at their own copy, which the
theme
also resolves every result link against.
Where that split runs is the whole fix. The merge lands in a plugin's
own
`on_post_build`, so the split has to be the last thing that event does.
Running
it on `on_shutdown` looks equivalent and is not: `mkdocs serve` never
shuts
down, so the preview went on serving the merged index however often it
rebuilt.
The new guard makes the same assertion against `mkdocs build` and
against
`mkdocs serve`, because passing one says nothing about the other.
The rest settles the shell against the reference layout:
- the rail's foot is its own box the navigation cannot show through, and
the tab
icon is the EverMind mark;
- the footer keeps to the content column instead of covering the fixed
columns
once the reader reaches the page foot;
- the contents column reaches the screen foot with its scrollbar hidden
behind a
fade, and follows the reader by centring the first lit entry;
- search opens as a centred dialog over the page. The form itself
travels into
that dialog, so what stays in the rail is drawn from the field's own
metrics
and its shape does not change on a click. Neither state animates: the
theme
transitions the two shapes into each other, and leaving search played
that out
in the corner of the page after the reader had moved on.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/integration/test_docs_site_search_e2e.py` -> 2
passed.
Without this change the preview case fails: the Chinese index is HTTP
404 and
the English index carries 146 Chinese pages.
- `uv run pytest tests/integration/test_docs_site_controls_e2e.py` -> 25
passed
- `uv run pytest tests/test_docs_site.py
tests/test_source_language_check.py` ->
31 passed
- `make check-commits`, `make check-source-language`, `make
check-large-files` ->
exit 0; `ruff check` on the added files -> no findings
- `make docs-build` -> the root index holds 149 entries and no Chinese
page; the
Chinese index holds 146, none of them addressed from the site root
Driven in a real browser at 1560x820 in both languages: a word that
appears in
both trees returns 10 results and 0 from the other language, and the
corner of
the page is pixel-identical to its never-opened state at every frame
after
leaving search. Every page of the built site was checked at the page
foot (28
pages, 0 faults) for a footer covering a column, for a column whose last
entry
cannot be reached, and for the rail's foot icons being clickable.
No page content changed, so nothing else needed updating with it.
- [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: search no longer returns pages from the other language,
and the
search control, the footer and the two fixed columns change shape. The
field
left in the rail while the dialog is open is a drawn replica, and every
rule
behind it sits above the theme's desktop breakpoint, so narrow viewports
keep
the theme's own full-screen search untouched.
Rollback: revert the commit. The hook is one file, and dropping it from
the
`hooks:` list in `docs-site/mkdocs.yml` restores the previous merged
index on
its own.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
Stands up a bilingual MkDocs site under `docs-site/`, published to
GitHub Pages
by a workflow that builds on every pull request and deploys only from
`main`.
Fourteen topics ship in English and Chinese: the quick start,
self-hosting,
Docker, the WebUI, the sandbox manual, the runtime architecture, the
command
reference, the repository layout, the developer workflow, the
proactivity design
and reference pair, the self-evolution map and the tracing API.
This pull request is additive. Both READMEs keep their prose and gain
one link
to the site in the header row; trimming them is deliberately a second
pull
request, so the site can be confirmed live before anything depends on
it.
Key decisions:
- **`docs-site/`, not `docs/`.** `docs/README.md` defines `docs/` as
design
notes and dated records, and `docs/plans/` is an archive explicitly not
held
to today's layout. A user manual has the opposite lifecycle.
- **Full bilingual parity**, via the `mkdocs-static-i18n` suffix
structure
(`page.md` beside `page.zh.md`). Parity decays immediately without a
guard, so
a test fails when a page has no twin.
- **Anchors are pinned on the Chinese side.** A CJK heading slugifies to
nothing, so Markdown numbers it `_1`, `_2`, and inserting one heading
renumbers every anchor below it, silently breaking links readers already
hold.
Each Chinese heading therefore states the anchor its English twin gets
for
free: 133 heading anchors, identical across the two languages, none
positional.
- **A left rail, not a top bar.** The header carries the brand, the
search box
and the navigation tree down the left; the table of contents on the
right is
one continuous polyline clipped to the headings currently on screen.
- **No template overrides.** Material customises through
`theme.custom_dir` with
Jinja partials, those partials are `.html`, and
`scripts/check_large_files.py`
holds `.html` in `BLOCKED_ASSET_EXTENSIONS`. The skin is therefore one
stylesheet remapping Material's own custom properties, plus one script
for the
table-of-contents rail. The brand mark is a `data:` URI for the same
reason.
- **An owner-signed `docs-site/` exemption zone** in AGENTS.md section
1.3. The
i18n config carries the Chinese navigation labels, and `mkdocs.yml` is
not
`*.md`, so the blanket suffix exemption does not reach it. A contract
test
holds the AGENTS.md list and `EXEMPT_PREFIXES` equal, so both moved
together.
- **The site never links out to a file it does not host.** Documents
that stay
in the repository are named as plain paths rather than linked, and a
guard
fails a page that links to an external webpage or a repository-relative
path.
Two defects found and closed here rather than after publication. The
Chinese
site rendered an English sidebar: navigation labels live in
`mkdocs.yml`, not in
any page, so comparing the two languages' Markdown finds nothing and
only the
rendered output shows it. And a control could be present, sized,
animated and
answer `querySelector` while being unclickable, because a popup Material
sized
for a top bar landed outside the viewport once the header became a rail.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All commands run at the pushed head, rebased onto `origin/main`.
```
make check-large-files exit 0
make check-source-language exit 0
make docs-build exit 0, 0 errors
docs-site/site/index.html and docs-site/site/zh/index.html both present
mkdocs_static_i18n: Translated 17 navigation elements to zh
uv run pytest tests/test_docs_site.py tests/test_source_language_check.py \
tests/test_readme_scope_canon.py tests/test_docker_runtime.py \
tests/test_living_docs.py 44 passed
uv run pytest tests/integration/test_docs_site_controls_e2e.py 13 passed
pre-commit run --files <changed files> all hooks pass
git diff --check clean
```
Anchor parity was measured on the built HTML rather than assumed: 14
page pairs,
133 heading anchors compared at h2 through h6, every one identical
between the
two languages and none positional.
The controls are hit-tested rather than queried.
`document.elementFromPoint` at
the exact point a reader clicks must return the control itself, which is
the
only check that catches an off-viewport popup; the language switcher,
the search
panel, the repository link and the table-of-contents rail each pass it.
The brand lockup is measured, not eyeballed. A failing test was written
first
and reported the wordmark sitting 4.00px below the mark's centre line;
it is
0.00px after the fix, and a 4x screenshot puts the residual optical
offset at
0.25px.
Every guard this branch adds was confirmed to fail first. The
brand-class guard
was mutated from both sides in turn: renaming `.em-eyebrow` in the
stylesheet
turned it red, renaming `class="em-standfirst"` in `index.md` turned it
red, and
it is green again with both restored. The anchor guard was shown to
catch both
failure modes, a missing anchor and a wrong one.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
No behaviour change to any shipped code path. Nothing imports
`docs-site/`, the
new Makefile targets are additive, and the only change outside
`docs-site/` and
its tests is one link added to each README's header row.
Rollback is deleting the branch: the site does not exist until Pages is
enabled
with `Source: GitHub Actions`, and every other change is inert without
it.
Disclosed residue, checked and deliberately not changed:
- The README header now links to `https://evermind-ai.github.io/Raven/`,
which
404s until Pages is enabled. It is the same URL the Documentation
section
already carries.
- The `deploy` job is skipped on pull requests by design, so a green
check here
does not prove deployment works. The first real evidence is the `deploy`
job's
own conclusion on the `main` run after merge.
- GitHub Pages is not enabled on this repository. Measured: `GET
/repos/.../pages`
returns 404. Under `Deploy from a branch` the uploaded artifact is
silently
ignored while the workflow still reports success, so the source must be
set to
`GitHub Actions`.
- `tests/integration/` is excluded by `norecursedirs`, so the browser
suite is a
local guard and never runs in CI.
- The self-hosting page's Makefile target, docker path and port claims
are
unguarded. They were equally unguarded in the README they came from, and
the
owner ruled against adding a guard for them.
- The self-evolution SOP and the benchmark contract stay in the
repository and
are named as plain paths from the pages that reference them. The SOP is
a
translation of an upstream project's internal document and carries
redaction
placeholders, which is a publication decision rather than a formatting
one.
- `docs/plans/` still shows the pre-restyle `mkdocs.yml`. CONTEXT.md
defines that
directory as an archive of the tree as it stood, with an explicit rule
against
updating an old plan to match a later change.
- The Chinese pages drop the brand's italic serif accent word. Cormorant
Garamond
carries no CJK glyphs, so it would fall back to another face without any
sign.
- The code font is Material's default Roboto Mono. The brand names four
typefaces and no monospace, so none was invented for it.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
The agent loop already names four strategy roles (Memory, Planning,
Capability, Action), but two judgements a turn makes still lived in the
shell around them. This moves both onto the roles, in two dependent
commits, with no behaviour change intended.
**1. The charter reads through Memory and Action.** A dispatched
sub-agent's playbook (`_meta["raven.playbook"]`) was read from four
places inside the loop and the tool registry. `prompt` and `stopWhen`
are now read by `DefaultMemory.assemble()`, which fills `task_brief` and
`task_done_when` on the `TurnContext` the identity segment renders.
`checks` and `code` are read by `DefaultAction.judge()`, which
`ToolRegistry.execute` asks once per proposed call, the way it already
asks the permission gate. `tools` stays in `withheld_names()` and the
registry still decides what a refusal does, so a replaced role withholds
nothing it could not already withhold.
**2. Mid-turn window shrinking seats on Memory.** The five recoveries
the loop ran inline go through one method,
`MemoryModule.shrink(messages, pressure, state, model)`, with
`WindowPressure`, `WindowState` and `ShrinkResult` as the carriers:
- proactive compaction, once the last billed reading crosses the trigger
- the standing image window
- a provider's overflow error
- a picture refused inside a tool result
- pictures refused for size
The retry mechanism stays in the shell. The six `continue` sites and the
iteration rollback did not move, so a hook sees a retried call exactly
as it saw the first. `WindowState` is a per-turn object the shell owns
and hands to each call, because the role outlives the turn;
`image_window` has no default, since 0 is a real value meaning "no
picture stays".
The pure pieces both sides need move to a new package,
`raven/agent/window/`, which the import contracts treat as cargo that
may not import the loop shell. `REASONING_EFFORT_LADDER` moves to
`contracts/llm_provider.py` because the loop's empty-response descent
and the window's head summary both read it and neither package may
import the other.
Contract papers: `CONTRACTS_VERSION` 26 to 28, `CONTRACTS_LINE_CEILING`
3,040 to 3,200, each bump with its own review paragraph in
`tests/test_kernel_budget.py`.
A follow-up PR carries the third step, which gives a sub-agent nine
verbs in place of the six hook phases. It is kept separate because it
touches every bundled plugin.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Gates, run at each of the two commits:
```
uv run ruff check --no-cache raven evolver agents plugins-dist tests scripts
uv run ruff format --check --no-cache raven evolver agents plugins-dist tests scripts
uv run lint-imports
uv run pytest -q
npx commitlint --from origin/main --to HEAD --config commitlint.config.cjs
uv run python scripts/check_commit_messages.py origin/main..HEAD
uv run python scripts/check_source_language.py origin/main..HEAD
uv run python scripts/check_large_files.py origin/main..HEAD
```
Import contracts: 10 kept, 0 broken at both commits. The suite is green
at both; the failures this machine shows are the same ones it shows on
an unmodified `main` (missing browser and optional packages), and
neither commit adds one. The loop's own e2e files, which the default
selection leaves out, were run too (charter, playbook, truncation,
direct chat, fallback chain, ACP stdio): no failure that `main` does not
also show.
Behaviour preservation. Each commit was run against a worktree of its
own parent under the same scripted provider, outputs normalised for
nonces and temp paths, then byte-compared. Four scenarios, eight
comparisons, all identical:
- a whole turn with no playbook: host turn, spawned sub-agent, tool
calls and refusals
- a playbook-on worker lane in process, including two charter refusals
- six window-shrink scenarios: proactive compaction, the standing image
window, overflow, a refused picture, oversized pictures, the effort
ladder
- the five-plugin hook seam, every phase's decision and metadata per
iteration
Mutation check on the second commit: breaking each of the five moves
inside `DefaultMemory.shrink` turns exactly its own scenario red, so the
comparison is not vacuous.
Real model, Sonnet 4.5 through OpenRouter, at both commits:
- playbook on, in-process lane: both workers receive the charter, write
their files and finish
- playbook on, ACP fork lane: the charter prompt crosses the process
boundary, and a charter check blocks a `write_file` outside the fence
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No user-visible behaviour change is intended, and the comparisons above
are byte-identical on every path they cover.
For anyone replacing a harness role: `MemoryModule` gains `shrink`, so a
replacement written against the old protocol needs it.
`DefaultMemory.bind()` names the missing member at assembly rather than
failing inside a turn.
Rollback is a revert of the merge commit. Nothing persisted on disk
changes shape.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: yao pengfei <yaopengfei@shanda.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: KT <74288668+0xKT@users.noreply.github.com>
## Summary
Make `MemoryBackend` the only seam between the host and the memory
subsystem, so a second memory plugin can be installed without editing
host code.
The abstraction is the goal; no second backend is being added.
What the branch does:
- `health()` joins the Protocol. `raven doctor` and `raven import` read
a `BackendHealth(ready, checks)` the backend fills in with its own
vocabulary, instead of reaching into EverOS internals. Doctor prints the
checks verbatim and never interprets a label.
- A new `[[plugin.contributes.onboard]]` kind, with
`raven/contracts/onboard.py` as its paper. The host lends the wizard
shell as one `OnboardUI` and records the result; the screen returns a
`StepOutcome`. The plugin never writes `memory.backend` -- that key
stays the host's. EverOS's step-4 screen and its `everos.toml`
management move into the plugin.
- The skill source and the after-turn feedback prefix are named from
`memory.backend` rather than the literal `everos`.
- `enabled_by_default` is gone from the manifest: an installed plugin
the user has not disabled is active.
- `tests/test_plugin_boundary.py` pins the dependency direction in both
directions, with an equality assertion so the remaining exceptions
cannot grow.
That guard's allowlist started at five host files still speaking
EverOS's wire protocol. The follow-ups below close three of them.
Two things this branch itself introduced were found in manual acceptance
on an install without the plugin and fixed here: a turn printed which
backends were installed -- empty on exactly the install that needs the
sentence -- and `settings.everos` / `settings.everosSet` let
`ModuleNotFoundError` reach the dispatcher as an internal error carrying
a traceback. Both now carry the note doctor and the wizard already use,
naming the distribution to install.
Review on this PR found four blockers, all fixed and covered. A fifth
defect came out of manual acceptance rather than review, and four more
out of the rounds that followed it -- every one of those in the
embedding endpoint's own plumbing, each found by the round after the fix
that introduced it. They are listed under Risk; the blockers are:
1. `onboard` is an optional contribution, but the wizard equated "no
matching screen" with "not configured", so one `raven onboard
--skip-memory` wrote `memory.backend` back to null for a third-party
backend configured by hand. A backend with no screen now answers on the
strength of having been selected; only one whose own screen says it is
unconfigured is cleared, which is the case that rule exists for.
2. The record a sub-agent call leaves behind ran through a backend
nobody had started. The shipped adapter begins in an unknown state, so
the first flushing write only scheduled a readiness probe and answered
false -- the record said "unavailable" while the service was up the
whole time, and each per-record HTTP client was left open. One context
manager now owns start and stop around a record, in both the manager and
the DAG runner.
3. That record's write and the recall after it addressed different
owners: a real config spells its keys in camelCase and the block reaches
the backend as written, while the adapter read only the contract's
snake_case, so a sub-agent's memories were filed under the host
identity. The adapter reads both spellings.
4. Legacy embedding discovery had narrowed to the recorded plugin root,
so an install predating root recording lost its knowledge-base endpoint
with a valid file still on disk.
**The five follow-ups the seam left behind are in this PR too**, rather
than in three stacked ones, because they are one goal and the branch
protection dismisses an approval on every push:
- The embedding endpoint is raven's. A knowledge base indexes inside the
gateway process and never speaks to the memory service, yet it read its
endpoint out of everos.toml, so selecting another backend left it with
no vectors and no message naming the cause. Raven holds the block now
and hands it to the backend at start -- as a shared default, not an
override: a plugin that was given an endpoint of its own keeps it, and
only one that has none takes raven's. Discovery of an existing
everos.toml still checks all three places the plugin itself looks, read
with plain tomllib so it works where the plugin is not installed. No
data migrates: a base is keyed on its model and measured width, not on
the base url.
- `delete()` joins the Protocol. The browser used to delete a row out of
EverOS's index, in the host process, through the plugin's repository
layer -- while the markdown EverOS treats as the source of truth kept
the text, so the memory came back on the next rebuild, after the user
was told it was gone. The adapter now uses only operations EverOS
already performs, for the kinds it performs them for.
- Sub-agent memory goes through the contract. The read half is a new
optional `recall_session`; the write half needed no new surface, only
two metadata conventions written down. `agents.<name>.config.everos`
becomes `config.memory`, opaque to the host except the two keys the host
reads; the old spelling still loads.
- The memory and settings pages say why they are empty -- no plugin, or
a backend this page does not read -- instead of four zeros and a retry
button that cannot help.
- The `everos` package leaves the host's dependencies for the plugin's
own, at the same exact pin; the host reaches the tree through the
plugin. This is the package layer only: the installers already deliver
`everos-memory` as a sibling wheel from the same release, so an ordinary
install still has long-term memory.
The boundary guard's allowlist falls from five entries to two, both GUI
surfaces still shaped around EverOS's own store. Generalising their wire
is a frontend change and is deliberately not in scope.
This branch was reviewed on GitLab as merge request 639 over three
rounds, including a post-rebase range-diff check. It is being moved here
because GitHub is now the source of truth.
## Type
- [x] Refactor
## Verification
- `uv run pytest` on this branch, rebased onto `main`: 22146 passed, 4
failed, 45 skipped. Three of the four (`test_agents_oncall_launcher`,
`test_agent_loop_token_budget`, `test_agents_code_launcher`) were re-run
on a detached checkout of that same `main` commit in this environment
and fail there identically. The fourth (`test_ppt_engine_image_search`)
could not run in that checkout, whose environment lacks the deck
engine's extras; this branch's only change anywhere under
`plugins-dist/ppt-engine` is the removal of the `enabled_by_default`
manifest key, which that test does not reach. So this branch adds no
regression.
- `npx vitest run` in ui-web: 1680 passed across 103 files. `npm run
type-check` and `npm run gen:check` clean, so the generated client
matches the contract.
- Every fix in the follow-up commits was mutated away and its test
confirmed red, then restored and confirmed green. For the record path
that is three separate mutations: dropping `start()`, dropping `stop()`,
and narrowing the owner lookup back to one spelling.
- `uv run ruff check .` and `uv run ruff format --check` on the changed
files: clean.
- `uv lock --check`: consistent.
- `scripts/check_commit_messages.py`, `scripts/check_large_files.py`,
`scripts/check_source_language.py` over the branch range: clean.
- Manual acceptance against a real isolated install (temporary
RAVEN_HOME, isolated EverOS root and port), 34 cases: `raven plugins`,
`raven doctor` across four backend states, `raven onboard` interactive
and non-interactive including all three step-4 lanes, `raven import`
refusing and importing, an end-to-end write and recall, the web UI's
memory and settings pages driven through a real browser, a sub-agent
trace record, and an install with no memory plugin at all. 31 passed; 1
failed and was fixed; 1 partial; 1 carried over from the earlier round.
- The failure is the one worth reading. On a fresh managed install the
wizard reported embedding configured and the service it started the next
moment ran keyword-only: the spawned process carried no
`EVEROS_EMBEDDING__` values, and EverOS logged that the embedding key
was not configured. The rule deciding whether everos.toml already held
an operator's own endpoint asked whether its model name was a `"<...>"`
placeholder; the shipped template seeds every section with a real model
name and an empty key, so every fresh install read as a deliberate
choice and the host's endpoint was never bound. It now asks the
criterion the module already had -- model and key. The unit tests missed
it because each built its "operator's own" section with a key in it; the
regression copies the shipped template itself.
- The partial: the memory page's search returned relevant results
without error, but every memory in the test corpus was on one subject,
so narrowing could not be observed. The carried-over case is the
skill-source prefix, whose path this branch does not touch.
- Findings recorded and not fixed here, none introduced by this branch:
a progress spinner is still drawn after `import` reports it imported
nothing; an unsupported delete surfaces as a generic internal error; the
TUI log and `doctor` word "no memory plugin" differently; a turn that
did reach disk still prints that it was not written.
- The partial case: an induced agent skill is discovered through
`find_skill` with the backend's prefix, but `read_skill` / `use_skill`
on that id fail. Nothing writes the on-disk layer those tools look in,
on this branch or on `main`, and no test covers it. Pre-existing; filed
as a follow-up.
- [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:
1. User-track recall is now strictly bounded by `top_k`. A profile row
used to ride outside that bound.
2. `raven doctor` builds the plugin factory, so a managed EverOS setup
writes its env var and config templates during a doctor run. It used to
be read-only. The `--json` memory section is reshaped around
`health.checks`.
3. A third-party drop-in plugin without `enabled_by_default = true` used
to be skipped and now loads.
4. The loader no longer back-fills the EverOS config slice's `root` /
`owned`, nor strips a legacy `mode` key; a leftover `mode` now draws an
unknown-key warning.
5. The wizard's recap shows the contribution name `everos` rather than
`EverOS`.
6. `use_skill` with an unknown prefix reports "not found" after a disk
lookup instead of "unknown source".
From the follow-ups:
7. Config gains an optional top-level `embedding` block. Absent, the
knowledge base reads the EverOS file as before and says so once. An
operator who moves the values across changes nothing else; one who names
a *different* model there gets the existing `StaleBaseError` telling
them to rebuild that base. The block is a default for the memory plugin
rather than an override, so an install that had configured the plugin
separately keeps what it had. Note that a config carrying this block
does not load on an older Raven, which rejects unknown top-level keys.
8. `agents.<name>.everos` is written back as `agents.<name>.memory`. The
old spelling still loads; a per-agent `baseUrl` is ignored with a
warning, having never had a user.
9. Deleting a memory now changes what EverOS treats as the source of
truth, so it stays deleted. Profiles and cases report that they cannot
be deleted rather than appearing to succeed.
10. `pip install raven` no longer pulls the memory engine in.
`install.sh` and `install.ps1` are unaffected: both already resolve
`everos_memory-*.whl` from the release they install and pass it as
`--with everos-memory`, and the source path installs it editable, so
those installs keep long-term memory. An install that reaches neither --
a release predating the sibling wheel, or a bare `pip install` -- now
boots without memory and says which distribution to install rather than
failing on an import.
Found after the acceptance run, in review, all fixed here. They share
one cause worth stating once: the endpoint acquired a second home, and
each fix taught one more reader about it while leaving the next one
behind.
11. The endpoint the wizard saved never reached the EverOS process it
then started. The rule for "does everos.toml already hold an operator's
own endpoint" asked whether its model name was a `"<...>"` placeholder;
the shipped template seeds every section with a real model name and an
empty key, so every fresh managed install read as a deliberate choice
and the host's endpoint was never bound. The service came out of the
wizard running keyword-only while the wizard said embedding was
configured. The rule now asks the criterion the module already had:
model and key.
12. The exported `EVEROS_EMBEDDING__*` variables are a third home,
documented by EverOS and ranked above its file. They were being
overwritten. A complete triple is now an operator's choice; an
incomplete one is not an endpoint and is replaced whole rather than
topped up from the host.
13. Raven writes those same variables itself at startup, so a reader
that asked only whether all three were set called raven's own binding an
operator's export -- a blank settings card and a save refused by naming
variables nobody had set. The module now records which of them it set.
14. That record lived in a module-level set, and `raven gateway
--restart` re-launches through `os.execv`: the values survive, module
state does not. The record now travels in a variable beside them, and is
stripped from the environment handed to EverOS.
15. A settings save the environment would outrank is refused with the
variable names, rather than written and silently ignored.
Four of the five arrived one per review round, each in the fix for the
one before it. The tests that missed them all shared a shape: each built
its "an operator configured this" fixture with a key in it, or cleared
the environment before the case, so the states the product actually
produces -- a template with no key, a live process that has just bound
its own endpoint -- were never the input. The regressions now copy the
shipped template, and run the startup sequence and a second interpreter
rather than a prepared state.
Rollback is a revert of the branch: the seam is additive, and
`memory.backend` keeps its shipped default.
- [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>
Give each design session its own working directory under designs using a
slug and a hash of the full session key. Restore the same directory when
the session resumes, including turns that skip the user inbound hook.
Keep review ledgers and auxiliary files in the session directory and
provide workdirPerSession=false for the existing shared-directory
behavior. Preserve existing shared files and task state without guessing
ownership.
Verify concurrent sessions, resumed turns, directory name collisions,
and completion isolation with regression tests and a live ACP rendering
run.
## Summary
Design sessions using the same working directory previously shared Task
State and output files. Give each session its own directory under
`designs/`, named with a session slug and a hash of the full session
key. Reuse that directory on resume and keep review ledgers and
auxiliary files there.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```bash
uv run --no-sync pytest -q tests/test_design_engine_*.py tests/test_agents_design_launcher.py tests/test_ppt_engine_plugin.py tests/test_agent_workdir.py -x
```
Result: 265 passed. One existing PPT test produced a non-failing timing
warning.
```bash
make check-large-files check-source-language COMMIT_RANGE=origin/main...HEAD
git diff --check
```
Result: passed. Pre-commit checks also passed for all seven changed
files.
A live ACP scenario exercised two concurrent sessions, actual model
calls, Chrome rendering, process restart, and session recovery. Both
sessions generated independent HTML, PDF, PNG, review ledgers, and Task
State. Revising session A left all nine session B artifact and state
file hashes unchanged. PDF image pixels matched the corresponding
previews.
The final verification command rechecked completed concurrent outputs
and ran the two recovery turns:
```bash
DESIGN_E2E_OUTPUT=/tmp/raven-design-live-e2e-hx9Ohs/run3 DESIGN_E2E_RESUME=1 uv run --no-sync pytest -q -s /tmp/raven-design-live-e2e-hx9Ohs/test_design_session_e2e.py
```
Result: 1 passed. This was a local live test harness outside the
repository. EverOS memory was disabled; Web UI interaction was not
covered.
- [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
## Related Issues
N/A
---------
Co-authored-by: Codex <noreply@openai.com>
## Summary
The tracing viewer keys its entire payload on a session id, and three
readers drop a span that has none. On the measured store that is **683
of 1,956 spans (35%)**, dropped silently: every `plugin.load` ever
recorded, every cron heartbeat, and the titles generated after a turn
ended. A day whose only activity was scheduled reads as a day with no
activity at all -- which is how three consecutive days (09-12 ... 09-14)
came to look empty in the panel while 154 spans sat on disk.
A span with neither `session.id` nor `session.key` now gets a session
derived from its own `startTime`, one per calendar day
(`background:<day>`). The derivation is **span-local on purpose**: the
whole-corpus reader in `server.js` and the per-file shard index are
already pinned against each other by test, and any derivation consulting
global state would let them elect different ids for the same span. A day
is the grain because per-trace would shatter a year of timer ticks into
a session each. A span that has a key but no id is untouched -- the
identity election resolves that one, and still drops it when it cannot.
`SCHEMA` goes 2 -> 3. The sidecar records nothing about the code that
built it, so leaving it at 2 would let every index already on disk keep
answering with the old contents: the fix would ship and change nothing
for the history it was written for. The comment above `SCHEMA` already
describes that failure from the last time it bit.
**This reverses a deliberate decision, and reviewers should weigh it as
such.** `server.js` carried an explicit rationale for the drop (added in
7b45527b5): *"there is nowhere in a session-oriented view to show it,
and on the measured store there are 34,644 of them."* Both halves are
addressed rather than ignored -- the per-day session is the place to
show it, and the per-day grain is what keeps the count in the same order
of magnitude as a real session. That comment is updated rather than left
contradicting the code.
`docs/specs/2026-08-25-tracing-viewer-sharded-reads-design.md` records
the narrowing: its constraint "a span cannot be attributed to a session
by looking at the span" is a statement about spans carrying a
`session.key`. A span with neither has no corpus fact to recover, which
is why attributing it span-locally is sound rather than a shortcut past
the constraint.
## Review round
Three findings, one commit each, all filed as non-blocking and all
fixed.
**The comparison tests could not see a reader disagreeing.** Both tests
that hold
the sharded reader against the whole-corpus one ran on a fixture whose
every span
carried both identity fields, so neither ever built a background
session. Changing
the day grain on one side alone left all 21 green. The fixture now
carries a
sessionless span, and the same change fails both comparisons.
**The panel opened on a background day.** The list is newest-first and
the page
takes the first row; background work is emitted continuously, so the
newest record
in a store is usually one of those. This branch therefore changed the
row the panel
opens on, a default nobody chose. The row now declares `isBackground`
and the page
prefers a conversation. The declaration is on both readers, which the
field-for-field
comparison between a list row and a whole-corpus session then holds
together.
**A sessionless trace across UTC midnight had no single owner.** Its
spans land in
two day rows, and the trace-id lookup returned whichever row iteration
reached
first. It now returns the earliest owner, which is the single-owner rule
the
trace-id union already states.
The day grain is deliberately unchanged. Deriving it per trace would
make one bucket
per sessionless span: measured on a real store, 770 sessionless spans
carried 770
distinct trace ids, which takes one file's pair count from 3 to 341 --
avoiding that
is why the grain is a day. So the straddling trace's spans stay split
across two
rows and only the ownership is settled. Measured incidence of a straddle
on that
store is zero, so its test forces the state rather than reporting a
failure anyone
has seen.
The review also named the `undated` fallback as reached by no test. It
is reachable rather than defensive -- `normalizeSpan` passes `startTime`
through as it finds it -- so it now has one, asserting the pool exists
and the span arrives through it. No writer emits an undated span and
none is on the measured store.
`SCHEMA` is untouched by this round: nothing here changes what a sidecar
holds.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
pytest tests/integration/test_tracing_viewer_e2e.py -m integration 24 passed (5 new)
pytest tests/test_tracing_api.py tests/test_cli_tracing_commands.py \
tests/test_tracing_compact.py tests/test_tracing_artifact_v2.py 131 passed
ruff check / ruff format --check clean
scripts/check_commit_file.py exit 0
node --check server.js shard-index.js clean
```
Against the real store (span logs copied to an isolated dir; artifacts
untouched):
| | sessions | distinct spans reachable |
|---|---|---|
| before | 4 | 1,266 |
| after | 9 | 1,950 |
The five new per-day sessions match the previously measured per-day
drops exactly: 188 / 341 / 48 / 48 / 59. All three readers agree
(`/api/data`, `/api/sessions`, `/api/llm-calls`), and
`/api/sessions/background:2026-09-14` returns 200 with 59 traces.
**Five new tests, each watched failing first.** The second of the
original pair matters more than it looks: with `SCHEMA` left at 2 it
fails because a sidecar written by the previous build keeps hiding the
spans -- the fix would have shipped and done nothing for existing
archives. Of the three added this round, the reader-comparison one was
run against the review's own mutant both ways (21 green before the
fixture change, 2 failed after), the trace-owner one against a revert of
its fix, and the undated-pool one against a build with the `undated`
fallback removed.
Rebased onto `56c79edf5` and re-verified there: `git range-diff` maps
the branch one-for-one, the merge commit the previous revision carried
is flattened away, and the counts above are from the new base.
- [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 -- no new input is parsed; the derived
id is built from a span's own `startTime`, already validated upstream.
- [x] Backward compatibility considered -- the `SCHEMA` bump invalidates
existing sidecars, which are a cache: they rebuild on first read, no
manual cleanup. Session ids in the `background:` namespace are new
values in an existing field; no consumer is keyed on the set of ids.
- [x] Rollback path is clear -- revert restores the previous behaviour;
sidecars written at schema 3 are rejected by the old code and rebuilt at
2.
### Two things a reviewer should know
1. **CI does not execute these tests.** `norecursedirs` keeps
`tests/integration` out of the default scope and `addopts` carries `-m
"not integration and not e2e"`; `ci.yml` runs exactly one integration
file (`test_cli_upgrade_real_uv.py`). The 21 tests here -- the 19 that
already existed and the 2 added -- only run locally. Unchanged by this
PR, but it means the regression net is manual.
2. **A known display rough edge, deliberately not fixed here.**
`ui/app.js` truncates with `shortId(sessionId, 18)`, and
`background:2026-09-14` is 21 chars, so the five cards read
`background:2026-09...` -- distinguishable by the start/update times on
the card and by the full id in the tooltip, but not by the title. Fixing
it means either widening a presentation constant or shortening the id;
the UI has no test harness, so it is left as a separate call rather than
changed blind.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
The one INSTALL_HINT was source-checkout-shaped (uv sync --extra
browser), which a uv-tool-installed user cannot run, and it answered two
different questions with one sentence. It splits: the missing-binary
branch names the interpreter that owns the playwright it already has
(sys.executable -m playwright install chromium, valid in both install
shapes), and the missing-package branch points back at the installers,
because python -m playwright cannot run without the module. The web
panel stops hardcoding the stale command and lets the gateway-computed
reason carry the fix for the host it was computed on; the shared catalog
copy now states the condition instead of prescribing a command, en and
zh alike. Regenerating the TUI catalog also carried one stale key
(gui.att.too_big) up to date with the shared catalog.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
Merges the GitHub trunk into this fork's main, as a merge rather than a rebase:
the resolutions below live in the merge commit, and rebasing would drop them.
Eleven upstream commits since 377a1da14 (2026-08-25), fifteen files
conflicting. The conflicts worth a reviewer's attention:
- **tracing**: upstream retired the runtime attempt id. `attempt.id` is now a
reserved span attribute and `attempts.json` owns the grouping, so
`begin_attempt` / `end_attempt` / `current_attempt` and every `attempt_id`
parameter go with it. Nothing on this side called them outside tests. This
fork's `surface` field and its `use()` helper share those hunks and stay.
- **appLayout.tsx**: took upstream's copy-notice line only. Its
`FloatingOverlays` hunk would render that component twice, because this side
had already moved it into its own anchor box.
- **onboard_everos.py**: upstream only refreshed three model ids, which this
side already carries. Kept the English-only role table (AGENTS.md 1.3).
- **test_everos_server.py**: took upstream's inotify-gate tests and pointed
them at `raven_everos.server`, where this side moved the module.
- **README.zh-CN.md**: the benchmark table had to be rebuilt by hand. Its
separator row auto-merged with the prerequisites table's and silently
dropped the three data rows.
Three follow-up commits fit upstream's new tests to this fork's environment.
Each is a fork/upstream difference, not a defect upstream:
- The listing tests widen the console with `env={"COLUMNS": "200"}`. That
cannot work here: this suite runs under xdist (`addopts` carries `-n 4`) and
its workers export `COLUMNS=80`, which rich freezes into `Console._width` at
import time, before any invoke sets the variable. An autouse fixture gives
the module console a real width, the way upstream's own browse test does.
- One test patched `raven.config.loader._current_config_path`; this fork keeps
that name in `raven.home`.
- Three CJK fixtures are written as `\uXXXX` escapes so the language gate
passes. `test_table_cjk_cells_stay_within_budget` measures what an
east-asian glyph costs in a table cell, so an ASCII replacement would void
the test; the escape keeps the runtime value upstream's.
**Reviewer attention, one deliberate rule break**: `MODULES_IN_CYCLES_CEILING`
in `tests/test_import_cycle_budget.py` goes 42 -> 46, and that file's comment
says the ceilings may only go down. Upstream's four new modules import each
other in pairs (`cli.trajectory_browse` with `cli.trajectory_commands`,
`trajectory.bugreport` with `trajectory.review`). Neither pair can be unpicked
by deferring an import, because that graph counts a function-local import like
a top-level one, so unpicking either means moving code that has just arrived
from upstream. The package and pair ceilings did not move. Raising the number
here is the call a reviewer may want to reverse; doing so means a refactor of
upstream's new modules, roughly 110 lines moved.
Project settings changed alongside this: `squash_option` `always` ->
`default_off`. A squash would flatten the merge commit and lose the manual
resolutions above, after which the next sync would have to redo all of them.
`merge_method` was already `merge` and is untouched.
A manual smoke run on the real hosts found one bug the suites did not, now
fixed on this branch: the sync took upstream's copy-on-select wiring into
`useMainApp` but not the two import lines it needs. Both sides had edited that
import block, so git resolved it to this fork's version and the added lines
went with it -- a semantic conflict, no marker. `raven tui --dev` died on entry
with `createCopyOnSelectReporter is not defined`. The 2072 vitest tests did not
catch it (none imports and renders the whole hook) and neither did eslint
(undefined names are left to the type checker here); `npm run type-check` does,
and is clean after the fix.
**Known red gate, recorded rather than bypassed.** Five of the eleven imported
commits fail `scripts/check_commit_messages.py` over this MR's range
(`1aef9f50`, `a83a3565`, `5ab90aa5`, `9c55d545`, `dcedd1c4`). The only
non-ASCII in them is three characters: the display name in a colleague's
`Co-authored-by` trailer (U+6C5F U+56FD U+5E86, address `guoqingjiang@`
unchanged and ASCII). Subjects and bodies are English. The job that runs this
checker fires on GitHub `pull_request` events, so a merge performed on GitLab
never runs it -- which is why this pipeline is green while the gate is red over
the same range.
The disposition, settled between the maintainer and the reviewer: a single
deliberate pass over the imported history will rewrite committer and author
information wholesale, and these five trailers belong to that pass. Rewriting
them here would be redone by it. So this is assigned to the change that can do
it once across all imported history, rather than five commits at a time inside
a sync -- not waved through as unimportant. This paragraph exists so the next
reader sees the gate was weighed, not missed.
One cleaner route remains open and is deliberately not taken here: teaching
`commit_lint.py` that a trailer's display name may be non-ASCII while its
address stays ASCII, which is arguably what AGENTS.md 3.1.1 already means when
its table calls the trailer "ASCII by format".
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other (upstream sync)
## Verification
- `uv run --all-extras pytest -q` -> 21814 passed, 4 failed, 45 skipped.
The four are pre-existing on main, verified by running them on a clean
`origin/main` worktree in the same environment:
`test_agents_oncall_launcher.py::test_the_products_tool_face_equals_the_forks_config_intent`,
`test_agents_code_launcher.py::test_the_products_tool_face_is_the_forks_config_intent_minus_the_ledger`,
`test_agent_loop_token_budget.py::test_a_ceiling_as_large_as_the_window_still_leaves_room_for_history`,
`test_ppt_engine_image_search.py::test_a_missing_key_is_said_once_rather_than_per_query`.
- `npm test` in `ui-tui/` -> 143 files, 2072 tests, all passing.
- `make lint-python` -> 1930 files already formatted.
- `make lint-imports` -> 10 contracts kept, 0 broken.
- `make lint-deps` -> no dependency issues.
- `make check-source-language` -> clean.
- `make check-large-files` -> clean.
Manual smoke on the real hosts (isolated `RAVEN_HOME`, own tmux session, the
running instance on this machine left untouched):
- `raven trajectory list` -> three attempts, matching the span log on disk.
- Interactive browser (bare `raven trajectory`, driven under tmux): session
list, attempt list, and the `turn.input_preview` values all render from the
real log. `[M]` merged two attempts; `attempts.json` gained the definition
with exactly those two member trace ids, and the span log stayed append-only.
- `raven trajectory split` put it back: `attempts.json` empty, listing back to
three rows.
- `raven trajectory report-bug` produced `br-20260911-b19368.tar.gz` with the
envelope and the nested trajectory inside; it correctly reported the fixture
as unreplayable and pinned the attempt.
- `raven tui --dev` reaches the main layout, and the completion overlay anchors
correctly (the `FloatingOverlays` hunk this merge resolved by hand).
- Copy-on-select driven end to end by sending SGR mouse press/drag/release
through tmux, against a sentinel value placed on the clipboard first. The
first drag put the selected span on the clipboard (`pbpaste` returned
exactly the 76 characters under the drag) and reported `copied 76
characters` into the transcript; a second drag reported `copied 10
characters` as the transient notice above the composer, which is the line
this merge resolved by hand. One drag, one clipboard write, one notice:
the duplicate subscription is gone from the observable behaviour too, not
only from the source. The host clipboard was restored byte-for-byte after.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes all come from upstream: the interactive trajectory
browser, the tester-facing bug report flow, the feishu websocket backoff, the
EverOS inotify spawn gate, and the TUI copy-on-select notice. The fork's own
behaviour is unchanged; the only fork-side edits are in tests.
The one runtime removal is the tracing attempt API. No caller outside tests
used it on this side, and upstream replaced what it did with `attempts.json`.
Rollback: revert the merge commit. Because this lands as a merge rather than a
squash, the branch history stays intact and a revert leaves main exactly where
it was.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Eleven commits from the GitHub trunk since 377a1da14, fifteen files
conflicting. How each was resolved:
- raven/tracing/context.py, trace.py, spans.py and tests/test_tracing_api.py:
upstream retired the runtime attempt id. attempt.id is now a reserved span
attribute and attempts.json owns the grouping, so begin_attempt,
end_attempt, current_attempt and every attempt_id parameter go with it.
Nothing on this side called them outside tests. The fork's surface field
and its use() helper share those hunks and stay.
- raven/trajectory/store.py: upstream's module docstring documents
attempts.json and is a superset of ours.
- raven/cli/onboard_everos.py and tests/test_cli_onboard_commands.py:
upstream only refreshed three model ids, which this side already carries.
Kept our English-only role table (AGENTS.md 1.3).
- tests/test_everos_server.py: took upstream's inotify-gate tests and pointed
them at raven_everos.server, where this side moved the module.
- ui-tui/src/app/useMainApp.ts: copy-on-select was never wired up here;
upstream wires it.
- ui-tui/src/components/appLayout.tsx: took upstream's copy notice line only.
Its FloatingOverlays hunk would render that component twice, because this
side had already moved it into its own anchor box.
- README.md and README.zh-CN.md: upstream's wording under this side's emoji
headings. The zh benchmark table had to be rebuilt: its separator row
auto-merged with the prerequisites table's and dropped the data rows.
- tests/test_provider_rates.py and tests/test_trajectory_bundle.py: both
sides appended independent tests at the end of the file; kept both.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
`playbooks.agentHarness` -- off by default -- has each turn write itself a table
of sub-agent workers before it starts: which sub-agents this question needs,
what each one's brief is, and what each one may see and do. The dispatching
model is offered those workers in place of the bare roster, and a dispatched
worker is held to the charter its table wrote.
The roster says which agents exist and nothing about what any of them should do
for *this* question, so every dispatch re-derived the brief from scratch and two
dispatches to one agent could not be told apart. A worker is a label, the roster
agent behind it, and a charter; two labels may name one agent, which is how a
single question gets a worker per subject without registering an agent per pair.
The label reaches the model as `spawn`'s own enum and resolves to the agent
before any dispatch, because a label resolves to no backend -- the dispatch, the
instance registry and the graph tool are all handed the roster name.
A charter is a prompt, the tools the job calls for, the judgements to apply
before each tool call, an optional judge as code, and a deadline. It travels
with the dispatch and is read by the worker in its own process.
**Narrowing, never widening.** Every field is an intersection with what the
worker would have done anyway, so the worst a bad charter can do is leave a turn
with fewer tools than it had. The tool list is enforced rather than merely shown:
it joins the registry's withheld set, which `execute` reads on every dispatch, so
the three routes around a tool array (progressive disclosure, the `tool_call`
meta tool, the model's own memory) are closed.
**Two lanes, because a worker is not always a fork.** A `kind: acp` worker reads
its charter off the wire (`_meta`, the channel `raven.usage` already uses) and
stages it for its next turn. The one `kind: builtin` row runs the loop in this
process, where there is no wire, so its backend opens the scope itself.
Decisions the code could not have been written without:
- **No `mode` or `model` on a worker.** `SubagentManager.resolve_mode` states
that a sub-agent's effort is the operator's setting and that the model
composing a dispatch is the one party that cannot know what was chosen. A
model-authored table is exactly that party, and a field it wrote would
overrule the person who set one.
- **`SpawnTool` authors its own `to_schema`.** A tool that defines one has
*declared* a dynamic shape and `ToolRegistry` serves it live; inherited, the
enum is frozen at admission and a per-turn table never reaches the model.
- **The reader half lives in `agent/subagent/`,** not beside the generator.
Writing a table is an optional capability and reading one is part of dispatch;
an inner layer may not know an optional capability at module level, and
`tests/test_l3_open_world.py` refused the first arrangement.
- **The setup call resolves the session's binding by hand.** It runs before
`use_binding` opens, where `self.provider` still answers with the loop's
default, so a session that switched model would otherwise have its setup call
go out on the model -- and the credential -- it switched away from.
- **A charter may carry Python,** because some judgements are not a prefix or a
pattern. It runs in the worker's process on the worker's own calls, so it
holds no authority the dispatched agent did not already have, and it passes an
allow-listed gate on the parse tree before anything is compiled: no imports,
no loops, no dunder access, no calls outside a named handful. Refusing `for`
and `while` at the gate is what makes running forever unreachable rather than
merely unlikely. A source the gate refuses is dropped with a line saying why,
and a judge that raises has said nothing rather than refused everything, so
the declarative rules beside it stand.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest tests/` -- 20647 passed, 3 failed, 184 skipped (the three are
disclosed below and are not from this change)
- `pytest` over the playbook, charter and delegate files -- 108 passed
- `ruff check raven/ tests/` and `ruff format --check` -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `PYTHONPATH=. python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
The switch's promise is measured rather than asserted. A whole turn runs through
`run_turn` -- not `_process_message`, which would skip the per-turn scopes the
table rides on -- with the feature off and on, and everything crossing the
provider boundary is diffed. Once the `wrap_untrusted` nonces and the temp path
are normalised, the model, the tool array, every message and the answer are
identical; the single difference is the target `spawn` offers.
Driven end to end against a real model as well, on both lanes: a question
produced a table, `spawn` offered its labels, a worker process was launched, its
own log recorded the charter it had been handed (`2 tool(s), 3 check(s)`, which
is what the table wrote), the worker did the work and its result was announced
back to the originating session.
Mutation, to show the added assertions are load-bearing rather than decorative:
```
scope stops restoring on exit -> 2 failed (the scope pair)
to_schema override removed -> 5 failed (every enum assertion)
labels resolve to themselves -> 2 failed (resolution and charter)
setup call reads self.provider again -> 1 failed (the session-model pin)
the call log reads text, not the result -> 1 failed (a failed prior call)
parse does not type-guard `checks` -> 1 failed (a malformed payload)
the ACP handler stops reading `_meta` -> 2 failed (staging and clearing)
an emitted field has no reader -> 1 failed (the vocabulary guard)
the in-process lane binds no charter -> 1 failed (the builtin worker)
the agent name follows the label -> 1 failed (the dispatch vocabulary)
```
The second is the one worth naming: without that override nothing raises and no
test of the table itself fails -- the enum simply never moves, which is why it is
asserted through the rendered tool array rather than through the table. The
eighth is the guard added after this review found `code` and `timeoutSeconds`
readable by a worker and writable by nobody: a field offered to the generating
model and consumed by no one produces a table that validates, a dispatch that
runs, and a brief missing half of what its author wrote, with no error anywhere.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Left unchecked: nothing user-facing changed. The switch is documented on
`PlaybookConfig.agent_harness` where an operator reading the config schema finds
it, the charter fields on `AgentPlaybookSpec` beside them, and `CONTEXT.md`
gains the domain terms that section 6 of the contribution rules requires of
newly coined ones.
## Disclosed
Three failures in a full run are **not** from this change. Each reproduces at
the `main` tip with this branch stashed:
- `tests/test_design_engine_rendering_outcome.py` (two) -- `ModuleNotFoundError:
No module named 'playwright'`. Two other cases in the same file guard the same
import with `importorskip` and skip cleanly; these two do not.
- `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`
-- asserts `"mem-root" in stdout` against a doctor rendering that no longer
prints it.
Two more failed on some full runs and passed on others, including runs of this
branch that differed in nothing else:
`tests/test_acp_methods.py::TestHeldTurn::test_the_heartbeat_keeps_the_wait_call_alive`
and `tests/test_agents_research_tools.py::test_a_thin_dataset_card_falls_back_to
_the_metadata_the_table_needs`. Both pass alone and pass with their own files.
The second calls `WebFetchTool().execute()` directly and so reaches no code this
branch touches; it shares a process-global session with its neighbours under
`xdist`. Not investigated further here.
## Risk
Off by default, and the off path is what the comparison above pins. Every reader
answers an absent charter with the value it returned before: an empty withheld
set, an empty refusal list, an empty string appended to the identity, no key on
the wire, the configured deadline. The hot readers ask whether a charter is
bound before they materialise anything, so a turn without one pays no allocation
for an answer that is always empty. The binding rides a `finally` on the turn's
existing scope stack, so a cancelled or raising turn cannot leave its table
behind. Rollback is the revert: nothing outside the loop reaches the new modules.
A charter arrives from another process and is treated as such. It is narrowed
against this install rather than applied as given; unknown keys are dropped
rather than refused, so a newer host can talk to an older worker; what is known
is bounded, so a malformed payload costs a log line rather than the dispatch.
Two consequences to know rather than to fix. `run_subagent_dag` renders its own
agent roster and does not see the worker table, so with the feature on a model
sees worker labels in `spawn` and agent names in the graph tool; a label passed
to the graph tool is refused by its roster check, which is an honest failure
rather than a silent one. And a worker's judge, being code, can be wrong: it is
bounded to saying nothing when it is, but a rule that never fires and a judge
that always raises look the same from outside, which is what the warning line it
logs is for.
## Related Issues
N/A
## Summary
Three defects a live twenty-page run surfaced, each of which cost whole pages.
`PageBox` said in its own docstring that it reads the same as `ppt_layout.Box`, and `Box`
answers to `.x` and `.y` as well as `.w` and `.h`. `PageBox` answered to two of the four.
A build helper read `round(b.y, 3)` once, in the one place it used for every page, and all
twenty pages failed to draw with `'PageBox' object has no attribute 'y'`. `Box` was given
the same pair after the same crash; the promise was the part that did not travel.
`_check_cut_out` asked its argument for `.name`, and the spelling the skill documents is
`replace_picture(shape_at(slide, n), str(FIGURES / image), fit)`. Every other branch takes
that string -- the ones that open the file hand it to PIL, which does -- so the only thing
that refused it was the warning that exists to explain a mistake. It raised
`'str' object has no attribute 'name'` over the top of the explanation and took the page
with it.
Rasterising now has a gate of its own, and it is one. `pdf()` spends its time in a
LibreOffice subprocess with a profile of its own, so width there costs nothing and buys
wall clock; `pages_of` spends its time in pypdfium2, in a worker thread of this process,
against a library that keeps state per process rather than per document. One gate for both
put them under the same number and let the second run concurrently with itself: over a
nine-template reference set, six of the nine PDFs failed to open with
`PDFium: Data format error` while every one of the nine opened when read one at a time, and
an earlier run on the same path took SIGSEGV. `pages_of` answers a failed read with an
empty dict, so the cost was a reference sheet quietly short of two thirds of its pages
rather than anything that looked like an error.
## 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 run on this branch, rebased onto main:
```
uv run --frozen pytest tests/ -k ppt -q
uv run --frozen pytest tests/test_ppt_engine_template.py -q \
-k "page_box_answers or cut_out_warning_survives or rasterising_runs_one_at_a_time"
uv run --frozen ruff check plugins-dist/ppt-engine/raven_ppt/services/template/compose.py \
plugins-dist/ppt-engine/raven_ppt/stages/_views.py
```
The three added tests were each confirmed to fail without the source change. The
concurrency one asserts on how many rasterisations are in flight -- the property -- rather
than on the width of a semaphore, which is one way to get it, and its stub renderer carries
the real signatures on purpose: a stub that shapes itself to the caller agrees with a call
the engine cannot make.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Two added properties and one widened type annotation are additive. The third change
narrows rasterising to one at a time while leaving conversion as wide as it was, so a deck
whose pages are read after conversion takes slightly longer in exchange for reading all of
them; reverting the commit restores the shared gate.
## Related Issues
N/A
## Summary
Three defects a live twenty-page run surfaced, each of which cost whole pages.
`PageBox` said in its own docstring that it reads the same as `ppt_layout.Box`, and `Box`
answers to `.x` and `.y` as well as `.w` and `.h`. `PageBox` answered to two of the four.
A build helper read `round(b.y, 3)` once, in the one place it used for every page, and all
twenty pages failed to draw with `'PageBox' object has no attribute 'y'`. `Box` was given
the same pair after the same crash; the promise was the part that did not travel.
`_check_cut_out` asked its argument for `.name`, and the spelling the skill documents is
`replace_picture(shape_at(slide, n), str(FIGURES / image), fit)`. Every other branch takes
that string -- the ones that open the file hand it to PIL, which does -- so the only thing
that refused it was the warning that exists to explain a mistake. It raised
`'str' object has no attribute 'name'` over the top of the explanation and took the page
with it.
Rasterising now has a gate of its own, and it is one. `pdf()` spends its time in a
LibreOffice subprocess with a profile of its own, so width there costs nothing and buys
wall clock; `pages_of` spends its time in pypdfium2, in a worker thread of this process,
against a library that keeps state per process rather than per document. One gate for both
put them under the same number and let the second run concurrently with itself: over a
nine-template reference set, six of the nine PDFs failed to open with
`PDFium: Data format error` while every one of the nine opened when read one at a time, and
an earlier run on the same path took SIGSEGV. `pages_of` answers a failed read with an
empty dict, so the cost was a reference sheet quietly short of two thirds of its pages
rather than anything that looked like an error.
## 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 run on this branch, rebased onto main:
```
uv run --frozen pytest tests/ -k ppt -q
uv run --frozen pytest tests/test_ppt_engine_template.py -q \
-k "page_box_answers or cut_out_warning_survives or rasterising_runs_one_at_a_time"
uv run --frozen ruff check plugins-dist/ppt-engine/raven_ppt/services/template/compose.py \
plugins-dist/ppt-engine/raven_ppt/stages/_views.py
```
The three added tests were each confirmed to fail without the source change. The
concurrency one asserts on how many rasterisations are in flight -- the property -- rather
than on the width of a semaphore, which is one way to get it, and its stub renderer carries
the real signatures on purpose: a stub that shapes itself to the caller agrees with a call
the engine cannot make.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Two added properties and one widened type annotation are additive. The third change
narrows rasterising to one at a time while leaving conversion as wide as it was, so a deck
whose pages are read after conversion takes slightly longer in exchange for reading all of
them; reverting the commit restores the shared gate.
## Related Issues
N/A
## Summary
`raven/sandbox/_runtime.py` read `raven.config.paths.get_sandbox_dir` to find the boxlite home, while `raven/config/schema.py` imports `raven.sandbox.config` for `SandboxConfig` -- a two-edge cycle between the two packages. An executor asking the configuration layer where its own data lives is the inverted half of that pair: it can be told instead.
`get_boxlite_runtime` now takes the home. `BoxliteExecutor` and `SandboxDebugServer` take a `sandbox_home` and pass it down. `build_executor` takes `sandbox_dir` -- the resolver, normally `get_sandbox_dir` -- and calls it only inside the boxlite branch.
The resolver rather than an already-resolved path, because resolving one creates the directory and `none` is the default backend: an eager path would leave every install a boxlite home it never uses. That laziness has a test, and the test goes red if the resolve moves above the branch.
`SandboxConfig` gains no field. Its model carries an alias generator, so a field there would become a user-writable knob in `config.json`, and a resolved runtime path is not a declaration. Five production call sites pass the resolver, all in packages that already import `raven.config`, so no new edge appears.
Measured on `origin/main` in the same environment, before -> after: packages in cycles 18 -> 17, mutual pairs 13 -> 12 (`config <-> sandbox` is gone), modules in cycles 42 -> 42. The ratchet ceilings in `tests/test_import_cycle_budget.py` are deliberately left where they are.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_sandbox_unit.py tests/test_sandbox_debug_server.py tests/test_agent_loop_workdir.py tests/test_cli_sandbox_commands.py tests/test_playbook_mcp.py tests/test_subagent_manager.py tests/test_import_cycle_budget.py -q` -> 336 passed
- `uv run lint-imports` -> 9 kept, 0 broken
- `uv run ruff check raven/ tests/` -> All checks passed
- `uv run ruff format --check` on the touched files -> already formatted
- `make check-source-language` -> exit 0
- The laziness guard was mutation-checked: moving `sandbox_dir("boxlite")` above the backend branch turns `test_the_sandbox_home_stays_unresolved_for_a_backend_that_has_none` red; reverting turns it green
- The integration suites under `tests/integration/` are updated to pass the real `get_sandbox_dir("boxlite")`, but were not executed here (they need a real VM)
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No behaviour change on the boxlite path: the same directory reaches the same runtime, and the memo cache is still keyed on it. On the `none` path the directory is no longer created, which is the intended difference. Any caller that constructs an executor without the new argument fails at call time with a `TypeError`, not silently. Rollback is a revert of the single commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Two things arrive together because the second is what made the first usable.
**Run raven from a container.** A Dockerfile builds the page, the Python
environment and the engine into one image; `cd docker && docker compose up`
serves it. nginx serves the built page and proxies the RPC socket to the engine
over the loopback they share -- the engine binds 127.0.0.1 only, so a proxy in a
second container would have no address to dial. Compose publishes on 127.0.0.1,
and the entrypoint prints a one-time sign-in link on boot.
**A first run is no longer a dead end.** The gateway used to refuse to start
until a provider was configured, while being the thing that serves the page
where a provider gets configured. It now starts, says what is missing, and picks
up a key saved in Settings on the next turn without a restart. The onboarding
overlay no longer takes the page either: New chat, the model chip and Send send
the reader to Settings > Models instead, and an empty model list is marked on
the control that fills it.
Also carried: the provider catalogue registry (capabilities, modalities and
context windows per model), the reworked Settings > Models pane, and four fixes
found in review of that work -- a sibling catalogue answering 200 with a
non-catalogue body no longer crashes the whole fetch; adding a tag no longer
erases the label and description already stored for that model; `authenticated`
no longer demands a bearer token from a local provider reached by address; and
registry rows are keyed by the spelling every lookup produces, which recovers
593 rows that no reader could reach.
## Type
- [ ] Fix
- [x] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands run on the branch head, with their results:
- `uv run pytest tests -q -k "provider or registry or catalog or model or rpc or gateway or docker or i18n"` -- 4389 passed, 46 skipped
- `npx vitest run` in `ui-web` -- 1573 passed (101 files)
- `npx vitest run` in `ui-tui` -- 2037 passed (142 files)
- `uv run ruff check raven scripts tests` and `ruff format --check` -- clean
- `npx tsc --noEmit` in `ui-web` and `npm run type-check` in `ui-tui` -- clean
- `npm run lint:rpc` in `ui-tui` -- generated.ts in sync
- `make check-source-language`, `make check-large-files` -- clean
Each of the four review fixes was checked by reverting it and watching a named
test go red, then restoring it.
The container image itself has not been built by CI or by me -- no Docker daemon
was available on the machine this was written on. It has been built and run by
the author of the branch.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Two deliberate security trade-offs in the container deployment, both documented
in `docker/README.md`:
- nginx rewrites the `Origin` header, because the engine accepts only an Origin
naming its own loopback port and no browser reaching a published port can send
one. This drops a defence-in-depth layer. The session cookie is
SameSite=Strict, so an unauthenticated socket is still refused -- but SameSite
ignores ports, so another page on localhost counts as same-site.
- `RAVEN_AUTO_LOGIN=1` is the default: nginx attaches the session cookie to
every page load, so anyone who can reach the published port is signed in. It
is contained by Compose publishing on 127.0.0.1 only. Set it to 0 for any
deployment reachable from elsewhere. These are two settings that must agree,
and nothing warns when they do not.
Behaviour changes outside the container: the gateway now starts without a
configured provider rather than exiting 1, and the first-run onboarding overlay
no longer opens by default (`?onboard=1` still forces it).
Rollback is by revert; nothing here migrates state or changes an on-disk format.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.
`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.
`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.
`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands and results, all at the branch head after rebasing onto `main`:
```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s
$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s
$ make lint-python # ruff check + ruff format --check
exit 0
$ make lint-imports
Contracts: 9 kept, 0 broken.
$ make lint-ui
exit 0
$ make check-source-language
exit 0
$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```
Two regression tests were added next to the existing state-directory fence cases:
- the session-workdir call reads a node's report under the sessions tree and still
refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
while one pinned at the state root itself does not.
The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.
Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.
Known gaps, disclosed rather than worked around:
- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
`bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
gateway's own file paths, not through a rebuilt page bundle.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.
`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.
Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.
## Related Issues
N/A
## Summary
The web file viewer refused every file a sub-agent's DAG node writes, and said the
wrong thing about why. Clicking such a report answered `403`, which the page renders
as "Raven is confined to the working directory" -- while `restrict_to_workspace` was
off and the real refusal came from the state-directory fence.
`/file` resolves a request against the session's working directory when the page names
a session. It also handed that directory to `in_state_dir` in the role that function
reserves for agent home. The fence derives its two exemptions from that argument -- the
workspace itself, and the per-channel working-directory root beside it -- so with the
session's directory in home's place the exemptions covered `~/.raven/tmp/<channel>` and
a sibling that does not exist. Everything the DAG runner writes under
`~/.raven/workspace/sessions/` then read as raven's own state and was refused, which is
the same defect the workspace exemption exists to prevent, one directory over. A
node's report was drawn on the shelf as a delivery and would not open.
`resolve_readable` now keeps the two roles apart. The caller's workspace still anchors
relative paths and the `restrict_to_workspace` fence; the state-directory fence is
anchored on `cfg.workspace_path`, and the session's directory is passed alongside it
through a new variadic parameter that adds to what the fence exempts rather than
replacing what it derives. A session pinned to a directory under the state root
therefore keeps its files, and every exemption -- derived or added -- is held to the
same direction check, so the state root itself and its ancestors still earn none.
`serve.json` and `config.json` stay refused on every path tested.
`_resolve_inside`, which backs `fs.list` and `fs.read`, carried the same substitution.
Its containment check hid the symptom, so nothing had surfaced there yet; it is
anchored the same way now, because the fence's contract is that the viewer, the `fs.*`
panel and `fs.reveal` answer alike for a given file.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands and results, all at the branch head after rebasing onto `main`:
```console
$ uv run pytest tests/test_rpc_transport.py tests/test_rpc_console.py tests/test_rpc_knowledge.py -q
147 passed in 2.84s
$ uv run pytest tests/test_rpc_files.py tests/test_utils_office.py -q
33 passed in 2.70s
$ make lint-python # ruff check + ruff format --check
exit 0
$ make lint-imports
Contracts: 9 kept, 0 broken.
$ make lint-ui
exit 0
$ make check-source-language
exit 0
$ uv run python scripts/check_commit_messages.py origin/main..HEAD
exit 0
```
Two regression tests were added next to the existing state-directory fence cases:
- the session-workdir call reads a node's report under the sessions tree and still
refuses `serve.json`;
- a session pinned to a directory under the state root keeps serving its own files,
while one pinned at the state root itself does not.
The first was proved load-bearing by reverting the fix and re-running it, which failed
with `PermissionError: ... is inside raven's state directory` on the report path. The
second is unchanged by the fix and is there to pin the behaviour the change must not
lose.
Behaviour was also checked against the running gateway's own files, on the real paths:
with the session's working directory supplied, a node's report resolves and both
`serve.json` and `config.json` raise `PermissionError`.
Known gaps, disclosed rather than worked around:
- `make lint-tui` and `make lint-bridge` do not pass in this environment. The first
reports `src/i18n/messages.generated.ts` stale, the second `tsc: not found`. Both fail
identically on a clean `main` worktree, and this change touches neither `ui-tui/` nor
`bridge/`.
- No browser check. The refusal and the fix were exercised through the resolver and the
gateway's own file paths, not through a rebuilt page bundle.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The fence's decisions are unchanged except for the one it was getting wrong. Nothing
that was refused before this change becomes readable, apart from the session-directory
subtree the fence was never meant to refuse: the added exemption is bounded by the same
direction check as the derived ones, so no ancestor of raven's state root and not the
root itself can ride it. The credential files were re-checked as refused on every path
the tests and the live probe cover.
`in_state_dir` gains a variadic parameter with no required argument, so existing calls
keep compiling and keep their previous meaning. Both in-tree callers were updated in
this change; there are no others.
Rollback is reverting the commit. The change is three files of resolver logic plus its
tests, with no migration, no stored state and no wire-format change.
## Related Issues
N/A
## Summary
A sub-agent whose whole output budget goes to reasoning returns an empty turn, and nothing
downstream can tell that apart from a run that simply had nothing to say. The observed case
spent sixteen minutes on six generations, each cut at the model's ceiling, with no tool call
and nothing on disk. The node was recorded `completed`, because the turn returned normally,
so the DAG never saw the cuts at all.
This carries that one fact from the run to the thing that judges it.
**Re-measured on the current base, because the target moved under this.** A change landed
meanwhile that attacks the same incident from the other side: the plain-empty retry now asks
a different question each time by lowering the reasoning effort, and a spent ladder ends the
turn as an error naming the budgets it burned rather than as the canned no-answer line. That
covers the lane running the shared agent loop, and on it this branch now adds the typed fact
and the category rather than the only account of what happened.
It does not cover the built-in sub-agent lane, which has no empty-response ladder at all. A
single cut response with no tool call leaves the raw content as the answer; an empty string
is not `None`, so the guard that raises for "nothing to hand back" does not fire, the run
logs that it completed successfully, and the reply is empty with nothing saying why.
Both lanes were re-measured through the real DAG runner on this branch, with the judge stubbed
to pass so the raw status could be read. A node whose run was cut at the ceiling ends
`completed`, `crashed` False, with an empty answer, and carries this fact. So the verdict is
still the only thing that can catch it, and on the built-in lane this fact is the only signal
that anything went wrong.
**Where the fact comes from.** Whichever lane holds it. A run this process hosts reads the
response flag directly, and reports before the no-answer raise so a run that ends with
nothing carries the reason too. A run behind ACP reports it the way the protocol already
provides for: `stopReason: max_tokens`. Raven serving the agent side sends that for a turn
whose generation stopped at the ceiling, refined from `end_turn` only -- `cancelled` and
`refusal` already say why the turn ended and the ceiling does not overwrite them -- and
driving the agent side it reads that value.
Using the protocol's field rather than a private metadata key is what makes the feature
work for agents other than Raven: any conforming agent already reports a ceiling hit this
way. It also keeps the Response Meta boundary intact -- that table is the agent's own
record, which the canonical term says the host decides nothing from.
**Why the session carries it inside a Raven agent.** A turn that spent its budget reasoning
persists no assistant row at all, so the message-seated observer stash has nowhere to land.
The slot is stamped with the index the turn's rows start at, which is how a reader tells this
turn's fact from an earlier one's, and every turn either writes it or clears it. The index
alone would not be enough: it is only monotonic until a history reset or an undo moves it
back, and an old marker could then sit at an index a later turn's own start satisfies -- so
that turn would be reported as cut, which is a wrong fact rather than a missing one. Writing
or clearing on every turn is what makes the slot turn-scoped.
**Why the response flag rather than the finish reason, in-process.** The flag is the union of
two pieces of evidence, and an upstream can answer a ceiling hit with a success claim
instead. One live trace in the investigated session reported `tool_calls` at exactly 16384
output tokens.
**What the judge is told.** The fact reaches both verdict calls -- the ordinary one and the
crashed-node one, since a run can crash because it was cut and naming why is that call's job
-- and `output_limit` joins the verdict categories, so the report the orchestrator
adjudicates on says what happened instead of falling to `other`.
It is stated outside the untrusted fence because it is read off the run's transport rather
than out of the answer the sub-agent composed. It does not claim to be a measurement made
here: for a delegated agent it is that agent's own report of why its turn ended, and the
wording says so, because an unfenced fact an agent can assert about itself is one the judge
should know the source of.
The instruction is deliberately neutral about what arrived. The trigger proves the run was
cut and says nothing about what the task owed, so an instruction presuming a short answer
would mislead on a turn cut after delivering one. It says the cut does not excuse work that
is not there, and leaves the judging to the material.
**Meaning of the signal.** The run's last generation was cut. A round that was cut and then
answered in full does not carry it. It is absent wherever a transport cannot report it --
the OpenAI-compatible agent protocol exposes no finish reason at all -- so absence reads as
"not known to have been cut", never "ran to completion".
**One fix found on the way, and it is the sharper half.** The verdict fail-open exists so an
unavailable judgement cannot fail a node, and it was swallowing `TypeError` from the call
itself. A judge whose signature drifts from the runner therefore marked every node
accomplished -- the verdict system switched off with nothing anywhere failing. Adding the
keyword above reproduced exactly that: the production judge had a strict signature, so a run
reported two nodes completed and zero failed while the traceback was logged. Raising is not
enough, because the raise is caught further out and the node stays `completed`; the node now
fails and says the judge could not be called.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Commands and results, in a worktree cut from the target branch:
- `uv run --all-extras pytest` -- 20821 passed, 170 skipped, 1 failed.
The one failure is `tests/test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`,
which is inherited and terminal-width dependent, not introduced here. Proven both ways at
the current base: it fails identically there, and it passes on this branch under
`COLUMNS=200`. 0 introduced.
- The touched suites, re-run after the rebase onto the current base -- 842 passed, 0 failed.
The agent loop is touched, so the loop, ACP, verdict, runner, manager, truncation, budget
and living-docs suites were run rather than the changed files alone.
- Node-level attribution measured through the real DAG runner, with a real built-in backend
whose every generation is cut at the ceiling and the judge stubbed to pass: both nodes end
`completed`, `crashed` False, output empty, and both carry the fact to the judge.
- `uv run ruff check raven/ tests/` -- All checks passed.
- `uv run ruff format --check raven/ tests/` -- 1538 files already formatted.
- `uv run python scripts/check_commit_messages.py` over the range -- exit 0.
- `make check-source-language` -- exit 0.
- `uv run --all-extras pytest tests/test_kernel_budget.py` -- 5 passed. This gate caught a
real defect during development: a new constant put the papers tree one line over its
reviewed ceiling, so the constant moved rather than the ceiling being bumped. The switch
to the protocol stop reason later removed that constant entirely.
Each new test was watched failing before the code that satisfies it, including the two
findings from the pre-submit sweep and both review blockers. The stop-reason rework was
driven red first: five tests, covering the refinement, the earlier-turn scoping, the refusal
to overwrite a more specific reason, the client reading the protocol field, and Response
Meta alone never recording the fact.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
**Behaviour changes a reader should know about.** Three.
A cut reply from a Raven agent behind ACP now carries the `[raven]` notice the client already
appends for any non-`end_turn` stop reason, naming `max_tokens`. That is the documented
purpose of that notice, and it is an improvement here: the original incident's reply said
nothing at all about having been cut. It is new visible text on that path.
A DAG node whose judge cannot be called now fails instead of passing. That is the point of
that fix, and it converts a silent, total loss of the verdict gate into a loud per-node
failure. If a judge implementation outside this repo has a strict signature, its nodes will
fail rather than silently pass; the error text names the cause.
A judged node can now be reported under a new category. Anything switching on the category
set sees one more member; unknown categories already fold to `other` on the read side, so an
older reader degrades rather than breaks.
**Rollback.** Revert the commits; nothing migrates and nothing persists beyond one
per-session metadata key that is overwritten each turn and ignored when absent.
**Deliberately not fixed, with reasons.** The OpenAI-compatible agent backend exposes no
finish reason, so it reports nothing and its nodes keep today's behaviour -- the signal is
either reported or absent, never inferred.
The built-in sub-agent lane treating an empty answer as an answer -- assigning the raw
content, so `""` sails past the `is None` guard written to raise for exactly this -- is a
defect of its own, older than this branch and reachable without it. Naming it here rather
than widening the diff into that loop under a branch about reporting. A host-side heuristic over the transcript shape
was considered and rejected: it cannot separate "hit the ceiling" from "returned empty",
which is the distinction the change exists to make.
**Checked and deliberately not changed.** The archived plan document carries the older
category list; the living-document rule makes it correct about its own date, so the spec was
updated and the plan was left alone.
## Related Issues
N/A