samagotchi 0.2.0 → 0.4.0

data/docs/hooks.md

@@ -50,7 +50,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 |-------|--------------|---------------|
 | `:session_start` | First turn of the session | `{ type: :session_start, session_id: "..." }` |
 | `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), messages: [...] (the history before this turn) }` |
-| `:after_turn` | After a turn completed or was cancelled (not after one that failed) | `{ type: :after_turn, status: "completed" \| "canceled", messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
+| `:after_turn` | After a turn completed or was cancelled (not after one that failed) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
 | `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
 | `:after_generation` | After LLM returns (both loops) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
@@ -59,7 +59,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 
 Every event also carries the hook runtime (next section): `hook:` (the label
 of the hook about to run) and the callables `notify:`, `ask_user:`,
-`stop_turn:`.
+`stop_turn:`, `steer:`.
 
 `messages:` is a **read-only copy**: a frozen array of copied message hashes
 (`{role:, content:, …}`). A hook that mutates it, or its strings, gets
@@ -69,8 +69,8 @@ cheap).
 ## What a hook can do: the runtime
 
 Besides reading (and, on `:before_tool_call`, voting on) its event, a hook
-can talk to the user through three callables the registry puts on every
-event:
+can talk to the user, and to the running turn, through four callables the
+registry puts on every event:
 
 ```ruby
 class Watchful
@@ -94,6 +94,14 @@ class Watchful
       # that call, and the rest of the batch is denied; from :after_turn or
       # :session_end it does nothing (false).
       event[:stop_turn].call("too many iterations without progress") if event[:iteration] > 20
+    when :after_tool_call
+      # Put text into the running turn, as the user's steering does: at the
+      # loop's next boundary it joins the conversation as its own user
+      # message, and every UI shows a nudge line ("<bundle> nudged: …").
+      # True when queued; false with no turn, and from :after_turn or
+      # :session_end. A steer that arrives after the model's final answer is
+      # dropped (logged), not merged: it never keeps a finished turn going.
+      event[:steer].call("Say briefly what you have found so far.") if event[:iteration] == 30
     end
   end
 end
@@ -103,11 +111,55 @@ end
 known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
+A steer is saved in the session as `{role: "user", kind: "steer", source:
+"<bundle>", content: "…"}`; the model reads only its text, as a user turn.
+Its `source` is the hook's bundle (a config or turn hook's label otherwise).
+
 Timing: a notice from `:after_turn` or `:session_end` shows after the turn's
 end line. A question from `:before_tool_call` shows **before** the tool
 line (the gate runs first), so its text should name the call. The notices
 are also logged (`turn` tag, `hook_notice`).
 
+## Presenting the answer (display only)
+
+`:after_turn` carries one more callable, `present:`. It changes how the
+turn's answer is **shown**, never what the model said: the block gets the
+current display text (the answer's content until a hook changed it) and
+returns the new one.
+
+```ruby
+class Shout
+  def call(event)
+    return unless event[:type] == :after_turn
+
+    event[:present].call { |text| text.gsub(/\bTODO\b/, "**TODO**") }
+  end
+end
+```
+
+- The result is kept as `display` on the answer's model message in the
+  session file. The model never sees it: the prompts and chat requests take
+  the fields they send, and the copies of the conversation given to hooks
+  (`messages:`), plugins (`ctx.messages`) and the recap leave it out.
+- Calls chain in hook order (bundle hooks by priority, then config hooks,
+  then turn hooks): each block gets what the one before returned. The call
+  returns the display text after it.
+- A block that raises, returns something other than a String, or returns
+  more than 200 000 characters leaves the display as it was (logged as
+  `present_rejected` with the hook's label).
+- It works on the stored conversation's last message only when that is the
+  model's answer: after a cancelled, failed or empty turn there is none, and
+  the call returns nil without running the block.
+- **The web** renders `display` instead of the answer (markdown, sanitised
+  like every answer: raw HTML is escaped, only http(s)/mailto links are
+  kept), on a live turn and after a reload. Its copy button copies the
+  display text. The page learns about it from an `answer_display` event
+  that comes after `turn_completed` (the hooks run after the turn ended).
+- **Terminals** (the REPL, the attached TUI) have printed the answer by then
+  and do not change it; use `event[:notify]` for something they should show.
+
+A plugin gets the same from `chi.on(:after_turn) { |event, ctx| event[:present].call { … } }`.
+
 ## Settings
 
 A hook class whose `initialize` takes an argument gets its settings: **one
@@ -299,7 +351,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md).
-- Shipped bundles: `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) and `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)).
+- Shipped bundles: `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)) and `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:
@@ -307,3 +359,154 @@ Lifecycle:
 - `chi bundle install <source>` copies `hooks/*.rb` to `~/.config/samagotchi/memories/.bundles/<name>/hooks/` and persists metadata + `trust_level` + `source_commit` (git HEAD) to provenance.
 - `Engine.new` loads `config.yml` hooks first, then bundle hooks via `Provenance.each_installed_holding_hooks` → `Hooks::BundleLoader.load`. Bundle hooks are process-scoped (they survive the per-turn `clear_hooks`; only plain hooks are cleared). Experimental bundles emit a one-line startup warning.
 - `chi bundle status`, `diff`, `uninstall`, `build` are hook-aware (counts, metadata, removal).
+
+## The source-links bundle
+
+```sh
+chi bundle install source-links
+```
+
+installs one `after_turn` hook and a short memory. When the model's answer
+mentions a known source ref — a JIRA ticket, a GitHub issue, an internal
+wiki page — the web links it in the answer (below), and every UI shows one
+line right after the message:
+
+```
+sources: JIRA JIRA-123 → https://myjira.com/browse/JIRA-123, JIRA JIRA-10 → https://myjira.com/browse/JIRA-10
+```
+
+The note is **not part of the conversation**: it is an event shown to the
+user, never stored in the session file. A UI replays it while the session's
+worker lives (a page reload keeps it; a stopped worker loses it). Only the
+model's final answer is scanned (the last `role: "model"` message), and only
+the first 20 000 characters of it. A ref that is already a link is skipped —
+inside a bare URL (`https://x.com/JIRA-123`), in a markdown link's target, or
+in a markdown link's label when the target names the same ref
+(`[JIRA-123](https://x.com/JIRA-123)`) — while `see https://x.com JIRA-123`
+and `[fix for JIRA-123](https://github.com/o/r/pull/9)` still link. A ref
+glued to URL punctuation (`/browse/JIRA-1`, `?key=JIRA-1`, `JIRA-1/foo`) is
+skipped too; `Ticket:JIRA-5` and `#JIRA-123` are ordinary plain text and do
+link. The line names each URL once (compared case-insensitively: `#12` and
+`dm1try/samagotchi#12` may be one issue, and with `case_insensitive: true`
+`JIRA-1` and `jira-1` are one ticket), in first-occurrence order, whatever
+order the sources are configured in. With no sources configured the hook is a
+silent no-op.
+
+```yaml
+bundles:
+  source-links:
+    sources:
+      - name: JIRA
+        prefix: JIRA              # simple form: \bJIRA-(\d+)\b
+        base_url: https://myjira.com/browse/
+      - name: GitHub
+        pattern: '\bGH-(\d+)\b'   # full form: a regex
+        url: 'https://github.com/org/repo/issues/{match}'
+        case_insensitive: false   # optional, default false
+    max: 10                       # optional: refs per line, default 10
+    note: false                   # optional: no sources line, default true
+```
+
+**In the web** the refs are also links in the answer itself: each
+occurrence becomes `[JIRA-123](https://myjira.com/browse/JIRA-123)` through
+[`event[:present]`](#presenting-the-answer-display-only), so the model's
+text stays as it was, and the links survive a reload and a stopped worker
+(they are the answer's `display` in the session file). The same skip rules
+apply, and a ref in code (a `` `span` `` or a fenced block) or anywhere in a
+markdown link is left as it is; past the first 20 000 characters the answer
+is unchanged. The terminals see only the line; `note: false` drops it and
+keeps the web links.
+
+The `prefix:` form compiles to `\b<prefix>-(\d+)\b` and the URL is
+`base_url` + the full ref text (`JIRA-123`). The `pattern:` form takes a
+regex and a `url:` template with placeholders (below). `case_insensitive:
+true` adds the `/i` flag. Past `max` refs the line ends with `… +N more`.
+
+Each regex is compiled with a per-regex timeout (0.5 s, per match attempt),
+so a catastrophic pattern is abandoned instead of hanging the turn: that
+source is skipped whole (its partial matches are discarded) with a warning,
+and the others still report. An entry with neither `prefix:` nor `pattern:`,
+or a pattern that does not compile, is skipped with a warning at load. The
+hook is `on_error: log`: a bug in it warns and the turn is unaffected. As with
+every bundle hook, a running worker picks it up after its next start.
+
+### Placeholders, and the project's own repo
+
+A `url:` template (the `pattern:` form only; `base_url:` is always
+`base_url` + the ref) can use:
+
+| placeholder | value | when it can't be filled |
+|---|---|---|
+| `{match}` | the first capture group, else the whole ref | never: it falls back to the ref |
+| `{1}` … `{9}` | a numbered capture group | the group didn't take part: the ref is **not linked** |
+| `{name}` | a named capture group `(?<name>…)` | the group didn't take part: **not linked** |
+| `{repo}`, `{host}` | the named group `repo` / `host` when the pattern has one and it took part; else the project's git remote | neither: **not linked** |
+
+A ref with a placeholder that can't be filled is left out of both the line
+and the answer: no URL is built with a hole in it (another source on the same
+ref can still link it). A `{word}` or `{N}` that is none of the above (not a
+group of the pattern, or `{7}` in a two-group pattern) stays as literal text,
+with one warning when the source is loaded. Every value is percent-encoded
+(everything outside `A-Za-z0-9-._~`, `/` included), except that `{repo}`
+keeps its `/` between segments (GitLab's `group/sub/proj`); a `{repo}` with an
+empty, `.` or `..` segment counts as unfilled.
+
+So one source links both `#12` in this project and a cross-repo ref:
+
+```yaml
+bundles:
+  source-links:
+    sources:
+      - name: GitHub
+        # `#12` → this project's repo; `owner/repo#12` → that repo
+        pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w))?#(?<num>\d+)\b'
+        url: 'https://github.com/{repo}/issues/{num}'
+        remote_host: github.com
+```
+
+```
+sources: GitHub #12 → https://github.com/dm1try/samagotchi/issues/12, GitHub rails/rails#5 → https://github.com/rails/rails/issues/5
+```
+
+GitHub redirects `/issues/N` to `/pull/N` and back, so one URL covers issues
+and pull requests. The lookbehind keeps `&#123;`, `x/#1` and a partial
+`b/c#1` inside `a/b/c#1` out; code and URLs are skipped as always. `PR #12`
+links, `PR#12` doesn't (a `#` right after a letter). The pattern is loose on
+purpose: a bare `#\d+` also matches "step #2", and `and/or#5` or `TCP/IP#3`
+read as qualified refs. A stricter variant wants `PR #`, `issue #` or a
+qualified ref:
+
+```yaml
+        pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w)#|\b(?:PR|[Ii]ssue) #)(?<num>\d+)\b'
+```
+
+**Where `{repo}` and `{host}` come from.** Without a named group that took
+part, they come from `git remote get-url <remote>` run in the session's
+working directory (the worker's; the in-process REPL's is the terminal's
+current directory). `remote:` picks the remote, default `origin` — a fork
+sets `remote: upstream`. Git applies `insteadOf` rewrites and includes, and a
+worktree reports its main repo's remote. The URL forms understood are
+`https://`, `http://`, `ssh://`, `git://` (credentials and port dropped) and
+scp-like `[user@]host:owner/repo`; the repo is the path without a trailing
+`.git` or `/`. A local path, `file://`, no git, no repo or no such remote
+leaves the ref unlinked, silently (a debug log line only). Git is asked only
+when a hit needs it — a JIRA source or a qualified ref never runs it — and
+the answer, even "none", is remembered for the worker's life: a remote
+changed mid-session counts after the worker's next start.
+
+`remote_host:` (a host or a list, compared case-insensitively) applies the
+remote-derived links only when the remote's host is one of them, so a
+`https://github.com/{repo}/…` template never points a GitLab project's `#12`
+at github.com. A qualified ref is linked whatever the local remote is. An SSH
+alias (`git@github-work:o/r.git` from a multi-account `~/.ssh/config`) or an
+`insteadOf` mirror reports its own host; list it too:
+`remote_host: [github.com, github-work]`.
+
+Two Ruby regex notes. With named groups in a pattern, a plain `(…)` doesn't
+capture and gets no number, so `{1}` is the first *named* group, and so is
+`{match}` (in the example above `{match}` is the repo part): use either named
+or numbered groups in one pattern, and named placeholders with named groups.
+And a pattern with a `host` (or `repo`) group lets the model's text choose the
+link's domain (or repo): the escaping rules out URL injection, but the choice
+of the target is the model's.
+

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

@@ -15,13 +15,13 @@ can run the whole release; the user approves the notes before the tag and the
 - **Every other shipped bundle** (btw, guardrails, known-names, loop-guard,
   mcp) has its own semver in its `manifest.yml` and, when it needs a newer chi,
   a `requires_chi:` line. They never upgrade by themselves: users run
-  `chi bundle upgrade NAME`. So:
+  `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`
     (`rake bundles:check` fails otherwise, once there's a tag to compare with);
   - a bundle that uses something new in chi raises its `requires_chi` in the
     same change; `release:bump` never touches `requires_chi`;
-  - the release notes list the `chi bundle upgrade NAME` steps for every
-    bundle whose version moved.
+  - the release notes say "run `chi update`" and name the bundles whose
+    version moved (what changed in each), not per-bundle upgrade steps.
 - Pre-1.0: config and commands may change in a minor version (0.2 → 0.3); a
   patch version (0.2.0 → 0.2.1) is fixes only.
 
@@ -58,9 +58,9 @@ The agent does each step and stops where the user has to say yes.
 1. **Start from main, up to date and green.** `git checkout main && git pull`;
    CI on main is green.
 2. **Draft the notes.** `bundle exec rake release:draft_changelog`, then edit
-   `## [Unreleased]` in CHANGELOG.md into short user-facing lines. Add the
-   `chi bundle upgrade NAME` steps for bundles whose version moved since the
-   last tag (`git diff vPREV -- lib/samagotchi/bundles/*/manifest.yml`).
+   `## [Unreleased]` in CHANGELOG.md into short user-facing lines. End with
+   "Update with `chi update`", naming the bundles whose version moved since
+   the last tag (`git diff vPREV -- lib/samagotchi/bundles/*/manifest.yml`).
    Pick the version: fixes only → patch, anything else → minor.
 3. **The user approves the notes and the version.** Show them the section.
 4. **Bump.** `bundle exec rake "release:bump[X.Y.Z]"`, review `git diff`.
@@ -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
+## CI on Linux
 
-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.
+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,26 @@ 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`).
+
+**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 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.
 
 ## Context notes
 
@@ -116,8 +135,9 @@ cancel during its thinking, it said it had never been asked.
 `chi send` is the other half of `chi note`: the text goes in as your message, the same as typing it in the attached terminal or the web composer, so a turn runs.
 
 ```sh
-chi send [-m TEXT] (ID|PREFIX)...
+chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
 chi send -m "is this the same bug?" 3fa2           # a message
+chi send --image shot.png -m "why is this red?" 3fa2  # with an image
 pbpaste | chi send -m "is this the same bug?" 3fa2  # the clipboard quoted above the message
 pbpaste | chi send 3fa2                             # the clipboard is the message
 ```
@@ -126,10 +146,31 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 - It goes through the same path as the web composer (`SessionManager.deliver_turn`): the worker's Bridge when it is up, so every attached UI shows it as your message (client id `cli:send`, shown like any user message); the input file when the worker is on its way out. During a running turn it is merged into that turn at the next step, like a message typed then.
 - 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`).
-- One line per session: `sent`, `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`.
+- `--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 is a usage error (exit 2) and nothing is sent. 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: a text-only one fails the turn in the session (the line here still says `sent`). 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`.
 
 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.
@@ -140,16 +181,3 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - Every child starts with the shipped `delegated` system memory preloaded (`preloaded_memory_names: ["system/delegated"]`; `--mute delegated` would hide it): put everything in the final reply, don't delegate further, don't write memories or change config, stay in the folder. Its system prompt also says `Delegated by session <parent id>`. The parent's own `--mute` list does not carry over.
 - Limits: a child cannot `delegate` (depth 1; the tool refuses), and one session may have at most `session.max_children` (default `4`, env `SAMAGOTCHI_SESSION_MAX_CHILDREN`) children running at a time, counted from the session files (a finished or idle-exited child does not count; one whose worker is still starting does, for 15 s). A refused call creates no session. Nothing stops children with the parent: `chi sessions stop ID` does.
 - The link is the session's `parent_id`, written before the worker starts, so a respawn keeps it; `GET /api/sessions` and `/api/sessions/:id` carry it, and `SessionManager.children_of` lists a parent's children.
-
-**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`).
-- 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.
-- 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.