samagotchi 0.66.0 → 0.68.0

data/docs/plugins.md

@@ -291,7 +291,7 @@ is what `targets:` says:
 - `command:`: a shell command the call runs; `command:` rules match it.
 - `cwd:`: where it runs, for the repo root and relative paths.
 - `acts_as:`: the tool a call stands for, when the tool runs other tools
-  (the mcp bundle's `mcp_call`). Rules keyed by that tool's name match the
+  (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).
 - `args:`: the arguments it acts with (a Hash), when they aren't the call's
@@ -308,7 +308,7 @@ targets: ->(args) { { acts_as: "mcp_#{args["server"]}_#{args["tool"]}", args: ar
 ```
 
 An approval of an `acts_as:` call keys on the tool's own name as well
-(`mcp_call>mcp_github_x:…`), so it never stands in for an approval of the
+(`call_tool>mcp_github_x:…`), so it never stands in for an approval of the
 tool it acts as, nor that one for it. Hooks see the call's own name, and so
 does loop-guard's `ignore_tools`.
 
@@ -548,7 +548,7 @@ end
 - **`provides_tools: true`**: the task provides what the plugin's tools
   need: tools of its own (with `chi.replace_tools`), or what fixed tools
   read (the mcp bundle's index of a first-run server's tools, which
-  `find_mcp_tools` searches). A turn sent while it runs starts at once (the user's
+  `find_tools` searches). A turn sent while it runs starts at once (the user's
   message shows), then waits for it **before its first model request**, so
   the model sees the tools; the UIs keep showing the task meanwhile. The
   wait lasts at most `timeout` seconds from the task's start (default 60).
@@ -579,6 +579,89 @@ tool (full) until it comes back, with a warning at its first turn. See
 chi.toolkit "review", base: "lean", add: %w[delegate delegate_result]
 ```
 
+### `chi.tool_source(call:, acts_as:, label:, wait:, prefix:)`
+
+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.
+
+```ruby
+@source = chi.tool_source(label: "mcp", prefix: "mcp_",
+                          call: ->(tool, args, ctx) { run(tool, args, ctx) },  # the result, as a tool block's
+                          acts_as: ->(group, tool) { "mcp_#{group}_#{tool}" }, # what rules match
+                          wait: ->(group) { start_of(group).value })           # a :starting group's start
+index = Samagotchi::Tools::ToolIndex
+@source.publish([index::Group.new(name: "fs", summary: "files in ~/scratch", tools: [
+                   index::Tool.new(group: "fs", name: "read", description: "Read a file.", schema: read_schema,
+                                   acts_as: "mcp_fs_read")
+                 ]),
+                 index::Group.new(name: "chrome", state: :starting)])
+```
+
+- **`publish(groups)`** swaps in the plugin's whole list, from any thread, at
+  any time (a server that started, `list_changed`): a search sees the old
+  list or the new one, never half. A `Group` has a `summary` (its line in
+  `find_tools`' description), a `state` (`:ready`; `:starting`, its tools may
+  still come: a call to it waits on `wait`, a search says "starting, try
+  again"; `:failed` with its `error`) and its tools. A group exists before its
+  tools do. A `Tool`'s `refusal` says why `call_tool` refuses it (nil: it can
+  be called), its `mark` what a search shows beside its name: the plugin
+  decides both (the mcp bundle: a bad schema, a name clash) and publishes
+  them again when they change.
+- **`call`** gets a call chi looked up and checked: the `Tool`, its `args`
+  typed by its `inputSchema`, and the plugin's `ctx`. It returns what a tool's
+  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
+  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
+  one guardrails were given is refused ("the MCP tools changed while the call
+  waited"), so a hook that disagrees refuses every call.
+- **The row** shows `label` (default: the bundle's name) and
+  `<group>/<tool> args…`. `@source.declared_names` and `declared_tokens` say
+  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.
+
+### `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
+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
+sources](context.md#peer-sources-the-peer-loop)).
+
+```ruby
+chi.peer_source "codex-review", label: "Codex"
+```
+
+- `name`: a context source name (as `chi context add` takes it). Another
+  bundle's is a load error.
+- `label:`: the peer's name, said in chi's own lines ("your peer agent
+  Codex"): a capital letter, then up to 23 letters and spaces.
+
+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`
+source. Needs chi 0.67.0 (guard it with `chi.respond_to?(:peer_source)`).
+
 ### `chi.ctx`
 
 The plugin's context (the `ctx` its handlers get), for `register` itself:
@@ -907,7 +990,9 @@ only against this API (`lib/samagotchi/bundles/btw/plugin.rb`).
 only against this API (`lib/samagotchi/bundles/mcp/plugin.rb`), and gives
 the model the tools of [MCP](https://modelcontextprotocol.io) servers. It
 has no memory file, and the servers' tools aren't declared to the model one
-by one: it has two tools, `find_mcp_tools` and `mcp_call` (~250 tokens in
+by one: the bundle publishes them into chi's tool index
+([chi.tool_source](#chitool_sourcecall-acts_as-label-wait-prefix), a group
+per server), and the model has its two tools, `find_tools` and `call_tool` (~250 tokens in
 every request plus a line per server, whatever the servers have; `/mcp`
 says how many). Stdio servers only, for now.
 
@@ -925,7 +1010,7 @@ bundles:
         env: {NODE_OPTIONS: "--no-warnings"}   # added to chi's environment
         cwd: ~/scratch                         # default: where chi runs
         tools: [read_*, list_directory]        # optional: only these (globs)
-        description: files in ~/scratch        # optional: its line in find_mcp_tools
+        description: files in ~/scratch        # optional: its line in find_tools
         timeout: 120                           # optional: this server's per-call timeout
       chrome:
         command: [npx, -y, "chrome-devtools-mcp@latest", --slim, --headless]
@@ -944,7 +1029,7 @@ bundles:
   one is replaced, and so is what a search finds. The model's tools never
   change, so the prompt cache keeps. The saved file also keeps the first
   sentence of the server's `instructions` (from `initialize`), for its line
-  in `find_mcp_tools`.
+  in `find_tools`.
 - **The first run** (no saved list, or the config changed) starts the
   server in an [init task](#chiinitlabel-provides_tools-false-quiet-false-timeout-nil--ctx--):
   every UI shows `Starting MCP server x (first run, saving its tools)`, and
@@ -977,9 +1062,9 @@ bundles:
     command: [chrome-devtools-mcp, --slim, --headless]   # after npm i -g chrome-devtools-mcp
   ```
 
-- **Tools: search, then call.** The servers' tools are kept in an index;
+- **Tools: search, then call.** The servers' tools are kept in chi's tool index;
   the model has two fixed tools:
-  - `find_mcp_tools(query, server?)` searches it by keywords over the
+  - `find_tools(query, server?)` 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
@@ -995,7 +1080,7 @@ bundles:
     `instructions`, and how many tools it has (`- chrome (26 tools)` with
     neither: tool names there get called blind, without a search; a first
     run's server is just its name until the next session).
-  - `mcp_call(tool, args)` calls one: `tool` is `<server>/<tool>`, and
+  - `call_tool(tool, args)` calls one: `tool` is `<server>/<tool>`, and
     `mcp_<server>_<tool>` works too (looked up, not parsed). Two tools whose
     `mcp_<server>_<tool>` comes out the same (servers `git-hub` and
     `git_hub`, names alike up to the 48-character cut) are both refused,
@@ -1039,18 +1124,18 @@ bundles:
   closed, then TERM and KILL go to the server's process group.
 - **`/mcp`** (anytime) shows a card with the servers, their state (cached
   (not started), running with its pid, failed with its count, stopped) and
-  their tools as `<server>/<tool>`, the name `mcp_call` takes.
+  their tools as `<server>/<tool>`, the name `call_tool` takes.
   A cached or running server's line says roughly how many tokens its tool
   definitions take (`~4,232 tokens`), which only a search's answer carries
-  now; the last line says what every request carries (`find_mcp_tools` and
-  `mcp_call`) and totals the servers'. It is an estimate:
+  now; the last line says what every request carries (`find_tools` and
+  `call_tool`) and totals the servers'. It is an estimate:
   the definitions' JSON as the chat API gets it (`api: openai`), divided by
   4. The native prompts (Gemma, Qwen) render a flatter schema, so there they
   take less. The log records each server's estimate when it changes
   (`mcp_tools_estimated`).
 - The server's stderr goes to the debug log (`plugins` records, bundle=mcp).
 - **Guardrails.** A rule's `tool:` can be a glob, so one rule covers every
-  MCP tool (a search is `find_mcp_tools`, outside `mcp_*`, so it isn't
+  MCP tool (a search is `find_tools`, outside `mcp_*`, so it isn't
   asked about):
 
   ```yaml
@@ -1062,20 +1147,21 @@ bundles:
         reason: an MCP server's tool
   ```
 
-  `mcp_call`'s `targets:` act as the tool it calls, by its
+  `call_tool`'s `targets:` act as the tool it calls, by its
   `mcp_<server>_<tool>` name ([acts_as:](#guardrails)), so `tool:
-  "mcp_github_*"` or `tool: mcp_github_merge_pull_request` match an
-  `mcp_call` to it, as they matched the tool when it was declared by that
+  "mcp_github_*"` or `tool: mcp_github_merge_pull_request` match a
+  `call_tool` to it, as they matched the tool when it was declared by that
   name. A call made before the server's tools are known (a first run
   still starting) is matched by the name the model gave, so the rule fires
   before the call waits; if the tool it then finds isn't that one, the
   call is refused. The question shows the inner arguments under `<server>: <tool>`
   (`everything: get_sum: a=20 b=22`), and "Allow this call for the
   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.)
-  Two things see `mcp_call`, not the tool: hooks (a `before_tool_call`
-  event's `tool:` is `"mcp_call"`, the tool in its args), and loop-guard's
-  `ignore_tools` (`mcp_call` ignores every MCP call; calls to different
+  (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
+  `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).
 
@@ -1653,10 +1739,20 @@ 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
+  ([`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.
 - **The skill.** `skill_claude_peer` (system scope) tells the model to send
-  only when you ask, to pick the part rather than the session, not to wait
-  or poll, and how to read the `claude-review` answer (a validate ends with
-  `VERDICT: OK`, `CHANGES` or `UNSURE`).
+  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`
+  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
+  and never answers with `chi send` (which counts as you typing).
 - **Asking first.** The tool has no `targets:`, so guardrails match it by name
   only: to be asked before each send, add a rule ([Rules in
   config.yml](guardrails.md#rules-in-configyml)):
@@ -1680,6 +1776,10 @@ Claude pairs; without one the bundle costs one tool declaration.
   bypasses permissions holds it for approval (in `-p` it expires after 5
   minutes). It is local only (a Unix socket), but it does hand session
   content to another agent: only what the model or you picked.
+- **Needs chi 0.67.0** for the loop (`chi update`): the plugin is built on
+  `Samagotchi::Plugin::Peer` (lib/samagotchi/plugin/peer.rb), the base both
+  peer bundles share (the tool, `/claude`, the cards, payloads), and each
+  bundle sets its strings and transport.
 
 ## The codex-peer bundle
 
@@ -1758,6 +1858,9 @@ 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
+  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.
 
 ## Shutdown
 

data/docs/sessions.md

@@ -76,7 +76,7 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 - `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 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), `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), `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), `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` (`node --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), `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:**
@@ -198,7 +198,7 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
 - `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
 - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. With a turn running, that turn's reply (its `interrupted_turn` mark names it), not a turn's queued behind it; with the step-limit question standing, the reply of the turn its Continue runs. With neither (or a worker whose `bridge.json` lacks `turn_ids`), the next reply of any turn. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
-- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model, LLM context and thinking level, so `--dir`, `--model`, `--llm-context*` and `--thinking` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1.
+- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model (or the one `--model` names), LLM context, thinking level and toolkit, so `--dir`, `--llm-context*`, `--thinking`, `--toolkit`, `--tool` and `--no-tool` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1, and a `--model` it can't start on is `chi send: could not start a session: …`, exit 1, nothing archived. A fallback to the default model (below) prints `chi send: warning: …`.
 - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
 - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
 
@@ -208,16 +208,16 @@ A session can **continue** an earlier one: "the next day of the same routine" (a
 
 `SessionManager.continue_session` makes the next link:
 
-- **What it copies:** the previous link's folder, its model (the name it was typed as, so an alias holds) and its own LLM context values. Its preview is the previous link's (until its first message is saved), unless it starts with a message.
+- **What it copies:** the previous link's folder, its model (the name it was typed as, so an alias holds) unless the continue names one (`--model`, the web's `model`), and its own LLM context values. A model given is checked like a new session's (a host config.yml doesn't have refuses the continue, nothing archived). An inherited model whose host can't run it any more (gone from config.yml, `enabled: false`, an alias naming another host) **falls back to the default model** with a warning, `gone:org/model can't run (unknown host 'gone' in model …); started on <default>`, decided before the archive; with no default model configured the continue is refused. The carry note doesn't mention the model. The new link carries no transcript, so a different model, or another provider, starts clean there. Its preview is the previous link's (until its first message is saved), unless it starts with a message.
 - **The carry note:** the new link starts with a context note from `session chain` (shown in its transcript as `note from session chain`), queued before its worker spawns, so its first turn sees it: `This session continues 3fa2c1d0 (2026-10-08), the previous link of its chain. Its recap, as of 2026-10-08 18:02:` and the previous link's recap (`recap.json`; cut at 8000 characters). No recap (fewer user turns than a recap needs, recaps off, none written in time): `… It left no recap.` Never more than the recap: no transcript. An idle new link holding only the note is kept, not discarded as empty.
 - **The recap first:** a previous link with a live worker is asked for a recap (the Bridge's `POST /recap`) and given up to 30 s to write it; one with none wrote its recap when its worker left.
 - **The previous link is archived** before the new one starts, by the archive's own rules (see *Archiving a session*): a turn running, a prompt queued or the step-limit question refuse it, a live idle worker is stopped, a plain REPL's session is refused. Its finished delegates are archived with it, as any archive does.
 - **Its open delegates move to the new link** instead: each direct delegate that is running, waiting for an answer, has a live worker or a reply its parent wasn't given, or has such a delegate below it (checked again after the recap wait, so one delegated meanwhile moves too). It moves with its own delegates, stays unarchived, and from then on is the new link's: its card folds under the new link, its reports ring the new link (an idle one runs a wake turn for them, as for its own delegates), `delegate_result` and the `⑂` chip count it there, and what its parent was already told (`delegates.json`) and any report still waiting come along, so nothing is reported twice. A moved delegate gets a context note from `session chain`, `Your parent session is now 4b7e9a01 (…), the next link of its session chain: …`, as its system prompt keeps naming the parent it started with. The move writes `<child>/parent.json` (`{parent_id, from, at}`) beside the child's session file, never the file itself, so a live child worker saving its own copy changes nothing; every reader applies it (a later move overwrites it; it is never removed). A continue is **refused for an open delegate that can't move** (`SessionContinue::Refused`, naming it): one whose live worker runs an older chi (`older chi worker 0.46.1; restart it`: `chi sessions restart <id>`, or stop it) or that is open in a chi REPL (close it there). An older `chi web` or CLI still running shows a moved delegate under the archived link until it is restarted.
 - **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 names a host config.yml no longer has. 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 not `dir`, `model` or `llm_context` (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); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a model whose host is gone; 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`.
+- **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.
-- **CLI:** `chi send --new --continues (ID|PREFIX|last:ID) [-m TEXT]` (see *Starting a session*).
+- **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.
 
 ## Toolkits

data/docs/sub-agent.md

@@ -19,7 +19,10 @@ you already work with (to validate, as context, or with a question), is the
 chi session, chi's `claude_send` tool or `/claude` writes to Claude's inbox,
 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`).
+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
+sources](context.md#peer-sources-the-peer-loop).
 
 ## The commands
 

data/docs/testing.md

@@ -17,9 +17,9 @@ clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (We
 
 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`, the chips, `info_bar.js`, `lists_view.js`, `context_chips.js`, `families_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`,
 `chains.js`, `vendor/lit-html.js`) needs a DOM: `import "./dom_shim.js";` as its first import (happy-dom, a devDependency only,
-never shipped; about 0.3 s per spec file that loads it; lit reads `document` as it loads). The shim's `markupOf(template)`,
+never shipped; lit reads `document` as it loads). The shim's `markupOf(template)`,
 `htmlOf(nodes)` and `canon(html)` compare markup without lit's marker comments; the DOM writes text with only `&`, `<`, `>`
 escaped (a `"` in text stays `"`) and an attribute with `&` and `"` escaped. happy-dom 20 picks the wrong option of a `<select>` whose options lit inserted with
 `?selected`: read the option marked `selected` (`option[selected]`), not `select.value`; the browser follows the mark.
@@ -27,6 +27,11 @@ A select bound with `.value` instead reads right in both, but lit sets it before
 `llm_context_chip.js`'s `renderForm` draws twice then. Assert a kept node with `assert.ok(a === b)`: a failing
 `assert.equal` on two DOM nodes inspects the whole DOM (huge output, can stall the run).
 
+`npm test` runs every file in one process (`--test-isolation=none`; CI and local runs use Node 24): the files share
+`globalThis`, the shim's one happy-dom window and every module's state: a global a spec sets (stage_view's
+`ResizeObserver` stand-in) is there for the files after it, so set only harmless stand-ins and put anything else
+back (`t.mock` restores itself). One file: `node --test spec/web/public/NAME.test.js`.
+
 Where a composer line goes is decided twice, in Ruby (`ComposerRoute`, both terminals) and in the web
 (`composer.js#routeComposerLine`). `spec/fixtures/composer_routes.json` holds the cases both answer: rspec
 (`spec/composer_route_spec.rb`) and `npm test` (`spec/web/public/composer.test.js`) run every row. A change to
@@ -44,8 +49,10 @@ 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 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.
+docs or source as text (its `RULES`: add one when a full run catches what the names missed), 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.
 The Ruby specs go to stdout; the node tests to run (`npm test` targets), "web changed: also run npm run e2e" and a
 hint for a hub class (named in too many specs to list) go to stderr. Nothing printed means nothing matched.
 
@@ -65,6 +72,13 @@ It runs `git worktree add ../samagotchi-NAME -b BRANCH main`, then `npm ci --pre
 `npm test` and `npm run e2e` work there right away (Ruby gems and Playwright's browsers are shared: nothing else
 to install). It refuses when the folder or the branch already exists.
 
+## The desktop helper's build specs
+
+`SAMAGOTCHI_MACOS_BUILD=1 bundle exec rspec spec/desktop` also compiles the macOS helper (`:macos_build`, needs the
+Command Line Tools) and runs `ChiHelper` against a fake kitty and, when a `tmux` is on PATH, a real one (private
+`-L` servers under a temp `TMUX_TMPDIR`, killed after). CI skips them, and `script/affected-specs` doesn't pick them
+for a Swift change: run them by hand after editing `lib/samagotchi/desktop/macos/`.
+
 ## Integration specs
 
 Examples tagged `:integration` (`spec/integration/`, the "with LLM access" part of `spec/hooks/integration_spec.rb`)

data/lib/samagotchi/bootstrap/probe.rb

@@ -9,6 +9,7 @@ require_relative "../version"
 require_relative "../llm/openai_chat"
 require_relative "../llm/http"
 require_relative "../llm/api_key"
+require_relative "../host_keys"
 require_relative "../redacted_inspect"
 
 module Samagotchi
@@ -229,10 +230,10 @@ module Samagotchi
       end
 
       # One attempt through LLM::HTTP (User-Agent, the key's Bearer header),
-      # any status returned as is. A key whose variable is not set sends no
-      # header: the server's 401 then says one is needed.
+      # any status returned as is. A key neither its variable nor the
+      # Keychain holds sends no header: the server's 401 then says one is needed.
       def send_request(uri, request, key_env, read_timeout:)
-        key = key_env && !@env[key_env].to_s.strip.empty? ? LLM::ApiKey.for(key_env, host: uri.host, env: @env) : nil
+        key = key_env && HostKeys.fetch(key_env, env: @env) ? LLM::ApiKey.for(key_env, host: uri.host, env: @env) : nil
         LLM::HTTP.new(label: uri.host, open_timeout: @timeout, read_timeout: read_timeout, api_key: key,
                       retry_policy: LLM::HTTP::RetryPolicy.none)
                  .fetch(uri, request, retries: false, check_status: false, log_fields: { purpose: "probe" })

data/lib/samagotchi/bootstrap_command.rb

@@ -4,6 +4,7 @@ require "rbconfig"
 require_relative "config"
 require_relative "model_profile"
 require_relative "host_registry"
+require_relative "host_keys"
 require_relative "bootstrap/probe"
 require_relative "bootstrap/config_writer"
 require_relative "bootstrap/bundles"
@@ -87,7 +88,7 @@ module Samagotchi
 
       key_env = options[:key_env]
       if key_env && unset?(key_env)
-        fail!("#{key_env} is not set; export it first (the API key; chi only writes its name)")
+        fail!("#{key_env} is not set; #{export_hint(key_env, "first")} (the API key; chi only writes its name)")
         return @exit
       end
 
@@ -187,7 +188,7 @@ module Samagotchi
       key_env = @stdin.gets.to_s.strip
       return fail!("no variable given") if key_env.empty?
       return fail!("#{key_env} isn't a variable name") unless key_env.match?(ConfigFile::ENV_NAME_RE)
-      return fail!("#{key_env} is not set; export it and run chi bootstrap again") if unset?(key_env)
+      return fail!("#{key_env} is not set; #{export_hint(key_env, "and run chi bootstrap again")}") if unset?(key_env)
 
       result = @probe.classify(result.candidate, key_env: key_env)
       return fail!("#{host} refused the key in #{key_env} (HTTP #{result.status})") if result.kind == :needs_key
@@ -433,7 +434,16 @@ module Samagotchi
       @stdin.respond_to?(:tty?) && @stdin.tty?
     end
 
-    def unset?(name) = @env[name].to_s.strip.empty?
+    # Neither the variable nor the Keychain (HostKeys) holds the key.
+    def unset?(name) = HostKeys.fetch(name, env: @env).nil?
+
+    # "export it first", or on macOS "export it or store it in the Keychain
+    # (security …) first".
+    def export_hint(name, tail)
+      return "export it #{tail}" unless HostKeys.available?
+
+      "export it or store it in the Keychain (#{HostKeys.store_command(name)}) #{tail}"
+    end
 
     def fail!(message)
       @stderr.puts("chi bootstrap: #{message}")

data/lib/samagotchi/bridge/ring_buffer.rb

@@ -40,11 +40,6 @@ module Samagotchi
         end
       end
 
-      # @return [Integer, nil] the highest seq buffered so far.
-      def last_seq
-        @mutex.synchronize { @events.last&.[](:seq) }
-      end
-
       # @return [Integer, nil] the lowest seq buffered so far.
       def oldest_seq
         @mutex.synchronize { @events.first&.[](:seq) }

data/lib/samagotchi/bridge.rb

@@ -374,7 +374,10 @@ module Samagotchi
 
         Thread.new { handle_connection(client) }.tap do |t|
           t.report_on_exception = false
-          @connection_threads << t
+          # The ended connections' threads go as a new one comes, so a
+          # long-lived worker's list holds its open connections only. A new
+          # Array: #await_answers and #stop may be walking the old one.
+          @connection_threads = @connection_threads.select(&:alive?) << t
         end
       end
     rescue StandardError => e
@@ -606,13 +609,13 @@ module Samagotchi
 
       record, error = Tools::TaskRuntime.get_record(task_id)
       return [{}, 404, { error: "task_not_found", task_id: task_id }] if error
-      return [{}, 409, { error: "not_running", status: record["status"], task_id: task_id }] unless record["status"] == "running"
+      return [{}, 409, { error: "not_running", status: record.status, task_id: task_id }] unless record.running?
 
       Log.info(:bridge, "task_stop", task_id: task_id)
       record, error = Tools::TaskRuntime.stop_task(task_id, by: "user")
       return [{}, 500, { error: "bridge_error", detail: error }] if error
 
-      [{}, 200, { status: record["status"], stop_reason: record["stop_reason"], task_id: task_id }]
+      [{}, 200, { status: record.status, stop_reason: record.stop_reason, task_id: task_id }]
     end
 
     # The tasks this session started: its history's (created_ids_in) and

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

@@ -1,22 +1,23 @@
 ---
 name: claude-peer
-version: 0.2.0
+version: 0.3.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"
 trust_level: reviewed
 files:
   skill_claude_peer.md:
-    sha256: sha256:dff0175d0370f43920daf5ecbb81315fdd2c7d8063a33fbefc75c7d0e7312993
-    description: "Send a part of the work to the paired Claude Code session (claude_send): only when the user asks; validate, context or question; Claude's answer comes as the claude-review context"
+    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"
 plugin:
   file: plugin.rb
-  sha256: sha256:ee44f119d6f8c6cb25917a0f3fb2cfd1fbca424d537ee5fa7043594a9eb04098
+  sha256: sha256:74960c46f4b98a453a6c6b16a53a4e9cb76752e6df1deecf55784fc7a0e616ce
 scripts:
   pair: sha256:033f1fc6a644950b57e71865253526a0a487bb4c9fd5a61bb89d031b65f40417
-  chi-peer-SKILL.md: sha256:f35f726b1a86091ff69d289e8dd58794ac6f44879a63630fcc88d69867c56e20
+  chi-peer-SKILL.md: sha256:753b609bca01877d46e6b1c3c5b74edba745433cbe33a86702d3ab75bc3f7107
 # 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).
-requires_chi: ">= 0.62.0"
+# The plugin needs Samagotchi::Plugin::Peer and chi.peer_source (chi 0.67.0).
+requires_chi: ">= 0.67.0"