samagotchi 0.20.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3b1a6860a8c22ed75259438c755633283385c12ffbc28a8fcb4c817f59114c5
-  data.tar.gz: 24f7c45ebe336077bc2d9a1e670d3313b364c48d5b28aef3624593705236f29e
+  metadata.gz: 9019626f95da411558ec5350303433de58fd07f9db6f9e22323856e4e2ed31a0
+  data.tar.gz: 015df1a469fb64ff5556ce6f683ee23abf039865a34584fff07e3f3c32e4724e
 SHA512:
-  metadata.gz: 9f1d9dec24344b223170728f80629a76d1db18697f752b2ce7135cf3569428a902f1cc18589a928184f7809bcbe3a20289281cd4cae6324bdd3f5bb1192cf860
-  data.tar.gz: 8bf9a7cf6dbaac98a7583987be61d98e06ddd3ab6a0b6f36423ae41a6aa530ef42479fa28139ad89b8253e61edce1a57013dd27d0a9bcbf5b31c080cea6f8801
+  metadata.gz: 1bd652f5d5c2d549dce4eba12cc6577f34cb80ae2a95ea4d63492b4581ed510a5f4eeb8b741f86da7af39198dbfc4981e5d6e7d019dfff7d90f8c0a19722cd6b
+  data.tar.gz: fe6e4cbc412b112d157ad16a1f176fa1308ed094498eb982770b5a6b87859a89c9d544b9c0791d953e0823e51e09396f13e484eccdb240cdd0a0daad8dfe3f8e

data/CHANGELOG.md

@@ -8,6 +8,80 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-10-04
+
+### Added
+
+- Claude models on OpenAI-compatible hosts (OpenRouter) use Anthropic's prompt cache: chat requests mark the
+  system message and the last message with `cache_control`, so each step reads the earlier prompt from the
+  cache (about a tenth of the price) instead of paying for all of it again. The log line shows `cache=on`.
+
+### Changed
+
+- An HTTP 402 is no longer a "rejected the request" bad request. OpenRouter's "would exceed your available
+  credits given your current in-flight requests" (credit reserved by another running request) is retried like a
+  429, 20s apart (about 100s with the default `retry.max`), instead of failing the turn at once; any other 402
+  fails as `out of credits on host <name>: …; add credits, then send again`, with `error_kind` `credits`.
+- `chi answer --option Continue --text "…"` is accepted: the text joins the continued turn as a steer (marked as the parent agent's for `chi answer`), instead of being refused.
+- The Continue answer's text keeps its line breaks in the continued turn's steer, and it is dropped (logged
+  `steer_dropped why=not_begun`) when the continue turn fails before it begins or a typed `/continue no` answered
+  the offer first, instead of joining whatever turn ran next.
+- `chi answer --format json` says `"answered_here": false` when the question was no longer open (answered
+  elsewhere, or another one waits now): it still waits for what comes next, but the JSON no longer reads as if
+  the given answer went in.
+- `chi send --wait` and `chi answer` with `--format json` say why a turn stopped: a failed turn adds `error_kind`
+  (the provider error's kind, e.g. `credits`, `server`) and `retryable`, a canceled one `cancel_reason` (`user`,
+  `hook`, `ctrl_c`, `manual`) and `stopped_by` (the hook, e.g. `loop-guard`), when known. The session's
+  `last_turn` records them.
+
+Update with `chi update` (no bundle versions moved). Restart `chi web` and running sessions afterwards (`chi sessions restart ID`).
+
+## [0.21.0] - 2026-10-04
+
+### Added
+
+- The debug log's generation_completed line names the OpenRouter provider that served it (provider=).
+
+### Fixed
+
+- loop-guard cuts thinking that loops in short sentences ("I'll write it. Go. OK. Writing."),
+  which it skipped before: such a loop ran for minutes to the provider's output cap. New settings
+  `thinking.short_run` (24) and `thinking.short_distinct` (6).
+- loop-guard's thinking watch no longer goes blind for the rest of a generation after an empty thinking
+  chunk (a FrozenError, logged as `plugin_hook_failed`), so it now sees every generation's thinking.
+- loop-guard no longer stops a whole turn for a thinking loop that comes long after the model recovered from
+  its first one: after `thinking.forget_after` (10) steps with no loop, the next loop is cut and retried again.
+- A turn a plugin stopped now says who did it, `✕ turn stopped by loop-guard` (the web: `✕ stopped by
+  loop-guard`), instead of `✕ canceled (by a hook)`, also after a reload of the web page.
+- An attached `/exit` the worker reads only after the TUI stopped waiting (a frozen or sleeping worker) no
+  longer stops it later: the request is dropped, as late turns and commands are.
+- The attached `/exit` (and `/exit --delete`, `/archive`) in an empty session no longer claims the session is
+  already gone: a note arriving before the worker stops keeps it, so it says it will be discarded if nothing
+  arrives.
+- Archiving a session (`/archive`, `chi sessions archive`, the web) with a prompt still queued or a step-limit
+  question open is refused with a message saying so, instead of stopping the worker and leaving the queued
+  prompt to run on the next resume.
+- `/exit` right after a `/detach` and `chi --attach` no longer says "another UI is attached" and leaves the worker
+  up: the worker notices a closed stream at once instead of at its next 15-second heartbeat.
+- Leaving chi's terminal UI (`/exit`, `/detach`, Ctrl-D) no longer can leave a stray cursor report such as
+  `^[[12;1R` at the shell prompt: input nobody read is dropped before the terminal is handed back.
+- Joining a running turn (web or `chi --attach`) while the model is holding before its first token now shows
+  the step it's on, as a live view does, instead of the previous step still live.
+- Web: sending into a session whose worker was already up (but the page didn't know) no longer draws
+  that worker's earlier turns a second time: the page re-reads the session instead.
+- Web without the session events stream (fetched list): a re-fetched list now badges and notifies like the
+  live list does.
+- Web: a session deleted while the page had lost the session events stream (or between two fetches of the
+  list) no longer keeps its question or card counted in the tab title's badge until the tab comes to front.
+- Web on a phone: the session footer's archive, stop and delete buttons are icons (the words stay as their
+  accessible names and tooltips), so the status and `mem N` chips beside them are in sight again.
+- Web: with several chi tabs in the background, a session that needs you shows one OS notification, not one
+  per tab (every tab still counts it in its title).
+- chi web: a session stream whose worker took the connection and froze before answering no longer holds the
+  request forever; it gives up after 5 s per attempt.
+
+Update with `chi update`: loop-guard moves to 0.3.1 (short-sentence loops, forget_after, the blind-watch fix). Restart `chi web` and running sessions afterwards (`chi sessions restart ID`).
+
 ## [0.20.0] - 2026-10-03
 
 ### Added
@@ -1199,7 +1273,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.20.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.22.0...HEAD
+[0.22.0]: https://github.com/dm1try/samagotchi/compare/v0.21.0...v0.22.0
+[0.21.0]: https://github.com/dm1try/samagotchi/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/dm1try/samagotchi/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/dm1try/samagotchi/compare/v0.18.1...v0.19.0
 [0.18.1]: https://github.com/dm1try/samagotchi/compare/v0.18.0...v0.18.1

data/docs/architecture.md

@@ -170,7 +170,8 @@ higher-level events so UIs get clean turn boundaries without inferring them:
 
 - `:turn_started` — `{ session_id:, prompt: }`
 - `:turn_completed` — `{ result: }` (the final `LLM::ModelResult`)
-- `:turn_canceled` — `{ cancellation_reason: }`
+- `:turn_canceled` — `{ cancellation_reason:, cancelled_by: }` (`cancelled_by`: the bundle or hook label that
+  stopped it, for `cancellation_reason: :hook`; else nil)
 
 Every event is a `Hash` with a `:type` symbol key; the sink must not raise (the Engine
 rescues sink errors). A new UI (web, API) supplies its own `on_event` and
@@ -391,8 +392,9 @@ output) and cancel. Cancel closes the in-flight socket from the
 `CancellationController` listener, so it works on any thread.
 
 **Errors.** A failed request raises an `LLM::ProviderError` of one kind:
-`ConnectionError` (`RetryExhausted`), `RateLimited`, `ServerError`, `AuthError`,
-`BadRequest` (`context_overflow?`) or `ProtocolError`. Engine keeps the turn's
+`ConnectionError` (`RetryExhausted`), `RateLimited` (`CreditsHeld`: a 402 about
+credit held by in-flight requests, retried after 20 s), `OutOfCredits` (any other
+402), `ServerError`, `AuthError`, `BadRequest` (`context_overflow?`) or `ProtocolError`. Engine keeps the turn's
 conversation (the prompt plus completed tool iterations) and emits
 `:turn_failed` with `error_kind:`, `retryable:`, `host:` and a one-line
 `summary:`, which the REPL, the attached TUI and the web show.

data/docs/cli.md

@@ -844,7 +844,8 @@ Behavior notes:
   `partial progress kept; !rollback restores the pre-turn state` under it (a canceled continue is back where it
   started). A failed turn ends with `✕ turn failed: <summary> · 2.0s` and a dim `prompt restored for retry`. The
   REPL and attached mode say the same; the web says `✕ canceled (Ctrl-C)` (`stopped` for its Stop button,
-  `by a hook` for a hook's).
+  `by a hook` for a hook's). A turn a bundle's plugin stopped names it: `✕ turn stopped by loop-guard` (the web:
+  `✕ stopped by loop-guard`).
 - Visible text the canceled request had streamed stays in the conversation, marked `[interrupted]`, so the next
   message (or a continue) picks up from the half-finished reply; the canceled request's thinking and any unfinished
   tool call are dropped.

data/docs/configuration.md

@@ -513,6 +513,12 @@ Every chat request carries the session's id as a `Session-Id` header (next to `U
 gateway that spreads requests over several providers can key on it to keep one conversation on one provider, so
 prompt caches hit and every turn is answered by the same model. Servers that don't know the header ignore it.
 
+Chat requests for a Claude model (an id containing `claude`, such as `anthropic/claude-sonnet-5.5`) on a remote
+OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the system message and on the last
+message), so each step reads the earlier prompt from Anthropic's cache instead of paying for it again; the debug
+log's line shows `cache=on`. Nothing to configure. A provider behind a gateway may still not cache: check the
+cached tokens in `/stats`.
+
 ## Llama Model Routing
 
 To explicitly route requests to a named model in llama.cpp, set:
@@ -607,6 +613,9 @@ Transient network failures are retried automatically with exponential backoff.
 - Retry scope: transient network errors (timeouts, reset connections, EOF/socket reachability failures),
   HTTP 429 and HTTP 500/502/503/504/529. A `Retry-After` header replaces the backoff delay; one longer than
   60s is not waited out and the error is reported instead.
+- An HTTP 402 about credit held by in-flight requests (OpenRouter reserves credit for each running request, so
+  one session's long request can make another's fail) is retried like a 429, 20s apart unless `Retry-After`
+  says otherwise: with the default `retry.max` that is about 100s. With `retry.max: 0` it fails at once.
 - A refused connection (nothing listening) is not retried: the turn fails at once with `can't reach host <name> at
   <address> (connection refused) — is the server running?`.
 - A stream that has already produced output is never retried (the retry would repeat it); it fails the turn.
@@ -653,6 +662,8 @@ message (before, a failed llama.cpp `/completion` ended the turn as
 |---|---|---|
 | connection | reset, timed out, dropped mid-stream; refused | yes (network retry), not mid-stream; refused: no |
 | rate limited | HTTP 429 | yes, honouring `Retry-After` |
+| credits held | HTTP 402 "… in-flight requests" | yes, after 20s (or `Retry-After`) |
+| credits | any other HTTP 402: out of credits | no |
 | server | HTTP 5xx, llama.cpp's mid-stream `error:` event | 500/502/503/504/529 only |
 | auth | HTTP 401/403 | no |
 | bad request | other 4xx; a prompt larger than the context window, whatever the status | no |

data/docs/plugins.md

@@ -831,16 +831,22 @@ minutes, until the provider's output cap ends it with no answer. loop-guard
 watches the thinking while it streams ([Watching the
 stream](hooks.md#watching-the-stream)) and cuts it:
 
-- The thinking is cut into sentences; short ones (under `min_words`) are
-  skipped. Two sentences count as the same when their words and word pairs
-  mostly match (`similarity`), so a reworded round ("Hmm, …", a synonym, a
-  swapped clause) still counts.
+- The thinking is cut into sentences. Two sentences of `min_words` or more
+  count as the same when their words and word pairs mostly match
+  (`similarity`), so a reworded round ("Hmm, …", a synonym, a swapped
+  clause) still counts.
 - A loop is a cycle of 1 to `max_period` sentences seen `repeats` times in a
   row, over at least `min_span_sentences` sentences and `min_span_chars`
   chars; or one sentence `max_same` times anywhere in the generation. One
   sentence over and over must be near-identical (`similarity` + 0.4), and a
   longer cycle must hold different sentences: a list of templated sentences
   ("Now I need to open the file <path> and …" for 14 paths) is no loop.
+- Short sentences (under `min_words`) are a loop of their own when
+  `short_run` of them come in a row with at most `short_distinct` different
+  ones among them ("I'll write it. Go. OK. Writing. Go. OK."). Normal
+  thinking has short sentences too ("Hmm.", "Fine."), but spread out or all
+  different (code lines); a longer sentence ends the run, and lines inside a
+  ```` ``` ```` code block don't count.
 - Nothing triggers before `min_chars` of thinking. The watch sees a loop
   within one batch (2000 chars, or a second) of its third cycle.
 
@@ -851,11 +857,16 @@ What happens (`action: retry`, the default):
    `loop-guard> thinking repeats itself (3 sentences ×3, 4k chars, 8 s): cut`
    and `↻ cut by loop-guard, asking again (1/1)`.
 2. If the retry loops too, the turn is stopped ("stopped the turn: …", "✕
-   turn canceled (hook)") with a card that quotes the repeated sentences.
+   turn stopped by loop-guard") with a card that quotes the repeated
+   sentences.
+3. A loop is forgotten after `forget_after` good steps in a row (generations
+   with no loop): a model that recovered and made progress gets its next
+   loop cut and retried again, not the turn stopped. `forget_after: 0`
+   never forgets: the turn's second loop stops it.
 
 The cut uses the `retry.empty_answer` budget: with `retry.empty_answer: 0`
-the first loop ends the turn as cancelled (hook), with the notice and no
-card. `action: stop` stops the turn at the first loop; `action: notify` only
+the first loop ends the turn as stopped by loop-guard, with the notice and
+no card. `action: stop` stops the turn at the first loop; `action: notify` only
 warns, once per generation.
 
 ```yaml
@@ -871,7 +882,10 @@ bundles:
       min_span_sentences: 6   # a loop spans at least this many sentences…
       min_span_chars: 600     # …and this many chars
       max_same: 8             # one sentence this many times in one generation is a loop
-      min_words: 5            # shorter sentences are ignored
+      min_words: 5            # shorter sentences only count toward a short run
+      short_run: 24           # this many short sentences in a row…
+      short_distinct: 6       # …with at most this many different ones is a loop
+      forget_after: 10        # good steps in a row that forget a loop; 0: never
 ```
 
 Not watched:

data/docs/sessions.md

@@ -15,7 +15,7 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **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`. With `"restart": true` (a worker whose sidecar lists the `restart` feature) the worker hands the session to a new worker on the newest chi installed: it leaves, then starts its successor once its lock is free, keeping even an empty session and writing no recap. Clients' streams don't hold a restart (a web tab and an attached terminal reconnect to the new worker); what would be lost does: a turn running or queued, a continue offer, a question or approval waiting, reminders, a `/btw` (or another anytime command) still running, a delegate's approval relay open or settled in the last 10 minutes, and background tasks this conversation started that still run (`WorkerIdleExit#hold_for_restart`; 409 `held` with `reason`). What lives only in the worker's memory goes: the event history a late client replays, the kept `/btw` answers, a plugin's in-memory state.
 
-**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.
+**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 is empty: it will be discarded if nothing arrives before its worker stops.` (a note or prompt landing first keeps it). 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.
 
 **Attached by default:** plain `chi` and `chi --resume ID` run their session in a background worker and attach to it (`session.shared`, default `true`; env `SAMAGOTCHI_SESSION_SHARED`). The worker runs in the session's `working_directory`, so `!commands` and tools see the directory the session was started in. `session.shared: false` keeps the in-process REPL, `--no-shared` does for one run; a session the REPL has open can't be attached ("close it there first"). See [CLI: Sharing a session](cli.md#sharing-a-session).
 
@@ -25,7 +25,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 (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 marks a session whose live worker runs an older chi than the newest installed (`worker_version` in its summary): `chi 0.18.1 · Restart`, which asks to confirm and calls `POST /api/sessions/:id/restart` (a refusal's reason shows in a toast); a worker from before restarts shows `chi sessions stop ID` instead. 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 prompt queued in `input/` (it would run on the next resume) or a live worker's step-limit question still open, in it or a child (409 `busy` too), 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, a queued prompt or an open step-limit question 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 marks a session whose live worker runs an older chi than the newest installed (`worker_version` in its summary): `chi 0.18.1 · Restart`, which asks to confirm and calls `POST /api/sessions/:id/restart` (a refusal's reason shows in a toast); a worker from before restarts shows `chi sessions stop ID` instead. 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.
 
@@ -172,7 +172,7 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 - `--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, 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.
+- `--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. 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.
 - 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.

data/docs/sub-agent.md

@@ -37,7 +37,7 @@ Exit codes, both commands:
 | 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`, `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) |
+| 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). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web or `chi sessions stop`; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -59,8 +59,11 @@ 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);
+reply (or its next question) comes back on that same wait. With
+`--text "…"` the text joins the continued turn as a steer (as a `chi send -m`
+into a running turn does, marked as coming from the parent agent), so one
+answer continues and redirects it. To stop it:
+`--option Stop`, with `--text "why"` for the model;
 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.
@@ -132,7 +135,9 @@ answers from any local process.
 - `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.
+  first) isn't sent; `chi answer` says so and waits for what comes next. Its
+  JSON then has `"answered_here": false` (absent when the answer went in), so
+  an `answered` status there is someone else's answer's turn, not yours.
 - `chi send --wait` and `chi answer` don't read stdin unless it's a pipe or a
   file. Agent shells usually pass `/dev/null`, which is fine.
 
@@ -165,7 +170,8 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
 - `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,
+  getting somewhere, continue it (`answer_with`, `--option Continue`, with
+  `--text "…"` to steer it on the way); 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>`

data/lib/samagotchi/answer_command.rb

@@ -34,7 +34,8 @@ module Samagotchi
         with it), then waits for what comes next and prints it as chi send
         --wait does.
         --question QID  the question's id (chi send --wait prints it); a
-                        question no longer open is not answered
+                        question no longer open is not answered (the JSON
+                        says "answered_here": false)
         --option N|LABEL
                         an option, by number (1-based) or label; repeat
                         on a multi-select question
@@ -47,7 +48,8 @@ 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
+        A step-limit question (kind continue): --option Continue [--text
+        STEER] (the text joins the continued turn as a steer), 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
@@ -214,9 +216,11 @@ module Samagotchi
     end
 
     # The question was answered elsewhere (the web first), or another one
-    # waits now: said, then what comes next is waited for.
+    # waits now: said, then what comes next is waited for (the JSON says
+    # answered_here: false).
     # @return [nil]
     def not_open(qid)
+      @answered_here = false
       error_line("#{command_name}: question #{qid} is no longer open; not answered here, waiting for what comes next")
       nil
     end

data/lib/samagotchi/bridge/sse_writer.rb

@@ -39,6 +39,8 @@ module Samagotchi
     class SSEWriter
       DEFAULT_MAX_QUEUE = 1024
       DEFAULT_HEARTBEAT_INTERVAL = 15.0
+      # Queued by the hang-up watcher (#watch_hangup) to wake #drain!.
+      HANGUP = Object.new.freeze
 
       # @param engine [Samagotchi::Engine] the owning engine (live fan-out)
       # @param ring [Samagotchi::Bridge::RingBuffer] shared capture buffer
@@ -77,6 +79,7 @@ module Samagotchi
         @foreign_cursor = !cursor_epoch.nil? && cursor_epoch != @epoch
         @high_water = @foreign_cursor ? 0 : cursor_seq
         @handle = nil
+        @hung_up = false
       end
 
       # Non-blocking enqueue used as the per-connection live observer. Any
@@ -97,6 +100,7 @@ module Samagotchi
       # the client disconnects or the bridge stops.
       def serve!(io)
         write_sse_headers(io)
+        watcher = watch_hangup(io)
         begin
           if @join_with_snapshot
             # Subscribe and snapshot as one step of the event log, then go live.
@@ -119,11 +123,36 @@ module Samagotchi
           # Client hung up; nothing to do.
         ensure
           @engine.unsubscribe(handle: @handle) if @handle
+          watcher&.kill
         end
       end
 
       private
 
+      # A client that hangs up is noticed now, not at the next write (a
+      # heartbeat, up to its interval away): the Bridge stops counting its
+      # stream (Bridge#open_streams_except), so an attached /exit from the
+      # TUI attached after it isn't held by it. A thread waits for the
+      # socket to read EOF and wakes #drain!. A client sends nothing after
+      # its request; bytes it does send are dropped. Real sockets only.
+      def watch_hangup(io)
+        return nil unless io.is_a?(IO)
+
+        Thread.new do
+          loop do
+            case io.read_nonblock(4096, exception: false)
+            when nil then break
+            when :wait_readable then io.wait_readable
+            end
+          end
+        rescue IOError, SystemCallError
+          nil
+        ensure
+          @hung_up = true
+          @queue.push(HANGUP)
+        end.tap { |thread| thread.report_on_exception = false }
+      end
+
       def replay!(io, snapshot_seq)
         from_seq = @high_water
         oldest = @ring.oldest_seq
@@ -146,6 +175,9 @@ module Samagotchi
       def drain!(io)
         loop do
           payload = @queue.pop(@heartbeat_interval)
+          # The watcher's flag, not only its HANGUP: an overflow can drop that.
+          break if @hung_up
+
           if payload
             if payload.is_a?(Hash) && payload[:sse_reset]
               emit_reset(io)

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -38,8 +38,8 @@ module Samagotchi
       end
 
       # @return [Hash, nil] a copy of the turn in progress: prompt, origin,
-      #   continue, ordered parts (thinking / text / tool / input / steer /
-      #   reminder / notice), pending_question and the last event_seq folded
+      #   continue, ordered parts (generation / 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 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
@@ -101,7 +101,9 @@ module Samagotchi
       # The turn in progress (#current_turn's shape, symbol keys) as the live
       # events that would have drawn it, in order, as turn_events.js
       # snapshotEvents replays it for the web (spec/shared/turn_snapshot.json
-      # pins both): a generation_chunk per thinking or text part (a
+      # pins both): a generation_started per generation part (a join during
+      # a hold shows the step the model is on), a generation_chunk per
+      # thinking or text part (a
       # generation_completed closes text before the next step's), a tool's
       # tool_call_started and, once finished, its tool_call_completed (with
       # the live activity: action, tool, params, status), a merged_input
@@ -123,6 +125,9 @@ module Samagotchi
         end
         Array(turn[:parts]).each do |part|
           case part[:kind]
+          when "generation"
+            close_text.call
+            events << { type: :generation_started, iteration: part[:iteration] }
           when "thinking" then events << { type: :generation_chunk, text: "", thinking: part[:text], iteration: part[:iteration] }
           when "text"
             close_text.call if !text_iteration.nil? && text_iteration != part[:iteration]
@@ -233,6 +238,8 @@ module Samagotchi
       def fold_turn_event(event)
         parts = @turn[:parts]
         case event[:type]
+        when :generation_started
+          parts << { kind: "generation", iteration: event[:iteration] }
         when :generation_chunk
           if event.key?(:text)
             # Profile-split stream: thinking and visible text separately.

data/lib/samagotchi/bridge.rb

@@ -134,7 +134,8 @@ module Samagotchi
 
     # Streams held by anyone but +client_id+: a client's own stream (or two,
     # while it reconnects and the old one isn't noticed dead yet) doesn't
-    # count. A closed stream counts until its next write fails (heartbeat).
+    # count. A closed stream stops counting once its writer reads the
+    # hang-up (SSEWriter#watch_hangup).
     # @return [Integer]
     def open_streams_except(client_id)
       @mutex.synchronize { @open_streams - (client_id ? @streams_by_client[client_id] : 0) }
@@ -698,7 +699,10 @@ module Samagotchi
     # event log held, so no POST /turn lands between its check and its
     # answer; it leaves from its loop after this reply.
     # 200 {status: "exiting", discard?: the session is empty and goes} ({status: "restarting"} for a restart), or 409
-    # {status: "held", reason:} naming what keeps it up. Returns [headers, status, body].
+    # {status: "held", reason:} naming what keeps it up. A past +deadline+
+    # (see #handle_post_turn), checked with the event log held: 408
+    # deadline_passed, the worker not asked (its client said it didn't stop).
+    # Returns [headers, status, body].
     def handle_exit_request(session_id, body)
       return [{}, 501, { error: "exit_unavailable" }] unless @on_exit_request
 
@@ -709,7 +713,15 @@ module Samagotchi
       delete = fetched(parsed, "delete") == true
       restart = fetched(parsed, "restart") == true
       options = restart ? { delete: delete, restart: true } : { delete: delete }
-      reason = @engine.synchronize_events { @on_exit_request.call(client_id, **options) }
+      deadline = fetched(parsed, "deadline")
+      return BAD_DEADLINE unless deadline_valid?(deadline)
+
+      reason = @engine.synchronize_events do
+        next :expired if expired?("exit_expired", deadline, sid: session_id, client_id: client_id)
+
+        @on_exit_request.call(client_id, **options)
+      end
+      return deadline_passed("exit request") if reason == :expired
       if reason.nil?
         return [{}, 200, { status: "restarting", session_id: @session_id }] if restart
 
@@ -849,7 +861,7 @@ module Samagotchi
     end
 
     # The 408 for a request read after its deadline: +what+ (turn, command,
-    # answer, dismissal) was dropped.
+    # answer, dismissal, exit request) was dropped.
     def deadline_passed(what)
       [{}, 408, { error: "deadline_passed", detail: "the #{what} arrived after its client stopped waiting; not run" }]
     end

data/lib/samagotchi/bridge_client.rb

@@ -20,6 +20,10 @@ module Samagotchi
     # A reply's status line; its code is group 1.
     STATUS_LINE = %r{\AHTTP/1\.[01] (\d{3})}
     STREAM_CONNECT_ATTEMPTS = 3
+    # Seconds #stream waits for the Bridge's response headers, per attempt:
+    # a worker that took the connection and froze must not hold the web's
+    # proxy thread (as EventStream::HEADER_TIMEOUT for the TUI's).
+    STREAM_HEADER_TIMEOUT = 5.0
     # Seconds #stream waits for bytes before it asks `running` again.
     STREAM_POLL = 0.5
     # Seconds a one-shot request waits for the whole reply. Every route
@@ -28,7 +32,7 @@ module Samagotchi
     # raises Errno::ECONNREFUSED. The event stream has no such limit.
     READ_TIMEOUT = 30
     # Share of the read timeout a request's deadline allows (25 s of 30): the
-    # Bridge drops a turn, command, answer or dismissal it reads after the
+    # Bridge drops a turn, command, answer, dismissal or exit it reads after the
     # deadline, so one this client timed out on, and said did not go
     # through, never runs when a frozen worker wakes. The rest covers the
     # write and the reply.
@@ -159,13 +163,14 @@ module Samagotchi
     # POST /session/:id/exit: ask the worker to exit now (+restart+: hand
     # the session to a new worker, a worker with the "restart" feature). 200
     # = it will (status "exiting"/"restarting"), 409 = something keeps it up (reason), 404 with
-    # error "not_found" = a worker older than the route.
+    # error "not_found" = a worker older than the route, 408 = too late.
     # @param client_id [String] the asking UI, whose own streams don't hold
     # @return [Response]
     def request_exit(client_id:, delete: false, restart: false)
       body = { client_id: client_id }
       body[:delete] = true if delete
       body[:restart] = true if restart
+      body[:deadline] = deadline
       post("exit", body, read_body: true)
     end
 
@@ -258,7 +263,8 @@ module Samagotchi
     # @param running [#call, nil] asked before every read, and every
     #   STREAM_POLL seconds of silence: the stream ends once it returns
     #   false. A quiet stream is never cut otherwise.
-    def stream(query: "", last_event_id: nil, running: nil)
+    # @param header_timeout [Float] see STREAM_HEADER_TIMEOUT
+    def stream(query: "", last_event_id: nil, running: nil, header_timeout: STREAM_HEADER_TIMEOUT)
       sock = nil
       # Absorb the probe→connect race around a resumed worker's bridge:
       # the sidecar probe can succeed a moment before the worker dies (or
@@ -266,7 +272,7 @@ module Samagotchi
       # avoid the silent empty-200 that EventSource would otherwise keep
       # re-opening.
       STREAM_CONNECT_ATTEMPTS.times do |attempt|
-        sock, = connect_stream(query: query, last_event_id: last_event_id)
+        sock, = connect_stream(query: query, last_event_id: last_event_id, timeout: header_timeout)
         break if sock
 
         sleep(0.15 * (attempt + 1))
@@ -302,7 +308,7 @@ module Samagotchi
     end
 
     # Open GET /session/:id/stream and read past the response headers.
-    # @param timeout [Float, nil] give up when the headers don't start in time
+    # @param timeout [Float, nil] give up when the headers aren't all in by then
     # @return [Array(TCPSocket, Integer), nil] the socket positioned at the
     #   body and the HTTP status, or nil when the Bridge can't be reached
     def connect_stream(query: "", last_event_id: nil, timeout: nil)
@@ -310,10 +316,9 @@ module Samagotchi
       lei = last_event_id.to_s.strip
       last_event_line = lei.empty? ? "" : "Last-Event-ID: #{lei}\r\n"
       sock.write("GET /session/#{@session_id}/stream#{query} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\nAccept: text/event-stream\r\n#{last_event_line}Connection: keep-alive\r\n\r\n")
-      raise Errno::ETIMEDOUT if timeout && !sock.wait_readable(timeout)
-
-      status = sock.gets.to_s[STATUS_LINE, 1].to_i
-      while (line = sock.gets)
+      deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
+      status = header_line(sock, deadline).to_s[STATUS_LINE, 1].to_i
+      while (line = header_line(sock, deadline))
         break if line.strip.empty?
       end
       [sock, status]
@@ -324,6 +329,25 @@ module Samagotchi
 
     private
 
+    # One line of the response headers, or nil at EOF; raises
+    # Errno::ETIMEDOUT once +deadline+ (monotonic, nil: none) has passed. A
+    # line read in pieces, so a Bridge that stops mid-line can't hold it.
+    def header_line(sock, deadline)
+      return sock.gets unless deadline
+
+      line = +""
+      loop do
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise Errno::ETIMEDOUT unless remaining.positive? && sock.wait_readable(remaining)
+
+        char = sock.getc
+        return line.empty? ? nil : line if char.nil?
+
+        line << char
+        return line if char == "\n"
+      end
+    end
+
     # When this client stops waiting for a reply, as epoch seconds (see
     # DEADLINE_SHARE). Wall clock: the worker runs on this machine and reads
     # the same one.