samagotchi 0.2.0 → 0.3.0

data/docs/plugins.md

@@ -305,7 +305,9 @@ end
 
 This is a bundle hook, the same as a `hooks/*.rb` file. See
 [hooks.md](hooks.md#hook-events) for the events and for what `event[:notify]`,
-`event[:ask_user]` and `event[:stop_turn]` do. Its label is
+`event[:ask_user]`, `event[:stop_turn]` and `event[:steer]` do; on `:after_turn`,
+`event[:present]` sets how the answer is shown in the web
+([Presenting the answer](hooks.md#presenting-the-answer-display-only)). Its label is
 `plugin.rb (bundle my-bundle)`. The block may take only the event. If it
 raises, the error is logged and the hook is skipped.
 
@@ -435,6 +437,8 @@ session's life, and each read gives the session as it is now.
 | `ctx.card(title:, body: "", actions: [], level: :info, id: nil)` | a card in every UI, returning its id: see [Cards](#cards) |
 | `ctx.ask_user(question:, options:, header: nil, allow_freeform: false)` | a question, like a hook's `event[:ask_user]` |
 | `ctx.cancelled?` | whether the running turn was cancelled (a long tool should stop) |
+| `ctx.steer(text)` | put text into the running turn, like a hook's `event[:steer]`: its own user message at the loop's next boundary, shown as `my-bundle> nudged: …`. Returns true when queued, false with no turn running (it never starts one; that is `ctx.sessions`' send). Dropped (logged) if the model answers or the turn ends first. Safe from any thread: an anytime command, a hook, your own |
+| `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason, like a hook's `event[:stop_turn]`; true when it stopped one now |
 | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
 | `ctx.sessions` | fork, send to and read other sessions: see [Other sessions](#other-sessions-ctxsessions) |
 
@@ -460,7 +464,11 @@ ctx.card(id: id, title: "Build finished", body: "no warnings left")  # replaces
 - `actions:` are up to 6 `{label:, command:}`. A command is a line the
   session runs as if the user typed it: `/hello again`, `/model x`, a
   plugin's own command. The web shows a button; the terminal shows
-  `→ /hello again`, to type.
+  `→ /hello again`, to type. A button's command leaves no echo: the web
+  sends it with `card: true` (`POST /api/sessions/:id/command`), its
+  `command_queued` and `command_ran` carry `card: true`, and no UI shows
+  its line; the web shows a bubble only when the command answers with
+  text or fails.
 - `level:` is `:info` or `:warn` (the warning colour).
 - `id:` names an earlier card to replace. Without one a new id is made. The
   web updates the card in place; the terminal prints it again, marked
@@ -748,6 +756,64 @@ Not caught (yet):
 - alternating calls (A, B, A, B) that each return something new;
 - thinking that goes in circles inside one long generation.
 
+## The check-in bundle
+
+`chi bundle install check-in` installs the bundle shipped with chi. It is
+written only against this API (`lib/samagotchi/bundles/check-in/plugin.rb`):
+`chi.on` hooks, `ctx.card`, `ctx.steer`, `ctx.stop_turn` and one anytime
+command. It has no memory file.
+
+A turn can run a long time on its own, reading and searching, without saying
+what it has found. check-in counts the turn's tool calls, and when there are
+`after` of them with no answer yet (then every `every` more) it checks in:
+
+- **`mode: ask`** (the default): a card, one per turn, updated in place at
+  each check-in: "50 tool calls, no answer yet", how long the turn has run
+  and its last few tools, and three actions:
+  - **Nudge** (`/checkin nudge`): puts `message` into the running turn
+    (`ctx.steer`); the model reads it at its next step and answers or says
+    what is left. Every UI shows `check-in> nudged: …`.
+  - **Keep going** (`/checkin later`): closes the card until the next
+    check-in.
+  - **Stop** (`/checkin stop`): stops the turn.
+
+  When the turn ends the card loses its actions ("The turn ended after N tool
+  calls"), so no stale buttons stay. In the attached terminal the actions are
+  `→ /checkin nudge` lines to type; the command runs beside the turn.
+- **`mode: nudge`**: nudges the model by itself, with a notice line.
+- **`mode: notify`**: a notice line only.
+
+The count is per turn: a new turn (a prompt, a continue, a reminder) starts
+from zero; steering merged into the running turn doesn't reset it. The polling
+tools are not counted. A nudge that arrives after the model's final answer is
+dropped (logged), never restarting a turn that is done; the card's "Nudged the
+model at N tool calls" then becomes "The answer came first; nudge not sent."
+
+```yaml
+# config.yml
+bundles:
+  check-in:
+    after: 50          # tool calls in one turn before the first check-in
+    every: 50          # then again every this many more
+    mode: ask          # ask | nudge | notify
+    message: "You've made {calls} tool calls in this turn without answering. Say briefly what you've found so far and what's left, then answer now or continue."
+    ignore_tools: [task_wait, task_get, delegate_result]
+```
+
+`{calls}` in `message` is the count. The default asks for what has been found
+and what is left, not "how's it going?": a small model tends to answer that
+with a line and carry on unchanged.
+
+`/checkin` (anytime) for this session, until its worker restarts:
+
+| | |
+|---|---|
+| `/checkin` | on or off, the mode, the threshold and this turn's count |
+| `/checkin on` / `off` | check in, or not |
+| `/checkin 30` | check in after 30 tool calls, then every 30 |
+| `/checkin mode ask` / `nudge` / `notify` | the mode |
+| `/checkin nudge` / `later` / `stop` | the card's actions, also by hand |
+
 ## Shutdown
 
 When the REPL exits, or a session's worker exits (an idle exit, `/exit`, a

data/docs/releasing.md

@@ -125,11 +125,21 @@ GitHub release as such (`gh release edit vX.Y.Z --prerelease` or edit its
 notes: "yanked: …"), add a `### Fixed` line under Unreleased, and release the
 next patch version.
 
-## Known CI gaps
-
-Some examples pass on macOS but fail on Linux CI. They carry `:ci_todo` and are
-skipped when `CI` is set: `chi send`/`chi note` subprocess specs (a child
-`ruby` without the bundle can't load nokogiri), `--all` on a peer list, the
-desktop fields in `chi self` (Linux has no helper), and KernelLoop's
-`send_note`. `spec/gem_contents_spec.rb` is skipped on Ruby 3.3 under CI
-(`Zlib::BufError` from `Gem::Package.build`). Fix these, then drop the tags.
+## CI on Linux
+
+The suite runs the same on Linux CI as on macOS, with no CI-only skips. A few
+things differ there, and a new spec that trips on them fails only on CI:
+
+- `CI` set marks every new session a test run, and `--all`, `list_sessions`
+  and friends leave test runs out. A spec that lists sessions makes them with
+  `test_run: false`.
+- The gems live under `vendor/bundle`: a child `ruby` started with a bare env
+  (`unsetenv_others: true`) needs `GEM_HOME`/`GEM_PATH` to find nokogiri.
+- Ruby 3.3's zlib raises `Zlib::BufError` when a thread interrupt lands in a
+  deflate (ruby/zlib#57, fixed in Ruby 3.4's zlib): build gems in a child
+  process, as `spec/gem_contents_spec.rb` does.
+
+To run it locally, use Docker with the Ruby build CI uses
+(`ruby-X.Y.Z-ubuntu-24.04-x64.tar.gz` from ruby/ruby-builder's releases) on
+`ubuntu:24.04` with `LANG=C.UTF-8`, `zip` and `git`, and run
+`CI=1 BUNDLE_PATH=… bundle exec rspec`.

data/docs/sessions.md

@@ -23,6 +23,8 @@ 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.
+
 **Lazy sweep:** automatic prune runs at most once per 24h on `GET /api/sessions` (Web). No background thread or cron. Manual prune is always available.
 
 **CLI:**
@@ -31,6 +33,8 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 chi sessions list [--sort updated_at|created_at] [--order desc|asc] [--limit N] [--scope=all]
 chi sessions list [--live] [--cwd PATH] [--limit N] [--format text|json|tsv] [--scope=all]
 chi sessions stop ID
+chi sessions archive ID...                            # hide from every list, keep for good; unarchive ID... undoes it
+chi sessions list --archived                          # archived sessions too, marked [archived]
 chi sessions delete [--force] ID...                    # for good; --force stops a live worker first
 chi sessions prune [--dry-run] [--days N] [--keep N] [--keep-status running,...] [--test-only]
 chi sessions clean [--dry-run] [--days N]             # test sessions: all, or older than N days
@@ -48,11 +52,11 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 
 `--dry-run` is the safe preview. Web has no prune endpoint; use the CLI.
 
-`chi sessions list` shows each session's saved recap, its first sentence without the "The user was…" opening (as on the web cards), in place of its last prompt, cut to 60 characters; a session with no recap shows its last prompt. A delegated session's row ends with `↳ <parent's short id>` (plain and `--live`; `--format json` has `parent_id`); rows keep their `updated_at` order, so a parent may be on another page than its children.
+`chi sessions list` shows each session's saved recap, its first sentence without the "The user was…" opening (as on the web cards), in place of its last prompt, cut to 60 characters; a session with no recap shows its last prompt. A delegated session's row ends with `↳ <parent's short id>` (plain and `--live`; `--format json` has `parent_id`); rows keep their `updated_at` order, so a parent may be on another page than its children. After the status, `ctx 12%` says how full the context was after the session's last counted turn (from its `analytics.json`; blank when no turn had a server count or the window is unknown; `ctx_pct` in `--format json`). The web's session cards show it quietly too (`12%`), and a session's ctx meter shows it on load, before its next turn streams.
 
 **Projects:** a session belongs to the git project it was started in: the repository, whichever worktree or subfolder of it (the same project root memories use). `chi sessions list` (with `--live` and `--format` too) and `chi web` show the current folder's project; `--scope=all` shows every session, and so does a folder in no repo (`~`). `--cwd PATH` is a folder filter instead of the project. The project is stored with the session (`project_root` in its JSON, `project` in `--format json`), so a session keeps it after its worktree is deleted; sessions older than that are placed by their folder, and one whose folder is gone shows in `--scope=all` only. Retention, `--resume`/`--attach ID`, `chi send`/`chi note ID` and `chi note --all` (every live session) are not scoped. The agent's `list_sessions` lists its own project's sessions; `cwd: "/"` lists every one.
 
-`--live`, `--cwd` and `--format` make `list` a picker for scripts (`SessionManager.session_summaries`): `--live` keeps the sessions a worker runs now (the owner lock, not the saved status; a session open in a plain REPL is left out), `--cwd PATH` those in PATH or below, and test runs are left out. `--live` shows 10 unless `--limit` says otherwise; filters apply before the limit. `--format json` prints `[{id, short_id, desc, cwd, updated_at, live, busy, owner, recap}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
+`--live`, `--cwd` and `--format` make `list` a picker for scripts (`SessionManager.session_summaries`): `--live` keeps the sessions a worker runs now (the owner lock, not the saved status; a session open in a plain REPL is left out), `--cwd PATH` those in PATH or below, and test runs are left out. `--live` shows 10 unless `--limit` says otherwise; filters apply before the limit. `--format json` prints `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap, parent_id, archived, scratch, ctx_pct}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
 
 ## Context notes
 
@@ -130,6 +134,26 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 
 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)`.
 
+### Starting a session
+
+`chi send --new` starts a new session with the message, the way the web start page does: a worker runs it, so it is in `chi web` and `chi sessions list` at once and streams live there; `chi --attach ID` joins it. `--wait` blocks until the answer and prints it, which makes it an agent's one-shot the user can watch (unlike `chi -p … --non-interactive`, which runs in-process and saves the session only at the end).
+
+```sh
+chi send --new -m "review the diff on feat/x"          # prints "<id>  started", returns at once
+git diff | chi send --new -m "review this"             # stdin is quoted context, as above
+chi send --new --wait -m "review the diff on feat/x"   # blocks; stdout is the answer
+chi send --wait -m "and the tests?" 3fa2               # a follow-up in the same session, waits too
+chi send --wait 3fa2                                   # sends nothing: waits for its next reply
+```
+
+- `--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 or a guardrail approval), with the line `waiting for an answer: …; open it: chi --attach ID or the web`, and the session keeps waiting; 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, the session was stopped, or `--timeout S` passed; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
+- `--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 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 guardrail ask until someone opens it; left alone it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
+
 ## Delegating
 
 The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; nothing checks the host serves it, so an unknown one fails the child's first turn). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail like an `execute` result. Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (a `↳` chip on its card, `delegated by` in its info bar, listed right after its parent in the all-sessions view) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
@@ -144,12 +168,14 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 **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, `host:model ▾`) chooses the model a new chat starts on: `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 browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`.
-- 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), `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`). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
+- 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, `host:model ▾`) chooses the model a new chat starts on: `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`.
+- 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`). 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).
 
 **Test-session hygiene:**
 
 - New sessions set `test_run:true` when `SAMAGOTCHI_ENV=test` or `RACK_ENV=test` or `CI` is set (explicit flag, `metadata_version` 2). Old sessions without the flag load as `test_run:false`.
 - Test runs are tagged and obey the same retention. `chi sessions clean` deletes every test session whatever its age (`--days N`: only those older than N days); a live worker or a `keep_status` status still keeps one. `chi sessions prune --test-only` applies the usual age and count rules to test sessions only.
+- A `chi scratch` session (`"scratch": true`) is deleted when its REPL ends; one a killed process left behind is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it. `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
 - For ad-hoc manual QA use `SAMAGOTCHI_ENV=test XDG_STATE_HOME=/tmp/chi-test-$USER chi ...` to isolate from real state; the flag also marks sessions that `chi web` or an attached `chi` spawn (their workers inherit the environment), so `clean` finds them if they land in the real state.

data/lib/samagotchi/answer_display.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "log"
+
+module Samagotchi
+  # How a turn's answer is shown, apart from what the model said: an
+  # after_turn hook (or a plugin's on(:after_turn)) calls event[:present]
+  # with a block that gets the current display text and returns the new
+  # one. The result is kept as `display` on the answer's model message in
+  # session.json; the web renders it instead of `content`. It is display
+  # only: nothing that talks to a model reads it (the payload builders take
+  # the fields they send, and the copies handed to hooks, plugins and the
+  # recap leave it out, see .strip).
+  #
+  # The target is the stored conversation's last message when it is the
+  # model's answer; a turn that ended any other way (cancelled, failed,
+  # empty: a turn note is last) has none and event[:present] does nothing.
+  class AnswerDisplay
+    KEY = :display
+    # A display text longer than this is refused (the display stays as it
+    # was): a hook must not bloat session.json or the page.
+    MAX_CHARS = 200_000
+
+    # A message as a model-facing reader may see it: without `display`.
+    # The same object when it has none.
+    def self.strip(message)
+      return message unless message.is_a?(Hash) && (message.key?(KEY) || message.key?(KEY.to_s))
+
+      message.reject { |key, _| key.to_s == KEY.to_s }
+    end
+
+    def self.strip_all(messages)
+      Array(messages).map { |message| strip(message) }
+    end
+
+    # @return [Hash, nil] the message event[:present] changes
+    attr_reader :target
+    # @return [String, nil] the display text so far
+    attr_reader :text
+
+    # @param messages [Array<Hash>] the conversation the turn stored
+    def initialize(messages)
+      last = Array(messages).last
+      @target = last if last.is_a?(Hash) && field(last, :role).to_s == "model"
+      @original = @target && (field(@target, KEY) || field(@target, :content)).to_s
+      @text = @original
+    end
+
+    # True when a hook set a display text other than what was shown before.
+    def changed?
+      !@target.nil? && @text != @original
+    end
+
+    # event[:present]: call it with a block; the block gets the current
+    # display text (the answer's content until a hook changed it) and
+    # returns the new one. A block that raises, returns something other than
+    # a String, or returns more than MAX_CHARS leaves the text unchanged
+    # (logged, named by event[:hook]).
+    # @param event [Hash] the after_turn event (for its :hook label)
+    # @return [Proc] returns the display text after the call, or nil when
+    #   the turn has no answer to present
+    def presenter(event)
+      lambda do |&block|
+        next nil unless @target
+        next @text unless block
+
+        apply(block, event[:hook])
+      end
+    end
+
+    private
+
+    def apply(block, hook)
+      value = begin
+        block.call(@text.dup)
+      rescue StandardError => e
+        return reject(hook, "raised #{e.class}: #{e.message}")
+      end
+      return reject(hook, "returned #{value.class}, not a String") unless value.is_a?(String)
+      return reject(hook, "returned #{value.length} characters (max #{MAX_CHARS})") if value.length > MAX_CHARS
+
+      @text = value.dup
+    end
+
+    def reject(hook, why)
+      Log.warn(:hooks, "present_rejected", echo: "[samagotchi:hooks] #{hook}: present #{why}; display unchanged",
+                                           hook: hook.to_s)
+      @text
+    end
+
+    def field(message, key)
+      message.key?(key) ? message[key] : message[key.to_s]
+    end
+  end
+end

data/lib/samagotchi/archive_store.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+
+require_relative "session"
+
+module Samagotchi
+  # A session's archive marker, <session dir>/archived (JSON):
+  #   {"archived_at": t}    archived: hidden from every list, kept by the
+  #                         retention sweep, not counted in its max_count
+  #   {"unarchived_at": t}  archived once, then unarchived: the sweep ages
+  #                         the session from max(updated_at, unarchived_at)
+  # A separate file, not a session.json field: Session#save rewrites that
+  # file from memory (and bumps updated_at) at every turn.
+  module ArchiveStore
+    FILE = "archived"
+    # Input a human typed: a web tab, a chi TUI, `chi send`, and nil (a
+    # worker's initial prompt; a web client may send none). Delegates,
+    # plugins and reminders are not (an allowlist, so a new automatic
+    # origin stays out).
+    USER_CLIENT_PREFIXES = %w[web: tui:].freeze
+    USER_CLIENT_IDS = ["cli:send"].freeze
+
+    # @return [Hash, nil] the marker (string keys), nil when none or unreadable
+    def self.read(session_dir)
+      data = JSON.parse(File.read(File.join(session_dir, FILE)))
+      data.is_a?(Hash) ? data : nil
+    rescue StandardError
+      nil
+    end
+
+    def self.archived?(session_dir)
+      read(session_dir)&.key?("archived_at") == true
+    end
+
+    # @return [Time, nil] when the session was last unarchived
+    def self.unarchived_at(session_dir)
+      value = read(session_dir)&.fetch("unarchived_at", nil)
+      value && Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    # @return [Boolean] whether the marker was written (false: the session
+    #   file is gone, so its dir is never recreated)
+    def self.archive(session_id, state_dir:)
+      write(session_id, { "archived_at" => Time.now.iso8601(3) }, state_dir: state_dir)
+    end
+
+    # @return [Boolean] whether it was archived (and is not now)
+    def self.unarchive(session_id, state_dir:)
+      return false unless archived?(Session.session_dir(session_id, state_dir: state_dir))
+
+      write(session_id, { "unarchived_at" => Time.now.iso8601(3) }, state_dir: state_dir)
+    end
+
+    # Whether +client_id+ (a turn's origin) is a human's input.
+    def self.user_input?(client_id)
+      return true if client_id.nil?
+
+      id = client_id.to_s
+      USER_CLIENT_IDS.include?(id) || USER_CLIENT_PREFIXES.any? { |prefix| id.start_with?(prefix) }
+    end
+
+    # A human's input came into the session: it is back in the lists. Its
+    # children stay archived. Never raises.
+    # @return [Boolean] whether it was archived
+    def self.user_input(session_id, state_dir:)
+      return false if session_id.nil?
+
+      unarchive(session_id, state_dir: state_dir)
+    rescue StandardError
+      false
+    end
+
+    def self.write(session_id, record, state_dir:)
+      return false unless File.exist?(File.join(state_dir, "#{session_id}#{Session::FILE_EXT}"))
+
+      dir = Session.session_dir(session_id, state_dir: state_dir)
+      FileUtils.mkdir_p(dir)
+      path = File.join(dir, FILE)
+      File.write("#{path}.tmp", JSON.generate(record))
+      File.rename("#{path}.tmp", path)
+      true
+    end
+    private_class_method :write
+  end
+end