## Summary
The release notes template had drifted from what main ships, so the
draft CI
builds for the next tag would carry four stale statements. This brings
the
template, and RELEASING.md which describes it, in line with main.
- Install: `install.sh` now downloads the word dictionary and PDF models
the
knowledge reader uses (#489). `RAVEN_MINIMAL=1` skips them and
`install.ps1`
does not download them, so the section names `raven resources` for both
cases.
- Install: bare `raven` opens the page where a browser can be opened and
the TUI
only otherwise; the terminal entry is `raven tui`. The v0.2.4 notes
corrected
this by hand, but the template kept the old sentence.
- Upgrade: the update row at the bottom of the sidebar upgrades a page
served by
0.2.3 or later. This too was written into the v0.2.4 notes by hand.
- Assets: a release attaches four plugin wheels since #883 added
`everos_cloud_memory`; the plugin list still installs the other three.
This should merge before the 0.2.5 version bump (#1025), so the drafts
its tags
build start from the corrected template.
Each statement was checked against main:
- `install.sh` runs `raven.resources --optional` unless `RAVEN_MINIMAL`
is set;
`install.ps1` has no resource step.
- With no subcommand, `raven` opens the page when a browser can be
opened and
the TUI otherwise (`raven/cli/commands.py`).
- `release.yml` builds the `everos-cloud-memory` wheel beside the other
three
plugin wheels and uploads every wheel, while `raven-plugins.txt` lists
only
`everos_memory`, `design_engine` and `ppt_engine`.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `sed "s/__VERSION__/9.9.9/g; s/__TAG__/v9.9.9/g"
.github/release-notes-template.md`,
the substitution `release.yml` runs: no placeholder is left, and the
three
TODO markers the draft keeps for hand-filling are unchanged.
- `PYTHONPATH=. python3 scripts/check_commit_messages.py
origin/main..HEAD`:
exit 0
- `npx commitlint --from origin/main --to HEAD --config
commitlint.config.cjs`:
exit 0
- `PYTHONPATH=. python3 scripts/check_large_files.py origin/main..HEAD`
and
`PYTHONPATH=. python3 scripts/check_source_language.py
origin/main..HEAD`:
exit 0
- No test run: no test reads either file.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Docs only. What changes is the Install, Upgrade and Release Status text
of the
next release drafts. Rollback is reverting this commit.
- [ ] 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 research, code, oncall and ppt agents keep prompt files in their
workspace that the model reads on every turn:
`agent_memory/profile/soul.md`, `agent_memory/profile/agent.md` and
`TOOLS.md`. They were written only when absent (`seed_once`), so after a
raven upgrade or a config change the model kept reading the text of the
first launch while the gates enforced the current release. A
Raven-Research install seeded before the reader layout still asked the
model for the `## Answer` / `## Findings` / `## Limitations` report
while its shape gate checked the reader layout.
These files are now generated output:
- `write_generated()` in `raven/config/product_render.py` rewrites a
product-owned file from the release and the rendered config on every
launch.
- An operator's own lines go in the sibling `*.local.md` file
(`agent_memory/profile/agent.local.md`, `soul.local.md`,
`TOOLS.local.md`) and are appended after the product text at the next
launch. They must be UTF-8: one in another encoding (an editor's legacy
code page, GBK for example) raises a decode error that names the
`*.local.md` and asks for UTF-8, rather than one naming the generated
file.
- A receipt beside each file (`.<name>.generated.sha256`) records
`<owner> <digest>` for the last text written. A file the caller's own
receipt lines do not name (edited in place, written by another product,
or left by an older release) is backed up to `<name>.bak-<time>-<pid>`
before it is replaced, and the log says which of those it is when the
receipt can tell. A backup is never readable by more accounts than the
original: on POSIX an owner-only copy; on Windows, where a new file
takes its folder's inherited ACL whatever mode it is created with, a
hard link to the file itself, so it keeps the file's security descriptor
and no bytes are written. A Windows volume that cannot hard-link refuses
the backup, and a failed backup leaves the file untouched. While the
target changes, the receipt names both texts, so a failure between the
two writes never leaves a file the next launch cannot recognise.
- `product_text=None` (raven-code's `CODE_CONDUCT=off`) removes only a
file this product wrote; an edited one, or another product's file and
receipt, is left alone.
- The launchers pass `adopt=True`, since their home is the product's own
ACP home, and refuse to start with the file named when a prompt cannot
be written. On a raven without `write_generated` they fall back to
seeding once and log that the file will not be refreshed.
- The ppt engine writes into whatever home its plugin is granted, which
can be a host's or another product's, so it passes `adopt=False`: it
replaces only a seat its own receipt, or the digest of a prompt it has
shipped, shows it wrote. A test fails when a ppt prompt changes without
its digest being added. It marks its identity written only once the
write lands and retries on the next turn otherwise. A seat that fails
does not stop the other seats; the host's template sync waits for the
retry, since it would fill the failed seat and a seat the engine did not
write is never replaced. A seat it leaves alone is logged at DEBUG, not
WARNING: in a host's home those are the host's own, every process, with
nothing to act on. The notice says how to hand a seat back (move the
lines into `*.local.md`, delete the file), which is what a seat edited
in Raven-PPT's own home before this release needs; the docs name that
exception.
- raven-code's earlier per-file receipts and legacy digests are still
honoured, so untouched copies are refreshed without a backup.
- `atomic_replace()` takes a `newline` argument so generated files stay
LF on every platform. It also removes its temp file when the replace
fails, and removes a temp file already present before it writes,
clearing the read-only attribute first: Windows refuses to replace a
read-only target once the temp file has taken its mode, and the
read-only temp file left behind used to fail every later launch even
after the target was made writable again.
- The temp file `atomic_replace()` writes is created no more open than
the target from its first byte. On Windows a new file takes its folder's
inherited ACL and `os.replace` (`MoveFileExW`) moves that descriptor
onto the target, so a prompt kept private in a folder other accounts may
read came back readable by them, `*.local.md` lines included. When the
target exists, the temp file is now made by `CreateFileW` with the
target's DACL as `GetFileSecurityW` reads it, and the save is refused
when that DACL cannot be read. On POSIX it is created with the target's
mode rather than the umask default, closing the span in which the new
text sat in a wider file until the chmod. This holds for every caller
that passes no explicit mode, `config.json` included. The Win32 bindings
behind it are declared once per process, behind a cache: a structure
defined per call left a new ctypes pointer type, about 6 KB, alive for
every save.
Docs: `agents/README.md` (the seed-once contract becomes "Regenerated
prompts", with rollback steps), `docs-site` agent integrations (en and
zh), `CONTEXT-MAP.md`, and `CHANGELOG.md` (an unreleased entry that
promised the old behaviour, plus a Fixed entry).
Tests whose meaning changed: seven existing tests asserted that an
edited prompt is never overwritten; they now assert it is backed up and
regenerated. The raven-code launcher test fixture now pins
`CODE_CONDUCT` and `CODE_CONDUCT_DISCIPLINE` to `on`: a deleted switch
fell back to the developer's `.env`, and two conduct tests on main
already failed with `CODE_CONDUCT_DISCIPLINE=off` for that reason.
Checked and deliberately not changed (documented in `agents/README.md`):
- The processes of one product (one per model binding) share these
files, so a launch can change what an older process still running reads
on its next turn. Closing that needs a per-process snapshot or
in-process injection of the prompt, which is a separate change.
- Backups are never deleted automatically.
- Host workspace templates (`USER.md`, `HEARTBEAT.md` and the rest) are
the user's files and stay write-if-missing.
- A file removed from a release is not removed from an installed
`~/.raven/agents` copy. Nothing loads such a leftover today: modes are
read by label, tools are imported by name, and no release has removed a
skill directory.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run at the head of this branch, rebased on the current main:
- `uv run pytest -q`: 32739 passed, 17 failed, 147 skipped, 2 xfailed.
The same 17 test IDs fail on the current main in a clean worktree with
the same interpreter and the same fetched tokenizer dictionary (proxy
redaction, tokenizer data, network-safety resolution, install script,
document converters, node runtime, trajectory time zone); none is
introduced here.
- `uv run pytest tests/test_agents_code_launcher.py -q` with
`CODE_CONDUCT` and `CODE_CONDUCT_DISCIPLINE` each set to `off` in the
environment, alone and together: 79 passed in all four runs.
- `make lint-python lint-imports lint-types lint-deps`: all pass, 10
import contracts kept, no dependency issues.
- `scripts/check_commit_messages.py`, `scripts/check_source_language.py`
and `scripts/check_large_files.py` over `origin/main..HEAD`, and `git
diff --check`: pass.
- Each fix was reverted on its own and its test went red: the receipt
written after the target, a failed target write, the backup mode, the
ppt `adopt=False` guard, receipts without an owner, an undeletable
earlier receipt, the `*.local.md` read-back from the assembled system
prompt, the temp file a failed replace leaves behind, and the temp
file's mode while it holds the new text.
- Windows review findings:
`test_a_windows_backup_is_the_edited_file_itself_so_its_acl_comes_with_it`
and `test_a_windows_backup_the_volume_cannot_link_is_refused_not_copied`
force the link path on Linux;
`test_a_failed_replace_takes_its_tmp_with_it` and
`test_a_read_only_tmp_a_dead_writer_left_does_not_block_the_replace`
cover the temp file on every platform;
`test_the_tmp_is_never_more_open_than_the_target_while_it_holds_the_new_bytes`
pins the POSIX mode from creation;
`test_a_read_only_prompt_regenerates_once_it_is_writable_again`
(read-only retry) and
`test_a_private_windows_prompt_keeps_its_own_dacl_when_regenerated_and_backed_up`
(a private prompt in a folder every local user may read keeps its own
DACL through regeneration and backup, read back with `icacls /save`) run
on Windows only.
- The `Windows ACP stdio` CI job gains a step that runs
`tests/test_config_product_render.py` and the two temp-file tests
natively. On the Windows runner: 158 passed, 2 skipped (the two
POSIX-mode tests), the DACL, read-only retry and hard-link backup tests
among the passes.
- Diff coverage over `raven/` with the related suites: 94.12%, above the
90% gate.
- Second-round review findings, each test red without its fix:
`test_an_addendum_that_is_not_utf8_is_named_and_nothing_is_written`,
`test_a_local_file_that_is_not_utf8_is_named_when_the_launch_stops` and
`test_an_addendum_that_is_not_utf8_names_itself_and_holds_back_no_other_seat`
(the decode error names the addendum; the ppt engine writes the other
seats and holds the sync);
`test_a_hosts_own_seats_are_left_alone_without_a_warning_in_every_process`
and `test_a_seat_left_alone_says_how_to_hand_it_back` (DEBUG level, and
the notice's instructions);
`test_the_windows_bindings_are_declared_once_not_per_save` (Win32
stand-ins on Linux, two saves load each DLL once).
Windows is covered by the CI step above, not by a local run. The CRLF
fold of an older copy is reasoned, not run. `npx commitlint` is not
installed on the machine this was run on; the Python commit check above
was run instead.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- User-visible: on the first launch after upgrading, each agent rewrites
its prompt files. A file edited in place, or left by an older release
without a receipt, is copied to `<name>.bak-*` and the launcher log
names the copy; an in-place edit stops taking effect until its lines are
moved into `*.local.md`. A `*.local.md` that is not UTF-8 stops the
launch with the file named. In Raven-PPT's own home a seat edited before
this release keeps the edit, and its `*.local.md` is not applied, until
the seat is deleted. A Raven-Research install seeded before the reader
layout switches to it at that launch.
- Security: a backup is never readable by more accounts than the file it
keeps (an owner-only copy on POSIX, a hard link keeping the file's ACL
on Windows), and a replaced file keeps its own mode, and on Windows its
DACL, from the temp file's first byte; receipts hold product names and
digests only; `*.local.md` is operator-owned and carries the same trust
as editing `agent.md` did before.
- Compatibility: a launcher running on a raven without `write_generated`
seeds once and logs it; the ppt engine on such a raven keeps
write-if-missing. On a Windows volume that cannot hard-link (FAT32,
exFAT, some network shares), an edited prompt file stops the launch with
the file named, until its lines move to `*.local.md` and the file is
deleted. On Windows, a save through `atomic_replace()` whose target's
DACL cannot be read is refused rather than made with the folder's ACL.
- Rollback: revert this change, then stop the product's processes,
delete each generated file whose `.<name>.generated.sha256` receipt
still names its current text, and relaunch so the older code seeds its
own. `*.local.md` files, backups and edited files are left as they are.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: userName20260323 <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
Pin the suite's per-test home in the pytest process and in a child
Python process, and run these regressions explicitly in the Windows ACP
job. This prevents a future fixture change from sending test
configuration or SSH aliases into the runner's real profile.
Main already routes the home fixture through `tests._home.point_home`,
which sets both `HOME` and `USERPROFILE`. The rebase keeps that
implementation and every other main fixture unchanged. This PR now adds
only two regression tests and their Windows CI step; it no longer
introduces a separate Windows-only environment assignment.
The tests check `Path.home()`, tilde expansion for `.ssh/config`,
`raven_home()` and the inherited child-process home. Main's existing
guard continues to check both path flavours and environment variables.
All existing Windows ACP steps remain present.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
On the rebased tree, Linux and Python 3.12.13:
```bash
uv run --frozen --no-sync pytest \
tests/test_conftest_home.py tests/test_conftest_no_real_home.py \
tests/test_conftest_idle_ceiling.py tests/test_conftest_utf8_guard.py \
tests/test_ops_connection_add.py tests/test_cli_ops_connection_commands.py \
tests/test_subagent_host_env.py tests/test_sandbox_unit.py -q -n 0 --tb=short
```
243 passed. HTTP(S) and ALL proxy variables were unset for the run.
- The resolved `tests/conftest.py` is byte-identical to main, including
the Codex network and EverOS isolation fixtures.
- The new test file is byte-identical to the original PR. Removing this
PR's one Windows step from the parsed workflow reproduces main's
complete job definitions.
- `uv run --frozen --no-sync ruff check tests/test_conftest_home.py` and
`uv run --frozen --no-sync ruff format --check
tests/test_conftest_home.py`: pass.
- `uv run --frozen --no-sync pre-commit run --files
.github/workflows/ci.yml tests/test_conftest_home.py`: pass.
- `UV_NO_SYNC=1 make check-large-files check-source-language
COMMIT_RANGE=origin/main...HEAD` and `uv run --no-sync python
scripts/check_commit_messages.py origin/main..HEAD`: pass.
Native Windows validation of this rebased combination is provided by the
Windows ACP CI job. The original branch's native Windows measurements
are historical and are not reused as verification of this rebase.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (test-only
change)
## Risk
No product code or test-home fixture changes relative to current main.
The additional Windows step runs the two home regressions before the
existing ACP checks. `APPDATA`, `LOCALAPPDATA` and agents discovered on
PATH retain main's existing behavior.
Rollback removes the added tests and CI step while preserving main's
home isolation.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
A sub-agent DAG node can now decide which of its downstream branches
run. Before this, a background run could not turn on a result: every
node ran, and choosing a path meant the host winding the run down and
starting another.
How it works:
- A node that declares `routes` (route name to condition) is a decision
node; `select` is `"one"` (the default) or `"many"`. Raven's per-node
judge, the existing verdict call, picks the route or routes the node's
answer satisfies. The node's own text never selects a route. A route
that cannot be determined fails the node, with no fallback route.
- A downstream node carries `when`, a guard over `<node>.<route>` and
`<node>.done` atoms joined with `not`, `and`, `or` and parentheses,
evaluated with three-valued logic: a route of a decision node that was
never executed is unknown. Every decision node in a node's `depends_on`
must appear in its `when`; such graphs are refused at submission
otherwise, along with guards that can never hold and a route named
`done` in any letter case. Validation keeps negation parity and the
surrounding boolean expression: a double-negated `done` and a
disjunction with a satisfiable arm are accepted, without expanding
disjunctions into combinations.
- A node that does not run is `not_executed`, with a reason:
`when_false`, `when_unknown` or `upstream_not_executed`. A node whose
dependencies all went unexecuted is not executed either; a failed or
skipped dependency still skips its dependents first.
- A merge node reads a missing upstream as a fixed sentence, `<This task
is not executed and the output is missing, please go on without this
output.>`, written outside every untrusted-content fence, plus a note
listing the inputs that may be missing. A file reference to the files of
a node that may not execute is refused at submission however its path is
spelled: `@nodes/`, an absolute path into the node root, or a workdir
path that lands there, symlinks followed. Windows case, separator and
drive-relative aliases are recognized, and the advice keeps the declared
node ID.
- Node judgement is always on: the `subagentDag.verdictEnabled` switch
is retired. Config migration 14 removes it with a notice, and drops it
again on every later load should an older build sharing the config write
it back. `raven playbook run` now judges its nodes too, on the same
`subagentDag` settings and a pinned `verdictModel`'s own provider; with
nobody there to answer, a node judged not to have accomplished its task
fails on the judge's reason. A host with no judge at all refuses graphs
that declare routes.
Where it shows:
- Run events, the manifest, `dag.get`, `tasks.list` and
`dag.run_completed` carry `reason`, `selected_routes` and
`route_evidence` per node, and `routes`, `select` and `when` from the
graph. The instance registry's DAG-node rows (and `InstanceRow`) carry
the outcome too, so a client that reloads before the run finalizes shows
what a branch decided. `TaskCounts.not_executed` is a new counter.
- TUI: a not-executed node shows a hollow marker and its reason in
words; a decision node shows its selection on the node's second line,
and the guard and route evidence in the detail and in `/dag <node>`. The
Agents Overlay and the live agents strip leave not-executed nodes out,
as the backend's agent lists do.
- Web: the desk's tasks tab names not-executed steps and shows the same
fields.
- Playbooks pass the three fields through, namespace guard atoms with
the run prefix, and keep them through compilation.
- The `run_subagent_dag` schema, the DAG orchestration skill and the
docs site (English and Chinese) describe routes, guards and the merge
rule; CHANGELOG has the entries.
A graph with no `routes` and no `when` behaves exactly as before: the
same judge requests, events, records, summary and finish text.
`route_evidence` is a quote the judge picks from the sub-agent's output;
it is cut at 500 characters, keeps a lone surrogate from a malformed
escape as the escape's own text, and never enters model-facing text
(finish text, `dag_status`, exception reports). When a judge answer does
not report a usable route, the judge is asked again at most twice, each
time with one correction. The shared instance registry drops its cache
when a write fails on the data rather than the disk, so a row the file
cannot hold fails its own write and no other.
Two Windows CI steps run the alias and finish-text regressions; the
latter exposes the installed Git `cat` executable required by the
existing fixture.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Linux, Python 3.12.13, on this revision rebased onto the current main
(`$CHECKS` is a temporary evidence directory):
```sh
uv run --frozen --no-sync pytest -q -n 4
# 23 failed, 33229 passed, 162 skipped, 1 xfailed, 3 errors
uv run --frozen --no-sync pytest $(git diff --name-only origin/main...HEAD -- tests/) -q -n 4 --idle-ceiling-strict --cov=raven --cov-branch --cov-report=json:$CHECKS/coverage.json
# the 20 test files this branch changes: 2622 passed, 1 skipped (a POSIX permission case that does not apply to root)
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json "$CHECKS/coverage.json" diff --base-ref origin/main --head HEAD --threshold 90
# Diff coverage: 99.48% (764/768 executable changed lines), passed the 90.00% threshold
```
The full run's 23 failures and 3 errors are 25 tests. 24 of them fail
the same way on the current main in this environment: the venv lacks
`nltk` and `datrie` (16), a proxy is set in the environment (5), this
box has its own `npm` in `/usr/bin` (1 install-script case), LibreOffice
writes no `.xls` here (1), and the run is root (1). The 25th,
`test_a_cli_run_left_on_the_machine_when_this_computer_stops_is_picked_up_by_the_next_start`,
failed with its teardown in the full run and in one of two runs of its
file, and passed in five runs on its own: it reads the remote-run record
the moment its pid file appears, a race in code this branch does not
change (#840 makes that test wait for both). The four uncovered changed
lines are the gateway's `_verdict_provider` body, whose helper is tested
on its own; a guard atom over a node that did not complete, which the
runner never evaluates because it reads a guard only once every
dependency completed or was not executed; and the cut of an over-long
terminal output.
Ruff check and format, `ty check` over the changed modules, the import
contracts, `deptry raven`, commitlint, and
`scripts/check_commit_messages.py`, `check_large_files.py` and
`check_source_language.py` over this branch's commits pass. ui-web:
`vitest run src/features/tasks/BoardCard.test.tsx scripts/gates` passes
50 files and 244 tests, and `tsc --noEmit` is clean. In Chromium a
not-executed title whose first word is wider than the room beside its
status now breaks that word instead of starting under a blank line, and
every other tasks-board card renders pixel-identical, English and
Chinese, light and dark. Firefox still starts such a title under a blank
line and cuts it without an ellipsis. CI's `TUI checks` covers ui-tui.
Mutation checks: removing any one of these makes its own test fail: the
every-load strip of the retired switch, the quote's escape before the
cut, the registry's cache drop, the node-root check in the tool, the
runner and the replan path, the physical path through a symlink, the
CLI's judge, its settings and its no-answer failure, and the pinned
judge provider. A model reading only the DAG skill's catch-all paragraph
answers that without a catch-all route the judge may pick the nearest
route or fail the node; an earlier wording led it to answer that the
graph always stops.
A live run on `openrouter/z-ai/glm-5.3-flash`, two graphs with synthetic
messages, selected the expected route at each decision node, left the
unselected branch `not_executed` with `when_false`, and put the fixed
sentence outside the fences. Earlier revisions of this change passed the
native Windows selections (aliases, finish text, guards; Windows build
26300, Python 3.13.12). The final revision has not been rerun on native
Windows or macOS.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Security: sub-agent text stays fenced or out of model-facing text on
every new path. The routes block in the judge request sits after the
last untrusted fence and is labelled as the graph author's; the
missing-output sentence is written outside every fence; `route_evidence`
is bounded and reaches records, events, the registry and the UIs only.
In the TUI, route evidence is drawn through the same path as a node's
error text; neither strips terminal control sequences, which this PR
leaves as it is.
Behaviour changes: a config that set `subagentDag.verdictEnabled: false`
now gets judged nodes; migration 14 removes the key and says so once.
`raven playbook run` judges every node, one more model call per node,
and a node judged not to have accomplished its task fails there instead
of completing. New wire fields are optional except
`TaskCounts.not_executed`, which is always present (0 when nothing
branched). `InstanceRow` gains three optional fields, and a decision
node's registry row now also stores its selection and up to 500
characters of route evidence.
Conditional-artifact validation matches node IDs using the session
namespace's case-insensitive identity on every host, including macOS.
This conservatively rejects case-only spellings even on case-sensitive
filesystems. Separator and drive normalization remain native, and
unconditional file resolution keeps its existing behaviour.
Rollback: revert the squash commit. A config already stamped 14 loads
unchanged on the previous build, since the stamp only gates migrations;
a user who had set `verdictEnabled: false` can set it again there, and a
later build drops it again on load.
## Related Issues
Related, found while building this and not changed here: #998, #999,
#1000. Follow-ups from its review, not changed here: #1008.
## Summary
The Mirasim adapter keeps one WebSocket connection to the Mirasim host
already running on the machine. It replaces the per-request `mirasim
ui-cli` processes and streams the host's session snapshots through ACP.
- Find the host through `RAVEN_MIRASIM_HOST` (`unix:<path>`, or a
loopback port as `<port>`, `127.0.0.1:<port>`, `localhost:<port>` or
`[::1]:<port>`, connected to as named), else the remote host's Unix
socket (Linux and macOS), else the desktop app's loopback port and its
token file. Tokens travel in headers. The adapter never requests
`ready` or `getConfig`, whose answers contain settings and
credentials. The WebSocket upgrade is bounded by the connect timeout.
- Stream text, thoughts, tools, sub-agents, plans, delivered files,
usage and accepted steers. Reconnect with backoff, resubscribe
sessions, and take a fresh snapshot when patches have a sequence gap.
- Live patches carry no segments; only settled history turns do. Within
one patch a call already shown settles before the text after it, and
a new call follows the text before it. A snapshot taken whole, on
subscribing, after a gap or when a queued turn is dispatched, puts its
calls before its text, so the answer after a call stays one message.
History replays in its segments' order, using the host's UTF-16
offsets.
- Support new, load with complete history replay, resume without
replay, list, close and delete. A turn running in the app while a
session loads is forwarded after the replay. Lists cover this agent's
conversations in the given directory, ones begun in Mirasim included.
Delete also removes the Mirasim conversation. A conversation the host
refuses to continue, deleted or not one of its own, is started again
once, with a note saying why. A list or history request the host
fails is refused at once with its reason, and history paging stops if
the host hands back a page it already gave.
- Cancel running tasks with `stop` and queued prompts with `recall`.
Prompts accepted after timeout remain tracked for cleanup and session
persistence. Failed or unconfirmed steers are recalled; if they
started their own task, that task is stopped by id. A prompt still in
the host's queue when the connection comes back is recognised from
the queue the host lists on resubscribe.
- Relay approvals and questions of turns Raven started through ACP
permission and elicitation requests; questions in turns Mirasim starts
are left to the app. Claude receives inline images; other agents get
an image linked as a local file as its path, and refuse inline ones.
Claude, Codex, DSH, Pi and ZCode support steering. Turns started in
Mirasim are forwarded while the adapter holds their session.
- Refuse queued prompts after session close or adapter shutdown. Every
local ACP agent whose tree a Windows Job or POSIX process group owns
gets an EOF grace that ends as soon as the agent exits. An agent may
ask for a longer one under `agentCapabilities._meta` as
`raven.shutdownGraceS`, granted up to five seconds; the Mirasim
adapter asks for five, so a first prompt the host accepts late is
still stopped. A close cancelled during the grace still releases the
connection. PID-only cleanup keeps the launcher alive for the
process-tree walk.
- The question of which agents Mirasim has runs in the environment the
presets' adapters get: the login shell's on Linux and macOS, Raven's
own on Windows. With no host reachable it lists none, and the boot
handshakes no Mirasim preset except a row that sets
`RAVEN_MIRASIM_HOST` or `MIRASIM_HOME` in its own `env`.
`readyTimeoutMs` is 150000, above the adapter's own connect and menu
limits.
The old `uicli.py` and `guard.py` transport is removed. Existing binding
files remain readable. The agent-integration documentation is updated
in English and Chinese. The Windows ACP job exercises the loopback
transport, real preset subprocesses and teardown. The live suite claims
a slot directory of its own by a lock, sweeps only that slot, and checks
the model each turn ran on.
`scripts/check_mirasim_frames.py` checks a host bundle for the frames
and fields the adapter uses. Run against the bundle that last worked, it
also reports each of those names that now occurs fewer times, which is
how a frame renamed in one of several places shows.
Protocol details verified against the host bundles 0.0.537, 0.0.547 and
0.0.558: `listSessions` filters by workdir, `getHistory` pages
backward, any prompt can set the session's route, there is no
unsubscribe frame, a request whose handler throws is answered with an
error carrying its `reqId` as `clientRef`, and live patches never carry
`segments`. Deleting a Mirasim conversation leaves the underlying
agent's transcript files intact.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Final local verification ran on Linux with Python 3.12.13 at the head
of this branch. Temporary report paths are abbreviated as `$CHECKS`.
```sh
PYTHONDONTWRITEBYTECODE=1 uv run --frozen --no-sync pytest \
tests/test_acp_mirasim_catalog.py tests/test_acp_mirasim_host.py \
tests/test_acp_mirasim_input.py tests/test_acp_mirasim_interactions.py \
tests/test_acp_mirasim_server.py tests/test_acp_mirasim_store.py \
tests/test_acp_mirasim_stream.py tests/test_check_mirasim_frames.py \
tests/test_subagent_mirasim.py tests/test_acp_client_teardown.py \
tests/test_acp_windows.py tests/test_acp_client_launch.py \
tests/test_acp_client_resume.py tests/test_subagent_probe.py \
tests/test_subagent_third_party.py tests/test_subagent_acp.py \
tests/test_acp_protocol.py \
-n 0 -q --tb=short --idle-ceiling-strict -p no:cacheprovider \
--cov=raven --cov-branch \
--cov-report=json:$CHECKS/coverage.json \
--junitxml=$CHECKS/regression.xml
# 1060 passed; no failures, errors, skips, or strict-idle violations
uv run --frozen --no-sync python scripts/coverage_gate.py \
--coverage-json $CHECKS/coverage.json \
diff --base-ref origin/main --threshold 90
# 99.20%: 1362 of 1373 executable changed lines
UV_NO_SYNC=1 make lint-python lint-types
# Ruff check/format: 2384 files; ty passes
uv run --frozen --no-sync lint-imports
# 10 contracts kept
uv run --frozen --no-sync deptry raven
# No dependency issues
uv run --frozen --no-sync pre-commit run --files <changed files>
# All applicable hooks pass
UV_NO_SYNC=1 make check-commits check-large-files check-source-language
# commitlint, commit messages, assets and source language pass
git diff --check origin/main...HEAD
# Exit 0
UV_PROJECT_ENVIRONMENT=$CHECKS/docsenv uv run --frozen --group docs \
--no-dev mkdocs build -f docs-site/mkdocs.yml --strict -d $CHECKS/site
# Built
for v in 0.0.537 0.0.547 0.0.558; do
uv run --frozen --no-sync python scripts/check_mirasim_frames.py \
~/.mirasim-remote/servers/$v/server.cjs \
--against ~/.mirasim-remote/servers/0.0.537/server.cjs
done
# Each: 13 sent frames, 11 read frames and 64 fields present,
# none fewer than in 0.0.537
PYTHONDONTWRITEBYTECODE=1 uv run --frozen --no-sync pytest \
tests/integration/test_acp_mirasim_real_llm.py \
-m integration -n 0 -q -p no:cacheprovider -rA --tb=short
# 10 passed in 346 s against the Mirasim host 0.0.537 running
# on this machine; every turn ran on glm-5.3-flash
```
Each new regression test was observed failing before its repair: the
refused unknown conversation, the reconnect with a prompt still queued,
the tool that ran while the connection was down, the turn running in
the app during a load, the repeated history page, the failed list and
history, the upgrade that never answers, the descendant holding the
agent's stdout, the close cancelled during the grace, the first prompt
the host accepts after the grace has passed, the empty agent list with
no host, the ready budget, and the frame check's count drop. The
stand-in host now hands frames to its dispatcher concurrently, as the
host does; removing the adapter's late recall makes three tests fail.
The frame check reports, against 0.0.537, copies with the dispatcher's
`stop` case renamed (6 occurrences, then 5), the six patch frames
renamed, and `coalesceMs` renamed; presence alone passed all three.
The local pass used the loopback stand-in host and real subprocess
tests; the live-model suite then ran against the Mirasim host already
running on the machine, across claude, codex, pi and zcode. Native
Windows and macOS were not run for this revision; the Windows ACP CI
job runs the four adapter test files natively.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
- Mirasim presets need a reachable host. Preset discovery still checks
for `mirasim` on the login PATH; a desktop-only install without that
executable does not offer the rows. The adapter's old `--executable`
argument is removed.
- The adapter is one more client of the user's own host: Raven's turns
show live in the Mirasim app and on paired phones, queue behind the
user's own turns on the same conversation, and end if the desktop app
closes or the host restarts. Turns the user starts in Mirasim on a
conversation Raven holds are forwarded to Raven as turns nobody
prompted.
- Removing an ACP instance now deletes its Mirasim conversation as well.
Loading a session replays its complete history. The host has no
unsubscribe operation.
- The desktop token is sent to the configured loopback endpoint, as
with `ui-cli --port`; discovery relies on the local token file and
port.
- Every local ACP agent's EOF grace now ends when the agent exits
rather than when its pipes close; an agent can ask for up to five
seconds. An unreachable host, abrupt parent death, or an adapter that
cannot finish within its grace can still prevent cancellation of work
owned by the shared host.
- Known limit: a queued prompt the host dispatches while the connection
is down is not recognised as this adapter's after it reconnects; it
is given up after 60 seconds and its turn runs on, forwarded as one
nobody prompted.
- Rollback: revert the squash commit to restore the per-request
transport. No binding migration is required. Conversations already
deleted from Mirasim are not restored by reverting code.
## Related Issues
N/A
## Summary
On native Windows, connecting an agent that runs as a process chain
failed every time with `[WinError 32] The process cannot access the file
because it is being used by another process:
'...\raven_subagent_ping_xxxx'`. The Claude Code preset is one such
chain: `npx.cmd`, `cmd.exe`, the node adapter, then `claude.exe`.
`ping_agent` handed the agent a fresh temporary directory to launch in
and removed it when its `with` block ended, which was before the
`finally` that closes the ping's pool and so ends the agent's process
tree. Windows refuses to remove a directory that a live process has as
its working directory, even an empty one, and the broad `except
Exception` turned that removal error into the ping's verdict: an agent
that had answered was reported as not answering a test message. A ping
that timed out was misreported the same way, and each press left its
directory in the temp folder.
`verify_agent`, the handshake behind Test and behind the capability
record a Connect writes once its ping passes, removed its session
directory in the same order. The Claude Agent SDK starts `claude.exe` in
the session's directory, so that check came back `unknown` with `verify
failed: [WinError 32] ...`.
Ending the tree was already right: the Job Object from #951 ends every
process in it, including descendants started later. What was wrong was
when the directory was removed, and what a failed removal was taken to
mean.
- `raven/utils/scratch.py` adds `ScratchDir`, a temporary directory that
is removed only when its caller says the agent has ended. The removal is
tried up to 5 times, 0.2 s apart, while a tree that was just ended
finishes exiting. A directory that still cannot be removed is logged
with its path and left in the temp folder, never raised. It removes
through `TemporaryDirectory.cleanup`, so read-only entries are still
cleared on Windows as before.
- `ping_agent` removes its directory after `pool.close_all()`, and
`verify_agent` after `client.close()`. The CLI test (`run_test`) and the
Kimi Code print-mode ask use `ScratchDir` as an async context manager:
their process has ended inside the block, and a refused removal no
longer replaces the CLI's reply or raises out of the ask.
- The `Windows ACP stdio` CI job runs a new real-process test of both
checks against an agent of the reported shape.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Native Windows 11 (build 26300, Python 3.12) unless marked Linux.
Reproduction with a stand-in agent of the reported shape: a `.cmd`
wrapper starting a Python ACP agent that, on `session/new`, starts a
worker in the session's directory and waits for it before answering.
- `main`: the ping returns `ok=False` with `[WinError 32] ...
raven_subagent_ping_...`; the handshake returns `unknown` with `verify
failed: [WinError 32] ... raven_acp_verify_...`; both directories stay
in `%TEMP%`.
- This branch: the ping returns `ok=True` ("it ran and replied"), the
handshake `ready`, and nothing stays in `%TEMP%`. Over 20 rounds of both
checks, all 40 directories were removed on the first try after the
close.
```text
uv run --frozen --no-sync pytest tests/integration/test_subagent_connect_windows_real_process.py -m integration -q -n 0
```
1 passed. On `main` it fails with `[WinError 32] ...
raven_subagent_ping_...`, the error text in the issue.
New unit tests: 5 in `tests/test_utils_scratch.py`, 3 in
`tests/test_subagent_acp.py`, 4 in `tests/test_subagent_probe.py` (the
CLI one is POSIX-only, like the neighbours whose shell stand-in it
shares) and 1 in `tests/test_subagent_kimi_code.py`. The ping and
handshake ordering tests run the real pool, client and stub agent, with
Windows' refusal stood in on any host by `tests/_windows_dirs.py`: a
removal is refused while an agent the test launched is not yet closed.
With the three changed modules put back to `main`, the six call-site
tests fail, each with the symptom it names (the CLI one on Linux). Each
new construct was then removed on its own, and a test goes red for every
one: removal before the pool close, removal before the client close,
either `None` guard, raising after the last try, a single try, no pause
between tries, and `shutil.rmtree` in place of
`TemporaryDirectory.cleanup`. That last one only shows on Windows, where
a read-only file blocks the removal.
Slices of the suite that reach the changed modules, this branch against
`main` at a71b488e:
- Linux, in Docker (`python3.12-bookworm-slim`,
`--idle-ceiling-strict`), 20 test files plus the new one: 9 failed, 1718
passed, 88 errors on this branch; 8 failed, 1706 passed, 88 errors on
`main`. The errors and eight of the failures are the same ids on both,
in remote-machine and file-permission tests: the container has no `ps`
and runs as root. The ninth,
`test_a_ping_answers_from_the_machine_and_leaves_one_directory`, timed
out once starting the machine's daemon (`did not answer within 20s`)
while the host was under load; run alone it passed 3 of 3 times on both
sides.
- Windows, `tests/test_subagent_acp.py tests/test_subagent_probe.py
tests/test_subagent_kimi_code.py tests/test_subagent_host_env.py
tests/test_acp_windows.py tests/test_rpc_subagents.py
tests/test_subagent_github_copilot.py`: 57 failed, 635 passed, 4 skipped
on this branch; 61 failed, 619 passed, 3 skipped on `main`. No test
fails only on this branch. Four tests that fail on `main` under Windows
pass with this change,
`test_the_roster_and_the_connect_button_read_one_answer` among them.
For anyone reproducing on Windows: the suite isolates the home by
setting `HOME`, which `Path.home()` ignores there in favour of
`USERPROFILE`, so a run reads and writes the real `%USERPROFILE%\.raven`
and tests can see each other's records. The Windows numbers above were
taken with `USERPROFILE` pointed at an empty folder. That gap predates
this change and is not addressed here.
```text
uv run --frozen --no-sync ruff check <the 10 changed Python files>
uv run --frozen --no-sync ruff format --check <the 10 changed Python files>
uv run --frozen --no-sync ty check raven/utils/scratch.py raven/agent/subagent/probe.py raven/agent/subagent/kimi_code.py raven/acp_client/capabilities.py
uv run --frozen --no-sync lint-imports
```
All passed, 10 import contracts kept.
Not measured: the real `@agentclientprotocol/claude-agent-acp` adapter.
The stand-in above takes its place.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The tests box stays unchecked because the slices above carry failures
that `main` carries too. No user-facing text or docs change.
## Risk
- POSIX behaviour is unchanged apart from order: the directory is
removed on the first try, as before, now after the agent has ended
rather than before.
- On Windows a refused removal adds at most about 0.8 s to a check, and
the directory is then left in the temp folder with a warning that names
it. Before this change every such check left its directory there and
failed.
- A check whose agent leaves a process running outside its job, or a CLI
that leaves a background worker, now reports the agent's answer where it
used to report the removal error.
- Rollback: revert the commit. No configuration, schema or stored state
changes.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#969
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Raven-Code reports Python syntax errors after file edits but misses
unresolved names and equivalent feedback after shell edits. Add advisory
Pyflakes F821/F822/F823 checks to the existing tool result; optional
F401 notices remain off by default. No additional model call or code
execution is involved.
```text
write_file / edit_file
-> inspect final source, compare with a baseline that can be read and analyzed
-> retain syntax warnings; suppress existing name findings
exec
-> require checkpoint visibility for the working directory
-> read the changed files from the host's write record for the command
-> ask visibility in batches of 256, select at most 8, check up to 4 concurrently
-> append ordered diagnostics, preserving exit status and file metadata
```
Existing syntax failures remain visible after unrelated edits and
identical rewrites. A baseline that cannot be read, parsed or analyzed
is marked unknown; overwriting non-UTF-8 source still checks the known
replacement. Source nested too deeply for the parser or checker, and a
changed file that cannot be read, report diagnostics unavailable for
that file rather than passing as clean. Every check reads a file as the
bytes Python runs: text a write or edit stores is checked as its UTF-8
bytes, the content it replaced included, and a file from disk as its
bytes, each decoded as Python decodes source, by its coding declaration
or as UTF-8. Bytes that do not decode are reported as a syntax error at
the line where decoding stops, so a declaration the written text cannot
satisfy is reported however the file was changed. Noqa comments are read
as Ruff reads them, including after other comment directives and never
inside string literals: a file-level `ruff: noqa` / `flake8: noqa`
counts only on a line of its own, and a marker counts only when codes
follow its colon or, with no colon, whitespace, another comment or the
end of the comment follows it. Unlike Ruff, which takes the first
directive in a comment, every directive in it counts. The seeded tool
guide gives the syntax note's own advice. With no checkpoint or no
visibility verdict, exec diagnostics do not inspect changed file
contents; direct file checks remain available.
Pyflakes is imported when the tool face loads, not by whichever check
first needs it: imported lazily, its cold import fell inside that
check's one-second wait, and on a slow Windows runner the one test that
paid it reported diagnostics unavailable for a plain syntax error.
Private workers bound reads and checks to four active jobs per process.
Saturated capacity rejects new work without queuing, and
timeout/cancellation retains each slot until the actual work finishes.
Name checks are capped at 256 KiB of source and the syntax check at 2
MiB, and a check skipped for size says so in one line. Findings are
capped at eight per file, and exec diagnostic text at 6,000 characters
plus omission notices.
Runtime changes stay inside the Raven-Code code-flow plugin, except for
one fix to `CheckpointService.trackable`, the visibility verdict that
exec diagnostics and the host's exec write record both rely on. On
macOS, git precomposes a file name it reads off the disk before matching
an ignore rule, but takes the paths `trackable` sends to `git
check-ignore --stdin` as written. A file stored with a decomposed (NFD)
name under a `.gitignore` rule written precomposed (NFC) is therefore
left out of the checkpoint, yet main vouches for it, so the write
record's diff carries its text, and exec diagnostics would quote its
source lines to the model. Nor is git's precomposition NFC: it composes
only neighbouring characters, by Unicode 3.2's table, and reorders
nothing, so a name whose combining marks are out of canonical order
comes out as neither the name as given nor its NFC. `trackable` now asks
about each name as given, as NFC and in git's macOS spelling, and
withholds it when any spelling is ignored. Other shared
file/shell/snapshot implementations are unchanged.
Raven-Code has no separate dependency manifest, so Pyflakes uses the
existing root dependencies. It is the only added package; uv normalized
existing lockfile markers without changing other package versions.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- **Before:** on main, Raven-Code's file tools report Python syntax
errors only, and its exec reports nothing about the Python files a
command changed. On macOS, main's `CheckpointService.trackable` vouches
for a file stored as `secret_cafe` + U+0301 + `.py` under the rule
`secret_caf` + U+00E9 + `.py`: the user's own git ignores it and the
checkpoint's staged tree leaves it out, yet its text reaches the exec
write record's stored diff.
- **After:** on macOS 26.6.2 / arm64 with Apple Git 2.54.0, the command
below passes 364 tests on Python 3.12.13 and on 3.14.6. The full default
suite on 3.12.13 has 32283 passed, 169 skipped, 20 failed and 3 errors
over 22 test ids: 21 of them also fail on the exact base in the same
environment, and the other, a remote process-tree cancel test that
missed its deadline under the suite's load, passes when run alone. Tests
cover actual worker overlap, retained capacity after
timeout/cancellation, host-tool isolation, hidden-file quotas,
visibility batching through the host's write-record wiring, baseline
handling, parser-limit failures, the size bounds and their skip notes,
undecodable bytes placed where decoding stops, coding declarations in
written and edited text, the baseline read staying on a worker, the
checker loaded with its module, the file each unavailable note names,
comment directives and their marker boundary, the tool guide's agreement
with the syntax note, portable commands in paths with spaces/non-ASCII
characters, and the checkpoint's verdict on decomposed names and on
names git spells as neither given nor NFC, held against its own staged
tree. Removing any of the three spellings from the query fails the cases
that pin it, as does removing the marker boundary, the parser-limit
report, the unknown-baseline handling, the syntax check past the
name-check bound and the decoding report, checking written text as its
stored bytes, the worker around the baseline read, loading the checker
with its module, or the file name in an unavailable note; restoring the
guide's earlier advice fails its agreement test. git's macOS spelling is
what libiconv's UTF-8-MAC conversion returns, which git precomposes
with: composing neighbours by Unicode 3.2's table reproduced it for all
281,928 names built from every decomposable character's decomposition
(reordered, partly composed, or with a mark added), and across 784,220
further mixed names and pairs no name was spelled outside the three
asked; the same held under Python 3.13 and 3.14. The decomposed-name
check asserts the macOS outcome only where git precomposes names, so it
also passes with `core.precomposeunicode = false` set through
`GIT_CONFIG_GLOBAL`. Across 102 noqa comment variants the reported lines
match Ruff 0.15.12, except the three that hold several directives in one
comment. Through the real `AgentLoop`, code-flow tool face,
`CodeExecutor` and checkpoint, with the working directory under `/tmp`,
under `$TMPDIR` and in a path with spaces and CJK characters, exec
diagnostics report created, modified and decomposed-name files, follow
`working_dir`, report an undecodable file at the line where decoding
stops, a syntax error past 256 KiB and a skip past 2 MiB, and withhold
`.gitignore`d files, including decomposed names and names git spells as
neither given nor NFC; across repeated runs on both interpreters, a file
near the 256 KiB cap is checked in 52-135 ms (117-128 ms against a
baseline), the syntax of a file near 2 MiB in 318-371 ms, and 600
ignored files plus one visible file take 73-90 ms with the event loop
held at most 20 ms. At this head CI passes the unit suite on
Linux/Python 3.12 (32619 tests over four shards), and its two Windows
steps pass the diagnostic files on native Windows/Python 3.13: 122
file/worker tests, and 27 exec diagnostic tests with 17 pre-existing
executor tests deselected; the symlink fixture skips only where the host
cannot create links.
```sh
env -u SERPER_API_KEY -u RAVEN_MIRRORED_SERPER_API_KEY uv run --no-sync pytest tests/test_agents_code_diagnostic_workers.py tests/test_agents_code_tools_plugin.py tests/test_agents_code_flow_exec.py tests/test_agents_code_flow_plugin.py tests/test_agents_code_flow_read_state.py tests/test_agents_code_launcher.py tests/test_workdir_snapshot.py tests/test_shell_command_writes.py tests/test_runtime_checkpoint.py tests/test_trajectory_upload.py::test_blocked_upload_hits_the_deadline -o addopts= -q --tb=short --maxfail=3
uv run --no-sync ruff check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py tests/test_runtime_checkpoint.py tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py tests/test_agents_code_diagnostic_workers.py
uv run --no-sync ty check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py
uv run --no-sync lint-imports
uv run --no-sync ruff format --check raven/agent/loop/checkpoint.py agents/raven-code/plugins/code-flow/code_flow/tools agents/raven-code/plugins/code-flow/code_flow/config.py tests/test_runtime_checkpoint.py tests/test_agents_code_flow_exec.py tests/test_agents_code_tools_plugin.py
```
Native Windows CI commands:
```sh
uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_diagnostic_workers.py tests/test_agents_code_tools_plugin.py -q -n 0 --tb=short
uv run --frozen --python 3.13 --no-sync pytest tests/test_agents_code_flow_exec.py -k test_exec_ -q -n 0 --tb=short
```
Ruff, format and type checks passed; all 10 import contracts kept; the
commit-message, large-file and source-language checks pass over the
branch. The launcher tests unset inherited search API keys to keep the
expected tool list deterministic.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Scope: Raven-Code's enabled code-flow tool face; installing Pyflakes
does not activate checks in other agents. The change is reversible and
never fixes/removes code or rolls back edits. Static diagnostics can
need judgment for dynamic names, target Python versions, and project
lint configuration; only explicit noqa directives are honored. Passing
diagnostics do not replace tests.
The `trackable` fix reaches every exec write record, not only
Raven-Code: a file whose name, as given, as NFC or in git's macOS
spelling, matches an ignore rule keeps its counts and loses its diff and
removal body. Where git matches another of those spellings, as off macOS
for a decomposed name under a precomposed rule, the checkpoint stores
the file but it is still withheld; its counts remain.
Exec diagnostics now require an active checkpoint. Noninteractive runs
using the default interactive checkpoint policy must explicitly enable
checkpoints to receive this feedback. Visibility is checked in batches
of up to 256 files and stops once eight visible files are found; each
batch holds the event loop while the host resolves its paths, about 130
ms for a full batch on native Windows. Each file-check wait is one
second, and post-command diagnostics have a three-second wait budget;
past it, or when they fail as a whole, they are dropped and the
command's result is kept. These are caller budgets, not hard I/O
deadlines: running OS reads and inherited synchronous host callbacks
cannot be forcibly interrupted. Private worker capacity remains bounded.
Between 256 KiB and 2 MiB only syntax is checked: near 2 MiB that took
0.3-0.4 s and about 190 MiB here, up to four checks run at once, and on
slower hardware such a check can outlast the one-second wait and report
diagnostics unavailable. Python's GIL means concurrency does not promise
a CPU speedup.
Windows CI exercises the diagnostics layer with the real native
DirectExecutor. The existing CodeExecutor environment probe uses POSIX
quoting and already fails on Windows at the base; this PR neither
changes that probe nor claims end-to-end compatibility for it. Symlink
setup is skipped only if the host cannot create the fixture.
Disable `pythonLint` for syntax-only feedback, `execPythonDiagnostics`
for no post-command checks, or `pythonSyntaxNote` for no diagnostics,
under `plugins.config["code-flow"].tools`. The PR can also be reverted
as a unit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
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
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
Native Windows installs fail from the shell Windows ships with. Both
commands the README gives for Windows break under Windows PowerShell
5.1:
- `irm https://raven.evermind.ai/install.ps1 | iex` stops with `(308)
Permanent Redirect`. PowerShell 5.1 follows 301, 302 and 307 redirects
but not 308, which is what that URL answers with. This is the error #148
reported; the README already offered the direct URL for it.
- The direct URL downloads the script, which then stops at "Could not
resolve the latest Raven release wheel from GitHub".
`Resolve-RavenLatestVersion` requests the release page without following
the redirect and reads the Location header off the exception that
raises. Only PowerShell 7 attaches the response to that exception.
PowerShell 5.1 returns the unfollowed redirect as the response and
reports `MaximumRedirectExceeded` as an error with no response, so the
lookup always came back empty. This came in with #299 and has been on
main since.
Changes:
- `install.ps1`: the release-page request uses `-ErrorAction Ignore`
instead of `-ErrorAction Stop`, so PowerShell 5.1 reads Location from
the returned response. PowerShell 7 still raises regardless of
`-ErrorAction` and goes through the existing catch. The Location is
still matched against the same stable-tag pattern.
- CI: the installer job ran `install.ps1` under `pwsh` only, which is
how this shipped. It now also runs the piped install under Windows
PowerShell 5.1 (`shell: powershell`), into its own tool, bin and home
directories, sharing the uv cache.
- Docs: README, README.zh-CN, the docs-site quick start (en, zh) and the
release notes template now say that Windows PowerShell 5.1 stops on the
short URL with `(308) Permanent Redirect` and to switch to the direct
URL when that appears. The short URL's redirect itself is unchanged.
- Tests: tripwires for the lookup (`-ErrorAction Ignore`, catch kept)
and for the CI gate (both shells, and separate tool, bin and home
directories, since the version check runs the `raven.exe` in the bin
directory).
Second topic, Windows test hygiene: three tests failed when the suite
ran on a Chinese-locale Windows checkout. CI runs the unit tests on
Linux only, so it never saw them.
- `test_no_workflow_step_enters_the_removed_page_directory` read
workflows in the locale encoding (GBK there) and stopped on the UTF-8 in
`release.yml`. It now reads UTF-8.
- The font and LibreOffice harness tests run `install.sh` code under
`sh`, which on Windows is Git Bash: its curl sits outside `/usr/bin` and
paths mix separators, so two failed and others passed for the wrong
reason (the digest-mismatch test passed because curl was missing). The
ten harness tests now carry the POSIX-only skip the other three
sh-driven tests already had, shared as one `POSIX_SH_ONLY` marker. Linux
runs are unchanged.
#861 merged first, and this branch is rebased onto it. The one conflict
was in `tests/test_install_script.py`. The sh-driven tests #861 added,
its two Node harness tests and
`test_a_download_that_cannot_be_hashed_is_not_installed`, now carry
`@POSIX_SH_ONLY` like their neighbours, so the marker stays the one
spelling of that skip.
Third topic, test infrastructure: Python's locale-dependent text I/O
uses the system code page when no `encoding=` is passed. On a GBK-locale
Windows checkout, any test that reads or writes a file containing
non-ASCII bytes will fail or silently corrupt data. The class of bug was
found above; there are ~790 `read_text()` call sites without `encoding`
in `tests/`. Measured on Linux under a zh_CN.GBK locale, main without
UTF-8 mode is not one test short: 87 tests fail only there, across 25
files, and `tests/test_rpc_schema_match.py` (418 tests) does not
collect, mostly on `UnicodeDecodeError` from reading UTF-8 files.
- Makefile: `export PYTHONUTF8 := 1`, so every recipe runs in UTF-8
mode, `check-core-wheel` (part of `make ci`) included.
- `tests/conftest.py` raises at import time on any interpreter whose
default text encoding is not the UTF-8 codec, telling the caller to set
`PYTHONUTF8=1` or use `-X utf8`. It compares codecs rather than names,
so Windows with the system-wide UTF-8 option, which reports `cp65001`,
passes. `uv run pytest`, which AGENTS.md documents and which does not
read the Makefile, now stops here on a GBK checkout, as does an IDE
runner that does not set the variable. CI's `--noconftest` self-upgrade
job (its tests all name `encoding` explicitly) is unaffected.
`tests/test_conftest_utf8_guard.py` pins the codec comparison and drives
the refusal in an ASCII-locale child.
- CI sets `PYTHONUTF8` in no job. The jobs that load `tests/conftest.py`
run on ubuntu-latest, where the locale is UTF-8 already, and the `unit`
job gets the variable from the Makefile through `make coverage-shard`.
The Windows self-upgrade job runs its one file with `--noconftest`, and
that file names its encodings. The installer job runs no tests at all:
its steps are raven installing itself and answering `--version`, so the
variable there would only change how raven runs, and that gate exists to
run it the way users do.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on Windows 11 (zh-CN) with Windows PowerShell 5.1.26100 and
PowerShell 7.6.6, before the rebase onto #861 and the second review
round. Every install below was isolated: `UV_TOOL_DIR`,
`UV_TOOL_BIN_DIR` and `RAVEN_HOME` in a temp directory,
`RAVEN_MINIMAL=1`, `RAVEN_NO_LAUNCH=1`.
- Before the fix, under 5.1: `irm https://raven.evermind.ai/install.ps1`
fails with `(308) Permanent Redirect`; `irm
https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1
| iex` stops at `Could not resolve the latest Raven release wheel from
GitHub`.
- `Invoke-WebRequest
https://github.com/EverMind-AI/Raven/releases/latest -MaximumRedirection
0 -UseBasicParsing -ErrorAction Stop`: 5.1 throws
`InvalidOperationException` (`MaximumRedirectExceeded`) with no
`Response`; 7.6.6 throws `HttpResponseException` whose
`Response.Headers.Location` is the tag URL. With `-ErrorAction Ignore`,
5.1 returns the 302 with Location set, and 7.6.6 still throws into the
catch.
- Redirects under 5.1, via httpbin `redirect-to`: 301, 302 and 307 are
followed; 308 is not.
- After the fix, `Get-Content install.ps1 -Raw | Invoke-Expression`
under 5.1 and under 7.6.6, with `uv tool update-shell` disabled in a
temp copy of the script to leave the user PATH alone: both resolved
v0.2.4, installed raven with everos-memory, design-engine and
ppt-engine, and `raven.exe --version` printed `Raven v0.2.4`.
- `uv run pytest tests/test_install_script.py
tests/test_release_plugin_list.py
tests/test_constraints_export_contract.py` plus the six installer tests
in `tests/test_cli_onboard_commands.py`, on Windows: 48 passed, 13
skipped (before: 55 passed, 3 skipped, 3 failed). The two new tripwires
fail against the previous `install.ps1` and `ci.yml`. With the UTF-8
gate added, a bare `uv run pytest --co -q tests/test_install_script.py`
on the GBK checkout raises RuntimeError naming `PYTHONUTF8=1`, while the
same invocations with the variable set pass (45 passed, 13 skipped).
- `uv run ruff check` and `uv run ruff format --check` on both test
files pass; `ty` does not cover `tests/`, the only Python this changes.
`PYTHONPATH=. uv run python scripts/check_source_language.py
origin/main` exits 0.
Run on Linux (Ubuntu 22.04, Python 3.12.13) at this head. A zh_CN.GBK
locale compiled into a private `LOCPATH` gives a non-UTF-8 interpreter
(`locale.getpreferredencoding(False)` is `GBK`, UTF-8 mode off).
- Full suite, `uv run --frozen --python 3.12 --all-extras pytest -q`: 7
failed, 27567 passed, 119 skipped. On main the same command gives 7
failed, 27556 passed, 119 skipped with the identical 7 failing IDs, this
machine's local baseline (five proxy tests, a root-only permission test
and an npm found on PATH), so 0 introduced; the 11 extra passes are this
PR's new tests.
- Main under GBK without UTF-8 mode: 86 failed, 27059 passed, 119
skipped, 11 errors. 87 IDs fail only there, and
`tests/test_rpc_schema_match.py` does not collect. One of the 87, a
non-ASCII file name, is specific to Linux, where GBK also becomes the
filesystem encoding.
- This head under GBK: a bare `uv run pytest --co -q
tests/test_install_script.py` stops at the conftest RuntimeError naming
`PYTHONUTF8=1`. `make test-python`, which exports it: 7 failed, 27567
passed, 119 skipped, the same 7 IDs as under UTF-8. `make
check-core-wheel`: 1 passed, where with the per-target exports it exited
2 at the guard.
- The harness tests marked `@POSIX_SH_ONLY` run on Linux in the full
suite above.
- Mutations: with the old name tuple back in the guard's predicate, only
the `cp65001` case of `tests/test_conftest_utf8_guard.py` fails; with
the guard deleted, its end-to-end refusal test fails. Giving the 5.1
step pwsh's `UV_TOOL_BIN_DIR`, or its `RAVEN_HOME`, now fails the CI
gate test naming the shared variable, where before it passed.
- `make lint-python` passes, and the commit-message, source-language and
large-file gates exit 0 over `origin/main..HEAD`.
- [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 one-line Windows install works again from Windows
PowerShell 5.1 through the direct URL. The short URL still answers with
a 308 there, and the docs now name that error. `install.ps1` is served
from main, so the fix reaches users on merge, and reverting the squash
commit rolls it back the same way. The resolved Location is still
matched against the same stable-tag pattern before anything is
downloaded. The installer CI job gains one Windows install, which reuses
the uv cache.
Developer-visible: on a Windows checkout whose code page is not UTF-8, a
pytest run that loads `tests/conftest.py` without UTF-8 mode stops at
import with a message naming `PYTHONUTF8=1`; the `make` targets set it,
and Linux and macOS runs are unaffected. On Windows the sh-driven
harness tests report as skipped: the ten this PR marks and
`test_a_download_that_cannot_be_hashed_is_not_installed`, beside the
five that already skipped there.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#148
---------
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
The release notes template that CI prefills into every release draft,
the structure sketch of the same sections in RELEASING.md, and the quick
start's upgrade recipe still described the 0.1.13 finish line. Since
then both installers end by opening Raven in the browser, where
first-run setup now happens; `raven upgrade` installs the plugin wheels
too; rerunning the installer cannot pick up a pre-release, since it
resolves `releases/latest`; and a release ships three plugin wheels plus
`raven-constraints.txt` and `raven-plugins.txt` beside the wheel and
sdist. Both files now say so.
The Upgrade section of the template and the "Update a one-line install"
recipe in docs-site/docs/quick-start.md and quick-start.zh.md are
written to match the upgrade code: stop the page, run `raven upgrade`,
and start Raven again only after the upgrade has finished. On Linux and
macOS the command execs the helper in the foreground and returns when
the install is done; on native Windows it spawns the helper and returns
at once, and a `raven web` started before the completion message runs
into the install marker and exits 75. `raven upgrade` installs the
latest stable release unless the install has joined the beta channel, in
which case it installs that channel's pre-release.
Each claim was checked against the v0.2.0 tree: the launch sections of
install.sh and install.ps1, the `web` command and
`_refuse_incomplete_install` in raven/cli/serve_commands.py,
`_handoff_upgrade` and `fetch_latest_for_channel` in
raven/updates/upgrade.py, the first-run gate in ui-web/src/app/boot.ts,
and the asset list in .github/workflows/release.yml.
The 0.2.0 draft is edited in place; this change only reaches the drafts
CI creates from now on. The `__VERSION__` and `__TAG__` placeholders and
the two TODO markers the release job and the notes step rely on are
unchanged.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `git diff --stat origin/main..HEAD`:
.github/release-notes-template.md, RELEASING.md,
docs-site/docs/quick-start.md, docs-site/docs/quick-start.zh.md
- `npx commitlint --from origin/main --to HEAD --config
commitlint.config.cjs`: exit 0
- `PYTHONPATH=. python scripts/check_commit_messages.py
origin/main..HEAD`: exit 0
- `PYTHONPATH=. python scripts/check_source_language.py
origin/main..HEAD`: exit 0
- Non-ASCII scan of the template and RELEASING.md: nothing found (the zh
quick start page is Chinese by design)
- No tests run: markdown only; the one code consumer is the sed in
release.yml, whose placeholders are unchanged. The docs build runs in
CI.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Documentation only. Rollback is reverting the commits; the next tagged
release then prefills the old text again.
- [ ] 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
Starting a gateway started LibreOffice. Fifteen seconds after every boot
the
template picker's covers were drawn on the host: ten conversions, three
at a
time, for a gallery most readers never open. On macOS those are three
icons
in the Dock on a start that was asked to do nothing of the kind.
The covers only depend on the templates the engine ships, so the release
renders them once instead of every installation rendering them again.
`scripts/bake_deck_template_covers.py` walks the template directory and
every
phrasebook beside it, writes one JPEG per template per language into
`raven_ppt/assets/templates/covers/`, and the ppt-engine wheel carries
that
directory. `deck_templates.shipped_cover` reads it before anything is
started, `cached_cover` and `cover_for` answer from it, and the warm-up
introduced in #624 then finds nothing missing and starts nothing. Twenty
covers, 398 KB.
The warm-up itself is unchanged, and so is the rendering path:
`shipped_cover`
answers None rather than raising, so a template dropped into the
directory by
hand, a language added after the build, and an install from source all
still
draw their own. Both the bake and the release gate read the directory
rather
than a list, so a new template or a new language is a new file and not a
code
change.
Two packaging lines were measured rather than assumed. Hatch reads the
ignore
file at the built project's root, and the rule lives at the repository
root,
so the `include` list alone ships the covers today; adding a
`.gitignore`
under `plugins-dist/ppt-engine` drops them to zero, which is what
`artifacts`
is there for. Both states were built and inspected.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run --frozen --python 3.12 --extra dev pytest
tests/test_rpc_deck_templates.py
tests/test_rpc_console.py tests/test_cli_serve_commands.py
tests/test_cli_gateway_commands.py
tests/test_ppt_engine_default_templates.py
tests/test_ppt_engine_templates.py -q`
-> 417 passed.
- Reverse check: with the two `shipped_cover` short circuits removed,
the two
new cases fail on the symptom they name (`a cover the wheel carries must
not
be drawn again`) -> 2 failed, 28 passed.
- End to end on one build, the only variable being whether the covers
are in
the package. Covers hidden: `drawing 10 missing cover(s)` and three
`soffice`
processes. Covers shipped: no log line, nothing queued, no `soffice`.
Run
against an empty RAVEN_HOME, in both `zh` and `en`.
- `scripts/bake_deck_template_covers.py` against the real package -> 20
covers,
398 KB; the `en` set carries English copy, checked by opening one.
- `uv build --wheel plugins-dist/ppt-engine` four times across the
include and
artifacts combinations -> 20 covers in the wheel, 0 without `artifacts`
when
a project-local `.gitignore` exists.
- `ruff check` and `ruff format --check` on the changed Python -> clean.
`scripts/check_source_language.py` and `scripts/check_large_files.py`
over
`github/main..HEAD` -> exit 0. `commitlint` on the commit -> exit 0.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- Nothing a reader sees changes: the picker shows the same pictures,
drawn by
the build rather than by their machine.
- The release job gains an apt install of `libreoffice-impress` and one
bake
step. If the bake fails the release fails there, rather than publishing
a
wheel whose covers are silently absent; the ppt-engine gate asserts one
cover
per template per language in the built wheel.
- An install from source has no baked covers and behaves exactly as it
does
today, rendering them once at boot.
- Rollback: revert the squash commit. Nothing is stored, cached or
migrated,
and a host with the old wheel keeps drawing its own covers.
- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
Stacked on #475 (`refactor/ui_web_architecture`): the conventions that
keep the rebuilt `ui-web/` from drifting, written down in
`ui-web/CONTRIBUTING.md` and enforced by gates. Twenty-two commits, each
landed with every gate green. Three of them change what a DOM diff sees
and are named below; the rest are DOM-invisible.
- **One store shape.** `state/store.ts` exports `makeStore<T>()` with
`get / set / subscribe / _resetForTests`; 33 hand-rolled stores
migrated, `getState` / `put` / `commit` / `wipe` retired; the
`store-shape` gate pins the eight modules that keep a different shape,
each with its reason.
- **One source seam.** `ds<K extends keyof Sources>(domain: K)` is
key-typed, so a renamed or missing domain is a compile error; every
`gateway()` call lives in a domain's `source.ts` (`rpc-names` enforces
placement); `app/install.ts` is the only module that assigns
`sources.*`; skills has its own `source.ts` and the shared `ext.list`
read is `features/installed/source.ts`.
- **No island bag.** `features/registry.ts`'s `islands` object is gone;
page-wide code imports a domain's store directly, and the three
callbacks `state/page.ts` needed are registered from `app/install.ts`.
That one edge was 18% of the import graph's closure weight and held the
tree's only module-evaluation-order hazard. The `import-direction` gate
now pins the layering (`lib <- components <- chrome <- app`, `lib <- rpc
<- state <- chrome, features, app`, `features -/-> features` except
`source.ts`/`types.ts`) with today's upward and cross-domain edges as a
down-or-gone list. Two of the four pinned import cycles are dissolved
the way the gate prescribes (a state module declares a slot, the domain
fills it): `state/page.ts` no longer reads `state/caps.ts`,
`state/navfly.ts` no longer imports the rail store; 17 files sit in a
cycle now, in two components, down from 21 in four.
- **Language is resolved at boot** (localStorage, then config, then
`<html lang>`), so `t(key)` is the only way to take a string; every
island root subscribes to the language store and the hand-kept repaint
list shrinks to the two imperative steps. `T()` and `lang.text()` are
retired, and so are the 61 inert `data-i18n*` attributes the old
document walk used to read.
- **Each domain declares itself once.** `features/<domain>/manifest.ts`
(aggregated in `features/manifests.ts`) and `state/pages.ts` drive the
page sections, the Escape order, the body order, the rail buttons, the
mounts and the region goldens; `domain-shape` and `domain-registration`
gates hold the two tables together.
- **Homes and names.** The desk is its own domain (`features/desk/`);
`resume` lives with the session runtime; the composer's three sheets
live in the composer; the session naming protocol is
`state/session/naming.ts`; `features/xa/` is `features/extAgents/` with
matching ids and exports; wiring modules are all `wire.ts`; page roots
are all `<Domain>App`; `popover`, `pane`, `escapeOrder`, `installEntry`
/ `installSkill`, `Frame` replace the competing words; `useInTask` (not
a hook) is `startTaskWith`; the `file-names` gate pins the case rules.
- **Hooks and types.** `react-hooks/rules-of-hooks` is an error (the
seven warnings were a misnamed verb and one hook after an early return,
now `PlainCallRow`); `tsconfig` adds `noUnusedParameters` and the eight
sites it named are gone; `npm run lint` is down to seven warnings, all
`exhaustive-deps` effects that deliberately run once plus one guarded
expression.
- **Gates and tooling.** The stylesheet hash pin is retired (the eleven
declaration-level CSS gates remain), the six CSS gates share one parser,
`check-css` and `check-class-namespace` run under `npm test`; the
class-namespace gate covers every domain with a per-domain prefix, reads
class literals inside `className={...}` expressions as well as
attributes, and pins today's debt as three down-or-gone lists (86
shared, 342 unprefixed, 91 unprefixed in expressions); fixture
responders return `Wire<ResultOf<M>>` instead of `as`-asserted literals
(which exposed five fixture answers that did not match the contract),
and the turn script fixture is a typed union with no cast left; the
offline library's coverage of every called method is gated with a named
exemption list; `boot-order` is three gates by concern; eslint with
import sorting and unused checks (the tui's config) runs as `npm run
lint` after a one-time 206-file sweep, and `make lint-ui` and the CI ui
job run it.
- **Docs and comments.** `ui-web/CONTRIBUTING.md` (layout, domain
skeleton, store shape, rendering, source and fixtures, naming, CSS,
tests and gates, tooling, the adding-a-domain checklist, and a table of
every pinned exception), new `ui-web/CONTEXT.md` entries, a README whose
layout table matches the tree, and `tests/test_living_docs.py` scanning
all three. Every code comment that explained a decision by what the
deleted script layers used to do now names the live owner or is gone.
What a reader can see change:
- The offline `?stub=1` page and the first live frame before the config
answers now render in one resolved language instead of Chinese markup
with English dynamic text; two tooltip strings in the boot golden moved
with it, and the golden now records tooltip attributes by name rather
than by sentence.
- Domain ids follow their directory: `#extAgentsPage`,
`#connectionsPage`, `#memoryPage`, `#playbooksPage` and their bodies and
rail buttons. `page.css` referenced none of them; the knowledge page
keeps `#kbPage` because the stylesheet pins it.
- The 61 `data-i18n`, `-ph`, `-title`, `-aria` and `-tip` attributes are
gone from the chrome markup. No selector, dataset read, stylesheet rule
or gate named one; the 14 goldens that carried them change by exactly
those attributes and nothing else (each new golden diffs clean against
the old one with the attribute text stripped).
Also restored: the cron page's run-history refetch on a language change,
which the earlier `redrawAll` deletion had dropped.
Outside `ui-web/`, three files: the `Makefile`'s `lint-ui` target and
the CI ui job gain `npm run lint`, and `tests/test_living_docs.py` scans
the three `ui-web/` documents.
Not in this PR, each recorded in `CONTRIBUTING.md`'s exceptions table:
i18n namespaces still use their old abbreviations because the catalogue
(`i18n/messages.json`) is shared with the TUI and lives outside
`ui-web/`; the two remaining import cycles (the six-file
composer/transcript/workspace knot and the eleven-file session knot);
the class names still defined in `page.css` rather than per domain; the
three places `rpc-schema/openrpc.json` disagrees with its own
descriptions, which is the backend's to settle.
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
From the repo root, on the branch head:
- `cd ui-web && npm run type-check && npm run lint` -> clean, 7 warnings
(from 14 on the base's first lint run), 0 errors
- `cd ui-web && HOME=$(mktemp -d) npx vitest run` -> 162 files, 2534
tests passed, 0 skipped (from 152 / 2494 on the base; one test whose
subject was deleted went with it)
- `make build-ui` -> `boot-snapshot: OK (284 nodes match golden)` and
`boot-snapshot: OK (285 nodes match golden)`
- `make lint-ui` -> `gen:check`, `npm run lint`, `type-check` all clean
- `cd ui-web && node scripts/check-page.mjs && node
scripts/check-css.mjs && node scripts/check-class-namespace.mjs && npm
run gen:check` -> all OK
- `uv run --frozen pytest tests/test_ui_agent_marks.py
tests/test_ui_provider_marks.py tests/test_ui_css_token_gate.py
tests/test_living_docs.py -q` -> 55 passed
- `make check-source-language` over `origin/main..HEAD` -> exit 0
- `uv run --frozen pre-commit run --from-ref
refactor/ui_web_architecture --to-ref HEAD` -> all passed
- `git diff --stat refactor/ui_web_architecture..HEAD -- . ':!ui-web'`
-> exactly `Makefile`, `.github/workflows/ci.yml`,
`tests/test_living_docs.py`
- Every new gate was mutation-checked (one-line breakage red, restored
green); per-step happy-dom dumps of the body order, listener sequence,
boot walk and language flips are byte-identical across the DOM-invisible
steps and differ only as described above in the other three.
- Not done: a real-browser pass.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- Security: none; no protocol or auth path changes.
- Backward compatibility: build entry points, script paths CI calls, URL
flags and DOM ids the stylesheet references are unchanged; renamed ids
and the dropped `data-i18n*` attributes appear only in goldens.
- Rollback: revert the squash merge into `refactor/ui_web_architecture`.
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
The page is rendered by src/App.tsx since the previous commit, so the
concatenated-script era has nothing left to carry. This removes src/legacy
(eighteen parts and their install order), the RavenShell bridge and its
shell/bridge.ts twin, and the tooling that only existed while those layers
did: legacy-part, legacy-index, the legacy shape and undefined-name gates,
count-shared-globals, and build.py's part manifests.
Every symbol the legacy parts still owned moves to a real home: the
conversation and rail row state into state/session, the skills and plugins
renderer halves into their features, the composer palette and the settings
chrome into their features, the DOM helpers into shell/dom.ts, the boot step
table into state/boot.ts. Callers import those modules directly; the tests
that faked the bridge's verbs now inject through the modules' own seams
(setTranslator on i18n/t.ts and friends), with every assertion unchanged.
The dead theme module goes with its only test. CI stops calling the retired
count-shared-globals gate, CONTEXT-MAP.md registers ui-web/CONTEXT.md, and
CONTEXT.md and README.md describe the tree as it now is.
Measured: both boot goldens (284 and 285 nodes), the 19 region goldens and
the 31 island snapshots are unchanged; the body order, the boot walk and the
language-flip dumps are byte-identical to the previous commit; the two
inline script blocks now precede the React-rendered regions in the body
(script elements are not rendered and no selector or code reads body child
positions, so this is invisible).
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
A pull request whose base is not the default branch carries, in its
`BASE..HEAD` range, every commit the default branch has gained since the
two
diverged. Both commit linters read that range, so they re-read history
that
already passed this gate when it landed and that nobody can rewrite now.
#529 is the case that surfaced it: merging `main` into
`refactor/ui_web_architecture` puts 38 `main` commits in range, one of
which
(`b01534d0`, #471) carries a `Co-authored-by` trailer with a non-ASCII
name.
The gate reports that PR red for a message it did not write. The same
will
happen to every future catch-up merge.
`scripts/check_commit_messages.py` now takes several revision arguments
and
passes them to `git log`, so a caret exclusion works. Commitlint has no
equivalent flag, so the workflow iterates the same revision list and
lints one
message at a time. On a pull request the workflow excludes the
repository's
default branch; a push to the default branch is unchanged and still
lints what
it pushed.
This does not touch the offending commit on `main` and does not relax a
rule:
a commit that a PR actually introduces is linted exactly as before.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
`uv run pytest tests/test_check_commit_messages.py
tests/test_commit_lint.py -q`
-- 15 passed. Three of those cases are new and cover a repo where the
default
branch carries a rejected message and the feature branch merges it in:
the
range fails without an exclusion, passes with one, and still fails when
the
bad commit is the branch's own.
Mutation check on the new cases: replacing `_commit_messages(args)` with
`_commit_messages(args[:1])`, which is the behaviour before this change,
turns
`test_excluding_the_default_branch_skips_the_history_it_carries` red and
leaves
the other three green. The pin fails when the fix is removed.
Against the real history behind #529, with the checker run directly:
- `check_commit_messages.py "bc74bf73..a0666244c"` -- exit 1, naming
`b01534d02` exactly as CI does.
- the same range plus `^github/main` -- exit 0.
The workflow's new loop was run as written against both ranges: 0
commits to
lint on the catch-up range, and a planted `Update stuff.` commit on a
feature
branch still sets the failure flag.
`make lint-python` -- clean. `scripts/check_source_language.py` over the
branch
-- exit 0; the test's non-ASCII message is built from an escape, so the
file
itself stays ASCII.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Commitlint now starts once per commit instead of once per range, so a PR
with
many commits spends a second or so more in this job. The exclusion only
ever
removes commits that are already on the default branch, so nothing a PR
introduces escapes either linter.
Rollback is reverting this PR; the previous behaviour is one range
argument and
one commitlint invocation.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A. Unblocks the `commit messages` check on #529.
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Stands up a bilingual MkDocs site under `docs-site/`, published to
GitHub Pages
by a workflow that builds on every pull request and deploys only from
`main`.
Fourteen topics ship in English and Chinese: the quick start,
self-hosting,
Docker, the WebUI, the sandbox manual, the runtime architecture, the
command
reference, the repository layout, the developer workflow, the
proactivity design
and reference pair, the self-evolution map and the tracing API.
This pull request is additive. Both READMEs keep their prose and gain
one link
to the site in the header row; trimming them is deliberately a second
pull
request, so the site can be confirmed live before anything depends on
it.
Key decisions:
- **`docs-site/`, not `docs/`.** `docs/README.md` defines `docs/` as
design
notes and dated records, and `docs/plans/` is an archive explicitly not
held
to today's layout. A user manual has the opposite lifecycle.
- **Full bilingual parity**, via the `mkdocs-static-i18n` suffix
structure
(`page.md` beside `page.zh.md`). Parity decays immediately without a
guard, so
a test fails when a page has no twin.
- **Anchors are pinned on the Chinese side.** A CJK heading slugifies to
nothing, so Markdown numbers it `_1`, `_2`, and inserting one heading
renumbers every anchor below it, silently breaking links readers already
hold.
Each Chinese heading therefore states the anchor its English twin gets
for
free: 133 heading anchors, identical across the two languages, none
positional.
- **A left rail, not a top bar.** The header carries the brand, the
search box
and the navigation tree down the left; the table of contents on the
right is
one continuous polyline clipped to the headings currently on screen.
- **No template overrides.** Material customises through
`theme.custom_dir` with
Jinja partials, those partials are `.html`, and
`scripts/check_large_files.py`
holds `.html` in `BLOCKED_ASSET_EXTENSIONS`. The skin is therefore one
stylesheet remapping Material's own custom properties, plus one script
for the
table-of-contents rail. The brand mark is a `data:` URI for the same
reason.
- **An owner-signed `docs-site/` exemption zone** in AGENTS.md section
1.3. The
i18n config carries the Chinese navigation labels, and `mkdocs.yml` is
not
`*.md`, so the blanket suffix exemption does not reach it. A contract
test
holds the AGENTS.md list and `EXEMPT_PREFIXES` equal, so both moved
together.
- **The site never links out to a file it does not host.** Documents
that stay
in the repository are named as plain paths rather than linked, and a
guard
fails a page that links to an external webpage or a repository-relative
path.
Two defects found and closed here rather than after publication. The
Chinese
site rendered an English sidebar: navigation labels live in
`mkdocs.yml`, not in
any page, so comparing the two languages' Markdown finds nothing and
only the
rendered output shows it. And a control could be present, sized,
animated and
answer `querySelector` while being unclickable, because a popup Material
sized
for a top bar landed outside the viewport once the header became a rail.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All commands run at the pushed head, rebased onto `origin/main`.
```
make check-large-files exit 0
make check-source-language exit 0
make docs-build exit 0, 0 errors
docs-site/site/index.html and docs-site/site/zh/index.html both present
mkdocs_static_i18n: Translated 17 navigation elements to zh
uv run pytest tests/test_docs_site.py tests/test_source_language_check.py \
tests/test_readme_scope_canon.py tests/test_docker_runtime.py \
tests/test_living_docs.py 44 passed
uv run pytest tests/integration/test_docs_site_controls_e2e.py 13 passed
pre-commit run --files <changed files> all hooks pass
git diff --check clean
```
Anchor parity was measured on the built HTML rather than assumed: 14
page pairs,
133 heading anchors compared at h2 through h6, every one identical
between the
two languages and none positional.
The controls are hit-tested rather than queried.
`document.elementFromPoint` at
the exact point a reader clicks must return the control itself, which is
the
only check that catches an off-viewport popup; the language switcher,
the search
panel, the repository link and the table-of-contents rail each pass it.
The brand lockup is measured, not eyeballed. A failing test was written
first
and reported the wordmark sitting 4.00px below the mark's centre line;
it is
0.00px after the fix, and a 4x screenshot puts the residual optical
offset at
0.25px.
Every guard this branch adds was confirmed to fail first. The
brand-class guard
was mutated from both sides in turn: renaming `.em-eyebrow` in the
stylesheet
turned it red, renaming `class="em-standfirst"` in `index.md` turned it
red, and
it is green again with both restored. The anchor guard was shown to
catch both
failure modes, a missing anchor and a wrong one.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
No behaviour change to any shipped code path. Nothing imports
`docs-site/`, the
new Makefile targets are additive, and the only change outside
`docs-site/` and
its tests is one link added to each README's header row.
Rollback is deleting the branch: the site does not exist until Pages is
enabled
with `Source: GitHub Actions`, and every other change is inert without
it.
Disclosed residue, checked and deliberately not changed:
- The README header now links to `https://evermind-ai.github.io/Raven/`,
which
404s until Pages is enabled. It is the same URL the Documentation
section
already carries.
- The `deploy` job is skipped on pull requests by design, so a green
check here
does not prove deployment works. The first real evidence is the `deploy`
job's
own conclusion on the `main` run after merge.
- GitHub Pages is not enabled on this repository. Measured: `GET
/repos/.../pages`
returns 404. Under `Deploy from a branch` the uploaded artifact is
silently
ignored while the workflow still reports success, so the source must be
set to
`GitHub Actions`.
- `tests/integration/` is excluded by `norecursedirs`, so the browser
suite is a
local guard and never runs in CI.
- The self-hosting page's Makefile target, docker path and port claims
are
unguarded. They were equally unguarded in the README they came from, and
the
owner ruled against adding a guard for them.
- The self-evolution SOP and the benchmark contract stay in the
repository and
are named as plain paths from the pages that reference them. The SOP is
a
translation of an upstream project's internal document and carries
redaction
placeholders, which is a publication decision rather than a formatting
one.
- `docs/plans/` still shows the pre-restyle `mkdocs.yml`. CONTEXT.md
defines that
directory as an archive of the tree as it stood, with an explicit rule
against
updating an old plan to match a later change.
- The Chinese pages drop the brand's italic serif accent word. Cormorant
Garamond
carries no CJK glyphs, so it would fall back to another face without any
sign.
- The code font is Material's default Roboto Mono. The brand names four
typefaces and no monospace, so none was invented for it.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
Add `.github/CODEOWNERS` with a single entry mapping `/raven/agent/` to
`@LivXue`, so a
pull request that changes a file under that directory automatically gets
a review request
from the directory's owner.
This only requests a review. The branch ruleset keeps
`require_code_owner_review` off, so
no approval requirement changes and no contributor's merge path is
affected. Making it a
merge gate would be a separate ruleset change, deliberately not made
here.
Two limits are inherent to the mechanism rather than gaps to close
later:
- GitHub never requests a review from the author of a pull request, so
one opened by the
owner does not assign them. The API answers that case with HTTP 422.
- A draft pull request gets no automatic request. It is sent when the
draft is marked
ready for review.
CODEOWNERS is read from the base branch, so this governs pull requests
opened after it
lands and does not apply retroactively. Ten of the sixteen pull requests
open at the time
of writing touch `raven/agent/`. Those were assigned manually, apart
from the one the
owner authored, which cannot take the assignment for the reason given
above.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
Gates run in a clean worktree branched from `origin/main`, each exit
code read rather than
inferred from empty output:
```
make check-large-files exit 0
make check-source-language exit 0
make check-commits exit 0
```
Behaviour checked against GitHub rather than by reading the file. The
CODEOWNERS validator
on the pushed branch returns no errors, which is what proves both that
the pattern parses
and that the named owner resolves to an account holding write access:
```
gh api "repos/EverMind-AI/Raven/codeowners/errors?ref=..."
{"errors":[]}
```
Not run, and why: `make lint` and `make test-python` analyse Python,
TypeScript and
JavaScript, and this diff adds one ten-line text file containing no
code, so neither
measures anything about the change. No test in the repository exercises
CODEOWNERS
resolution, which is why the validator above is cited instead of a test.
Separately
confirmed that nothing reads the directory this file lands in as a set:
of the three tests
mentioning `.github/`, one validates backticked documentation paths
carrying a known file
extension, one names a single workflow file, and one globs
`.github/workflows` only.
- [ ] Relevant tests pass locally
- [ ] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Nothing changes for any contributor: an added review request does not
gate a merge, and
CODEOWNERS confers no permission of its own. The owner handle named here
is already public
on every commit and pull request in this repository, so the file
discloses nothing new.
Rollback is deleting the file, or the one entry in it. Nothing depends
on it.
- [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
Turn "bug fix to regression case" from a manual chore into a gated
pipeline, and give trajectory regressions their own CI gate.
- `raven trajectory replay --json`: stable machine-readable report
(schema_version 1) with defensive JSON coercion; on a halted replay the
full JSON is still emitted before exit code 2.
- Case metadata contract: `case.yaml` requires non-blank
issue/owner/why/re_record; residual-scan findings pass only with an
explicit per-token human sign-off (`reviewed_residuals`: full-token
sha256 plus a verbatim reason, nothing exempted automatically -- a
machine-produced redaction report is not approval).
- `raven trajectory regression validate [CASE_DIR|--all]`: static commit
gate -- whole-directory discovery so a broken case cannot hide, both
schemas, cassette completeness down to the replay contract (valid JSON
is not a usable payload: missing payloads via the extracted
replayability check, corrupt inner fields via `validate_recording`),
rejection of files the residual scanner would silently skip, and a 256
KiB / 1 MiB size budget; every parse boundary collects problems instead
of raising, so one malformed case cannot abort the --all sweep.
- `raven trajectory regression init <source> --name <case>`: scaffold
from a bundle directory, attempt id, trajectory report tarball, or bug
report package (two-layer extraction; both passes accept only regular
files/directories with root-contained names). Minimize lands in staging;
residual findings are reviewed interactively (the full token is shown
locally, files receive digest and reason); publication copies onto the
destination filesystem under a `.init-` staging name, re-checks the case
name, then renames on one device -- failures clean up only what the run
created.
- Vacuous-pass guard (`MIN_COMMITTED_CASES`, raised by hand) and a
`trajectory` CI job: replay the committed cases, run `validate --all`
even after a pytest failure so both gates report, upload per-case
failure reports (replay --json schema plus check failures, mode from
each case's expect.yaml) as a 14-day artifact.
- Docs: the Trajectory Regression Case entry in CONTEXT.md extended in
place; `tests/trajectories/README.md` documents the per-case layout and
workflow.
Also: `config_secrets_loaded` (a field name of redaction.json itself, a
guaranteed self-referential false positive in every cassette) joins the
residual scanner's benign literals, and both sample cases gain real
`case.yaml` metadata.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/ -q` (after rebasing onto latest main): 23149
passed; the 37 failures and 20 errors are environment-bound and
reproduced identically on a pristine origin/main worktree without these
changes.
- `uv run pytest tests/test_trajectory_regressions.py
tests/test_cli_trajectory_regression_commands.py
tests/test_cli_trajectory_commands.py tests/test_trajectory_replay.py
tests/test_trajectory_cassette.py tests/test_trajectory_redact.py -q`:
282 passed (about 90 new tests across the five steps).
- `uv run ruff check .`, `uv run ruff format --check .`, `make
lint-imports`, `make lint-deps`, `make check-large-files`, `make
check-source-language`: pass. `make lint-types` reports one diagnostic
in `raven/agent/tools/web.py`, a file this branch does not touch,
pre-existing on main.
- CI workflow YAML parses (`yaml.safe_load`); the first real run of the
new `trajectory` job happens on this PR (see this PR's checks).
- CLI assertion width-independence re-verified with `COLUMNS=60`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- All additive: the default `replay` output path is unchanged;
`regression init/validate` are new subcommands; the one scanner change
adds a fixed benign literal (any variation still flags).
- The new `trajectory` CI job becomes a required-passing gate for PRs;
to lift it in an emergency, revert the CI commit (`ci: add trajectory
regression gate job and case-count guard`) -- the remaining commits are
independent.
- Tar extraction accepts only regular files and directories with
root-contained relative names on both layers, with `filter="data"` kept
as defense in depth.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
Nothing in this repo could see a signature change reach its callers.
Ruff reads one file at a time, the import contracts read edges rather
than calls, and the suite only covers lines it executes. The consequence
was concrete: a required `sandbox_home` argument added to
`BoxliteExecutor` reached `plugins-dist/design-engine`'s render path
with CI green, and a reviewer -- not a gate -- found it.
`ty` answers that question. This adds it as a pinned dev dependency, a
`make lint-types` target and a CI step, with **110 of its 133 rules
live**: nine switched off with their measured backlog recorded beside
each, fourteen shipped disabled upstream and untouched.
Getting there meant clearing 81 diagnostics. This PR folds what were
three stacked PRs (#422 and #423, now closed); each rule's story is a
commit of its own.
### 1. The gate, at 108 rules (`chore(*): gate call correctness...`)
21 diagnostics to clear, five of them real:
| Where | What |
|---|---|
| `evolver/orchestrator/production.py` | `design_of` annotated as taking
two parameters while its docstring, its only implementation and its one
call site all use three |
| `raven/cli/provider_commands.py` | `dict[str, callable]` -- the
builtin function, not a type, so the annotation asserted nothing |
| `raven/config/schema.py` | `Config` is a `BaseSettings` but declared
`env_prefix` / `env_nested_delimiter` through pydantic's `ConfigDict`,
which does not carry those keys |
| `raven/spine/delivery.py` | `StreamDelta.conversation_id` is optional
and was used as a `dict[str, str]` key; a delta without one stored a
`None` entry the close path then read as "no open stream", losing that
stream's done marker |
| `research_flow/support/harness_text.py` | a predicate table typed its
matchers as `object`, so nothing checked they are callable |
The rest were unproven invariants and annotations wider than the code:
three late-bound callables asserted where a comment used to carry the
claim, one closure binding the callable it guarded instead of re-reading
it, four `hasattr` probes that now check what the call actually needs,
and a contextmanager yielding the value it just set.
### 2. `unresolved-import` (`fix(*): resolve the imports the type gate
could not`)
21 diagnostics; three were stale module paths nothing had run into:
- `HarnessNode.current_core_version()` read `raven.__core_version__`, a
module that exists neither here nor in the wheel
`scripts/build_core_wheel.py` produces. The read sat inside `try/except
ImportError`, so the except branch was the only branch and **every node
`store.py` saved recorded `core_version="unknown"`**. It reads
`raven.__version__` now and returns `0.1.13`.
- `raven/agent/loop/wiring.py` imported `SkillForgeRouterConfig` from
`raven.config.schema`; it lives in `raven.config.raven`. Under
`TYPE_CHECKING`, so the annotation simply meant nothing.
- three scripts imported `raven.context_engine.base` and
`raven.memory_engine.base`, neither of which exists. **Two failed at
module import** -- running them was not possible.
The other eighteen were the environment: the three agent products keep
their plugin package beside them, so their roots are declared in
`[tool.ty.environment]`; `lxml` ships a compiled `etree` with no type
information, so `lxml-stubs` is a dev dependency (real types rather than
five silenced lines); `uno` and `com.sun.star.*` are suppressed per
line, since that worker runs inside LibreOffice's own interpreter.
### 3. `invalid-return-type` (`fix(*): make the declared return types
true`)
39 diagnostics, and **one stale annotation held eight of them**:
`run_turn` and the `_run_turn` behind it were declared `-> LoopOutcome`
while all three of their returns build a `TurnOutcome` -- a different
dataclass with no field in common. Nothing broke, because the spine
worker reads what it actually gets and `LoopOutcome` never leaves
`_run_agent_loop`. The annotation was the only thing wrong.
The other 31: nine annotations narrower than the code (five `return
tuple(<genexpr>)` typed as fixed-arity tuples, an inner `one()` still
declaring the two-tuple it returned before a third element was added,
`image_block`'s TypedDict), five declarations refusing a value the
function returns (four tool `execute` overrides saying `-> str` while
returning `ToolResult`), seven invariants that lived in a `# type:
ignore` comment, and ten honest widenings.
### 4. What the gates then caught in this PR's own work
- The qq factory guard passed locally only because an earlier test had
left an event loop behind. Reproduced the CI state
(`asyncio.set_event_loop(None)`), then made the test async so the loop
is its own.
- `invalid-return-type`, while still disabled, hid a regression
introduced here: the qq factory returning the class instead of an
instance. Found by diffing the rule histogram, which is why that rule is
on now.
- The diff-coverage gate named four lines in `raven/routing/cache.py` --
the asserts this work had just added, sitting inside a `try` whose
`except Exception` would have swallowed the `AssertionError` and served
the stale cache. `_do_refresh` returns its data now; the asserts, their
noqa and the swallowing all go with it.
`child_scope`, `QQChannel.start()` and `BenchmarkCache` had no tests at
all and have them now. Every one was mutation-checked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `make lint-types` -> All checks passed; 81 diagnostics cleared across
the three rule sets
- Gate proven live three times, once per rule: a missing argument, an
import of a module that does not exist, and a function returning a str
under `-> int` each turn it red, and removing the probe turns it green
- `uv run ruff check` + `ruff format --check` over all six trees ->
clean
- `uv run lint-imports` -> 10 kept, 0 broken; `deptry raven` (all
extras) -> no issues; `uv lock --check` -> resolved
- `make check-source-language` -> exit 0; `commitlint` -> exit 0
- `make coverage` locally: **22050 passed, 45 skipped, 4 failed**; diff
coverage 92.59%
- All four failures are **pre-existing on `main`**, checked by a real
checkout in the same environment where they fail identically: two
`test_the_products_tool_face_*` launcher tests,
`test_a_ceiling_as_large_as_the_window_still_leaves_room_for_history`
(`reserved_tools = 6044 > 6_000`), and
`test_a_missing_key_is_said_once_rather_than_per_query`
(environment-dependent: it asserts `SERPER_API_KEY` is absent)
- Rule counts measured with both `--extra dev` and `--all-extras` --
identical, so this gate's verdict does not depend on which optional
packages are installed
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Behaviour changes are confined to the fixes listed above, and each
replaces an error path with a correct one: nodes are stamped with the
real raven version instead of `"unknown"`, two scripts that could not
start now start, the stream bookkeeping no longer stores a `None` key,
and a cache refresh returns what it fetched. Everything else is a
declaration moved to match what the function already returned.
`tests/` is out of the gate's scope (113 diagnostics under the same
rules). Tests are executed, so a broken call there is already loud; this
gate is for code CI does not run. Bringing them in is sized, separate
work.
Rollback: revert the whole PR to drop the gate and its fixes together,
or delete the `[tool.ty]` block, the `lint-types` target and its CI step
to keep the fixes and drop only the gate.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Two dependency-bump PRs (#385, #387) cannot pass commit lint, and the
four
open dependabot PRs do not agree with the twelve already on main about
what a
dependency bump is called. This fixes both, on the two sides that own
them.
**The scope enum lost a scope it was already using.** `scope-enum`
became
enforced on 2026-09-05 (8f6ef4c0) with a literal `deps` entry. But
`chore(deps-dev)` had merged to main on 2026-06-30 (b3959c9f, #24), two
months
earlier. The enum swept in the sibling and missed this one, so every
dependabot
dev-dependency PR fails a gate for using a scope the repo had already
accepted.
`deps-dev` is restored to the enum; it is not a new scope.
**Dependabot guesses its own prefix, and it has drifted.** Nothing
pinned it, so
it infers one from recent history. The 12 bumps merged so far are
`chore(deps*)`;
the 4 open ones are `build(deps*)`. That split means `git log --grep`
needs two
prefixes to find dependency work, and it will move again. Every
ecosystem now
pins `prefix: "build"` with `include: "scope"`, which is the documented
way to
get `build(deps)` / `build(deps-dev)`. `build` is what AGENTS.md section
3.1
defines for external dependencies.
**Two npm trees had no entry at all.** The repo has five npm lockfiles;
dependabot.yml configured three. `/ui-web` and
`/ui-tui/packages/hermes-ink` were
missing, and both have produced real dependabot PRs (#385 is a `/ui-web`
PR right
now, #57 was a hermes-ink one). Security updates reach them through the
dependency graph regardless of this file, so they were inheriting none
of the
labels, grouping or commit-message settings the other trees get. Adding
them is
what makes the prefix fix actually cover every tree rather than three of
five.
**Neither fix had a gate behind it, so there is one now.** Both files
are edited
by hand, neither imports the other, and the drift they just had stayed
invisible
until a person read a CI log. `tests/test_dependabot_scope_canon.py`
pins six
things: every ecosystem pins its prefix rather than letting dependabot
infer one,
the pinned prefixes agree with each other, every scope the config will
emit is in
the enum, scopes nobody declared are still rejected, every lockfile
tracked in the
tree has an entry, and a repo that has workflows has an ecosystem for
them. It reads the enum
by evaluating `commitlint.config.cjs` with node instead of matching its
text,
anchored on a scope that cannot move so a broken extraction fails loudly
rather
than satisfying every membership assertion.
What this does not fix: dependabot PR bodies quote upstream release
notes
verbatim, which carry emoji and em-dashes, so they still fail the ASCII
gate in
`scripts/check_pr_body.py`. That gate is correct - the PR body becomes
the squash
commit body - and the body is rewritten by hand per PR. Only the scope
half is
automated here.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Ran in a clean worktree cut from `origin/main`:
```
$ uv run pytest tests/test_dependabot_scope_canon.py \
tests/test_commit_lint.py tests/test_readme_scope_canon.py -q
19 passed in 2.65s
$ uv run pre-commit run --files .github/dependabot.yml commitlint.config.cjs
check yaml ... Passed (all hooks Passed or Skipped, none Failed)
$ npx commitlint --from origin/main --to HEAD --config commitlint.config.cjs
(no output, exit 0)
$ PYTHONPATH=. uv run python scripts/check_commit_messages.py origin/main..HEAD
(no output, exit 0)
```
Each of the four open dependabot subjects, and its prospective squash
header,
piped through the real commitlint with this config. Before the change:
```
FAIL build(deps-dev): bump the npm-root-security group across 1 directory with 2 updates
PASS build(deps): bump the tui-security group across 1 directory with 6 updates
```
After:
```
PASS build(deps-dev): bump the npm-root-security group across 1 directory with 2 updates
PASS build(deps-dev): bump js-yaml from 4.3.1 to 4.3.2 in /ui-web
PASS build(deps): bump the bridge-security group across 1 directory with 2 updates
PASS build(deps): bump the tui-security group across 1 directory with 6 updates
PASS build(deps-dev): bump the npm-root-security group across 1 directory with 2 updates (#387)
PASS build(deps-dev): bump js-yaml from 4.3.1 to 4.3.2 in /ui-web (#385)
FAIL build(nonsense-scope): bump something
FAIL build(deps-devv): bump something
FAIL build(deps-dev): Bump something with a capital
```
The last three are the point: the enum still rejects scopes it should
reject, so
this widens it by exactly one entry rather than loosening it.
Each assertion in the new test was then checked against a mutant that
must fail
it, because a config test that only reads the config it was written
against
proves nothing:
```
KILLED drop deps-dev from the enum -> 1 failed, 5 passed
KILLED let the enum accept a typo scope -> 1 failed, 5 passed
KILLED empty the enum entirely -> 2 failed, 4 passed
KILLED drop the /ui-web entry -> 1 failed, 5 passed
KILLED split the ecosystems across two types -> 1 failed, 5 passed
KILLED drop the github-actions ecosystem -> 1 failed, 5 passed
KILLED let one ecosystem guess its prefix again -> 1 failed, 5 passed
```
The dependabot.yml edit was checked structurally, not by eye: both
versions
parsed, and every pre-existing entry is identical apart from the added
`commit-message` block, no entry was dropped, group names stay unique,
and the
npm directories now equal the set of npm lockfiles tracked in the repo.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Behaviour changes, all in tooling:
- One more scope is legal. `feat(deps-dev): ...` also becomes legal,
because
commitlint cannot tie a scope to a type. `deps` already had that
property; this
does not introduce it.
- Future dependabot commits and PR titles are pinned to `build(deps)` /
`build(deps-dev)` instead of whatever it infers. Existing open PRs
already use
those, so nothing needs rewriting.
- `/ui-web` and `/ui-tui/packages/hermes-ink` security updates will now
be
grouped and labelled like the other trees rather than arriving
unconfigured.
`open-pull-requests-limit: 0` matches the other entries, so no
version-update
PRs are enabled by this.
- The prefix pin cannot be verified until the next advisory;
dependabot's
behaviour here is documented but not observable from a local run. If it
turns
out wrong, the enum change alone still unblocks the open PRs.
Rollback: revert the commits. Nothing depends on either file at runtime.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A. Unblocks #385 and #387, which fail `scope-enum` today.
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
<img width="2518" height="1798" alt="image"
src="https://github.com/user-attachments/assets/9bb2dbb6-fe29-42ff-8dba-2e035557b254"
/>
Turns the knowledge page into something a reader can actually run a
knowledge base from: put material into it four ways, look at what is in
it, test what it answers with, and configure it.
**Data sources.** The panel had one button that uploaded one file. It
now offers file, folder, note and URL behind one menu, plus a drop
target over the whole panel. A picked folder is walked by the browser; a
dropped one is walked here, because a drop hands over a directory entry
rather than files. Either way the files are filtered to what this build
can index, capped, and uploaded one at a time: each carries its bytes
base64 in a single websocket frame under a 25 MB ceiling, so N at once
is N of those in memory. One file failing no longer takes the rest of
the folder with it.
A note and a fetched page are stored as the markdown they were captured
as, in the same blob store as every upload, so nothing downstream learns
a second shape. Reading a page follows Cherry Studio's own capture: Jina
Reader, asked for JSON so the page title comes back as a field rather
than as a preamble to parse out of the text, and through
`validate_url_target` first, because the URL arrives from a browser and
without that check the gateway is a request forger.
**Recall Test.** Asks a base a question and shows what comes back: the
chunk, where in its document it sat, its score beside its rank, and what
the search cost. An explicit button rather than search-as-you-type,
because every keystroke used to spend a billed embedding call. Past
questions are kept in localStorage and nowhere else.
**Settings.** Each base carries its own Top K and chunking, with a
sentence on every field saying what moving it costs. The embedding model
is shown and not offered: the collection is sized to its vector width at
creation, so changing it is a rebuild of every vector rather than a
setting, which is what the stale-base check exists to detect. Letting a
reader change it is a separate piece of work.
**Two defects found while measuring the above.**
SiliconFlow refuses an entire request when one input is over the model's
token limit, naming neither which input nor what was wrong with it. A
document of eighteen chunks where seven were long indexed none of the
other eleven, and four documents in a real base were failing this way.
The cause is the chunker's token estimate -- utf-8 bytes over four, an
English-prose rule that reads a CJK character as three quarters of a
token when it is one, and a URL as a quarter of what it costs.
Binary-searching the longest accepted prefix of real documentation pages
against the endpoint put the true figure at 2.1 to 2.3 characters per
token. A vendor client now cuts each input to fit before sending; the
four documents embed whole.
Search reported one number for its cost. It now reports two, because
they answer different questions: embedding is a round trip to whatever
endpoint is configured and runs to hundreds of milliseconds, while the
store query is the index doing its job. A surface reporting one figure
as the search time wants the second, or it is describing the provider.
**Deliberately not wired yet.** File processing lists the processors it
will offer with every row disabled and saying why it is unavailable;
smart chunking, separator, chunk size and overlap are stored on the base
but not yet read by the chunker. Both are placeholders with their state
stated rather than controls that would be silently ignored.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on this branch rebased onto `main` at `4f5d7dac`:
- `uv run pytest -q` -- 22151 passed, 45 skipped
- `npx vitest run` in `ui-web` -- 1738 passed (103 files), of which 92
cover this page
- `npx vitest run` in `ui-tui` -- 2072 passed
- `npx tsc --noEmit` in `ui-web` and `ui-tui` -- clean
- `uv run ruff check raven/ tests/` and `ruff format --check` -- clean
- `node scripts/check-page.mjs`, `check-css.mjs`,
`check-class-namespace.mjs`, `count-shared-globals.mjs` -- all OK
- `make check-large-files` -- OK
- The SiliconFlow client was measured against the live endpoint, not
mocked: batch size is not the limit (64 short inputs pass), 500 CJK
characters pass and 512 do not, and all four previously failing
documents in a real base now embed whole.
- Every panel was checked in the browser in both light and dark themes.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible behaviour changes, all additive:
- A search that names no `top_k` now answers with the base's own setting
instead of a hardcoded 5. New bases default to 6.
- Documents carry an `origin` and bases carry six settings. Every field
is defaulted, so a registry written before them loads with the behaviour
it already had; an older gateway answering without them is read as those
same defaults. A field from a build *after* this one is ignored rather
than losing the row, which is the same protection in the other
direction.
- The SiliconFlow client truncates an over-long input rather than
failing the request. A cut chunk's vector speaks for its beginning; the
chunk is still stored and shown in full when retrieved. The proper fix
is chunking to the model's real limit, which this does not do.
- Four brand-logo SVGs are added under `ui-web/src/assets/providers/`
(16 KB total) and spared the dark-mode inversion that monochrome vendor
marks get.
- Previewing an office file retains a suffixed copy of its bytes in the
render cache, because the converter picks its input filter from the
extension and a blob is stored under a bare id. Deleting the document or
its base now removes that copy, and the cache sweep reaches it as a
backstop for one whose owner never got the chance.
Rollback is a `git revert` of the squash commit; nothing migrates on
disk.
A registry written by this branch stays readable by the previous build,
and that took work: its loader hands every stored key to a dataclass
constructor and drops the row when one is a keyword that constructor
does not take, so a new field written beside the record would make every
base and document vanish from a rolled-back binary, with the records
still on disk and nothing listing them. The settings and the document
origins are therefore written under two sibling keys of `bases` and
`documents`, which a loader that does not know them does not read; a
record that uses none of them is written exactly as before, down to its
keys. What a rollback loses is the settings, which that build has no use
for. What it keeps is every base and every document. A test pins the
stored shape against the field set the shipped loader accepts, rather
than against our own reader.
Security: the URL source takes an arbitrary address from a browser and
fetches it server-side, so it goes through the same
`validate_url_target` guard the web tools use, and there is a test
asserting a refused target never reaches the network.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: admin <admin@SH-HuKai.local>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Follow-up to #413, from a measured look at what was left: a CI shard now
spends 72 s on fixed cost (22 s environment, 48 s collection and worker
start) against 82 s of tests, the four shards are within 15 s of each
other, and 70 unmarked tests were still over the 2 s wall-clock ceiling
on CI against 42 on a laptop because CPU-bound work runs three to four
times slower there. This PR makes the ceiling a gate that is portable
across machines, takes the remaining waits out, precompiles bytecode so
the workers stop doing it four times, and fixes two product waits the
same investigation surfaced.
- `test(*)`: the ceiling judges idle time instead of wall clock, where
idle is the wall clock minus every CPU second spent on the test's
behalf, the reaped children's included (`os.times`). A test waiting on a
production sleep or a process that answers nothing waits the same
seconds on every machine; a test that computes for 2 s here and 7 s on
CI, or drives a browser or eight spawned workers, is not the problem.
The numbers ride on the teardown report so the xdist controller can
judge them; options are `--idle-ceiling` / `--idle-ceiling-strict`. The
fixture that shortens production ladders takes in the ACP cancel settle
(5 s) and the gateway delivery grace (2 s); the CLI agent tests stub the
one-shot command's unconditional 2 s hand-off grace; the rpc subagent
tests no longer spawn a login shell or probe a real endpoint over the
network; three literal timeouts shrink where the stub never answers
anyway. What is left over the ceiling carries a marker: seven real
LibreOffice renders and two tests that wait on a process answering
nothing carry `slow`, two whose assertion is the wait itself carry
`production_timing`.
- `ci(*)`: every shard runs with `--idle-ceiling-strict` (on the make
line, not in `addopts`: the Windows job runs `--noconftest`). Bytecode
precompilation was tried and dropped, the numbers are below; the
workflow is otherwise unchanged from #413.
- `test(agent)`: a heartbeat test asked for five beats of the fifteen
its intervals should produce in a 0.6 s window, and a loaded runner
delivered three. It reads the two gaps instead, which the load cannot
invert: the wait before the first beat is one interval, the wait after
it is the other. Older than the gate that surfaced it; nothing here
touches the registry.
- `perf(ppt-engine)`: `MeasuredWidth.width` remembers measured widths
(bounded, oldest key out); a 15-slide template's QA gates made 1848
freetype calls over 162 distinct keys. Importing `text_metrics` first
raised on a circular import through `template.capacity`; capacity now
imports the module and resolves the name at call time.
- `perf(*)`: `raven gateway` and `raven web` start the litellm import on
a daemon thread at boot, so saving a key from the settings page no
longer waits three to five seconds on it.
- `fix(providers)`: one thread at a time initialises litellm. It raises
three logger levels for the duration of the import and puts the captured
values back after, which holds only while one thread is doing it; a
second caller arriving inside that window captures WARNING as the level
to restore, and litellm's DEBUG and INFO stop reaching the file sink
until a restart. The window was narrow while every import sat on a
startup path and is ordinary now that a server warms it in the
background, so the two callers share a module lock. The strict-mode
warm-up also runs before the fixtures that redirect the home, and
publishing the OAuth token directories created them, so it warms under a
temporary home.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Whole suite, `uv run --frozen --all-extras pytest -q` (macOS, 4
workers), before and after the waits came out and with the ceiling
strict:
| run | result | idle list |
|---|---|---|
| main after #413 | 22052 passed, 43 skipped in 219.41 s | 39 over 2 s
wall clock |
| this branch, `--idle-ceiling` warning | 22057 passed, 43 skipped in
210.20 s | 14 over 2 s idle, all real render or subprocess, now marked |
| this branch, `--idle-ceiling-strict` | 22058 passed, 43 skipped in
204.89 s, exit 0 | none |
The ceiling is three seconds, placed from the suite's own distribution
rather than guessed. Unmarked tests over one second of idle, measured
across the whole suite:
| idle | tests | what they are |
|---|---|---|
| 1.00-1.19 s | 19 | a test that sets a one second timeout and lets it
expire |
| 1.2-1.3 s | 3 | a subprocess handshake |
| 1.5-1.6 s | 3 | an ACP turn interrupted after 0.8 s, and two like it |
| above 1.6 s | 0 | the renders above this line all carry a marker |
A runner stretches that 1.6 s to about 2.2 s, which is how a two second
line failed two shards over tests waiting exactly as long as they meant
to. Three seconds sits in the gap the population leaves, and stays under
every ladder this guards against: the shortest constant the audit found
was a three second grace, the rest run 5, 15, 30 and 60 seconds.
What the metric separates, measured on this suite: a test that sleeps 5
s reports `4.96s idle of 5.02s`; a test that drives a headless browser
for 13 s reports under 0.8 s; six `raven doctor` subprocesses report 1.2
s where wall clock said 4.2 s; eight spawned processes contending for a
lock report under 0.8 s where wall clock said 3.6 s.
Files touched by the product changes and the new markers (`uv run
--frozen --all-extras pytest -q tests/test_litellm_setup.py
tests/test_cli_gateway_commands.py tests/test_cli_serve_commands.py
tests/test_ppt_engine_assets_fonts.py
tests/test_ppt_engine_template_capacity.py
tests/test_cli_doctor_commands.py tests/test_ppt_engine_end_to_end.py
tests/test_ppt_engine_render_service.py tests/test_rpc_model.py`): `434
passed, 2 skipped in 33.39s`, none over 1 s idle. `python -c "import
raven_ppt.services.assets.text_metrics"` in a fresh interpreter:
ImportError before, imports after.
Test-side speedups, measured per test: the ten CLI agent tests 2.0-4.4 s
to 0.05-0.36 s; the three rpc subagent tests 1.4-2.6 s to 0.01-0.02 s;
the rpc save-key test 2.2-2.8 s to 0.03 s; the two ACP probe tests 2.1 s
to 0.2 s.
Bytecode precompilation, seconds from the start of the pytest step to
the first test, per shard, over three runs of this workflow:
| what was compiled | shard 1 | shard 2 | shard 3 | shard 4 | mean |
install step |
|---|---|---|---|---|---|---|
| nothing (#413) | 52.7 | 46.5 | 45.9 | 46.0 | 47.8 | 3-4 s |
| site-packages and checkout | 39.8 | 39.3 | 35.6 | 45.5 | 40.1 | 12-17
s |
| checkout only | 55.5 | 50.1 | 44.4 | 53.8 | 51.0 | 3-4 s |
Compiling site-packages is the half that moved the number and it cost
more in the install step than it returned. Compiling the checkout alone
is inside the noise of doing nothing: the four workers share one `.pyc`
cache, so the first to import a module writes it for the rest, and most
of what a laptop measures as cold compilation is pytest rewriting test
files through a cache `compileall` cannot fill. Both are gone; the
comment in the workflow records it.
The reworked heartbeat assertion was checked against the bug it guards
by making the registry keep its first interval for every beat: one beat
arrives in the window and the assertion fails on it.
The diff gate is reproduced locally against `origin/main` after a full
`make coverage`: `Diff coverage: 100.00% (12/12 executable changed
lines)`. The two warm-up calls in the serving boot coroutines carry a
no-cover pragma naming the test that pins them, because those coroutines
bind a port and serve until they are killed.
The lock is checked against the race it closes: with it taken away, a
test that holds the first caller inside the import and starts a second
fails on `[30, 30, 30] == [20, 20, 20]`. A strict session under a clean
HOME now leaves no `.raven` behind.
`make lint-python` clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none)
## Risk
- The ceiling is now a gate on CI. A new test that waits more than 2 s
without `slow` or `production_timing` turns its shard red; the summary
names the test and the marker to use. A local run stays warning-only.
- A subprocess that does real work is charged to the test that reaped
it, so only a real wait trips the gate. A strict session imports litellm
up front, because its 1.7 s of file opens would otherwise land on
whichever test in the shard imports it first.
- The litellm warm-up runs on a daemon thread at server boot only; unit
tests never reach either boot path (their source is pinned instead), and
a failed import is logged, not raised.
- The width memo returns the same floats; the cap evicts the oldest key.
The capacity import change resolves the same name one step later.
- Rollback: revert the PR; every change is additive or a marker.
- [x] Security impact considered (no security surface touched)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
The unit job takes twelve minutes on one runner. The first cut of this
PR took the production waits out of the tests, which made the suite a
quarter faster on a laptop and moved CI by 14 s (pytest 720.95 s on
main, 706.57 s here): the runner is three to four times slower than a
laptop on CPU-bound tests, and two of the twelve minutes are the four
xdist workers importing every test module. So the PR now attacks the
wall clock from every side that CI's own numbers pointed at.
- `ci(*)`: the unit job runs as four shards. pytest gains `--shard K/N`
in `tests/conftest.py`, decided in `pytest_ignore_collect` so a shard
never imports the other shards' files; test files are dealt round-robin
over their sorted list so the slow families that sort together (the ppt
engine's) are spread out. Each shard writes coverage data and no report;
a `coverage` job downloads the four data files, combines them, writes
`coverage.json` and `coverage.xml`, and runs the gates that used to
follow the tests.
- `perf(ppt-engine)`: `menu()` caches its reading of a template, capped
at eight entries. One bind reads the bound template and then every other
bundled template for the borrow offer; with ten templates bundled, every
bind evicted what the next one needed and re-measured all of them with
freetype. The cap is 32 and a hit moves its entry to the back. On this
PR's first CI run the template-tool file alone was 257 s of the
over-ceiling list, its tests 10 to 26 s each.
- `test(*)`: an autouse fixture collapses the provider chat retry
ladder, the loop's LLM-error ladder and the memory store backoff to a
millisecond per step, and the steer hook grace to one poll. It keeps
each tuple's length because both ladders count attempts with `len()`;
the steps are a millisecond rather than zero because the store pipeline
waits with `wait_for(stopping.wait(), timeout=delay)`, and a zero
timeout cancels that wait before it runs. A test that proves a timing
property opts out with the new `production_timing` marker. Ten tests
spent 257 s of the suite's worker time in those waits; none asserted on
the time.
- `test(*)`: a wall-clock ceiling. Setup plus call over 2 s on a test
marked neither `slow` nor `production_timing` is listed at the end of
the run; `--wall-clock-ceiling-strict` fails an otherwise green session
on it. Warning only here; CI flips to strict once the remaining tail is
marked.
- `test(*)`: every test created two numbered temp directories, and
pytest picks each number by scanning the base temp dir; the fake home is
now a sibling of `tmp_path`. `MPLCONFIGDIR` points at a git-ignored dir
in the checkout, because the fake home changed per test and matplotlib
rebuilt its font list from the system fonts on every run.
- `refactor(agent)`: the outer LLM-error retry ladder default `(15, 30,
60)` lived in three places; it is one constant in
`raven/config/schema.py` now, read by both `RecoveryLimits` and
`_ladder`. Behaviour unchanged.
- `test(updates)`: the first sharded run turned up an order dependency.
`beta_channel` binds `ReleaseInfo` from `raven.updates.upgrade` at
import, the update-notice tests stand a fake in for that module through
`sys.modules`, and `_refresh` imports `beta_channel` lazily; a worker
that imported `beta_channel` for the first time inside that test got an
`ImportError` swallowed as a failed refresh. The test module now imports
`beta_channel` at the top.
- `ci(*)`: the PR diff gate named every `.py` under `plugins-dist` as
production code while coverage measures only `raven` and `raven_everos`,
so a change to the ppt or design engine could never appear in the report
and the gate refused every such PR on sight; the first sharded run hit
it on `menu.py`. The pathspec now names `plugins-dist/everos-memory`,
and a test holds every production pathspec to a package some `--cov`
flag in the Makefile measures.
- Two slow tests were not waits: the sandbox second-cancel test
cancelled one tick too early (two pending cancels coalesce into one
`CancelledError`) and now waits, under a one second timeout, for the
kill to land; the two thousand-session dispatch tests wrote a span per
refused enqueue through a store that opens its file per span, so tracing
is off for them. Follow-up on the product side: `raven/tracing/store.py`
should reuse its handle.
The suite has 30 upper-bound assertions of the form `assert elapsed <
X`; shortened delays can only make those looser.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Whole suite, `uv run --frozen --all-extras pytest -q` (macOS, 4
workers), 22051 passed / 43 skipped each time:
| tree | wall clock | unmarked tests over 2 s |
|---|---|---|
| main before this branch | 372.82 s | (no ceiling yet) |
| after the waits were taken out | 279.65 s | 63 |
| this branch | 224.25 s | 39 |
The shards partition the suite exactly (`uv run --frozen --all-extras
pytest --collect-only -q -n 0 --shard K/4`, K = 1..4):
| whole | shard 1 | shard 2 | shard 3 | shard 4 | union | ids in two
shards |
|---|---|---|---|---|---|---|
| 22095 | 5058 | 5555 | 5955 | 5527 | 22095 | 0 |
196 / 195 / 194 / 194 test files per shard. A shard collects in 7 s
where the whole suite takes 23 s on the same machine. `--ignore` still
works under `--shard`: with four `--ignore` flags on shard 1, the
ignored file that shard owns is gone from its collection (5034 ids
against 5058).
Combining loses nothing. Two small runs with `--cov=raven
--cov=raven_everos --cov-branch --cov-report=` and `COVERAGE_FILE` set,
then `make coverage-combine COVERAGE_DATA_DIR=<dir>`, against one `make
coverage` of the whole suite on main:
| report | files | statements | branches |
|---|---|---|---|
| one run of the whole suite | 704 | 82634 | 25548 |
| two shards combined | 704 | 82636 | 25548 |
Same file set; the two extra statements are the new constant and its
import. A source package's never-imported files reach the combined
report through the shard that imported it, as they reached the single
run.
The menu cache, the three files that bind templates (`uv run --frozen
--all-extras pytest -q tests/test_ppt_engine_template_tool.py
tests/test_ppt_engine_outline_checks.py
tests/test_ppt_engine_default_templates.py`): 101 s of worker time in
the last profile, now `196 passed in 11.84s` with no test over 2.9 s.
The files that call `menu()` directly: `219 passed in 8.06s`.
The font cache, the formula render test at `-n 0`: 8.91 s cold, 0.69 s
on the next run. Seven home-sensitive files: `484 passed in 5.30s`.
Ceiling guard, both modes, with the ceiling forced low so it has
something to list:
```
uv run --frozen --all-extras pytest -q -n 0 --wall-clock-ceiling=0.01 tests/test_import_cycle_budget.py tests/test_updates_install_guard.py
uv run --frozen --all-extras pytest -q -n 2 --wall-clock-ceiling=0.01 --wall-clock-ceiling-strict tests/test_updates_install_guard.py
```
First: 28 passed, five listed, exit 0. Second: 24 passed, four listed,
exit 1 (the controller flips the status; workers do not).
`make lint-python` clean, `make lint-imports` passes. The CI run on this
PR is the measurement that matters: four `unit` shards and one `coverage
gates` job.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none: CI
plumbing, a cache cap, test setup)
## Risk
- The coverage gates now run in a job after the four shards. A red shard
skips the gates, a deliberate trade: combining three of four data files
would report a coverage drop that is not one, and the PR is red either
way. The gate scripts and their thresholds are unchanged.
- The diff gate no longer sees `plugins-dist/ppt-engine` or
`plugins-dist/design-engine` at all, as it could never judge them;
measuring them (`--cov=raven_ppt --cov=raven_design`, a new ratchet
baseline) is the follow-up that would bring them under the gate.
- `--shard` is opt-in; a plain `pytest` run collects everything as
before. Shard data artifacts are kept one day, the combined reports 30
days as before.
- No product behaviour change: the ladder default is the same tuple read
from one place; the menu cap only changes how long the cache keeps
entries.
- Test-only risk: a test that implicitly relied on a production-length
retry delay would see different timing. The full suite passed with the
fixture on, and a single test can opt out with `production_timing`.
- Rollback: revert the PR. The unit job goes back to one runner with the
gates inline; both markers are additive.
- [x] Security impact considered (no security surface touched)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
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
Two bugs in the served page, both of the same shape: a refusal the surface did
not report as one. They are one MR because they were found in one pass over the
page's write paths and each is a few lines; the commits are separate and can be
read independently.
**1. Bulk delete dropped rows the server had kept.** `DS.sessions.deleteAll`
awaited `session.delete` and counted every call that did not throw as a
removal. A refusal does not throw: the method answers
`{deleted: null, still_on_disk: true}` when the filesystem refused to remove
the file, and that is a resolved promise. The rail dropped the row while the
transcript stayed on disk, so the session came back on the next reload -- the
one thing the note above that function says it must never do. The bulk path now
reads the answer with the predicate the single delete already uses. The
single-delete half was fixed in 3d4075c8, which added `still_on_disk`; the bulk
path was not part of that change.
**2. Attachments over about 3 MB killed the socket.** `fs.upload` accepts
25 MB. The socket carrying it accepted 4 MiB, because
`web.WebSocketResponse(heartbeat=30)` left `max_msg_size` at aiohttp's default.
An upload rides as base64 inside one JSON-RPC frame and base64 costs four bytes
for every three, so the real ceiling was about 2.99 MB of file -- enforced by
closing the connection, before `fs.upload` was ever called. The reader saw a
reconnect rather than a reason, and every other in-flight call on that socket
died with it. The advertised 25 MB limit was unreachable, and so was the
message that states it. The knowledge base feeds the same method, and manuals
and reports clear 3 MB far more often than pasted screenshots do.
The upload limit moves to `raven/rpc/files.py` beside `MAX_VIEW_BYTES`, and
`frame_ceiling_for_upload` derives the transport ceiling from it, so raising one
can no longer leave the other behind. The page also refuses an oversized file
itself: past the ceiling the socket still closes, so the server's own refusal
cannot reach a client that sent one.
**Checked and deliberately not changed.**
- The page carries its own copy of the 25 MB number. No limit rides the wire
today, and publishing one through `system.hello` is a schema change with
generated-client churn on both front ends, which this fix does not need. The
Python constant is named as the source in the comment beside the copy.
- A client that is not the page -- a script, a future surface -- can still cross
the frame ceiling and lose the socket, because the guard is in the page. The
transport cannot answer a frame it refused to read; the fix for that is an
upload route that does not ride the socket at all, which is a larger change
than this bug warrants.
- A file one byte over the limit is refused by a message that rounds both
numbers to `25.0 MB`. Showing exact byte counts reads worse for every other
size, and the server refuses that file too.
- The composer still encodes before it refuses, unlike the knowledge path. Its
caller in the React island holds the `File`, so moving the check there is an
island change; the files it stages are screenshots, where the encode is cheap.
- `MAX_VIEW_BYTES` is unchanged. It bounds what the viewer reads back out and
travels over HTTP, not over the socket.
- `<agent home>/uploads` has no TTL, no count cap and no reclaim path, and this
change raises what a single upload can put there from about 3 MB to 25 MB.
Deferred rather than solved here: a reclaim policy is a decision about that
directory's whole lifetime, and the ceiling it would be sized against is the
one this MR is what makes reachable. Named so that it reads as a deferral
rather than as an oversight.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Gates, each run as its own target and its exit code read directly rather than
through a pipe:
- `make lint-python` -- 0. First run reported `raven/rpc/files.py` and
`tests/test_rpc_transport.py` would be reformatted; `ruff format` applied and
the rerun is clean.
- `make lint-imports` -- 0
- `make lint-ui` -- 0 (`gen:check` in sync, `type-check` clean)
- `make test-ui` -- 0. 103 files, 1671 tests, 0 failed.
- `make build-ui` -- 0. `dist/index.html` rebuilt.
- `make test-python` -- 0. 21341 passed, 55 skipped, 0 failed, in 389s. No
failures to reconcile against a clean `origin/main`, because there were none.
- `make check-commits`, `make check-source-language`, `make check-large-files`
-- all 0.
Mutation tests, each reverted afterwards with `git status` confirmed clean:
- Removing `max_msg_size` from `WebSocketResponse` fails
`test_the_socket_carries_a_frame_larger_than_aiohttp_would_allow_by_default`
and nothing else.
- Making `frame_ceiling_for_upload` return the limit without the base64
expansion fails
`test_the_frame_ceiling_can_carry_the_largest_upload_the_method_accepts` and
nothing else.
- Restoring the bare `await` in `deleteAll` fails two of the four new bulk
cases: `keeps the rows whose files survived their removal` and `keeps a row
when the server does not carry the field`.
Verified against a running gateway, not only in tests. Uploading through
`/rpc` with the session token, before the change: 1 MB and 2.5 MB stored, 3 MB
and 3.2 MB and 5 MB lost the connection. After: all five stored, and 24 MB
stored. The page's own guard was then exercised out of the built
`dist/index.html` rather than the source: a file of exactly the limit passes,
one byte more is refused, and the refusal names the file and both sizes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
An authenticated client can now make the gateway buffer a frame of about
33 MiB rather than 4 MiB. The socket is reachable only with the session cookie
or the token, and the method it feeds already accepted 25 MB, so this raises
what an authorised caller can spend, not who can spend it.
No contract changes: no method gains or loses a field, and no response shape
moves. A page built before this change works against a gateway carrying it, and
the reverse holds with the old ceiling. Rollback is a revert of either commit
independently.
## Related Issues
N/A
## Summary
Two bugs in the served page, both of the same shape: a refusal the surface did
not report as one. They are one MR because they were found in one pass over the
page's write paths and each is a few lines; the commits are separate and can be
read independently.
**1. Bulk delete dropped rows the server had kept.** `DS.sessions.deleteAll`
awaited `session.delete` and counted every call that did not throw as a
removal. A refusal does not throw: the method answers
`{deleted: null, still_on_disk: true}` when the filesystem refused to remove
the file, and that is a resolved promise. The rail dropped the row while the
transcript stayed on disk, so the session came back on the next reload -- the
one thing the note above that function says it must never do. The bulk path now
reads the answer with the predicate the single delete already uses. The
single-delete half was fixed in 3d4075c8, which added `still_on_disk`; the bulk
path was not part of that change.
**2. Attachments over about 3 MB killed the socket.** `fs.upload` accepts
25 MB. The socket carrying it accepted 4 MiB, because
`web.WebSocketResponse(heartbeat=30)` left `max_msg_size` at aiohttp's default.
An upload rides as base64 inside one JSON-RPC frame and base64 costs four bytes
for every three, so the real ceiling was about 2.99 MB of file -- enforced by
closing the connection, before `fs.upload` was ever called. The reader saw a
reconnect rather than a reason, and every other in-flight call on that socket
died with it. The advertised 25 MB limit was unreachable, and so was the
message that states it. The knowledge base feeds the same method, and manuals
and reports clear 3 MB far more often than pasted screenshots do.
The upload limit moves to `raven/rpc/files.py` beside `MAX_VIEW_BYTES`, and
`frame_ceiling_for_upload` derives the transport ceiling from it, so raising one
can no longer leave the other behind. The page also refuses an oversized file
itself: past the ceiling the socket still closes, so the server's own refusal
cannot reach a client that sent one.
**Checked and deliberately not changed.**
- The page carries its own copy of the 25 MB number. No limit rides the wire
today, and publishing one through `system.hello` is a schema change with
generated-client churn on both front ends, which this fix does not need. The
Python constant is named as the source in the comment beside the copy.
- A client that is not the page -- a script, a future surface -- can still cross
the frame ceiling and lose the socket, because the guard is in the page. The
transport cannot answer a frame it refused to read; the fix for that is an
upload route that does not ride the socket at all, which is a larger change
than this bug warrants.
- A file one byte over the limit is refused by a message that rounds both
numbers to `25.0 MB`. Showing exact byte counts reads worse for every other
size, and the server refuses that file too.
- The composer still encodes before it refuses, unlike the knowledge path. Its
caller in the React island holds the `File`, so moving the check there is an
island change; the files it stages are screenshots, where the encode is cheap.
- `MAX_VIEW_BYTES` is unchanged. It bounds what the viewer reads back out and
travels over HTTP, not over the socket.
- `<agent home>/uploads` has no TTL, no count cap and no reclaim path, and this
change raises what a single upload can put there from about 3 MB to 25 MB.
Deferred rather than solved here: a reclaim policy is a decision about that
directory's whole lifetime, and the ceiling it would be sized against is the
one this MR is what makes reachable. Named so that it reads as a deferral
rather than as an oversight.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Gates, each run as its own target and its exit code read directly rather than
through a pipe:
- `make lint-python` -- 0. First run reported `raven/rpc/files.py` and
`tests/test_rpc_transport.py` would be reformatted; `ruff format` applied and
the rerun is clean.
- `make lint-imports` -- 0
- `make lint-ui` -- 0 (`gen:check` in sync, `type-check` clean)
- `make test-ui` -- 0. 103 files, 1671 tests, 0 failed.
- `make build-ui` -- 0. `dist/index.html` rebuilt.
- `make test-python` -- 0. 21341 passed, 55 skipped, 0 failed, in 389s. No
failures to reconcile against a clean `origin/main`, because there were none.
- `make check-commits`, `make check-source-language`, `make check-large-files`
-- all 0.
Mutation tests, each reverted afterwards with `git status` confirmed clean:
- Removing `max_msg_size` from `WebSocketResponse` fails
`test_the_socket_carries_a_frame_larger_than_aiohttp_would_allow_by_default`
and nothing else.
- Making `frame_ceiling_for_upload` return the limit without the base64
expansion fails
`test_the_frame_ceiling_can_carry_the_largest_upload_the_method_accepts` and
nothing else.
- Restoring the bare `await` in `deleteAll` fails two of the four new bulk
cases: `keeps the rows whose files survived their removal` and `keeps a row
when the server does not carry the field`.
Verified against a running gateway, not only in tests. Uploading through
`/rpc` with the session token, before the change: 1 MB and 2.5 MB stored, 3 MB
and 3.2 MB and 5 MB lost the connection. After: all five stored, and 24 MB
stored. The page's own guard was then exercised out of the built
`dist/index.html` rather than the source: a file of exactly the limit passes,
one byte more is refused, and the refusal names the file and both sizes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
An authenticated client can now make the gateway buffer a frame of about
33 MiB rather than 4 MiB. The socket is reachable only with the session cookie
or the token, and the method it feeds already accepted 25 MB, so this raises
what an authorised caller can spend, not who can spend it.
No contract changes: no method gains or loses a field, and no response shape
moves. A page built before this change works against a gateway carrying it, and
the reverse holds with the old ceiling. Rollback is a revert of either commit
independently.
## Related Issues
N/A
## Summary
`image_generate` could only be handed one prompt, so a caller that needs several
pictures pays for them one call at a time. In a real deck run, eight backdrops
were asked for one after another and the nine calls took 38.6, 35.2, 43.3, 54.2,
81.6, 85.9, 95.4, 103.6 and 108.0 seconds: 645.8 seconds of pure serial waiting
for work that has no order between its pieces.
The deck engine had already answered exactly this for its own generator
(`ppt_generate_image` takes `prompts` and gathers them). This puts that shape on
the host tool every caller shares, rather than leaving it behind a plugin.
Key decisions:
- `prompts[]` carries a full spec per picture: its own `prompt`, and optional
`filename`, `images`, `aspect_ratio` and `quality`. Whatever an item leaves
out falls back to the call's top-level value, so a batch that varies only the
prompt stays short. `model` and `output_dir` stay shared by the whole call --
one call speaks to one deployment and writes into one directory.
- A top-level `prompt` given alongside `prompts` is generated as the first
picture, so the two forms compose instead of conflicting.
- One prompt, in whichever form it arrives, is answered in exactly the shape it
always was, key for key. Existing callers see no change.
- The batch holds at four in flight, the ceiling the deck engine settled on: a
batch is waited on as a whole, so the cap only has to keep the slowest picture
from arriving last, and a wider fan-out against one key buys 429s.
- Failures are per picture. The batch is gathered with `return_exceptions=True`,
so a directory refused for one of eight does not throw the other seven away;
the answer keeps every path under `paths` for the `message` tool's `media`
field and says on each result what was made, or why it was not.
- An optional `filename` is sanitised to a bare stem before it names a file. The
name comes from the model, so a directory inside it is dropped rather than
honoured, and `output_dir` stays the only thing that decides where a picture
lands.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All run from the rebased branch tip, after `uv sync --frozen --all-extras`
(exit 0), with `set -o pipefail` and the exit code checked each time.
- `uv run --frozen pytest tests/test_media_gen_tool.py -q` -- 84 passed, exit 0.
The file gained 211 lines of tests covering: the single-prompt reply being
unchanged key for key, top-level values as batch defaults, per-item overrides,
the top-level prompt landing first, a missing or blank prompt being refused,
one picture failing while the rest come back, an exception inside one picture
not taking the batch, concurrency capped at four, and `filename` refusing a
path traversal.
- `uv run --frozen pytest` over the 15 test files that touch `image_generate` /
`media_gen` / `ImageGenerateTool` (`test_media_gen_tool`,
`test_ppt_engine_generate_image_tool`, `test_ppt_engine_plugin`,
`test_ppt_engine_assembly`, `test_agent_loop_web_tools`, `test_tool_registry_timeout`,
`test_tool_registry_turn_scope`, `test_tool_capabilities`, `test_tool_search`,
`test_core_plugin_stack`, `test_plugin_contribution_ledger`, `test_rpc_console`,
`test_cli_doctor_commands`, `test_provider_auth_method`,
`test_agents_design_launcher`) -- 592 passed, exit 0.
- `make lint-python` -- exit 0. Ruff check: all checks passed. Ruff format:
1921 files already formatted.
- `COMMIT_RANGE=origin/main..HEAD make check-source-language` -- exit 0.
- `COMMIT_RANGE=origin/main..HEAD make check-commits` -- exit 0.
- `COMMIT_RANGE=origin/main..HEAD make check-large-files` -- exit 0.
Not verified here: a live batch against the OpenRouter endpoint. The tests drive
the HTTP layer through a stub.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible behaviour changes:
- The tool schema no longer marks `prompt` as required, because either `prompt`
or `prompts` will do. A call carrying neither is refused at runtime with
`nothing to generate: give prompt, or prompts=[{"prompt": ...}, ...]` instead
of being rejected by the schema, so the model reads a sentence rather than a
validation error.
- `filename` is new at the top level and per item. A name that carries a
directory is reduced to its stem; it is not honoured and not an error.
- The tool description now tells the caller to plan every picture and ask for
them together, so an agent that used to emit N calls will tend to emit one.
That is the point of the change, but it does shift how the tool gets called.
- Every reply for a single prompt keeps its old shape, so nothing that reads
`paths` or `success` today needs to change.
Rollback: the change is one commit touching `raven/agent/tools/media_gen.py` and
`tests/test_media_gen_tool.py`. Reverting it restores the single-prompt tool
exactly; no state, config, schema or stored data is carried forward.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
`image_generate` could only be handed one prompt, so a caller that needs several
pictures pays for them one call at a time. In a real deck run, eight backdrops
were asked for one after another and the nine calls took 38.6, 35.2, 43.3, 54.2,
81.6, 85.9, 95.4, 103.6 and 108.0 seconds: 645.8 seconds of pure serial waiting
for work that has no order between its pieces.
The deck engine had already answered exactly this for its own generator
(`ppt_generate_image` takes `prompts` and gathers them). This puts that shape on
the host tool every caller shares, rather than leaving it behind a plugin.
Key decisions:
- `prompts[]` carries a full spec per picture: its own `prompt`, and optional
`filename`, `images`, `aspect_ratio` and `quality`. Whatever an item leaves
out falls back to the call's top-level value, so a batch that varies only the
prompt stays short. `model` and `output_dir` stay shared by the whole call --
one call speaks to one deployment and writes into one directory.
- A top-level `prompt` given alongside `prompts` is generated as the first
picture, so the two forms compose instead of conflicting.
- One prompt, in whichever form it arrives, is answered in exactly the shape it
always was, key for key. Existing callers see no change.
- The batch holds at four in flight, the ceiling the deck engine settled on: a
batch is waited on as a whole, so the cap only has to keep the slowest picture
from arriving last, and a wider fan-out against one key buys 429s.
- Failures are per picture. The batch is gathered with `return_exceptions=True`,
so a directory refused for one of eight does not throw the other seven away;
the answer keeps every path under `paths` for the `message` tool's `media`
field and says on each result what was made, or why it was not.
- An optional `filename` is sanitised to a bare stem before it names a file. The
name comes from the model, so a directory inside it is dropped rather than
honoured, and `output_dir` stays the only thing that decides where a picture
lands.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All run from the rebased branch tip, after `uv sync --frozen --all-extras`
(exit 0), with `set -o pipefail` and the exit code checked each time.
- `uv run --frozen pytest tests/test_media_gen_tool.py -q` -- 84 passed, exit 0.
The file gained 211 lines of tests covering: the single-prompt reply being
unchanged key for key, top-level values as batch defaults, per-item overrides,
the top-level prompt landing first, a missing or blank prompt being refused,
one picture failing while the rest come back, an exception inside one picture
not taking the batch, concurrency capped at four, and `filename` refusing a
path traversal.
- `uv run --frozen pytest` over the 15 test files that touch `image_generate` /
`media_gen` / `ImageGenerateTool` (`test_media_gen_tool`,
`test_ppt_engine_generate_image_tool`, `test_ppt_engine_plugin`,
`test_ppt_engine_assembly`, `test_agent_loop_web_tools`, `test_tool_registry_timeout`,
`test_tool_registry_turn_scope`, `test_tool_capabilities`, `test_tool_search`,
`test_core_plugin_stack`, `test_plugin_contribution_ledger`, `test_rpc_console`,
`test_cli_doctor_commands`, `test_provider_auth_method`,
`test_agents_design_launcher`) -- 592 passed, exit 0.
- `make lint-python` -- exit 0. Ruff check: all checks passed. Ruff format:
1921 files already formatted.
- `COMMIT_RANGE=origin/main..HEAD make check-source-language` -- exit 0.
- `COMMIT_RANGE=origin/main..HEAD make check-commits` -- exit 0.
- `COMMIT_RANGE=origin/main..HEAD make check-large-files` -- exit 0.
Not verified here: a live batch against the OpenRouter endpoint. The tests drive
the HTTP layer through a stub.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible behaviour changes:
- The tool schema no longer marks `prompt` as required, because either `prompt`
or `prompts` will do. A call carrying neither is refused at runtime with
`nothing to generate: give prompt, or prompts=[{"prompt": ...}, ...]` instead
of being rejected by the schema, so the model reads a sentence rather than a
validation error.
- `filename` is new at the top level and per item. A name that carries a
directory is reduced to its stem; it is not honoured and not an error.
- The tool description now tells the caller to plan every picture and ask for
them together, so an agent that used to emit N calls will tend to emit one.
That is the point of the change, but it does shift how the tool gets called.
- Every reply for a single prompt keeps its old shape, so nothing that reads
`paths` or `success` today needs to change.
Rollback: the change is one commit touching `raven/agent/tools/media_gen.py` and
`tests/test_media_gen_tool.py`. Reverting it restores the single-prompt tool
exactly; no state, config, schema or stored data is carried forward.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
`pyproject.toml` already carried three hand-written pins against a single
failure mode:
```
# transitive dep of litellm -- pinning it directly so the everos
# extractor keeps working if upstream ever drops it.
# transitive dep (via lancedb) -- pinning it directly so routing keeps
# working if upstream ever drops it.
# Reaches us anyway via everos[multimodal] -> everalgo-parser, but that is a
# three-hop transitive path -- pinning it directly so reading an image keeps
# working if any link in that chain drops it.
```
The mode is real and the team was already defending against it one package at a
time. This wires up `deptry`, which is that habit automated, and it found seven
more the manual pass had missed.
**What it catches.** A direct import of a package that only reaches the install
through someone else's dependency table. The day that package drops it, the
install stops carrying it and raven fails at import time, far from the cause.
**This is insurance, not iteration speed.** It adds a gate; it makes nothing
faster. The argument for it is that the failure it prevents is one this
repository has already decided is worth defending against by hand.
### What the 45 reports actually were
Four real, three correct-as-written:
| Package | Sites | Disposition |
|---|---|---|
| `aiohttp` | 15 (3 module-level) | **Declared.** Imported at module level in `rpc/control.py` and both rpc transports, yet it appeared only under `[tool.uv] constraint-dependencies` -- which constrains a version without declaring a dependency |
| `click` | 2 | **Declared.** Used directly, arrives through typer |
| `pyarrow` | 1 | **Declared.** Used directly, arrives through lancedb |
| `pydantic_core` | 1 | **No dependency added.** `pydantic.fields` re-exports the same `PydanticUndefined` object, verified `is`-identical, so the import moves instead |
| `raven_everos` | 24 | **Ignored, reason recorded.** A separate distribution discovered through the `raven.plugins` entry-point group; every import is inside a function for that reason, and declaring it would turn an optional plugin into a hard runtime requirement |
| `requests` | 1 | **Ignored, reason recorded.** Probed under `try: import ... except ImportError` in `channels/errors.py` so its connection errors join the transient set when the host happens to carry it |
| `cryptography` | 1 | **Ignored, reason recorded.** Fallback AES path in the weixin adapter under `with suppress(ImportError)` |
The `aiohttp` case is the one worth a reviewer's attention: a
`constraint-dependencies` entry looks like a declaration in a diff and is not
one. Three module-level imports were relying on something else to bring it.
### Only DEP003 is a gate
`DEP001` and `DEP002` are off. Both are dominated here by the gap between a
distribution name and its import name (`matrix-nio` -> `nio`, `qq-botpy` ->
`botpy`, `python-socketio` -> `socketio`), so they report the same fact twice as
noise. `DEP002` would additionally report the three deliberate pins quoted above
as unused dependencies, which is the opposite of their intent.
Wired as `make lint-deps`, run from `lint` and from CI beside the import
contracts. `lint-imports` was missing from `.PHONY`; both are added.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Other: a dependency gate, three dependency declarations, and one import moved.
## Verification
```
$ uv run --frozen --python 3.12 deptry raven
Success! No dependency issues found.
$ make lint-deps
Success! No dependency issues found.
$ uv run --frozen --python 3.12 --extra dev ruff check --no-cache \
raven evolver agents plugins-dist tests scripts
All checks passed!
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/ -q -k "update_providers or provider_commands or knowledge or weixin or channels_errors or confirm_injection or cli_dispatch"
496 passed
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
Checked in the failing direction, since a gate never seen red is not known to
work. The first probe was a mistake worth recording: importing `litellm` changed
nothing, because litellm is a declared dependency and the gate was right to stay
quiet. A genuinely undeclared transitive package does trip it:
```
$ echo 'import certifi' >> raven/utils/text.py # arrives via httpx, declared nowhere
raven/utils/text.py:81:8: DEP003 'certifi' imported but it is a transitive dependency
Found 1 dependency issue.
```
The probe was reverted.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Three packages move into `[project.dependencies]`. All three are already present
in every install today -- they arrive through typer, lancedb and the aiohttp
constraint -- so this records what is already true rather than adding weight.
The one code change is an import moved to a re-export of the identical object,
verified with `is`.
The risk the gate itself carries is a false negative on a package that is both
optional and genuinely needed; the three ignores are the place that could go
wrong, which is why each carries its reason in the config rather than a bare
name.
Rollback is reverting the one commit. Loosening instead is removing `lint-deps`
from the `lint` target, which leaves the declarations in place.
## Related Issues
N/A
## Summary
This branch folds four merge requests and one unpushed commit into one, so that `main`
takes one review, one approval and one merge instead of four, and so the eight-file
overlap between them is resolved once. It carries, in this order:
- **!602** `feat/ppt_deliver_to_named_path` -- `ppt_build` takes `deliver_to`; every
publish writes the deck under `out/` and copies the same measured bytes to the path
the user named, recording it with `role: "delivery"`. The PDF preview rides along only
where its own `.pdf` name is free: a file already at that stem is the user's and is
left alone, and the reply says the preview stayed under `out/`.
- **!628** `feat/ppt_copy_route_and_page_isolation` -- `adapt` is removed, so cloning a
template page and writing into it with `replace_text` is the only route; a page whose
block raises loses only itself and the pages after it still build; a draft counts
against the tier's build cap and one is released at it.
- **!632** `feat/ship_templates_and_soffice_dep` -- the ten bundled deck templates are
tracked in git with per-file sha256 pins, so a fresh clone can build a deck; the
LibreOffice dependency is declared and resolved through one resolver.
- **!642** `fix/ppt_copy_route_and_clone_typography` -- a copy-route lookup that finds
nothing names the near miss before the inventory; a text frame with no paragraph at
all can be written into; a cloned page's title size is said; `row_type_drift` compares
the same structural slot across a run's units.
- **D57's other-page clause, rewired.** D57 gave five refusals a "did you mean" hint,
and one of them also answered "the string you named is on page N of this template".
That clause needs the file a page was cloned out of, and the only refusal holding it
was `adapt`'s, which !628 removed. It is restored by reading `PPT_TEMPLATE_SOURCE`,
which the runner already sets in the author's own process and which this module
already reads for `bundled()`; the two helpers behind the clause are unchanged.
- **D60** `read the ground under each word, not across the whole box` -- the `unreadable`
contrast gate also measures the render's own word boxes, as extra regions through the
same guards, so a two-line block crossed by a narrow bright ridge can no longer elect
the dark ground and read as legible.
Decisions the union forced, none of which drops a behaviour:
- The publish record is built !602's way, with its delivery `role`, and written the way
D49 requires -- read back off the file, atomic, and refused rather than silent when
the record cannot be written.
- `clear_region`, `shapes_in`, `page_box` and the refusal of a bare four-number region
survive `adapt`'s removal; so do `_heading_rows` and its helpers, which the row
reading loads even though the call they were written for is gone.
- The author-facing guidance names !628's single route and keeps D59's rule that a
region must declare which reading it is.
**The decision log carries a numbering collision, on purpose.** It is a set union with
no wording changed, and the numbers are left exactly as each branch wrote them, so a
reviewer meets this rather than discovers it:
- !602 and !628 each wrote a **D37** and a **D38**, about different decisions.
- !628's **D45** is not `main`'s D45; they are unrelated entries under one number.
- !628's **D42** is `main`'s **D45** word for word, so the merged log carries one
decision under two numbers.
Renumbering touches every cross-reference in the log, and doing that inside a
seventy-commit fold immediately before a merge is how a silent break gets in. The
numbering is being fixed on a separate branch, which carries a script and a test that
fails when a citation points at nothing.
## Type
- [x] Feature
- [x] Fix
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on an interpreter carrying `python-pptx`, with `PYTHONPATH` at this worktree and its
`plugins-dist/ppt-engine`, confirmed from a neutral working directory that `raven` and
`raven_ppt` resolve out of the worktree and not the host repo.
- `make test-python` (the whole suite, as CI runs it) -- 20826 passed, 49 skipped, and
26 failures this machine produces on any branch: it has no `/usr/share/zoneinfo`, so
every cron timezone case raises `ValueError: unknown timezone 'Asia/Shanghai'`. Checked
out plain `origin/main` in a clean worktree and ran the same two files: the same 6
failed and 20 errors, the ids identical character for character. Nothing on this branch
touches cron or timezones. The stale `test_trunks_executor_would_have_dropped_that_output`
that failed on the previous revision is retired on the new base and its replacement,
`test_trunks_executor_preserves_output_on_timeout`, was run on its own and passes.
The 6 failures and 20 errors are all cron timezone tests failing identically on plain
`main` in a clean worktree, on a host with no `/usr/share/zoneinfo`.
- `make check-commits` -- exit 0.
- `make check-source-language` -- exit 0.
- `make check-large-files` -- exit 0.
- `make lint-imports` -- exit 0, 9 contracts kept, 0 broken.
- `ruff check` and `ruff format --check` over the 80 changed Python files -- exit 0.
- `pytest tests/test_ppt_engine_templates.py tests/test_utils_office.py
tests/test_cli_doctor_commands.py` -- 97 passed; the ten templates are tracked and
satisfy their pins, and the soffice resolver finds the local binary.
- The delivery contract, the record read-back, the page isolation and the near miss were
each run as a measurement rather than asserted; the `unreadable` gate was run through
the real LibreOffice render chain on a delivered 12-page deck and reports BLOCKING on
page 12 under one word at 1.6:1.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes: `ppt_build` gains `deliver_to` and delivers outside `out/`;
`adapt` is gone from the author-facing template module, so a program calling it fails to
import -- `title=` and `subtitle=` have no replacement and the heading is named by the
words the template put there; a draft now counts against the tier's build cap; three
gates that nothing measured against being wrong no longer refuse; and the ten templates
are now bytes in the repository rather than a private registry fetch.
Two pieces here are about not destroying something the user has. The delivery
refuses to write its `.pdf` where a file the user already owns sits at the same
stem, rather than replacing it; and the large-file roster moved out of the manifest
inside the tree being checked and into the gate's own source, so a change can no
longer grant itself the exception the gate exists to withhold.
Rollback is per piece: each of the five sources is a contiguous run of commits on this
branch, in the order listed above, so any one of them can be reverted as a range without
touching the others.
- [x] Backward compatibility considered
- [x] Security impact considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Add GPT Image 2.5 Sunburst and Flare to the image model picker, with Sunburst selected when no model is configured. Remove Nano Banana 2 from the recommended list while retaining custom model entry.
Order presets by GPT Image 2.5 (Sunburst, Flare), GPT Image 2 (low, medium, high), Seedream (Lite, Pro), Qwen Image (3, 3 Pro), and Grok Image. Use provider-default quality for the new variants when no quality is supplied; retain the GPT Image 2 medium default and explicit settings precedence.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Python commands used UV_PROJECT_ENVIRONMENT=../raven/.venv; script checks also used PYTHONPATH=.
- `uv run --no-sync pytest tests/test_media_gen_tool.py -q -n0`: 64 passed.
- `npm test --prefix ui-web -- src/features/settings/SettingsPage.test.tsx`: 52 passed.
- `npm run type-check --prefix ui-web`: passed.
- `uv run --no-sync ruff check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync ruff format --check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_source_language.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_large_files.py origin/main..HEAD`: passed.
- `git diff --check origin/main..HEAD`: passed.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No separate documentation or screenshot update was needed for this preset-list change.
## Risk
Existing explicit model and quality settings remain in effect. A saved Nano Banana 2 model is shown as a custom entry. When neither settings nor a tool argument supplies quality, GPT image variants other than GPT Image 2 now use the provider default instead of an implicit medium setting; output quality and cost may therefore change. No credentials, permissions or endpoints change. Revert this change to restore the prior list and implicit quality behavior.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Add GPT Image 2.5 Sunburst and Flare to the image model picker, with Sunburst selected when no model is configured. Remove Nano Banana 2 from the recommended list while retaining custom model entry.
Order presets by GPT Image 2.5 (Sunburst, Flare), GPT Image 2 (low, medium, high), Seedream (Lite, Pro), Qwen Image (3, 3 Pro), and Grok Image. Use provider-default quality for the new variants when no quality is supplied; retain the GPT Image 2 medium default and explicit settings precedence.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Python commands used UV_PROJECT_ENVIRONMENT=../raven/.venv; script checks also used PYTHONPATH=.
- `uv run --no-sync pytest tests/test_media_gen_tool.py -q -n0`: 64 passed.
- `npm test --prefix ui-web -- src/features/settings/SettingsPage.test.tsx`: 52 passed.
- `npm run type-check --prefix ui-web`: passed.
- `uv run --no-sync ruff check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync ruff format --check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_source_language.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_large_files.py origin/main..HEAD`: passed.
- `git diff --check origin/main..HEAD`: passed.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No separate documentation or screenshot update was needed for this preset-list change.
## Risk
Existing explicit model and quality settings remain in effect. A saved Nano Banana 2 model is shown as a custom entry. When neither settings nor a tool argument supplies quality, GPT image variants other than GPT Image 2 now use the provider default instead of an implicit medium setting; output quality and cost may therefore change. No credentials, permissions or endpoints change. Revert this change to restore the prior list and implicit quality behavior.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Clicking a .pptx in the workspace file view gave the binary note and an open-with
offer, which is nothing on a remote gateway. It now shows the deck: the gateway renders
the file to PDF and the viewer frames it, in the same unsandboxed frame that made
Chromium's PDF viewer work.
The cheap path first. A deck published by the engine already has its PDF beside it, so
when a .pdf sits next to the .pptx and is no older, that file is served and no
conversion runs. Otherwise the result is cached under the raven state directory, keyed
by resolved path, size and mtime, so a rebuilt deck re-renders and a second click is a
cache read. Only then does soffice run, headless with a throwaway profile, in its own
process group with a timeout that kills the group, and success is judged by whether the
output file appeared rather than by an exit code. One lock per key means a double click
never starts two conversions.
Failures are told apart rather than collapsed: no LibreOffice is 503, a timeout is 504,
a run that produced nothing is 500, and the reason reaches the pane as text the reader
can act on. The request goes through the same token URL and the same resolve_readable
fence as any other file, and only a .pptx may ask for a rendering.
## Type
- [x] Feature
## Verification
- `uv run --frozen pytest tests/test_rpc_transport.py tests/test_rpc_files.py -q` ->
51 passed, 11 of them new: the rendering and its headers, a cache hit, a stale mtime
re-rendering, the beside-PDF shortcut when newer and when older, a double click
converting once, no output as 500, a hang as 504 leaving no cache entry, no
LibreOffice as 503, a non-deck path as 400, and no session as 401
- `npm run type-check` and `npx vitest run` -> 1487 passed; `npm run build` succeeds
- Real check with a real deck and real soffice: an 8-page deck rendered cold in 2.9 s to
a PDF whose byte count matches the one the engine publishes, pdfinfo reports 8 pages,
a cache hit answers in 0.2 ms, and the beside-PDF path answers in 1.6 ms
- Clicked in full Chromium against a live gateway: both a deck with a PDF beside it and
a template without one open in the browser's own PDF viewer with page count, zoom and
thumbnails
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
New behaviour on a file kind that previously rendered nothing; a .pdf, an image and
every other kind are untouched. The conversion runs where the gateway runs and is
bounded by a timeout and a per-key lock. The cache lives under the state directory and
drops entries untouched for seven days. Rollback is the revert, and the cache directory
can be deleted.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Clicking a .pptx in the workspace file view gave the binary note and an open-with
offer, which is nothing on a remote gateway. It now shows the deck: the gateway renders
the file to PDF and the viewer frames it, in the same unsandboxed frame that made
Chromium's PDF viewer work.
The cheap path first. A deck published by the engine already has its PDF beside it, so
when a .pdf sits next to the .pptx and is no older, that file is served and no
conversion runs. Otherwise the result is cached under the raven state directory, keyed
by resolved path, size and mtime, so a rebuilt deck re-renders and a second click is a
cache read. Only then does soffice run, headless with a throwaway profile, in its own
process group with a timeout that kills the group, and success is judged by whether the
output file appeared rather than by an exit code. One lock per key means a double click
never starts two conversions.
Failures are told apart rather than collapsed: no LibreOffice is 503, a timeout is 504,
a run that produced nothing is 500, and the reason reaches the pane as text the reader
can act on. The request goes through the same token URL and the same resolve_readable
fence as any other file, and only a .pptx may ask for a rendering.
## Type
- [x] Feature
## Verification
- `uv run --frozen pytest tests/test_rpc_transport.py tests/test_rpc_files.py -q` ->
51 passed, 11 of them new: the rendering and its headers, a cache hit, a stale mtime
re-rendering, the beside-PDF shortcut when newer and when older, a double click
converting once, no output as 500, a hang as 504 leaving no cache entry, no
LibreOffice as 503, a non-deck path as 400, and no session as 401
- `npm run type-check` and `npx vitest run` -> 1487 passed; `npm run build` succeeds
- Real check with a real deck and real soffice: an 8-page deck rendered cold in 2.9 s to
a PDF whose byte count matches the one the engine publishes, pdfinfo reports 8 pages,
a cache hit answers in 0.2 ms, and the beside-PDF path answers in 1.6 ms
- Clicked in full Chromium against a live gateway: both a deck with a PDF beside it and
a template without one open in the browser's own PDF viewer with page count, zoom and
thumbnails
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
New behaviour on a file kind that previously rendered nothing; a .pdf, an image and
every other kind are untouched. The conversion runs where the gateway runs and is
bounded by a timeout and a per-key lock. The cache lives under the state directory and
drops entries untouched for seven days. Rollback is the revert, and the cache directory
can be deleted.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
All eight bundled templates were light and the selection prompt told the model not to
choose a dark style, so a request for a dark technology look had nowhere to go: it
landed on a light template and came out mixed. Two dark 16:9 templates cut from user
uploads join the catalogue, and the prompt now takes one when the request asks for a
dark, black or night look or a technology register.
Both templates went through one pipeline: drop the hidden vendor pages, strip the
vendor marks D32 asks for, then borrow the roles each one lacked. What to borrow was
measured rather than guessed. All 37 reference pages were cloned onto the dark masters
and rendered, and the ones that came back with white type pinned on a run over a pale
fill, or with flat artwork that does not follow the theme, were dropped. The black
circuit deck takes 14 borrowed pages (34 in all), the green aurora deck 11 (28 in all),
and each declares its own reference pages for other decks to borrow.
Three collision fixes ride along, all found with the extractor the gate itself uses
rather than the one a hand check reaches for first:
- The black deck's cover and agenda carried a two-layer title, the large English word
behind the Chinese one, measured at 53 and 46 percent. The English layer is gone and
the section numerals sit clear of their titles.
- On the investment-trend page the card titles were bottom-anchored, so a title that
wraps grows upward into the numeral row. They are top-anchored now, the title box is
budgeted against the numeral above and the body below, and titles of one, two and
three lines were rendered and measured. The green deck borrowed that page, so it had
the same defect and the same fix.
- gold_panel_year_end_summary holds a text box whose entire content is a single 12pt
period on five of its pages. Nothing shows -- a render before and after differs by 16
pixels out of 921,600 -- but the extractor sees a 3pt box inside a line of body copy
and reports up to 98 percent overlap, and word_collision refuses a deck. Any deck
cloning one of those pages was refused for a mark no reader can see. That template
goes from 17 blocking pairs to none.
The payload changed, so all ten files are uploaded as package version 2026.09.09 and
the manifest endpoint names it, which is what the manifest asks for: a new cut is a new
version rather than files replaced under the old one.
## Type
- [x] Feature
## Verification
- `uv run --frozen --extra dev pytest tests/test_ppt_engine_default_templates.py
tests/test_ppt_engine_templates.py tests/test_ppt_engine_skill.py -q` -> 92 passed
- `fetch_templates.py --verify` -> all 10 pins hold; and after emptying the assets
directory, `fetch_templates.py` refetched all ten from the registry and every pin held
- Collision sweep with `services.measure.words.words_from_pdf` over every page of both
dark templates and of gold_panel: no pair at or above 30 percent
- Every page of both templates was rendered and looked at, and the changed pages were
rendered again at 200 dpi and inspected as crops
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
Behaviour change: a brief asking for a dark or technology look now binds a dark
template instead of a light one. Decks that named a template by filename are unaffected.
The two dark templates carry Chinese placeholder copy like the other eight.
The manifest endpoint moved to 2026.09.09. A checkout that fetched templates before
this lands has the old bytes; `make fetch-templates` refreshes them. Rollback is the
previous endpoint and pins, and 2026.09.03 is still in the registry.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
All eight bundled templates were light and the selection prompt told the model not to
choose a dark style, so a request for a dark technology look had nowhere to go: it
landed on a light template and came out mixed. Two dark 16:9 templates cut from user
uploads join the catalogue, and the prompt now takes one when the request asks for a
dark, black or night look or a technology register.
Both templates went through one pipeline: drop the hidden vendor pages, strip the
vendor marks D32 asks for, then borrow the roles each one lacked. What to borrow was
measured rather than guessed. All 37 reference pages were cloned onto the dark masters
and rendered, and the ones that came back with white type pinned on a run over a pale
fill, or with flat artwork that does not follow the theme, were dropped. The black
circuit deck takes 14 borrowed pages (34 in all), the green aurora deck 11 (28 in all),
and each declares its own reference pages for other decks to borrow.
Three collision fixes ride along, all found with the extractor the gate itself uses
rather than the one a hand check reaches for first:
- The black deck's cover and agenda carried a two-layer title, the large English word
behind the Chinese one, measured at 53 and 46 percent. The English layer is gone and
the section numerals sit clear of their titles.
- On the investment-trend page the card titles were bottom-anchored, so a title that
wraps grows upward into the numeral row. They are top-anchored now, the title box is
budgeted against the numeral above and the body below, and titles of one, two and
three lines were rendered and measured. The green deck borrowed that page, so it had
the same defect and the same fix.
- gold_panel_year_end_summary holds a text box whose entire content is a single 12pt
period on five of its pages. Nothing shows -- a render before and after differs by 16
pixels out of 921,600 -- but the extractor sees a 3pt box inside a line of body copy
and reports up to 98 percent overlap, and word_collision refuses a deck. Any deck
cloning one of those pages was refused for a mark no reader can see. That template
goes from 17 blocking pairs to none.
The payload changed, so all ten files are uploaded as package version 2026.09.09 and
the manifest endpoint names it, which is what the manifest asks for: a new cut is a new
version rather than files replaced under the old one.
## Type
- [x] Feature
## Verification
- `uv run --frozen --extra dev pytest tests/test_ppt_engine_default_templates.py
tests/test_ppt_engine_templates.py tests/test_ppt_engine_skill.py -q` -> 92 passed
- `fetch_templates.py --verify` -> all 10 pins hold; and after emptying the assets
directory, `fetch_templates.py` refetched all ten from the registry and every pin held
- Collision sweep with `services.measure.words.words_from_pdf` over every page of both
dark templates and of gold_panel: no pair at or above 30 percent
- Every page of both templates was rendered and looked at, and the changed pages were
rendered again at 200 dpi and inspected as crops
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
Behaviour change: a brief asking for a dark or technology look now binds a dark
template instead of a light one. Decks that named a template by filename are unaffected.
The two dark templates carry Chinese placeholder copy like the other eight.
The manifest endpoint moved to 2026.09.09. A checkout that fetched templates before
this lands has the old bytes; `make fetch-templates` refreshes them. Rollback is the
previous endpoint and pins, and 2026.09.03 is still in the registry.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Brand marks for the third-party sub-agent roster landed with the desk palette's
grouped list and reached neither of the other two agent surfaces. This closes
both.
- The sub-agents page drew a coloured initial taken from the row's name, so
every agent was a letter in a tinted square.
- The conversation panel's flat instance list drew a status dot and nothing
saying which agent ran the row -- it has no agent headings, so the identity
was simply absent.
Both now render through the existing `AgentMark`, which means a preset gets its
vendor's mark and a row without a preset gets the generic glyph. Two decisions
worth stating:
**Keyed on the preset, never on the row's name.** A configured row's name is
the reader's to change, so a renamed agent keeps its brand, and a hand-written
row that merely spells itself like a preset gets none. What a row draws is a
fact about the package behind it.
**A row with no preset keeps the generic glyph** rather than an initial or a
raven mark. That covers the agents shipped under the product tree and anything
the reader wrote themselves; their names sit beside the mark and do the
distinguishing.
Enabling this needed one contract change: `SetupRow` declared its `tile` as a
boolean, which can ask for the letter tile or for nothing and cannot carry a
mark. It now takes a node, the same shape `SheetHead` already declared, so a
row and the sheet it opens can take the one mark. The predicate resolves
against `undefined` rather than truthiness, because "draw no tile" and "draw
the default tile" are different answers that a truthiness test reads as one.
All three existing call sites are unaffected: two pass nothing and keep the
letter tile, one passes `false` and keeps its tile-less grid.
`.pmtile` is sized per container, so a mark standing in for one takes that
container's geometry or it renders at its own roster default. Two containers
size a tile a mark can occupy: the roster row, whose grid also places the cell,
and the detail card's header at 46px against the row's 28px. Both are covered,
and a stylesheet contract reads the expected box off each tile's own rule
rather than restating it, so a slot whose tile is resized takes its mark with
it. That contract lives with the other stylesheet guards because no DOM test
can see this -- happy-dom applies no stylesheet, and the failure is silent: the
mark simply renders small. A mark drawn where no tile is sized, such as the
desk's roster head or an instance row, keeps the roster default and is correct
there.
### Checked and deliberately not changed
- **The desk palette's own instance children.** Their group head carries the
agent's mark two lines above them, so a per-child copy repeats it.
- **A numeric tile node.** `tile={0}` would take the tile-less grid and still
render the character. No call site does this and a number is not a mark; the
falsy-node path exists for `false` and `null`.
- **The panel's roster filter.** The conversation-side roster is filtered to
enabled agents, so the brand marks there become visible only once a
third-party agent is connected. That filter predates this change and is
deliberate; it is why the sub-agents page is where the change is immediately
visible.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All commands run at the rebased head.
Web unit tests, every test file this branch touches plus the two pre-existing
`SetupRow` consumers, whose contract it changes:
```
npx vitest run src/features/xa/XaPage.test.tsx \
src/features/subagents/SubagentsPage.test.tsx src/shell/agent-mark.test.tsx \
src/features/cron/CronPage.test.tsx src/features/connections/ConnPage.test.tsx \
scripts/agent-mark-css.test.mjs
-> Test Files 6 passed (6), Tests 232 passed (232)
```
That is the 225 those files held before, plus the 7 added here. The two
pre-existing setup-row consumers are in the list because this changes the
`SetupRow` contract.
All seven new tests are load-bearing, proven in two parts.
The six markup tests: reverting only the four source files to the base and
re-running turns all six red.
```
npx vitest run src/features/xa/XaPage.test.tsx \
src/features/subagents/SubagentsPage.test.tsx -t "brand"
-> Tests 6 failed | 134 skipped (140)
```
One of those six originally passed against the base, because "no brand mark" is
also true of a page that draws no marks at all. It now asserts the slot exists
and holds the generic glyph, which is what makes it fail without the fix.
The stylesheet contract: removing only the header's own mark rule, and nothing
else, turns it red naming the slot that lost its geometry.
```
-> AssertionError: .pmdhead sizes an agent mark too: expected +0 to be 1
```
The tree was restored after each and the suites re-run green.
Full web suite, compared by failing test ID against the base in a separate
clean worktree, both runs through the same interpreter:
```
npx vitest run --reporter=json
-> base: 1494 tests, 1129 passed, 365 failed
-> branch: 1501 tests, 1136 passed, 365 failed
-> newly failing: 0 tests lost: 0 new tests: 7
```
The 365 are pre-existing on this machine and identical as a set on both sides
(node 26 with happy-dom, where `localStorage` is undefined in several suites).
Counts alone would not have shown that, which is why the comparison is by ID.
Python gates, which is what the pipeline runs, plus the test reaching the module
the new base changed:
```
uv run --frozen --python 3.12 --all-extras pytest -q \
tests/test_ui_agent_marks.py tests/test_ui_css_token_gate.py \
tests/test_tool_params_cast.py
-> 61 passed
```
Type, contract, lint and repository gates:
```
npx tsc --noEmit -p tsconfig.json -> No errors found
npm run gen:check -> generated.ts matches the contract (162 methods)
node scripts/check-css.mjs -> OK (color literals confined to tokens)
uv run lint-imports -> Contracts: 9 kept, 0 broken
make check-source-language -> exit 0
make check-large-files -> exit 0
python scripts/check_commit_messages.py -> exit 0
```
`lint-imports`, the css gate and the whole web suite are not run by this
project's pipeline, so they were run locally.
The toolchain was confirmed to have read the edited files rather than another
checkout's copy, since the web dependency tree is shared:
```
npx tsc --noEmit -p tsconfig.json --listFiles | grep -E "setuprow|XaPage|SubagentsPage"
-> three absolute paths, all inside the branch's own tree
```
Rendered check, driven through a real browser against the built bundle, since
the stylesheet is where happy-dom sees nothing:
- Light and dark theme, sub-agents page, a roster covering every mark in the
table. Each third-party row draws its vendor's mark; the preset-less rows
draw the generic glyph.
- Dark theme is where the tone corrections matter, and they survive the new
size: the marks drawn in `currentColor` invert to readable, and the one mark
that pairs a brand colour with an adaptive tone keeps its green rather than
inverting to magenta.
- Measured geometry on the sub-agents page: every row mark 28 by 28 at the same
offset with the tile's corner radius, every name starting at the same
x whether or not the row has a preset, and no mark overflowing its row.
- Measured geometry on the detail card's header: 46 by 46 with the header's
corner radius, matching what that container sizes a letter tile to and
larger than the row mark that opens it.
- Measured geometry on the instance row: every mark 20 by 20 at the same
offset, no overflow.
Known gap in that last item: the conversation panel's instance list is fed by a
session-scoped source that a static page cannot populate, so its geometry was
measured on the component's own markup under the real stylesheet rather than
through the live store. The markup itself is pinned by the added test, which
drives the real component and asserts the resolved mark per row.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Nothing to update: no user-facing document describes the roster's marks, and
this coins no domain term, so there is no `CONTEXT.md` entry to add.
## Risk
Presentation only. No wire shape, stored value, guard or dispatch path changes,
and nothing new is written to disk.
The one shared piece is `SetupRow`, used by three pages. Its `tile` widens from
a boolean to a node with the previous two behaviours preserved exactly, so the
schedules page keeps its tile-less grid and the entrances page keeps its letter
tile; both are covered by their own suites in the run above.
Rollback is reverting the two commits; nothing persists and no migration is
involved.
- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Security is not applicable: no authentication, path resolution, credential or
network surface is touched.
## Related Issues
N/A
## Summary
Brand marks for the third-party sub-agent roster landed with the desk palette's
grouped list and reached neither of the other two agent surfaces. This closes
both.
- The sub-agents page drew a coloured initial taken from the row's name, so
every agent was a letter in a tinted square.
- The conversation panel's flat instance list drew a status dot and nothing
saying which agent ran the row -- it has no agent headings, so the identity
was simply absent.
Both now render through the existing `AgentMark`, which means a preset gets its
vendor's mark and a row without a preset gets the generic glyph. Two decisions
worth stating:
**Keyed on the preset, never on the row's name.** A configured row's name is
the reader's to change, so a renamed agent keeps its brand, and a hand-written
row that merely spells itself like a preset gets none. What a row draws is a
fact about the package behind it.
**A row with no preset keeps the generic glyph** rather than an initial or a
raven mark. That covers the agents shipped under the product tree and anything
the reader wrote themselves; their names sit beside the mark and do the
distinguishing.
Enabling this needed one contract change: `SetupRow` declared its `tile` as a
boolean, which can ask for the letter tile or for nothing and cannot carry a
mark. It now takes a node, the same shape `SheetHead` already declared, so a
row and the sheet it opens can take the one mark. The predicate resolves
against `undefined` rather than truthiness, because "draw no tile" and "draw
the default tile" are different answers that a truthiness test reads as one.
All three existing call sites are unaffected: two pass nothing and keep the
letter tile, one passes `false` and keeps its tile-less grid.
`.pmtile` is sized per container, so a mark standing in for one takes that
container's geometry or it renders at its own roster default. Two containers
size a tile a mark can occupy: the roster row, whose grid also places the cell,
and the detail card's header at 46px against the row's 28px. Both are covered,
and a stylesheet contract reads the expected box off each tile's own rule
rather than restating it, so a slot whose tile is resized takes its mark with
it. That contract lives with the other stylesheet guards because no DOM test
can see this -- happy-dom applies no stylesheet, and the failure is silent: the
mark simply renders small. A mark drawn where no tile is sized, such as the
desk's roster head or an instance row, keeps the roster default and is correct
there.
### Checked and deliberately not changed
- **The desk palette's own instance children.** Their group head carries the
agent's mark two lines above them, so a per-child copy repeats it.
- **A numeric tile node.** `tile={0}` would take the tile-less grid and still
render the character. No call site does this and a number is not a mark; the
falsy-node path exists for `false` and `null`.
- **The panel's roster filter.** The conversation-side roster is filtered to
enabled agents, so the brand marks there become visible only once a
third-party agent is connected. That filter predates this change and is
deliberate; it is why the sub-agents page is where the change is immediately
visible.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All commands run at the rebased head.
Web unit tests, every test file this branch touches plus the two pre-existing
`SetupRow` consumers, whose contract it changes:
```
npx vitest run src/features/xa/XaPage.test.tsx \
src/features/subagents/SubagentsPage.test.tsx src/shell/agent-mark.test.tsx \
src/features/cron/CronPage.test.tsx src/features/connections/ConnPage.test.tsx \
scripts/agent-mark-css.test.mjs
-> Test Files 6 passed (6), Tests 232 passed (232)
```
That is the 225 those files held before, plus the 7 added here. The two
pre-existing setup-row consumers are in the list because this changes the
`SetupRow` contract.
All seven new tests are load-bearing, proven in two parts.
The six markup tests: reverting only the four source files to the base and
re-running turns all six red.
```
npx vitest run src/features/xa/XaPage.test.tsx \
src/features/subagents/SubagentsPage.test.tsx -t "brand"
-> Tests 6 failed | 134 skipped (140)
```
One of those six originally passed against the base, because "no brand mark" is
also true of a page that draws no marks at all. It now asserts the slot exists
and holds the generic glyph, which is what makes it fail without the fix.
The stylesheet contract: removing only the header's own mark rule, and nothing
else, turns it red naming the slot that lost its geometry.
```
-> AssertionError: .pmdhead sizes an agent mark too: expected +0 to be 1
```
The tree was restored after each and the suites re-run green.
Full web suite, compared by failing test ID against the base in a separate
clean worktree, both runs through the same interpreter:
```
npx vitest run --reporter=json
-> base: 1494 tests, 1129 passed, 365 failed
-> branch: 1501 tests, 1136 passed, 365 failed
-> newly failing: 0 tests lost: 0 new tests: 7
```
The 365 are pre-existing on this machine and identical as a set on both sides
(node 26 with happy-dom, where `localStorage` is undefined in several suites).
Counts alone would not have shown that, which is why the comparison is by ID.
Python gates, which is what the pipeline runs, plus the test reaching the module
the new base changed:
```
uv run --frozen --python 3.12 --all-extras pytest -q \
tests/test_ui_agent_marks.py tests/test_ui_css_token_gate.py \
tests/test_tool_params_cast.py
-> 61 passed
```
Type, contract, lint and repository gates:
```
npx tsc --noEmit -p tsconfig.json -> No errors found
npm run gen:check -> generated.ts matches the contract (162 methods)
node scripts/check-css.mjs -> OK (color literals confined to tokens)
uv run lint-imports -> Contracts: 9 kept, 0 broken
make check-source-language -> exit 0
make check-large-files -> exit 0
python scripts/check_commit_messages.py -> exit 0
```
`lint-imports`, the css gate and the whole web suite are not run by this
project's pipeline, so they were run locally.
The toolchain was confirmed to have read the edited files rather than another
checkout's copy, since the web dependency tree is shared:
```
npx tsc --noEmit -p tsconfig.json --listFiles | grep -E "setuprow|XaPage|SubagentsPage"
-> three absolute paths, all inside the branch's own tree
```
Rendered check, driven through a real browser against the built bundle, since
the stylesheet is where happy-dom sees nothing:
- Light and dark theme, sub-agents page, a roster covering every mark in the
table. Each third-party row draws its vendor's mark; the preset-less rows
draw the generic glyph.
- Dark theme is where the tone corrections matter, and they survive the new
size: the marks drawn in `currentColor` invert to readable, and the one mark
that pairs a brand colour with an adaptive tone keeps its green rather than
inverting to magenta.
- Measured geometry on the sub-agents page: every row mark 28 by 28 at the same
offset with the tile's corner radius, every name starting at the same
x whether or not the row has a preset, and no mark overflowing its row.
- Measured geometry on the detail card's header: 46 by 46 with the header's
corner radius, matching what that container sizes a letter tile to and
larger than the row mark that opens it.
- Measured geometry on the instance row: every mark 20 by 20 at the same
offset, no overflow.
Known gap in that last item: the conversation panel's instance list is fed by a
session-scoped source that a static page cannot populate, so its geometry was
measured on the component's own markup under the real stylesheet rather than
through the live store. The markup itself is pinned by the added test, which
drives the real component and asserts the resolved mark per row.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Nothing to update: no user-facing document describes the roster's marks, and
this coins no domain term, so there is no `CONTEXT.md` entry to add.
## Risk
Presentation only. No wire shape, stored value, guard or dispatch path changes,
and nothing new is written to disk.
The one shared piece is `SetupRow`, used by three pages. Its `tile` widens from
a boolean to a node with the previous two behaviours preserved exactly, so the
schedules page keeps its tile-less grid and the entrances page keeps its letter
tile; both are covered by their own suites in the run above.
Rollback is reverting the two commits; nothing persists and no migration is
involved.
- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Security is not applicable: no authentication, path resolution, credential or
network surface is touched.
## Related Issues
N/A
## Summary
A sub-agent's direct chat drew its messages out of order and kept every step
behind a click. Both come from the shared transcript renderer, which a
delegated pane -- an instance's direct chat, a spawn record, a DAG node -- uses
through the same `history()` the conversation uses.
**Order.** That reader classifies the last thing the model said as the turn's
answer, and an answer is emitted past the turn's fold. On a settled record the
two coincide. They part company whenever a turn goes on working after speaking:
a narration line that introduced a tool call was drawn below the call. A running
turn is redrawn from its newest line on every poll, which made this the normal
case rather than an edge one -- the line the model had just written sat under
everything that came after it, and moved again two seconds later.
On a delegated lane the answer is now the model's last word rather than merely
the last thing it said. Any work after a text -- a tool row, or the message's
own tool calls -- makes that text narration, so it stays in the fold where it
was said; a text nothing follows still gets the answer row. Rows now only ever
append, which also removes the per-poll reshuffle.
**Fold.** The fold over a delegated turn is born open. That pane is one
sub-agent's work and its steps are what the reader opened it for. Every turn's,
not just the last, so `shutAutoFolds` stays on the live path. It is marked
`auto`, so the reader's own collapse takes it over and survives the next poll.
The conversation's own lane is deliberately unchanged: its live path does not go
through `history()` at all, so changing the replay would make it disagree with
what the reader had just watched. The divergence is stated at all three places
that now read `lane.main`.
Two things ride along with no behaviour of their own. Five comments described
the model as it read before this change and now say what it reads instead, one
of them a weight claim that needed a measurement rather than a rewording (it is
in Verification). And one word: the fold was briefly called a "trajectory" here,
which the renderer never calls it -- the segment is `kind: 'fold'`, built by
`collapse`, flipped by `toggleFold` -- and which CONTEXT.md already defines for
one task try under `raven/trajectory/`.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Baseline is a detached worktree at `origin/main` with `ui-web/node_modules`
symlinked; both runs are serial, because the one `--localstorage-file` this box
needs is shared by parallel workers and makes its own flakes.
```
# base and head, same command
NODE_OPTIONS=--localstorage-file=... npx vitest run --no-file-parallelism \
--reporter=json --outputFile=...
base: 1494 tests, 2 failed
head: 1498 tests, 2 failed
failing-ID diff: introduced NONE, fixed NONE
```
The two failures are the same pair on both sides: `deskStore` and `palette`'s
"when storage refuses" cases, which are unevaluable on this box -- with the flag
storage works where they need it to throw, and without it their file dies in
`beforeEach`. Neither imports the transcript module. An independent full run
of the same head in another environment came back 1498/1498, which is a second
environment confirming the pair is environmental rather than a property of this
change.
One existing test asserted that a delegated fold is born closed, which is the
behaviour this change reverses. Its subject is that the reader's own choice
survives a repaint, which still holds, so it now drives the reader closing an
open fold rather than opening a closed one.
```
make lint-ui # gen:check 162 methods match; tsc --noEmit clean
make check-large-files # clean
make check-source-language # clean
scripts/check_commit_messages.py origin/main..HEAD # clean
```
Four tests added, driven through the store rather than a fake, expressing the
rule as a flat render-order trace. Proven not to be theatre by reverse-applying
only the two logic hunks on the current head, comments left in place. Four go
red -- three of the four new ones, plus that re-pointed one. The fourth new
test ("the turn keeps its answer when the model has the last word") passes
either way by design: it pins the behaviour that must not change.
Replayed three real instance records off disk (7, 55 and 197 messages, the last
one two turns) through the delegated lane: every fold open, every narration line
above the calls it introduced, one answer row per turn.
Weight, measured because the comment justifying the shut default cites a number
(a forty-turn session building 7361 DOM nodes, 6400 of them in shut bodies).
Rendering the two largest instance records with every fold open: 55 messages in
one turn build 356 nodes against 103 shut, 197 messages in two turns build 738
against 334.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No docs entry: `ui-web/` has no CONTEXT.md, and CONTEXT-MAP.md lists no context
for it. Not screenshotted.
## Risk
User-visible, on delegated panes only:
- a turn whose text is followed by tool work no longer gets an answer row, so
that text loses the answer row's copy button and sits in the fold in its real
position instead. This falls out of ordering by payload rather than by
classification, and is why opening the fold by default matters;
- every turn's fold is open on opening such a pane, where one click used to be
needed per turn. Nothing caps that: it grows with the record at roughly four
nodes a message, so an instance kept for thousands of turns would reach the
figure the weight comment cites. The measurements above are an order of
magnitude under it, and the comment now says both.
The conversation's transcript is untouched, and so is every other lane
behaviour: the fold still holds one turn's steps, the reader's own toggles still
survive a repaint, and the live path still shuts the previous turn's fold.
Rollback is the two logic hunks: the `lane.main` guard inside `isFinal`, and
`born` in `collapse`. Reverting either alone is safe and independent.
Not fixed, and outside this change: `DirectTurn.steer` and `DirectTurn.interrupted`
are on the wire and documented as rows a reader should draw inside the turn
rather than as new ones, and the web renderer reads neither, so a steered
message opens a spurious question. No record on disk currently carries one.
## Related Issues
N/A
## Summary
A sub-agent's direct chat drew its messages out of order and kept every step
behind a click. Both come from the shared transcript renderer, which a
delegated pane -- an instance's direct chat, a spawn record, a DAG node -- uses
through the same `history()` the conversation uses.
**Order.** That reader classifies the last thing the model said as the turn's
answer, and an answer is emitted past the turn's fold. On a settled record the
two coincide. They part company whenever a turn goes on working after speaking:
a narration line that introduced a tool call was drawn below the call. A running
turn is redrawn from its newest line on every poll, which made this the normal
case rather than an edge one -- the line the model had just written sat under
everything that came after it, and moved again two seconds later.
On a delegated lane the answer is now the model's last word rather than merely
the last thing it said. Any work after a text -- a tool row, or the message's
own tool calls -- makes that text narration, so it stays in the fold where it
was said; a text nothing follows still gets the answer row. Rows now only ever
append, which also removes the per-poll reshuffle.
**Fold.** The fold over a delegated turn is born open. That pane is one
sub-agent's work and its steps are what the reader opened it for. Every turn's,
not just the last, so `shutAutoFolds` stays on the live path. It is marked
`auto`, so the reader's own collapse takes it over and survives the next poll.
The conversation's own lane is deliberately unchanged: its live path does not go
through `history()` at all, so changing the replay would make it disagree with
what the reader had just watched. The divergence is stated at all three places
that now read `lane.main`.
Two things ride along with no behaviour of their own. Five comments described
the model as it read before this change and now say what it reads instead, one
of them a weight claim that needed a measurement rather than a rewording (it is
in Verification). And one word: the fold was briefly called a "trajectory" here,
which the renderer never calls it -- the segment is `kind: 'fold'`, built by
`collapse`, flipped by `toggleFold` -- and which CONTEXT.md already defines for
one task try under `raven/trajectory/`.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Baseline is a detached worktree at `origin/main` with `ui-web/node_modules`
symlinked; both runs are serial, because the one `--localstorage-file` this box
needs is shared by parallel workers and makes its own flakes.
```
# base and head, same command
NODE_OPTIONS=--localstorage-file=... npx vitest run --no-file-parallelism \
--reporter=json --outputFile=...
base: 1494 tests, 2 failed
head: 1498 tests, 2 failed
failing-ID diff: introduced NONE, fixed NONE
```
The two failures are the same pair on both sides: `deskStore` and `palette`'s
"when storage refuses" cases, which are unevaluable on this box -- with the flag
storage works where they need it to throw, and without it their file dies in
`beforeEach`. Neither imports the transcript module. An independent full run
of the same head in another environment came back 1498/1498, which is a second
environment confirming the pair is environmental rather than a property of this
change.
One existing test asserted that a delegated fold is born closed, which is the
behaviour this change reverses. Its subject is that the reader's own choice
survives a repaint, which still holds, so it now drives the reader closing an
open fold rather than opening a closed one.
```
make lint-ui # gen:check 162 methods match; tsc --noEmit clean
make check-large-files # clean
make check-source-language # clean
scripts/check_commit_messages.py origin/main..HEAD # clean
```
Four tests added, driven through the store rather than a fake, expressing the
rule as a flat render-order trace. Proven not to be theatre by reverse-applying
only the two logic hunks on the current head, comments left in place. Four go
red -- three of the four new ones, plus that re-pointed one. The fourth new
test ("the turn keeps its answer when the model has the last word") passes
either way by design: it pins the behaviour that must not change.
Replayed three real instance records off disk (7, 55 and 197 messages, the last
one two turns) through the delegated lane: every fold open, every narration line
above the calls it introduced, one answer row per turn.
Weight, measured because the comment justifying the shut default cites a number
(a forty-turn session building 7361 DOM nodes, 6400 of them in shut bodies).
Rendering the two largest instance records with every fold open: 55 messages in
one turn build 356 nodes against 103 shut, 197 messages in two turns build 738
against 334.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No docs entry: `ui-web/` has no CONTEXT.md, and CONTEXT-MAP.md lists no context
for it. Not screenshotted.
## Risk
User-visible, on delegated panes only:
- a turn whose text is followed by tool work no longer gets an answer row, so
that text loses the answer row's copy button and sits in the fold in its real
position instead. This falls out of ordering by payload rather than by
classification, and is why opening the fold by default matters;
- every turn's fold is open on opening such a pane, where one click used to be
needed per turn. Nothing caps that: it grows with the record at roughly four
nodes a message, so an instance kept for thousands of turns would reach the
figure the weight comment cites. The measurements above are an order of
magnitude under it, and the comment now says both.
The conversation's transcript is untouched, and so is every other lane
behaviour: the fold still holds one turn's steps, the reader's own toggles still
survive a repaint, and the live path still shuts the previous turn's fold.
Rollback is the two logic hunks: the `lane.main` guard inside `isFinal`, and
`born` in `collapse`. Reverting either alone is safe and independent.
Not fixed, and outside this change: `DirectTurn.steer` and `DirectTurn.interrupted`
are on the wire and documented as rows a reader should draw inside the turn
rather than as new ones, and the web renderer reads neither, so a steered
message opens a spurious question. No record on disk currently carries one.
## Related Issues
N/A
## Summary
A conversation the reader is not looking at loses its graph and hides what it needs.
Both halves have the same cause: live events reach the page only for the conversation
on screen, and there was no other way for one to say anything.
**The graph.** `rpc.notify.event` drops a `dag.*` event for any other conversation
unless a parked-turn buffer exists, and `parkTurn` builds one only while that turn is
busy. A graph outlives the turn that started it, so most node reports arrive when no
buffer is there. The disk-based recovery already existed and could not run: `resumeDag`
refused unless `sessionStorage` held a note naming the run, and that note is written
only once a live event has been applied, so it is absent exactly for a graph that
started while the reader was elsewhere. `dag.get` answers such a run correctly,
unfinalized ones included, and was never asked.
The run to read is now resolved from three sources, ordered by how current each can be:
the graph already on screen, then the stored note, then the run ids the transcript
carries, which `session.resume` already stamps onto the row that started each graph.
The note keeps its rank above the transcript because it is the only one of the two
carrying a preference; a reader watching the first of two graphs is not moved onto the
second by a reload.
`mount.resume` also stops declining a conversation whose sheet is still up, which is
the case with no reload at all: the reader leaves, node reports are dropped, and the
sheet they return to is as stale as the moment they left. A read of the same run is
applied to it; only a different run is declined, the live one then being the newer.
Whether a conversation should be read at all moved to the caller. The parked path in
`sessionOpen` takes the graph half of this and not the desk half, because its windows
are still open and replaying them would give the reader each one twice.
**The notice.** An approval, confirm or clarify raised elsewhere rendered nothing
anywhere: its sheet mounts only on its own conversation, the repaints were skipped, and
the row's status vocabulary had no word for it. The row now carries an asking state that
outranks running, since a blocked conversation still has a turn open. It clears when the
wait ends and when the reader opens the conversation.
Its mark is a disc inside a halo, which is neither of the shapes already taken: a bare
disc is running and a bare ring is finished. The first revision of this branch wrote the
state without writing its mark, so the row rendered a transparent dot over the timestamp
that the same selector hides -- less than a row with no state at all, with only the ARIA
label correct. The stylesheet check added with the fix derives the state set from the
component's own tail line rather than listing it, because listing would repeat that
omission for the next state added; it also covers running, finished and failed, none of
which had been asserted to paint either.
**What this does not do.** It does not make a pending request survivable. The approval
ceiling is 30 seconds visible and 35 in total, fixed where the broker is built; nothing
re-sends a request that is still pending; and a disconnect fails every pending one
closed. A reader who looks 40 seconds later still finds it gone. Making the request
itself recoverable needs the server to publish what is pending, which is deliberately
not in this change. The event drop is also left in place: this reads the gateway again
on open rather than replaying what was missed, so the reader gets current state and not
the transitions in between.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
The second commit is a `feat` and is described above; the branch as a whole is a fix.
## Verification
Sixteen tests added, five of them written failing first. Each fix was shown to be
load-bearing by breaking it again: reverting the `refreshDag` error guard reddens its one
test, removing the parked path's re-read reddens the assembled harness assertion, and
deleting the asking mark's rule reddens three of the stylesheet check's four cases.
```
npx vitest run --no-file-parallelism 1507 passed, 2 failed of 1509, 0 unhandled
npm run type-check --prefix ui-web clean
npm run type-check --prefix ui-tui clean
npm run build --prefix ui-web built, 564.82 kB
npm run gen:check --prefix ui-web generated.ts matches the contract
node ui-tui/scripts/gen-i18n.mjs --check generated catalogue is up to date
scripts/check_source_language.py exit 0
scripts/check_large_files.py exit 0
scripts/check_commit_messages.py exit 0
pytest tests/test_i18n_boundary.py tests/test_i18n_prompts.py 6 passed
```
Zero failures introduced: failing test ids were captured on `origin/main` and on this
branch and the sets diffed, rather than the counts compared.
Three signals are read, because no one of them is sufficient here, and an earlier run of
this branch's own verification proved it: an unhandled `TypeError` out of an assembled
harness under `ui-web/scripts/` is not an assertion failure, so `numFailedTests` stayed
zero and a suite with a broken seam read as green. The exit code alone is no better,
since the two remaining failures make it nonzero on a good run. So the exit code,
`numFailedTests`, and the unhandled-error count are all read; the last is now zero.
Those two remaining failures, `deskStore.test.ts` and `palette.test.ts` under `when
storage refuses`, are red on `origin/main` too and are unevaluable on this machine in
either configuration. Node 26 ships an experimental `localStorage` that is `undefined`
without `--localstorage-file` and shadows the one happy-dom installs, which fails about
365 tests across 65 suites at any revision; supplying the flag fixes those and makes the
two storage-refusal tests fail instead, because they need storage to throw. That flag
names one file shared by every worker, so the suite must also run with
`--no-file-parallelism` or three storage-touching suites flake in rotation. No CI job
runs this suite, which is how the 365 went unnoticed.
- [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 unchecked deliberately: the asking state is a visible change to the
session rail and no screenshot is attached. The string itself is in the shared
catalogue in both locales.
## Risk
Behaviour changes a reader can see. Reopening a conversation now asks the gateway for
its graph in cases where it previously asked for nothing, so a sheet appears where none
used to. A sheet already up is refreshed rather than left alone, so its node states can
change on reopen; that is the point, and the reader's fold is preserved across it. A row
gains a fourth state, drawn as a new mark in a slot that previously held three.
Confirm is the one lane whose badge can outlive its request: its broker times out and
answers with its default without sending any frame, where approval and clarify both
close themselves. Opening the conversation clears it, which is what the badge asks for,
so the stale window is bounded by the one action it prompts.
Rollback is a revert. The change adds one exported verb and one status value and alters
no wire contract, no stored format and no server behaviour; reverting restores the
previous resolution order and the previous three-state row.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
A conversation the reader is not looking at loses its graph and hides what it needs.
Both halves have the same cause: live events reach the page only for the conversation
on screen, and there was no other way for one to say anything.
**The graph.** `rpc.notify.event` drops a `dag.*` event for any other conversation
unless a parked-turn buffer exists, and `parkTurn` builds one only while that turn is
busy. A graph outlives the turn that started it, so most node reports arrive when no
buffer is there. The disk-based recovery already existed and could not run: `resumeDag`
refused unless `sessionStorage` held a note naming the run, and that note is written
only once a live event has been applied, so it is absent exactly for a graph that
started while the reader was elsewhere. `dag.get` answers such a run correctly,
unfinalized ones included, and was never asked.
The run to read is now resolved from three sources, ordered by how current each can be:
the graph already on screen, then the stored note, then the run ids the transcript
carries, which `session.resume` already stamps onto the row that started each graph.
The note keeps its rank above the transcript because it is the only one of the two
carrying a preference; a reader watching the first of two graphs is not moved onto the
second by a reload.
`mount.resume` also stops declining a conversation whose sheet is still up, which is
the case with no reload at all: the reader leaves, node reports are dropped, and the
sheet they return to is as stale as the moment they left. A read of the same run is
applied to it; only a different run is declined, the live one then being the newer.
Whether a conversation should be read at all moved to the caller. The parked path in
`sessionOpen` takes the graph half of this and not the desk half, because its windows
are still open and replaying them would give the reader each one twice.
**The notice.** An approval, confirm or clarify raised elsewhere rendered nothing
anywhere: its sheet mounts only on its own conversation, the repaints were skipped, and
the row's status vocabulary had no word for it. The row now carries an asking state that
outranks running, since a blocked conversation still has a turn open. It clears when the
wait ends and when the reader opens the conversation.
Its mark is a disc inside a halo, which is neither of the shapes already taken: a bare
disc is running and a bare ring is finished. The first revision of this branch wrote the
state without writing its mark, so the row rendered a transparent dot over the timestamp
that the same selector hides -- less than a row with no state at all, with only the ARIA
label correct. The stylesheet check added with the fix derives the state set from the
component's own tail line rather than listing it, because listing would repeat that
omission for the next state added; it also covers running, finished and failed, none of
which had been asserted to paint either.
**What this does not do.** It does not make a pending request survivable. The approval
ceiling is 30 seconds visible and 35 in total, fixed where the broker is built; nothing
re-sends a request that is still pending; and a disconnect fails every pending one
closed. A reader who looks 40 seconds later still finds it gone. Making the request
itself recoverable needs the server to publish what is pending, which is deliberately
not in this change. The event drop is also left in place: this reads the gateway again
on open rather than replaying what was missed, so the reader gets current state and not
the transitions in between.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
The second commit is a `feat` and is described above; the branch as a whole is a fix.
## Verification
Sixteen tests added, five of them written failing first. Each fix was shown to be
load-bearing by breaking it again: reverting the `refreshDag` error guard reddens its one
test, removing the parked path's re-read reddens the assembled harness assertion, and
deleting the asking mark's rule reddens three of the stylesheet check's four cases.
```
npx vitest run --no-file-parallelism 1507 passed, 2 failed of 1509, 0 unhandled
npm run type-check --prefix ui-web clean
npm run type-check --prefix ui-tui clean
npm run build --prefix ui-web built, 564.82 kB
npm run gen:check --prefix ui-web generated.ts matches the contract
node ui-tui/scripts/gen-i18n.mjs --check generated catalogue is up to date
scripts/check_source_language.py exit 0
scripts/check_large_files.py exit 0
scripts/check_commit_messages.py exit 0
pytest tests/test_i18n_boundary.py tests/test_i18n_prompts.py 6 passed
```
Zero failures introduced: failing test ids were captured on `origin/main` and on this
branch and the sets diffed, rather than the counts compared.
Three signals are read, because no one of them is sufficient here, and an earlier run of
this branch's own verification proved it: an unhandled `TypeError` out of an assembled
harness under `ui-web/scripts/` is not an assertion failure, so `numFailedTests` stayed
zero and a suite with a broken seam read as green. The exit code alone is no better,
since the two remaining failures make it nonzero on a good run. So the exit code,
`numFailedTests`, and the unhandled-error count are all read; the last is now zero.
Those two remaining failures, `deskStore.test.ts` and `palette.test.ts` under `when
storage refuses`, are red on `origin/main` too and are unevaluable on this machine in
either configuration. Node 26 ships an experimental `localStorage` that is `undefined`
without `--localstorage-file` and shadows the one happy-dom installs, which fails about
365 tests across 65 suites at any revision; supplying the flag fixes those and makes the
two storage-refusal tests fail instead, because they need storage to throw. That flag
names one file shared by every worker, so the suite must also run with
`--no-file-parallelism` or three storage-touching suites flake in rotation. No CI job
runs this suite, which is how the 365 went unnoticed.
- [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 unchecked deliberately: the asking state is a visible change to the
session rail and no screenshot is attached. The string itself is in the shared
catalogue in both locales.
## Risk
Behaviour changes a reader can see. Reopening a conversation now asks the gateway for
its graph in cases where it previously asked for nothing, so a sheet appears where none
used to. A sheet already up is refreshed rather than left alone, so its node states can
change on reopen; that is the point, and the reader's fold is preserved across it. A row
gains a fourth state, drawn as a new mark in a slot that previously held three.
Confirm is the one lane whose badge can outlive its request: its broker times out and
answers with its default without sending any frame, where approval and clarify both
close themselves. Opening the conversation clears it, which is what the badge asks for,
so the stale window is bounded by the one action it prompts.
Rollback is a revert. The change adds one exported verb and one status value and alters
no wire contract, no stored format and no server behaviour; reverting restores the
previous resolution order and the previous three-state row.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
A raven installed by `install.sh` listed Raven-Design and Raven-PPT in the roster and
could dispatch to neither.
Discovery reads the `engine` block in each `agents/<product>/subagent.json` and sets the
row's `enabled` from whether that package is importable where raven runs, so a product
whose distribution is absent is listed and disabled. Nothing in any automated path
installed those two distributions: `install.sh` carries only the `everos-memory` plugin,
and a product's own `install.py` registers a roster row without touching its
distribution. The refusal text says to install the engine "where raven is installed" and
names no command, so the remedy was stated nowhere the installer ran.
This is the split the layering intends -- `everos-memory` is the host's own memory
backend, the other two are product harnesses -- but the products ship in the same
repository and the same release, and no other step picks them up.
Four changes:
- Source mode carries both engines beside the memory plugin.
- The degradation ladder gains a rung between them, on both the source and the release
path. The engines pull native builds (PDF, raster, plotting) that a platform can refuse
on its own; losing long-term memory to a failed PDF rasteriser is the wrong trade, so
the engines fall first and the memory plugin is dropped only if it fails on its own.
The engine requirements live in their own variable for that reason: sharing one with
the memory plugin makes the first engine that cannot build take everos-memory with it.
- The plugin directories are passed as positional parameters, not encoded into a string.
sh has no arrays, and an option/path pair in a scalar is split on every space, so a
checkout path holding one loses all three plugins and the ladder ends at bare raven
reporting success.
- Release mode resolves the two wheels from the release assets the way it already
resolves `everos-memory`, and the release workflow builds them so those assets exist.
An absent wheel stays a warning rather than a failure: the release still installs and
the two rows stay disabled the way discovery already reports them.
- The Windows installer gets the same two, in both of its modes. It mirrors the shell one
and carried no plugin arguments at all, so a Windows install reached exactly the state
described above. Its wheel resolver reads the release object the raven-wheel lookup
already fetched rather than calling the API again, because unauthenticated callers get
60 requests per hour per IP and the script's own comment says a shared egress can
exhaust that.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Source mode, end to end on Linux, against a wiped `~/.raven` and `~/.everos`:
- Before, on the unpatched script: `raven 0.1.13`, `everos-memory 1.2.0`,
`design-engine NOT installed`, `ppt-engine NOT installed`.
- After: `raven 0.1.13`, `everos-memory 1.2.0`, `design-engine 0.2.0`, `ppt-engine 0.2.0`,
and `raven_everos` / `raven_design` / `raven_ppt` all resolve under the installed
interpreter -- the probe discovery itself runs.
- The roster verdict is the assertion that matters. Driving the discovery scan directly,
all five products now report `ready=True`; before the change, Raven-Design and Raven-PPT
reported `ready=False` with "the design-engine engine wheel is not installed in this
raven's environment" and the ppt-engine equivalent.
Both degradation properties were driven rather than argued, each against the failure it
exists for:
- A checkout path containing a space: the source ladder's first rung builds eleven argv
entries with each of the three plugin directories intact as one argument. Encoding the
pairs into a scalar had produced fourteen, splitting every path in half. The
no-plugin rung still expands cleanly under `set -u`.
- A release install where only `design-engine` fails to resolve: three invocations, the
third carrying `everos-memory` and succeeding. Sharing one variable had made that third
invocation carry no plugin at all.
The Windows installer needs neither fix and was checked for both: its plugin list is a
real array, so splatting keeps a spaced path one argument (verified on 7.6.5 with a path
containing a space), and it carries no memory plugin to lose.
PowerShell, driven rather than read, on 7.6.5:
- The whole file parses clean through `Parser::ParseFile`.
- The new wheel resolver was extracted and driven over four states: no cached release
(the API failed, or the release-page fallback ran) returns null; a release carrying
both engine wheels returns each; a release carrying only the raven wheel -- which is
what the current latest release is -- returns null for both; and a release carrying
only an engine sdist returns null rather than handing uv a tarball.
- Empty-array splatting was driven too, since it is the analogue of the bash hazard
below: `@cArgs @pArgs` with both empty passes one argument, not three.
- Every one of the six `& $UvPath tool install` calls reads `$LASTEXITCODE` back on the
next line. `$ErrorActionPreference` does not cover native commands and
`$PSNativeCommandUseErrorActionPreference` is still False by default at 7.6.5, so a
failed uv would otherwise return to the caller and the script would report success.
Not run: no Windows machine was available, so the PowerShell half is verified by parse,
by driving the new function, and by the exit-code audit -- not by an install.
Shell portability, because the script is `#!/bin/sh` with `set -eu` and the reviewed
hazard is a bash-only construct reaching a POSIX shell:
- `sh -n install.sh` and `dash -n install.sh` both clean. The added helper uses
positional parameters only -- no arrays, no `local`, no `+=`.
- The ladder's control flow was driven rather than read: under `sh -eu`, a helper
returning non-zero inside `if !` falls through to the next rung instead of aborting,
and the success path returns without entering it.
Other gates:
- `python3 -c "import yaml; yaml.safe_load(...)"` over the release workflow: parses.
- `scripts/check_commit_messages.py origin/main..HEAD`: exit 0.
- `uv run --all-extras pytest tests/test_install_script.py
tests/test_constraints_export_contract.py tests/test_cli_onboard_commands.py`:
321 passed.
- Python unit suite: `8422 passed, 1 failed`. The failure,
`test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`, is
pre-existing and environment-dependent, not introduced here: it fails identically at
the merge base in a separate detached worktree (same file, same line, same assertion),
and it passes on this branch under `COLUMNS=200`. It is a rich-wrapping width
assertion. The change adds no Python; it is shell, PowerShell and CI configuration.
Not run: `shellcheck` is not installed in the environment this was written in, so the
`# shellcheck disable=SC2086` directive on the helper is unverified by the tool itself.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Behaviour change for every source install: two more distributions land in the tool
environment, and `ppt-engine` pulls native builds. That is why the ladder gained a rung
rather than extending the existing plugin argument -- an engine that cannot build on a
platform now costs that platform its two product rows and nothing else, where a naive
extension would have cost it long-term memory as well.
Release mode is inert until a release carries the wheels. The current latest release
carries none, including no `everos-memory` wheel, so the two new warnings will fire
alongside the existing memory-plugin warning until the next release is cut from the
updated workflow.
Rollback is the revert: without these lines the installer behaves exactly as before, and
the two rows return to being listed and disabled.
Windows carries a specific risk the other platforms do not. `cairosvg` and `cairocffi`
are pure-python wheels that load a system libcairo at runtime, and a stock Windows
machine does not have it, so the deck engine can install and then fail to render. Every
other native dependency of the two engines has Windows wheels on PyPI (`pymupdf`,
`pypdfium2`, `matplotlib`, `pillow`), and `python-pptx` is pure python. That is the
reason the ladder drops the engines a rung before raven itself rather than failing the
install.
Disclosed, not fixed. `everos-memory` is absent from the Windows installer and stays
absent: it was never carried there, and whether EverOS belongs on Windows is a separate
question from closing the roster gap. So a Windows install still boots memoryless and
`raven doctor` explains why, exactly as before this change.
The deck engine has a second manual step this change does not address: its templates are
not in git and are fetched separately after cloning.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Reported as "deliver_files is broken". It is not: **the tool never ran.**
Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:
```
Error: Invalid parameters for tool 'deliver_files': files should be array
```
What the model sent was the array, spelled as a string:
```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```
`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.
## Type
- [x] Fix
- [ ] Feature
## The edge of the forgiving is the design
When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.
**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.
**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.
## Not just deliver_files
Six built-in tools declare an array or object parameter and were all exposed:
| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |
The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.
## Verification
```
make lint-python ruff check + ruff format --check, 1850 files
make lint-imports 9 contracts kept, 0 broken
pytest tests/ 19,699 passed, 7 failed (all pre-existing, see below)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string
**End to end, through the real tool**, with the exact payload that failed five times in production:
```
files sent as: str -> [{"path": ".../poster.png", "title": "..."}]
returned: Delivered 1 file(s): poster.png (72 B).
still "should be array": False
registered in the store: True
```
Twelve cases, five mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |
The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.
**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.
## Risk
- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.
- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.
Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).
## Deliberately not fixed
The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.
## Moved from !594
Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.
Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
## Summary
Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:
- Navigation: every screen opens with a help area under its title (page
purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
sentinel can never reach a conversion or the data layer; a cancelled
report keeps its pre-confirm bundle-and-pin side effects (the existing
declined-report contract). Back/Exit menu entries are gone; answered
prompts erase themselves and navigation is echoed as breadcrumb lines
with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
drops as a whole column when it no longer fits, and below the dynamic
minimum width the tightest layout is kept while the renderer clips
overlong lines at the terminal edge. Every dynamic cell passes a
single-line sanitization gate before width math (verdict sidecars only
guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
passes the terminal's CPR reply through to the renderer instead of
treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
(advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
laggy Esc feel.
The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The interactive browser's look and key protocol change wholesale (that
is
the point of this PR): Esc no longer quits from the top level (Ctrl+C
does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
interaction wholesale, no data migration involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.
1. A sub-agent's result relay into a page session ran on the gateway spine while the
page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
at once: the same tool calls were drawn twice and the result delivered twice, and
`turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
`raven.gateway.submit_router.route_submit` hands turns whose conversation carries
the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
The sub-agent manager and the deep-research submit both take the routed callable;
a gateway without a page keeps the gateway submit unchanged.
2. The watch-work judgement (one model call on a turn's first look) was paid on relay
and sentinel turns, whose "last user message" is the runtime's re-injected report,
and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
reads as no request, and the judgement is cut at 60 seconds and treated as no
verdict. CRON and heartbeat turns are deliberately still judged: their text is the
owner's own instruction.
3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
was mid-conversation with rendered to the main agent as "no turns yet"; the model
read that as free and spawned onto it. The handoff now reads the manager's live
direct turns (`live_direct_turns`) and renders an answering instance with the time
it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
behind such a turn no longer writes `running` before it holds the handle lock (it
stays the `pending` it was announced as), and no longer takes over the instance's
live view: `activity.watching_instance` registers only when the slot is free and
pops only what it registered, so the direct chat's steps stay on screen and the
spawn's appear once it runs.
4. When reasoning ran to the model's output ceiling with no content and the
empty-response recovery fed it back as a prefill, the continuation opened on the
rest of the cut thought and that fragment streamed and was stored as the head of the
answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
whitespace and ends at the first sentence or line boundary within 200 characters;
`ContinuationGate` holds streamed deltas until the same rule can decide, so what the
reader sees matches what the session stores. Only a continuation after
ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.
Decisions worth knowing:
- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
`RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
importing `raven.rpc`, so a test holds the two equal instead of one importing the
other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
moved (after the handle lock). The page's spawn card reads identity from `pending`
and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
source-language gate reads the literal marks as non-English source.
Review round 1 (all findings non-blocking, all taken):
- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
method, the rpc spine and the submit router call it, and the router test pins the
identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
`DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
The enclosing handler already kept the turn alive, but left the verdict unset, so a
failing judgement was paid again on every path-touching tool call; the comment that
claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
whole (no case, so no mid-sentence signal); the comment and a test now say that the
CJK stops end an admitted fragment rather than open one.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
-> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
-> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests -> clean
uv run lint-imports -> 9 kept, 0 broken
make check-source-language -> exit 0
scripts/check_commit_messages.py origin/main..HEAD -> exit 0
```
Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.
Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
Handoff Block)
## Risk
- A relay into a page session now waits behind the page's running turn on that session
instead of running beside it. That is the intended serialisation; the cost is latency
on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
that turn only; before, the same turn hung. No configuration knob: the bound is a
class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
continuation whose intended answer begins with a lowercase word and a full stop within
200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.
- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
page mount is unaffected)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A