samagotchi 0.16.0 → 0.18.0

data/docs/sessions.md

@@ -13,7 +13,7 @@ Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/s
 
 A session is deleted if **expired by age OR overflow by count** (unless `keep_status` or the live-owner guard: a session a worker or `chi` still has open is never pruned). A session's `status` is its turn state (`idle`/`running`), not whether a worker is alive. Orphan dirs without a `*.json` are never deleted, except skeleton-only ones (see *Empty sessions*). Deletion removes both `*.json` and sidecar dir atomically. Set both `DAYS=0` and `MAX=0` to retain forever.
 
-**Worker idle exit:** a background worker (plain `chi`, Web UI sessions) exits after `SAMAGOTCHI_SESSION_IDLE_EXIT_MINUTES` (`session.idle_exit_minutes`, default `30`, `0`=never) with no turn running or queued, no client on its stream (an open web tab or attached terminal keeps it), no reminder registered and no continue offer waiting for an answer. It removes `bridge.json` and frees `owner.lock`; the next prompt or `--attach` wakes a new worker (`WorkerIdleExit`, `SessionManager.run_session_loop`). A client can also ask the worker to exit right away (Bridge `POST /session/:id/exit`; `/exit` in an attached terminal does, `/detach` doesn't): the same rules apply without the timeout (even with `0`), and the asker's own stream doesn't count. The reply names what keeps it up. The session's status stays as it was, not `stopped`.
+**Worker idle exit:** a background worker (plain `chi`, Web UI sessions) exits after `SAMAGOTCHI_SESSION_IDLE_EXIT_MINUTES` (`session.idle_exit_minutes`, default `30`, `0`=never) with no turn running or queued, no client on its stream (an open web tab or attached terminal keeps it), no reminder registered and no continue offer (the step-limit question) waiting for an answer. It removes `bridge.json` and frees `owner.lock`; the next prompt or `--attach` wakes a new worker (`WorkerIdleExit`, `SessionManager.run_session_loop`). A client can also ask the worker to exit right away (Bridge `POST /session/:id/exit`; `/exit` in an attached terminal does, `/detach` doesn't): the same rules apply without the timeout (even with `0`), and the asker's own stream doesn't count. The reply names what keeps it up. The session's status stays as it was, not `stopped`.
 
 **Empty sessions:** a session nothing happened in is deleted when it is left, so `chi` → `/exit` leaves no trace. Empty means: no messages, no turn tried (a failed turn leaves a `last_prompt` and keeps it), no memory used, no pending question, nothing in `input/`, `notes/` or `images/`, nothing in its dir beyond the worker's skeleton, mode `assist`, and the default model. A session on another model (`/model`, `--model`) counts as prepared and stays (`SessionManager.discardable?`). The worker checks as it idle-exits or leaves on a client's request and deletes it once its lock is free, checking again first. The attached `/exit` then says `Detached; the session was empty, so it is discarded.` The REPL (`--no-shared`) does the same at `/exit` or Ctrl-D. The retention sweep catches those killed first: empty sessions over an hour old with no live owner, whatever `DAYS`/`MAX`, and skeleton-only dirs with no `*.json`. `session.keep_empty: true` (env `SAMAGOTCHI_SESSION_KEEP_EMPTY`) turns all of it off.
 
@@ -23,7 +23,7 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **Deleting a session:** `chi sessions delete ID...`, `/exit --delete` in a terminal and the Web UI's delete all go through `SessionManager.delete_session`: it resolves a unique prefix, removes `<id>.json` and the whole `<id>/` dir, and returns what it removed. A session a plain REPL has open (`owner.lock` kind `tui`) is always refused. One a worker runs is refused unless the caller asks to stop it: then it stops the worker as `chi sessions stop` does and deletes once `owner.lock` is free (`--force` on the CLI, 10 s; the web always, 2 s; `/exit --delete` after the worker agreed to exit, 10 s). A worker that outlives the wait leaves the session in place. The web's route is `DELETE /api/sessions/:id` (200 `{status: "deleted", session_id, stopped}`; 409 `owned_by_tui` or `still_stopping`; 404).
 
-<a id="archiving-a-session"></a>**Archiving a session:** `chi sessions archive ID...`, `/archive` in a terminal and the Web UI's `archive` go through `SessionManager.archive_session`: it writes `<id>/archived` (`{"archived_at": …}`; not a session.json field, which every save rewrites) for the session and its delegated children. `Session.list` leaves archived sessions out unless `include_archived:`, and everything built on it follows: `chi sessions list` (`--archived` shows them, `[archived]`), the summaries (`--live`, json/tsv, the desktop panel, the agent's `list_sessions`) and the retention prune, which neither deletes nor counts them against `max_count`. `children_of` (max_children, `delegate_result`) still sees them, and `--resume`/`--attach ID`, `chi send`/`chi note ID` reach them as before. Refused: a turn running in the session or in one of its children (naming the child; 409 `busy` on the web), a plain REPL owning it (`owned_by_tui`), a `chi scratch` session (`scratch`). A live idle worker is stopped first, and the marker is written even if it is still shutting down. Input a human typed brings a session back (`{"unarchived_at": …}`): a prompt from the web, an attached or plain terminal or `chi send` (origin `web:*`, `tui:*`, `cli:send`, none), steering merged into a running turn, a `/continue` answer or a question answered; a delegate's follow-up, a plugin's turn, a reminder, the idle recap, a note and just opening it don't. A child's input brings only the child back. The retention sweep ages an unarchived session from when it was unarchived, so unarchiving an old session doesn't let the next sweep take it. `/archive` leaves the session first, as `/exit` does, then archives it: in an attached terminal the worker is asked to exit (one that stays up for another UI is stopped by the archive; a running turn refuses it), and an empty session is discarded instead; `chi scratch` refuses it. `chi sessions unarchive ID...` and the web's `unarchive` bring back the whole family. Web routes: `POST /api/sessions/:id/archive` (200 `{status, session_id, archived, stopped, discarded}`, ids) and `POST /api/sessions/:id/unarchive` (200 `{status, session_id, unarchived}`). The session hub and `GET /api/sessions` keep archived sessions, `archived: true` in their summaries: the page leaves them out of the strip, its count and the list at render, and "include archived" by the all-sessions search shows them, dimmed with an `archived` badge. The info bar reads `archive · stop · delete` (`unarchive` on an archived one); archiving the open session stays on it, with an Undo toast.
+<a id="archiving-a-session"></a>**Archiving a session:** `chi sessions archive ID...`, `/archive` in a terminal and the Web UI's `archive` go through `SessionManager.archive_session`: it writes `<id>/archived` (`{"archived_at": …}`; not a session.json field, which every save rewrites) for the session and its delegated children. `Session.list` leaves archived sessions out unless `include_archived:`, and everything built on it follows: `chi sessions list` (`--archived` shows them, `[archived]`), the summaries (`--live`, json/tsv, the desktop panel, the agent's `list_sessions`) and the retention prune, which neither deletes nor counts them against `max_count`. `children_of` (max_children, `delegate_result`) still sees them, and `--resume`/`--attach ID`, `chi send`/`chi note ID` reach them as before. Refused: a turn running in the session or in one of its children (naming the child; 409 `busy` on the web), a plain REPL owning it (`owned_by_tui`), a `chi scratch` session (`scratch`). A live idle worker is stopped first, and the marker is written even if it is still shutting down. Input a human typed brings a session back (`{"unarchived_at": …}`): a prompt from the web, an attached or plain terminal or `chi send` (origin `web:*`, `tui:*`, `cli:send`, none), steering merged into a running turn, a `/continue` answer or a question answered (the step-limit question too); a delegate's follow-up, a plugin's turn, a reminder, the idle recap, a note and just opening it don't. A child's input brings only the child back. The retention sweep ages an unarchived session from when it was unarchived, so unarchiving an old session doesn't let the next sweep take it. `/archive` leaves the session first, as `/exit` does, then archives it: in an attached terminal the worker is asked to exit (one that stays up for another UI is stopped by the archive; a running turn refuses it), and an empty session is discarded instead; `chi scratch` refuses it. `chi sessions unarchive ID...` and the web's `unarchive` bring back the whole family. Web routes: `POST /api/sessions/:id/archive` (200 `{status, session_id, archived, stopped, discarded}`, ids) and `POST /api/sessions/:id/unarchive` (200 `{status, session_id, unarchived}`). The session hub and `GET /api/sessions` keep archived sessions, `archived: true` in their summaries: the page leaves them out of the strip, its count and the list at render, and "include archived" by the all-sessions search shows them, dimmed with an `archived` badge. The info bar reads `archive · stop · delete` (`unarchive` on an archived one); archiving the open session stays on it, with an Undo toast.
 
 **Lazy sweep:** automatic prune runs only while `chi web` runs, at most once per `session.sweep_interval_hours` (default 24): the web's session hub gives it a chance on its periodic full scan, and `GET /api/sessions` does too. No cron, and a terminal-only chi never sweeps. Manual prune is always available.
 
@@ -40,7 +40,7 @@ chi sessions prune [--dry-run] [--days N] [--keep N] [--keep-status running,...]
 chi sessions clean [--dry-run] [--days N]             # test sessions: all, or older than N days
 ```
 
-A session whose worker waits for an answer (a question, a hook's question or a guardrail approval) reads `waiting` in the status column, and json has `waiting: "question"|"approval"|"hook"` and `waiting_id`, the question's id for `chi answer --question` (both null otherwise). A delegate's approval its parent relayed to its own card (see *Delegating*) reads `waiting (in parent ab12)`, json `relayed_to: "ab12…"` (the parent's short id, else null). Only while a worker runs it: a question a dead worker left in the file shows the saved status. Answer it with `chi answer`, the web or `chi --attach ID`; `chi sessions stop ID` frees the worker instead.
+A session whose worker waits for an answer (a question, a hook's question, a guardrail approval, or the step-limit question of a turn that ran out of steps, which waits between turns) reads `waiting` in the status column, and json has `waiting: "question"|"approval"|"hook"|"continue"` and `waiting_id`, the question's id for `chi answer --question` (both null otherwise). A delegate's approval its parent relayed to its own card (see *Delegating*) reads `waiting (in parent ab12)`, json `relayed_to: "ab12…"` (the parent's short id, else null). Only while a worker runs it: a question a dead worker left in the file shows the saved status. Answer it with `chi answer`, the web or `chi --attach ID`; `chi sessions stop ID` frees the worker instead.
 
 Examples:
 
@@ -63,7 +63,7 @@ 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; "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). 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). The info bar copies `chi --attach <id>` for a terminal. 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; 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}], warning?}`; 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). 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 command line (`/model …`) still starts the session as its `prompt`. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`. ↑/↓ 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; 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); "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). 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). The info bar copies `chi --attach <id>` for a terminal. 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; 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}], warning?}`; 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). 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 choice; 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), `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). Unit-tested via `npm test` (`node --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).
@@ -149,7 +149,8 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 - A session with no worker gets one started (like `--attach` or the web composer). A session open in a plain REPL (`--no-shared`) refuses it. Only sessions on this machine: Bridges listen on 127.0.0.1.
 - Fire and forget: it returns once the message is queued and never prints the answer; that shows in whatever is attached. A guardrail "ask" waits for a UI to answer it, so with nothing attached the turn stalls there until one attaches (`chi --attach ID`).
 - `--image PATH` (repeatable, up to 20) sends images with the message, as the web composer's chips do. Each file is read once before anything is sent (bmp, tiff and heic converted to png, large ones downscaled, as for `@path`); a missing file or one that isn't an image stops the send (exit 1; with `--wait --format json`, an `error` line) and nothing is sent; more than 20 is a usage error (exit 2). Each session gets its own copy in `<session>/images/`. Text is still required (`-m` or stdin; context alone counts), also with `--wait`. The session's model must see images: one known not to (the host's model list says text-only, `vision: false` in `models:` or `hosts:`, a native llama.cpp without a vision model) is refused before anything is sent, with the reason (`<id>  refused: gemma can't take images (…); send text only or switch the model (/model)`); the other sessions of the same send still get it, and the exit is 1. With `--new` nothing is started. When chi can't tell (a native host whose `/props` doesn't answer, a list that doesn't say), the message is sent as before and a text-only model fails the turn in the session. A running turn doesn't take images mid-turn: the message runs as the next turn, and the line says `(runs after the current turn)`. With `--new` the session starts idle with the message as its preview, then the message goes in as its first turn once its worker is up (`<id>  started with 1 image`); if the worker doesn't come up in 5 s the session is kept, with its id on the `failed:` line.
-- One line per session: `sent`, `sent with 2 images`, `sent (the running turn picks it up)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
+- A session command runs as the command, as typed in a terminal: `chi send -m "/model qwen" 3fa2` switches the model (`sent as a session command`), and the model never sees the line. What counts is what the session's worker knows (the built-ins, `!cmd`, its bundles' commands); an unknown `/word` (`/usr/bin/env is missing`) goes in as a message. With `--new` a line starting with `/` or `!` starts the session idle and goes to its worker once it is up, which decides. With `--wait` a command has no reply to wait for: exit 0 at once, `<id>  sent as a session command: no reply to wait for …` on stderr (`{"status":"command",…,"detail":…}` with `--format json`); its output shows where the session is open.
+- One line per session: `sent`, `sent as a session command`, `sent with 2 images`, `sent (the running turn picks it up)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
 
 The Automator action above works for messages too: swap its last line for `pbpaste | "$chi" send -m "what do you make of this?" $(print -r -- "$picked" | cut -f1)`.
 
@@ -168,7 +169,7 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 - `--new` takes no ids (one new session per call). `--dir DIR` is its folder, and so its project (default the current one); `--model M` its model (default the configured one; the name isn't checked up front, a wrong one fails the worker's first turn).
 - `--new` prints `<full id>  started` on stdout. With `--wait` that line (and the `sent` line for an existing session) goes to stderr, so stdout is exactly the answer: the reply of the turn the message started, in full. It is the worker's `output/` file, the same one `delegate` reads; a turn that ends with only tool calls and no text has none.
 - `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; wait or attach`, exit 1): the message would run after it, and its reply would come back as the answer.
-- Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question or a guardrail approval), 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.
+- 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). 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. 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).
 - 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.
@@ -181,6 +182,7 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - `delegate(task, model:, session:, wait:, timeout:)`: starts a child and, by default, waits for its reply (`wait: false` returns at once, so several children can run side by side; `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.
 - `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one.
 - What a wait returns, `session: <id>` then `status:` and the text, with the status words `chi send --wait --format json` uses: `answered` with the reply after a `---` line; `question` as soon as the child opens a question (the model's own, or a hook's), with the question's text, options and the `chi answer` command for it (nothing is answered for it: `chi answer`, attach or use the web, then wait again); `failed`, `canceled` or `no_answer` when the child's turn ended with nothing to say (its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `worker_gone` when the child has had no worker for 15 seconds (it crashed without saying so, or idle-exited): `delegate` with `session:` starts it again; `running` on timeout, or when the parent's own turn is canceled (the child keeps running; the next turn can wait again). A reply saved before the child's worker idle-exited is returned at once.
+- **A child's step-limit question goes back to the parent model**, not to its user: `delegate_result` returns `status: question` with the `chi answer` commands for Continue and Stop, and says the model may instead send a narrower follow-up (`delegate session:`, which drops the question) or report back. A parent's `chi answer` follows `turn.parent_continue` (see [chi as a sub-agent](sub-agent.md#the-step-limit)).
 - **A child's approvals go to the parent's user** (the approval relay). While the parent waits (`delegate`, `delegate_result`), a guardrail approval the child opens reopens as the parent session's own approval: the same card in the parent's web page and attached terminal, with the same facts and diff, a line naming the delegate and its task (`delegate ab12 · fix the flaky spec…`, linked to its session) and the header `Approve delegate ab12's tool call?`. The options are the child's, by index; "for the session" says it is the delegate's session (the session scope keys on the child; repo and rule approvals are one shared store). The user answers once there; the parent's model never sees the approval, only one line per relayed approval in the tool's result, before the reply: `approval relayed to your user: execute: git push origin main → allowed once` (or `denied ("why")`, `dismissed (denied)`, `answered on the child`, `not delivered (the child's worker is gone)`, `refused by the child …`, `still open (your turn was stopped)`). The time the card is open doesn't count against `timeout`. While the parent waits on one child, its other running children's approvals are relayed too, oldest first, one card at a time (`+1 more delegate waiting`); each outcome comes in that child's next result.
   - The child's own card stays answerable (the first answer wins: answered there, the parent's card closes as "answered in ab12"). While relayed it says `Waiting for approval in parent ab12: answering here works too`; `chi sessions list` shows the child as `waiting (in parent ab12)` (`--format json`: `relayed_to`), and the web's bell rings for the parent's card, not the child's.
   - How the child trusts it: the parent's POST that says "answered" (Bridge `POST /session/<child>/relay`) carries no answer. The child asks its parent session's live Bridge (`POST /session/<parent>/relay/status`), which reports only what the parent's question flow took from a UI (`RelayDesk`, in memory only), and takes it only for this child, the question pending now, answered. A parent agent's answer on the relay card (a piped or marked `chi --attach PARENT`, `chi answer`) is held to `guardrails.parent_approvals` by the parent and again by the child.

data/docs/sub-agent.md

@@ -33,9 +33,11 @@ Exit codes, both commands:
 | Exit | `status` | Meaning |
 |---|---|---|
 | 0 | `answered` | `text` is chi's reply |
+| 0 | `command` | (`chi send`) the message was a session command (`/model x`): it ran as one, no reply comes |
+| 0 | `not_continued` | (`chi answer`) a Stop answered the step-limit question; the turn's work so far stays |
 | 3 | `question` | chi waits for an answer: `question`, `answer_with` |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
-| 1 | `failed`, `canceled`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened |
+| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it) |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -48,8 +50,33 @@ With `--format json` stdout is one JSON object (see
   "allow_freeform":false},"answer_with":"chi answer 297da360-… --question 3f1c… --option N"}
 ```
 
-`kind` is `question` (the model's), `hook`, or `approval`, which adds the tool,
-command, folder, rule and reason.
+`kind` is `question` (the model's), `hook`, `approval`, which adds the tool,
+command, folder, rule and reason, or `continue`, the step-limit question below.
+
+## The step limit
+
+A turn that runs out of steps (`turn.max_iterations`, default 100) before it
+answers waits as a question of kind `continue` (`"limit": 100`, options
+`Continue` and `Stop`). `answer_with` continues it:
+`chi answer ID --question QID --option Continue`, and the continued turn's
+reply (or its next question) comes back on that same wait. To stop it:
+`--option Stop`, with `--text "why"` for the model (Continue takes no text);
+that wait ends with `status: not_continued`, exit 0, and the turn's work so far
+stays in the session. A message instead (`chi send ID -m "…"`) drops the
+question and starts a new turn. It can't be dismissed.
+
+A parent may Continue by default: Continue grants no permission (every tool
+call still meets the guardrails), it only spends time and tokens. With
+`turn.parent_continue: false` in chi's config.yml (config.yml only, no
+environment variable) a parent may only Stop: `chi answer` and the worker
+refuse a Continue (exit 1, `a parent agent may only stop this turn here`), and
+the user continues it from the web or the terminal.
+
+A chi parent's `delegate_result` gets a child's step-limit question back as a
+`question` with these commands, for its model to decide: continue it (the
+`chi answer` command, through `execute`), send a narrower follow-up with
+`delegate session:` (which drops the question), or report back. It isn't
+relayed to the parent's user the way approvals are.
 
 ## Approvals
 
@@ -74,6 +101,10 @@ variable), "Allow once" goes through; the wider scopes never do,
 and neither does any allow on chi's own config, hooks or guardrail rules. See
 [Guardrails](guardrails.md#approvals-from-a-parent-agent).
 
+Start a child in the folder it should change (`chi send --new --dir PATH`):
+writes and mutating git outside its own repo ask (`write-outside-repo`,
+`git-outside-repo`), which a parent can only deny.
+
 An answer typed into `chi --attach` or the REPL counts as a parent's too when
 stdin isn't a terminal or an agent marker (`CLAUDECODE`, `AI_AGENT`,
 `CODEX_THREAD_ID`, `SAMAGOTCHI_PARENT_SESSION`) is set.
@@ -95,7 +126,11 @@ answers from any local process.
   `chi answer` then exits 1 and says to send the task again
   (`chi send --wait -m "…" ID`); a wait ends with `worker_gone` (exit 1).
 - A follow-up (`chi send --wait -m "…" ID`) to a session waiting for an answer
-  isn't sent: it exits 1 with the `chi answer` command for the question.
+  isn't sent: it exits 1 with the `chi answer` command for the question. The
+  step-limit question is the exception: it waits between turns, so a message
+  goes in, drops it and starts a new turn.
+- `chi send --wait ID` with no message waits past a question already reported
+  (the step-limit question too), until someone answers it.
 - An answer to a question that is no longer open (you answered it in the web
   first) isn't sent; `chi answer` says so and waits for what comes next.
 - `chi send --wait` and `chi answer` don't read stdin unless it's a pipe or a
@@ -129,6 +164,10 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
   `chi answer`, a piped `chi --attach` or chi's web API.
 - `status: running` (exit 4): still working. Wait again:
   `chi send --wait --format json --timeout 500 <session_id>`.
+- `question.kind: continue`: chi ran out of steps before it answered. If it is
+  getting somewhere, continue it (`answer_with`, `--option Continue`); if not,
+  stop it (`--option Stop --text "why"`, exit 0, status `not_continued`) or send
+  a narrower follow-up instead. Ask your user when unsure.
 - Anything else (exit 1): report `detail` to your user. `chi --attach <session_id>`
   shows the session.
 

data/docs/testing.md

@@ -0,0 +1,47 @@
+# Testing
+
+```sh
+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)
+```
+
+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).
+
+## Integration specs
+
+Examples tagged `:integration` (`spec/integration/`, the "with LLM access" part of `spec/hooks/integration_spec.rb`)
+run turns against a live model server. They are skipped unless `SAMAGOTCHI_INTEGRATION=1` is set, and they need the
+server and the model it serves:
+
+| Variable | Meaning | Default |
+| --- | --- | --- |
+| `SAMAGOTCHI_INTEGRATION` | `1` runs them | off |
+| `SAMAGOTCHI_INTEGRATION_HOST` | model server host | `localhost` |
+| `SAMAGOTCHI_INTEGRATION_PORT` | model server port | `8080` |
+| `SAMAGOTCHI_INTEGRATION_MODEL` | the served model id | none: the examples skip |
+| `SAMAGOTCHI_INTEGRATION_API` | `openai` for the chat loop (`hosts.<name>.api`) | none: the native loop |
+| `SAMAGOTCHI_INTEGRATION_TRANSPORT` | `llama_cpp`, `mlx` or `omlx` (`server.transport`) | none: `llama_cpp` |
+
+They run under a config built from these variables alone (`default.model`, `server.host`/`port`, and one
+`hosts.integration` entry; `spec/support/integration_server.rb`), never your `~/.config/samagotchi/config.yml`: no
+aliases, memories, hooks, guardrails or other hosts of yours. Sessions and logs go to the suite's temp state folder.
+
+Run them one at a time (plain `rspec`, not `parallel_rspec`): each example is a real model turn, and the server may be
+shared.
+
+```sh
+SAMAGOTCHI_INTEGRATION=1 \
+SAMAGOTCHI_INTEGRATION_HOST=192.0.2.10 SAMAGOTCHI_INTEGRATION_PORT=8081 \
+SAMAGOTCHI_INTEGRATION_MODEL=org/Model-GGUF:Q4_K_M \
+bundle exec rspec --tag integration spec/integration spec/hooks/integration_spec.rb spec/integration_config_spec.rb
+```
+
+A run takes one to four minutes against a 35B MoE model on llama.cpp (25 examples). `ECONNREFUSED` means the server is down. The
+examples assert what the model did (the tool it called, the file it edited), not its wording, but they still depend on
+a model that follows tool instructions: a small model may fail some of them.
+
+`spec/integration/omlx_spec.rb` tests oMLX's model-id resolution and runs only with
+`SAMAGOTCHI_INTEGRATION_TRANSPORT=omlx`, against an oMLX server (a short model selector in
+`SAMAGOTCHI_INTEGRATION_MODEL`).

data/lib/samagotchi/answer_command.rb

@@ -6,6 +6,7 @@ require_relative "bridge_client"
 require_relative "reply_wait"
 require_relative "parent_report"
 require_relative "guardrails/parent_approvals"
+require_relative "guardrails/parent_continue"
 require_relative "cli/command"
 require_relative "cli/flags"
 require_relative "cli/parent_wait"
@@ -46,6 +47,9 @@ module Samagotchi
         An approval (a guardrail's ask) can be denied here: deny it, and
         tell your user; allowing it is the user's. With
         guardrails.parent_approvals: once, "Allow once" is let through.
+        A step-limit question (kind continue): --option Continue, or
+        --option Stop [--text WHY] (exit 0, status not_continued); it
+        can't be dismissed.
         Exit: 0 answered, 1 failed, refused or the worker is gone, 2
         usage or an option the question doesn't offer, 3 a question waits,
         4 still running (--timeout), 130 Ctrl-C.
@@ -105,8 +109,10 @@ module Samagotchi
       baseline = ReplyWait.baseline_of(session, question_id: qid)
 
       if pending && pending[:id].to_s == qid
+        return failure(not_dismissable(pending)) if options[:dismiss] && ParentReport.continue?(pending)
+
         selected = selection(pending, options) or return @selection_status
-        refusal = approval_refusal(pending, selected, id)
+        refusal = approval_refusal(pending, selected, id) || continue_refusal(pending, selected)
         return failure(refusal) if refusal
 
         posted = post(id, qid, selected, options)
@@ -154,6 +160,18 @@ module Samagotchi
       reason && Guardrails::ParentApprovals.message(reason)
     end
 
+    # Why a parent may not answer Continue (turn.parent_continue: false in
+    # this process's config.yml), or nil; the worker checks it again.
+    def continue_refusal(pending, selected)
+      Guardrails::ParentContinue.refusal(pending, selected) && Guardrails::ParentContinue.message
+    end
+
+    # A step-limit question can't be left unanswered: the turn waits on it.
+    def not_dismissable(pending)
+      "the step-limit question can't be dismissed: answer #{Array(pending[:options]).join(' or ')} " \
+        "(--option Stop --text WHY stops it)"
+    end
+
     # Post the answer (or the dismissal) to the live worker's Bridge.
     # @return [Integer, nil] an exit status when it didn't go in; nil to
     #   wait (it went in, or the question was no longer open: 409)
@@ -174,7 +192,10 @@ module Samagotchi
 
       case reply.status
       when 200 then nil
-      when 409 then not_open(qid)
+      when 409
+        return failure(reply.json&.dig("detail").to_s) if reply.json&.dig("error") == "not_dismissable"
+
+        not_open(qid)
       when 400 then usage_failure(reply.json&.dig("detail") || "the worker refused the answer")
       # The worker's own guardrails.parent_approvals refused the allow.
       when 403 then failure(reply.json&.dig("detail") || "the worker refused the allow: deny it, and tell your user")

data/lib/samagotchi/answer_tail.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "context_note"
+require_relative "output_formatter"
+require_relative "steer"
+require_relative "turn_note"
+
+module Samagotchi
+  # "The last answer a UI shows": the newest message the web's history
+  # shows as an assistant message. One rule for the worker's Bridge (`/tail`,
+  # Engine#last_answer_message) and the web's disk path, so the two can't
+  # drift. Any change to what the web shows as an answer goes through here.
+  module AnswerTail
+    module_function
+
+    # @param messages [Array<Hash>] a session's messages (symbol keys from
+    #   disk or the Engine, string keys from a Bridge snapshot)
+    # @param turn_id [String, nil] that turn's answer: the last one between
+    #   the prompt carrying this turn id and the next prompt (a queued turn's
+    #   page re-reads after the next turn ran). An unknown or missing id:
+    #   the newest answer.
+    # @return [Hash, nil] the raw message (not a copy), or nil
+    def find(messages, turn_id: nil)
+      list = Array(messages)
+      list = turn_slice(list, turn_id.to_s) || list unless turn_id.to_s.empty?
+      list.reverse_each { |m| return m if answer?(m) }
+      nil
+    end
+
+    # The messages of the turn whose prompt carries +turn_id+, from its
+    # prompt up to the next prompt (merged input and steers stay in it), or
+    # nil when no prompt carries it.
+    def turn_slice(list, turn_id)
+      start = list.rindex { |m| Steer.turn_prompt?(m) && (m[:turn_id] || m["turn_id"]).to_s == turn_id }
+      return nil unless start
+
+      stop = list.each_index.find { |i| i > start && Steer.turn_prompt?(list[i]) } || list.size
+      list[start...stop]
+    end
+
+    # Shown as an assistant message: role assistant or model, not a context
+    # note, a steer or a no-answer turn's marker, and some text left once the
+    # wire-format markup is stripped (a tool-call-only step has none).
+    def answer?(message)
+      return false unless message.is_a?(Hash)
+      return false if ContextNote.note?(message) || Steer.steer?(message) || TurnNote.empty_answer(message)
+      return false unless %w[assistant model].include?((message[:role] || message["role"]).to_s)
+
+      !OutputFormatter.strip_markup((message[:content] || message["content"]).to_s).empty?
+    end
+  end
+end

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -41,11 +41,23 @@ module Samagotchi
       #   continue, ordered parts (thinking / text / tool / input / steer /
       #   reminder / notice), pending_question and the last event_seq folded
       #   in. A finished tool part keeps the live row's action and duration_ms
-      #   too. A notice part holds the event of one of the turn's rows
-      #   (TurnNotice: a hook's notice, an empty-answer retry, a question and
-      #   its answer), which a UI replays through its live handler.
+      #   too, a running one the time it has run so far (elapsed_ms), so a
+      #   join times its row from its start. A notice part holds the event
+      #   of one of the turn's rows (TurnNotice: a hook's notice, an
+      #   empty-answer retry, a question and its answer), which a UI replays
+      #   through its live handler.
       def current_turn
-        @mutex.synchronize { @turn && Marshal.load(Marshal.dump(@turn)) }
+        @mutex.synchronize do
+          next nil unless @turn
+
+          turn = Marshal.load(Marshal.dump(@turn))
+          now = @clock.call
+          Array(turn[:parts]).each do |part|
+            started_at = part[:kind] == "tool" && part[:status] == "running" && @tool_started_at[[part[:iteration], part[:call_index]]]
+            part[:elapsed_ms] = ((now - started_at) * 1000).round if started_at
+          end
+          turn
+        end
       end
 
       # The turn in progress as conversation messages, for a plugin's
@@ -142,7 +154,10 @@ module Samagotchi
         call[:label] = part[:label] if part[:label]
         title = part[:title] ? { title: part[:title] } : {}
         events = [{ type: :tool_call_started, **call, params: part[:params], **title }]
-        return events if part[:status] == "running"
+        if part[:status] == "running"
+          events.first[:elapsed_ms] = part[:elapsed_ms] unless part[:elapsed_ms].nil?
+          return events
+        end
 
         activity = { tool: part[:tool], status: part[:status], params: part[:params], **title }
         activity[:action] = part[:action] if part[:action]

data/lib/samagotchi/bridge.rb

@@ -209,8 +209,11 @@ module Samagotchi
     # last cards and between-turns notices (CardStore#list), the session's commands (Commands::Registry#listing:
     # what an attached TUI routes and completes, the web's autocomplete), and the event_seq it all covers.
     # Taken with the log held, so no event is half-applied.
-    # @return [Hash] {messages:, current_turn:, queued:, recap:, saved_recap:, continue_offer:, guardrail_warning:,
-    #   plugin_warning:, init_tasks:, cards:, commands:, event_seq:, event_id:}
+    # The pending question at the top level too: one asked between turns
+    # (the step-limit question) belongs to no turn, so the accumulator
+    # doesn't keep it.
+    # @return [Hash] {messages:, current_turn:, queued:, recap:, saved_recap:, continue_offer:, pending_question:,
+    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, event_seq:, event_id:}
     def snapshot
       @engine.synchronize_events do
         seq = @engine.event_count
@@ -221,6 +224,7 @@ module Samagotchi
           recap: @accumulator.recap,
           saved_recap: @engine.saved_recap,
           continue_offer: @accumulator.continue_offer,
+          pending_question: @engine.pending_question,
           guardrail_warning: @engine.guardrail_warning,
           plugin_warning: @engine.plugin_warning,
           init_tasks: @engine.init_tasks,
@@ -244,6 +248,34 @@ module Samagotchi
       end
     end
 
+    # What the page re-reads at a turn's end and when a card arrives: the
+    # session state, the last answer (Engine#last_answer_message: one
+    # message, not the conversation) and the cards, as one step of the event
+    # log (one event_seq). Light whatever the session's length: GET tail.
+    # @return [Hash] {session_id:, session_state_snapshot:, answer:, cards:, event_seq:, event_id:}
+    # +turn_id+: that turn's answer, not the newest (Engine#last_answer_message).
+    def tail_frame(turn_id: nil)
+      @engine.synchronize_events do
+        seq = @engine.event_count
+        state = @engine.session_state_snapshot.merge(event_seq: seq, event_id: event_id(seq))
+        { session_id: @session_id, session_state_snapshot: state, answer: @engine.last_answer_message(turn_id: turn_id),
+          cards: @cards.list, event_seq: seq, event_id: event_id(seq) }
+      end
+    end
+
+    # The worker's own way in for a session command that came as a message
+    # (its first prompt, an input file): queued and announced as a POST
+    # /command's is (#handle_command).
+    # @return [String] its command_id
+    def queue_command(line, client_id: nil, card: false)
+      command = { command_id: SecureRandom.uuid, client_id: client_id, line: line.to_s.strip }
+      # A card's action (the step-limit question's answer): the UIs leave
+      # its line out.
+      command[:card] = true if card
+      @engine.synchronize_events { queue_command_locked(command) }
+      command[:command_id]
+    end
+
     private
 
     # The Engine's commands: the built-ins and its plugins'.
@@ -337,7 +369,7 @@ module Samagotchi
                                     client_id: stream_client_id(request[:query]))
           break # SSE owns the connection until the client disconnects.
         else
-          payload, status, body = dispatch(route.first, route.last, request[:body])
+          payload, status, body = dispatch(route.first, route.last, request[:body], request[:query])
           write_json(io, status, payload, body)
         end
 
@@ -436,7 +468,8 @@ module Samagotchi
       %w[POST relay/status] => :handle_relay_status,
       %w[GET state] => :handle_state,
       %w[GET stats] => :handle_stats,
-      %w[GET snapshot] => :handle_snapshot
+      %w[GET snapshot] => :handle_snapshot,
+      %w[GET tail] => :handle_tail
     }.freeze
     ROUTE_PATH = %r|\A/session/([^/]+)/(.+)\z|u
 
@@ -452,8 +485,10 @@ module Samagotchi
     # #own_session?), and a handler that raises answers 500 bridge_error,
     # logged (the connection thread doesn't report).
     # @return [Array(Hash, Integer, Hash)] headers, status, body
-    def dispatch(handler, session_id, body)
+    # Only GET tail takes the request's +query+.
+    def dispatch(handler, session_id, body, query = nil)
       return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
+      return handle_tail(session_id, body, query) if handler == :handle_tail
 
       send(handler, session_id, body)
     rescue StandardError => e
@@ -523,7 +558,7 @@ module Samagotchi
         [{}, 409, { error: "question_not_pending", detail: e.message }]
       rescue QuestionDesk::Refused => e
         Log.info(:bridge, "parent_approval_refused", sid: session_id, id: qid, reason: e.reason)
-        [{}, 403, { error: "parent_approval_refused",
+        [{}, 403, { error: e.reason == :stop_only ? "parent_continue_refused" : "parent_approval_refused",
                     detail: Guardrails::ParentApprovals.message(e.reason) }]
       rescue ArgumentError => e
         [{}, 400, { error: "invalid_answer", detail: e.message }]
@@ -579,7 +614,12 @@ module Samagotchi
       return BAD_DEADLINE unless deadline_valid?(deadline)
       return deadline_passed("dismissal") if expired?("dismiss_expired", deadline, sid: session_id, id: qid)
 
-      dismissed = @engine.cancel_question("dismissed", id: qid)
+      begin
+        dismissed = @engine.cancel_question("dismissed", id: qid)
+      rescue QuestionDesk::NotDismissable => e
+        # A step-limit question: its answer is Continue or Stop.
+        return [{}, 409, { error: "not_dismissable", detail: e.message }]
+      end
       return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless dismissed
 
       [{}, 200, { status: "dismissed", id: qid, session_id: @session_id }]
@@ -612,17 +652,21 @@ module Samagotchi
       deadline = fetched(parsed, "deadline")
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
-      command = { command_id: SecureRandom.uuid, client_id: fetched(parsed, "client_id"), line: line }
+      queue_command_request(session_id, line, client_id: fetched(parsed, "client_id"), deadline: deadline,
+                                              card: fetched(parsed, "card") == true)
+    end
+
+    # Queues +line+ (a session command) for the worker and announces its
+    # :command_queued, unless +deadline+ has passed. Returns [headers,
+    # status, body]: 202 with its command_id, or 408.
+    def queue_command_request(session_id, line, client_id:, deadline: nil, card: false)
+      command = { command_id: SecureRandom.uuid, client_id: client_id, line: line }
       # A card's action: the UIs leave its line out (the card is the echo).
-      command[:card] = true if fetched(parsed, "card") == true
+      command[:card] = true if card
       queued = @engine.synchronize_events do
         next false if expired?("command_expired", deadline, sid: session_id, client_id: command[:client_id])
 
-        @on_command.call(command)
-        # An anytime command runs now, beside a turn (D8): the UIs show its
-        # line here, so the cards it shows come after it.
-        anytime = command_registry.lookup(line)&.anytime ? { anytime: true } : {}
-        @engine.announce(type: :command_queued, **command, **anytime)
+        queue_command_locked(command)
         true
       end
       return deadline_passed("command") unless queued
@@ -630,6 +674,15 @@ module Samagotchi
       [{}, 202, { status: "accepted", command_id: command[:command_id], session_id: @session_id }]
     end
 
+    # With the event log held.
+    def queue_command_locked(command)
+      @on_command.call(command)
+      # An anytime command runs now, beside a turn (D8): the UIs show its
+      # line here, so the cards it shows come after it.
+      anytime = command_registry.lookup(command[:line])&.anytime ? { anytime: true } : {}
+      @engine.announce(type: :command_queued, **command, **anytime)
+    end
+
     # A client asks the worker to exit now (`/exit` in the attached TUI). The
     # worker decides with the event log held, so no POST /turn lands between
     # its check and its answer; it leaves from its loop after this reply.
@@ -688,6 +741,14 @@ module Samagotchi
       deadline = fetched(parsed, "deadline")
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
+      # A session command sent as a message (chi send -m "/model x", chi -p,
+      # a UI whose command list lags) runs as the command, as typed in a
+      # TUI; an unknown /word stays a prompt. Not with images: those are
+      # for the model.
+      if images.empty? && @on_command && command_registry.command?(prompt.to_s)
+        return queue_command_request(sid, prompt.to_s.strip, client_id: client_id, deadline: deadline)
+      end
+
       enqueued_id = SecureRandom.uuid
       # Write and announce with the event log held: the worker can't emit
       # this turn's :turn_started (or merge it mid-turn) before
@@ -733,6 +794,17 @@ module Samagotchi
       [{}, 200, snapshot_frame]
     end
 
+    # The page's light re-read (#tail_frame): no message list. `?turn_id=`:
+    # that turn's answer (a queued turn's page re-reads late). The one
+    # handler that gets the query (#dispatch); an older worker's route
+    # ignores it and sends the newest answer.
+    def handle_tail(session_id, _body = nil, query = nil)
+      turn_id = query && URI.decode_www_form(query).to_h["turn_id"].to_s
+      [{}, 200, tail_frame(turn_id: turn_id.to_s.empty? ? nil : turn_id)]
+    rescue ArgumentError
+      [{}, 200, tail_frame]
+    end
+
     # The stream cursor for +seq+ in this worker.
     def event_id(seq)
       EventId.format(seq.to_i, @epoch)

data/lib/samagotchi/bridge_client.rb

@@ -210,17 +210,32 @@ module Samagotchi
     # GET /session/:id/<path> as JSON.
     # @return [Hash, nil] the parsed body, or nil unless the Bridge answered 200
     def get_json(path)
+      status, body = get(path)
+      status == 200 ? body : nil
+    end
+
+    # GET /session/:id/<path>, telling a refusal apart from no answer: an
+    # older worker's 404 for a route it lacks from a refused connect, a
+    # timeout or a 500.
+    # @return [Array(Integer, Object)] the status and the parsed JSON body
+    #   (nil when it isn't JSON); [nil, nil] when no reply came
+    def get(path)
       sock = TCPSocket.new(@host, @port)
       sock.write("GET /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\nConnection: close\r\n\r\n")
       response = read_reply(sock, path)
       sock.close rescue nil
       # A 500 whose text has "200" in it is not a 200.
-      return nil unless response && response[STATUS_LINE, 1] == "200"
+      status = response && response[STATUS_LINE, 1]
+      return [nil, nil] unless status
 
       body = response.split("\r\n\r\n", 2)[1] || ""
-      JSON.parse(body)
+      [status.to_i, begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end]
     rescue StandardError
-      nil
+      [nil, nil]
     end
 
     # Monotonic SSE cursor of the live Engine, from GET /session/:id/state.