## Summary
A background `exec` launch (`run_in_background=True`) returned as soon
as `Popen` did and always told the model the command was running. A
command that fails at once - a port already bound, a missing binary -
was handed back as a live task. In session 692e5c (2026-09-22) `python
-m http.server 8765` lost the port and exited, and the agent went on
debugging its client against a server that never bound.
- `start_note` now waits up to 0.9s (`_CONFIRM_S`) for the process to
contradict the launch. A command that ended in that window gets an
"ended immediately" note with its exit code (or the signal that killed
it) and the last 2000 bytes of its log, and is named as not running and
not reaped later. A command still alive after the window gets the
existing running note, which claims no more than the window shows.
- The wait runs in a worker thread (`asyncio.to_thread` in
`ExecTool.execute`), so a launch that keeps running does not stall the
event loop, and every other turn in the gateway with it, for that
second.
- The note carries the exit verdict: `start_note` returns a `ToolOutput`
with `ok=False` for a nonzero exit seen in the window, so the registry,
the tool event and every success-sensitive consumer record the call as
failed, as the synchronous lane does. An exit 0 inside the window and a
task still running stay `ok=True`.
- The env-hygiene test now reads the child's output from the launch
note, since an `env` that finishes inside the window is reported as
ended with its log attached.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Head e6183de67, rebased on origin/main 8ee5ae0d8; `git range-diff` shows
both commits replayed unchanged, and `tests/test_shell_background.py`
reran at this head: 23 passed. The other numbers below are from
ea9d6c209 on afdc04f89.
```
uv run --frozen --python 3.12 --all-extras pytest -q tests/test_shell_background.py tests/test_tool_registry*.py tests/test_shell*.py
615 passed
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q -p no:cacheprovider
25910 passed, 109 skipped, 1 failed: tests/test_rpc_files.py::test_a_host_without_libreoffice_says_so
(local only and pre-existing: it fails the same way on origin/main afdc04f89 on this machine, which has
LibreOffice installed; this branch does not touch rpc/files)
uv run --frozen --python 3.12 --extra dev ruff check raven tests -> All checks passed
uv run --frozen --python 3.12 --extra dev ruff format --check raven/agent/tools tests/test_shell_background.py -> already formatted
make lint-types -> exit 0
git diff --check origin/main...HEAD -> clean
PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD -> exit 0
make check-commits; make check-pr-title; COMMIT_RANGE=origin/main...HEAD make check-large-files -> exit 0
git merge-tree --write-tree HEAD origin/main -> clean
```
Revert-to-red, run with `tests/test_shell_background.py`:
- `start_note` reverted to the unconditional running note: 7 failed (the
six ended-note tests plus the env-hygiene test).
- `ExecTool` calling `start_note` on the loop thread instead of
`asyncio.to_thread`: 1 failed,
`test_the_launch_check_waits_off_the_event_loop` (it measures the
largest gap between 50 ms ticks of a concurrent task, about 0.9s when
blocked).
- `start_note` returning the ended note without `ok=`: 1 failed,
`test_the_registry_reads_an_early_exit_as_the_call_s_verdict[exit
7-True]` (it goes through `ToolRegistry.execute` and `call_failed`).
Not run: `make coverage-diff`, and the integration suite (`-m
integration`); this change does not touch an integration path.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no doc
describes the launch note)
## Risk
- Every successful background launch now returns about 0.9s later than
before; the turn still does not wait for the command itself.
- A command that legitimately finishes within 0.9s (for example `echo`)
is now reported as ended, with its output, instead of as a background
task to poll. That is the accurate answer, and nothing is left to reap.
- Rollback: revert the commit; no state or config format changes.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
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
The three DAG control tools -- `cancel_dag`, `dag_status`, `resolve_dag_node` -- are
withheld from the provider schema on purpose, so the per-turn tool list carries nothing a
conversation that never starts a graph has any use for. The consequence is that the only
thing a model ever reads about them is another tool's result text, and that text retold
their arguments by hand in three separate places. The retellings had drifted: the
exception report spelled `decision`, the foreground report named no arguments at all, and
the orchestration guide gave a third wording. A model working from a JSON example in prose
rather than from a declared field reached for `action` instead of `decision` three runs in
a row and lost a call each time.
Each advertisement now carries the tool's own definition, generated from the registry, in
the same shape a visible tool gets. Three decisions worth naming:
- `ToolRegistry.hidden_definition` follows the same snapshot-or-live rule `get_definitions`
already uses, and refuses a tool that is *not* hidden -- a visible tool is already in the
array, so re-advertising it is the duplication this exists to end, and that is now
structurally impossible rather than a convention.
- `resolve_dag_node` authors `to_schema` to declare its shape dynamic. Its node schema
carries a `subagent` enum built from the hot-appliable agent table, so the snapshot taken
at wiring time would advertise the roster as it stood when the loop was built.
- The replan field's node shape is referenced, not inlined. `run_subagent_dag` is not
schema-hidden, so pointing at that shape costs 455 tokens where inlining it cost 1251.
The pointer names both routes rather than asserting residency: the tool list, or
`tool_search` for the graph tool when the list does not carry it, because
`DEFAULT_ALWAYS_VISIBLE` deliberately omits `run_subagent_dag` and above the compaction
threshold it is cataloged rather than offered. It travels in `description` rather than
`$comment`, which JSON Schema defines as a note to developers that implementations must
not present -- a normalizing provider would be entitled to drop it and leave the field
an empty object. A test pins both the route and the key.
The orchestration guide keeps what the three decisions mean and drops how to spell them, so
the field names now live only where they are generated. That guide's body reaches the model
only when it calls `read_skill`, while the report always arrives, so the authoritative copy
moved from the on-demand surface to the unconditional one.
The three tools remain absent from the provider schema. Nothing about the per-turn tool
list changes, and a conversation that never starts a graph pays nothing.
Deliberately not changed, having been considered:
- The two one-field tools are advertised in full even though the prose above them already
spells their only argument, which makes their 211 tokens largely redundant. Left for a
follow-up rather than special-cased here.
- The exception report keeps its two hand-written invocations beside the generated schema.
The foreground path wrapped that report and appended the definition a second time; it no
longer does, and a test pins the count at one.
They carry the concrete run and node ids and the judgement about when replanning is the
right answer, which a schema cannot express. A test reads the field names back out of
those invocations and requires each to be one the tool still declares, so the two halves
cannot drift apart silently.
- The CLI playbook path builds a graph tool without a renderer, matching its existing
omission of the reachability predicate: there is no model on that path to advertise to.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest` over the dag, registry, tool-search, wiring, subagent, playbook and skill
selection: 3282 passed, 5 skipped. The five skips are pre-existing and environmental
(they document that an effective uid overriding the write bit is answered yes).
- Six mutants, each killed by the test written for it:
`hidden_definition` returning nothing kills 3; removing the node-shape reference kills 2;
dropping the `to_schema` declaration kills 1; silencing the graph tool's accessor kills
2; stopping the report from appending the schema kills 1; flipping the node-shape
pointer to `$comment` kills 1.
- `lint-imports`: 8 contracts kept, 0 broken. The GitLab pipeline does not run this.
- `ruff check` and `ruff format --check` over every changed Python file: clean.
- `scripts/check_commit_messages.py`, `scripts/check_source_language.py` and
`scripts/check_large_files.py` over the branch range: all pass. The pipeline runs none of
these three.
- Rendered the finished text at each of the three code sites and read it as the model
receives it. That is what caught two defects the diff did not show: a missing separator
that ran a JSON object straight into the next sentence, and the `$comment` field above.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Model-facing text changes on three paths, and the orchestration guide loses its copy of the
argument shapes. A model that had learned the old prose still finds every field name, since
the generated schema names them all. No wire shape, no stored payload and no provider tool
list changes, so there is nothing for an existing client to renegotiate.
`hidden_definition` exposes only tools their owner hid from the schema, and only to the text
that already names them. It refuses everything else, so it cannot be used to read out a
schema the caller was not already entitled to call.
Rollback is a revert: the advertisement is additive text plus one new module, and the paths
that consume it degrade to their previous wording when the renderer is absent -- which is
the state a tool built without a loop is already in, and is covered by tests.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The three DAG control tools -- `cancel_dag`, `dag_status`, `resolve_dag_node` -- are
withheld from the provider schema on purpose, so the per-turn tool list carries nothing a
conversation that never starts a graph has any use for. The consequence is that the only
thing a model ever reads about them is another tool's result text, and that text retold
their arguments by hand in three separate places. The retellings had drifted: the
exception report spelled `decision`, the foreground report named no arguments at all, and
the orchestration guide gave a third wording. A model working from a JSON example in prose
rather than from a declared field reached for `action` instead of `decision` three runs in
a row and lost a call each time.
Each advertisement now carries the tool's own definition, generated from the registry, in
the same shape a visible tool gets. Three decisions worth naming:
- `ToolRegistry.hidden_definition` follows the same snapshot-or-live rule `get_definitions`
already uses, and refuses a tool that is *not* hidden -- a visible tool is already in the
array, so re-advertising it is the duplication this exists to end, and that is now
structurally impossible rather than a convention.
- `resolve_dag_node` authors `to_schema` to declare its shape dynamic. Its node schema
carries a `subagent` enum built from the hot-appliable agent table, so the snapshot taken
at wiring time would advertise the roster as it stood when the loop was built.
- The replan field's node shape is referenced, not inlined. `run_subagent_dag` is not
schema-hidden, so pointing at that shape costs 455 tokens where inlining it cost 1251.
The pointer names both routes rather than asserting residency: the tool list, or
`tool_search` for the graph tool when the list does not carry it, because
`DEFAULT_ALWAYS_VISIBLE` deliberately omits `run_subagent_dag` and above the compaction
threshold it is cataloged rather than offered. It travels in `description` rather than
`$comment`, which JSON Schema defines as a note to developers that implementations must
not present -- a normalizing provider would be entitled to drop it and leave the field
an empty object. A test pins both the route and the key.
The orchestration guide keeps what the three decisions mean and drops how to spell them, so
the field names now live only where they are generated. That guide's body reaches the model
only when it calls `read_skill`, while the report always arrives, so the authoritative copy
moved from the on-demand surface to the unconditional one.
The three tools remain absent from the provider schema. Nothing about the per-turn tool
list changes, and a conversation that never starts a graph pays nothing.
Deliberately not changed, having been considered:
- The two one-field tools are advertised in full even though the prose above them already
spells their only argument, which makes their 211 tokens largely redundant. Left for a
follow-up rather than special-cased here.
- The exception report keeps its two hand-written invocations beside the generated schema.
The foreground path wrapped that report and appended the definition a second time; it no
longer does, and a test pins the count at one.
They carry the concrete run and node ids and the judgement about when replanning is the
right answer, which a schema cannot express. A test reads the field names back out of
those invocations and requires each to be one the tool still declares, so the two halves
cannot drift apart silently.
- The CLI playbook path builds a graph tool without a renderer, matching its existing
omission of the reachability predicate: there is no model on that path to advertise to.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `pytest` over the dag, registry, tool-search, wiring, subagent, playbook and skill
selection: 3282 passed, 5 skipped. The five skips are pre-existing and environmental
(they document that an effective uid overriding the write bit is answered yes).
- Six mutants, each killed by the test written for it:
`hidden_definition` returning nothing kills 3; removing the node-shape reference kills 2;
dropping the `to_schema` declaration kills 1; silencing the graph tool's accessor kills
2; stopping the report from appending the schema kills 1; flipping the node-shape
pointer to `$comment` kills 1.
- `lint-imports`: 8 contracts kept, 0 broken. The GitLab pipeline does not run this.
- `ruff check` and `ruff format --check` over every changed Python file: clean.
- `scripts/check_commit_messages.py`, `scripts/check_source_language.py` and
`scripts/check_large_files.py` over the branch range: all pass. The pipeline runs none of
these three.
- Rendered the finished text at each of the three code sites and read it as the model
receives it. That is what caught two defects the diff did not show: a missing separator
that ran a JSON object straight into the next sentence, and the `$comment` field above.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Model-facing text changes on three paths, and the orchestration guide loses its copy of the
argument shapes. A model that had learned the old prose still finds every field name, since
the generated schema names them all. No wire shape, no stored payload and no provider tool
list changes, so there is nothing for an existing client to renegotiate.
`hidden_definition` exposes only tools their owner hid from the schema, and only to the text
that already names them. It refuses everything else, so it cannot be used to read out a
schema the caller was not already entitled to call.
Rollback is a revert: the advertisement is additive text plus one new module, and the paths
that consume it degrade to their previous wording when the renderer is absent -- which is
the state a tool built without a loop is already in, and is covered by tests.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
`exec` gains two lanes, and the on-call plugin's own exec retires onto them.
- `machine=<registered id>` runs a short look on a registered machine through the connection registry (capped at 60 s, killed on both ends; longer work is a job). Looked up through the registry's `load()`; the refusal for an unknown id lists the machines the way `shown()` renders them, no address.
- `run_in_background` runs long mechanical work on this computer under a managed log. The two lanes never combine, which closes the accounting bypass where jobs were driven over raw ssh past the ledger.
- The local machine-lane command runs in its own session and the cap kills the whole group (TERM, grace, KILL); platform-aware, with `taskkill /T /F` where `os.killpg` does not exist.
- `raven connection add` keeps an ssh alias so transfers need no address in prompts.
- `ops_exec` retires onto trunk exec; a cap kill routes by the command's shape (transfers to the background lane, jobs to `ops_submit`).
Stacked on `fix/oncall-flow-submit-and-launcher`: until that merges, this MR shows its six commits too; after it merges the diff reduces to the seven commits of this branch.
## Type
- [x] Feature
## Verification
```
uv run ruff check raven tests agents && uv run ruff format --check raven tests agents # clean
uv run pytest tests/test_shell_*.py tests/test_cli_ops_connection_commands.py tests/test_agents_oncall_flow_case_dict_tools.py tests/test_agents_oncall_flow_hooks.py tests/test_agents_oncall_flow_tools.py tests/test_agents_oncall_flow_watcher.py tests/test_agents_oncall_launcher.py tests/test_agent_loop_token_budget.py -q # 386 passed
uv run python scripts/check_commit_messages.py origin/main..HEAD # clean
```
Field check: four launcher shapes run on the GPU machine's real shell on 2026-09-03 (self-detaching command refused, non-zero rc recorded, group kill leaves nothing behind).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
`exec` accepts two new optional parameters; `ops_exec` is gone from the on-call tool set (the model-facing text no longer names it). The machine lane hands the model no address or credential. Rollback is a revert of the squash commit.
## Related Issues
Split from !476 (closed), retargeted at main. Merge after `fix/oncall-flow-submit-and-launcher`.