72 Commits

Author SHA1 Message Date
Kevin Hu
82c76a82a9
feat(knowledge): read every format, show what the index holds, and let an agent search it (#489)
<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>
2026-10-12 19:05:16 +08:00
Dizhan Xue
b92afe133d
fix(installer): fail closed on missing Node.js integrity evidence (#861)
## Summary

Both installers verify the private Node.js runtime against the
release's SHASUMS256.txt before running it, but each let the download
through whenever the check could not be made. This makes every such
case stop before extraction.

Measured on `main` before this change, running the real functions
against a fake nodejs.org that serves one release at exact URLs:

| Case | install.sh | install.ps1 |
| --- | --- | --- |
| digest matches | installed | installed |
| digest mismatch | aborted | installed ("continuing") |
| SHASUMS256.txt unreachable | installed | installed |
| package not listed | installed | installed |
| no sha256sum or shasum | installed | n/a (Get-FileHash) |

After it, every row but the first stops with its own reason and a
hint to install Node.js >= 22 with npm and re-run; the installer then
uses that Node instead of downloading one.

- `install.sh`: the three warn-and-continue branches become `die`,
  each removing the staged download first. Hashing goes through the
  existing `sha256_of` helper.
- `install.ps1`: `Fail` raises under the script's
  `$ErrorActionPreference = "Stop"`, and the mismatch `Fail` sat
  inside the `try` whose `catch` printed "Could not verify Node
  checksum; continuing". Only the fetch stays inside that `try` now.
  The fetch also passes `-UseBasicParsing`, so Windows PowerShell 5.1
  without the IE engine is refused for missing evidence only, never
  for a parser it lacks.
- The optional Chinese font for deck preview counted an empty digest
  (no hash tool) as a match. It now compares the digest directly, as
  the LibreOffice download already did, so an unchecked face is
  skipped with the existing warning and the install carries on.

Unchanged and out of scope: the uv bootstrap (astral.sh) and the raven
wheels are not hash-pinned, and SHASUMS256.txt comes from the same
origin as the tarball over HTTPS, so its signature is not checked.

Context: requirement 1 of the external review in
WenyuChiou/awesome-agentic-ai-zh#289.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run in a worktree. The head `902e351` sits on `3632e6040`; the six
commits `main` gained while this branch was in flight touch none of the
three files it changes. The test-first and mutation runs below were
taken before that rebase, on `5be9698a1`; the full suite and the
installer test file (with pwsh) were re-run at the head.

```
uv run --frozen --all-extras pytest tests/test_install_script.py -k "node_download or cannot_be_hashed"
PATH=<pwsh 7.6.5>:$PATH uv run --frozen --all-extras pytest tests/test_install_script.py -k windows_node_download
PATH=<pwsh 7.6.5>:$PATH uv run --frozen --all-extras pytest tests/test_install_script.py --idle-ceiling-strict
PATH=<pwsh 7.6.5>:$PATH uv run --frozen --all-extras pytest -q
```

- Tests first, against the unmodified scripts: the first command gave
  4 failed (install.sh unreachable, not listed, no hash tool; the font
  with no hash tool) while the mismatch and matching cases passed. The
  second gave 3 failed (mismatch, unreachable, not listed) and 1
  passed. After the change both selections pass.
- One-construct mutations of `install.sh` against the new tests:
  dropping the no-hash-tool refusal, the not-listed refusal, the
  unreachable refusal, the staged-download cleanup, or the font's
  direct comparison each turned exactly one test red; a control that
  skips extraction turned the matching-digest test red.
- The installer test file under `--idle-ceiling-strict`: 54 passed,
  1 failed; without pwsh, 50 passed, 4 skipped, 1 failed. The failure
  is `test_resolve_node_dir_answers_each_case_it_exists_for`, which
  fails the same way on the base on this machine: its fixture PATH
  includes `/usr/bin`, which holds an npm here. It stubs
  `provision_private_node`, so this change cannot reach it.
- Full suite at the head, pwsh on PATH: 27560 passed, 7 failed, 115
  skipped in 350.94 s. The seven are this machine's standing failures
  on `main`: five proxy tests in
  `tests/test_config_update_providers.py` (the shell carries a proxy),
  the node-dir test above, and one that fails when run as root:

`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
- Live network: the extracted `install.sh` functions provisioned
  v22.23.3 from nodejs.org, verified it against the published
  SHASUMS256.txt, ran it, and left no staged download, in 6 s.
- `dash -n` and `bash -n` on `install.sh`: clean. The PowerShell
  parser over `install.ps1` on this branch and on the base: 0 errors
  each. `ruff check` and `ruff format --check` on the test file:
  clean.
- Not verified here: `install.ps1` has not run on Windows, and
  `-UseBasicParsing` matters only to Windows PowerShell 5.1, which no
  test exercises. CI does not close that gap: the two installer jobs
  find Node v22.23.3 already on their runners, so neither reaches the
  private-Node download this change touches.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No user-facing doc describes the checksum behaviour, so none changed.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

A machine without Node.js >= 22 that cannot fetch the release's
SHASUMS256.txt, or that has neither sha256sum nor shasum, used to get
an unverified runtime with a warning; it now gets an error and the
hint above. A system Node >= 22 never downloads anything and is
unaffected. On the build-time path (a system node without npm) the
download was already subshelled or caught, so a refusal there skips
the TUI and page builds with the existing warning rather than ending
the install. The font step changes only on a machine with no hash
tool. Both scripts are served from `main`, so the change reaches new
installs at merge, and reverting this commit rolls it back the same
way.

## Related Issues

N/A in this repository. External:
WenyuChiou/awesome-agentic-ai-zh#289 (requirement 1, once a tagged
release carries this).

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-08 15:08:06 +08:00
KT
c3e9305864
fix(cli): keep the working directory off sys.path when the page starts its engine (#776)
## Summary

`raven web` starts its supervisor and the engine under it as `python -m
raven ...`, and `-m` puts the working directory first on `sys.path`.
Started from inside a source checkout, the installed raven came up
running that checkout's code on the release environment's dependencies,
and the detached supervisor, which keeps that directory for as long as
the page is up, did it again on every restart. Verified consequences:
the checkout's config migrations ran against the user's real
`~/.raven/config.json`; a checkout importing a dependency the wheel
lacks crash-looped the supervisor; the page fell back to
`<repo>/ui-web/dist`. The released 0.2.0 carries the same three
launches.

Changes:

- `raven/cli/serve_commands.py`: pass `-P` (PYTHONSAFEPATH) on all three
launches, so the child imports the raven installed beside its
interpreter. Editable installs still resolve through their `.pth` entry.
- `install.sh`: `launch_web` moves to the home directory before the
closing `raven web --stop` / `--foreground`, so an install run from
inside a clone does not start the just-installed release on the clone's
source. The installer is served from main, so this also covers 0.2.0
installs.
- `install.ps1`: the same move in `Start-Web`, restored afterwards with
`Pop-Location` because under `irm | iex` the script runs in the caller's
own shell. Reviewer note: no PowerShell is available on the author's
machine, so this file is checked by text assertions only.
- Tests (`tests/test_cli_serve_commands.py`,
`tests/test_install_script.py`): the argv pins expect `-P`; a decoy
`raven` package under the working directory shows the bare interpreter
shadows and the guarded one does not; the supervisor launch is pinned
too; the `install.sh` harness records where the page was started from,
and a text pin covers both installers.

Out of scope, noted for later: the `/restart` path in
`gateway_commands.py` re-execs `[sys.executable] + sys.argv`, which
under `-m` switches to script mode; different mechanism, not touched
here. The sub-agent launchers (`agents/*/run.py`) also run `python -m
raven`, but each pins its working directory to the agent's own folder,
which holds no `raven` package, so they are not exposed.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests/test_cli_serve_commands.py tests/test_install_script.py -q
```
169 passed.

Mutation check: removing `-P` from `_gateway_argv` fails 2 of the new
tests, removing it from `_spawn_supervisor` fails 1, and removing the
`cd` from `install.sh` fails 2; restoring each brings all 7 back to
green.

Real-environment probe, with the 0.2.0 wheel installed as a uv tool into
a scratch `UV_TOOL_DIR` and a raven checkout as the working directory:

```
cd <checkout> && <UV_TOOL_DIR>/raven/bin/python -c "import raven; print(raven.__file__)"
# -> <checkout>/raven/__init__.py            (what the 0.2.0 launcher gets)
cd <checkout> && <UV_TOOL_DIR>/raven/bin/python -P -c "import raven; print(raven.__file__)"
# -> <UV_TOOL_DIR>/raven/lib/python3.12/site-packages/raven/__init__.py
```

```
uv run ruff check raven/cli/serve_commands.py tests/test_cli_serve_commands.py tests/test_install_script.py
uv run ruff format --check raven/cli/serve_commands.py tests/test_cli_serve_commands.py tests/test_install_script.py
sh -n install.sh
shellcheck install.sh
```
ruff clean; `sh -n` clean; shellcheck reports the same 3 pre-existing
findings as on main, none on the changed lines.

Full unit suite locally, on the final commit: 26203 passed, 3 failed.
All three are pre-existing and unrelated to this change:
`tests/test_rpc_files.py::test_a_host_without_libreoffice_says_so` fails
on any Mac with `/Applications/LibreOffice.app` (also on an untouched
main checkout);
`tests/test_shell_background.py::test_the_background_child_gets_the_baseline_env_not_the_host_env`
is flaky only under the full parallel run and passes alone;
`tests/test_runtime_checkpoint_deep.py::test_d5_perf_1k_files_commit` is
a `slow` perf bound (cold commit under 30s) that took 31.8s under the
full parallel run and passes alone in 27s on this branch and 26s on
main.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no
user-facing docs describe this path)

## Risk

Behaviour changes only for a page started from a directory that itself
contains a `raven` package, which is a source checkout. For every other
start the child resolves the same modules as before. `python -m raven`
from a checkout that was never installed would no longer import from the
working directory; that is not a supported way to run raven (`uv sync`
installs it editable).

The `install.ps1` edit has not been executed on Windows here, and the CI
installer job runs with `RAVEN_NO_LAUNCH=1`, so the launch step itself
is not exercised in CI on either platform; the harness test covers the
POSIX side.

Rollback: revert the commit. No data or config format is touched.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-24 17:02:39 +08:00
Zuyi Zhou
e358113493
fix: quiet source installer dependency export (#727)
## Summary

Add `-q` to the source installer's `uv export` command so dependency
requirements are written to the constraints file without flooding the
terminal.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `sh -n install.sh`: passed.
- `uv run pytest tests/test_install_script.py -q -x`: 32 passed.
- `make check-source-language`: passed.
- `git diff --check origin/main...HEAD`: passed.
- Compared real exports with and without quiet mode: stdout decreased
from 753 lines to zero; dependency contents were identical with command
headers excluded.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No documentation or screenshot change is needed for quieter installer
output.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

Only export verbosity changes; dependency selection and the constraints
file remain intact. Revert the one-line change to restore verbose
output.

## Related Issues

N/A
2026-09-23 19:31:37 +08:00
Tchen-data
f178990780
fix: give the renderer a Han face rather than hoping the host has one (#668)
## Summary

Chinese in a deck came out as boxes (or as nothing) in the preview
panel, the delivery thumbnail, the template gallery, and the pages the
model renders to check its own work. LibreOffice reports success and the
PDF is well formed, so nothing flagged it.

Why, per platform:

- **Linux**: apt's `libreoffice` brings no CJK face.
- **macOS**: the system already ships Han faces (Songti, STHeiti,
Hiragino Sans GB, PingFang). Since 26.8 the macOS build renders headless
through a bundled fontconfig (`--enable-headless
--without-system-fontconfig` in `distro-configs/LibreOfficeMacOSX.conf`)
that looks for `/usr/local/etc/fonts/fonts.conf`, which an Apple Silicon
Mac does not have; without it that fontconfig lists 0 fonts, and a face
in `~/Library/Fonts` or a per-user fontconfig file is ignored. That is
why installing a font on a Mac never helped, and why the Macs that
worked had a CJK face copied into `LibreOffice.app` by hand.
openai/codex#32968 reports the same symptom from Codex's own
headless-only LibreOfficeDev build, whose fontconfig carries a
`/@..._OOO/etc/fonts` prefix; the cask build looks in
`/usr/local/etc/fonts`, so that thread's workaround is not the one
needed here.

What the PR does (the net diff; earlier commits on the branch tried
render-time detection, environment injection and then an
installer-written fontconfig file, and the later commits replace them):

1. **Linux font.** The LibreOffice offer installs `libreoffice
fonts-noto-cjk`. Where that did not run and `fc-list :lang=zh` is empty,
a pinned Noto Sans SC (size and sha256 checked before it is put in
place) goes into `~/.local/share/fonts` and `fc-cache` is rerun.
2. **macOS: the Mac's own faces, linked into LibreOffice's profile.**
LibreOffice always reads the `user/fonts` folder of the profile it runs
with. `office.link_han_faces(profile)` links Songti, STHeiti, Hiragino
Sans GB and PingFang (found under `AssetsV2` each time, so a link a
macOS update left dangling is replaced) into `profile/user/fonts`.
`office.to_pdf` does it for its throwaway profile (preview panel,
delivery thumbnail, template covers, ppt engine), the design engine for
its two profiles, and `ExecTool` for LibreOffice's default profile,
which the model's own `soffice --convert-to` uses. No download, no
password, nothing written outside the user's home, and it reaches users
who upgrade without rerunning `install.sh`.
3. **LibreOffice on a Mac without Homebrew.** This used to be a warning
and no preview at all. The installer now fetches the release dmg
(26.8.0, sha256 pinned per arch, from the stable directory and then the
archive), mounts it read-only, copies `LibreOffice.app` into
`/Applications` or `~/Applications`, never over an existing app, and
writes a two-line `~/.local/bin/soffice` launcher the way the cask does.
A failed `brew install` falls back to it too.
4. **Finding it.** `office.find_soffice` falls back to the launcher
inside `LibreOffice.app` in either Applications folder when nothing is
on PATH; the design engine now asks the same resolver.
5. **Stale renders.** The pdf-preview and deck-template cover cache keys
mix in `office.RENDER_GENERATION` (3), which retires every picture drawn
before this change. The Linux font step also clears both caches whenever
it installs a face.

Removed relative to earlier revisions: `raven/utils/fonts.py`
(`render_env`, `han_face`, `can_draw_han`, `host_han_faces`,
`install_hint`; several were never called), the exec-environment
wrapping, the ppt-engine face lookup, and the installer's sudo-written
`/usr/local/etc/fonts/fonts.conf`.

Known limits:

- A `soffice` run with a profile raven did not prepare (a caller passing
its own `-env:UserInstallation`) gets no faces on a Mac.
- A `deck.pdf` rendered beside a deck before the fix is still preferred
by the viewer until the deck is re-rendered or touched.
- Verified on macOS 15.7.1 arm64, and by review on macOS 26.5 arm64
(LibreOffice 26.8.0.3 from the cask); macOS 14 and Intel Macs have not
been run.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

macOS 15.7.1 arm64, LibreOffice 26.8.0.3 run from the stock dmg (no CJK
face in its bundle), fontconfig handed an empty configuration (so no
`fonts.conf` of any kind), HOME pointed at an empty directory:

- `main`: the model's own `soffice --convert-to` (default profile, after
building an `ExecTool`), `pdf_preview.pdf_for` / `png_for`, the ppt
engine's `to_pdf` and the design engine's `LibreOfficeBackend` each
embedded only Carlito and LinuxLibertineG (`pdffonts`).
- This branch: the same four paths each embedded PingFangSC, STHeitiSC
and STSongti-SC; the default profile held links to the five faces.
- No-Homebrew path, with PATH stripped of `/opt/homebrew`, an empty HOME
and a read-only Applications folder: the step downloaded the dmg,
matched its digest, installed into `~/Applications` (`codesign --verify
--deep --strict` valid, `spctl --assess` accepted) and wrote the
launcher; a second run downloaded nothing.
- Linux (container with every CJK face hidden): the font step downloaded
Noto Sans SC and the render embedded NotoSansSC; a second run did
nothing.
- `uv run --frozen --all-extras pytest -q tests/test_utils_office.py
tests/test_install_script.py
tests/test_design_engine_rendering_office.py
tests/test_rpc_deck_templates.py tests/test_shell_background.py
tests/test_ppt_engine_render_service.py`: 142 passed, 1 skipped.
- `uv run --frozen lint-imports`: 10 kept, 0 broken. `ruff check` /
`ruff format --check` on the changed files: clean. `shellcheck -s sh
install.sh`: no new findings. `scripts/check_source_language.py`: pass.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no docs
describe this step)

## Risk

- [x] Security impact considered: the dmg and the font are checked
against pinned sha256 digests before use; the macOS change only creates
symlinks under LibreOffice profiles in the user's home, never replaces a
real file there, and runs no privileged command.
- [x] Backward compatibility considered: Linux hosts that already have a
CJK face are untouched; on a Mac, a profile that already holds its own
fonts keeps them. The cache-key bump costs one re-render.
- [x] Rollback path is clear for risky changes: deleting the links in
`~/Library/Application Support/LibreOffice/4/user/fonts` returns
LibreOffice to its previous behaviour; reverting the PR restores the old
installer.

User-visible: a Mac without Homebrew downloads about 300 MB of
LibreOffice once; nothing asks for a password.

## Related Issues

N/A

---------

Co-authored-by: litong <litong02@shanda.com>
Co-authored-by: Claude (claude-opus-4-6) <noreply@anthropic.com>
Co-authored-by: KT <74288668+0xKT@users.noreply.github.com>
2026-09-23 19:10:53 +08:00
zhanghui
c9ea7c570c
fix(core): the memory service stops holding up the first session (#630)
## Summary

Two changes against the same symptom: the first session after an install
waits
on the memory service and then runs without long-term memory anyway.

**The wait is unnecessary.** A resident host awaited `backend.start()`
at boot,
so it held for the readiness budget -- 10s -- before serving anything.
The
backend already has a state machine for exactly that window: `store`
answers
False so the loop retries the record, and `recall` returns no hits for
that turn
and schedules a probe. Waiting for the service before serving the first
turn is
what the state machine replaced everywhere else.

`plugin_stack.start_backend_detached` is the same shape as
`warm_up_in_background` for litellm: a resident process starts the slow
thing
once and goes on serving, and the on-demand path reports a failure to
whoever
needs it. Three callers take it -- the gateway at boot and at a
generation swap,
and `raven a2a serve`. The other three keep awaiting, because for them
there is
no later turn to recover into: an import checks readiness immediately, a
sub-agent writes one record, and a one-shot turn exits. It is retired in
`Runtime.dispose`, the single point both resident hosts go through.

**The wait was also far longer than its budget.** uv does not compile
bytecode
by default, so the first process to import a module compiles it, and for
raven
that process is the EverOS service the first session starts. Measured on
a fresh
isolated install: 22s from spawn to ready, of which 18s elapses before
the
service writes its first log line. `UV_COMPILE_BYTECODE=1` in the
installer
moves that into the install, where the user is already watching a
progress line.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Measured on a throwaway install in an isolated `RAVEN_HOME` /
`UV_TOOL_DIR` /
`UV_TOOL_BIN_DIR`, built from this checkout:

- cold first start, as shipped today: 22s spawn to ready (readiness
budget 10s)
- second start against the same tree: 2.2s
- freshly scaffolded root, bytecode already compiled: 2.1s
- byte-compiling the rest of that tree: 13.9s for 16756 files, single
threaded,
  so the cost is compilation and it is paid once per machine

The detached start was read at the layer that owns the ordering, the
gateway's
own log. Before this change `Page:` cannot appear until after
`everos server ready`; after it:

```
17  EverosBackend.start
20  Page: http://127.0.0.1:18894
28  started everos server
31  everos server ready
```

The page is serving at line 20 and the child is only spawned at line 28.
The
interval this removes from the boot measured 5.5s on a machine whose
bytecode is
already compiled.

Commands:

- `uv run --frozen --python 3.12 --all-extras pytest
tests/test_core_plugin_stack.py tests/test_core_runtime_swap.py
tests/test_cli_gateway_commands.py tests/test_cli_a2a_commands.py
tests/test_cli_import_commands.py tests/test_memory_backend_protocol.py
-q` -- 191 passed after the rebase onto main
- the same set plus `tests/test_everos_backend.py` and
`tests/test_core_runtime_eval_hooks.py` -- 364 passed
- `ruff check raven/ tests/` -- all checks passed
- `ruff format --check raven/ tests/` -- 1654 files already formatted
- `sh -n install.sh` -- clean

Each of the six new cases was mutated to confirm it can fail: dropping
the task
reference, dropping the done-callback, making the cancel a no-op, and
removing
the cancel from `dispose`. Every mutation turned the case that names
that
behaviour red, and the source was restored and hash-compared 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 change: a resident host now serves its first turn before
the memory
service has answered. A turn that arrives in that window gets no recall,
and its
record is retried rather than lost. Previously the host waited and, when
the wait
overran, that session had no memory at all -- so the window is narrower
than what
it replaces, not wider.

The installer now compiles bytecode, which makes an install slower by
roughly the
compile time and larger by the `.pyc` tree.

Rollback: both commits are independent and revert cleanly. Reverting the
first
restores the awaited start; reverting the second restores the uncompiled
install.

- [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>
2026-09-22 15:46:12 +08:00
zhanghui
010ca4b44d
fix(*): probe raven web before launch and install plugins from the release list (#588)
## Summary

The one-line installers are served from `main` and install the latest
published release, so an ending on `raven web` (PR #476) shipped against
v0.1.13, which has no `web`: since 2026-09-17 every `curl
raven.evermind.ai/install.sh | sh` has ended in `No such command 'web'`
with exit code 2. This PR fixes that class of failure and the upgrade
defect behind the next release.

- **Probe rule.** Every `raven <sub>` call in `install.sh` and
`install.ps1` is preceded by `raven <sub> --help`. When the probe fails
the install ends on the one command every release has (`raven`), and
neither the stop nor the page's own exit code becomes the script's.
`RAVEN_NO_LAUNCH=1` skips the launch (CI, Dockerfiles); the PATH hint
the launch displaced is back.
- **The release says what it ships.** `release.yml` writes
`raven-plugins.txt`, one `name @ url` line per plugin wheel it just
built, beside the wheel and the constraints. Both installers derive
every URL from the release page redirect and hand the list to `uv tool
install --with-requirements`. No GitHub API call, no grepping asset
names out of its JSON. A release without a list (0.1.13 and older)
installs raven alone, as it effectively did before.
- **Upgrade keeps the plugins.** uv replaces a tool's requirement set
with what one command names, so the old helper (`raven[channels]` only)
uninstalled every plugin the installer had put in. The helper now
installs from the same list, descends one loss at a time (engines, then
the memory plugin, then the channel extras), and refuses to run without
the list rather than install raven alone. `raven upgrade` on an
up-to-date install whose list names a plugin it lacks reinstalls the
version with its plugins. The helper also moves a beta wheel URL's
deploy token into the request header (urllib reads `user:token@host` as
a host name) and copies it onto the list's URLs for uv.
- **Gates.** CI installs the latest release with the PR's scripts,
piped, on ubuntu and windows whenever an installer changes. The release
job installs itself from `dist/` with `install.sh` before the draft is
created and asserts the three plugin packages and `web` on the result.
The beta publisher builds and lists the same three plugin wheels. A
contract test holds the release workflow, the beta publisher, both
installers (remote list and local clone mode) and the helper to one
plugin list.

Decisions, for the reviewer: the plugins are not published to PyPI and
no names are reserved there; the list carries direct URLs, so no plugin
is ever resolved by name against an index. The LibreOffice and chromium
steps in the scripts are unchanged. The three hosted-memory plugins
(mem0, zep, memos) are built and uploaded as before but stay off the
default list.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

All installs below ran piped (`cat install.sh | sh`) in isolated
directories (own HOME, UV_TOOL_DIR, UV_TOOL_BIN_DIR, UV_CACHE_DIR,
RAVEN_HOME) with `RAVEN_MINIMAL=1`.

- `main`'s `install.sh` against the live latest release (v0.1.13): exit
2, `No such command 'web'`. This branch's `install.sh`, same
environment: exit 0, `Raven installed. Open a new terminal ... then run:
raven`; `raven --version` prints 0.1.13. With `RAVEN_NO_LAUNCH=1`: exit
0.
- A local release directory built by `scripts/publish_beta.py` (`_build`
at 0.1.14b1: raven wheel, three plugin wheels, constraints, list): this
branch's `install.sh` with `RAVEN_WHEEL_URL=file://...` installs raven
0.1.14b1, `python -c "import raven_everos, raven_design, raven_ppt"`
succeeds in the tool venv, and the uv receipt lists raven plus the three
plugins.
- The release workflow's two new step bodies (`Write the plugin list`,
`Install the release from dist with install.sh`) extracted and run
locally against that build: exit 0; removing one plugin wheel makes the
list step exit 1.
- The script's ending against the 0.1.14b1 install: `raven web --help`
exit 0, `raven web --stop` exit 0 with nothing to stop, `raven web
--foreground --port 18999` answers `GET /` with HTTP 200 after about 20
seconds.
- `uv run raven upgrade` and `uv run raven upgrade --check` from the
checkout against live GitHub: `Raven 0.1.13 is up to date.`, exit 0.
- `uv run pytest tests/integration/test_cli_upgrade_real_uv.py`: 2
passed. The test now installs the old fixture `--with` a companion wheel
and asserts the companion survives the upgrade; against `main`'s helper
the same test fails on that assertion.
- `uv run pytest tests/test_install_script.py
tests/test_release_plugin_list.py tests/test_updates_upgrade.py
tests/test_publish_beta.py tests/test_cli_smoke.py`: all pass (37 + 6 +
188 on the last run of each).
- `uv run pytest` (full suite, before the last installer rewrite): 23543
passed, 121 skipped, 4 failed. The 4 (`test_agents_oncall_launcher`,
`test_agents_code_launcher`, `test_agent_loop_token_budget`,
`test_ppt_engine_image_search`) fail identically on plain `github/main`
in a separate worktree.
- `uv run ruff check` and `uv run ruff format --check` on every touched
Python file: clean. `sh -n install.sh`, `bash -n install.sh`: clean.
Both workflow files parse.
- Not run here: the new CI job's Windows leg and the release gate inside
GitHub Actions (this PR is their first run). `install.ps1` has no local
PowerShell to execute it; its changes mirror `install.sh` and are pinned
by the text tests.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible changes: the installers no longer fail on a release without
`web`; they print the plugins they install and a warning when a release
carries none; `raven upgrade` refuses to proceed when the target
release's plugin list cannot be fetched (previously it would install
raven alone and drop the plugins), and repairs an up-to-date install
that lacks listed plugins. The beta channel's next publish carries the
three plugin wheels and the list; a beta upgrade to a build published
before this change will refuse for lack of a list, and rerunning the
beta installer is the remedy.

Rollback: revert the commit. Releases published with `raven-plugins.txt`
keep working with the old scripts, which ignore the file.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-21 16:25:33 +08:00
Kevin Hu
de3870a5b7
feat(installer): the installers end on a running page and rebuild what moved on (#476)
## 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>
2026-09-17 06:21:34 -07:00
0xKT
e6f073291c fix(*): a failed tty read declines the office offer
The reviewer's follow-up named the exact gap: read failing is not the
same event as a deliberate empty Enter, and with a default-yes prompt
the difference is consent. Ctrl-D at the prompt, or a terminal lost
after the openability gate passed, used to fall into the yes arm and
attempt sudo; the read's failure branch now warns and returns, so only
an answer actually read -- including a deliberate bare Enter -- can
accept. A tripwire pins the failure branch.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-12 01:00:54 +08:00
0xKT
a27559e331 fix(*): the final audit closes consent, tty truth, and the cache lies
An adversarial last pass over the whole branch found what the review
rounds had not. Consent first: the sh decline arm matched only bare n/N,
so a typed "no" installed LibreOffice through sudo; the arm now takes
the word too, and a tripwire pins the default-yes prompt in both
installers so the review-round decision cannot silently flip back. The
tty gate probed existence where openability is the truth -- the node
exists in CI, cron and docker -t without -i -- so the gate now opens it,
and a consoleless run skips instead of defaulting yes or hanging.
install.ps1 finally carries the everos memory wheel through both of its
paths with sh's own rung discipline, so the Windows summary's memory row
can be green at all. The two cache resolvers follow playwright's real
lookups (XDG_CACHE_HOME, LOCALAPPDATA, chrome-win64 layouts), a
non-object registry degrades instead of raising, and the four mouths
that name a fix now say the same runnable thing on every platform.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-12 00:50:35 +08:00
0xKT
1d37a81a0f fix(*): the review round closes the linux64 layout, wrap-proof tests, office default
Three findings from review, one wave. The per-user cache patterns learn
chromium-*/chrome-linux64/chrome -- the layout playwright 1.62 actually
installs on Linux and the one the VM group already knew -- so doctor and
the design renderer stop disagreeing about a machine the new installer
just set up. The two doctor assertions that read a literal path fragment
out of rendered output now inject a wide console first, because xdist's
longer tmp paths cross Rich's 80-column default and split the token
mid-word. And the Linux LibreOffice offer defaults to yes with the
consequence spelled out in the prompt, matching what macOS already does
silently: for the deck lane this is the one dependency that matters, and
sudo's own password prompt still stands between Enter and any change;
install.ps1 mirrors the same default and wording.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-11 23:48:28 +08:00
0xKT
5b84e24782 feat(*): install.sh delivers the browser, offers LibreOffice, then reports
An install used to end with three optional capabilities silently off:
the chromium binary nobody downloaded, LibreOffice nobody mentioned at
install time, and no way to see either. The installer now finishes the
job it can finish alone -- the tool venv's own python runs playwright
install chromium, probed first because a pinned wheel URL or the
release-page fallback installs no engines -- and offers what needs the
operator: LibreOffice lands directly through brew on macOS, and on Linux
only after a yes read from /dev/tty, since under curl|sh stdin is the
script itself and sudo's prompt needs the terminal too. Every new step
degrades to one warning line; RAVEN_MINIMAL=1 skips both installs. The
tail then prints raven doctor --install-summary either way, so what
landed and what is still missing is the last thing an installer run
says. Tripwires pin the tty reads, the skip switch, and that the new
code stays above the closing block another test owns.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-11 23:48:28 +08:00
0xKT
ed7ddd61b5 feat: refresh image model presets and default to sunburst
## Summary

Add GPT Image 2.5 Sunburst and Flare to the image model picker, with Sunburst selected when no model is configured. Remove Nano Banana 2 from the recommended list while retaining custom model entry.

Order presets by GPT Image 2.5 (Sunburst, Flare), GPT Image 2 (low, medium, high), Seedream (Lite, Pro), Qwen Image (3, 3 Pro), and Grok Image. Use provider-default quality for the new variants when no quality is supplied; retain the GPT Image 2 medium default and explicit settings precedence.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Python commands used UV_PROJECT_ENVIRONMENT=../raven/.venv; script checks also used PYTHONPATH=.

- `uv run --no-sync pytest tests/test_media_gen_tool.py -q -n0`: 64 passed.
- `npm test --prefix ui-web -- src/features/settings/SettingsPage.test.tsx`: 52 passed.
- `npm run type-check --prefix ui-web`: passed.
- `uv run --no-sync ruff check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync ruff format --check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_source_language.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_large_files.py origin/main..HEAD`: passed.
- `git diff --check origin/main..HEAD`: passed.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No separate documentation or screenshot update was needed for this preset-list change.

## Risk

Existing explicit model and quality settings remain in effect. A saved Nano Banana 2 model is shown as a custom entry. When neither settings nor a tool argument supplies quality, GPT image variants other than GPT Image 2 now use the provider default instead of an implicit medium setting; output quality and cost may therefore change. No credentials, permissions or endpoints change. Revert this change to restore the prior list and implicit quality behavior.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:59:46 +00:00
daoxize1
a178d7bd69 feat: refresh image model presets and default to sunburst
## Summary

Add GPT Image 2.5 Sunburst and Flare to the image model picker, with Sunburst selected when no model is configured. Remove Nano Banana 2 from the recommended list while retaining custom model entry.

Order presets by GPT Image 2.5 (Sunburst, Flare), GPT Image 2 (low, medium, high), Seedream (Lite, Pro), Qwen Image (3, 3 Pro), and Grok Image. Use provider-default quality for the new variants when no quality is supplied; retain the GPT Image 2 medium default and explicit settings precedence.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Python commands used UV_PROJECT_ENVIRONMENT=../raven/.venv; script checks also used PYTHONPATH=.

- `uv run --no-sync pytest tests/test_media_gen_tool.py -q -n0`: 64 passed.
- `npm test --prefix ui-web -- src/features/settings/SettingsPage.test.tsx`: 52 passed.
- `npm run type-check --prefix ui-web`: passed.
- `uv run --no-sync ruff check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync ruff format --check raven/agent/tools/media_gen.py tests/test_media_gen_tool.py`: passed.
- `uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_source_language.py origin/main..HEAD`: passed.
- `uv run --no-sync python scripts/check_large_files.py origin/main..HEAD`: passed.
- `git diff --check origin/main..HEAD`: passed.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No separate documentation or screenshot update was needed for this preset-list change.

## Risk

Existing explicit model and quality settings remain in effect. A saved Nano Banana 2 model is shown as a custom entry. When neither settings nor a tool argument supplies quality, GPT image variants other than GPT Image 2 now use the provider default instead of an implicit medium setting; output quality and cost may therefore change. No credentials, permissions or endpoints change. Revert this change to restore the prior list and implicit quality behavior.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:59:46 +00:00
0xKT
afcc0b0014 feat(*): open a .pptx in the file viewer as a PDF the gateway renders
## Summary

Clicking a .pptx in the workspace file view gave the binary note and an open-with
offer, which is nothing on a remote gateway. It now shows the deck: the gateway renders
the file to PDF and the viewer frames it, in the same unsandboxed frame that made
Chromium's PDF viewer work.

The cheap path first. A deck published by the engine already has its PDF beside it, so
when a .pdf sits next to the .pptx and is no older, that file is served and no
conversion runs. Otherwise the result is cached under the raven state directory, keyed
by resolved path, size and mtime, so a rebuilt deck re-renders and a second click is a
cache read. Only then does soffice run, headless with a throwaway profile, in its own
process group with a timeout that kills the group, and success is judged by whether the
output file appeared rather than by an exit code. One lock per key means a double click
never starts two conversions.

Failures are told apart rather than collapsed: no LibreOffice is 503, a timeout is 504,
a run that produced nothing is 500, and the reason reaches the pane as text the reader
can act on. The request goes through the same token URL and the same resolve_readable
fence as any other file, and only a .pptx may ask for a rendering.

## Type

- [x] Feature

## Verification

- `uv run --frozen pytest tests/test_rpc_transport.py tests/test_rpc_files.py -q` ->
  51 passed, 11 of them new: the rendering and its headers, a cache hit, a stale mtime
  re-rendering, the beside-PDF shortcut when newer and when older, a double click
  converting once, no output as 500, a hang as 504 leaving no cache entry, no
  LibreOffice as 503, a non-deck path as 400, and no session as 401
- `npm run type-check` and `npx vitest run` -> 1487 passed; `npm run build` succeeds
- Real check with a real deck and real soffice: an 8-page deck rendered cold in 2.9 s to
  a PDF whose byte count matches the one the engine publishes, pdfinfo reports 8 pages,
  a cache hit answers in 0.2 ms, and the beside-PDF path answers in 1.6 ms
- Clicked in full Chromium against a live gateway: both a deck with a PDF beside it and
  a template without one open in the browser's own PDF viewer with page count, zoom and
  thumbnails

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally

## Risk

New behaviour on a file kind that previously rendered nothing; a .pdf, an image and
every other kind are untouched. The conversion runs where the gateway runs and is
bounded by a timeout and a per-key lock. The cache lives under the state directory and
drops entries untouched for seven days. Rollback is the revert, and the cache directory
can be deleted.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:59:07 +00:00
Tchen
3245a050e0 feat(*): open a .pptx in the file viewer as a PDF the gateway renders
## Summary

Clicking a .pptx in the workspace file view gave the binary note and an open-with
offer, which is nothing on a remote gateway. It now shows the deck: the gateway renders
the file to PDF and the viewer frames it, in the same unsandboxed frame that made
Chromium's PDF viewer work.

The cheap path first. A deck published by the engine already has its PDF beside it, so
when a .pdf sits next to the .pptx and is no older, that file is served and no
conversion runs. Otherwise the result is cached under the raven state directory, keyed
by resolved path, size and mtime, so a rebuilt deck re-renders and a second click is a
cache read. Only then does soffice run, headless with a throwaway profile, in its own
process group with a timeout that kills the group, and success is judged by whether the
output file appeared rather than by an exit code. One lock per key means a double click
never starts two conversions.

Failures are told apart rather than collapsed: no LibreOffice is 503, a timeout is 504,
a run that produced nothing is 500, and the reason reaches the pane as text the reader
can act on. The request goes through the same token URL and the same resolve_readable
fence as any other file, and only a .pptx may ask for a rendering.

## Type

- [x] Feature

## Verification

- `uv run --frozen pytest tests/test_rpc_transport.py tests/test_rpc_files.py -q` ->
  51 passed, 11 of them new: the rendering and its headers, a cache hit, a stale mtime
  re-rendering, the beside-PDF shortcut when newer and when older, a double click
  converting once, no output as 500, a hang as 504 leaving no cache entry, no
  LibreOffice as 503, a non-deck path as 400, and no session as 401
- `npm run type-check` and `npx vitest run` -> 1487 passed; `npm run build` succeeds
- Real check with a real deck and real soffice: an 8-page deck rendered cold in 2.9 s to
  a PDF whose byte count matches the one the engine publishes, pdfinfo reports 8 pages,
  a cache hit answers in 0.2 ms, and the beside-PDF path answers in 1.6 ms
- Clicked in full Chromium against a live gateway: both a deck with a PDF beside it and
  a template without one open in the browser's own PDF viewer with page count, zoom and
  thumbnails

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally

## Risk

New behaviour on a file kind that previously rendered nothing; a .pdf, an image and
every other kind are untouched. The conversion runs where the gateway runs and is
bounded by a timeout and a per-key lock. The cache lives under the state directory and
drops entries untouched for seven days. Rollback is the revert, and the cache directory
can be deleted.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:59:07 +00:00
0xKT
11d2ce89c0 feat(ppt-engine): bundle two dark templates and clear the collisions they carried
## Summary

All eight bundled templates were light and the selection prompt told the model not to
choose a dark style, so a request for a dark technology look had nowhere to go: it
landed on a light template and came out mixed. Two dark 16:9 templates cut from user
uploads join the catalogue, and the prompt now takes one when the request asks for a
dark, black or night look or a technology register.

Both templates went through one pipeline: drop the hidden vendor pages, strip the
vendor marks D32 asks for, then borrow the roles each one lacked. What to borrow was
measured rather than guessed. All 37 reference pages were cloned onto the dark masters
and rendered, and the ones that came back with white type pinned on a run over a pale
fill, or with flat artwork that does not follow the theme, were dropped. The black
circuit deck takes 14 borrowed pages (34 in all), the green aurora deck 11 (28 in all),
and each declares its own reference pages for other decks to borrow.

Three collision fixes ride along, all found with the extractor the gate itself uses
rather than the one a hand check reaches for first:

- The black deck's cover and agenda carried a two-layer title, the large English word
  behind the Chinese one, measured at 53 and 46 percent. The English layer is gone and
  the section numerals sit clear of their titles.
- On the investment-trend page the card titles were bottom-anchored, so a title that
  wraps grows upward into the numeral row. They are top-anchored now, the title box is
  budgeted against the numeral above and the body below, and titles of one, two and
  three lines were rendered and measured. The green deck borrowed that page, so it had
  the same defect and the same fix.
- gold_panel_year_end_summary holds a text box whose entire content is a single 12pt
  period on five of its pages. Nothing shows -- a render before and after differs by 16
  pixels out of 921,600 -- but the extractor sees a 3pt box inside a line of body copy
  and reports up to 98 percent overlap, and word_collision refuses a deck. Any deck
  cloning one of those pages was refused for a mark no reader can see. That template
  goes from 17 blocking pairs to none.

The payload changed, so all ten files are uploaded as package version 2026.09.09 and
the manifest endpoint names it, which is what the manifest asks for: a new cut is a new
version rather than files replaced under the old one.

## Type

- [x] Feature

## Verification

- `uv run --frozen --extra dev pytest tests/test_ppt_engine_default_templates.py
  tests/test_ppt_engine_templates.py tests/test_ppt_engine_skill.py -q` -> 92 passed
- `fetch_templates.py --verify` -> all 10 pins hold; and after emptying the assets
  directory, `fetch_templates.py` refetched all ten from the registry and every pin held
- Collision sweep with `services.measure.words.words_from_pdf` over every page of both
  dark templates and of gold_panel: no pair at or above 30 percent
- Every page of both templates was rendered and looked at, and the changed pages were
  rendered again at 200 dpi and inspected as crops

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally

## Risk

Behaviour change: a brief asking for a dark or technology look now binds a dark
template instead of a light one. Decks that named a template by filename are unaffected.
The two dark templates carry Chinese placeholder copy like the other eight.

The manifest endpoint moved to 2026.09.09. A checkout that fetched templates before
this lands has the old bytes; `make fetch-templates` refreshes them. Rollback is the
previous endpoint and pins, and 2026.09.03 is still in the registry.

- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:58:24 +00:00
Tchen
7e3749121d feat(ppt-engine): bundle two dark templates and clear the collisions they carried
## Summary

All eight bundled templates were light and the selection prompt told the model not to
choose a dark style, so a request for a dark technology look had nowhere to go: it
landed on a light template and came out mixed. Two dark 16:9 templates cut from user
uploads join the catalogue, and the prompt now takes one when the request asks for a
dark, black or night look or a technology register.

Both templates went through one pipeline: drop the hidden vendor pages, strip the
vendor marks D32 asks for, then borrow the roles each one lacked. What to borrow was
measured rather than guessed. All 37 reference pages were cloned onto the dark masters
and rendered, and the ones that came back with white type pinned on a run over a pale
fill, or with flat artwork that does not follow the theme, were dropped. The black
circuit deck takes 14 borrowed pages (34 in all), the green aurora deck 11 (28 in all),
and each declares its own reference pages for other decks to borrow.

Three collision fixes ride along, all found with the extractor the gate itself uses
rather than the one a hand check reaches for first:

- The black deck's cover and agenda carried a two-layer title, the large English word
  behind the Chinese one, measured at 53 and 46 percent. The English layer is gone and
  the section numerals sit clear of their titles.
- On the investment-trend page the card titles were bottom-anchored, so a title that
  wraps grows upward into the numeral row. They are top-anchored now, the title box is
  budgeted against the numeral above and the body below, and titles of one, two and
  three lines were rendered and measured. The green deck borrowed that page, so it had
  the same defect and the same fix.
- gold_panel_year_end_summary holds a text box whose entire content is a single 12pt
  period on five of its pages. Nothing shows -- a render before and after differs by 16
  pixels out of 921,600 -- but the extractor sees a 3pt box inside a line of body copy
  and reports up to 98 percent overlap, and word_collision refuses a deck. Any deck
  cloning one of those pages was refused for a mark no reader can see. That template
  goes from 17 blocking pairs to none.

The payload changed, so all ten files are uploaded as package version 2026.09.09 and
the manifest endpoint names it, which is what the manifest asks for: a new cut is a new
version rather than files replaced under the old one.

## Type

- [x] Feature

## Verification

- `uv run --frozen --extra dev pytest tests/test_ppt_engine_default_templates.py
  tests/test_ppt_engine_templates.py tests/test_ppt_engine_skill.py -q` -> 92 passed
- `fetch_templates.py --verify` -> all 10 pins hold; and after emptying the assets
  directory, `fetch_templates.py` refetched all ten from the registry and every pin held
- Collision sweep with `services.measure.words.words_from_pdf` over every page of both
  dark templates and of gold_panel: no pair at or above 30 percent
- Every page of both templates was rendered and looked at, and the changed pages were
  rendered again at 200 dpi and inspected as crops

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally

## Risk

Behaviour change: a brief asking for a dark or technology look now binds a dark
template instead of a light one. Decks that named a template by filename are unaffected.
The two dark templates carry Chinese placeholder copy like the other eight.

The manifest endpoint moved to 2026.09.09. A checkout that fetched templates before
this lands has the old bytes; `make fetch-templates` refreshes them. Rollback is the
previous endpoint and pins, and 2026.09.03 is still in the registry.

- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:58:23 +00:00
0xKT
1feda5a868 fix(ui-web): the sub-agent rosters draw each agent its brand, not its initial
## Summary

Brand marks for the third-party sub-agent roster landed with the desk palette's
grouped list and reached neither of the other two agent surfaces. This closes
both.

- The sub-agents page drew a coloured initial taken from the row's name, so
  every agent was a letter in a tinted square.
- The conversation panel's flat instance list drew a status dot and nothing
  saying which agent ran the row -- it has no agent headings, so the identity
  was simply absent.

Both now render through the existing `AgentMark`, which means a preset gets its
vendor's mark and a row without a preset gets the generic glyph. Two decisions
worth stating:

**Keyed on the preset, never on the row's name.** A configured row's name is
the reader's to change, so a renamed agent keeps its brand, and a hand-written
row that merely spells itself like a preset gets none. What a row draws is a
fact about the package behind it.

**A row with no preset keeps the generic glyph** rather than an initial or a
raven mark. That covers the agents shipped under the product tree and anything
the reader wrote themselves; their names sit beside the mark and do the
distinguishing.

Enabling this needed one contract change: `SetupRow` declared its `tile` as a
boolean, which can ask for the letter tile or for nothing and cannot carry a
mark. It now takes a node, the same shape `SheetHead` already declared, so a
row and the sheet it opens can take the one mark. The predicate resolves
against `undefined` rather than truthiness, because "draw no tile" and "draw
the default tile" are different answers that a truthiness test reads as one.
All three existing call sites are unaffected: two pass nothing and keep the
letter tile, one passes `false` and keeps its tile-less grid.

`.pmtile` is sized per container, so a mark standing in for one takes that
container's geometry or it renders at its own roster default. Two containers
size a tile a mark can occupy: the roster row, whose grid also places the cell,
and the detail card's header at 46px against the row's 28px. Both are covered,
and a stylesheet contract reads the expected box off each tile's own rule
rather than restating it, so a slot whose tile is resized takes its mark with
it. That contract lives with the other stylesheet guards because no DOM test
can see this -- happy-dom applies no stylesheet, and the failure is silent: the
mark simply renders small. A mark drawn where no tile is sized, such as the
desk's roster head or an instance row, keeps the roster default and is correct
there.

### Checked and deliberately not changed

- **The desk palette's own instance children.** Their group head carries the
  agent's mark two lines above them, so a per-child copy repeats it.
- **A numeric tile node.** `tile={0}` would take the tile-less grid and still
  render the character. No call site does this and a number is not a mark; the
  falsy-node path exists for `false` and `null`.
- **The panel's roster filter.** The conversation-side roster is filtered to
  enabled agents, so the brand marks there become visible only once a
  third-party agent is connected. That filter predates this change and is
  deliberate; it is why the sub-agents page is where the change is immediately
  visible.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

All commands run at the rebased head.

Web unit tests, every test file this branch touches plus the two pre-existing
`SetupRow` consumers, whose contract it changes:

```
npx vitest run src/features/xa/XaPage.test.tsx \
  src/features/subagents/SubagentsPage.test.tsx src/shell/agent-mark.test.tsx \
  src/features/cron/CronPage.test.tsx src/features/connections/ConnPage.test.tsx \
  scripts/agent-mark-css.test.mjs
-> Test Files 6 passed (6), Tests 232 passed (232)
```

That is the 225 those files held before, plus the 7 added here. The two
pre-existing setup-row consumers are in the list because this changes the
`SetupRow` contract.

All seven new tests are load-bearing, proven in two parts.

The six markup tests: reverting only the four source files to the base and
re-running turns all six red.

```
npx vitest run src/features/xa/XaPage.test.tsx \
  src/features/subagents/SubagentsPage.test.tsx -t "brand"
-> Tests 6 failed | 134 skipped (140)
```

One of those six originally passed against the base, because "no brand mark" is
also true of a page that draws no marks at all. It now asserts the slot exists
and holds the generic glyph, which is what makes it fail without the fix.

The stylesheet contract: removing only the header's own mark rule, and nothing
else, turns it red naming the slot that lost its geometry.

```
-> AssertionError: .pmdhead sizes an agent mark too: expected +0 to be 1
```

The tree was restored after each and the suites re-run green.

Full web suite, compared by failing test ID against the base in a separate
clean worktree, both runs through the same interpreter:

```
npx vitest run --reporter=json
-> base:   1494 tests, 1129 passed, 365 failed
-> branch: 1501 tests, 1136 passed, 365 failed
-> newly failing: 0    tests lost: 0    new tests: 7
```

The 365 are pre-existing on this machine and identical as a set on both sides
(node 26 with happy-dom, where `localStorage` is undefined in several suites).
Counts alone would not have shown that, which is why the comparison is by ID.

Python gates, which is what the pipeline runs, plus the test reaching the module
the new base changed:

```
uv run --frozen --python 3.12 --all-extras pytest -q \
  tests/test_ui_agent_marks.py tests/test_ui_css_token_gate.py \
  tests/test_tool_params_cast.py
-> 61 passed
```

Type, contract, lint and repository gates:

```
npx tsc --noEmit -p tsconfig.json          -> No errors found
npm run gen:check                          -> generated.ts matches the contract (162 methods)
node scripts/check-css.mjs                 -> OK (color literals confined to tokens)
uv run lint-imports                        -> Contracts: 9 kept, 0 broken
make check-source-language                 -> exit 0
make check-large-files                     -> exit 0
python scripts/check_commit_messages.py    -> exit 0
```

`lint-imports`, the css gate and the whole web suite are not run by this
project's pipeline, so they were run locally.

The toolchain was confirmed to have read the edited files rather than another
checkout's copy, since the web dependency tree is shared:

```
npx tsc --noEmit -p tsconfig.json --listFiles | grep -E "setuprow|XaPage|SubagentsPage"
-> three absolute paths, all inside the branch's own tree
```

Rendered check, driven through a real browser against the built bundle, since
the stylesheet is where happy-dom sees nothing:

- Light and dark theme, sub-agents page, a roster covering every mark in the
  table. Each third-party row draws its vendor's mark; the preset-less rows
  draw the generic glyph.
- Dark theme is where the tone corrections matter, and they survive the new
  size: the marks drawn in `currentColor` invert to readable, and the one mark
  that pairs a brand colour with an adaptive tone keeps its green rather than
  inverting to magenta.
- Measured geometry on the sub-agents page: every row mark 28 by 28 at the same
  offset with the tile's corner radius, every name starting at the same
  x whether or not the row has a preset, and no mark overflowing its row.
- Measured geometry on the detail card's header: 46 by 46 with the header's
  corner radius, matching what that container sizes a letter tile to and
  larger than the row mark that opens it.
- Measured geometry on the instance row: every mark 20 by 20 at the same
  offset, no overflow.

Known gap in that last item: the conversation panel's instance list is fed by a
session-scoped source that a static page cannot populate, so its geometry was
measured on the component's own markup under the real stylesheet rather than
through the live store. The markup itself is pinned by the added test, which
drives the real component and asserts the resolved mark per row.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Nothing to update: no user-facing document describes the roster's marks, and
this coins no domain term, so there is no `CONTEXT.md` entry to add.

## Risk

Presentation only. No wire shape, stored value, guard or dispatch path changes,
and nothing new is written to disk.

The one shared piece is `SetupRow`, used by three pages. Its `tile` widens from
a boolean to a node with the previous two behaviours preserved exactly, so the
schedules page keeps its tile-less grid and the entrances page keeps its letter
tile; both are covered by their own suites in the run above.

Rollback is reverting the two commits; nothing persists and no migration is
involved.

- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

Security is not applicable: no authentication, path resolution, credential or
network surface is touched.

## Related Issues

N/A
2026-09-10 02:57:10 +00:00
LivXue
3ecc81a091 fix(ui-web): the sub-agent rosters draw each agent its brand, not its initial
## Summary

Brand marks for the third-party sub-agent roster landed with the desk palette's
grouped list and reached neither of the other two agent surfaces. This closes
both.

- The sub-agents page drew a coloured initial taken from the row's name, so
  every agent was a letter in a tinted square.
- The conversation panel's flat instance list drew a status dot and nothing
  saying which agent ran the row -- it has no agent headings, so the identity
  was simply absent.

Both now render through the existing `AgentMark`, which means a preset gets its
vendor's mark and a row without a preset gets the generic glyph. Two decisions
worth stating:

**Keyed on the preset, never on the row's name.** A configured row's name is
the reader's to change, so a renamed agent keeps its brand, and a hand-written
row that merely spells itself like a preset gets none. What a row draws is a
fact about the package behind it.

**A row with no preset keeps the generic glyph** rather than an initial or a
raven mark. That covers the agents shipped under the product tree and anything
the reader wrote themselves; their names sit beside the mark and do the
distinguishing.

Enabling this needed one contract change: `SetupRow` declared its `tile` as a
boolean, which can ask for the letter tile or for nothing and cannot carry a
mark. It now takes a node, the same shape `SheetHead` already declared, so a
row and the sheet it opens can take the one mark. The predicate resolves
against `undefined` rather than truthiness, because "draw no tile" and "draw
the default tile" are different answers that a truthiness test reads as one.
All three existing call sites are unaffected: two pass nothing and keep the
letter tile, one passes `false` and keeps its tile-less grid.

`.pmtile` is sized per container, so a mark standing in for one takes that
container's geometry or it renders at its own roster default. Two containers
size a tile a mark can occupy: the roster row, whose grid also places the cell,
and the detail card's header at 46px against the row's 28px. Both are covered,
and a stylesheet contract reads the expected box off each tile's own rule
rather than restating it, so a slot whose tile is resized takes its mark with
it. That contract lives with the other stylesheet guards because no DOM test
can see this -- happy-dom applies no stylesheet, and the failure is silent: the
mark simply renders small. A mark drawn where no tile is sized, such as the
desk's roster head or an instance row, keeps the roster default and is correct
there.

### Checked and deliberately not changed

- **The desk palette's own instance children.** Their group head carries the
  agent's mark two lines above them, so a per-child copy repeats it.
- **A numeric tile node.** `tile={0}` would take the tile-less grid and still
  render the character. No call site does this and a number is not a mark; the
  falsy-node path exists for `false` and `null`.
- **The panel's roster filter.** The conversation-side roster is filtered to
  enabled agents, so the brand marks there become visible only once a
  third-party agent is connected. That filter predates this change and is
  deliberate; it is why the sub-agents page is where the change is immediately
  visible.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

All commands run at the rebased head.

Web unit tests, every test file this branch touches plus the two pre-existing
`SetupRow` consumers, whose contract it changes:

```
npx vitest run src/features/xa/XaPage.test.tsx \
  src/features/subagents/SubagentsPage.test.tsx src/shell/agent-mark.test.tsx \
  src/features/cron/CronPage.test.tsx src/features/connections/ConnPage.test.tsx \
  scripts/agent-mark-css.test.mjs
-> Test Files 6 passed (6), Tests 232 passed (232)
```

That is the 225 those files held before, plus the 7 added here. The two
pre-existing setup-row consumers are in the list because this changes the
`SetupRow` contract.

All seven new tests are load-bearing, proven in two parts.

The six markup tests: reverting only the four source files to the base and
re-running turns all six red.

```
npx vitest run src/features/xa/XaPage.test.tsx \
  src/features/subagents/SubagentsPage.test.tsx -t "brand"
-> Tests 6 failed | 134 skipped (140)
```

One of those six originally passed against the base, because "no brand mark" is
also true of a page that draws no marks at all. It now asserts the slot exists
and holds the generic glyph, which is what makes it fail without the fix.

The stylesheet contract: removing only the header's own mark rule, and nothing
else, turns it red naming the slot that lost its geometry.

```
-> AssertionError: .pmdhead sizes an agent mark too: expected +0 to be 1
```

The tree was restored after each and the suites re-run green.

Full web suite, compared by failing test ID against the base in a separate
clean worktree, both runs through the same interpreter:

```
npx vitest run --reporter=json
-> base:   1494 tests, 1129 passed, 365 failed
-> branch: 1501 tests, 1136 passed, 365 failed
-> newly failing: 0    tests lost: 0    new tests: 7
```

The 365 are pre-existing on this machine and identical as a set on both sides
(node 26 with happy-dom, where `localStorage` is undefined in several suites).
Counts alone would not have shown that, which is why the comparison is by ID.

Python gates, which is what the pipeline runs, plus the test reaching the module
the new base changed:

```
uv run --frozen --python 3.12 --all-extras pytest -q \
  tests/test_ui_agent_marks.py tests/test_ui_css_token_gate.py \
  tests/test_tool_params_cast.py
-> 61 passed
```

Type, contract, lint and repository gates:

```
npx tsc --noEmit -p tsconfig.json          -> No errors found
npm run gen:check                          -> generated.ts matches the contract (162 methods)
node scripts/check-css.mjs                 -> OK (color literals confined to tokens)
uv run lint-imports                        -> Contracts: 9 kept, 0 broken
make check-source-language                 -> exit 0
make check-large-files                     -> exit 0
python scripts/check_commit_messages.py    -> exit 0
```

`lint-imports`, the css gate and the whole web suite are not run by this
project's pipeline, so they were run locally.

The toolchain was confirmed to have read the edited files rather than another
checkout's copy, since the web dependency tree is shared:

```
npx tsc --noEmit -p tsconfig.json --listFiles | grep -E "setuprow|XaPage|SubagentsPage"
-> three absolute paths, all inside the branch's own tree
```

Rendered check, driven through a real browser against the built bundle, since
the stylesheet is where happy-dom sees nothing:

- Light and dark theme, sub-agents page, a roster covering every mark in the
  table. Each third-party row draws its vendor's mark; the preset-less rows
  draw the generic glyph.
- Dark theme is where the tone corrections matter, and they survive the new
  size: the marks drawn in `currentColor` invert to readable, and the one mark
  that pairs a brand colour with an adaptive tone keeps its green rather than
  inverting to magenta.
- Measured geometry on the sub-agents page: every row mark 28 by 28 at the same
  offset with the tile's corner radius, every name starting at the same
  x whether or not the row has a preset, and no mark overflowing its row.
- Measured geometry on the detail card's header: 46 by 46 with the header's
  corner radius, matching what that container sizes a letter tile to and
  larger than the row mark that opens it.
- Measured geometry on the instance row: every mark 20 by 20 at the same
  offset, no overflow.

Known gap in that last item: the conversation panel's instance list is fed by a
session-scoped source that a static page cannot populate, so its geometry was
measured on the component's own markup under the real stylesheet rather than
through the live store. The markup itself is pinned by the added test, which
drives the real component and asserts the resolved mark per row.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Nothing to update: no user-facing document describes the roster's marks, and
this coins no domain term, so there is no `CONTEXT.md` entry to add.

## Risk

Presentation only. No wire shape, stored value, guard or dispatch path changes,
and nothing new is written to disk.

The one shared piece is `SetupRow`, used by three pages. Its `tile` widens from
a boolean to a node with the previous two behaviours preserved exactly, so the
schedules page keeps its tile-less grid and the entrances page keeps its letter
tile; both are covered by their own suites in the run above.

Rollback is reverting the two commits; nothing persists and no migration is
involved.

- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

Security is not applicable: no authentication, path resolution, credential or
network surface is touched.

## Related Issues

N/A
2026-09-10 02:57:10 +00:00
0xKT
72b343f5e8 fix(ui-web): a sub-agent's chat reads in the order it happened, with its fold open
## Summary

A sub-agent's direct chat drew its messages out of order and kept every step
behind a click. Both come from the shared transcript renderer, which a
delegated pane -- an instance's direct chat, a spawn record, a DAG node -- uses
through the same `history()` the conversation uses.

**Order.** That reader classifies the last thing the model said as the turn's
answer, and an answer is emitted past the turn's fold. On a settled record the
two coincide. They part company whenever a turn goes on working after speaking:
a narration line that introduced a tool call was drawn below the call. A running
turn is redrawn from its newest line on every poll, which made this the normal
case rather than an edge one -- the line the model had just written sat under
everything that came after it, and moved again two seconds later.

On a delegated lane the answer is now the model's last word rather than merely
the last thing it said. Any work after a text -- a tool row, or the message's
own tool calls -- makes that text narration, so it stays in the fold where it
was said; a text nothing follows still gets the answer row. Rows now only ever
append, which also removes the per-poll reshuffle.

**Fold.** The fold over a delegated turn is born open. That pane is one
sub-agent's work and its steps are what the reader opened it for. Every turn's,
not just the last, so `shutAutoFolds` stays on the live path. It is marked
`auto`, so the reader's own collapse takes it over and survives the next poll.

The conversation's own lane is deliberately unchanged: its live path does not go
through `history()` at all, so changing the replay would make it disagree with
what the reader had just watched. The divergence is stated at all three places
that now read `lane.main`.

Two things ride along with no behaviour of their own. Five comments described
the model as it read before this change and now say what it reads instead, one
of them a weight claim that needed a measurement rather than a rewording (it is
in Verification). And one word: the fold was briefly called a "trajectory" here,
which the renderer never calls it -- the segment is `kind: 'fold'`, built by
`collapse`, flipped by `toggleFold` -- and which CONTEXT.md already defines for
one task try under `raven/trajectory/`.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Baseline is a detached worktree at `origin/main` with `ui-web/node_modules`
symlinked; both runs are serial, because the one `--localstorage-file` this box
needs is shared by parallel workers and makes its own flakes.

```
# base and head, same command
NODE_OPTIONS=--localstorage-file=... npx vitest run --no-file-parallelism \
  --reporter=json --outputFile=...
base: 1494 tests, 2 failed
head: 1498 tests, 2 failed
failing-ID diff: introduced NONE, fixed NONE
```

The two failures are the same pair on both sides: `deskStore` and `palette`'s
"when storage refuses" cases, which are unevaluable on this box -- with the flag
storage works where they need it to throw, and without it their file dies in
`beforeEach`. Neither imports the transcript module. An independent full run
of the same head in another environment came back 1498/1498, which is a second
environment confirming the pair is environmental rather than a property of this
change.

One existing test asserted that a delegated fold is born closed, which is the
behaviour this change reverses. Its subject is that the reader's own choice
survives a repaint, which still holds, so it now drives the reader closing an
open fold rather than opening a closed one.

```
make lint-ui                  # gen:check 162 methods match; tsc --noEmit clean
make check-large-files        # clean
make check-source-language    # clean
scripts/check_commit_messages.py origin/main..HEAD   # clean
```

Four tests added, driven through the store rather than a fake, expressing the
rule as a flat render-order trace. Proven not to be theatre by reverse-applying
only the two logic hunks on the current head, comments left in place. Four go
red -- three of the four new ones, plus that re-pointed one. The fourth new
test ("the turn keeps its answer when the model has the last word") passes
either way by design: it pins the behaviour that must not change.

Replayed three real instance records off disk (7, 55 and 197 messages, the last
one two turns) through the delegated lane: every fold open, every narration line
above the calls it introduced, one answer row per turn.

Weight, measured because the comment justifying the shut default cites a number
(a forty-turn session building 7361 DOM nodes, 6400 of them in shut bodies).
Rendering the two largest instance records with every fold open: 55 messages in
one turn build 356 nodes against 103 shut, 197 messages in two turns build 738
against 334.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No docs entry: `ui-web/` has no CONTEXT.md, and CONTEXT-MAP.md lists no context
for it. Not screenshotted.

## Risk

User-visible, on delegated panes only:

- a turn whose text is followed by tool work no longer gets an answer row, so
  that text loses the answer row's copy button and sits in the fold in its real
  position instead. This falls out of ordering by payload rather than by
  classification, and is why opening the fold by default matters;
- every turn's fold is open on opening such a pane, where one click used to be
  needed per turn. Nothing caps that: it grows with the record at roughly four
  nodes a message, so an instance kept for thousands of turns would reach the
  figure the weight comment cites. The measurements above are an order of
  magnitude under it, and the comment now says both.

The conversation's transcript is untouched, and so is every other lane
behaviour: the fold still holds one turn's steps, the reader's own toggles still
survive a repaint, and the live path still shuts the previous turn's fold.

Rollback is the two logic hunks: the `lane.main` guard inside `isFinal`, and
`born` in `collapse`. Reverting either alone is safe and independent.

Not fixed, and outside this change: `DirectTurn.steer` and `DirectTurn.interrupted`
are on the wire and documented as rows a reader should draw inside the turn
rather than as new ones, and the web renderer reads neither, so a steered
message opens a spurious question. No record on disk currently carries one.

## Related Issues

N/A
2026-09-10 02:45:14 +00:00
LivXue
e7589891f9 fix(ui-web): a sub-agent's chat reads in the order it happened, with its fold open
## Summary

A sub-agent's direct chat drew its messages out of order and kept every step
behind a click. Both come from the shared transcript renderer, which a
delegated pane -- an instance's direct chat, a spawn record, a DAG node -- uses
through the same `history()` the conversation uses.

**Order.** That reader classifies the last thing the model said as the turn's
answer, and an answer is emitted past the turn's fold. On a settled record the
two coincide. They part company whenever a turn goes on working after speaking:
a narration line that introduced a tool call was drawn below the call. A running
turn is redrawn from its newest line on every poll, which made this the normal
case rather than an edge one -- the line the model had just written sat under
everything that came after it, and moved again two seconds later.

On a delegated lane the answer is now the model's last word rather than merely
the last thing it said. Any work after a text -- a tool row, or the message's
own tool calls -- makes that text narration, so it stays in the fold where it
was said; a text nothing follows still gets the answer row. Rows now only ever
append, which also removes the per-poll reshuffle.

**Fold.** The fold over a delegated turn is born open. That pane is one
sub-agent's work and its steps are what the reader opened it for. Every turn's,
not just the last, so `shutAutoFolds` stays on the live path. It is marked
`auto`, so the reader's own collapse takes it over and survives the next poll.

The conversation's own lane is deliberately unchanged: its live path does not go
through `history()` at all, so changing the replay would make it disagree with
what the reader had just watched. The divergence is stated at all three places
that now read `lane.main`.

Two things ride along with no behaviour of their own. Five comments described
the model as it read before this change and now say what it reads instead, one
of them a weight claim that needed a measurement rather than a rewording (it is
in Verification). And one word: the fold was briefly called a "trajectory" here,
which the renderer never calls it -- the segment is `kind: 'fold'`, built by
`collapse`, flipped by `toggleFold` -- and which CONTEXT.md already defines for
one task try under `raven/trajectory/`.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Baseline is a detached worktree at `origin/main` with `ui-web/node_modules`
symlinked; both runs are serial, because the one `--localstorage-file` this box
needs is shared by parallel workers and makes its own flakes.

```
# base and head, same command
NODE_OPTIONS=--localstorage-file=... npx vitest run --no-file-parallelism \
  --reporter=json --outputFile=...
base: 1494 tests, 2 failed
head: 1498 tests, 2 failed
failing-ID diff: introduced NONE, fixed NONE
```

The two failures are the same pair on both sides: `deskStore` and `palette`'s
"when storage refuses" cases, which are unevaluable on this box -- with the flag
storage works where they need it to throw, and without it their file dies in
`beforeEach`. Neither imports the transcript module. An independent full run
of the same head in another environment came back 1498/1498, which is a second
environment confirming the pair is environmental rather than a property of this
change.

One existing test asserted that a delegated fold is born closed, which is the
behaviour this change reverses. Its subject is that the reader's own choice
survives a repaint, which still holds, so it now drives the reader closing an
open fold rather than opening a closed one.

```
make lint-ui                  # gen:check 162 methods match; tsc --noEmit clean
make check-large-files        # clean
make check-source-language    # clean
scripts/check_commit_messages.py origin/main..HEAD   # clean
```

Four tests added, driven through the store rather than a fake, expressing the
rule as a flat render-order trace. Proven not to be theatre by reverse-applying
only the two logic hunks on the current head, comments left in place. Four go
red -- three of the four new ones, plus that re-pointed one. The fourth new
test ("the turn keeps its answer when the model has the last word") passes
either way by design: it pins the behaviour that must not change.

Replayed three real instance records off disk (7, 55 and 197 messages, the last
one two turns) through the delegated lane: every fold open, every narration line
above the calls it introduced, one answer row per turn.

Weight, measured because the comment justifying the shut default cites a number
(a forty-turn session building 7361 DOM nodes, 6400 of them in shut bodies).
Rendering the two largest instance records with every fold open: 55 messages in
one turn build 356 nodes against 103 shut, 197 messages in two turns build 738
against 334.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No docs entry: `ui-web/` has no CONTEXT.md, and CONTEXT-MAP.md lists no context
for it. Not screenshotted.

## Risk

User-visible, on delegated panes only:

- a turn whose text is followed by tool work no longer gets an answer row, so
  that text loses the answer row's copy button and sits in the fold in its real
  position instead. This falls out of ordering by payload rather than by
  classification, and is why opening the fold by default matters;
- every turn's fold is open on opening such a pane, where one click used to be
  needed per turn. Nothing caps that: it grows with the record at roughly four
  nodes a message, so an instance kept for thousands of turns would reach the
  figure the weight comment cites. The measurements above are an order of
  magnitude under it, and the comment now says both.

The conversation's transcript is untouched, and so is every other lane
behaviour: the fold still holds one turn's steps, the reader's own toggles still
survive a repaint, and the live path still shuts the previous turn's fold.

Rollback is the two logic hunks: the `lane.main` guard inside `isFinal`, and
`born` in `collapse`. Reverting either alone is safe and independent.

Not fixed, and outside this change: `DirectTurn.steer` and `DirectTurn.interrupted`
are on the wire and documented as rows a reader should draw inside the turn
rather than as new ones, and the web renderer reads neither, so a steered
message opens a spurious question. No record on disk currently carries one.

## Related Issues

N/A
2026-09-10 02:45:14 +00:00
0xKT
867533970b fix(ui-web): a conversation you are not looking at stops losing its graph
## Summary

A conversation the reader is not looking at loses its graph and hides what it needs.
Both halves have the same cause: live events reach the page only for the conversation
on screen, and there was no other way for one to say anything.

**The graph.** `rpc.notify.event` drops a `dag.*` event for any other conversation
unless a parked-turn buffer exists, and `parkTurn` builds one only while that turn is
busy. A graph outlives the turn that started it, so most node reports arrive when no
buffer is there. The disk-based recovery already existed and could not run: `resumeDag`
refused unless `sessionStorage` held a note naming the run, and that note is written
only once a live event has been applied, so it is absent exactly for a graph that
started while the reader was elsewhere. `dag.get` answers such a run correctly,
unfinalized ones included, and was never asked.

The run to read is now resolved from three sources, ordered by how current each can be:
the graph already on screen, then the stored note, then the run ids the transcript
carries, which `session.resume` already stamps onto the row that started each graph.
The note keeps its rank above the transcript because it is the only one of the two
carrying a preference; a reader watching the first of two graphs is not moved onto the
second by a reload.

`mount.resume` also stops declining a conversation whose sheet is still up, which is
the case with no reload at all: the reader leaves, node reports are dropped, and the
sheet they return to is as stale as the moment they left. A read of the same run is
applied to it; only a different run is declined, the live one then being the newer.
Whether a conversation should be read at all moved to the caller. The parked path in
`sessionOpen` takes the graph half of this and not the desk half, because its windows
are still open and replaying them would give the reader each one twice.

**The notice.** An approval, confirm or clarify raised elsewhere rendered nothing
anywhere: its sheet mounts only on its own conversation, the repaints were skipped, and
the row's status vocabulary had no word for it. The row now carries an asking state that
outranks running, since a blocked conversation still has a turn open. It clears when the
wait ends and when the reader opens the conversation.

Its mark is a disc inside a halo, which is neither of the shapes already taken: a bare
disc is running and a bare ring is finished. The first revision of this branch wrote the
state without writing its mark, so the row rendered a transparent dot over the timestamp
that the same selector hides -- less than a row with no state at all, with only the ARIA
label correct. The stylesheet check added with the fix derives the state set from the
component's own tail line rather than listing it, because listing would repeat that
omission for the next state added; it also covers running, finished and failed, none of
which had been asserted to paint either.

**What this does not do.** It does not make a pending request survivable. The approval
ceiling is 30 seconds visible and 35 in total, fixed where the broker is built; nothing
re-sends a request that is still pending; and a disconnect fails every pending one
closed. A reader who looks 40 seconds later still finds it gone. Making the request
itself recoverable needs the server to publish what is pending, which is deliberately
not in this change. The event drop is also left in place: this reads the gateway again
on open rather than replaying what was missed, so the reader gets current state and not
the transitions in between.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

The second commit is a `feat` and is described above; the branch as a whole is a fix.

## Verification

Sixteen tests added, five of them written failing first. Each fix was shown to be
load-bearing by breaking it again: reverting the `refreshDag` error guard reddens its one
test, removing the parked path's re-read reddens the assembled harness assertion, and
deleting the asking mark's rule reddens three of the stylesheet check's four cases.

```
npx vitest run --no-file-parallelism    1507 passed, 2 failed of 1509, 0 unhandled
npm run type-check --prefix ui-web      clean
npm run type-check --prefix ui-tui      clean
npm run build --prefix ui-web           built, 564.82 kB
npm run gen:check --prefix ui-web       generated.ts matches the contract
node ui-tui/scripts/gen-i18n.mjs --check    generated catalogue is up to date
scripts/check_source_language.py        exit 0
scripts/check_large_files.py            exit 0
scripts/check_commit_messages.py        exit 0
pytest tests/test_i18n_boundary.py tests/test_i18n_prompts.py   6 passed
```

Zero failures introduced: failing test ids were captured on `origin/main` and on this
branch and the sets diffed, rather than the counts compared.

Three signals are read, because no one of them is sufficient here, and an earlier run of
this branch's own verification proved it: an unhandled `TypeError` out of an assembled
harness under `ui-web/scripts/` is not an assertion failure, so `numFailedTests` stayed
zero and a suite with a broken seam read as green. The exit code alone is no better,
since the two remaining failures make it nonzero on a good run. So the exit code,
`numFailedTests`, and the unhandled-error count are all read; the last is now zero.

Those two remaining failures, `deskStore.test.ts` and `palette.test.ts` under `when
storage refuses`, are red on `origin/main` too and are unevaluable on this machine in
either configuration. Node 26 ships an experimental `localStorage` that is `undefined`
without `--localstorage-file` and shadows the one happy-dom installs, which fails about
365 tests across 65 suites at any revision; supplying the flag fixes those and makes the
two storage-refusal tests fail instead, because they need storage to throw. That flag
names one file shared by every worker, so the suite must also run with
`--no-file-parallelism` or three storage-touching suites flake in rotation. No CI job
runs this suite, which is how the 365 went unnoticed.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

The last box is unchecked deliberately: the asking state is a visible change to the
session rail and no screenshot is attached. The string itself is in the shared
catalogue in both locales.

## Risk

Behaviour changes a reader can see. Reopening a conversation now asks the gateway for
its graph in cases where it previously asked for nothing, so a sheet appears where none
used to. A sheet already up is refreshed rather than left alone, so its node states can
change on reopen; that is the point, and the reader's fold is preserved across it. A row
gains a fourth state, drawn as a new mark in a slot that previously held three.

Confirm is the one lane whose badge can outlive its request: its broker times out and
answers with its default without sending any frame, where approval and clarify both
close themselves. Opening the conversation clears it, which is what the badge asks for,
so the stale window is bounded by the one action it prompts.

Rollback is a revert. The change adds one exported verb and one status value and alters
no wire contract, no stored format and no server behaviour; reverting restores the
previous resolution order and the previous three-state row.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:45:02 +00:00
LivXue
b40c86aea9 fix(ui-web): a conversation you are not looking at stops losing its graph
## Summary

A conversation the reader is not looking at loses its graph and hides what it needs.
Both halves have the same cause: live events reach the page only for the conversation
on screen, and there was no other way for one to say anything.

**The graph.** `rpc.notify.event` drops a `dag.*` event for any other conversation
unless a parked-turn buffer exists, and `parkTurn` builds one only while that turn is
busy. A graph outlives the turn that started it, so most node reports arrive when no
buffer is there. The disk-based recovery already existed and could not run: `resumeDag`
refused unless `sessionStorage` held a note naming the run, and that note is written
only once a live event has been applied, so it is absent exactly for a graph that
started while the reader was elsewhere. `dag.get` answers such a run correctly,
unfinalized ones included, and was never asked.

The run to read is now resolved from three sources, ordered by how current each can be:
the graph already on screen, then the stored note, then the run ids the transcript
carries, which `session.resume` already stamps onto the row that started each graph.
The note keeps its rank above the transcript because it is the only one of the two
carrying a preference; a reader watching the first of two graphs is not moved onto the
second by a reload.

`mount.resume` also stops declining a conversation whose sheet is still up, which is
the case with no reload at all: the reader leaves, node reports are dropped, and the
sheet they return to is as stale as the moment they left. A read of the same run is
applied to it; only a different run is declined, the live one then being the newer.
Whether a conversation should be read at all moved to the caller. The parked path in
`sessionOpen` takes the graph half of this and not the desk half, because its windows
are still open and replaying them would give the reader each one twice.

**The notice.** An approval, confirm or clarify raised elsewhere rendered nothing
anywhere: its sheet mounts only on its own conversation, the repaints were skipped, and
the row's status vocabulary had no word for it. The row now carries an asking state that
outranks running, since a blocked conversation still has a turn open. It clears when the
wait ends and when the reader opens the conversation.

Its mark is a disc inside a halo, which is neither of the shapes already taken: a bare
disc is running and a bare ring is finished. The first revision of this branch wrote the
state without writing its mark, so the row rendered a transparent dot over the timestamp
that the same selector hides -- less than a row with no state at all, with only the ARIA
label correct. The stylesheet check added with the fix derives the state set from the
component's own tail line rather than listing it, because listing would repeat that
omission for the next state added; it also covers running, finished and failed, none of
which had been asserted to paint either.

**What this does not do.** It does not make a pending request survivable. The approval
ceiling is 30 seconds visible and 35 in total, fixed where the broker is built; nothing
re-sends a request that is still pending; and a disconnect fails every pending one
closed. A reader who looks 40 seconds later still finds it gone. Making the request
itself recoverable needs the server to publish what is pending, which is deliberately
not in this change. The event drop is also left in place: this reads the gateway again
on open rather than replaying what was missed, so the reader gets current state and not
the transitions in between.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

The second commit is a `feat` and is described above; the branch as a whole is a fix.

## Verification

Sixteen tests added, five of them written failing first. Each fix was shown to be
load-bearing by breaking it again: reverting the `refreshDag` error guard reddens its one
test, removing the parked path's re-read reddens the assembled harness assertion, and
deleting the asking mark's rule reddens three of the stylesheet check's four cases.

```
npx vitest run --no-file-parallelism    1507 passed, 2 failed of 1509, 0 unhandled
npm run type-check --prefix ui-web      clean
npm run type-check --prefix ui-tui      clean
npm run build --prefix ui-web           built, 564.82 kB
npm run gen:check --prefix ui-web       generated.ts matches the contract
node ui-tui/scripts/gen-i18n.mjs --check    generated catalogue is up to date
scripts/check_source_language.py        exit 0
scripts/check_large_files.py            exit 0
scripts/check_commit_messages.py        exit 0
pytest tests/test_i18n_boundary.py tests/test_i18n_prompts.py   6 passed
```

Zero failures introduced: failing test ids were captured on `origin/main` and on this
branch and the sets diffed, rather than the counts compared.

Three signals are read, because no one of them is sufficient here, and an earlier run of
this branch's own verification proved it: an unhandled `TypeError` out of an assembled
harness under `ui-web/scripts/` is not an assertion failure, so `numFailedTests` stayed
zero and a suite with a broken seam read as green. The exit code alone is no better,
since the two remaining failures make it nonzero on a good run. So the exit code,
`numFailedTests`, and the unhandled-error count are all read; the last is now zero.

Those two remaining failures, `deskStore.test.ts` and `palette.test.ts` under `when
storage refuses`, are red on `origin/main` too and are unevaluable on this machine in
either configuration. Node 26 ships an experimental `localStorage` that is `undefined`
without `--localstorage-file` and shadows the one happy-dom installs, which fails about
365 tests across 65 suites at any revision; supplying the flag fixes those and makes the
two storage-refusal tests fail instead, because they need storage to throw. That flag
names one file shared by every worker, so the suite must also run with
`--no-file-parallelism` or three storage-touching suites flake in rotation. No CI job
runs this suite, which is how the 365 went unnoticed.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

The last box is unchecked deliberately: the asking state is a visible change to the
session rail and no screenshot is attached. The string itself is in the shared
catalogue in both locales.

## Risk

Behaviour changes a reader can see. Reopening a conversation now asks the gateway for
its graph in cases where it previously asked for nothing, so a sheet appears where none
used to. A sheet already up is refreshed rather than left alone, so its node states can
change on reopen; that is the point, and the reader's fold is preserved across it. A row
gains a fourth state, drawn as a new mark in a slot that previously held three.

Confirm is the one lane whose badge can outlive its request: its broker times out and
answers with its default without sending any frame, where approval and clarify both
close themselves. Opening the conversation clears it, which is what the badge asks for,
so the stale window is bounded by the one action it prompts.

Rollback is a revert. The change adds one exported verb and one status value and alters
no wire contract, no stored format and no server behaviour; reverting restores the
previous resolution order and the previous three-state row.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:45:01 +00:00
LivXue
42dbfcf402 fix(*): install the product engines the roster gates Raven-Design and Raven-PPT on
## Summary

A raven installed by `install.sh` listed Raven-Design and Raven-PPT in the roster and
could dispatch to neither.

Discovery reads the `engine` block in each `agents/<product>/subagent.json` and sets the
row's `enabled` from whether that package is importable where raven runs, so a product
whose distribution is absent is listed and disabled. Nothing in any automated path
installed those two distributions: `install.sh` carries only the `everos-memory` plugin,
and a product's own `install.py` registers a roster row without touching its
distribution. The refusal text says to install the engine "where raven is installed" and
names no command, so the remedy was stated nowhere the installer ran.

This is the split the layering intends -- `everos-memory` is the host's own memory
backend, the other two are product harnesses -- but the products ship in the same
repository and the same release, and no other step picks them up.

Four changes:

- Source mode carries both engines beside the memory plugin.
- The degradation ladder gains a rung between them, on both the source and the release
  path. The engines pull native builds (PDF, raster, plotting) that a platform can refuse
  on its own; losing long-term memory to a failed PDF rasteriser is the wrong trade, so
  the engines fall first and the memory plugin is dropped only if it fails on its own.
  The engine requirements live in their own variable for that reason: sharing one with
  the memory plugin makes the first engine that cannot build take everos-memory with it.
- The plugin directories are passed as positional parameters, not encoded into a string.
  sh has no arrays, and an option/path pair in a scalar is split on every space, so a
  checkout path holding one loses all three plugins and the ladder ends at bare raven
  reporting success.
- Release mode resolves the two wheels from the release assets the way it already
  resolves `everos-memory`, and the release workflow builds them so those assets exist.
  An absent wheel stays a warning rather than a failure: the release still installs and
  the two rows stay disabled the way discovery already reports them.
- The Windows installer gets the same two, in both of its modes. It mirrors the shell one
  and carried no plugin arguments at all, so a Windows install reached exactly the state
  described above. Its wheel resolver reads the release object the raven-wheel lookup
  already fetched rather than calling the API again, because unauthenticated callers get
  60 requests per hour per IP and the script's own comment says a shared egress can
  exhaust that.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Source mode, end to end on Linux, against a wiped `~/.raven` and `~/.everos`:

- Before, on the unpatched script: `raven 0.1.13`, `everos-memory 1.2.0`,
  `design-engine NOT installed`, `ppt-engine NOT installed`.
- After: `raven 0.1.13`, `everos-memory 1.2.0`, `design-engine 0.2.0`, `ppt-engine 0.2.0`,
  and `raven_everos` / `raven_design` / `raven_ppt` all resolve under the installed
  interpreter -- the probe discovery itself runs.
- The roster verdict is the assertion that matters. Driving the discovery scan directly,
  all five products now report `ready=True`; before the change, Raven-Design and Raven-PPT
  reported `ready=False` with "the design-engine engine wheel is not installed in this
  raven's environment" and the ppt-engine equivalent.

Both degradation properties were driven rather than argued, each against the failure it
exists for:

- A checkout path containing a space: the source ladder's first rung builds eleven argv
  entries with each of the three plugin directories intact as one argument. Encoding the
  pairs into a scalar had produced fourteen, splitting every path in half. The
  no-plugin rung still expands cleanly under `set -u`.
- A release install where only `design-engine` fails to resolve: three invocations, the
  third carrying `everos-memory` and succeeding. Sharing one variable had made that third
  invocation carry no plugin at all.

The Windows installer needs neither fix and was checked for both: its plugin list is a
real array, so splatting keeps a spaced path one argument (verified on 7.6.5 with a path
containing a space), and it carries no memory plugin to lose.

PowerShell, driven rather than read, on 7.6.5:

- The whole file parses clean through `Parser::ParseFile`.
- The new wheel resolver was extracted and driven over four states: no cached release
  (the API failed, or the release-page fallback ran) returns null; a release carrying
  both engine wheels returns each; a release carrying only the raven wheel -- which is
  what the current latest release is -- returns null for both; and a release carrying
  only an engine sdist returns null rather than handing uv a tarball.
- Empty-array splatting was driven too, since it is the analogue of the bash hazard
  below: `@cArgs @pArgs` with both empty passes one argument, not three.
- Every one of the six `& $UvPath tool install` calls reads `$LASTEXITCODE` back on the
  next line. `$ErrorActionPreference` does not cover native commands and
  `$PSNativeCommandUseErrorActionPreference` is still False by default at 7.6.5, so a
  failed uv would otherwise return to the caller and the script would report success.

Not run: no Windows machine was available, so the PowerShell half is verified by parse,
by driving the new function, and by the exit-code audit -- not by an install.

Shell portability, because the script is `#!/bin/sh` with `set -eu` and the reviewed
hazard is a bash-only construct reaching a POSIX shell:

- `sh -n install.sh` and `dash -n install.sh` both clean. The added helper uses
  positional parameters only -- no arrays, no `local`, no `+=`.
- The ladder's control flow was driven rather than read: under `sh -eu`, a helper
  returning non-zero inside `if !` falls through to the next rung instead of aborting,
  and the success path returns without entering it.

Other gates:

- `python3 -c "import yaml; yaml.safe_load(...)"` over the release workflow: parses.
- `scripts/check_commit_messages.py origin/main..HEAD`: exit 0.
- `uv run --all-extras pytest tests/test_install_script.py
  tests/test_constraints_export_contract.py tests/test_cli_onboard_commands.py`:
  321 passed.
- Python unit suite: `8422 passed, 1 failed`. The failure,
  `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`, is
  pre-existing and environment-dependent, not introduced here: it fails identically at
  the merge base in a separate detached worktree (same file, same line, same assertion),
  and it passes on this branch under `COLUMNS=200`. It is a rich-wrapping width
  assertion. The change adds no Python; it is shell, PowerShell and CI configuration.

Not run: `shellcheck` is not installed in the environment this was written in, so the
`# shellcheck disable=SC2086` directive on the helper is unverified by the tool itself.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

Behaviour change for every source install: two more distributions land in the tool
environment, and `ppt-engine` pulls native builds. That is why the ladder gained a rung
rather than extending the existing plugin argument -- an engine that cannot build on a
platform now costs that platform its two product rows and nothing else, where a naive
extension would have cost it long-term memory as well.

Release mode is inert until a release carries the wheels. The current latest release
carries none, including no `everos-memory` wheel, so the two new warnings will fire
alongside the existing memory-plugin warning until the next release is cut from the
updated workflow.

Rollback is the revert: without these lines the installer behaves exactly as before, and
the two rows return to being listed and disabled.

Windows carries a specific risk the other platforms do not. `cairosvg` and `cairocffi`
are pure-python wheels that load a system libcairo at runtime, and a stock Windows
machine does not have it, so the deck engine can install and then fail to render. Every
other native dependency of the two engines has Windows wheels on PyPI (`pymupdf`,
`pypdfium2`, `matplotlib`, `pillow`), and `python-pptx` is pure python. That is the
reason the ladder drops the engines a rung before raven itself rather than failing the
install.

Disclosed, not fixed. `everos-memory` is absent from the Windows installer and stays
absent: it was never carried there, and whether EverOS belongs on Windows is a separate
question from closing the roster gap. So a Windows install still boots memoryless and
`raven doctor` explains why, exactly as before this change.

The deck engine has a second manual step this change does not address: its templates are
not in git and are fetched separately after cloning.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 02:44:40 +00:00
Handsome-wzw
7b45527b5b fix(tools): an array sent as its own JSON is still an array
## 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.
2026-09-09 15:42:36 +00:00
forrestjgq
f01231fef6 fix(cli): overhaul trajectory browser interaction ux (#379)
## 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>
2026-09-05 23:58:20 +08:00
0xKT
28299e5f0e fix(*): relays on the page lane, live direct chats reported, continuation heads cut
## Summary

Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.

1. A sub-agent's result relay into a page session ran on the gateway spine while the
   page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
   at once: the same tool calls were drawn twice and the result delivered twice, and
   `turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
   turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
   `raven.gateway.submit_router.route_submit` hands turns whose conversation carries
   the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
   The sub-agent manager and the deep-research submit both take the routed callable;
   a gateway without a page keeps the gateway submit unchanged.

2. The watch-work judgement (one model call on a turn's first look) was paid on relay
   and sentinel turns, whose "last user message" is the runtime's re-injected report,
   and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
   The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
   reads as no request, and the judgement is cut at 60 seconds and treated as no
   verdict. CRON and heartbeat turns are deliberately still judged: their text is the
   owner's own instruction.

3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
   was mid-conversation with rendered to the main agent as "no turns yet"; the model
   read that as free and spawned onto it. The handoff now reads the manager's live
   direct turns (`live_direct_turns`) and renders an answering instance with the time
   it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
   behind such a turn no longer writes `running` before it holds the handle lock (it
   stays the `pending` it was announced as), and no longer takes over the instance's
   live view: `activity.watching_instance` registers only when the slot is free and
   pops only what it registered, so the direct chat's steps stay on screen and the
   spawn's appear once it runs.

4. When reasoning ran to the model's output ceiling with no content and the
   empty-response recovery fed it back as a prefill, the continuation opened on the
   rest of the cut thought and that fragment streamed and was stored as the head of the
   answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
   whitespace and ends at the first sentence or line boundary within 200 characters;
   `ContinuationGate` holds streamed deltas until the same rule can decide, so what the
   reader sees matches what the session stores. Only a continuation after
   ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.

Decisions worth knowing:

- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
  `RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
  importing `raven.rpc`, so a test holds the two equal instead of one importing the
  other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
  block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
  moved (after the handle lock). The page's spawn card reads identity from `pending`
  and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
  source-language gate reads the literal marks as non-English source.

Review round 1 (all findings non-blocking, all taken):

- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
  method, the rpc spine and the submit router call it, and the router test pins the
  identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
  `DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
  The enclosing handler already kept the turn alive, but left the verdict unset, so a
  failing judgement was paid again on every path-touching tool call; the comment that
  claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
  is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
  whole (no case, so no mid-sentence signal); the comment and a test now say that the
  CJK stops end an admitted fragment rather than open one.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
  -> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
     worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
     design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
  tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
  tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
  tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
  -> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests   -> clean
uv run lint-imports                                                       -> 9 kept, 0 broken
make check-source-language                                                -> exit 0
scripts/check_commit_messages.py origin/main..HEAD                        -> exit 0
```

Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.

Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
      Handoff Block)

## Risk

- A relay into a page session now waits behind the page's running turn on that session
  instead of running beside it. That is the intended serialisation; the cost is latency
  on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
  that turn only; before, the same turn hung. No configuration knob: the bound is a
  class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
  continuation whose intended answer begins with a lowercase word and a full stop within
  200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.

- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
      page mount is unaffected)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-09 06:25:28 +00:00
userName20260323
50ad9377bd fix(*): relays on the page lane, live direct chats reported, continuation heads cut
## Summary

Four sub-agent orchestration defects found on 2026-09-08 while running the research
sub-agent from the TUI and the page; all share one root, the host loop not seeing what
its sub-agents are doing right now.

1. A sub-agent's result relay into a page session ran on the gateway spine while the
   page's own turns to that session ran on the RPC spine, so a relay and a user turn ran
   at once: the same tool calls were drawn twice and the result delivered twice, and
   `turn.send`'s one-turn-per-session guard saw neither. The RPC stack now exposes its
   turn scheduler (`RpcStack.turn_scheduler`, surfaced on `PageMount.submit`), and
   `raven.gateway.submit_router.route_submit` hands turns whose conversation carries
   the page prefix (`tui:`) to the page lane and everything else to the gateway lane.
   The sub-agent manager and the deep-research submit both take the routed callable;
   a gateway without a page keeps the gateway submit unchanged.

2. The watch-work judgement (one model call on a turn's first look) was paid on relay
   and sentinel turns, whose "last user message" is the runtime's re-injected report,
   and ran unbounded: one relay turn spent 1229 seconds in it on a reasoning runaway.
   The turn's origin now reaches the loop; a re-injected origin (SUBAGENT, SENTINEL)
   reads as no request, and the judgement is cut at 60 seconds and treated as no
   verdict. CRON and heartbeat turns are deliberately still judged: their text is the
   owner's own instruction.

3. The direct-chat handoff recorded a turn only when it landed, so an instance the user
   was mid-conversation with rendered to the main agent as "no turns yet"; the model
   read that as free and spawned onto it. The handoff now reads the manager's live
   direct turns (`live_direct_turns`) and renders an answering instance with the time
   it began answering (handle lock held) and a line saying it is the user's conversation. The spawn that lands
   behind such a turn no longer writes `running` before it holds the handle lock (it
   stays the `pending` it was announced as), and no longer takes over the instance's
   live view: `activity.watching_instance` registers only when the slot is free and
   pops only what it registered, so the direct chat's steps stay on screen and the
   spawn's appear once it runs.

4. When reasoning ran to the model's output ceiling with no content and the
   empty-response recovery fed it back as a prefill, the continuation opened on the
   rest of the cut thought and that fragment streamed and was stored as the head of the
   answer. `cut_reasoning_head` drops an opening fragment that starts in lowercase or
   whitespace and ends at the first sentence or line boundary within 200 characters;
   `ContinuationGate` holds streamed deltas until the same rule can decide, so what the
   reader sees matches what the session stores. Only a continuation after
   ceiling-cut reasoning (`finish_reason == "length"`) is treated this way.

Decisions worth knowing:

- The `tui:` prefix is spelled in `raven.gateway.submit_router` and as
  `RoutingQuestionBroker`'s default; the layer contract keeps `raven.gateway` from
  importing `raven.rpc`, so a test holds the two equal instead of one importing the
  other.
- The gateway wiring has no import seam, so its test pins the source of the mounted
  block, the same way the neighbouring cron-partition test does.
- The `subagent.status` payload shape is unchanged; only the `running` frame's timing
  moved (after the handle lock). The page's spawn card reads identity from `pending`
  and the record id from `running`, both still present.
- A CJK boundary class in the head-cut regex is spelled as escapes because the
  source-language gate reads the literal marks as non-English source.

Review round 1 (all findings non-blocking, all taken):

- The lane key is now one definition, `raven.spine.conversation_id`; the scheduler's
  method, the rpc spine and the submit router call it, and the router test pins the
  identity and compares against the scheduler's method instead of literals.
- The loop's wiring of the handoff to the manager's live turns has its own test (a bare
  `DirectChatHandoff()` went green before).
- `activity.live_instances_of` is gone: nothing called it.
- The watch-work judgement now reads any exception as no verdict, not only a timeout.
  The enclosing handler already kept the turn alive, but left the verdict unset, so a
  failing judgement was paid again on every path-touching tool call; the comment that
  claimed a raise was handled is corrected.
- A direct chat's start time is stamped once the handle lock is held, not when the slot
  is claimed, so a chat queued behind another holder is not reported as answering.
- The continuation cut deliberately leaves a continuation that opens directly on CJK
  whole (no case, so no mid-sentence signal); the comment and a test now say that the
  CJK stops end an admitted fragment rather than open one.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run pytest tests -q -p no:cacheprovider -n 8 --ignore=tests/integration
  -> 7 failed, 19705 passed, 153 skipped. The same 7 fail on a detached origin/main
     worktree through the same interpreter (doctor memories path 1, NAT64 resolution 4,
     design-engine rendering 2): 0 introduced.
uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_watch_work.py \
  tests/test_gateway_submit_router.py tests/test_subagent_activity.py \
  tests/test_subagent_handoff.py tests/test_subagent_direct_chat.py \
  tests/test_rpc_bootstrap.py tests/test_cli_gateway_page.py tests/test_cli_gateway_commands.py
  -> 279 passed (before round 1); round 1 adds 5 tests and removes 1, see the pipeline
uv run ruff check raven tests; uv run ruff format --check raven tests   -> clean
uv run lint-imports                                                       -> 9 kept, 0 broken
make check-source-language                                                -> exit 0
scripts/check_commit_messages.py origin/main..HEAD                        -> exit 0
```

Red-checked (fix reverted, test goes red, fix restored): activity.py alone reverted
-> `a second lane never unseats the first`; the spawn-path hunk of manager.py alone reverted
-> `['pending', 'running'] == ['pending']`; turn_path.py alone reverted -> the continuation
test sees the `Lagg in an token` head. Round 1: the handoff wiring test goes red on a bare
`DirectChatHandoff()`; the queued-direct-chat test goes red with the stamp back on the slot;
the raising-judgement test goes red with the narrow catch (two calls instead of one). The other new tests fail without their change by
construction (missing symbol or signature), which proves less and is noted as such.

Live check of the shipped page: the served `ui-web/dist` bundle booted under happy-dom in
stub and live mode against a gateway running this branch, desk mounted, no console
errors; `subagents.list` and `subagents.instances` answer as before.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (CHANGELOG, CONTEXT.md
      Handoff Block)

## Risk

- A relay into a page session now waits behind the page's running turn on that session
  instead of running beside it. That is the intended serialisation; the cost is latency
  on a relay while a long page turn runs.
- A judgement that takes over 60 seconds is dropped and the turn runs unwatched for
  that turn only; before, the same turn hung. No configuration knob: the bound is a
  class attribute.
- The head cut only runs on the continuation after a ceiling-cut prefill. A
  continuation whose intended answer begins with a lowercase word and a full stop within
  200 characters would lose that first clause; the test file names the shapes kept.
- Rollback: revert the squash commit. No persisted format changes.

- [x] Security impact considered (no new surface; routing stays in-process)
- [x] Backward compatibility considered (payload shapes unchanged; a gateway without a
      page mount is unaffected)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-09 06:25:28 +00:00
daoxize1
5ee8a14f43 feat(rpc): attribute and filter usage by task
## Change description

Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.

Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.

Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.

Validation:

- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others

## Related issues (if there is)

N/A

## Checklists

### Development

- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass

### Security

- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [ ] Merge request linked to JIRA ticket when applicable

No related JIRA ticket was supplied.
2026-09-09 04:15:30 +00:00
daoxize1
135312987b feat(rpc): attribute and filter usage by task
## Change description

Attach session and root-task identifiers to usage records. Propagate ownership through ACP child agents and asynchronous tool execution so recorded child usage can be attributed to its parent task.

Add a task selector to the usage settings page, including task titles and an all-tasks view. Prevent stale requests from replacing the selected task's results. Historical records without task identifiers remain visible only in the aggregate view.

Include usage recorded by child agents and the built-in image tool in the owning task. Extend the usage RPC schema and generated clients, and bump the contract version for the root-task field.

Validation:

- `uv run pytest tests/test_token_wise_usage_tracker.py tests/test_rpc_contract_shapes.py tests/test_subagent_acp_mcp_lifecycle.py tests/test_rpc_schema_match.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py tests/test_media_gen_tool.py -x`: 498 passed.
- `npm --prefix ui-web test -- --run src/features/settings/SettingsPage.test.tsx`: 46 passed.
- `npm --prefix ui-web run type-check`: passed.
- `make lint-python`, `make check-source-language check-large-files`, and `git diff --check`: passed.
- Both repository commit-message checks passed.

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others

## Related issues (if there is)

N/A

## Checklists

### Development

- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass

### Security

- [x] Security impact of change has been considered
- [x] Code follows company security practices and guidelines

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [ ] Merge request linked to JIRA ticket when applicable

No related JIRA ticket was supplied.
2026-09-09 04:15:30 +00:00
0xKT
231b270dd7 refactor(*): the vendored subagents tree retires and agents/ is the one home
## Summary

Retires the vendored fork tree (`subagents/`, ~7,500 files) and makes `agents/` the one home for the five agent products. The products were already thin launchers that render a config and exec the installed raven's own `raven acp`; this PR removes the frozen fork checkouts they replaced, migrates every consumer, and keeps the A/B verification power as byte snapshots.

Key decisions:

- **A side becomes a record.** The fork trees are deleted; the files the parity guards compare against live on as byte snapshots under `tests/fixtures/vendored_fork/` (added to ruff's exclude so a record can never be reformatted). The research flow's oracle is the fork's frozen measurement (`research_parity_probe.json`), a constant by construction.
- **Config floors v6 and v7.** Stored roster rows that pointed into the retired tree are migrated in place (floor six): rows whose folder maps to a shipped product are re-aimed at `agents/`, fork-era rows that cannot be re-aimed are left untouched and reported, unparseable rows get a fix-by-hand notice. Verdict-driven, path-root anchored, with a stamped sidecar so each pass runs once.
- **The research product reclaims its name (floor seven).** The `-NG` suffix existed only to coexist with the fork's own row, so it retires with the fork: registered `Raven-Research-NG` rows rename to `Raven-Research` on load; if a fork-era row still holds the name, the advisory repeats and the stamp holds at floor six, so the rename completes on a later load once the name frees (never two rows under one name). Display name only -- the machine id `raven-research-ng` (state root, ACP home, everos identity, the `RESEARCH_NG_*` variables) is a stable key and stays. The v6 name gate maps the research folder to None (never re-aim): the fork's research rows were cli-kind on a different flow, and after the rename a name match would select exactly the rows the gate exists to refuse.
- **Guards retire with their subject.** The vendored-invariant and vendored-subagents guard suites, their Makefile/pre-commit/CI hooks, and the fork-era install stage in `install.sh` are removed. The external-consumer tripwire now derives the promised surface from the five product installers and the charter's uninstall recipe (`add_third_party_subagent` and `remove_third_party_subagent` today) instead of restating a list that goes stale; the fork-era pin count (eight names) retired with its consumers, and `get_third_party_subagents` stays only as a courtesy to fork-era installer copies already carried into raven homes.
- **Wheel and sdist slim down.** The wheel force-includes `agents/` file-by-file from the git index (filled-in `.env` files are refused). The sdist shrinks 93.2 MB -> 2.76 MB (-97%).
- **Docs speak one era.** AGENTS.md, CONTEXT.md, README, CHANGELOG, the demo READMEs, and the RPC field descriptions (models.py -> openrpc.json -> both generated clients) describe the product tree in the present and the fork in the past.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other

## Verification

- Controlled A/B on a clean bench, same machine and env fingerprint, at the current pair: base 19,938 passed / 137 skipped / 0 failed vs branch 19,796 / 137 / 0, skip roster identical line by line. The -142 delta equals the collection delta and reconciles file by file: -159 across the twelve retired or trimmed test files, +9 floor-six migration tests, +8 floor-seven tests. The branch diff is fingerprint-stable across rebases (`git patch-id --stable` verified pairwise), so the reconciliation transfers to later bases. A second fingerprint (dev worktree env) shows 19,555 / 148 / 2 at the final tip; the 2 are `test_design_engine_rendering_outcome` renders hitting a local playwright-home quirk -- on the clean bench both sides skip them identically ("no system chromium"), and the branch does not touch that file.
- `uv run pytest tests/integration/test_research_subagent_smoke.py -m integration`: 2 passed (the smoke now drives the migrated product launcher end to end).
- `make lint-python` (ruff check + format), `make lint-imports` (tail line: `Contracts: 9 kept, 0 broken.` -- the ninth contract landed on main mid-branch), `make check-large-files`: all green.
- `npm run lint:rpc --prefix ui-tui` and `npm run gen:check --prefix ui-web`: generated clients in sync with `rpc-schema/openrpc.json`.
- `bash -n install.sh`: clean.
- Wheel built from the branch, installed into a clean venv: onboarding discovers the five products, and a filled-in `.env` placed in the tree fails the build (secrets refusal probed).
- Real-config upgrade rehearsal on a genuine floor-5 home config (owner present): the migration stamped the sidecar to 6, rewrote nothing (the five product rows were already registered against `agents/`; the one fork-era orphan row got its advisory notice and was left untouched), a second load was silent, and the upgraded config served a live probe plus one full one-shot agent turn. The floor-seven rehearsal on the same config renamed its one transition row (a one-line diff against the byte backup), stamped seven, was silent on the second load, and left the machine ids and the row's command untouched.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- User-visible: on first load of a pre-v6 config, roster rows pointing into the retired tree are re-aimed at the product tree, with a one-line `Migrated` notice per changed row and a cleanup hint for the stale on-disk copy. Rows the migration cannot decide are reported, never rewritten. The floor-seven rename tells once per changed row too; only a blocked rename repeats its advisory, deliberately, until the blocking row is gone. While the block holds, the roster shows the discovered `Raven-Research` row beside the stored `Raven-Research-NG` row -- same launcher, same state root, no state split -- and converges to one row once the name frees.
- Rollback: revert the squash commit. The fork trees return from git history, and a config the migration already re-aimed keeps working on both sides of the revert: the wheel carries `agents/` before and after (that packaging landed separately), so no config rollback is needed. Rows the migration could not decide were never rewritten, and the version sidecar is additive.
- Packaging: a wheel built from an sdist (what a combined `uv build` does) carries no agent products by design -- the sdist has no `.git` for the hook's tracked-files read; the hook warns loudly, and release.yml builds the wheel directly from the checkout and asserts the products are present. Release artifacts are unaffected; do not publish a combined-build wheel.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

BREAKING CHANGE: the `subagents/` source tree is gone. Installs never consumed it directly (the wheel carries `raven/agents`), but any local tooling that read `subagents/` paths must move to `agents/` or the snapshots under `tests/fixtures/vendored_fork/`.
2026-09-09 03:59:19 +00:00
0xKT
677d090476 feat(ui-web): an instance can be set apart from the conversation
## Summary

!478 gives the conversation a sub-agent tier. This gives one instance an effort of its own, from that instance's own pane.

The two are a **precedence, not a pair**: `SubagentManager.resolve_mode` reads the instance's override and falls through to the session's tier when there is none. So the default is not a mode -- it is the ABSENCE of one, and the wire already says so with `mode: null`. The row for it reads **Auto**, and `clear: true` is what puts an instance back on it. There is no sentinel id for it on purpose, since an agent is free to call one of its own modes "default".

**Auto names where it currently lands**, not just "Auto". That is what `inherited` is for, and why !474 reports it apart from `mode`: it is the session's tier already clamped to this agent's rungs, which is not the same as the tier. A session on `high` and an agent that cannot rank it means the agent's own default runs, and the row says so.

**The menu is this AGENT's, never the ladder.** Each advertises its own rungs from its own ACP handshake -- measured, not declared. raven-research offers `fast`/`deep`/`ultra` and raven-code `low`/`max`; drawing `medium`/`high`/`max` here would offer rungs the agent does not have. An agent that advertises none draws no chip: nothing to choose between is not the same as a choice that could not be read.

A reply decides, never the click. The manager refuses a rung the agent does not advertise, naming what it does offer, and that refusal is shown rather than the chip moved to a mode the next turn will not run at.

On the pane header, through the shared menu writer with the trailing tick the model chip already uses, rather than a third popover. Live instances only -- a record is a run that already happened.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Stacked on !478

Target is !478's branch. Kept separate per the ask to split MRs by focus: !478 is the conversation's control and stands alone, this is the per-instance one and only makes sense after it.

Worth noting that !474's later scope change made this smaller. Withdrawing the per-dispatch `mode` left `resolve_mode` at two levels -- the instance's override, else the session's tier -- which is exactly the two a reader can be shown. The third would have had to be explained without being settable.

## Verification, and what it does not cover

Said plainly, because the interesting half could not be driven end to end here.

**What the server really answered.** On the running page, against !474's server, with a real instance started from the agents panel:

```
subagents.instance.set_mode -> { mode: null, inherited: null, availableModes: [] }
```

Every agent registered in this environment is `kind` `cli` or `openai`, and `agent_meta` reads modes only for `acp` -- so none can advertise any, and **the chip correctly draws nothing**. That much is end to end: real server, real instance, real pane, no chip.

**What the component does with a menu** could only be driven by answering the seam on the page. The component, the menu writer, the styles and the pane are the real built ones; the reply is not the server's:

```
Auto                chip "Deep"  (.auto)      menu: Auto · Deep ✓ / Fast / Deep / Ultra
pick Ultra          chip "Ultra" (pill)       sent: ('Raven', 'raven-4cc87d', 'ultra')
reopen              menu: Auto · Deep / Fast / Deep / Ultra ✓
pick Auto           chip "Deep"  (.auto)      sent: ('Raven', 'raven-4cc87d', null)
```

So: the wire shape, the clear-versus-set distinction and the rendering are verified; **what is not** is a real agent's real advertised menu arriving over the socket. Reaching that needs an ACP sub-agent product installed and probed, which this environment has none of. The unit cases cover the states.

I also tried the other way first -- hand-writing a capability snapshot with `availableModes` -- and it changed nothing, because `agent_meta` gates the read on `kind == "acp"` and no configured agent is one. Recording it so nobody repeats it.

```
ui-web  vitest 93 files / 1330 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

Mutation-checked nine ways, each redding a different case: Auto showing "Auto" instead of the inherited rung, an empty menu still drawing, painting the click instead of the reply, the Auto row sending an id instead of clearing, the chip not stopping `pointerdown`, and a failed read keeping the previous instance's value. The last one survived the first pass -- the case I had only failed the FIRST read, where there is nothing to keep -- so a case was added for a pane moving to an instance it cannot read.

## After review

**An Auto chip went stale when the conversation tier moved -- `536c62a9`.** Under
Auto the chip shows `inherited`, the session's tier clamped to this agent, so a
switch changes what the pane says with nothing on the pane touched. The effect
keyed on `(agent, handle)` and `shell/tier.ts` told nobody. Reproduced by counting
the reads, with a control, since the chip does not draw against this
environment's agents:

```
                                  before          after
Auto pane open                    High, reads 1   High, reads 1
session tier switched to Max      HIGH, reads 1   Max,  reads 2
control: open another instance     reads 2         reads 3
```

The tier publishes the move and lets whoever is in the way decide -- the shape
`composer/sheets` uses for `watchAsking`, and for its reason. Two tightenings
mutation-checking forced: it tells listeners **only on a real move** (every read
passes through the same place, including the one per conversation change, so
announcing an unchanged value would have every open pane re-fetch for nothing --
my first version notified unconditionally and the suite stayed green), and the
listener re-reads **only under Auto**, through a ref so switching this instance's
own mode does not tear the subscription down and rebuild it.

**The new test file had no purpose comment -- same commit.** AGENTS.md 1.1 wants
one on every new code file. Worth recording what I checked: 38 of the 40 `ui-web`
test files I sampled carry nothing beyond the vitest directive, so the practice is
not the rule; `features/workspace/deliveries.test.ts` is the compliant form. The
rule wins for a file I am adding. `shell/tier.test.ts` on !478 has the same gap
and I have raised it there rather than pushing to an MR already cleared.

```
ui-web  vitest 93 files / 1333 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** — nothing moved; a new reader of an existing method.
- **2 (a value with several entry points)** — the held state has one writer, fed only by a reply.
- **3c (state out of its owner)** — kept in the component rather than a store: it is one pane's, read when the pane points at a different instance, and no other surface reads it.
- **3d (several lanes through one sink)** — one lane, the seam. The pane header's `pointerdown` is the drag handle and the pane raise, so the chip stops it; there is a case for that.
- **6c (generated artifacts)** — `ui-tui/src/i18n/messages.generated.ts` regenerated, since the catalogue is shared and `make lint-tui` fails without it.
- **9 (error handling)** — a failed read draws nothing rather than a stale rung; a refused switch is shown with the manager's own text, which names the rungs the agent does offer.
- **11** — `tsc --listFiles` resolves 194 files, 0 outside this worktree; `npm ci` in both workspaces.
- **4** — failing test IDs diffed against the base, not counts: 0 introduced.

Not applicable: 3, 3b, 3e, 4b-4d, 5, 5b, 6, 6b, 7, 7b, 8, 10.
2026-09-07 05:36:07 +00:00
Handsome-wzw
b33a35a171 feat(ui-web): an instance can be set apart from the conversation
## Summary

!478 gives the conversation a sub-agent tier. This gives one instance an effort of its own, from that instance's own pane.

The two are a **precedence, not a pair**: `SubagentManager.resolve_mode` reads the instance's override and falls through to the session's tier when there is none. So the default is not a mode -- it is the ABSENCE of one, and the wire already says so with `mode: null`. The row for it reads **Auto**, and `clear: true` is what puts an instance back on it. There is no sentinel id for it on purpose, since an agent is free to call one of its own modes "default".

**Auto names where it currently lands**, not just "Auto". That is what `inherited` is for, and why !474 reports it apart from `mode`: it is the session's tier already clamped to this agent's rungs, which is not the same as the tier. A session on `high` and an agent that cannot rank it means the agent's own default runs, and the row says so.

**The menu is this AGENT's, never the ladder.** Each advertises its own rungs from its own ACP handshake -- measured, not declared. raven-research offers `fast`/`deep`/`ultra` and raven-code `low`/`max`; drawing `medium`/`high`/`max` here would offer rungs the agent does not have. An agent that advertises none draws no chip: nothing to choose between is not the same as a choice that could not be read.

A reply decides, never the click. The manager refuses a rung the agent does not advertise, naming what it does offer, and that refusal is shown rather than the chip moved to a mode the next turn will not run at.

On the pane header, through the shared menu writer with the trailing tick the model chip already uses, rather than a third popover. Live instances only -- a record is a run that already happened.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Stacked on !478

Target is !478's branch. Kept separate per the ask to split MRs by focus: !478 is the conversation's control and stands alone, this is the per-instance one and only makes sense after it.

Worth noting that !474's later scope change made this smaller. Withdrawing the per-dispatch `mode` left `resolve_mode` at two levels -- the instance's override, else the session's tier -- which is exactly the two a reader can be shown. The third would have had to be explained without being settable.

## Verification, and what it does not cover

Said plainly, because the interesting half could not be driven end to end here.

**What the server really answered.** On the running page, against !474's server, with a real instance started from the agents panel:

```
subagents.instance.set_mode -> { mode: null, inherited: null, availableModes: [] }
```

Every agent registered in this environment is `kind` `cli` or `openai`, and `agent_meta` reads modes only for `acp` -- so none can advertise any, and **the chip correctly draws nothing**. That much is end to end: real server, real instance, real pane, no chip.

**What the component does with a menu** could only be driven by answering the seam on the page. The component, the menu writer, the styles and the pane are the real built ones; the reply is not the server's:

```
Auto                chip "Deep"  (.auto)      menu: Auto · Deep ✓ / Fast / Deep / Ultra
pick Ultra          chip "Ultra" (pill)       sent: ('Raven', 'raven-4cc87d', 'ultra')
reopen              menu: Auto · Deep / Fast / Deep / Ultra ✓
pick Auto           chip "Deep"  (.auto)      sent: ('Raven', 'raven-4cc87d', null)
```

So: the wire shape, the clear-versus-set distinction and the rendering are verified; **what is not** is a real agent's real advertised menu arriving over the socket. Reaching that needs an ACP sub-agent product installed and probed, which this environment has none of. The unit cases cover the states.

I also tried the other way first -- hand-writing a capability snapshot with `availableModes` -- and it changed nothing, because `agent_meta` gates the read on `kind == "acp"` and no configured agent is one. Recording it so nobody repeats it.

```
ui-web  vitest 93 files / 1330 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

Mutation-checked nine ways, each redding a different case: Auto showing "Auto" instead of the inherited rung, an empty menu still drawing, painting the click instead of the reply, the Auto row sending an id instead of clearing, the chip not stopping `pointerdown`, and a failed read keeping the previous instance's value. The last one survived the first pass -- the case I had only failed the FIRST read, where there is nothing to keep -- so a case was added for a pane moving to an instance it cannot read.

## After review

**An Auto chip went stale when the conversation tier moved -- `536c62a9`.** Under
Auto the chip shows `inherited`, the session's tier clamped to this agent, so a
switch changes what the pane says with nothing on the pane touched. The effect
keyed on `(agent, handle)` and `shell/tier.ts` told nobody. Reproduced by counting
the reads, with a control, since the chip does not draw against this
environment's agents:

```
                                  before          after
Auto pane open                    High, reads 1   High, reads 1
session tier switched to Max      HIGH, reads 1   Max,  reads 2
control: open another instance     reads 2         reads 3
```

The tier publishes the move and lets whoever is in the way decide -- the shape
`composer/sheets` uses for `watchAsking`, and for its reason. Two tightenings
mutation-checking forced: it tells listeners **only on a real move** (every read
passes through the same place, including the one per conversation change, so
announcing an unchanged value would have every open pane re-fetch for nothing --
my first version notified unconditionally and the suite stayed green), and the
listener re-reads **only under Auto**, through a ref so switching this instance's
own mode does not tear the subscription down and rebuild it.

**The new test file had no purpose comment -- same commit.** AGENTS.md 1.1 wants
one on every new code file. Worth recording what I checked: 38 of the 40 `ui-web`
test files I sampled carry nothing beyond the vitest directive, so the practice is
not the rule; `features/workspace/deliveries.test.ts` is the compliant form. The
rule wins for a file I am adding. `shell/tier.test.ts` on !478 has the same gap
and I have raised it there rather than pushing to an MR already cleared.

```
ui-web  vitest 93 files / 1333 tests, type-check, gen:check (161 methods)
ui-tui  lint:i18n up to date, lint:rpc in sync, type-check clean
```

## Swept

`mr-review-patterns` pre-submit sweep, over the branch diff.

- **1 (a write location moved)** — nothing moved; a new reader of an existing method.
- **2 (a value with several entry points)** — the held state has one writer, fed only by a reply.
- **3c (state out of its owner)** — kept in the component rather than a store: it is one pane's, read when the pane points at a different instance, and no other surface reads it.
- **3d (several lanes through one sink)** — one lane, the seam. The pane header's `pointerdown` is the drag handle and the pane raise, so the chip stops it; there is a case for that.
- **6c (generated artifacts)** — `ui-tui/src/i18n/messages.generated.ts` regenerated, since the catalogue is shared and `make lint-tui` fails without it.
- **9 (error handling)** — a failed read draws nothing rather than a stale rung; a refused switch is shown with the manager's own text, which names the rungs the agent does offer.
- **11** — `tsc --listFiles` resolves 194 files, 0 outside this worktree; `npm ci` in both workspaces.
- **4** — failing test IDs diffed against the base, not counts: 0 introduced.

Not applicable: 3, 3b, 3e, 4b-4d, 5, 5b, 6, 6b, 7, 7b, 8, 10.
2026-09-07 05:36:07 +00:00
0xKT
9f4a091857 feat(agents): the request's checkable parts ride back down to where it is answered
## Summary

Three of the dimensions lost on 2026-09-04 were not research failures. A named
section was absent from the report entirely, five candidates outside the stated
length envelope took slots in the main table, and the do-not-bother list carried
items the request had already ruled out. Each of those was stated in the request
and satisfied by intention rather than by checking, because by the time the report
is written the request is fifteen thousand tokens up the context - the same reason
the template reminder exists, and it rides the same seam.

`brief_checklist` reads a request for the parts a parser can settle and the
reminder carries them back:

```
Read literally, this message asks for: 15 to 25 items; nothing from LongBench,
LooGLE, ZeroSCROLLS, LoCoMo; a do-not-bother list; a community-convention table.
Deliver each one, or name it in `## Limitations` and say why it is absent.
```

Three properties are the whole design.

**It only reads; it never judges the answer.** No bounce, no model call, no
latency. The gate that owns bouncing says in its own docstring that it bounces for
a missing section and nothing else, and a checklist wrong about what was asked
would spend generations arguing with the reader. A checklist that is merely
incomplete costs nothing.

**It quotes rather than interprets.** The count is the range as written, the
exclusions are the names as written, the artefacts are the noun phrases as
written. A misread is then visibly a misread of the request rather than a rule the
harness invented, which is also why the sentence opens "read literally" and closes
with somewhere for a wrong item to go.

**It stays silent when unsure.** A range followed by a unit is a size, not a count
("16k-256k words", "2024-2026", "4x-8x", "8-80GB"). An exclusion stated in prose
("the four we already ran") yields nothing. A bare "a table" is not an artefact and
"a report" is the answer itself. On a request with no machine-readable constraints
the reminder renders exactly the bytes it always rendered - pinned by a test.

The one thing worth naming as a near-miss: an earlier form of the name rule
anchored on a leading capital and quoted `xRAG` back as `RAG`, which is a checklist
telling the model about a benchmark that does not exist. Items are now split first
and kept or dropped whole, and that case is a test.

No new config key, and no new injection seam: the checklist rides inside the
reminder's own delimiters, so one pair still bounds everything injected and
`strip_reminder` needs no second case.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling

## Verification

```
uv run --frozen --python 3.12 --all-extras pytest -q tests/ -k research
  774 passed in 61.74s

PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD
  clean

uv run --frozen --python 3.12 --extra dev ruff check agents tests
  All checks passed!

uv run --frozen --python 3.12 --extra dev ruff format --check agents tests
  907 files already formatted
```

Sixteen tests, weighted towards what the extractors refuse: four shapes of range
that are sizes rather than counts, a prose exclusion, a bare noun, the answer
itself, an empty task, the camel-cased name, and the unchanged bytes on a request
that carries nothing.
2026-09-07 05:35:48 +00:00
ZuyiZhou
3ab6df8504 feat(agents): the request's checkable parts ride back down to where it is answered
## Summary

Three of the dimensions lost on 2026-09-04 were not research failures. A named
section was absent from the report entirely, five candidates outside the stated
length envelope took slots in the main table, and the do-not-bother list carried
items the request had already ruled out. Each of those was stated in the request
and satisfied by intention rather than by checking, because by the time the report
is written the request is fifteen thousand tokens up the context - the same reason
the template reminder exists, and it rides the same seam.

`brief_checklist` reads a request for the parts a parser can settle and the
reminder carries them back:

```
Read literally, this message asks for: 15 to 25 items; nothing from LongBench,
LooGLE, ZeroSCROLLS, LoCoMo; a do-not-bother list; a community-convention table.
Deliver each one, or name it in `## Limitations` and say why it is absent.
```

Three properties are the whole design.

**It only reads; it never judges the answer.** No bounce, no model call, no
latency. The gate that owns bouncing says in its own docstring that it bounces for
a missing section and nothing else, and a checklist wrong about what was asked
would spend generations arguing with the reader. A checklist that is merely
incomplete costs nothing.

**It quotes rather than interprets.** The count is the range as written, the
exclusions are the names as written, the artefacts are the noun phrases as
written. A misread is then visibly a misread of the request rather than a rule the
harness invented, which is also why the sentence opens "read literally" and closes
with somewhere for a wrong item to go.

**It stays silent when unsure.** A range followed by a unit is a size, not a count
("16k-256k words", "2024-2026", "4x-8x", "8-80GB"). An exclusion stated in prose
("the four we already ran") yields nothing. A bare "a table" is not an artefact and
"a report" is the answer itself. On a request with no machine-readable constraints
the reminder renders exactly the bytes it always rendered - pinned by a test.

The one thing worth naming as a near-miss: an earlier form of the name rule
anchored on a leading capital and quoted `xRAG` back as `RAG`, which is a checklist
telling the model about a benchmark that does not exist. Items are now split first
and kept or dropped whole, and that case is a test.

No new config key, and no new injection seam: the checklist rides inside the
reminder's own delimiters, so one pair still bounds everything injected and
`strip_reminder` needs no second case.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling

## Verification

```
uv run --frozen --python 3.12 --all-extras pytest -q tests/ -k research
  774 passed in 61.74s

PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD
  clean

uv run --frozen --python 3.12 --extra dev ruff check agents tests
  All checks passed!

uv run --frozen --python 3.12 --extra dev ruff format --check agents tests
  907 files already formatted
```

Sixteen tests, weighted towards what the extractors refuse: four shapes of range
that are sizes rather than counts, a prose exclusion, a bare noun, the answer
itself, an empty task, the camel-cased name, and the unchanged bytes on a request
that carries nothing.
2026-09-07 05:35:47 +00:00
0xKT
d365264b41 fix(ppt-engine): let an outline's optional page fields arrive as null
## Summary

Two engine-side fixes for `ppt_outline` and `ppt_template`, both measured on live deck runs.

**1. Optional outline fields accept `null`.** `ppt_outline` declared every optional page field (`carries`, `layout`, `layers`, `anti_pattern`, `figures`, `says`, `section`, `role`, `needs`) as a bare `string` or `array`. A page whose `anti_pattern` was `null` was therefore refused by the registry's schema check before the tool ran, once per page, and the whole outline with it. A model with nothing to put in an optional field writes `null` as readily as it leaves the key out, and both readers (`_plan` at the tool, `load_outline` in the contracts) already read the two alike. Measured cost: three live runs lost an outline round to this (the amber run on 2026-09-06 twice, a Shanghai deck on 2026-09-07 once), each a minutes-long re-plan, each surfaced to the user as a wall of `pages[N].anti_pattern should be string` errors. The nine optional page fields now take `["<type>", "null"]`, the shape `prototype` and `borrowed` already had, and the two with an enum (`layout`, `role`) list `null` in the enum as well: a provider reads the parameters as JSON Schema, where `type` and `enum` apply together, so the type alone promised nothing there. `page` and `claim` stay required and still refuse `null`.

**2. The template roster rides on a bind, not on every page read.** A `ppt_template` call with `pages=[...]` returned the full roster (`canvas_in`, `layouts`, `example_pages`, `build_from`, `theme_colours`, `fonts`) ahead of the source, on every reply. The Shanghai run read pages in seven calls and received the same roster seven times, inside a reply the host already cuts at 16,000 characters. The roster is now assembled by one helper and attached to a bind and to a render call, where it first shows or changes; a bare page read returns the pages, the `pages_read` / `pages_cut` / `pages_not_read` bookkeeping, and the note when a `path` was ignored. A call that binds and reads in one go keeps the roster. The tool description says a `pages` call returns "those example pages, and only those".

Not in this MR: the amber run also once omitted the required `page` on every entry (`missing required pages[N].page`); numbering absent pages by position is a separate decision.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
PYTHONPATH=plugins-dist/ppt-engine uv run --frozen --no-sync pytest tests/test_ppt_engine_outline_roles.py tests/test_ppt_engine_outline_checks.py tests/test_ppt_engine_prompt_claims.py tests/test_ppt_engine_plugin.py -q
  -> 109 passed, 23 skipped (the skips are the fetched template payload, absent in this checkout)
PYTHONPATH=plugins-dist/ppt-engine uv run --frozen --no-sync pytest tests/test_ppt_engine_template_tool.py tests/test_ppt_engine_template.py -q
  -> 117 passed
uv run --frozen --no-sync ruff check / ruff format --check <4 files> -> clean
uv run --frozen --no-sync python scripts/check_source_language.py HEAD -> ok
```

Mutation checks: `test_a_page_saying_null_for_what_it_has_no_answer_to_is_accepted` drives the call through `ToolRegistry.execute`, so the schema check is the one under test; with `anti_pattern` put back to a bare `string` it fails (1 failed), and it pins that `claim: null` is still refused. `test_the_declared_schema_takes_null_in_every_optional_page_field_as_json_schema` validates the declared parameters with `jsonschema.Draft202012Validator` against a page with all nine optional fields null, and fails with `None is not one of ['', 'P1', ...]` when the layout enum loses its null. `test_a_page_read_carries_the_pages_and_not_the_roster_again` fails (1 failed) when the roster is attached unconditionally; `test_a_call_that_binds_and_reads_in_one_go_keeps_the_roster` pins the bind-and-read case.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none needed: the tool descriptions are the documentation the author model reads, and the `ppt_template` one is updated in this MR)

## Risk

Engine behaviour visible to the author model only. An outline carrying `null` in an optional page field is now accepted and read as empty, where before it was refused. A `ppt_template` page read no longer carries the roster; an author that wants the layouts again calls the tool with just the project (renders) or with `path` (bind), as before. Nothing in the recorded outline, the bound template, or the build changes. Rollback: revert the two commits.

- [x] Security impact considered (no new input reaches anything; the values were already accepted when the key was absent, and the roster change only removes fields from a reply)
- [x] Backward compatibility considered (outlines on disk are unaffected; the readers did not change)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-07 05:35:22 +00:00
Tchen
effe985f11 fix(ppt-engine): let an outline's optional page fields arrive as null
## Summary

Two engine-side fixes for `ppt_outline` and `ppt_template`, both measured on live deck runs.

**1. Optional outline fields accept `null`.** `ppt_outline` declared every optional page field (`carries`, `layout`, `layers`, `anti_pattern`, `figures`, `says`, `section`, `role`, `needs`) as a bare `string` or `array`. A page whose `anti_pattern` was `null` was therefore refused by the registry's schema check before the tool ran, once per page, and the whole outline with it. A model with nothing to put in an optional field writes `null` as readily as it leaves the key out, and both readers (`_plan` at the tool, `load_outline` in the contracts) already read the two alike. Measured cost: three live runs lost an outline round to this (the amber run on 2026-09-06 twice, a Shanghai deck on 2026-09-07 once), each a minutes-long re-plan, each surfaced to the user as a wall of `pages[N].anti_pattern should be string` errors. The nine optional page fields now take `["<type>", "null"]`, the shape `prototype` and `borrowed` already had, and the two with an enum (`layout`, `role`) list `null` in the enum as well: a provider reads the parameters as JSON Schema, where `type` and `enum` apply together, so the type alone promised nothing there. `page` and `claim` stay required and still refuse `null`.

**2. The template roster rides on a bind, not on every page read.** A `ppt_template` call with `pages=[...]` returned the full roster (`canvas_in`, `layouts`, `example_pages`, `build_from`, `theme_colours`, `fonts`) ahead of the source, on every reply. The Shanghai run read pages in seven calls and received the same roster seven times, inside a reply the host already cuts at 16,000 characters. The roster is now assembled by one helper and attached to a bind and to a render call, where it first shows or changes; a bare page read returns the pages, the `pages_read` / `pages_cut` / `pages_not_read` bookkeeping, and the note when a `path` was ignored. A call that binds and reads in one go keeps the roster. The tool description says a `pages` call returns "those example pages, and only those".

Not in this MR: the amber run also once omitted the required `page` on every entry (`missing required pages[N].page`); numbering absent pages by position is a separate decision.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
PYTHONPATH=plugins-dist/ppt-engine uv run --frozen --no-sync pytest tests/test_ppt_engine_outline_roles.py tests/test_ppt_engine_outline_checks.py tests/test_ppt_engine_prompt_claims.py tests/test_ppt_engine_plugin.py -q
  -> 109 passed, 23 skipped (the skips are the fetched template payload, absent in this checkout)
PYTHONPATH=plugins-dist/ppt-engine uv run --frozen --no-sync pytest tests/test_ppt_engine_template_tool.py tests/test_ppt_engine_template.py -q
  -> 117 passed
uv run --frozen --no-sync ruff check / ruff format --check <4 files> -> clean
uv run --frozen --no-sync python scripts/check_source_language.py HEAD -> ok
```

Mutation checks: `test_a_page_saying_null_for_what_it_has_no_answer_to_is_accepted` drives the call through `ToolRegistry.execute`, so the schema check is the one under test; with `anti_pattern` put back to a bare `string` it fails (1 failed), and it pins that `claim: null` is still refused. `test_the_declared_schema_takes_null_in_every_optional_page_field_as_json_schema` validates the declared parameters with `jsonschema.Draft202012Validator` against a page with all nine optional fields null, and fails with `None is not one of ['', 'P1', ...]` when the layout enum loses its null. `test_a_page_read_carries_the_pages_and_not_the_roster_again` fails (1 failed) when the roster is attached unconditionally; `test_a_call_that_binds_and_reads_in_one_go_keeps_the_roster` pins the bind-and-read case.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none needed: the tool descriptions are the documentation the author model reads, and the `ppt_template` one is updated in this MR)

## Risk

Engine behaviour visible to the author model only. An outline carrying `null` in an optional page field is now accepted and read as empty, where before it was refused. A `ppt_template` page read no longer carries the roster; an author that wants the layouts again calls the tool with just the project (renders) or with `path` (bind), as before. Nothing in the recorded outline, the bound template, or the build changes. Rollback: revert the two commits.

- [x] Security impact considered (no new input reaches anything; the values were already accepted when the key was absent, and the roster change only removes fields from a reply)
- [x] Backward compatibility considered (outlines on disk are unaffected; the readers did not change)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-07 05:35:22 +00:00
0xKT
f8885923aa fix: drop workspace members from exported install constraints
## Summary

`uv export --no-emit-project` leaves workspace members in the exported constraints as unnamed editables (`-e ./plugins-dist/...`), and `uv tool install -c` rejects unnamed requirements. Since `plugins-dist/*` joined the uv workspace (2026-08-31), every constraints-pinned install path failed at constraint parsing: `./install.sh` from a checkout (all three fallbacks), `install.ps1` on Windows, and any beta published by `scripts/publish_beta.py`, whose `raven-constraints.txt` is what `raven upgrade` downloads for `-c`. The `release.yml` copy was latent until the next GitHub tag; no published release carries a bad file (v0.1.13 predates the defect).

Key decisions:

- Switch all four trunk export sites to `--no-emit-workspace`: it drops the members along with the root project and keeps every transitive pin. The export loses exactly the three editable lines and their via comments (697 -> 691 lines).
- Add `tests/test_constraints_export_contract.py` as the tripwire: any export site using `--no-emit-project` inside a project that declares `[tool.uv.workspace]` fails; the four trunk sites are pinned by name so a rename cannot blind the scan; the vendored forks' 12 export sites stay watched. The forks themselves are untouched: their `--no-emit-project` is correct while they declare no workspace, and the contract fires the day one appears.

Not covered here: `install.ps1` was not executed end to end (no PowerShell on the dev machine; the flag semantics are proven by the same uv binary through the sh path), and a beta published between the defect (2026-08-31) and this fix would still carry a bad constraints file in the registry until the next `make beta` overwrites it.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- Reproduced the reported three-error cascade at the unfixed base with a sandboxed replica of install.sh's install core (`UV_TOOL_DIR` / `UV_TOOL_BIN_DIR` isolated, real tool env untouched).
- Same replica after the fix: install passes on the first attempt (154 packages, everos plugin editable installed), `raven --version` runs from the sandbox bin, no fallback fires.
- `uv export` variants (install `--frozen`, release `--locked`, beta unlocked) each emit 0 unnamed requirements; `uv pip install --dry-run -c <file> packaging` accepts the fixed file.
- Mutation audit of the contract test: reverting install.sh's flag fails 2 of its tests; adding a `[tool.uv.workspace]` table to a fork fails the tripwire naming all 3 of that fork's sites; both mutations restored.
- `make test-python`: 19154 passed, 133 skipped, 0 failed (7m36s).
- After rebase onto latest main: `uv run pytest tests/test_constraints_export_contract.py tests/test_updates_beta_channel.py tests/test_updates_upgrade.py tests/test_vendored_invariants.py -q` -> 194 passed.
- `make lint-python`, `make check-commits`, `make check-vendored-subagents`, `make check-vendored-invariants`, `scripts/check_source_language.py`, `scripts/check_large_files.py`: all pass.
- No user-facing docs affected: RELEASING.md describes the CI step without naming the flag and stays accurate.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

- User-visible change: `./install.sh` / `install.ps1` from a source checkout work again, and `make beta` publishes a usable constraints file. Constraint strength is unchanged (same pins, minus the three unnamed editable lines uv rejected).
- Rollback: revert the single commit; the installers return to failing at constraint parsing, nothing else depends on the new flag.
- No security surface: the change alters which lines an already-local export writes, not what gets downloaded or executed.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-07 05:34:33 +00:00
0xKT
2f862d8ca2 feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## 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.
2026-09-05 17:09:13 +00:00
hylarucoder
c703db6ffd feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## 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.
2026-09-05 17:09:13 +00:00
0xKT
b4c23d184f fix(*): review findings: hot-start door bypass, installer argv split, roster drift
The MR review's two blocking findings, the coverage gap behind them, and
the same-class drift the fixes surfaced:

- gateway: start_one routes the section through dispense_channel_config
  before the factory, via a _build_channel helper both entrances share,
  so a hot-started declaring channel reads nested cargo exactly as a
  cold-started one does instead of raising AttributeError on its first
  matching message. The door's refusal becomes a drawable outcome word
  (bad_config, charter description updated), and the missing-dependency
  probe now builds the same dispensed view so bad cargo cannot mask a
  missing SDK.
- install.sh: the everos-memory requirement is a space-free PEP 508
  direct reference. The spaced form word-split into four argv entries
  under sh, every uv rung failed with "unexpected argument", and each
  release that shipped the sibling wheel silently degraded to a bare
  install. A new test pins the spelling.
- channels: discover_channel_names skips plain modules, the rule
  discover_specs always applied, so a stray file beside the adapters
  cannot become a phantom channel in rosters derived from the names.
- tests: the all-channel parametrizations derive from the spec registry;
  the retired ChannelsConfig reflection collected zero cases and skipped
  silently. A roster guard pins the list non-empty and equal to the
  writer's universe.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-31 16:21:01 +08:00
0xKT
e2807f39bc fix(plugins): the everos move's install face closes
One wave back the backend left the wheel; the registry path degraded
loudly and everything else did not. Seven host surfaces imported the
plugin package directly -- 25 function-level imports, none guarded -- so
an install without the distribution turned raven doctor, onboard,
import, the memory RPC methods and the sub-agent trace writer into
tracebacks instead of the loud degrade the ruling requires. And no
install path carried the distribution at all: install.sh built only the
root project and the release published only its wheel, so a released
raven upgraded straight into the degraded state its own default config
names.

The host now asks one question, everos_plugin_installed -- a spec lookup
that executes no plugin code, so an installed-but-broken plugin stays a
visible bug instead of reading as an absence -- and each surface answers
in its own register: doctor reports plugin_missing as the fault it is,
onboard names what to install, the RPC returns its own error shape, the
trace writer logs once. install.sh carries the distribution on both its
paths with a degrade ladder that never blocks the install, the release
builds and uploads the sibling wheel, and the diff-coverage gate's
pathspec follows the code it had lost sight of. The absence tests take
the package away for real (a sys.modules sentinel) rather than stubbing
the guard they exist to prove.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-31 06:09:43 +08:00
Handsome-wzw
c065cb0f3c refactor: rename ui to ui-web
## Summary

Rename `ui/` to `ui-web/`. Second half of the `ui-webui` retirement (!425): with three directories called some variant of "ui", the served page had the name that says least about it.

Mechanical, but it reaches CI, the release workflow and the wheel build, so it is its own MR rather than 155k lines of deletion with a rename hidden in it.

## The one decision worth reviewing

**The path inside the wheel stays `raven/ui/dist`. The source tree becomes `ui-web/`.**

Two names on purpose:

- `ui-web/` is what this repository calls the page's sources.
- `raven/ui/dist` is the **installed layout**. `_install_guard` reads it back out of the installed RECORD (`PAGE_RECORD_ENTRY`), the release workflow and `publish_beta.py` assert it inside the built wheel, and anything outside this repository that packages or copies an installed raven may name it.

Renaming a source directory is not a reason to move a path that leaves the repository, and "不破坏" was the constraint I was given. So `hatch_build.py` copies `ui-web/dist` → `raven/ui/dist`, with the reason written where the two sit next to each other, and the same note beside `_UI_DIR` / `_PACKAGED_UI_DIST` in `serve_commands.py`.

`test_hatch_build.py` now asserts the source and the destination as two *different* strings, with a comment saying it is deliberate — otherwise the next reader files the mismatch as drift and "fixes" it.

**If you would rather the wheel path move too, say so and I will do it in this MR** — it is `PAGE_RECORD_ENTRY`, two assertions in `release.yml`, two in `publish_beta.py`, `hatch_build.py`, `_PACKAGED_UI_DIST`, and the doctor/install-guard message text.

## What was deliberately not renamed

- **`docs/plans/` and `docs/specs/`.** They record what was true when written, and one (`2026-08-25-build-wrapup-precondition.md`) is a verification log of a run that actually happened — rewriting it would be editing a record. Same rule I applied in !425.
- **The vendored sub-agent trees under `subagents/`.** My first pass hit four of them; every match was `ui/composer` used as a *concept*, not a path, and those trees answer to `check_vendored_invariants`. Reverted.

## Verification

- `uv run pytest -q` — **12610 passed**, 50 skipped, **5 failed**
  - The 5 are pre-existing on `origin/main`: same node ids fail on an untouched `origin/main` worktree at the merge base (`e1011cb1`). Four `test_security_network.py` NAT64 cases, one `test_cli_doctor_commands.py::test_doctor_answers_where_the_memories_are`.
  - A 6th failed on my first run and was **mine**: `test_hatch_build.py::test_an_editable_install_gets_no_copy_of_the_web_assets`, which is exactly the test that should catch a rename touching the wheel path. Fixed as described above.
- `uv run ruff check raven tests scripts` — All checks passed
- `uv run ruff format --check raven tests scripts` — 1241 files already formatted
  - (Both halves. On !425 I ran only the first and CI caught the second.)
- `npm run build --prefix ui-web` + `python3 ui-web/build.py` + `check-page.mjs`, `check-css.mjs`, `count-shared-globals.mjs` — pass
- `npx vitest run` in `ui-web` — 89 files, 1222 passed
- `npm run gen:check --prefix ui-web` — in sync, 147 methods; `type-check` clean
- `scripts/check_vendored_invariants.py`, `scripts/check_vendored_subagents.py` — pass
- `git diff --check origin/main...HEAD` — clean
- `scripts/commit_lint` — no errors
- `git ls-files | grep -c node_modules` — 0

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear

No wire change, no behaviour change. The installed layout is unchanged, which is the compatibility surface that matters. The blast radius is build and CI paths, all of which are exercised above. Rollback is a revert.

**Merge order:** independent of !425 except for one line in `AGENTS.md` that lists the application source trees; whichever lands second takes a one-line conflict there.
2026-08-28 12:51:24 +00:00
Handsome-wzw
9a87470fdf fix(rpc): turn.started is a turn event, and says so on all three sides
## Summary

Found while investigating the first row of Dizhan's `子智能体功能与显示问题` doc (*回注内容过程中未正常显示,刷新后才会正常显示*). This is not that bug's fix, but it is a real defect on the same wire, and it is the one that explains why "前后端接线没有约定好" was a fair thing to say.

**`turn.started` is not in the `TurnEvent` union — on either side.** It has a schema component, it has a Pydantic model, and neither is reachable from the union that `tests/test_rpc_schema_match.py` walks. The 290-test contract guard has never looked at this event.

So it drifted the first time anyone touched it. `05957452` (judge a dag node) taught `announce_dag_exception` to emit:

```python
mark = {"kind": "dag", "label": run_id, "status": "exception", "run_id": run_id, "node_id": node_id}
```

while `TurnStartedEvent.payload.delegated` still declared `status: enum ["ok","error"]` with `additionalProperties: false`, and `TurnStartedPayload` had **no `delegated` field at all** under `extra="forbid"`. Verified with `jsonschema` against the published contract before changing anything:

```
Additional properties are not allowed ('node_id' was unexpected)
```

That commit did carry `exception` into `TranscriptDelegated` and `SubagentDeliveredEvent` — two of the three places this status lives. The third is the one no test covers.

**It does not crash today**, and I want to be exact about that: `SubscriptionEmitter.emit` pushes a raw dict with no validation, and the page reads only the fields it knows. But the contract test's own docstring says what the cost is — *"both sides declare `additionalProperties: false` / `extra="forbid"`, so a consumer validating against the schema rejects the whole event, not just the unknown field"*. Losing this event loses the boundary that advances the workspace turn counter and draws the delegated row.

## What this does

- `TurnStartedEvent` joins the `TurnEvent` union, in `openrpc.json` and in `raven/rpc/models.py`, so the existing sweep covers it from now on.
- The schema's `delegated.status` gains `exception`; `node_id` is declared.
- `TurnStartedPayload` gains `delegated` as a typed model (`TurnStartedDelegated`), three-valued status included.
- Both generated TypeScript clients regenerated.
- A new test drives **the exact marker `manager.py` builds** through both validators, so the next status or field fails here instead of in a client nobody is watching.

## One thing the union surfaced

`ui-tui` never handled `turn.started`. Its exhaustiveness check said so the moment the variant existed. It draws the delegated row from `subagent.delivered`, which the page deliberately ignores in favour of this event — the two mark different moments: **submitted** versus **started**.

Left as it is, with an explicit `case 'turn.started'` saying why. Moving that surface onto the truer moment changes when the TUI draws the row, which is a product change, not a contract fix.

## Verification

- New test red before the fix, by construction: adding the variant to the union alone reds `test_schema_match_turn_event_discriminated_union` and `..._payload_fields` (schema/pydantic drift), which is how the gap was proved.
- Mutation checks, each reverting one thing:

| reverted | reds |
|---|---|
| `exception` out of the schema enum | 1 |
| `node_id` out of the schema | 1 |
| `delegated` off the Pydantic payload | 2 |

- `uv run pytest -q` — **12900 passed**, 50 skipped, 5 failed; the same five pre-existing on `origin/main` (four `test_security_network.py` NAT64 cases, one `test_doctor_answers_where_the_memories_are`), reproduced on an untouched merge-base worktree.
- `uv run ruff check` / `ruff format --check` on `raven tests scripts` — both clean (both halves of `make lint-python`).
- `ui`: `gen:check` 147 methods, `type-check` clean, `npx vitest run` 89 files / **1225 passed**.
- `ui-tui`: `type-check` clean, `lint:rpc` in sync, `lint:i18n` up to date, `npm test` 138 files / **1990 passed**.
  - Worth recording: with `ui-tui/node_modules` symlinked from another checkout the suite reports 82 failed / 59 failed — and reports **the same numbers on an untouched `origin/main`**. It is the symlink, not the branch. Ran `npm ci` in the worktree to get a trustworthy number.
- `scripts/commit_lint` — no errors.
- `git ls-files | grep -c node_modules` — 0.

## Type

- [x] Fix

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear

Widening a contract to match what the runtime already emits: every payload valid before is valid now. No emit site changes, no behaviour changes. The one code change outside the schema and the models is an explicit no-op branch in `ui-tui`. Rollback is a revert.
2026-08-28 12:51:10 +00:00
forrestjgq
8ecfae3e0c test(tracing): isolate span emission into per-test tmp dirs (#371)
## Summary

Unit tests were leaking tracing spans into the real `~/.raven/traces`
store. Tracing is on by default and `trace.span()` calls are embedded in
library code (agent loop, subagents, TUI RPC), so any test exercising
those paths emitted spans with fabricated session keys (`session-a`,
`weixin:c`, `tui:default`, ...). Those spans then surfaced as phantom
sessions in `raven trajectory`, while the TUI `/sessions` list (which
reads the real session store) stayed clean.

This PR adds an autouse fixture in `tests/conftest.py` that:

- redirects `RAVEN_TRACING_DIR` to a per-test tmp directory, and
- resets the lazy module-level `TraceStore` cache
(`raven.tracing.spans._store`) around each test, since it pins the
directory resolved at first emit.

Key decisions:

- Only the directory is redirected, not the enabled switch, so the suite
keeps exercising the real emission path with zero behavior change; leaks
land in tmp instead.
- This centralizes the setenv-plus-cache-reset pattern that 8
tracing/trajectory test files already perform manually. Those tests keep
working: their own `monkeypatch.setenv` runs after the fixture and wins,
and they already reset the cache themselves.
- Existing phantom sessions come from archived span logs written before
this fix; the fixture only prevents new leaks. One archive file mixes a
real session with test keys, so cleanup needs line-level filtering and
is left out of scope.

## Type

- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other

Test-suite hygiene (`test` commit type).

## Verification

- `uv run pytest tests/test_tracing_api.py
tests/test_trajectory_store.py tests/test_trajectory_bundle.py
tests/test_trajectory_replay.py tests/test_trajectory_redact.py
tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py -q`: 308 passed, 1 failed
(`test_viewer_health_true_for_our_viewer`, fails identically on
unmodified `main`, environment-specific)
- `uv run pytest tests/test_agent_loop_run_emit.py
tests/test_subagent_manager.py tests/test_tui_rpc_turn_send.py
tests/test_deep_research_tool.py tests/test_agent_loop_approval.py -q`:
109 passed; the real `~/.raven/traces` log did not grow during the run
- Positive check: running `tests/test_agent_loop_run_emit.py` with
`--basetemp` shows the previously leaked session keys (`cli:c`, `tg:c`,
`weixin:c`) now land in per-test tmp dirs
- `uv run pytest tests/ --ignore=tests/integration -q`: 6837 passed, 11
failed, 20 errors; the same failure set reproduces on unmodified `main`
(environment-specific: cron/tz, everos server, theme, config loader,
viewer health), zero regressions from this change
- `uv run ruff check tests/conftest.py` and `uv run ruff format --check
tests/conftest.py`: both pass

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

Docs box left blank: test-only change, no user-facing docs affected.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

Test-only change; no production code touched. One known interaction:
`RAVEN_TRACING_DIR` takes precedence over `RAVEN_HOME`, so a future test
that fakes `RAVEN_HOME` and expects traces under it must also set
`RAVEN_TRACING_DIR` itself. Rollback: revert the single commit.

## Related Issues

N/A

Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-28 19:21:16 +08:00
Tchen
66090c4626 fix(ppt): make a weighted table answer the height it draws
## Summary

`table_size` and `table` answered different heights for the same weighted table, and the
gap was drawn on top of whatever came next on the page.

`_table_geometry.spread_of` discarded `weights` when given no box:

    weights = None if box is None else weights

under a comment claiming "the height is exact either way". That claim was false. Weights
are proportions of the box a table is given, so an unboxed answer measured at the
content's own column widths is a height for a differently-shaped table. `docs/ppt-raven-design.md`
D13 states this cannot happen -- "`table_size` and `table` go through the same
`_table_geometry`, so the size asked for not being the size drawn is impossible, not
merely unlikely" -- and it was happening.

Measured on a delivered page (`cnn-grokbh2` page 15, identical bytes in the delivered
file and the job output): a table handed a 1.8333in box drew at 2.0656in and sat 0.0922in
inside the note panel below it, and **no finding of any kind was recorded for that page**.
Four checks miss it, each correctly by its own terms: `rendered.py::_escaped()` files
every `has_table` frame into `elsewhere` so `box_overflow` structurally cannot see it;
`overlap.py`'s `COVERED = 0.6` is not met by 4.5%, and the table is drawn first so it is
the subject rather than the cover; `off_page` measures the canvas edge only;
`content.py::native_tables` states it "does not judge how much of its region a table
fills". `word_collision` staying silent is correct -- no glyph touches a glyph.

So the fix is that the arithmetic has to agree, not that a check has to fire. Given
weights with no box are now apportioned over `sum(content)`, the width the unboxed answer
already reports as `.w`. Same fixture as the delivered page: the answer goes 1.833 ->
2.066in, which is the height actually drawn at that page's lane widths.

Two follow-on defects surfaced in review and are fixed here:

- **a mark could squeeze a column below one glyph.** With a fixed unboxed width,
  `_mark_floors` was still funded with `inf`, so `_column_widths` scaled full mark floors
  into a width that could not grow. `reserve` is now the divided width for a weighted
  unboxed table (hoisted from the `_column_widths` call beside it, so no number is typed)
  and stays `inf` for an unweighted one, whose width *is* the sum of the shares the floors
  raise. A marked weighted answer now equals its unmarked one, which is what
  `_mark_floors`' docstring already promised for the boxed case.
- **`_wrapped` never terminated on a box narrower than one character.** `cut =
  len(current) - 1` was 0 for a one-character token, so `current[cut:]` returned the
  string unchanged. Now `max(1, ...)`: the character takes a line of its own and overflows
  it, and overflow is measured off the render and reported. This loop is pre-existing on
  `main` and reachable with no marks at all.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

    uv run pytest tests/ppt/test_assets_script_helpers.py tests/ppt/test_script_backend.py tests/ppt/test_build_stage.py
    162 passed

Generalisation swept, because a narrow answer is the failure mode here: 4 weight shapes x
marks/no-marks x 4 box widths, 32 calls, **every one returns**. `answered.w` is identical
with and without marks for all three weight shapes. `drawn.h <= answered.h` holds at every
box at or above the answered width and fails below it, in every combination -- so the
docstring's stated limit ("a box at least this wide") is the honest limit and is left as
written rather than widened.

The loop fix verified against both trees directly, not inferred: `_wrapped` at a
sub-glyph width returns the characters whole on this branch and hangs on `origin/main`,
where faulthandler ends it at 20s inside `_wrapped`.

Revert proof, each fix against the test that guards it:

| reverted | marks test | loop test |
|---|---|---|
| `reserve` only | FAIL, `3.373 != 2.081` | pass |
| `max(1, ...)` only | pass | FAIL, TimeoutError |
| both | FAIL, TimeoutError | FAIL, TimeoutError |

`assert asked.h > plain.h` fails on `origin/main` with `1.3611 > 1.3611` -- the weights
never reached the answer. One existing test asserted `weighted.h == loose.h`, which is the
false claim itself, and was rewritten.

The timeout regressions use a `SIGALRM` context manager rather than a worker thread, so
the signal raises inside the loop and ends it; a leaked thread would keep appending for
the rest of the session. `pytest-timeout` is not a dependency.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No doc change: D13 already states the property this restores, and `_mark_floors`'
docstring already stated the mark promise -- its wording was widened to cover the unboxed
case in the same commit rather than a new claim being added.

## Risk

`table_size` answers a taller height for a weighted call given no box, which is the point:
it is now the height that gets drawn. A caller that reserved the old, smaller number gets
more room; a `Stack.take()` of the new height can overrun a region that previously
appeared to fit, which surfaces as the existing take-overrun message rather than as
silent overflow.

The first commit on this branch (`fecd3639`) made `table()` raise on overflow and was
blocked for turning a warning-only measurement into a build failure. It is left in history
so the decision is visible; the raise is reverted and `table()` draws and returns its
actual box.

Flagged rather than folded in: at 0.35x with marks, `table()` now reaches the pre-existing
`_harvey` guard ("a 5-step scale does not fit in 0.06in", untouched here). Those cells hung
before, so a stated refusal in milliseconds is strictly better -- but it is still a raise
inside a generated build script and deserves its own decision under invariant 6 / D2.

Rollback is reverting the three commits; nothing migrates.

## Related Issues

N/A
2026-08-28 08:13:58 +00:00
Tchen
e3a1aadd3e fix(ppt): make a weighted table answer the height it draws
## Summary

`table_size` and `table` answered different heights for the same weighted table, and the
gap was drawn on top of whatever came next on the page.

`_table_geometry.spread_of` discarded `weights` when given no box:

    weights = None if box is None else weights

under a comment claiming "the height is exact either way". That claim was false. Weights
are proportions of the box a table is given, so an unboxed answer measured at the
content's own column widths is a height for a differently-shaped table. `docs/ppt-raven-design.md`
D13 states this cannot happen -- "`table_size` and `table` go through the same
`_table_geometry`, so the size asked for not being the size drawn is impossible, not
merely unlikely" -- and it was happening.

Measured on a delivered page (`cnn-grokbh2` page 15, identical bytes in the delivered
file and the job output): a table handed a 1.8333in box drew at 2.0656in and sat 0.0922in
inside the note panel below it, and **no finding of any kind was recorded for that page**.
Four checks miss it, each correctly by its own terms: `rendered.py::_escaped()` files
every `has_table` frame into `elsewhere` so `box_overflow` structurally cannot see it;
`overlap.py`'s `COVERED = 0.6` is not met by 4.5%, and the table is drawn first so it is
the subject rather than the cover; `off_page` measures the canvas edge only;
`content.py::native_tables` states it "does not judge how much of its region a table
fills". `word_collision` staying silent is correct -- no glyph touches a glyph.

So the fix is that the arithmetic has to agree, not that a check has to fire. Given
weights with no box are now apportioned over `sum(content)`, the width the unboxed answer
already reports as `.w`. Same fixture as the delivered page: the answer goes 1.833 ->
2.066in, which is the height actually drawn at that page's lane widths.

Two follow-on defects surfaced in review and are fixed here:

- **a mark could squeeze a column below one glyph.** With a fixed unboxed width,
  `_mark_floors` was still funded with `inf`, so `_column_widths` scaled full mark floors
  into a width that could not grow. `reserve` is now the divided width for a weighted
  unboxed table (hoisted from the `_column_widths` call beside it, so no number is typed)
  and stays `inf` for an unweighted one, whose width *is* the sum of the shares the floors
  raise. A marked weighted answer now equals its unmarked one, which is what
  `_mark_floors`' docstring already promised for the boxed case.
- **`_wrapped` never terminated on a box narrower than one character.** `cut =
  len(current) - 1` was 0 for a one-character token, so `current[cut:]` returned the
  string unchanged. Now `max(1, ...)`: the character takes a line of its own and overflows
  it, and overflow is measured off the render and reported. This loop is pre-existing on
  `main` and reachable with no marks at all.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

    uv run pytest tests/ppt/test_assets_script_helpers.py tests/ppt/test_script_backend.py tests/ppt/test_build_stage.py
    162 passed

Generalisation swept, because a narrow answer is the failure mode here: 4 weight shapes x
marks/no-marks x 4 box widths, 32 calls, **every one returns**. `answered.w` is identical
with and without marks for all three weight shapes. `drawn.h <= answered.h` holds at every
box at or above the answered width and fails below it, in every combination -- so the
docstring's stated limit ("a box at least this wide") is the honest limit and is left as
written rather than widened.

The loop fix verified against both trees directly, not inferred: `_wrapped` at a
sub-glyph width returns the characters whole on this branch and hangs on `origin/main`,
where faulthandler ends it at 20s inside `_wrapped`.

Revert proof, each fix against the test that guards it:

| reverted | marks test | loop test |
|---|---|---|
| `reserve` only | FAIL, `3.373 != 2.081` | pass |
| `max(1, ...)` only | pass | FAIL, TimeoutError |
| both | FAIL, TimeoutError | FAIL, TimeoutError |

`assert asked.h > plain.h` fails on `origin/main` with `1.3611 > 1.3611` -- the weights
never reached the answer. One existing test asserted `weighted.h == loose.h`, which is the
false claim itself, and was rewritten.

The timeout regressions use a `SIGALRM` context manager rather than a worker thread, so
the signal raises inside the loop and ends it; a leaked thread would keep appending for
the rest of the session. `pytest-timeout` is not a dependency.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

No doc change: D13 already states the property this restores, and `_mark_floors`'
docstring already stated the mark promise -- its wording was widened to cover the unboxed
case in the same commit rather than a new claim being added.

## Risk

`table_size` answers a taller height for a weighted call given no box, which is the point:
it is now the height that gets drawn. A caller that reserved the old, smaller number gets
more room; a `Stack.take()` of the new height can overrun a region that previously
appeared to fit, which surfaces as the existing take-overrun message rather than as
silent overflow.

The first commit on this branch (`fecd3639`) made `table()` raise on overflow and was
blocked for turning a warning-only measurement into a build failure. It is left in history
so the decision is visible; the raise is reverted and `table()` draws and returns its
actual box.

Flagged rather than folded in: at 0.35x with marks, `table()` now reaches the pre-existing
`_harvey` guard ("a 5-step scale does not fit in 0.06in", untouched here). Those cells hung
before, so a stated refusal in milliseconds is strictly better -- but it is still a raise
inside a generated build script and deserves its own decision under invariant 6 / D2.

Rollback is reverting the three commits; nothing migrates.

## Related Issues

N/A
2026-08-28 08:13:58 +00:00
LivXue
923f3a18c0 feat(install): build the served page, and keep web assets out of editable wheels
## Summary

A source install now ends up with both web assets, and an editable build stops
carrying copies of them that nothing reads.

`ui/dist/index.html` (the page `raven web` serves) and `ui-tui/dist/entry.js`
(the TUI bundle) are both gitignored build artifacts. A release wheel carries
them; an editable install of a checkout gets neither. The installers built only
the bundle, so `raven web` exited 1 with "No page is built" on every source
install until someone ran `ui/build.py` by hand.

Two changes:

1. `install.sh` and `install.ps1` build the page in their local-editable branch,
   beside the bundle. Both artifacts share one node/npm probe, so their skip
   paths cannot drift apart. Python for the page assembler comes from uv,
   already a hard requirement of both installers, rather than from a bare
   `python3` / `python`: on a fresh macOS that name is a stub that prompts for
   the Command Line Tools, and on Windows it is usually the Microsoft Store
   stub. A failed page build warns and lets the install finish, unlike the
   bundle, whose failure aborts the script -- bare `raven` opens the TUI,
   so a machine that cannot build the page still gets the surface the installer
   exists to deliver.

2. `hatch_build.py` skips both force-includes for an editable build, the guard
   the vendored sub-agent tree already had. Hatchling honours the map for
   editable builds too, and an editable install resolves both artifacts from the
   checkout it was built from -- the packaged path both resolvers try first
   points inside the checkout's own `raven/`, where neither exists. The two
   warnings go with the map rather than firing mode-blind: they tell the reader
   what to run before building a release wheel, which an editable build is not,
   and the command that needs a missing artifact already says so accurately
   (`raven tui` names both candidate paths and the npm command, `raven web`
   names `ui/build.py`).

Review round: the PowerShell installer's bundle build was reading back neither
native exit code, so on Windows a failed `npm ci` returned to the caller, ran
`npm run build` anyway, continued through the page build and the raven install,
and reported success with no bundle -- leaving bare `raven`, which opens the
TUI, unusable. Both calls now read `$LASTEXITCODE` back and abort, which is
what `install.sh` already did under `set -e`. It was never a 5.1-only hazard:
`$PSNativeCommandUseErrorActionPreference` is False by default as late as
PowerShell 7.6.5, measured there.

Still deliberately asymmetric: a failed page build warns and lets the install
finish, while a failed bundle build aborts it. Bare `raven` opens the TUI, so a
machine that cannot build the page still gets the surface the installer exists
to deliver, and `raven web` names `ui/build.py` when it finds none.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Installers, driven as functions against a real checkout:

- `sh -n`, `dash -n`, `bash -n` on `install.sh` -- clean.
- Full success path from zero artifacts: both built. The assembler reported
  `built dist/index.html (1,241,498 bytes)` and `copied dist/assets (286,416
  bytes)`; that first figure is characters, since `ui/build.py` prints
  `len(out)`, and the file is 1,277,613 bytes on disk once the inlined
  catalogue's multi-byte characters are counted. The bundle came out at
  3,018,503 bytes. `resolve_ui_dist()` then returns the built directory, so
  `raven web` starts.
- Degradation, with a PATH holding coreutils but neither node nor npm:
  `No usable node found; skipping the served-page build; raven web will not
  start`. With a node shim and no npm: `Found node but not npm; ...`. With
  `npm ci` exiting 1: the warning fires and the script continues. The `set -e`
  behaviour behind that was reproduced in dash and bash first -- a failing
  subshell aborts the script, and `set -e` does not apply inside a function its
  caller guards with `||`, which is why the page build is one `&&` chain.
- `install.ps1` under PowerShell 7.6.5: `Parser::ParseFile` reports no errors,
  on the base copy too as a control. `Build-WebAssets` was then executed across
  six states -- both artifacts present (silent), page missing without npm (one
  warning naming the page), both missing without npm (two warnings, the
  bundle's own wording preserved), success (an argv log shows `npm ci`,
  `npm run build`, then `uv run --no-project python <abs>/ui/build.py`), the
  page's `npm ci` exiting 7 (warns, and never reaches the assembler), and the
  bundle's `npm ci` exiting 1 (aborts with `TUI bundle build failed: npm ci
  exited 1`, having run no second npm and never started the page build). The
  last state fails on the pre-fix file exactly as the finding described: the
  argv log there shows all four npm calls and the assembler, and the function
  returns normally with no bundle on disk.

Build hook, measured by building the wheel both ways rather than read:

- Editable wheel before: 4,647,584 bytes of force-included files
  (`raven/ui-tui` 3,018,503, `raven/ui/` 1,564,029, `raven/bridge` 65,052).
  After: 65,052 bytes, all of it the `bridge` entry from `pyproject.toml`.
- Standard wheel after: still carries `raven/ui/dist/index.html` and
  `raven/ui-tui/dist/entry.js`. Release and beta both build with
  `uv build --wheel`, so neither is affected.

Tests and gates:

- `pytest` per file: `tests/test_hatch_build.py` 10 passed,
  `tests/test_cli_onboard_commands.py` 290 passed,
  `tests/test_cli_serve_commands.py` 75 passed,
  `tests/test_channels_manager.py` 24 passed,
  `tests/test_cli_tui_bootstrap.py` 19 passed.
- `tests/test_cli_doctor_commands.py` 1 failed, 70 passed:
  `test_doctor_answers_where_the_memories_are`. It fails identically with this
  branch's five files reverted to the target branch, and no file under `raven/`
  is touched here.
- The new tests were proved load-bearing by reverting each half separately:
  with the installers reverted the installer test fails on its first assertion,
  with the hook reverted both new hook tests fail, and with the bundle branch
  restored to its unchecked form the exit-code test names both offending lines.
  That last test is structural rather than about one branch -- it requires every
  `npm` invocation in the file to be followed by a `$LASTEXITCODE` read, so a
  future call cannot reintroduce the hazard. It is text-based because no
  PowerShell runs in CI.
- `make lint-python`: all checks passed, 1236 files already formatted.
  `make check-vendored-subagents`, `make check-vendored-invariants`,
  `make check-large-files`, and `scripts/check_commit_messages.py` each exit 0.
- Not run: the JS lint targets, since the diff contains no JS or TS.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

The docs box is blank on purpose. `README.md` describes what a clone install
adds (the sub-agents) and never enumerated build artifacts -- the bundle was
not listed there either -- so no claim needed updating, and the recovery hints
in `serve_commands.py` and `hatch_build.py` stay accurate.

## Risk

`raven web` starts on a source install where it used to exit 1. That page binds
`127.0.0.1` and its token is stored 0600, so this makes an existing loopback
surface reachable rather than adding one, and nothing about how it
authenticates changes.

An editable install no longer holds packaged copies of the two assets. Both
resolvers already preferred the checkout's own copy there, and no diagnostic
reports the packaged path, so nothing reads what is no longer written.

Rollback: revert either commit on its own. The first adds a build step to the
installers' local branch and nothing else; the second only narrows a
force-include map.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-08-28 08:10:53 +00:00
arelchan
7c33c4133a fix(rpc): let the viewer open the files a turn actually wrote
## Summary

A delivered artifact could not be opened from the page: the file viewer answered
403 and the transcript drew "Raven is confined to the workspace, so this file
cannot be opened here" over a delivery card it had just rendered.

The viewer's state-directory fence exempts the workspace subtree, on the stated
grounds that the default workspace lives inside raven's home and denying it
would refuse every file the agent itself wrote. Since agent home and the working
directory were split apart, a turn no longer writes there: it writes in
`~/.raven/tmp/<channel>`, a sibling of the workspace, inside the same state root
and outside the carve-out. So the fence denied exactly what the carve-out exists
to allow, one directory over, for every artifact produced since that split.

This exempts the working-directory root alongside the workspace, using the same
containment test in the same direction, so a working-directory root that happens
to sit above raven's home earns no exemption. `config.json`, `oauth/` and
`serve.json` are siblings of both and stay refused, which is what the fence is
for.

Worth noting for a reviewer: the bytes were already reachable. `/files/download`
serves a delivered file by token with no path fence, so this was never a
security boundary for deliveries -- only a viewer that refused to render what
the same page could already download.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- `uv run pytest tests/test_rpc_transport.py tests/test_rpc_files.py tests/test_rpc_knowledge.py tests/test_rpc_console.py -q` -> 123 passed
- `uv run ruff check` and `uv run ruff format --check` on both changed files -> clean
- Both new assertions were mutation-checked, each against its own mutation:
  - narrowing the carve-out back to the workspace alone reds
    `test_the_turn_working_directory_is_exempt_from_the_state_dir_fence` only (1 failed, 3 passed)
  - dropping the containment-direction guard reds
    `test_a_working_directory_root_that_contains_the_state_root_earns_no_exemption`
    and the pre-existing state-dir test (2 failed, 2 passed)
- Against the real reporting case: the two files that were answering 403
  (`~/.raven/tmp/tui/*.md`, `*.pptx`) now resolve, while `~/.raven/config.json`
  and `~/.raven/serve.json` still raise PermissionError.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

- Widens what the file viewer will render by exactly one subtree: the directory
  turns work in. Everything the fence was written to protect (provider keys in
  `config.json`, the OAuth token store, `serve.json`) sits beside that subtree,
  not inside it, and stays refused -- pinned by the tests above.
- `fs.list` / `fs.reveal` share the function but pass the session's working
  directory as the root, which their own containment check already bounds, so
  their behaviour is unchanged.
- Rollback is a one-line revert of the exemption tuple.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-08-28 04:57:29 +00:00