<img width="2318" height="1448" alt="image"
src="https://github.com/user-attachments/assets/bca71d69-4972-420c-b14e-c8cf74a17de9"
/>
## Summary
Everything a knowledge base could not read, and the pieces it cut them
into
saying what they are.
**Reading a PDF.** A PDF records glyphs at coordinates; whether they are
a
heading, a table cell or a running footer is inferred from how they
look. There
are now two readers. The geometric one infers structure from type size
and
position and needs nothing but the file. The other asks deepdoc's
models, ported
into `raven/knowledge/parser/deepdoc`: a layout model that says what
each region
is, a detector and recognizer that read a page carrying no text at all,
and a
table-structure model that rebuilds a grid from a picture of one.
Detecting boxes around text the file already spells
out exactly costs an inference pass per page to learn less, and
recognising it
costs accuracy.
The layout graph answers with a shape its own postprocessing
raises on, and its classes are DocLayout-YOLO's order rather than the
list
Both were established by running the model, and the label order is
pinned by a test.
**Tables go in as tables.** `<table>` is the only shape that keeps what
a grid
states -- which column a cell stood under, which cells are merged, which
row is
the header -- and it is the shape a model reads a table in, which is
what these
chunks are for. PDF, Word and PowerPoint all state their merges exactly,
and
they now survive as `colspan` and `rowspan`. The flat form this replaces
had to
repeat a header standing over two columns across both of them, because
there was
nowhere to record a span; it had no callers left afterwards and is gone.
Two
deviations from upstream, both about what the string is for: every
cell's text
is escaped, where upstream interpolates it raw and a cell holding a `<`
produces
markup that is no longer a table, and the span attributes are written
only where
there is a span, where upstream emits `<td >` for every ordinary cell.
**A picture of where each chunk came from.** A chunk is a few hundred
words with
a page number on it, which is enough to cite and not enough to answer
whether
the parser read the page correctly. So every PDF chunk that knows where
it sits
carries one image: the regions it covers, cropped out of the rendered
pages and
stacked. here they are already structured in the parser's element spans,
so
the markers would only put text nobody wrote into the thing being
embedded.
The panel draws a chunk's tables as tables, parsed and
rebuilt as elements rather than injected: a person can rewrite any piece
from
that same panel, so what comes back from the store is user input however
it got
there.
**The page that reads them.** Upstream retired the knowledge page while
this
branch was out; it is rebuilt against the new architecture, and the half
that
never existed is the one a reader needs -- what a document actually
became once
it was cut and embedded. Documents sit in one-level folders and arrive
by four
routes: a file, a folder, a URL, a written note. Adding and indexing are
two
calls on the contract and nothing drains that queue on its own, so a
page that
stopped after the first left every upload saying Queued for good.
Opening a file takes the whole page: the document on the left, the
pieces the
index holds of it on the right. The left half is the file drawn as its
own
pages rather than framed by the browser's PDF viewer, which reads where
to open
once and answers to nothing afterwards -- and which nothing can be drawn
on.
Pages are rendered once and kept, and the region a piece was cut from is
washed
over the page it came from, placed in fractions of the page so the
picture's
own scale never enters the arithmetic. Clicking a piece takes the file
there;
double-clicking opens it for rewriting.
The pieces can be searched, filtered by state, turned on and off,
deleted,
rewritten and added to, one at a time or in a batch. Every one of those
was
already on the contract with no reader for it. A base's settings are
back and
fuller: how many pieces a search returns, how documents are cut, and how
much
prose comes with a table or a figure. The embedding model is a picker
while the
base holds no pieces and a stated fact once it does -- moving it then is
the
collection made again at the new width and every document re-cut, which
is not
a thing a panel does by being saved.
**An agent can read them.** The retrieval engine was there and nothing
could
reach it: no agent had a tool that opened a library. A reader now points
a
conversation at bases from the composer, the way they pin a working
directory,
and the selection rides in the same place -- the session's metadata,
bound
around the turn.
The tool takes a query and never a base. The scope is the reader's
choice, so a
model cannot reach material nobody offered it, and it is withheld where
nothing
was picked rather than offered and refused. A hit says which document
and page
it came from, because a hit a reader cannot place is a hit they cannot
check --
and the passages are pressable in the transcript, walking into the base,
the
document, the folder it is filed under and then the piece. A citation a
reader
cannot follow is a claim they have to take on trust, and the whole point
of
searching their own material is that they can go and look.
**The word segmenter and the resources.** `raven.core.Tokenizer` is
Infinity's
`rag_tokenizer`, ported: a forward and backward maximum match over a
dictionary
trie, with stemming and lemmatisation on the latin path. XGBoost is not
carried
over. None of the data lives in git -- the dictionary, the NLTK corpora
and the
ONNX graphs run to about a hundred megabytes, so `make fetch-resources`
on an
install and an optional Docker layer behind `RAVEN_RESOURCES` both point
at one
script. A checkout that could not reach the network still works, and
every
feature that reads this data says so when asked.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on macOS against Python 3.12, with the deepdoc weights fetched (the
model
tests skip without them):
```
uv run pytest 27450 passed, 111 skipped, 3 failed
npm run test --prefix ui-web 3276 passed
npm run test --prefix ui-tui 2106 passed
npm run type-check --prefix ui-web clean (tsc)
npm run lint --prefix ui-web clean (4 pre-existing hook warnings)
make lint-python clean (ruff check + format)
make lint-types clean (ty)
make lint-imports 10 contracts kept, 0 broken
make check-source-language clean
make check-large-files clean
make build-ui built, both boot snapshots match
node ui-web/scripts/check-css.mjs clean
node ui-web/scripts/check-class-namespace.mjs clean
```
The three Python failures are not this branch's and were each confirmed
on the
base alone: one asks a host without LibreOffice to refuse a render and
this host
has LibreOffice installed, and two simulation cases fail on an
unmodified
checkout of the base commit.
The RPC contract was regenerated for both consumers and both match it
(`npm run gen --prefix ui-web`, `npm run gen:rpc --prefix ui-tui`, then
`gen:check`). The page's boot snapshots and region goldens were
refreshed where
the composer bar gained a button, and each records that button and
nothing else.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
A PDF's tables, and a Word or PowerPoint file's, are now indexed as HTML
rather
than as header-prefixed lines. Chunk text changes shape for those
documents, so
a base indexed before this and searched after it holds both forms until
its
documents are reindexed; retrieval keeps working either way, because
both forms
are text. The same applies to how much prose a table or a figure carries
with
it: the setting now reaches as far as it says, where before it stopped
at the
nearest paragraph, so a chunk cut before this keeps the narrower context
until
its document is rebuilt. Rolling back is reverting the branch and
reindexing.
The deepdoc models are optional. An install that never ran `make
fetch-resources` reads PDFs geometrically, exactly as before, and says
so when
the models are asked for by name. Nothing here reaches the network at
request
time.
Chunk crops and rendered pages are written at index time and on first
view, both
under the state directory rather than in the repository, and both are
deleted
with their document. A page is immutable for the life of its document
id, so
the route serving them caches; the document route does not. All three
routes
take ids and no path, and the two image routes answer under the
strictest
sandbox in the tree.
What an agent may search is the reader's choice and nothing else. The
tool takes
no base argument, so a model cannot name one, and it is absent from the
schema
entirely for a conversation that named none -- a lane nobody pointed at
a base
is unchanged by this branch. The bases a session carries are stored
beside its
working directory and travel no further.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Five sections leave both READMEs: self-hosting, the command reference,
the
documentation index, the repo layout and the architecture. Each is
already a
page on the documentation site, and a second copy in the README is the
one
that drifts. Quick Start now ends by naming the site, so a reader who
has just
installed Raven is told where the rest lives. English drops 258 lines
and
Chinese 228, and the two stay in step: every section removed and the
pointer
added exist in both.
The repo-layout table went with them, and it was never only prose. It is
the
canonical set of commit scopes: a test held it equal to the packages on
disk
while commitlint computes its enum from that same tree, so the table is
what
keeps the list a reader is sent to and the list the tooling enforces
from
splitting. Removing the section broke both of that test's assertions,
and the
test reads the documentation page now, which carries the same table and
the
same key directories block. It is renamed with the move, because it no
longer
reads a README. AGENTS.md, raven/README.md and two comments in
commitlint.config.cjs name the page as well. The enum commitlint
computes is
unchanged at 71 scopes, because it was always read from the tree rather
than
from the table.
Two things are deliberately left alone. The dated records under
docs/plans and
docs/specs still describe the old location: they record the tree as of
their
date. And the English README keeps a Showcase section the Chinese one
does not
have, which is how they already were.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
The coupling was demonstrated rather than assumed: removing the sections
first
was run against the existing test, which failed with "README.md lost its
'Repo
layout' section" and "Key directories lost its agents/ line". After
repointing,
dropping one table row from the documentation page fails it again with
"package
on disk without a table row: ['acp']", so the guard still bites from its
new
source.
- `uv run pytest tests/test_scope_canon.py tests/test_docs_site.py
tests/test_docker_runtime.py tests/test_living_docs.py
tests/test_external_consumer_surface.py` -> 22 passed
- `uv run pytest` over the eleven other tests that read a README -> 859
passed
- `make lint-python`, `make lint-imports`, `make lint-deps`, `make
lint-types`
-> exit 0, against an environment synced the way CI installs
- `make check-commits`, `make check-source-language`, `make
check-large-files`,
and `pre-commit run --from-ref origin/main --to-ref HEAD` -> exit 0
- `make docs-build` -> built
- `node -e` on commitlint.config.cjs -> 71 scopes, the same set as
before
- the only internal anchors left in either README are `#readme-top`,
whose
target is still there, and no remaining link points into a removed
section
## Risk
User-visible: the README no longer answers self-hosting, the commands,
the
layout or the architecture; it points at the site instead. Anyone who
had
bookmarked a README anchor for one of those sections loses it. The scope
list
AGENTS.md sends a contributor to is now a page rather than a README
section.
Rollback: revert the commit. Nothing outside the repository depends on
the
removed sections, and the site pages they moved to were already
published.
## Related Issues
N/A
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
The installers stop telling you what to run and run it. `install.sh`
ends with
`raven web --stop && raven web --foreground`, so a finished install is
the page
open in a browser rather than a hint to go and type something; first-run
setup
is walked through by the page's own onboarding. The capability summary,
the
upgrade-versus-first-run wording and the config.json probe that fed it
go with
it. `install.ps1` mirrors all of this, with one deliberate divergence: a
non-zero page exit only warns there, because under `irm | iex` that is
the
reader's own interactive PowerShell and Ctrl-C, the ordinary way to end
a
foreground page, returns non-zero.
Two gaps that only bite a source install are closed on the way:
- `build_web_assets` compares each artifact against its sources instead
of only
testing that it exists. An editable install relinks Python and nothing
else,
so `ui-tui/dist/entry.js` and `ui-web/dist/index.html` kept serving
whatever
the tree held at first install while every `.py` beside them moved on.
The
page watches `i18n/` too, since `ui-web/build.py` inlines the catalogue.
`node_modules`, `dist` and `.modern` are pruned: `npm ci` rewrites the
first
on every build, and the other two hold the artifact being judged.
- A node packaged without npm now fetches a private runtime that carries
one.
Debian and Ubuntu split the two packages, so a system node >= 22
satisfied
`ensure_node` and the build then found no npm with no private runtime
ever
provisioned. The download body is split out as `provision_private_node`
and
called from the build probe as well, subshelled so a failure there is a
skipped build rather than a failed install. It stays lazy rather than
moving
into `ensure_node`, so a wheel install that never runs npm does not pay
for a
50 MB download it has no use for.
Both READMEs are reordered and the clone install is documented under
Quick
Start, where it was missing: `./install.sh` and a piped run do different
things
from inside a checkout, because local mode requires `$0` to be a real
file, and
`RAVEN_LOCAL_SRC` is the opt-out. The Chinese README also picks up the
EverMind
ecosystem table the English one had already moved to.
One test changed rather than being deleted.
`test_readme_quickstart_matches_the_installer_hint`
required an `Onboard and run` heading in both READMEs; the installers no
longer
close with a first-run hint and neither README carries that section, so
the pin
had no subject left. It is repointed at what the two must still agree
on, which
is the clone install.
`install.ps1` has not been parsed or executed. There is no pwsh on the
machine
this was written on and no PowerShell step in CI, so every Windows
change here
is reviewed by eye and pinned by text tripwires only. A real Windows run
before
release would be worth it.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
`uv run python -m pytest tests/ --ignore=tests/integration` on the
merged tree:
23161 passed, 109 skipped.
`uv run pytest tests/test_install_script.py`: 27 passed, including a
functional
test that extracts the real `is_stale` and `resolve_node_dir` from
`install.sh`
and runs them under `sh`. `is_stale` is checked across missing artifact,
fresh
artifact, touched page source, touched catalogue, and build output
touched;
`resolve_node_dir` across system node with npm, node without npm, node
without
npm and a failed fetch, and no node at all. Both were mutation-checked:
removing
the fallback line from `install.sh` turns the new tests red.
`sh -n install.sh`, `make check-source-language`, `make
check-large-files`,
`ruff check`, `ruff format --check`: all clean.
- [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: a finished install now holds the terminal on a running
page
instead of returning to the prompt. That also means the installer's exit
code is
the gateway's, so on a clone where the page build only warned,
`install.sh` now
exits 1 with "No page is built" where it used to exit 0 with a working
TUI. A
re-run over a checkout that has moved on will rebuild the frontend,
which costs
an `npm ci` it used to skip.
Rollback is per commit: the launch, the rebuild-on-change and the npm
fallback
are independent edits to `install.sh` and `install.ps1` and can be
reverted
separately. No runtime code outside the installers changed.
- [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
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
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.
The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.
Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.
Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.
This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
tests/test_permissions_gate.py tests/test_acp_server.py \
tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s
$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s
$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
raven/acp/server.py raven/agent/tools/shell.py
All checks passed!
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.
Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.
Effect on the dependency graph:
```
permissions -> agent edges 1 -> 0
mutually importing pairs 14 -> 13
packages in an import cycle 22 -> 22 (unchanged)
```
The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.
No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.
## Related Issues
N/A
## Summary
`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.
The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.
Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.
Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.
This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
tests/test_permissions_gate.py tests/test_acp_server.py \
tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s
$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s
$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
raven/acp/server.py raven/agent/tools/shell.py
All checks passed!
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.
Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.
Effect on the dependency graph:
```
permissions -> agent edges 1 -> 0
mutually importing pairs 14 -> 13
packages in an import cycle 22 -> 22 (unchanged)
```
The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.
No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.
## Related Issues
N/A
## Summary
Three reader-facing changes to the TUI transcript and the instance strip.
**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.
The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.
Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.
**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.
**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.
`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on a worktree at this branch's tip, against the current main tip:
- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0
No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Three user-visible changes, all inside the terminal UI:
- a tool call that returned something now opens to a capped preview instead of
staying shut. A reader who prefers it shut clicks once, and that decision
holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
has one column less for its name.
- the status ticker shows a different set of glyphs and words.
No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Three reader-facing changes to the TUI transcript and the instance strip.
**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.
The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.
Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.
**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.
**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.
`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on a worktree at this branch's tip, against the current main tip:
- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0
No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Three user-visible changes, all inside the terminal UI:
- a tool call that returned something now opens to a capped preview instead of
staying shut. A reader who prefers it shut clicks once, and that decision
holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
has one column less for its name.
- the status ticker shows a different set of glyphs and words.
No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## What
Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.
## Why
On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:
- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
from three classes outside the falsified list" (the falsified list named 18 specific
hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".
The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.
## The three rules
1. The owner's words and scope go into every node's brief as written; the orchestrator's
own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
*not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.
## Checks
- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
`tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
adds later in the same file.
## What
Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.
## Why
On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:
- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
from three classes outside the falsified list" (the falsified list named 18 specific
hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".
The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.
## The three rules
1. The owner's words and scope go into every node's brief as written; the orchestrator's
own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
*not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.
## Checks
- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
`tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
adds later in the same file.
## Summary
The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.
It comes back as a section of the card, not a third verb on the row:
- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.
No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.
**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:
- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.
This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.
**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)
**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.
**Checked and deliberately not changed, for the reviewer:**
- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:
- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.
```
npm run test --prefix ui-web 101 files, 1550 passed
npm run test --prefix ui-tui 141 files, 2017 passed, 13 skipped
npm run gen:check --prefix ui-web generated client matches the contract (162 methods)
npm run type-check --prefix ui-web clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui 23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py pass over the branch
make build-ui dist rebuilt and served
```
The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)
## Risk
User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.
- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.
It comes back as a section of the card, not a third verb on the row:
- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.
No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.
**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:
- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.
This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.
**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)
**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.
**Checked and deliberately not changed, for the reviewer:**
- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:
- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.
```
npm run test --prefix ui-web 101 files, 1550 passed
npm run test --prefix ui-tui 141 files, 2017 passed, 13 skipped
npm run gen:check --prefix ui-web generated client matches the contract (162 methods)
npm run type-check --prefix ui-web clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui 23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py pass over the branch
make build-ui dist rebuilt and served
```
The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)
## Risk
User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.
- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.
Key decisions:
- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
`use_skill` and the segment builder's post-gate hydrate refuse exactly what
they refused before. Reading is the weaker case because it installs nothing
and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
products rather than being one, so reporting the root refused a skill for
mentioning XDG at all. The reported path now runs down to the segment naming
the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.
`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.
- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
3 skipped. The three skips are pre-existing and environment-bound (two
`chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
note `these instructions reference paths outside Raven (~/.config/mcporter,
~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.
The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.
The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.
Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.
## Related Issues
N/A
## Summary
The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.
Key decisions:
- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
`use_skill` and the segment builder's post-gate hydrate refuse exactly what
they refused before. Reading is the weaker case because it installs nothing
and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
products rather than being one, so reporting the root refused a skill for
mentioning XDG at all. The reported path now runs down to the segment naming
the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.
`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.
- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
3 skipped. The three skips are pre-existing and environment-bound (two
`chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
note `these instructions reference paths outside Raven (~/.config/mcporter,
~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.
The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.
The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.
Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.
## Related Issues
N/A
## Summary
Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.
**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.
**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.
**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.
**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.
The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.
Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Branch and base run in separate worktrees, both at the same base, same interpreter.
- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
`unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
need `--localstorage-file` for `localStorage` to exist on this box at all, and with
it the store no longer refuses, so the refusal each asserts does not happen. Both
reproduce on the base, and neither file imports anything this change touches. A
second environment settles it: review ran the same head and reported 1,536 tests
passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
`check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
`lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
`renamed` call, a missing export, a missing harness verb, and the pre-edit title.
The ordering one is driven through the real `rpc.onReconnect` rather than
`openLiveSession`, because the ordering is between the two and a test that calls the
inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
editor gone, button back, zero title calls, no page error. Reconnect with the editor
open, forced by closing the socket from the page: before, `Cannot read properties of
null (reading 'textContent')` with the input stranded and no session reload; after,
heading restored, editor gone, reload done, no page error. Reconnect with a name
typed into an open editor: heading and rail row both settle on the committed name,
no page error. That probe renamed a real conversation, so its title was put back and
the stored metadata checked byte-identical afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible, all of it in the same direction: a title that used to vanish stays put.
- Ending an editor on a conversation switch commits what was typed, which is what
leaving the field already did. It cannot reach a different conversation than the one
it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
only case that changes is a name being generated, where the heading is empty and the
row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
shape or a schema.
Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.
## Related Issues
N/A
## Summary
Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.
**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.
**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.
**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.
**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.
The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.
Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Branch and base run in separate worktrees, both at the same base, same interpreter.
- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
`unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
need `--localstorage-file` for `localStorage` to exist on this box at all, and with
it the store no longer refuses, so the refusal each asserts does not happen. Both
reproduce on the base, and neither file imports anything this change touches. A
second environment settles it: review ran the same head and reported 1,536 tests
passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
`check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
`lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
`renamed` call, a missing export, a missing harness verb, and the pre-edit title.
The ordering one is driven through the real `rpc.onReconnect` rather than
`openLiveSession`, because the ordering is between the two and a test that calls the
inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
editor gone, button back, zero title calls, no page error. Reconnect with the editor
open, forced by closing the socket from the page: before, `Cannot read properties of
null (reading 'textContent')` with the input stranded and no session reload; after,
heading restored, editor gone, reload done, no page error. Reconnect with a name
typed into an open editor: heading and rail row both settle on the committed name,
no page error. That probe renamed a real conversation, so its title was put back and
the stored metadata checked byte-identical afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible, all of it in the same direction: a title that used to vanish stays put.
- Ending an editor on a conversation switch commits what was typed, which is what
leaving the field already did. It cannot reach a different conversation than the one
it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
only case that changes is a name being generated, where the heading is empty and the
row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
shape or a schema.
Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.
## Related Issues
N/A
## Summary
The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.
This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.
Key decisions:
- Memory is more than an adapter over the context engine. Two decisions that
sat in the shell move onto the role that owns them: which history slice is
even a candidate (it turns on whether the engine archives for itself), and
how much of the window a prompt may occupy (that window's own arithmetic).
organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
A live model switch rebuilds the provider and the window, and trajectory
replay rebinds loop.tools after the constructor returns. The context engine
is the exception and is bound directly: nothing rebinds it, and a
generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
contract tier: a replacement loop may name its own strategy points, so these
four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
list cannot move which message gets marked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.
- Captured on this branch and twice on its parent commit. Raw diffs contain
only wrap_untrusted fence nonces, which are random per invocation; capturing
the parent twice shows those are the sole variance. After normalising them
all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
default set, the two decisions Memory took over, both Action paths, the
callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.
The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.
This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.
Key decisions:
- Memory is more than an adapter over the context engine. Two decisions that
sat in the shell move onto the role that owns them: which history slice is
even a candidate (it turns on whether the engine archives for itself), and
how much of the window a prompt may occupy (that window's own arithmetic).
organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
A live model switch rebuilds the provider and the window, and trajectory
replay rebinds loop.tools after the constructor returns. The context engine
is the exception and is bound directly: nothing rebinds it, and a
generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
contract tier: a replacement loop may name its own strategy points, so these
four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
list cannot move which message gets marked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.
- Captured on this branch and twice on its parent commit. Raw diffs contain
only wrap_untrusted fence nonces, which are random per invocation; capturing
the parent twice shows those are the sole variance. After normalising them
all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
default set, the two decisions Memory took over, both Action paths, the
callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.
The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.
Key decisions:
- **Templates are real code, fire-tested before templating.** The eleven
files under raven/templates/agents_scaffold/ pass ruff and py_compile
like any source, ride the wheel, and their content was proven live
before landing: discovery, handshake, and plugin tool/hook injection
all green on a hand-assembled probe in a disposable home. A dedicated
spike also proved the placement is invisible to the import-linter
contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
target is the raven home's agents/ tree, discovery's first root: a
scaffolded folder is on the roster without any registration.
--register mirrors the generated install.py through the same pinned
write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
manifest, re-parses the plugin manifest, compiles every generated
file, and really scans discovery; smoke spawns the launcher for one
initialize frame. Three smoke outcomes are told apart: GREEN, the
launcher's loud no-key refusal (fail-closed design, passed through
verbatim), and FAILED with the scene preserved. Display names are
fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
renders schemas/subagent.schema.json (a discriminated union on kind)
and schemas/raven-plugin.schema.json from the pydantic models; a
contract family holds the on-disk files byte-equal to a fresh render
and validates every real manifest on the tree against them. Editors
get instant validation with two settings lines, documented in the
guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
the from-zero developer guide (gold standard: a developer who never
read the source reaches a green handshake in ten minutes); CONTEXT.md
renames the category entry to Discovered agent -- agent the thing,
harness the mechanism, subagent the protocol seat -- with product
absorbed into Avoid; the charter gains the scaffold entry and the
engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
project in the working directory (pip install -e territory); --here
lands it on the plugins-dist shelf. The launcher adopts the official
ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
is missing; the doctor reports that row as disabled by design with
the install cure printed. No plugins/ directory ships beside an
engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
hostile lenses (filesystem edges of a command that writes into real
raven homes; template quality as the file set every future agent
copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
pin an enabled row that cannot start, the name fence ignored the
discovered tree, one installed engine wheel rode the host's and every
sibling's turns through a fixed tool name, and crash residue was
discovered as a hidden live agent. All fourteen close in a
dedicated hardening commit, each with a regression test built from the review's own
reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
Nothing under raven/contracts/ or the agent loop changed. The branch
carries exactly two narrow runtime fixes exposed by the review:
discovery now skips dot-directories (crash residue is never an
agent), and the config schema gains an engine round-trip field
(declared as a field-level neutral seam; merge and readiness
semantics untouched).
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- Every commit landed through a full-suite rehearsal on a clean bench
before touching the branch; tails over the original base's 19953
passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
every step a pure addition, +65 tests net. The branch diff is
fingerprint-stable across the rebase (git patch-id --stable verified
pairwise across two clean rebases); the branch closes at 20094 passed
/ 137 skipped / exit 0 on the current main base, +80 tests net over
whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
end: one command scaffolds into ~/.raven/agents, the four-segment
card runs all green, and a genuine LLM turn has the agent's own model
call its own scaffolded hello tool through the permission gate and
relay the exact output; the probe was then removed without touching
the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
four doctor lines, readiness ready, and a live ACP initialize
handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
tampered file each turn the family red); all six subagent manifests
and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
make check-large-files, make check-source-language: green at every
step; wheel build carries all seventeen template files and none of
schemas/.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.
## Related Issues
N/A
## Summary
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
Three strands of raven-research work, held together because they all touch the vendored fork and so share one `subagents/TREE_HASHES` line.
**Web search and fetch route through the vendor the deployment picked.** Both tools in the research-flow plugin were pinned to Serper and Jina, so a host on Tavily or Brave still needed a Serper key for the pair. They now carry the kernel's vendor tables (seven search backends, five fetch) with per-vendor request encoding and response normalisation. Serper and Jina wire traffic is byte-identical to before. A vendor that publishes no result offset declares it up front (`SearchProviderSpec.paginates`), so the saturation rule never escalates to a page rung the vendor cannot answer.
The launcher resolves the vendor first and mirrors the SELECTED vendor's key into the plugin slice, never a key by fixed path: a mismatched pair sends one vendor's credential to another's endpoint and every call comes back unauthorized. Every vendor gets an env slot at the same path the host holds it, inherited from the host config when unset, so a deployment configures a vendor once, centrally. The two legacy vendors are also read from the vendor slot, where a host configured after the vendor table landed writes them. `require_search` follows the selection rather than the default.
**The research modes take the host's effort vocabulary**: `deep` becomes `high`, `ultra` becomes `max`, and `medium` is the baseline. This is what lets the companion MR's host tier reach this agent by name.
**The ask_user gate closes after a hook rollback**, and host questions take the conversation lock like every other route, including the `direct_ask` grant. The digest follows its session's mode, a typo in a mode overlay refuses to launch rather than running the base value under the overlay's label, and the reviewer records which model judged.
Three defects found while building it, each with the test that pins it:
- **A credential reached disk.** The retry rows of the search and fetch ledger recorded `str(exc)` for a status error, and httpx puts the whole request URL in that text. SerpApi authenticates by query parameter, so a 429 or 503 wrote the key into the JSONL file. The redaction the search and fetch rows already had is now one function, `_error_text`, used by both writers, in the plugin and in the vendored copy. The regression test drives a retryable status and reads the ledger file off disk; the previous test used 401, which is not retryable and so never reached the leaking write. The key never reached the model or the answer: the appendix partitions on `search` / `fetch` / `verify` / `force_finalize` and reads nothing from a retry row.
- **A keyless fetch backend refused every call.** The kernel's `web_fetch` degrades a keyed backend with no resolvable key to Jina, out loud. The plugin's replacement did not, and it REPLACES the kernel's, so `fetch.provider = tavily` with no Tavily key made a research run the single place that config could not read a page, while a plain raven on it read the page fine. The launcher itself produces that state: it writes the provider unconditionally and the key only when one resolves. Fixed at the build site, where the kernel resolves it, and a test asserts both implementations answer identically for every vendor.
Reported by chandler.zhang and completed in `ac7d364c`: the degraded backend was still handed the key of the vendor it replaced, which is absent by definition, so a deployment holding a Jina key read pages authenticated through raven's built-in fetch and anonymously through the plugin -- losing the configured quota on the very fallback the rule exists to match. The kernel looks the key up a second time under the EFFECTIVE provider; the slice carries one key per role and no vendor table, so the launcher now mirrors the default reader's key beside the selected vendor's and the build picks by destination, a lookup keyed on the provider the tool will actually call. It is mirrored whenever the selection is not already the default rather than only when the fallback will fire, because the rule that decides that lives in `effective_provider` and a launcher second-guessing it would be the copy that drifts.
- **A typo in a vendor name refused to launch for the wrong reason.** The plugin degrades an unknown vendor to its default, which is right for a slice nothing validates. Carried through the launcher, the same typo had `require_search` demand a key for a vendor that does not exist while the working Serper key sat in the config -- sending the operator to set a credential they already had. The launcher now refuses naming the name and the valid list.
`.env.example` and the plugin docstrings were still describing the fixed Serper and Jina pair; both now cover the provider switch and the per-vendor key slots. The plugin MANIFEST was missed in that pass and is corrected in `18ce29df`, also on chandler.zhang's report: it still called `search.apiKey` a Serper key and `fetch.apiKey` a Jina reader key, and said web_search declines "when no Serper key resolves". A direct plugin user reaching it without the launcher could set `search.provider = tavily` and supply a Serper credential, which this code then sends to Tavily's endpoint.
`subagents/TREE_HASHES` is recorded once, in the final commit, rather than per commit: the hash covers every tracked byte under the fork, so an intermediate value goes stale the moment the next edit or a rebase lands.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on this branch at its current head:
- `uv run pytest` -- 5 failed, 18545 passed, 69 skipped. The five are this host's pre-existing baseline, identical on `origin/main`: `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are` and four `test_security_network.py` NAT64 parameters. 0 introduced.
- `make lint-python` -- passed, 1787 files already formatted.
- `uv run lint-imports` -- 8 contracts kept, 0 broken.
- `make check-vendored-subagents` -- exit 0, hash recorded.
- `make check-vendored-invariants`, `make check-large-files`, `make lint-ui`, `make lint-tui`, `scripts/check_commit_messages.py origin/main..HEAD` -- all exit 0.
- The vendored fork's own suite, run with the fork on `PYTHONPATH` so `raven` resolves to its copy: 19 failed, 6223 passed, 4 errors. Reverting only this branch's change to the fork gives the same 19 failures and 4 errors, all in three files that never import the changed module, so 0 introduced. Those failures are an artifact of running the fork against the trunk's venv, not the fork's own.
Reverting each fix and confirming the matching test fails: the ledger redaction (the 429 case red, the 401 case correctly still green), the fetch degradation (4 keyed vendors red, Jina correctly unaffected), the vendor-name refusal (2 red), and the slice key following the selected vendor (2 red).
Three more for the review fix: the build passing the selected vendor's key to the reader that replaced it (1 red), the launcher not mirroring the fallback key (1 red), and the launcher mirroring it for the default vendor too (1 red, the case where a second copy of the same key is one more place for the pair to disagree).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Security: a credential stopped being written to disk. Any research-flow ledger file written before this change by a deployment on SerpApi may contain the key in a `search_retry` or `fetch_retry` row. Those files live under the plugin's state root, one per turn, and are unlinked at the end of the turn that wrote them; a process killed mid-turn leaves one behind. Treat a SerpApi key used on an affected build as exposed and rotate it, then check for leftover files.
Other user-visible changes:
- A research deployment that selected a keyed fetch vendor without its key now reads pages through Jina instead of failing every fetch, and does so on the host's configured Jina key rather than anonymously. Behaviour improves; the log says which vendor is serving.
- That fallback key now travels in the rendered plugin slice as `fetch.fallbackApiKey`, beside the selected vendor's key, wherever the rendered config already holds credentials. It is only ever handed to the default reader: the build looks the key up by destination, so a provider neither key belongs to gets none.
- An unknown vendor name in `search.provider` or `fetch.provider` now refuses to launch. A deployment running on a typo today would have been failing its search calls anyway.
- The research mode ids change: `deep` becomes `high` and `ultra` becomes `max`. A caller that names `deep` by id gets the agent's default instead.
- Ledger `*_retry` rows record `HTTPStatusError: HTTP <status>` where they recorded the full httpx message. The one offline reader, the fork's `bench/rollout.py`, buckets by status either way and already read the search and fetch rows in that shape.
Rollback: revert the commits on this branch. `TREE_HASHES` is recorded in its own final commit, so reverting the set restores the recorded hash with the tree.
## Related Issues
N/A
<!-- The repo guide says to leave this trailer to the commits, on the premise that
the platform collects it into the squash commit. This GitLab does not, and the
squash body is taken from this description, so it is repeated here to survive. -->
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Three strands of raven-research work, held together because they all touch the vendored fork and so share one `subagents/TREE_HASHES` line.
**Web search and fetch route through the vendor the deployment picked.** Both tools in the research-flow plugin were pinned to Serper and Jina, so a host on Tavily or Brave still needed a Serper key for the pair. They now carry the kernel's vendor tables (seven search backends, five fetch) with per-vendor request encoding and response normalisation. Serper and Jina wire traffic is byte-identical to before. A vendor that publishes no result offset declares it up front (`SearchProviderSpec.paginates`), so the saturation rule never escalates to a page rung the vendor cannot answer.
The launcher resolves the vendor first and mirrors the SELECTED vendor's key into the plugin slice, never a key by fixed path: a mismatched pair sends one vendor's credential to another's endpoint and every call comes back unauthorized. Every vendor gets an env slot at the same path the host holds it, inherited from the host config when unset, so a deployment configures a vendor once, centrally. The two legacy vendors are also read from the vendor slot, where a host configured after the vendor table landed writes them. `require_search` follows the selection rather than the default.
**The research modes take the host's effort vocabulary**: `deep` becomes `high`, `ultra` becomes `max`, and `medium` is the baseline. This is what lets the companion MR's host tier reach this agent by name.
**The ask_user gate closes after a hook rollback**, and host questions take the conversation lock like every other route, including the `direct_ask` grant. The digest follows its session's mode, a typo in a mode overlay refuses to launch rather than running the base value under the overlay's label, and the reviewer records which model judged.
Three defects found while building it, each with the test that pins it:
- **A credential reached disk.** The retry rows of the search and fetch ledger recorded `str(exc)` for a status error, and httpx puts the whole request URL in that text. SerpApi authenticates by query parameter, so a 429 or 503 wrote the key into the JSONL file. The redaction the search and fetch rows already had is now one function, `_error_text`, used by both writers, in the plugin and in the vendored copy. The regression test drives a retryable status and reads the ledger file off disk; the previous test used 401, which is not retryable and so never reached the leaking write. The key never reached the model or the answer: the appendix partitions on `search` / `fetch` / `verify` / `force_finalize` and reads nothing from a retry row.
- **A keyless fetch backend refused every call.** The kernel's `web_fetch` degrades a keyed backend with no resolvable key to Jina, out loud. The plugin's replacement did not, and it REPLACES the kernel's, so `fetch.provider = tavily` with no Tavily key made a research run the single place that config could not read a page, while a plain raven on it read the page fine. The launcher itself produces that state: it writes the provider unconditionally and the key only when one resolves. Fixed at the build site, where the kernel resolves it, and a test asserts both implementations answer identically for every vendor.
Reported by chandler.zhang and completed in `ac7d364c`: the degraded backend was still handed the key of the vendor it replaced, which is absent by definition, so a deployment holding a Jina key read pages authenticated through raven's built-in fetch and anonymously through the plugin -- losing the configured quota on the very fallback the rule exists to match. The kernel looks the key up a second time under the EFFECTIVE provider; the slice carries one key per role and no vendor table, so the launcher now mirrors the default reader's key beside the selected vendor's and the build picks by destination, a lookup keyed on the provider the tool will actually call. It is mirrored whenever the selection is not already the default rather than only when the fallback will fire, because the rule that decides that lives in `effective_provider` and a launcher second-guessing it would be the copy that drifts.
- **A typo in a vendor name refused to launch for the wrong reason.** The plugin degrades an unknown vendor to its default, which is right for a slice nothing validates. Carried through the launcher, the same typo had `require_search` demand a key for a vendor that does not exist while the working Serper key sat in the config -- sending the operator to set a credential they already had. The launcher now refuses naming the name and the valid list.
`.env.example` and the plugin docstrings were still describing the fixed Serper and Jina pair; both now cover the provider switch and the per-vendor key slots. The plugin MANIFEST was missed in that pass and is corrected in `18ce29df`, also on chandler.zhang's report: it still called `search.apiKey` a Serper key and `fetch.apiKey` a Jina reader key, and said web_search declines "when no Serper key resolves". A direct plugin user reaching it without the launcher could set `search.provider = tavily` and supply a Serper credential, which this code then sends to Tavily's endpoint.
`subagents/TREE_HASHES` is recorded once, in the final commit, rather than per commit: the hash covers every tracked byte under the fork, so an intermediate value goes stale the moment the next edit or a rebase lands.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on this branch at its current head:
- `uv run pytest` -- 5 failed, 18545 passed, 69 skipped. The five are this host's pre-existing baseline, identical on `origin/main`: `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are` and four `test_security_network.py` NAT64 parameters. 0 introduced.
- `make lint-python` -- passed, 1787 files already formatted.
- `uv run lint-imports` -- 8 contracts kept, 0 broken.
- `make check-vendored-subagents` -- exit 0, hash recorded.
- `make check-vendored-invariants`, `make check-large-files`, `make lint-ui`, `make lint-tui`, `scripts/check_commit_messages.py origin/main..HEAD` -- all exit 0.
- The vendored fork's own suite, run with the fork on `PYTHONPATH` so `raven` resolves to its copy: 19 failed, 6223 passed, 4 errors. Reverting only this branch's change to the fork gives the same 19 failures and 4 errors, all in three files that never import the changed module, so 0 introduced. Those failures are an artifact of running the fork against the trunk's venv, not the fork's own.
Reverting each fix and confirming the matching test fails: the ledger redaction (the 429 case red, the 401 case correctly still green), the fetch degradation (4 keyed vendors red, Jina correctly unaffected), the vendor-name refusal (2 red), and the slice key following the selected vendor (2 red).
Three more for the review fix: the build passing the selected vendor's key to the reader that replaced it (1 red), the launcher not mirroring the fallback key (1 red), and the launcher mirroring it for the default vendor too (1 red, the case where a second copy of the same key is one more place for the pair to disagree).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Security: a credential stopped being written to disk. Any research-flow ledger file written before this change by a deployment on SerpApi may contain the key in a `search_retry` or `fetch_retry` row. Those files live under the plugin's state root, one per turn, and are unlinked at the end of the turn that wrote them; a process killed mid-turn leaves one behind. Treat a SerpApi key used on an affected build as exposed and rotate it, then check for leftover files.
Other user-visible changes:
- A research deployment that selected a keyed fetch vendor without its key now reads pages through Jina instead of failing every fetch, and does so on the host's configured Jina key rather than anonymously. Behaviour improves; the log says which vendor is serving.
- That fallback key now travels in the rendered plugin slice as `fetch.fallbackApiKey`, beside the selected vendor's key, wherever the rendered config already holds credentials. It is only ever handed to the default reader: the build looks the key up by destination, so a provider neither key belongs to gets none.
- An unknown vendor name in `search.provider` or `fetch.provider` now refuses to launch. A deployment running on a typo today would have been failing its search calls anyway.
- The research mode ids change: `deep` becomes `high` and `ultra` becomes `max`. A caller that names `deep` by id gets the agent's default instead.
- Ledger `*_retry` rows record `HTTPStatusError: HTTP <status>` where they recorded the full httpx message. The one offline reader, the fork's `bench/rollout.py`, buckets by status either way and already read the search and fetch rows in that shape.
Rollback: revert the commits on this branch. `TREE_HASHES` is recorded in its own final commit, so reverting the set restores the recorded hash with the tree.
## Related Issues
N/A
<!-- The repo guide says to leave this trailer to the commits, on the premise that
the platform collects it into the squash commit. This GitLab does not, and the
squash body is taken from this description, so it is repeated here to survive. -->
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
## Summary
Subagent discovery switches rails from the subagents/ fork trees to the
agents/ product tree. This makes the five migrated products (code, oncall,
ppt, research, design) the factory default: a fresh install discovers them
without running any per-product installer, and the fork trees stop being
scanned entirely (they remain on disk, untouched, until their separately
scheduled retirement).
Key decisions:
- Discovery resolves an agents root through the same three levels the fork
scan used: raven home copy, beside the package, wheel-embedded. The copy
to raven home is kept folders-only so a product's .env survives upgrades.
- Readiness has new semantics: the launcher's absolute-path command tokens
must exist, and a product-declared engine distribution must be importable
(importlib find_spec). A product whose engine wheel is missing is listed
but disabled, naming the wheel to install. Credential checks leave the
discovery phase: the launcher itself refuses loudly, which live handshake
smoke verified for all five products.
- Config rows keep whole-row precedence over discovered rows; the merge
mechanics are unchanged (verified byte-equivalent modulo renames by an
independent adversarial review).
- The main wheel now ships the five product launchers under raven/agents
and no longer embeds raven/subagents (118 files / 1.3 MB, verified by
building and listing the wheel; zero pyproject changes, the inclusion
lives in the hatch build hook).
- The design/ppt manifests gain one machine-readable field,
`engine: {package, wheel}`, consumed by the readiness probe; launch
behavior is untouched and older readers ignore the field (verified).
- A discovered row whose readiness is clean but whose runtime probe misses
now renders as attention instead of a dead Install button (fix from the
adversarial review).
An independent adversarial review (verdict: land after fixes) preceded this
MR; its one HIGH (net test-coverage loss on host_can_lend_a_key edge
branches) and one MED (the Install dead-end above) are fixed in the commit,
with companion tests. Fork-era behaviors it confirmed as bit-identical
inheritances (home-first shadowing, path-with-spaces refusal) are recorded,
not changed.
## Type
- [x] Feature
## Verification
- Full canonical suite on the branch: `uv run pytest tests -q` under
`uv sync --all-extras` -> 18494 passed, 40 skipped, exit 0 (rehearsal
tree); 18472 passed, 62 skipped on the drafting stack. Net def-level
movement vs baseline accounted name-for-name in the wave report.
- Targeted families at landing: tests/test_agents_ppt_launcher.py,
tests/test_cli_subagent_setup.py, tests/test_hatch_build.py,
tests/test_rpc_subagents.py, tests/test_subagent_dag_machines.py,
tests/test_subagent_vendored_agents.py -> 242 passed.
- `make lint-python` -> exit 0; `uv run lint-imports` -> 8 kept, 0 broken;
`make check-vendored-subagents`, `check-vendored-invariants`,
`check-large-files` -> exit 0. subagents/ is byte-untouched.
- Wheel audit: `uv build --wheel`, listed contents -> 5 launchers +
5 manifests under raven/agents, 0 raven/subagents entries, no secrets.
- Fresh-venv install test: wheel installed into an isolated venv discovers
and materializes all five rows; design/ppt correctly disabled without
their engine wheels; research launcher runs to its credential verdict.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: fork rows stop appearing on fresh installs; the five
product rows appear instead. Machines with existing config rows are
unaffected (config precedence unchanged). The RPC wire shape is frozen
(vendored/building keys and subagents.build kept), so no client regeneration
is needed. Rollback: revert the squash commit; discovery returns to the
fork trees, which are still on disk in the repo and still embedded in any
wheel built before this change.
## Related Issues
N/A
## Summary
Subagent discovery switches rails from the subagents/ fork trees to the
agents/ product tree. This makes the five migrated products (code, oncall,
ppt, research, design) the factory default: a fresh install discovers them
without running any per-product installer, and the fork trees stop being
scanned entirely (they remain on disk, untouched, until their separately
scheduled retirement).
Key decisions:
- Discovery resolves an agents root through the same three levels the fork
scan used: raven home copy, beside the package, wheel-embedded. The copy
to raven home is kept folders-only so a product's .env survives upgrades.
- Readiness has new semantics: the launcher's absolute-path command tokens
must exist, and a product-declared engine distribution must be importable
(importlib find_spec). A product whose engine wheel is missing is listed
but disabled, naming the wheel to install. Credential checks leave the
discovery phase: the launcher itself refuses loudly, which live handshake
smoke verified for all five products.
- Config rows keep whole-row precedence over discovered rows; the merge
mechanics are unchanged (verified byte-equivalent modulo renames by an
independent adversarial review).
- The main wheel now ships the five product launchers under raven/agents
and no longer embeds raven/subagents (118 files / 1.3 MB, verified by
building and listing the wheel; zero pyproject changes, the inclusion
lives in the hatch build hook).
- The design/ppt manifests gain one machine-readable field,
`engine: {package, wheel}`, consumed by the readiness probe; launch
behavior is untouched and older readers ignore the field (verified).
- A discovered row whose readiness is clean but whose runtime probe misses
now renders as attention instead of a dead Install button (fix from the
adversarial review).
An independent adversarial review (verdict: land after fixes) preceded this
MR; its one HIGH (net test-coverage loss on host_can_lend_a_key edge
branches) and one MED (the Install dead-end above) are fixed in the commit,
with companion tests. Fork-era behaviors it confirmed as bit-identical
inheritances (home-first shadowing, path-with-spaces refusal) are recorded,
not changed.
## Type
- [x] Feature
## Verification
- Full canonical suite on the branch: `uv run pytest tests -q` under
`uv sync --all-extras` -> 18494 passed, 40 skipped, exit 0 (rehearsal
tree); 18472 passed, 62 skipped on the drafting stack. Net def-level
movement vs baseline accounted name-for-name in the wave report.
- Targeted families at landing: tests/test_agents_ppt_launcher.py,
tests/test_cli_subagent_setup.py, tests/test_hatch_build.py,
tests/test_rpc_subagents.py, tests/test_subagent_dag_machines.py,
tests/test_subagent_vendored_agents.py -> 242 passed.
- `make lint-python` -> exit 0; `uv run lint-imports` -> 8 kept, 0 broken;
`make check-vendored-subagents`, `check-vendored-invariants`,
`check-large-files` -> exit 0. subagents/ is byte-untouched.
- Wheel audit: `uv build --wheel`, listed contents -> 5 launchers +
5 manifests under raven/agents, 0 raven/subagents entries, no secrets.
- Fresh-venv install test: wheel installed into an isolated venv discovers
and materializes all five rows; design/ppt correctly disabled without
their engine wheels; research launcher runs to its credential verdict.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: fork rows stop appearing on fresh installs; the five
product rows appear instead. Machines with existing config rows are
unaffected (config precedence unchanged). The RPC wire shape is frozen
(vendored/building keys and subagents.build kept), so no client regeneration
is needed. Rollback: revert the squash commit; discovery returns to the
fork trees, which are still on disk in the repo and still embedded in any
wheel built before this change.
## Related Issues
N/A
## Summary
Governance hardening batch: the collaboration rulebook catches up with the
post-layering tree, the repository's comments and records are brought up to
its own standards, and the standards themselves become enforced gates.
Five commits, in series:
1. docs: the rulebook catches up -- AGENTS.md gains the source-language rule
with the owner-signed CJK zones, a portable PR check replaces the
GitHub-only wording, README's repo-layout table becomes the canonical
scope list, CONTEXT-MAP gains its third route, and CONTEXT.md records the
migration vocabulary.
2. docs: 133 surgical comment fixes across 83 files -- comments now say why,
and only why; edit markers and restated-what comments are gone.
3. docs: stale orphans leave -- 5 dead documents deleted, 4 dated records
stamped as historical, the zh README shrinks to a translated landing
page, and the living-docs guard widens its glob.
4. ci: the honor system grows teeth -- scripts/check_source_language.py
(diff-based, three passes), a commitlint scope enum computed from the
tree, tests/test_readme_scope_canon.py, and the CI/make wiring for all
three.
5. fix: a second pass brings the batch current with what landed on main
after it was drafted -- the design engine's two owner-signed zones enter
the gate and the rulebook, the scope enum learns the fifth product and
the wheel distributions, CONTEXT.md records the third distributed member
and the Visual Domain Selector, and one zh fixture added by a follow-on
wave is respelled to English with its placeholder semantics preserved.
The batch is docs and CI only: no runtime behavior changes. The one source
edit outside docs/CI is the fixture respell in commit 5, verified by its own
test family.
## Type
- [x] CI / tooling
## Verification
- Full suite on the batch tree: `uv run --frozen --all-extras pytest tests -q`
-> 18513 passed, 40 skipped, exit 0.
- `make lint-python` -> All checks passed; `uv run lint-imports` -> 0 broken.
- Guard families after landing commit 5: `uv run pytest
tests/test_playbook_generator.py tests/test_commit_lint.py
tests/test_living_docs.py tests/test_readme_scope_canon.py
tests/test_source_language_check.py -q` -> 55 passed.
- Language-gate self-run over the batch's own range and over main's history
since the batch base: exit 0 (one genuine pre-existing violation found and
fixed in commit 5).
- Commitlint over all five batch subjects: 5/5 pass; `make check-large-files`
-> exit 0.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No runtime code paths change. The new CI gates can reject future commits by
design; if a gate misfires, reverting the squash commit removes the gates
and the rulebook text together. Existing CJK carriers in main's history are
exempt: the gate is diff-based and only judges new changes.
## Related Issues
N/A
## Change description
The bespoke `subject-case: [2, "always", ["lower-case"]]` rule forced
all-lowercase subjects and rejected proper nouns (EverOS, HTTP), so a PR
title
like "... with EverOS HTTP backend" passed the pre-merge PR-title check
but
failed commit-lint on the squash commit after merge.
This switches `subject-case` to the standard
`@commitlint/config-conventional`
value (forbid Title Case / ALL CAPS / Sentence case; allow lowercase
subjects
with proper nouns), plus one matching example in AGENTS.md. It
intentionally does
NOT `extends` config-conventional, to avoid newly enforcing body/footer
line-length rules on the squash body (= PR description).
Verified locally: proper-noun titles pass, Title Case / Sentence case /
ALL CAPS
still rejected, `style:` still rejected (type-enum unchanged), long body
lines
unaffected.
## Type of change
- [x] Bug fix
- [ ] New feature
- [ ] Document
- [ ] Others
## Related issues (if there is)
Closes#186
## Checklists
### Development
- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [ ] Automated tests covering modified code pass
### Security
- [x] Security impact of change has been considered
- [x] Code follows security best practices and guidelines
### Code review
- [x] Pull request has a descriptive title and context useful to a
reviewer. Screenshots or screencasts are attached as necessary
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
EverOS defaulted both its user-level config toml and its data root
(sqlite / lancedb / .index / ome.db) to a bare ~/.everos. Scope raven's
instance under ~/.everos/raven so config and data stay isolated from any
other EverOS consumer on the machine.
Add update_everos.configure_everos_env(): it sets EVEROS_CONFIG_FILE and
EVEROS_MEMORY__ROOT via setdefault (so an explicit operator override
still wins) before EverOS's @cache-d load_settings() first runs. The
everos backend factory and the understand_media tool factory call it as
the earliest raven-controlled EverOS entry points; _EVEROS_CONFIG now
derives from a single _EVEROS_BASE constant.
No data migration: existing ~/.everos data is left untouched and a fresh
~/.everos/raven is created lazily on first write/use.
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>