samagotchi 0.68.0 → 0.70.0

data/docs/plugins.md

@@ -25,6 +25,8 @@ plugin:
   file: plugin.rb
   sha256: sha256:6a1a7022…   # shasum -a 256 plugin.rb
 requires_chi: ">= 0.1.28"    # optional: a gem-style requirement (">= 0.1.28, < 0.2"); the bundle's hooks/ check it too
+# requires_chi_next: true    # shipped bundles only, ignored by chi: rake release:bump raises requires_chi
+                             # to the chi being released (docs/releasing.md)
 needs: [gh]                  # optional: outside commands it relies on (see memory.md#bundles-that-need-outside-commands)
 ```
 
@@ -294,6 +296,8 @@ is what `targets:` says:
   (chi's `call_tool`, which calls a tool a [source](#chitool_sourcecall-acts_as-label-wait-prefix) published). Rules keyed by that tool's name match the
   call too, as well as rules on the tool's own name. It can't be one of
   chi's own tools or another bundle's tool: that is dropped (and logged).
+  The "another bundle's tool" drop doesn't apply to chi's `call_tool`: its
+  `acts_as` is always a tool its sources published.
 - `args:`: the arguments it acts with (a Hash), when they aren't the call's
   own (a dispatcher's inner arguments). A call with no `command:` or
   `paths:` is asked about with them, and "allow this call" is keyed by them.
@@ -583,15 +587,32 @@ chi.toolkit "review", base: "lean", add: %w[delegate delegate_result]
 
 Tools the model reaches through a search instead of declaring them one by
 one: the plugin publishes them into chi's **tool index**, and chi declares
-two tools in all, whatever the number of sources: `find_tools` (a keyword
-search that answers each match's `inputSchema`) and `call_tool` (calls one as
-`<group>/<tool>`; its row label is the first source's `label`). They
-are declared once, after the plugins load, and only when a plugin registered
-a source: a session without one declares neither. Nothing a source publishes
-later changes the request's tools, only what a search answers, so the prompt
-cache keeps (the search tool's description lists the groups as they were at
-load). The mcp bundle is the only source so far (a group per server), and the
-texts speak of MCP servers.
+two tools in all, whatever the number of sources: `find_tools(query,
+group?)` (a keyword search that answers each match's `inputSchema`) and
+`call_tool(tool, args)` (calls one as `<group>/<tool>`; its row label is the
+first source's `label`). The index has one group of its own, **`chi`**: the
+built-ins the session's toolkit leaves out but doesn't remove
+([toolkits](configuration.md#toolkits)), each with its registered schema.
+The two tools are registered once, after the plugins load, and declared per
+toolkit: when a plugin registered a source then, or when the toolkit has a
+reachable built-in (`full` with no source declares neither). Nothing a
+source publishes later changes the request's tools, only what a search
+answers, so the prompt cache keeps: the search tool's description lists the
+source groups as they were at load, and a `chi` line first, per toolkit.
+The mcp bundle is the only source so far (a group per server). A source's
+group named `chi`, or named like an earlier group, is left out of search,
+lookup and the description, with one warning per name.
+
+**A built-in through `call_tool` runs as that built-in.** `call_tool(tool:
+"chi/delegate", args: {…})` (or a bare `delegate` while it's reachable) is
+turned into the `delegate` call itself before the guardrails, so rules on
+`delegate`, approvals (keyed `delegate:…`, the same as a direct call's),
+`before_tool_call`/`after_tool_call` hooks and the row see `delegate`, with
+`call[:via] == "call_tool"`; the row reads "delegate (via call_tool)", live
+and after a reload. `tool: call_tool` rules see MCP calls and misses only. A
+`chi/` name the toolkit removes or declares, or any built-in once
+`call_tool` itself is removed, is refused by its name before the guardrails
+(no hook, no card).
 
 ```ruby
 @source = chi.tool_source(label: "mcp", prefix: "mcp_",
@@ -621,7 +642,8 @@ index = Samagotchi::Tools::ToolIndex
   block returns (a String, a `ToolResult` with images).
 - **Guardrails** see a `call_tool` as the tool it calls: its `acts_as`, its
   arguments and `"<group>: <tool>"` as the question's label
-  ([acts_as:](#guardrails)). A call made before its tool is published is
+  ([acts_as:](#guardrails)), even when another bundle has a tool of that
+  name (only the core-tool drop applies). A call made before its tool is published is
   named by `acts_as` from the names alone; a bare name with `prefix` is
   taken as an `acts_as` as given. The `acts_as:` hook must give exactly the
   `acts_as` the source publishes for that tool: a call whose tool isn't the
@@ -632,24 +654,24 @@ index = Samagotchi::Tools::ToolIndex
   what the two tools take in every request (none when other tools had both
   names). A `Group` in a state other than the three, holding another group's
   tool, or a `Tool` with a blank `acts_as` raises `ArgumentError`.
-- `find_tools` and `call_tool` aren't chi's own tools: every toolkit declares
-  them (unless its `remove:` names them), as it does plugin tools. A bundle
-  that declares tools of those names itself (an mcp bundle before 0.7.0 has
-  `find_mcp_tools` and `mcp_call`) keeps them, and with no source chi
-  declares neither.
+- `find_tools` and `call_tool` aren't chi's own tools: a toolkit that needs
+  them declares them (unless its `remove:` names one; `call_tool` stays
+  usable with `find_tools` removed). A bundle that declares tools of other
+  names itself (an mcp bundle before 0.7.0 has `find_mcp_tools` and
+  `mcp_call`) keeps them; with no source, `full` declares neither of chi's.
 
 ### `chi.peer_source(name, label:)`
 
 Declares a context source as a peer agent's answers: the peer bundles'
-`claude-review` and `codex-review`. Such a source, when it is a pushed source
+`claude-outbox` and `codex-outbox`. Such a source, when it is a pushed source
 of the session's own, wakes the session by the peer loop's rules instead of
-the 10-minute window: up to `context.peer_turns` wake turns in a row, no wake
-for an answer whose verdict is `VERDICT OK`, and a wake line that names the
-peer and keeps the turn within the user's task (see [Waking: peer
+the 10-minute window: up to `context.peer_turns` wake turns in a row, one
+closing wake (outside that count) for an answer whose verdict is `VERDICT OK`,
+and a wake line that names the peer and keeps the turn within the user's task (see [Waking: peer
 sources](context.md#peer-sources-the-peer-loop)).
 
 ```ruby
-chi.peer_source "codex-review", label: "Codex"
+chi.peer_source "codex-outbox", label: "Codex"
 ```
 
 - `name`: a context source name (as `chi context add` takes it). Another
@@ -659,7 +681,7 @@ chi.peer_source "codex-review", label: "Codex"
 
 The declaration lives in the session's process only, like a tool: a source
 file can't make itself a peer's, and uninstalling the bundle ends it.
-Subclasses of `Samagotchi::Plugin::Peer` (below) declare their `REVIEW`
+Subclasses of `Samagotchi::Plugin::Peer` (below) declare their `OUTBOX`
 source. Needs chi 0.67.0 (guard it with `chi.respond_to?(:peer_source)`).
 
 ### `chi.ctx`
@@ -1064,7 +1086,7 @@ bundles:
 
 - **Tools: search, then call.** The servers' tools are kept in chi's tool index;
   the model has two fixed tools:
-  - `find_tools(query, server?)` searches it by keywords over the
+  - `find_tools(query, group?)` searches it by keywords over the
     server's name, the tool's name and its description, and answers up to 5
     tools, each with its name `<server>/<tool>`, its description and its
     whole `inputSchema`. A word counts more the fewer tools have it (a word
@@ -1089,7 +1111,7 @@ bundles:
     `args` are typed by the tool's
     `inputSchema` (numbers and booleans given as text, JSON text for an
     object). A name it doesn't know answers the closest ones (`Error: no
-    MCP tool chrome/open_url. Closest: chrome/new_page, …`). Its row shows
+    tool chrome/open_url. Closest: chrome/new_page, …`). Its row shows
     `mcp chrome/take_screenshot fullPage=true`.
   - A tool turn takes a few more steps than when every tool was declared
     (the P1 spike: about 1.5 more on a 30-tool server), and each request is
@@ -1159,8 +1181,9 @@ bundles:
   session" (or in this repo) allows that tool with those arguments only.
   (Approvals stored before 0.6.0, under the old name, don't carry over, nor
   ones stored before 0.7.0 under `mcp_call`: each MCP tool is asked about once more.)
-  Two things see `call_tool`, not the tool: hooks (a `before_tool_call`
-  event's `tool:` is `"call_tool"`, the tool in its args), and loop-guard's
+  Two things see `call_tool`, not the MCP tool: hooks (a `before_tool_call`
+  event's `tool:` is `"call_tool"`, the tool in its args; a built-in reached
+  through `call_tool` is the exception, it fires as that built-in), and loop-guard's
   `ignore_tools` (`call_tool` ignores every MCP call; calls to different
   tools, or with different args, stay distinct, since the tool is in the
   args).
@@ -1692,7 +1715,7 @@ Claude pairs; without one the bundle costs one tool declaration.
 - **Pairing is Claude's.** chi can't see Claude's inbox, so Claude attaches
   two pushed sources to the chi session: `claude-inbox`, whose hint is its
   per-session inbox socket (`CLAUDE_CODE_MESSAGING_SOCKET`, Claude Code
-  2.1.224 or later), and `claude-review`, where its answers come. You never
+  2.1.224 or later), and `claude-outbox`, where its answers come. You never
   run that yourself:
   1. `/claude install-skill` (once) shows a card with the target,
      `$CLAUDE_CONFIG_DIR/skills/chi-peer/SKILL.md` (else `~/.claude/…`),
@@ -1707,12 +1730,12 @@ Claude pairs; without one the bundle costs one tool declaration.
   2. In Claude Code you say "pair with chi <id or chi web URL>". The skill runs
      `sh <bundle>/scripts/pair <id or URL>`, which attaches `claude-inbox` (the
      socket as its hint, pushed as JSON so a re-pair after a Claude restart
-     refreshes it) and `claude-review`, and lists the session's context. A
+     refreshes it) and `claude-outbox`, and lists the session's context. A
      re-pair keeps Claude's last answer.
   3. Claude answers a validate or a question with a JSON push to
-     `claude-review` (`text`, `summary`, `wake: true`), which wakes chi, the
+     `claude-outbox` (`text`, `summary`, `wake: true`), which wakes chi, the
      first answer too (on chi 0.62 the first one arrives as a note without
-     waking); the model reads it with `context_read claude-review`.
+     waking); the model reads it with `context_read claude-outbox`.
 - **The tool `claude_send(kind, title, text)`**, `kind` being `validate`,
   `context` or `question`, writes one JSON line to that socket. The message
   starts with a header, `chi <id> · <kind> · <title>`. A text up to 4,000
@@ -1727,7 +1750,11 @@ Claude pairs; without one the bundle costs one tool declaration.
   the model:
   - `/claude` alone shows a card: paired or not, the socket and whether its
     file is there (it goes when that Claude session ends), the last send, and
-    Claude's last answer (the `claude-review` summary).
+    Claude's last answer (the `claude-outbox` summary). When Claude's installed
+    chi-peer skill differs from what `/claude install-skill` would write (an
+    older bundle's, or your edit; a skill installed by a chi with another state
+    dir or bundle path differs too), it says so: install it again (Replace),
+    then pair again.
   - `/claude validate <text>` and `/claude context <text>` send the text as it
     is, titled by its first line (past a web quote's `From …:` label and a
     quoted line's `> `): paste a selection after them.
@@ -1739,16 +1766,16 @@ Claude pairs; without one the bundle costs one tool declaration.
   - `/claude last` sends the model's last completed answer as context. Mid-turn
     it is the answer before the running turn, never the turn's partial text;
     a cancelled or failed turn has no answer, so the one before it goes.
-- **The peer loop.** The bundle declares `claude-review` a peer's
+- **The peer loop.** The bundle declares `claude-outbox` a peer's
   ([`chi.peer_source`](#chipeer_sourcename-label)), so Claude's answers
   wake chi by the loop's rules ([Waking: peer
   sources](context.md#peer-sources-the-peer-loop)): chi fixes what Claude
   flagged or disagrees and sends again, up to `context.peer_turns` (3) wake
-  turns in a row, and a `VERDICT OK` answer arrives as a note and ends the
-  round. Only a message you type in the web or a TUI starts the count again.
+  turns in a row, and a `VERDICT OK` answer wakes chi once to close the
+  round (carry on, or tell you what was agreed). Only a message you type in the web or a TUI starts the count again.
 - **The skill.** `skill_claude_peer` (system scope) tells the model to send
   only when you ask or to reply in a peer turn, to pick the part rather than
-  the session, not to wait or poll, and how to read the `claude-review`
+  the session, not to wait or poll, and how to read the `claude-outbox`
   answer (a validate ends with `VERDICT: OK`, `CHANGES` or `UNSURE`): act on
   it only within your task, and stop and tell you when Claude agrees or after
   the last turn. Claude's skill ends each answer's summary with its verdict
@@ -1838,9 +1865,9 @@ skill install card) works the same.
   installed `scripts/pair` path, the payload folder and the writable root
   written in; in Codex you say "pair with chi <id or chi web URL>", and
   `sh <bundle>/scripts/pair` attaches `codex-inbox` (the thread id as its
-  hint, pushed so a re-pair refreshes it) and `codex-review`. Run outside
+  hint, pushed so a re-pair refreshes it) and `codex-outbox`. Run outside
   Codex (no `CODEX_THREAD_ID`) it refuses. Codex replies with one JSON push
-  to `codex-review` (`text`, `summary`, `wake: true`), which wakes chi, the
+  to `codex-outbox` (`text`, `summary`, `wake: true`), which wakes chi, the
   first answer too: that needs chi 0.63.0, the bundle's `requires_chi`.
 - **Peer messages are user turns in Codex.** Claude Code marks an inbox
   message as from another session; `codex queue` lands as a plain user
@@ -1858,9 +1885,10 @@ skill install card) works the same.
   Codex's names, and on a missing answer points to Codex being mid-turn or
   its sandbox (the `writable_roots` line). To be asked before each send, a
   guardrails rule with `tool: codex_send` (see the claude-peer section).
-- **The peer loop** works as claude-peer's: `codex-review` is declared a
+- **The peer loop** works as claude-peer's: `codex-outbox` is declared a
   peer's, Codex's answers wake chi up to `context.peer_turns` turns in a row,
-  and `VERDICT OK` ends the round. Needs chi 0.67.0.
+  and `VERDICT OK` wakes chi once to close the round. Needs chi 0.67.0 (the closing
+  wake: the chi released with this bundle).
 
 ## Shutdown
 

data/docs/releasing.md

@@ -18,8 +18,14 @@ can run the whole release; the user approves the notes before the tag and the
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`
     (`rake bundles:check` fails otherwise, once there's a tag to compare with);
-  - a bundle that uses something new in chi raises its `requires_chi` in the
-    same change; `release:bump` never touches `requires_chi`;
+  - a bundle that uses something new in chi marks it in the same change with
+    `requires_chi_next: true` (or a short reason) in its `manifest.yml`, and
+    leaves `requires_chi` alone: raising it to a chi that isn't released yet
+    would make chi on main refuse its own bundle. `release:bump` raises a
+    marked bundle's `requires_chi` to `">= X.Y.Z"` and drops the marker;
+    `release:check` fails while a marker is left. chi itself ignores the key,
+    and `bundles:check` notes it (and fails a marker that isn't `true` or a
+    one-line string). `release:bump` touches no other `requires_chi`;
   - a new shipped bundle joins a profile (`includes:` in `core` or `dev`; a
     spec checks every bundle is in exactly one), and that profile's version
     goes up: `chi update` then installs only the new bundle for those who
@@ -49,11 +55,11 @@ as the GitHub release body.
 | Task | What it does |
 | --- | --- |
 | `rake bundles:sha` | Recomputes the sha256 lines of every shipped bundle manifest (`files:`, `hooks:`, `plugin:`). |
-| `rake bundles:check` | Sha lines match; a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: raise it if the change uses anything new. The release workflow and `release:check` run it in full. |
+| `rake bundles:check` | Sha lines match; a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: mark it `requires_chi_next` if the change uses anything new. Notes a bundle marked `requires_chi_next`. The release workflow and `release:check` run it in full. |
 | `rake 'bundles:check[ci]'` | The CI workflow's (every push and PR): the same, except the version check leaves out the system bundle, which is changed and unbumped between releases (`release:bump` moves its version with VERSION). A task argument, not `CI=1`: GitHub sets `CI` in the release workflow too. |
 | `rake release:draft_changelog` | A draft Unreleased section from the commit subjects since the last tag, grouped. Stdout only. |
-| `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG. No commit. |
-| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, `bundles:check`, `rake lint` (RuboCop), rspec + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
+| `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG, and `requires_chi: ">= X.Y.Z"` for each bundle marked `requires_chi_next` (the marker dropped). No commit. |
+| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, no `requires_chi_next` left, `bundles:check`, `rake lint` (RuboCop), rspec + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
 | `rake release:notes[X.Y.Z]` | Prints the CHANGELOG section (default: the current VERSION). |
 
 ## Runbook
@@ -68,7 +74,9 @@ The agent does each step and stops where the user has to say yes.
    the last tag (`git diff vPREV -- lib/samagotchi/bundles/*/manifest.yml`).
    Pick the version: fixes only → patch, anything else → minor.
 3. **The user approves the notes and the version.** Show them the section.
-4. **Bump.** `bundle exec rake "release:bump[X.Y.Z]"`, review `git diff`.
+4. **Bump.** `bundle exec rake "release:bump[X.Y.Z]"`, review `git diff`: it
+   names the bundles whose `requires_chi` it raised (their `requires_chi_next`
+   markers are gone).
 5. **Check.** Commit first (the check wants a clean tree), then run it:
    `git commit -am "Release X.Y.Z"` and `bundle exec rake release:check`.
    Fix anything it finds in new commits and run it again.

data/docs/sessions.md

@@ -1,6 +1,6 @@
 # Sessions
 
-Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`). Besides the messages and turn state, the JSON keeps `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
+Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
 
 **Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
 
@@ -74,9 +74,9 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 **Ordering:**
 
 - `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
-- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). A file in a tool row (a read, edit or write's title) and its diff lines are refs: hover one and click to open the current file in your editor at that line, on this machine only (`web.editor`; the browser's "always allow" for the page's port and VS Code's "allow opening local files" are asked once; see [Opening files from chi web](configuration.md#opening-files-from-chi-web)). So are an edit or write approval card's paths (at the first line the dry run changes) and its diff lines, before you approve, and the numbered lines of a read's output: `lines 40–60` under it opens the text as read, numbered, when the output is the file as-is (not the head/tail preview of a big file, an error or an image; no numbers after a cut). A `path:line` (or `path:line-line`) in an answer or a step's text is one too once the turn has ended, and after a reload, when it names a file a row or card on the page touched: the path under the session's folder, else the one touched file it ends with (a bare `app.js:12` when only one touched file is named so; two such files make it none); a path without a line counts only when it is a touched file exactly. Code blocks, links, bare URLs and inline code with more than the ref in it are left alone, and a file the session didn't touch is never linked; a link whose text is such a ref alone (github-pr's link to the PR diff) becomes a ref too, and its plain click still goes to the PR. A plugin's refs on an answer (an `after_turn` hook's, see [Refs on the answer](hooks.md#refs-on-the-answer-display-only)) are paired with its links and text whatever the rows touched: they can link a file the session didn't touch, or an issue or a commit, and add their own actions to the ref's menu. A plugin tool's row carries the refs its `refs:` gives (see [Refs on a tool's row](plugins.md#refs-on-a-tools-row)): its title opens the first, and its `▾` menu adds the others as `<ref> · <action>` (the URL on hover); their URL actions work on a phone too. A ref with more than one target shows a small `▾` on hover: it opens a menu of them, in order **PR diff** (a link's), **Open in editor**, **Show in turn** and **Copy path**, and a plain click runs the first (a link's own, else the editor, else show in turn). **Show in turn** scrolls to the tool row that touched the file (looked for in the ref's own step, then its own turn, then the rows before it, then the nearest after it; there, the last one showing the ref's line, else the last one), opens the steps, the stage's steps and the row's diff (or the read showing the line) and flashes the row and the line; an answer's or a step's ref and an approval card's path have it, not a row's own title or lines. It needs no editor, so a viewer without one (a phone on the LAN) gets an answer's refs with **Show in turn** as their click; a row's title and diff lines stay plain text there. On a touch screen a tap opens the menu. A ref with a target is a tab stop: Enter runs its first target, ↓ opens the menu (↑/↓ move, Enter picks, Esc closes back to the ref). Diff and read lines have their click only. The info bar copies `chi --attach <id>` for a terminal. A session whose prompt carried model notes has a `notes: deepseek` chip there (the names without `model_notes_`; the tooltip lists each with its scope and size; `session.prompt_notes` in `GET /api/sessions/:id`, the live worker's, else the session file's; see [Memory](memory.md#model-notes)). Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. Its `think` chip does the same for the thinking level (`/thinking`), and on a chat host its `reasoning` chip for the reasoning history (`reasoning all · session`, `/reasoning-history`; `session.reasoning_history`, null on a native host). A `/thinking` or `/reasoning-history` change that restarts the prompt cache asks first: the reply bubble has an **Apply (restarts the cache)** button that sends its `--yes` line (the chips' Set sends that line itself; see [Changes that restart the prompt cache](configuration.md#changes-that-restart-the-prompt-cache)). It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only (one estimated from a `hosts.<name>.models` price shows with `~`: `cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`), and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first (an id the host declares under `hosts.<name>.models` first, noted `config`, its tooltip `served by config (hosts.<name>.models)`; a host that failed to list its models keeps those ids, greyed and noted `host down`, still pickable; a remembered or default model stays chosen even then, greyed on the button); typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, configured?, unavailable?, sampling?, llm_context?}], warning?}`; `configured: true` marks an id declared under `hosts.<name>.models`, listed first under its host, `unavailable: true` one whose host failed to list its models; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). Beside it, an `llm ctx` chip shows the LLM context the picked model starts under (each `GET /api/models` row's `llm_context`, as the info bar's); its form sets one for the new chat only, sent as `POST /api/sessions`'s `llm_context` and never remembered (see [configuration.md](configuration.md#llm-context-a-sessions-own-strategy)). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last model picked; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). A file in a tool row (a read, edit or write's title) and its diff lines are refs: hover one and click to open the current file in your editor at that line, on this machine only (`web.editor`; the browser's "always allow" for the page's port and VS Code's "allow opening local files" are asked once; see [Opening files from chi web](configuration.md#opening-files-from-chi-web)). So are an edit or write approval card's paths (at the first line the dry run changes) and its diff lines, before you approve, and the numbered lines of a read's output: `lines 40–60` under it opens the text as read, numbered, when the output is the file as-is (not the head/tail preview of a big file, an error or an image; no numbers after a cut). A `path:line` (or `path:line-line`) in an answer or a step's text is one too once the turn has ended, and after a reload, when it names a file a row or card on the page touched: the path under the session's folder, else the one touched file it ends with (a bare `app.js:12` when only one touched file is named so; two such files make it none); a path without a line counts only when it is a touched file exactly. Code blocks, links, bare URLs and inline code with more than the ref in it are left alone, and a file the session didn't touch is never linked; a link whose text is such a ref alone (github-pr's link to the PR diff) becomes a ref too, and its plain click still goes to the PR. A plugin's refs on an answer (an `after_turn` hook's, see [Refs on the answer](hooks.md#refs-on-the-answer-display-only)) are paired with its links and text whatever the rows touched: they can link a file the session didn't touch, or an issue or a commit, and add their own actions to the ref's menu. A plugin tool's row carries the refs its `refs:` gives (see [Refs on a tool's row](plugins.md#refs-on-a-tools-row)): its title opens the first, and its `▾` menu adds the others as `<ref> · <action>` (the URL on hover); their URL actions work on a phone too. A ref with more than one target shows a small `▾` on hover: it opens a menu of them, in order **PR diff** (a link's), **Open in editor**, **Show in turn** and **Copy path**, and a plain click runs the first (a link's own, else the editor, else show in turn). **Show in turn** scrolls to the tool row that touched the file (looked for in the ref's own step, then its own turn, then the rows before it, then the nearest after it; there, the last one showing the ref's line, else the last one), opens the steps, the stage's steps and the row's diff (or the read showing the line) and flashes the row and the line; an answer's or a step's ref and an approval card's path have it, not a row's own title or lines. It needs no editor, so a viewer without one (a phone on the LAN) gets an answer's refs with **Show in turn** as their click; a row's title and diff lines stay plain text there. On a touch screen a tap opens the menu. A ref with a target is a tab stop: Enter runs its first target, ↓ opens the menu (↑/↓ move, Enter picks, Esc closes back to the ref). Diff and read lines have their click only. The info bar copies `chi --attach <id>` for a terminal. A session whose prompt carried model notes has a `notes: deepseek` chip there (the names without `model_notes_`; the tooltip lists each with its scope and size; `session.prompt_notes` in `GET /api/sessions/:id`, the live worker's, else the session file's; see [Memory](memory.md#model-notes)). Its `llm ctx` chip names the LLM context strategy the next turn runs under (`llm ctx stale,forget · session`, in the accent colour when the session set its own; the tooltip gives each value's source), and its popover sets the session's own strategy, apply rule and budget, or follows the model again, by running `/llm-context` in the worker (the reply shows as a command bubble); `GET /api/sessions/:id`'s `session.llm_context` carries the values (the live worker's, else resolved from the session file), and a `command_ran` that changed them carries the new ones. Its `think` chip does the same for the thinking level (`/thinking`), and on a chat host its `reasoning` chip for the reasoning history (`reasoning all · session`, `/reasoning-history`; `session.reasoning_history`, null on a native host). A `/thinking` or `/reasoning-history` change that restarts the prompt cache asks first: the reply bubble has an **Apply (restarts the cache)** button that sends its `--yes` line (the chips' Set sends that line itself; see [Changes that restart the prompt cache](configuration.md#changes-that-restart-the-prompt-cache)). It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only (one estimated from a `hosts.<name>.models` price shows with `~`: `cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`), and the memory indexes its prompt holds (`memory index: ~3.4k tokens in this session's prompt (system 2.0k, project 1.4k)`; see [Memory](memory.md#the-indexs-size)). The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on, and a fresh chain link's (see [Session chains](#session-chains); there a pick shows as a `/model` command bubble in the link); it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first (an id the host declares under `hosts.<name>.models` first, noted `config`, its tooltip `served by config (hosts.<name>.models)`; a host that failed to list its models keeps those ids, greyed and noted `host down`, still pickable; a remembered or default model stays chosen even then, greyed on the button); typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, configured?, unavailable?, sampling?, llm_context?}], warning?}`; `configured: true` marks an id declared under `hosts.<name>.models`, listed first under its host, `unavailable: true` one whose host failed to list its models; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). Beside it, an `llm ctx` chip shows the LLM context the picked model starts under (each `GET /api/models` row's `llm_context`, as the info bar's); its form sets one for the new chat only, sent as `POST /api/sessions`'s `llm_context` and never remembered (see [configuration.md](configuration.md#llm-context-a-sessions-own-strategy)). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last model picked; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
 - Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
-- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover; the chip and rows as lit-html templates), `keep_focus.js` (lit reuses a list's nodes by position: a redraw keeps the focus on the same item by its `data-id` / `data-name`), `chains.js` (session chains: the links from `continues`, the cards folded into the latest link's, its `day N` chip and rows as lit-html templates, the info bar's ← → links, a refused continue), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `bubbles.js` (the history's bubbles between the turns' rows: output chunks, end lines, every client's prompt bubbles by `enqueued_id` with their queued/steered badges, the idle recap, guardrail warnings, hooks' notices, plugins' steers, command and note bubbles; lit-html templates, put in the history with the sticky follow by `createBubbles`), `cards_place.js` (where plugin cards and a snapshot's notices go in the history: a card added or updated in place by its id, a running turn's into its step, a snapshot's each above the first turn after it, a finished turn's notice in its step's rows and its question resolved where it was asked; a card's action buttons), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history), `commands.js` (session commands: which composer lines are commands, the page's own replies, a `command_ran`'s bubble, the page's command bubbles kept across a re-read), `composer.js` (where a composer line goes, `routeComposerLine`: /cut and /queue, the start page's own replies, a session command or `!cmd`, a typo hint, else a turn; and a session command sent from the composer or a chip), `delivery_line.js` (the composer's row above the text field in a session, always there so the composer keeps its height: the key hint while idle, and the delivery line while a turn runs: where a message typed now goes in, from the step's phase, clock and size, whether "cut in now" can land, and the queue link for a worker with the `delivery` feature, as a pure `deliveryLine`, its lit-html template and `createDeliveryControl`, which ticks it and keeps a choice armed from a link; see docs/cli.md, "Typing during a turn"), `restore.js` (a failed turn's prompt handed back into this tab's composer, before or after its `/turn` ack), `lists_view.js` (the session lists: the strip and its pill, all sessions with its search, count and select mode, their cards, the family and chain popovers; the cards, tile and pill as lit-html templates, drawn as new nodes each time, and the lists' orders as pure functions), `stream_handlers.js` (the open session's stream event handlers, by event type, over the page's views and hooks; a snapshot replays through them too), `stage_view.js` (the stage view: the running turn pinned above the composer, then handed off into the history; its pure rules and texts in `stage_model.js`, its live slots (headline, now row, trail, ticks) in `stage_slots.js`, its cap and held height in `stage_frame.js`, the in-use watch that times the hand-off in `stage_watch.js`), `info_bar.js` (the session bar's info line as a lit-html template over a plain model: id, status, model, chain links, chips, ctx, speed, clock, worker badge), `info_bar_model.js` (that model and the bar's buttons' states, built from the page's session state, its list and its in-flight continues and restarts as pure functions; `app.js`'s `updateInfoBar` applies them every second while a turn runs), `session_state.js` (what the page knows about the open session: its empty state, and `sessionStateFrom`, the fields a `GET /sessions/:id` payload sets), `refs.js` (refs: a kind and a target on the element, a plugin's ref data (label, http(s) URL actions) bound in a WeakMap by `bindRef`, the targets per kind, show in turn, one delegated set of click, key and hover listeners), `ref_menu.js` (a ref's `▾` and its menu), `ref_scan.js` (the `path:line` refs in an answer's or a step's text that name a file the session's rows touched), `answer_refs.js` (the refs a plugin attached to an answer, its `display_refs`: bound to the answer's bubble, paired with its links and text, bound with `bindRef`). Unit-tested via `npm test` (`spec/web/public/*.test.js`).
+- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover; the chip and rows as lit-html templates), `keep_focus.js` (lit reuses a list's nodes by position: a redraw keeps the focus on the same item by its `data-id` / `data-name`), `chains.js` (session chains: the links from `continues`, the cards folded into the latest link's, its `day N` chip and rows as lit-html templates, the info bar's ← → links, a refused continue, and the fresh-link rule), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `bubbles.js` (the history's bubbles between the turns' rows: output chunks, end lines, every client's prompt bubbles by `enqueued_id` with their queued/steered badges, the idle recap, guardrail warnings, hooks' notices, plugins' steers, command and note bubbles; lit-html templates, put in the history with the sticky follow by `createBubbles`), `cards_place.js` (where plugin cards and a snapshot's notices go in the history: a card added or updated in place by its id, a running turn's into its step, a snapshot's each above the first turn after it, a finished turn's notice in its step's rows and its question resolved where it was asked; a card's action buttons), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history), `commands.js` (session commands: which composer lines are commands, the page's own replies, a `command_ran`'s bubble, the page's command bubbles kept across a re-read), `composer.js` (where a composer line goes, `routeComposerLine`: /cut and /queue, the start page's own replies, a session command or `!cmd`, a typo hint, else a turn; and a session command sent from the composer or a chip), `delivery_line.js` (the composer's row above the text field in a session, always there so the composer keeps its height: the key hint while idle, and the delivery line while a turn runs: where a message typed now goes in, from the step's phase, clock and size, whether "cut in now" can land, and the queue link for a worker with the `delivery` feature, as a pure `deliveryLine`, its lit-html template and `createDeliveryControl`, which ticks it and keeps a choice armed from a link; see docs/cli.md, "Typing during a turn"), `restore.js` (a failed turn's prompt handed back into this tab's composer, before or after its `/turn` ack), `lists_view.js` (the session lists: the strip and its pill, all sessions with its search, count and select mode, their cards, the family and chain popovers; the cards, tile and pill as lit-html templates, drawn as new nodes each time, and the lists' orders as pure functions), `stream_handlers.js` (the open session's stream event handlers, by event type, over the page's views and hooks; a snapshot replays through them too), `stage_view.js` (the stage view: the running turn pinned above the composer, then handed off into the history; its pure rules and texts in `stage_model.js`, its live slots (headline, now row, trail, ticks) in `stage_slots.js`, its cap and held height in `stage_frame.js`, the in-use watch that times the hand-off in `stage_watch.js`), `info_bar.js` (the session bar's info line as a lit-html template over a plain model: id, status, model, chain links, chips, ctx, speed, clock, worker badge), `info_bar_model.js` (that model and the bar's buttons' states, built from the page's session state, its list and its in-flight continues and restarts as pure functions; `app.js`'s `updateInfoBar` applies them every second while a turn runs), `session_state.js` (what the page knows about the open session: its empty state, and `sessionStateFrom`, the fields a `GET /sessions/:id` payload sets), `refs.js` (refs: a kind and a target on the element, a plugin's ref data (label, http(s) URL actions) bound in a WeakMap by `bindRef`, the targets per kind, show in turn, one delegated set of click, key and hover listeners), `ref_menu.js` (a ref's `▾` and its menu), `ref_scan.js` (the `path:line` refs in an answer's or a step's text that name a file the session's rows touched), `answer_refs.js` (the refs a plugin attached to an answer, its `display_refs`: bound to the answer's bubble, paired with its links and text, bound with `bindRef`). Unit-tested via `npm test` (`spec/web/public/*.test.js`).
 - Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).
 
 **Test-session hygiene:**
@@ -216,7 +216,7 @@ A session can **continue** an earlier one: "the next day of the same routine" (a
 - **If the continue fails part-way:** a new link that fails to start gives its moved delegates back before it is deleted (each gets a note saying so; its worker is stopped first, if one started, and a worker that won't stop is reported, the link left), with any report one of them rang it with meanwhile; the previous link, back in the lists, is woken for reports waiting. A continue that dies in the middle leaves a `move.json` in the new link's folder: the new link's next worker finishes that move (only the delegates it names, and without a second note to one already told) as it starts. Until the new link's own worker holds it, a ring from a moved delegate doesn't start another (a `starting` marker in its folder, which that worker removes; a stale one, over 60 s old or from a process that is gone, is ignored). An open delegate below an archived delegate refuses the continue (`under archived …`): unarchive that one, or archive this one.
 - **Refused too:** a link that is continued already (naming the link that continues it; continue that one, or `last:<id>`), a previous link whose folder is gone, and one whose model's host can't run it when no default model is configured to fall back to. A refusal starts nothing and archives nothing; a new link that fails to start puts back what was archived. Every refusal that can be known up front (the archive's ones included) comes before the recap wait. One continue of a session runs at a time (a lock in its folder; other chains don't wait), so a double click finds the first one's link and is refused, while a `last:<id>` continue that waited follows the chain to its new end.
 - **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and `model` (or `model_name`) for the new link's model, but not `dir`, `llm_context` or `thinking` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none), and `model_warning`: the default-model fallback's warning, then any about the model id, joined by `; ` (`null` for none); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a given model whose host config.yml doesn't have (or a fallback with no default model); 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.
-- **The page:** the info bar's `continue →` continues the open session (`continues: <id>, idle: true`; it reads `continuing…` through the recap wait) and opens the new link with `Continue where we left off.` in the composer, not sent (the same line for every chain; a draft already there stays instead); the previous link is archived, a toast says so (`Continued 3fa2c1d0 in 4b7e9a01; 3fa2c1d0 is archived; 1 open delegate moved`), and a moved delegate's card folds under the new link. A link continued already has no `continue →`: its `→` link goes to the next link (a stale page's continue answered 409 `continued` opens `next_id`). A continue refused for open delegates that can't move shows a toast that names each one (its preview and what the server says to do: `older chi worker 0.46.1; restart it`, `open in a chi REPL; close it there`), each a link to its page; any other refusal shows the server's words. The info bar of a link carries `← 2026-10-08` (the previous link's day) and, on an earlier link, `2026-10-10 →`, each a link with its preview and id in the tooltip. A link whose title is the opener and nothing else (its first message once sent) shows its chain's first link's title instead, on its card, in the popover and in its info bar's title line, display only (its messages and data keep the opener; its own title when the first link is gone). The lists fold a chain into the card of its latest listed link, whatever the earlier links' archived state (typing in an archived link brings it back, folded there still), their delegates with them: the card's `↩ day N` chip (`day N of M` when later links aren't listed) opens a popover of the other links, newest first (`day N`, its date, its recap's first sentence or its preview, `archived`), a click opens one; the chip shows a live dot or `waiting` for a link that has a worker or waits on the user, and a waiting link puts its chain's card first. All sessions folds nothing while a search is typed or "include archived" is on: every link is a card of its own then, its chip `day N of M`, with its own delegates folded in, so a search finds an earlier link and its delegates.
+- **The page:** the info bar's `continue →` continues the open session (`continues: <id>, idle: true`; it reads `continuing…` through the recap wait) and opens the new link with `Continue where we left off.` in the composer, not sent (the same line for every chain; a draft already there stays instead); the previous link is archived, a toast says so (`Continued 3fa2c1d0 in 4b7e9a01; 3fa2c1d0 is archived; 1 open delegate moved`), and a moved delegate's card folds under the new link. When the previous link's model's host is gone the link starts on the default model and the toast carries the server's `model_warning` too, and then stays until closed. A fresh link (one with no turn yet, however it was made: `continue →`, `chi send --new --continues`, a reload) shows the model picker in its composer with the link's model, until its first turn starts (a failed or canceled first turn ends it too); a pick runs `/model <name>` in the link (a command bubble; the info bar follows) and changes neither the start page's remembered model nor its Recent list, and a Send right after it waits for the `/model` to be taken. A link a chi REPL owns, or one continued already, shows none. A link continued already has no `continue →`: its `→` link goes to the next link (a stale page's continue answered 409 `continued` opens `next_id`). A continue refused for open delegates that can't move shows a toast that names each one (its preview and what the server says to do: `older chi worker 0.46.1; restart it`, `open in a chi REPL; close it there`), each a link to its page; any other refusal shows the server's words. The info bar of a link carries `← 2026-10-08` (the previous link's day) and, on an earlier link, `2026-10-10 →`, each a link with its preview and id in the tooltip. A link whose title is the opener and nothing else (its first message once sent) shows its chain's first link's title instead, on its card, in the popover and in its info bar's title line, display only (its messages and data keep the opener; its own title when the first link is gone). The lists fold a chain into the card of its latest listed link, whatever the earlier links' archived state (typing in an archived link brings it back, folded there still), their delegates with them: the card's `↩ day N` chip (`day N of M` when later links aren't listed) opens a popover of the other links, newest first (`day N`, its date, its recap's first sentence or its preview, `archived`), a click opens one; the chip shows a live dot or `waiting` for a link that has a worker or waits on the user, and a waiting link puts its chain's card first. All sessions folds nothing while a search is typed or "include archived" is on: every link is a card of its own then, its chip `day N of M`, with its own delegates folded in, so a search finds an earlier link and its delegates.
 - **CLI:** `chi send --new --continues (ID|PREFIX|last:ID) [--model M] [-m TEXT]` (see *Starting a session*).
 - **Which link:** an id, a unique prefix, or `last:<id or prefix>`, the latest link of the chain that session is in. It walks the links that still exist: a deleted link in the middle (`chi sessions delete`, the retention sweep of an unarchived one) ends the walk before it, so `last:` of an earlier link then names that earlier link, and continuing it starts a second line beside the links after the gap; name a link after the gap instead. A trigger names the chain this way: `chi send` to an archived link would bring it back (a human's input), not continue the chain.
 
@@ -232,7 +232,7 @@ and a fork (`ctx.sessions.fork`) keep it, as they keep the thinking level; a del
 
 ## Delegating
 
-The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail like an `execute` result. Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `delegated by` in its info bar; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
+The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail above 64 KB (`DelegateWait.cut`); a reply longer than `max_tool_output_chars` keeps its start and its end (the conclusion), with a gap line naming that `output/` file, where the whole reply is (`ToolOutputCut`'s `:head_tail_ref`; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `delegated by` in its info bar; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
 
 - `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one. The wait (`wait: true`, a later `delegate_result`) and the delegate report are for the reply of the child's turn the follow-up went to: its running turn, which it merges into, or the turn of its own it runs when the child is idle (`turn` in `delegates.json`, set when the child's worker names `turn_ids`), not a newer reply of a turn queued behind it. A follow-up merged as a steer into a turn the child started at that moment (a wake, a reminder, another message) gets that turn's reply or question. A child on its first turn, or with an older worker, gives its next reply, as before.
 - `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's.

data/docs/sub-agent.md

@@ -21,7 +21,8 @@ and Claude's answer comes back as attached context. The
 [codex-peer bundle](plugins.md#the-codex-peer-bundle) does the same with a
 Codex CLI session (`codex_send`, `/codex`, through `codex queue`). The peer's
 answers wake chi in a short loop (fix or disagree, send again) until it says
-`VERDICT OK` or after `context.peer_turns` turns: [Waking: peer
+`VERDICT OK` (one closing wake: chi carries on or tells you what was agreed)
+or after `context.peer_turns` turns: [Waking: peer
 sources](context.md#peer-sources-the-peer-loop).
 
 ## The commands

data/docs/testing.md

@@ -4,6 +4,7 @@
 bundle exec parallel_rspec -n 8   # Ruby specs, in parallel (or plain: bundle exec rspec)
 npm test                          # web frontend specs
 npm run e2e                       # web UI happy paths in Chromium, fake model (once: npx playwright install chromium)
+npx playwright test spec/e2e/stage.spec.js   # one e2e file (the root playwright.config.js is the suite's)
 bundle exec rake lint             # RuboCop: no offenses (CI runs it)
 ```
 
@@ -15,6 +16,11 @@ bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
+Goldens (`*_golden_spec.rb`, the prompt snapshots) hold no machine state, so they pass on any runner: no absolute
+paths (replace them with placeholders), no PATH tools (the suite pins `rg` as found, `spec_helper.rb`; an example
+that sets PATH to test the lookup is tagged `:real_rg`), no Ruby-version-dependent `inspect` (a Hash's or an
+exception's text changes between Ruby versions: write the string yourself).
+
 The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
 `question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
@@ -49,7 +55,8 @@ script/affected-specs A..B            # another range (A...B: from their merge-b
 
 A builder runs these while working, not the full suite: the specs the change touched, the specs named after the
 files it changed (`lib/samagotchi/foo/bar.rb` → `spec/foo/bar_spec.rb`, `bar_*_spec.rb`…), the specs that read
-docs or source as text (its `RULES`: add one when a full run catches what the names missed), then the other name
+docs or source as text (its `RULES`: add one when a full run catches what the names missed) and the golden of a changed
+file's layer (any `terminal_ui/*.rb` → `spec/terminal_ui_golden_spec.rb`), then the other name
 matches (a spec named after several changed files first, e.g. `engine_toolkit_spec.rb` for `engine.rb` and
 `toolkit.rb`; then one beside the file, so `plugin/context.rb` picks `spec/samagotchi/plugin/*context*` before
 `spec/guardrails/context_spec.rb`), then the specs that name a changed file's class. The default range is the merge-base with main (or origin/main) plus uncommitted and untracked files.

data/lib/samagotchi/bootstrap/probe.rb

@@ -239,9 +239,7 @@ module Samagotchi
                  .fetch(uri, request, retries: false, check_status: false, log_fields: { purpose: "probe" })
       end
 
-      def network_errors
-        [*LLM::HTTP::NETWORK_ERRORS, OpenSSL::SSL::SSLError, Errno::EADDRNOTAVAIL, Errno::ENETDOWN, Errno::EPIPE]
-      end
+      def network_errors = LLM::HTTP::NETWORK_ERRORS
 
       def reason(error)
         case error

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -3,6 +3,7 @@
 require_relative "../events"
 require_relative "../kernel_loop"
 require_relative "../steer"
+require_relative "../tool_output_cut"
 require_relative "../tool_row_fields"
 require_relative "turn_notice"
 
@@ -294,7 +295,7 @@ module Samagotchi
           capped = output.length > @max_output_chars
           tool[:status] = (event.dig(:activity, :status) || "ok").to_s
           tool[:no_match] = true if event.dig(:activity, :no_match)
-          tool[:output] = capped ? output[0, @max_output_chars] : output.dup
+          tool[:output] = capped ? ToolOutputCut.preview(output, cap: @max_output_chars, tool: event[:tool]) : output.dup
           tool[:output_truncated] = capped || !!event[:output_truncated]
           tool[:images] = event[:images] if event[:images]
           tool[:diff] = event[:diff] if event[:diff]

data/lib/samagotchi/bundles/claude-peer/manifest.yml

@@ -1,23 +1,25 @@
 ---
 name: claude-peer
-version: 0.3.0
+version: 0.4.0
 scope: system
-description: "Pair this session with a Claude Code session you work with: the claude_send tool and /claude send it a part of the work (a plan step, a diff, a finding) to validate or as context, and Claude's answer comes back as the claude-review context; /claude install-skill installs Claude's chi-peer skill, which pairs"
+description: "Pair this session with a Claude Code session you work with: the claude_send tool and /claude send it a part of the work (a plan step, a diff, a finding) to validate or as context, and Claude's answer comes back as the claude-outbox context; /claude install-skill installs Claude's chi-peer skill, which pairs"
 trust_level: reviewed
 files:
   skill_claude_peer.md:
-    sha256: sha256:9293740f3e1afa0fc2eff381f2c6406087598205df351abd22b4459a3bcb5d0e
-    description: "Send a part of the work to the paired Claude Code session (claude_send): only when the user asks, or to reply to its answer in a peer turn; validate, context or question; Claude's answer comes as the claude-review context"
+    sha256: sha256:d94a5a3d4961453fcce7733b44163f217636534c5ef31b397785ffc1d07e1366
+    description: "Send a part of the work to the paired Claude Code session (claude_send): only when the user asks, or to reply to its answer in a peer turn; validate, context or question; Claude's answer comes as the claude-outbox context"
 plugin:
   file: plugin.rb
-  sha256: sha256:74960c46f4b98a453a6c6b16a53a4e9cb76752e6df1deecf55784fc7a0e616ce
+  sha256: sha256:08000c9ccd8672ecae38fb4f53694ad3220caa8ed06de70cc4661ce7e882eecb
 scripts:
-  pair: sha256:033f1fc6a644950b57e71865253526a0a487bb4c9fd5a61bb89d031b65f40417
-  chi-peer-SKILL.md: sha256:753b609bca01877d46e6b1c3c5b74edba745433cbe33a86702d3ab75bc3f7107
+  pair: sha256:35f3be2b466a5ba07591d64040bc5780fdd843b9b08737f8ea8a2fccb2102832
+  chi-peer-SKILL.md: sha256:e991a91139a127a60f9a216043eb5864945fb211952a1e3c8db2068c6cc254f1
 # Two things need chi 0.63.0, and the bundle works without them on 0.62:
 # ctx.context.list's summary: (the /claude card's last answer; without it
 # the card shows no summary), and a pushed source's first wake: true push
 # waking the session (on 0.62 Claude's first answer arrives as a note
 # without waking; later ones wake).
 # The plugin needs Samagotchi::Plugin::Peer and chi.peer_source (chi 0.67.0).
-requires_chi: ">= 0.67.0"
+# An agreeing answer's closing wake (the skills say an OK wakes chi once)
+# and the plugin's OUTBOX (Plugin::Peer's rename of REVIEW) need chi 0.70.0.
+requires_chi: ">= 0.70.0"

data/lib/samagotchi/bundles/claude-peer/plugin.rb

@@ -9,7 +9,7 @@ require "samagotchi/plugin/peer"
 # this chi session and a Claude Code session the user works with. Claude
 # pairs (its chi-peer skill, scripts/pair): it attaches the `claude-inbox`
 # context, whose hint is its per-session inbox socket
-# (CLAUDE_CODE_MESSAGING_SOCKET), and `claude-review`, where its answers
+# (CLAUDE_CODE_MESSAGING_SOCKET), and `claude-outbox`, where its answers
 # come back as pushes that wake chi.
 #
 # The claude_send tool sends a part of the work (a plan step, a diff, a
@@ -30,7 +30,7 @@ require "samagotchi/plugin/peer"
 # /claude (anytime: it only reads files, writes one and posts to a socket)
 # lets the user send without the model: `/claude` alone is a status card
 # (paired or not, the socket and whether it is there, the last send, the
-# last claude-review answer); `/claude validate|context <text>` sends the
+# last claude-outbox answer); `/claude validate|context <text>` sends the
 # text as it is, titled by its first line; `/claude last` sends the model's
 # last completed answer as context (mid-turn, a worker's ctx.messages holds
 # the running turn's partial text, so the before_turn and after_turn hooks
@@ -51,7 +51,7 @@ require "samagotchi/plugin/peer"
 # socket transport.
 class Plugin < Samagotchi::Plugin::Peer
   INBOX = "claude-inbox"
-  REVIEW = "claude-review"
+  OUTBOX = "claude-outbox"
   BUNDLE = "claude-peer"
   NAME = "Claude"
   APP = "Claude Code"
@@ -76,7 +76,7 @@ class Plugin < Samagotchi::Plugin::Peer
                      "question about. Only when the user asks for it, or to reply to its answer " \
                      "in a peer turn. Needs a paired Claude Code session: without one it fails, " \
                      "and the user pairs from Claude. Claude's answer comes back later as the " \
-                     "claude-review context (a validate's wakes you): don't wait or poll. Never " \
+                     "claude-outbox context (a validate's wakes you): don't wait or poll. Never " \
                      "send secrets or the whole conversation."
   TOOL_PARAMS = {
     kind: { type: "string", enum: KINDS, required: true,

data/lib/samagotchi/bundles/claude-peer/scripts/chi-peer-SKILL.md

@@ -28,7 +28,7 @@ sh "__CHI_PEER_PAIR__" <chi session id or URL>
 ```
 
 It attaches `claude-inbox` to the chi session (this session's inbox socket,
-`$CLAUDE_CODE_MESSAGING_SOCKET`, as its hint) and `claude-review` (where your
+`$CLAUDE_CODE_MESSAGING_SOCKET`, as its hint) and `claude-outbox` (where your
 answers go), then lists the session's context. Running it again only refreshes
 the socket. The socket changes when this Claude session restarts: pair again
 then.
@@ -70,12 +70,12 @@ Tell the user in one line what came in and what you answered.
 
 ## Reply into chi
 
-Push the answer to the `claude-review` source. JSON gives the note chi sees a
+Push the answer to the `claude-outbox` source. JSON gives the note chi sees a
 summary, and `wake` starts a chi turn only when chi is waiting on it:
 
 ```sh
 ruby -rjson -e 'puts JSON.generate(text: STDIN.read, summary: ARGV[0], wake: ARGV[1] == "wake")' \
-  "validate <title>: VERDICT CHANGES, 2 issues" wake <<'EOF' | chi context push claude-review <id>
+  "validate <title>: VERDICT CHANGES, 2 issues" wake <<'EOF' | chi context push claude-outbox <id>
 <the full answer>
 EOF
 ```
@@ -84,8 +84,8 @@ EOF
   for a reply to context.
 - Each answer replaces the last (chi keeps the latest one), so start the
   summary with the title you are answering, and end it with your verdict
-  (`VERDICT OK`, `VERDICT CHANGES` or `VERDICT UNSURE`): chi doesn't wake for
-  an OK.
+  (`VERDICT OK`, `VERDICT CHANGES` or `VERDICT UNSURE`): an OK wakes chi once
+  to close the round.
 - Never answer a chi message with `chi send`: it counts as the user typing,
   outside the round's limit. Use it only when the user asks you to.
 
@@ -106,4 +106,4 @@ tell the user.
   read those without being asked each time, the user can allow
   `Read(__CHI_PEER_PAYLOADS__/**)` in Claude Code's permissions (their call).
 - Auto mode refuses posting to this session's own socket, so test from chi.
-- Unpair: `chi context rm claude-inbox <id>` and `chi context rm claude-review <id>`.
+- Unpair: `chi context rm claude-inbox <id>` and `chi context rm claude-outbox <id>`.