## Summary
- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Passed on the rebased revision:
```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed
uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed
UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.
## Risk
Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
## Summary
Three defects a live twenty-page run surfaced, each of which cost whole pages.
`PageBox` said in its own docstring that it reads the same as `ppt_layout.Box`, and `Box`
answers to `.x` and `.y` as well as `.w` and `.h`. `PageBox` answered to two of the four.
A build helper read `round(b.y, 3)` once, in the one place it used for every page, and all
twenty pages failed to draw with `'PageBox' object has no attribute 'y'`. `Box` was given
the same pair after the same crash; the promise was the part that did not travel.
`_check_cut_out` asked its argument for `.name`, and the spelling the skill documents is
`replace_picture(shape_at(slide, n), str(FIGURES / image), fit)`. Every other branch takes
that string -- the ones that open the file hand it to PIL, which does -- so the only thing
that refused it was the warning that exists to explain a mistake. It raised
`'str' object has no attribute 'name'` over the top of the explanation and took the page
with it.
Rasterising now has a gate of its own, and it is one. `pdf()` spends its time in a
LibreOffice subprocess with a profile of its own, so width there costs nothing and buys
wall clock; `pages_of` spends its time in pypdfium2, in a worker thread of this process,
against a library that keeps state per process rather than per document. One gate for both
put them under the same number and let the second run concurrently with itself: over a
nine-template reference set, six of the nine PDFs failed to open with
`PDFium: Data format error` while every one of the nine opened when read one at a time, and
an earlier run on the same path took SIGSEGV. `pages_of` answers a failed read with an
empty dict, so the cost was a reference sheet quietly short of two thirds of its pages
rather than anything that looked like an error.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Commands run on this branch, rebased onto main:
```
uv run --frozen pytest tests/ -k ppt -q
uv run --frozen pytest tests/test_ppt_engine_template.py -q \
-k "page_box_answers or cut_out_warning_survives or rasterising_runs_one_at_a_time"
uv run --frozen ruff check plugins-dist/ppt-engine/raven_ppt/services/template/compose.py \
plugins-dist/ppt-engine/raven_ppt/stages/_views.py
```
The three added tests were each confirmed to fail without the source change. The
concurrency one asserts on how many rasterisations are in flight -- the property -- rather
than on the width of a semaphore, which is one way to get it, and its stub renderer carries
the real signatures on purpose: a stub that shapes itself to the caller agrees with a call
the engine cannot make.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Two added properties and one widened type annotation are additive. The third change
narrows rasterising to one at a time while leaving conversion as wide as it was, so a deck
whose pages are read after conversion takes slightly longer in exchange for reading all of
them; reverting the commit restores the shared gate.
## Related Issues
N/A
## Summary
Three defects a live twenty-page run surfaced, each of which cost whole pages.
`PageBox` said in its own docstring that it reads the same as `ppt_layout.Box`, and `Box`
answers to `.x` and `.y` as well as `.w` and `.h`. `PageBox` answered to two of the four.
A build helper read `round(b.y, 3)` once, in the one place it used for every page, and all
twenty pages failed to draw with `'PageBox' object has no attribute 'y'`. `Box` was given
the same pair after the same crash; the promise was the part that did not travel.
`_check_cut_out` asked its argument for `.name`, and the spelling the skill documents is
`replace_picture(shape_at(slide, n), str(FIGURES / image), fit)`. Every other branch takes
that string -- the ones that open the file hand it to PIL, which does -- so the only thing
that refused it was the warning that exists to explain a mistake. It raised
`'str' object has no attribute 'name'` over the top of the explanation and took the page
with it.
Rasterising now has a gate of its own, and it is one. `pdf()` spends its time in a
LibreOffice subprocess with a profile of its own, so width there costs nothing and buys
wall clock; `pages_of` spends its time in pypdfium2, in a worker thread of this process,
against a library that keeps state per process rather than per document. One gate for both
put them under the same number and let the second run concurrently with itself: over a
nine-template reference set, six of the nine PDFs failed to open with
`PDFium: Data format error` while every one of the nine opened when read one at a time, and
an earlier run on the same path took SIGSEGV. `pages_of` answers a failed read with an
empty dict, so the cost was a reference sheet quietly short of two thirds of its pages
rather than anything that looked like an error.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Commands run on this branch, rebased onto main:
```
uv run --frozen pytest tests/ -k ppt -q
uv run --frozen pytest tests/test_ppt_engine_template.py -q \
-k "page_box_answers or cut_out_warning_survives or rasterising_runs_one_at_a_time"
uv run --frozen ruff check plugins-dist/ppt-engine/raven_ppt/services/template/compose.py \
plugins-dist/ppt-engine/raven_ppt/stages/_views.py
```
The three added tests were each confirmed to fail without the source change. The
concurrency one asserts on how many rasterisations are in flight -- the property -- rather
than on the width of a semaphore, which is one way to get it, and its stub renderer carries
the real signatures on purpose: a stub that shapes itself to the caller agrees with a call
the engine cannot make.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Two added properties and one widened type annotation are additive. The third change
narrows rasterising to one at a time while leaving conversion as wide as it was, so a deck
whose pages are read after conversion takes slightly longer in exchange for reading all of
them; reverting the commit restores the shared gate.
## Related Issues
N/A
## Summary
`raven/sandbox/_runtime.py` read `raven.config.paths.get_sandbox_dir` to find the boxlite home, while `raven/config/schema.py` imports `raven.sandbox.config` for `SandboxConfig` -- a two-edge cycle between the two packages. An executor asking the configuration layer where its own data lives is the inverted half of that pair: it can be told instead.
`get_boxlite_runtime` now takes the home. `BoxliteExecutor` and `SandboxDebugServer` take a `sandbox_home` and pass it down. `build_executor` takes `sandbox_dir` -- the resolver, normally `get_sandbox_dir` -- and calls it only inside the boxlite branch.
The resolver rather than an already-resolved path, because resolving one creates the directory and `none` is the default backend: an eager path would leave every install a boxlite home it never uses. That laziness has a test, and the test goes red if the resolve moves above the branch.
`SandboxConfig` gains no field. Its model carries an alias generator, so a field there would become a user-writable knob in `config.json`, and a resolved runtime path is not a declaration. Five production call sites pass the resolver, all in packages that already import `raven.config`, so no new edge appears.
Measured on `origin/main` in the same environment, before -> after: packages in cycles 18 -> 17, mutual pairs 13 -> 12 (`config <-> sandbox` is gone), modules in cycles 42 -> 42. The ratchet ceilings in `tests/test_import_cycle_budget.py` are deliberately left where they are.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_sandbox_unit.py tests/test_sandbox_debug_server.py tests/test_agent_loop_workdir.py tests/test_cli_sandbox_commands.py tests/test_playbook_mcp.py tests/test_subagent_manager.py tests/test_import_cycle_budget.py -q` -> 336 passed
- `uv run lint-imports` -> 9 kept, 0 broken
- `uv run ruff check raven/ tests/` -> All checks passed
- `uv run ruff format --check` on the touched files -> already formatted
- `make check-source-language` -> exit 0
- The laziness guard was mutation-checked: moving `sandbox_dir("boxlite")` above the backend branch turns `test_the_sandbox_home_stays_unresolved_for_a_backend_that_has_none` red; reverting turns it green
- The integration suites under `tests/integration/` are updated to pass the real `get_sandbox_dir("boxlite")`, but were not executed here (they need a real VM)
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No behaviour change on the boxlite path: the same directory reaches the same runtime, and the memo cache is still keyed on it. On the `none` path the directory is no longer created, which is the intended difference. Any caller that constructs an executor without the new argument fails at call time with a `TypeError`, not silently. Rollback is a revert of the single commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Reported as "deliver_files is broken". It is not: **the tool never ran.**
Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:
```
Error: Invalid parameters for tool 'deliver_files': files should be array
```
What the model sent was the array, spelled as a string:
```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```
`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.
## Type
- [x] Fix
- [ ] Feature
## The edge of the forgiving is the design
When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.
**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.
**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.
## Not just deliver_files
Six built-in tools declare an array or object parameter and were all exposed:
| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |
The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.
## Verification
```
make lint-python ruff check + ruff format --check, 1850 files
make lint-imports 9 contracts kept, 0 broken
pytest tests/ 19,699 passed, 7 failed (all pre-existing, see below)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string
**End to end, through the real tool**, with the exact payload that failed five times in production:
```
files sent as: str -> [{"path": ".../poster.png", "title": "..."}]
returned: Delivered 1 file(s): poster.png (72 B).
still "should be array": False
registered in the store: True
```
Twelve cases, five mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |
The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.
**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.
## Risk
- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.
- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.
Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).
## Deliberately not fixed
The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.
## Moved from !594
Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.
Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
## Summary
Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:
- Navigation: every screen opens with a help area under its title (page
purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
sentinel can never reach a conversion or the data layer; a cancelled
report keeps its pre-confirm bundle-and-pin side effects (the existing
declined-report contract). Back/Exit menu entries are gone; answered
prompts erase themselves and navigation is echoed as breadcrumb lines
with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
drops as a whole column when it no longer fits, and below the dynamic
minimum width the tightest layout is kept while the renderer clips
overlong lines at the terminal edge. Every dynamic cell passes a
single-line sanitization gate before width math (verdict sidecars only
guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
passes the terminal's CPR reply through to the renderer instead of
treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
(advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
laggy Esc feel.
The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The interactive browser's look and key protocol change wholesale (that
is
the point of this PR): Esc no longer quits from the top level (Ctrl+C
does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
interaction wholesale, no data migration involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
Reported from real use, with a screenshot: an open spawn card's stream box could not be scrolled back up, and the page behind it would not move either. It reads as the surface freezing.
The box is `overscroll-behavior: contain`:
```css
.dlgchat { max-height: 340px; overflow-y: auto; overscroll-behavior: contain; }
```
That is right at its **bottom** edge -- reading a stream to its end should not then carry the whole conversation past the card. At the **top** edge it has nothing to hold back and takes something away. The box is a third of the window tall and the full width of the column, so a reader's cursor is very likely inside it; once the box itself is at the top, every further wheel-up is swallowed and the page stays where it is.
## What I tried first, and why neither works
Both were measured in a real Chromium against a minimal page with the same two boxes, one `contain` and one `auto`.
**Dropping `contain`.** It protects something real: with `auto`, one continuous gesture that scrolls past the box's end dragged the page 840px. That is the annoyance the property was added for.
**Toggling the property from a handler** (on `scroll`, and on `wheel` by direction). Both released the top -- and both leaked 600px downwards. The browser reads `overscroll-behavior` when the gesture *starts*, so a value written mid-gesture applies to the next one, by which time the reader has already watched the page refuse to move. CSS has no directional form of this.
So the containment stays, and the upward remainder is handed to the page by hand.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Measured in a real browser
Same probe, all three states, with the cursor re-centred on the box before each phase -- an earlier run of this probe reported a false leak because the page had scrolled the box out from under the pointer:
```
A box still has room, wheel up box 560 -> 440 page 1021 -> 1021 page still
B box at its top, wheel up box 0 page 1021 -> 781 page follows
C wheel down past the box's end box 0 -> 560 page 781 -> 781 page not dragged
```
B is the bug. C is what `contain` is for, and it still holds.
## The ancestor walk, and the guard that turned out to be load-bearing
The page scroller is walked for rather than named, so the same card works wherever it is mounted. The walk skips an ancestor whose content already fits, and that is not a formality -- run against the live page, the chain from the box is:
```
.bd overflow-y: auto scrollHeight 94 clientHeight 94 skipped
.dtl.dlg hidden
.wkin .wk .step.in .tfb .tfold visible
#stage.col visible
#scroll overflow-y: auto scrollHeight 1980 clientHeight 846 taken
```
`.bd` sits directly between the box and `#scroll` and is a scroller that cannot scroll. Without the `scrollHeight > clientHeight` test the gesture would be forwarded into it, which swallows it in a new place.
## The wheel is read in the unit it was reported in
Review caught that the first revision assigned `deltaY` straight onto `scrollTop`. Only `deltaMode` 0 is pixels: a mouse reporting lines sends about `-3` for one notch and a page-mode device sends `-1`, so the page would have crept a few pixels while the box went on consuming the gesture -- the same freeze this change is for, with a smaller number.
`pixelDelta` normalises first, on the convention `PlaybooksPage.tsx:630` already uses: a line is 16px (exported as `WHEEL_LINE_PX`, so two readings of one device cannot drift), a page is the **scroller's own** visible height -- a page means a page of the thing being scrolled -- and a scroller reporting no height falls back to a line rather than multiplying by zero, which would report a move and make none.
The line and page arithmetic is covered by unit cases, not by a real device: Playwright's `mouse.wheel` emits pixel mode only, so a line-mode gesture could not be driven through a real browser. What was measured there is the containment behaviour itself, above.
## Verification
```
make test-ui 96 files, 1422 tests passed
make lint-ui gen:check 162 methods, type-check
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed -- no docs surface; the measurements above are the record
Ten cases on the rule and one on the wiring. Nine mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the direction test | 2 |
| drop the at-the-top test | 2 |
| drop `scrollHeight > clientHeight` | 1 |
| stop the walk at the immediate parent | 3 |
| line mode treated as pixels | 2 |
| page mode treated as pixels | 2 |
| drop the zero-height fallback | 1 |
| stop passing `deltaMode` from the component | 1 |
| remove `onWheel` from the card | 1 |
Geometry is fabricated in the unit cases rather than laid out: happy-dom lays nothing out, so `scrollHeight` and `clientHeight` are both 0 there and every ancestor would look unscrollable -- the walk would find nothing and the cases would pass having forwarded nothing. The scroll position they assert is then only ever the number the code under test wrote, which is the whole of what is being checked.
## Risk
- [x] Security impact considered -- no new data, no network or storage surface; the change is which element a wheel gesture moves
- [x] Backward compatibility considered -- one new module and one handler on one element. The CSS is untouched, so every other nested scroller behaves exactly as before, and a page with nothing to scroll finds no target and does nothing
- [x] Rollback path is clear for risky changes -- single-commit revert; the box returns to swallowing the gesture
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over the branch diff.
- **1 (a write location moved)** -- nothing moved; a gesture that reached no scroller now reaches one.
- **2 (a value with several entry points)** -- `#scroll`'s `scrollTop` also has `tail.ts` as a writer, which follows the tail while `stuck`. A reader scrolling up clears `stuck`, so the two cannot fight: by the time this forwards anything the follow is already off.
- **3d (several lanes through one sink)** -- one handler on one element; the decision is a pure function with its own cases.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
- **9 (error handling)** -- the two ways out are both silent and both correct: no scrollable ancestor, and a wheel the box can still answer. Neither is an error and neither throws.
- **11** -- `npm ci` in `ui-web`; this worktree was fresh.
Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
## Summary
Reported from real use, with a screenshot: an open spawn card's stream box could not be scrolled back up, and the page behind it would not move either. It reads as the surface freezing.
The box is `overscroll-behavior: contain`:
```css
.dlgchat { max-height: 340px; overflow-y: auto; overscroll-behavior: contain; }
```
That is right at its **bottom** edge -- reading a stream to its end should not then carry the whole conversation past the card. At the **top** edge it has nothing to hold back and takes something away. The box is a third of the window tall and the full width of the column, so a reader's cursor is very likely inside it; once the box itself is at the top, every further wheel-up is swallowed and the page stays where it is.
## What I tried first, and why neither works
Both were measured in a real Chromium against a minimal page with the same two boxes, one `contain` and one `auto`.
**Dropping `contain`.** It protects something real: with `auto`, one continuous gesture that scrolls past the box's end dragged the page 840px. That is the annoyance the property was added for.
**Toggling the property from a handler** (on `scroll`, and on `wheel` by direction). Both released the top -- and both leaked 600px downwards. The browser reads `overscroll-behavior` when the gesture *starts*, so a value written mid-gesture applies to the next one, by which time the reader has already watched the page refuse to move. CSS has no directional form of this.
So the containment stays, and the upward remainder is handed to the page by hand.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Measured in a real browser
Same probe, all three states, with the cursor re-centred on the box before each phase -- an earlier run of this probe reported a false leak because the page had scrolled the box out from under the pointer:
```
A box still has room, wheel up box 560 -> 440 page 1021 -> 1021 page still
B box at its top, wheel up box 0 page 1021 -> 781 page follows
C wheel down past the box's end box 0 -> 560 page 781 -> 781 page not dragged
```
B is the bug. C is what `contain` is for, and it still holds.
## The ancestor walk, and the guard that turned out to be load-bearing
The page scroller is walked for rather than named, so the same card works wherever it is mounted. The walk skips an ancestor whose content already fits, and that is not a formality -- run against the live page, the chain from the box is:
```
.bd overflow-y: auto scrollHeight 94 clientHeight 94 skipped
.dtl.dlg hidden
.wkin .wk .step.in .tfb .tfold visible
#stage.col visible
#scroll overflow-y: auto scrollHeight 1980 clientHeight 846 taken
```
`.bd` sits directly between the box and `#scroll` and is a scroller that cannot scroll. Without the `scrollHeight > clientHeight` test the gesture would be forwarded into it, which swallows it in a new place.
## The wheel is read in the unit it was reported in
Review caught that the first revision assigned `deltaY` straight onto `scrollTop`. Only `deltaMode` 0 is pixels: a mouse reporting lines sends about `-3` for one notch and a page-mode device sends `-1`, so the page would have crept a few pixels while the box went on consuming the gesture -- the same freeze this change is for, with a smaller number.
`pixelDelta` normalises first, on the convention `PlaybooksPage.tsx:630` already uses: a line is 16px (exported as `WHEEL_LINE_PX`, so two readings of one device cannot drift), a page is the **scroller's own** visible height -- a page means a page of the thing being scrolled -- and a scroller reporting no height falls back to a line rather than multiplying by zero, which would report a move and make none.
The line and page arithmetic is covered by unit cases, not by a real device: Playwright's `mouse.wheel` emits pixel mode only, so a line-mode gesture could not be driven through a real browser. What was measured there is the containment behaviour itself, above.
## Verification
```
make test-ui 96 files, 1422 tests passed
make lint-ui gen:check 162 methods, type-check
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed -- no docs surface; the measurements above are the record
Ten cases on the rule and one on the wiring. Nine mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the direction test | 2 |
| drop the at-the-top test | 2 |
| drop `scrollHeight > clientHeight` | 1 |
| stop the walk at the immediate parent | 3 |
| line mode treated as pixels | 2 |
| page mode treated as pixels | 2 |
| drop the zero-height fallback | 1 |
| stop passing `deltaMode` from the component | 1 |
| remove `onWheel` from the card | 1 |
Geometry is fabricated in the unit cases rather than laid out: happy-dom lays nothing out, so `scrollHeight` and `clientHeight` are both 0 there and every ancestor would look unscrollable -- the walk would find nothing and the cases would pass having forwarded nothing. The scroll position they assert is then only ever the number the code under test wrote, which is the whole of what is being checked.
## Risk
- [x] Security impact considered -- no new data, no network or storage surface; the change is which element a wheel gesture moves
- [x] Backward compatibility considered -- one new module and one handler on one element. The CSS is untouched, so every other nested scroller behaves exactly as before, and a page with nothing to scroll finds no target and does nothing
- [x] Rollback path is clear for risky changes -- single-commit revert; the box returns to swallowing the gesture
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over the branch diff.
- **1 (a write location moved)** -- nothing moved; a gesture that reached no scroller now reaches one.
- **2 (a value with several entry points)** -- `#scroll`'s `scrollTop` also has `tail.ts` as a writer, which follows the tail while `stuck`. A reader scrolling up clears `stuck`, so the two cannot fight: by the time this forwards anything the follow is already off.
- **3d (several lanes through one sink)** -- one handler on one element; the decision is a pure function with its own cases.
- **4** -- failing test IDs diffed against the base, not counts: 0 introduced.
- **9 (error handling)** -- the two ways out are both silent and both correct: no scrollable ancestor, and a wheel the box can still answer. Neither is an error and neither throws.
- **11** -- `npm ci` in `ui-web`; this worktree was fresh.
Not applicable: 3, 3b, 3c, 3e, 4b-4d, 5, 5b, 6, 6b, 6c, 7, 7b, 8, 10.
## Summary
Land the permission-mode design: a permission gate the tool registry consults before dispatching any tool call, replacing the lexical blacklist inside ExecTool and its abort-the-whole-turn refusals.
Decision waterfall, per call: the builtin unconditional deny list (catastrophe-class commands only), then the user's deny/allow tiers and exec prefix rules from the new `permissions` config node, then the permission mode's reading of the ask tier: `ask` prompts for everything, `smart` has an LLM reviewer allow or escalate (fail-closed; the reviewer's verdict and the final decision are audited as attributes on the call's own tool.call trace span, alongside every other terminal decision -- no permission-only audit file), `full` runs it without prompting while the deny list and user deny rules still hold. The default mode is `ask`.
One ruling language, on purpose. Three specials that punched holes in each other were folded into the tiers during review (the later commits in this MR; the earlier design had them):
- A command family a surface declares (none by default; the ACP editor declares deletion and six external-effect families) does not decide anything. It names the prompt -- the human reads "push to a remote" rather than the bare command -- and is recorded on the call's tool.call span as `permission.family` whichever way the tiers decide; the call answers to the tiers and the mode like any other mutation, so a user allow rule lifts it and full mode runs it.
- A sub-agent's gate reads the turn's mode and asks through the responder the parent turn bound (the permission turn is a ContextVar its task inherits), instead of being pinned to full with asking disabled. The user authorized the spawn, not every command composed afterwards: a delegated `git push` reaches the human exactly as a direct one does, and an unattended parent (cron, one-shot) leaves it unattended.
- `tools.exec.allowDestructiveCommands` is retired. It lifted a blanket recursive-delete refusal that no longer exists (an ordinary `rm -rf build/` is ask-tier daily work; only a root or home tree is catastrophe-class). The key is still accepted and ignored, with a startup notice naming the tiers; the settings toggle, the live reader, the launcher inheritance and the settings-whitelist entry are removed.
A conversation can run in its own mode. `permissions.mode` in config is the default every conversation starts on; `config.set` with a `session_id` (same scope rule as a model switch, one shared helper) gives one conversation its own, kept the way its model is kept (in memory and on the conversation's record, so a restart does not undo it), and the gate reads the conversation's own mode first on every tool call, sub-agent tasks included. Bidirectional: the person at the keyboard can tighten or loosen either. Surfaces: `/perm X` in the TUI changes this conversation, `/perm default X` the default; on the web the composer chip changes the open conversation (a pick made in a draft is staged and applied to the session the first message mints, like the model and tier chips) and the settings panel gains the default-mode picker.
Other key decisions:
- Refusals continue the turn: every deny path returns a reasoned tool error with `continuation=CONTINUE`; the one path that ends a turn is the deny-and-stop approval choice. Parallel siblings of a blocked call still never execute. A command the policy cannot parse is refused with instructions to fix it (close the quote, or write the script to a file) rather than to give up.
- The gate is a built-in registry step ahead of the plugin tool gates: platform authority precedes plugin policy, and the gate can wait on a human and answer with a full ToolResult, which the plugin paper deliberately cannot.
- Approval outcomes carry choice (`allow`/`deny`/`deny_stop`) plus optional feedback the human types, relayed verbatim to the model. Both frontends grow the third key and the note field, localized. A channel user answers approvals through the same ask round-trip that already carries questions (`ApprovalViaAsk`); cron/sentinel/one-shot turns stay unattended and the ask tier refuses with a reason there.
- A command bound for a registered machine (the target's new exec `machine` lane) names that machine on its approval prompt -- `rm -rf /data (on prod-gpu-1)` -- and in the per-turn dedup key, so a refusal here does not pre-refuse the same text elsewhere; the gate's rulings themselves apply on every machine alike. The background lane is ruled on at the registry door like any other call and cannot be a way around a refusal.
- ShellCommandPolicy stays in place (classification, wrapper stripping, surface family registration) and is consumed by the gate; ExecTool keeps only its own integrity boundary (allowlist, workspace fence) and execution.
- Contracts: `contracts/permissions.py` is a new contract paper (ledger re-pinned across the review rounds, CONTRACTS_VERSION 5 -> 9); `SupportsApprovalTurn` is removed with its last consumer. `rpc-schema/openrpc.json` gains `config.get.session_id`; both generated clients are regenerated.
- Sandboxing earns no relaxation anywhere in the permission path: Boxlite mounts the real workspace read-write, so the deny list and the catastrophic-delete checks apply to sandboxed and direct execution alike.
- The target's config hot-reload for `tools.exec.extra_deny_patterns` is preserved and enforced at the gate: `BuiltinRulings` re-reads the live source before each ruling, a non-compiling pattern rejects the edit and keeps the current policy.
Deliberate v1 cuts, called out for review: the smart-mode reviewer sees only the tool request itself (no conversation tail); gate refusals always set `blocks_call=True` except the parse-error refusal, which the model keeps to fix. Approval frames carry the real per-call `tool_call_id`.
Out of scope, stated in CONTEXT.md: ACP-dispatched external agents (auto-approved by `acp_client/permissions.py`) and vendored out-of-process sub-agents are not covered by the gate. The channel approval transport keys late replies by conversation only; the expired-approval-then-second-approval overlap is recorded as a QuestionBroker follow-up.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
- `uv run --all-extras pytest tests/ -q` on the final tree (rebased onto main): 19424 passed, 144 skipped, 0 failed.
- `make lint`: all stages green (python, ui, tui, bridge, vendored checks).
- TUI `npx vitest run`: 2023 passed, 0 failed. Web `npx vitest run`: 1378 passed, 0 failed. `tsc --noEmit` clean on both.
- Reverse verification: with the continuation flip removed, `test_denied_delete_continues_the_turn` fails on the claimed symptom (the turn ends with the canned abort reply); restored and green. The TUI localization change was mutation-verified (keys pointed at a missing id -> red, restored -> green).
- Manual acceptance against `raven serve` with a real model (isolated RAVEN_HOME; TUI through tmux, web through Playwright), reconciled on three layers (UI rendering, server config.json, audit spans): ask prompts / allow-once / deny-with-feedback / deny-and-stop / same-turn dedupe / unconditional deny / full / smart reviewer states, on both surfaces. Two defects found there are fixed in this MR (`/perm` always reported ask: wrong `config.get` shape; approval prompt not localized).
- The delegated-approval path passed a manual pass of its own, which found and fixed a real defect: a sub-agent's first command is often asked AFTER the parent turn has ended, and the end-of-turn overlay reset wiped that prompt off the TUI with nobody having answered, so the call died at the runtime's 35s ceiling and the sub-agent reported a refusal for a prompt the user never saw. Measured both ways on a live gateway: before, the span was deny/approval at exactly 35.0s with no TUI response; after, the prompt stays up past the turn's end and the span is allow/approval/allow at 13.3s with the file written.
- The per-conversation mode passed the same manual pass (TUI and web, 13 steps): a conversation switched to full ran a write with while the default moved to smart underneath it and a new conversation followed the default; after a gateway restart the same conversation still ran at (had the record not been read back, smart would have sent the call to the reviewer); a mode picked on the web draft page landed on the session its first message minted (record metadata, prompt shown, ), and the settings panel moved only the default.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible behavior changes: the default mode is `ask`, so mutating tools (write/edit/exec and unknown MCP tools) prompt on interactive surfaces and are refused with a reason on unattended ones; previously they ran freely. Policy refusals no longer end the turn. Cron/sentinel turns lose mutating tools under the default mode until the user picks `smart` or `full`.
Changes to positions the earlier rounds of this MR had documented: on the ACP surface, full mode now runs a delete or a push it used to refuse, and a user allow rule can lift a declared family; a sub-agent in ask mode now prompts the human through the parent turn where it used to run silently; `tools.exec.allowDestructiveCommands` is read but ignored (startup notice). A conversation's own mode is stored on its session record, like its model, and survives a restart.
Rollback: set `permissions.mode` to `full`, which reproduces the old no-prompt behavior except that catastrophe-class commands are refused rather than run.
## Related Issues
N/A
## Summary
A read-only audit of all 298 test files found the suite in good shape --
exactly one genuinely fake test -- with the real debt sitting in file
names and a scattering of assertions that passed for the wrong reason.
This clears that, and fixes the bugs found while clearing it.
**Three dead tests dealt with.** Two removed because neither could ever
assert anything:
- `test_chat_e2e.py` was a module-level skip over three
`NotImplementedError` stubs. The wire-up it waited for has shipped
(`tui_commands` instantiates `SubscriptionEmitter`) and the proposal doc
it cited is gone.
- `test_tui_exit_e2e.py` asserted that building the agent loop leaves
lancedb's thread live. It does not: the loop is constructed but never
started, and the memory plugin talks to everos over HTTP, so lancedb is
not even imported. The assertion could not hold in any configuration.
The third, `slashParity.test.ts`, shelled out to python for a
`raven_cli.commands.COMMAND_REGISTRY` that no longer exists, and skipped
all three of its cases when the import failed -- three skips on every
run. The parity it wanted needs no python: `createSlashHandler.ts:45-51`
routes a slash locally when `findSlashCommand` resolves it and otherwise
hands it to `slash.exec`, a CLI subprocess a mutation cannot reach the
live session from. It now asserts that predicate directly.
`NATIVE_MUTATING_COMMANDS` and the three-way `classifyRoute` went with
it: all six names in that set are also in the local registry, so the
native branch could not change any outcome.
**19 files renamed** off phase, ticket and bug codes (AGENTS.md section
5.1), including one reversed CLI name and two integration files moved
onto a legal `<kind>`. Reference updates ride along:
`.pre-commit-config.yaml` names one of these files in a
`detect-private-key` exclude, and three docs pages point at them.
**Assertions that passed for the wrong reason, tightened**: eight
over-broad `pytest.raises(Exception)` narrowed to the type each site
actually raises; an `except` clause that swallowed the `AssertionError`
its own fakes use as a tripwire; a `hasattr` probe replaced by binding a
broker and checking it stuck; and a recall assertion that read as a pass
on an empty result set.
**Dead weight removed**: ten unused locals, three dead code blocks, six
`importorskip` guards on hard dependencies, two hardcoded `/tmp` paths,
and ticket codes left in docstrings after the renames.
**Two coverage gaps the deletions exposed are now closed**:
- `tests/test_cli_exit.py` pins the hard-exit guard, which had no tests
at all.
- The TUI chat e2e gains a multi-turn case. It reads the persisted
session rather than the screen, because a prompt is echoed into the
transcript the moment it is typed -- screen-scraping for a planted word
passes even when history is broken.
**Three timing bugs fixed in the TUI e2e tests.** They keyed off the
banner, which paints about seven seconds before the app accepts input,
and submitted the moment text was typed. Dropped prompts made the
pipeline look dead in one test, and made a negative assertion (`assert
not leak_detected`) pass vacuously in another -- no prompt means no
streaming means no leak.
**Gaps in the two features that landed during review**, small enough to
close here: the `session.py` wiring that fills `update_available` /
`update_command` (removing it left the suite green),
`_upgrade_command_works` (a fixture stubbed it to `True` everywhere), an
`episodeSummary` case with an empty test body, and `clipToWidth` /
`hasMeaningfulReasoning`, which had no coverage at all. The larger items
from that audit are tracked in #229.
**Upstream review attributions dropped from ui-tui comments.** 36
mentions of another project's review thread (#19835 as "Copilot round-N
review"), plus #18994, #19194 and #14045 -- none resolve to anything
here, and AGENTS.md section 1.1 rules out comments pointing at
information only visible elsewhere. The rationale each carried is kept;
four `describe()` titles lose a trailing `(#18994)`. Three went further
and documented a python counterpart that does not exist: `platform.ts`
credited key-spelling normalization to `raven_cli/voice.py` (no such
module -- `raven/tui_rpc/methods/_stubs.py` answers `voice.toggle` with
"voice not supported in Raven v0.1"), and `useConfigSync.ts` plus its
test credited an `interrupt` default to `raven_cli/config.py` and
`tui_gateway/server.py::_load_busy_input_mode` (`busy_input_mode`
appears nowhere in python; neither module exists).
**One flaky test fixed, caught by this PR's own CI run.**
`test_stdio_no_executor_does_not_raise` set `command="true"` and let
`connect_mcp_servers` really spawn it, so the result depended on how a
live child process raced the MCP handshake -- it failed once on CI in
the full-suite run while passing 30 out of 30 standalone runs locally.
It also asserted only that whatever came back was not a
`SandboxInitError`. The transport now raises instead of running (the
idiom its sibling test already uses) and the test asserts the stdio
branch was reached.
Review follow-ups, folded in: the hard-exit test now skips rather than
asserting no lancedb thread exists process-wide, `tests/conftest.py` no
longer credits the pytest segfault to a lancedb thread the suite never
starts (raven imports lancedb nowhere), and the status-bar patterns the
two TUI e2e tests wait on live in one module instead of a hand-mirrored
copy per file.
Every new or changed assertion was checked by mutating the code under
test and confirming the assertion fails.
## Type
- [x] Others
Test files, test configuration, and comments. The only non-test files
touched are ui-tui comments and four `describe()` titles -- no behaviour
change.
## Verification
```
uv run --all-extras pytest -q
# 4654 passed, 25 deselected
cd ui-tui && npx vitest run
# 936 passed, no skips
uv run --all-extras pytest tests/tui/autotest -m e2e -q
# passes locally with tui-use installed and ui-tui built
bash .claude/scripts/preflight_ci.sh
# ALL PREFLIGHT CHECKS PASSED (including the TUI lane)
```
Mutation checks, each confirming the new assertion fails when the code
under test is broken: the `session.py` nudge wiring removed;
`clipToWidth` replaced with identity; `hasMeaningfulReasoning` forced to
`true`; a never-sent prompt added to the multi-turn session assertion.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
No behaviour changes: the non-test diff is comments only. The renames
touch git history for 19 test files; #208 is the only open PR affected
and has been notified.
Two known items are deliberately left alone: `test_dogfood_whitelist.py`
is flaky when the whole file runs (tracked in #228, unchanged here), and
the `lancedb_finalization_hazard` gate in `commands.py` never fires
today -- its test docstring says so explicitly, so the coverage does not
read as an argument for keeping it.
## Related Issues
Closes#223
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>