samagotchi 0.141.0 → 0.143.0

data/docs/sessions.md

@@ -1,6 +1,6 @@
 # Sessions
 
-Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `written_by` (the chi version that saved it last; see *Which chi a worker runs*), `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
+Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)). Its keys are in [the Session file table](#session-file). A file from before `used_memory_names`, `preloaded_memory_names`, `muted_memory_names`, `parent_id` or `continues` reads those as empty lists, no parent and no previous link.
 
 **Message times:** an entry of `messages` may carry `at`, when it happened: a local-offset ISO time with milliseconds (`2026-10-24T14:32:05.120+02:00`). User prompts, lines merged into a turn and steers, reminders, context and task notes, and the model's replies have one (a note's is its `created_at`); tool results, `!cmd` messages and chi's own turn notes don't, nor does anything saved before chi stamped messages (no backfill). It is for the UIs only (the gap dividers, a bubble's time): it never goes to the model, so it changes nothing in the requests or their prompt cache. The one time the model reads is the reminders': due reminders go into a turn as a system message headed `[SYSTEM: REMINDERS DUE 2026-10-24 14:32 local]` (the turn's local time; `ReminderQueue#inject!`), written into the saved content then, so a later request sends the same text.
 
@@ -45,6 +45,8 @@ A new session field (the rule in `Session::FIELDS`' comment): only top-level key
 
 <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. Typed while a turn runs, `/archive` waits for the turn's end (an attached terminal for the commands queued behind it too) and then archives. `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 the `archived` toggle beside 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 `continue → · archive · stop · delete` (`unarchive` on an archived one; no `continue →` on a link continued already, see *Session chains*; `continue →` is a plain button like `archive`, in the accent on an archived session, where it is the thing to do); archiving the open session stays on it, with an Undo toast.
 
+**System 1's saved runs** last as long as sessions: the sweep ages them by day file, and deleting a session purges its runs ([system-one.md](system-one.md)).
+
 **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.
 
 <a id="cli"></a>**CLI:**
@@ -111,6 +113,51 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 - 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.
 
+## Session file
+
+`Session::FIELDS` is the table of `<uuid>.json`, in the order `Session#save` writes it (`Session.from_h` and `#to_h` both go by it; 41 keys). A key a file lacks reads as the default below; `review`, `first_turn_id`, `verdicts` and `verify_fresh` are written only when set (`OPTIONAL_FIELDS`). A key this chi doesn't know is kept and written back as it was (see the rule above). "Who writes it": the Engine runs in the session's worker (or the REPL); the rest are named.
+
+| Key | Meaning | Written by |
+|-----|---------|------------|
+| `metadata_version` | The file format version (`METADATA_VERSION`, 3). | `Session#save` |
+| `written_by` | The chi version that saved the file last (see *Which chi a worker runs*). | `Session#save` |
+| `id` | The uuid; also the file name. Required. | `Session.new_session` |
+| `mode` | `assist`, the only mode. Required. | `SessionManager.spawn_session` |
+| `model_name` | The resolved model ref (an alias applied; `host:id` when it names a host), so a resume keeps the model. Required. | creation, `/model` |
+| `model_typed` | The name it was typed as when that differs (an alias), for the `models:` lookup after a resume; `null` otherwise. | creation, `/model` |
+| `working_directory` | The folder the session runs in. Required. | creation |
+| `messages` | The conversation (symbol keys in memory, strings on disk). While a turn runs, a save writes the turn's checkpoint here instead (`TurnCheckpoint`). | the Engine, per turn |
+| `created_at`, `updated_at` | ISO times; `updated_at` is stamped by every save and orders the lists. Required. | `Session#save` |
+| `status` | `idle`, `running`, `error` or `stopped` (turn state, not liveness; a stop is also the `<id>/stopped` marker). | the worker / Engine; the marker by `chi sessions stop` |
+| `last_prompt` | The newest prompt; a session created with a first prompt holds it here until its worker takes it; after an `error` status, the reason. | `SessionManager.spawn_session`, the Engine, `Session.mark_error` |
+| `first_preview` | The first user message as a one-line preview (whitespace collapsed, 80 characters), or the first context note's (`note: …`) until a message is typed. Cached so lists and `Session.resolve_id`'s ambiguity message need not read `messages`. | `Session#save` (`compute_first_preview!`) |
+| `title` | The name the user gave (`/title`, whitespace collapsed, 80 characters); shown in place of `first_preview` (`display_title`); a continue's new link inherits it. The recap's auto title is not stored here. See [Session titles](#session-titles). | `/title` (`TitleCommand`), `SessionManager` |
+| `test_run` | Tagged by `SAMAGOTCHI_ENV=test`, `RACK_ENV=test` or `CI` (see Test-session hygiene). | creation |
+| `pending_question` | The question the worker waits on (`PendingQuestion`), `null` with none. | `QuestionDesk` |
+| `used_memory_names` | The memories the session read. | the Engine |
+| `project_root` | The project the session started in, stored because a worktree may be deleted later; `null` outside a repo. | creation |
+| `preloaded_memory_names`, `muted_memory_names` | `--memory` and `--mute`, written before the worker starts so a respawn builds the same prompt. | creation |
+| `prompt_notes` | The model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)). | the Engine, at each prompt build |
+| `parent_id` | The session that delegated this one or forked it (`ctx.sessions.fork`); `null` otherwise. See [Delegating](#delegating). | `SessionManager.spawn_session`; `ChildMove` writes a `parent.json` beside it instead of this file |
+| `scratch` | A `chi scratch` session, deleted when its REPL ends. | creation |
+| `last_turn` | How the last turn ended (`LastTurn`), for a parent's wait and the web's notifications. | the Engine, at a turn's end |
+| `verdicts` | Verdict cards recorded by completed Verify turns, in append order. | `Engine#record_verdict`, `VerifyFresh` |
+| `delegate` | Started by the `delegate` tool (a fork has a `parent_id` but isn't one). | `Tools::Delegate` via `spawn_session` |
+| `llm_context` | The session's own LLM context values (strategy, apply rule, budget), over the model's; `null` with none. | creation (`--llm-context`), `/llm-context`; copied by a fork and a continue, not a delegate child |
+| `continues` | The previous link of a chain; `null` otherwise. See [Session chains](#session-chains). | `SessionContinue` |
+| `thinking` | The session's own thinking level (`off`/`low`/`medium`/`high`), over the process default and the model's. | creation (`--thinking`), `/thinking`; kept by a continue and a fork |
+| `reasoning_history` | Its own `reasoning_history` level (`drop`/`turn`/`all`). | `/reasoning-history`; carried like `thinking` |
+| `appended_prompt_files` | The absolute paths of the files `--append-system-prompt` put into the system prompt (config.yml's `append_system_prompt:` entries are not stored); kept by respawns, copied by a fork and a continue (`SessionSetup`). | creation |
+| `toolkit` | The toolkit it was created on, as named (`{name, add, remove}`); `null` is `full`. See [Toolkits](configuration.md#toolkits). | creation, `/toolkit` |
+| `toolkit_origin` | Why it is on that kit: `default`, `chosen` (also the reading of a file from before the field), `inherited` or `suggested`. | creation, `/toolkit`, the toolkit suggestion |
+| `bundle_settings`, `config_settings` | `--set`: `BUNDLE.KEY` values by bundle and the session-settable core keys; kept by a respawn, a continue and a fork, not by a delegate child. | creation |
+| `interrupted_turn` | The mark of a turn a worker checkpointed and never finished (`InterruptedTurn`); the next worker settles it and sets it to `null`. | the worker |
+| `parent_answers` | Its own `guardrails.parent_answers` (it may only tighten config.yml's). | creation (`--parent-answers`), `/parent-answers` |
+| `working_set_pins` | The working-set items the user pinned (`/working-set pin`); kept by a respawn, a continue and a fork. | the Engine's command |
+| `review` | A review session's subjects and source (`SessionReview`), see [Review sessions](#review-sessions). | `ReviewStart` |
+| `first_turn_id` | The id the creating prompt's turn gets, so a wait can name it (`chi send --new --wait`, `--wait --turn T ID`); `null` for a session created idle. | `SessionManager.spawn_session` |
+| `verify_fresh` | A Verify fresh child's requester, rules and claim (`VerifyFreshOrigin`). | `VerifyFresh.start`, once |
+
 ## Context notes
 
 A context note is text pushed into a session as background: not a prompt, and it starts no turn.
@@ -311,30 +358,7 @@ sessions](cli.md#review-sessions)); both start idle and print the `chi share` li
 
 ## Toolkits
 
-A session file's `toolkit` (`{"name", "add", "remove"}`) is the toolkit it was created on, as named: config's
-`toolkit.default`, `toolkit.child` for a delegate child, or `chi --toolkit` / `chi send --new --toolkit` (with
-`--tool` / `--no-tool`). It is never resolved again from config: a respawned or woken worker declares the same
-tools. `null` (a session from before toolkits) is `full`. A continue (`continue →`, `chi send --new --continues`)
-and a fork (`ctx.sessions.fork`) keep it, as they keep the thinking level; a delegate child gets the kit its
-`delegate` call names (`toolkit:`, any kit the parent knows) or `toolkit.child`; one its worker can't resolve
-declares every tool (full). The file stores only the name: a kit's tools and prompt text come from its definition.
-`/toolkit` changes it, saved at once, from the next turn's start. See
-[Toolkits](configuration.md#toolkits).
-
-`toolkit_origin` records why the session is on that kit: `default` for the configured kit, `chosen` for a
-user-selected kit (including `/toolkit` and `ctx.use_toolkit`), `inherited` for a continue or fork, or `suggested`
-when `toolkit.suggest.mode: on` switched it ([Toolkits](configuration.md#toolkits)). A session file from before the
-field reads as `chosen`. Only a `default` session is ever suggested a kit.
-
-A `find_tools` result on a chat host saves the tools its hit loads as `loaded: ["list_sessions", "mcp_fs_read"]` on
-its `tool_response` entry (wire names: a built-in's, an MCP tool's `mcp_<server>_<tool>`), whatever the host: a
-later turn on `api: anthropic` (after a `/model` switch, a resume) sends the load as references, any other host
-ignores it. The names stay deferred for the session's life, across respawns, `--resume` and forks.
-
-A plugin's `ctx.load_tools` leaves a system entry `{"role": "system", "kind": "tool_change", "content": "[tools loaded:
-delegate (bundle)]", "tool_change": {"add": ["delegate"], "by": "bundle"}}` after the turn's user message, only on a
-host that takes tool changes (`api: anthropic`). It is never the system head, counts as conversation, is hidden in
-the web and TUI histories, and goes to no other wire; its names stay deferred for the session's life like a load's.
+A session's `toolkit` and `toolkit_origin` are in the [Session file](#session-file) table. What a toolkit is, how it is saved at creation, what a continue, a fork and a delegate child get, `/toolkit`, and how `find_tools` loads and `ctx.load_tools` tool changes are saved in the conversation: [Toolkits](configuration.md#toolkits).
 
 ## Parent answers
 
@@ -425,7 +449,7 @@ mise.toml pins Ruby 3.4 gets that `ruby`, `gem` and `bundle` in its tools while
 
 ## 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; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). 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 above 64 KB (`DelegateWait.cut`); a reply longer than `max_tool_output_chars` keeps its start and its end (the conclusion), with a gap line naming that `output/` file, where the whole reply is (`ToolOutputCut`'s `:head_tail_ref`; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `↑ <parent id>` in its info bar, its tooltip `delegated by session …`; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) 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.
+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; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). 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 above 64 KB (`DelegateWait.cut`); a reply longer than `max_tool_output_chars` keeps its start and its end (the conclusion), with a gap line naming that `output/` file, where the whole reply is (`ToolOutputCut`'s `:head_tail_ref`; see [Tool output guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)). Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `↑ <parent id>` in its info bar, its tooltip `delegated by session …`; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) 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.
 
 - `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one. The wait (`wait: true`, a later `delegate_result`) and the delegate report are for the reply of the child's turn the follow-up went to: its running turn, which it merges into, or the turn of its own it runs when the child is idle (`turn` in `delegates.json`, set when the child's worker names `turn_ids`), not a newer reply of a turn queued behind it. A follow-up merged as a steer into a turn the child started at that moment (a wake, a reminder, another message) gets that turn's reply or question. A child on its first turn, or with an older worker, gives its next reply, as before.
 - `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's.
@@ -434,7 +458,7 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - A wait that timed out or was canceled still gets its delegate report: neither moves the parent's cursor, so the child's reply comes as a report when its turn ends. The result says so (`chi brings its reply here by itself as a delegate report …`; with `queue`, that it joins the next step or turn) and that `delegate_result` waits again only if the turn needs the reply now. A parent that gets no reports (`session.delegate_reports: off`, a `--no-shared` REPL, `--non-interactive`) is told `delegate_result <id> waits again` instead, and `wait: false`'s result says `delegate_result waits for its reply`.
 - What a wait returns, `session: <id>` then `status:` and the text, with the status words `chi send --wait --format json` uses: `answered` with the reply after a `---` line; `question` as soon as the child opens a question (the model's own, or a hook's), with the question's text, options and the `chi answer` command for it (nothing is answered for it: `chi answer`, attach or use the web, then wait again); `failed`, `canceled` or `no_answer` when the child's turn ended with nothing to say (its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `worker_gone` when the child has had no worker for 15 seconds (it crashed without saying so, or idle-exited): `delegate` with `session:` starts it again; `running` on timeout, or when the parent's own turn is canceled (the child keeps running; the next turn can wait again). A reply saved before the child's worker idle-exited is returned at once.
 - **A child's step-limit question goes back to the parent model**, not to its user: `delegate_result` returns `status: question` with the `chi answer` commands for Continue and Stop, and says the model may instead send a narrower follow-up (`delegate session:`, which drops the question) or report back. A parent's `chi answer` follows `guardrails.parent_answers`, or the child's own when stricter (`hard`: Stop only; see [chi as a sub-agent](sub-agent.md#the-step-limit)).
-- **A child at its cost cap** (the [cost-cap bundle](plugins.md#the-cost-cap-bundle), the child's own cap: `child:` in its settings, or `/cap`) asks a `hook` question, "Cost cap", `Continue` or `Stop`. Like every hook's question on a `delegate` child, it goes where it can be decided, under the child's `guardrails.parent_answers` (config.yml's, or the child's own when stricter): when the parent may pick an option other than a deny (Stop) there, `standard` and `soft` here, it comes back to the parent's model as `status: question` with the `chi answer` commands; when it may not, `hard` here (a parent's Continue is refused), it goes to the parent's user as a card, as approvals do (the relay below), and the model sees one line: `hook question relayed to your user: Cost cap → Stop` (or `dismissed`, which the hook reads as it likes, cost-cap as Stop; `refused by the child …`, `answered on the child`, `still open (your turn was stopped)`). Free text alone doesn't count as an option the parent may pick. A **background** child (`wait: false`) paused at its cap rings its parent as a question does (delegate reports, below): the parent's model gets it as a report when it may answer; otherwise the parent's worker relays it to its user at its next step boundary, or in a wake turn's first boundary when idle (before the model is called), and the report the model gets is the outcome line. While that card is open the parent's turn waits on it; a Stop closes it and leaves the question for your next input (or a `delegate_result`): no wake turn offers that question again meanwhile, while other children's reports and attached-context wakes go on. Under the default `soft` that means a background parent's model now hears its child's cost cap, and may Continue it.
+- **A child at its cost cap** (the [cost-cap bundle](bundles.md#the-cost-cap-bundle), the child's own cap: `child:` in its settings, or `/cap`) asks a `hook` question, "Cost cap", `Continue` or `Stop`. Like every hook's question on a `delegate` child, it goes where it can be decided, under the child's `guardrails.parent_answers` (config.yml's, or the child's own when stricter): when the parent may pick an option other than a deny (Stop) there, `standard` and `soft` here, it comes back to the parent's model as `status: question` with the `chi answer` commands; when it may not, `hard` here (a parent's Continue is refused), it goes to the parent's user as a card, as approvals do (the relay below), and the model sees one line: `hook question relayed to your user: Cost cap → Stop` (or `dismissed`, which the hook reads as it likes, cost-cap as Stop; `refused by the child …`, `answered on the child`, `still open (your turn was stopped)`). Free text alone doesn't count as an option the parent may pick. A **background** child (`wait: false`) paused at its cap rings its parent as a question does (delegate reports, below): the parent's model gets it as a report when it may answer; otherwise the parent's worker relays it to its user at its next step boundary, or in a wake turn's first boundary when idle (before the model is called), and the report the model gets is the outcome line. While that card is open the parent's turn waits on it; a Stop closes it and leaves the question for your next input (or a `delegate_result`): no wake turn offers that question again meanwhile, while other children's reports and attached-context wakes go on. Under the default `soft` that means a background parent's model now hears its child's cost cap, and may Continue it.
 - **A child's approvals go to the parent's user** (the approval relay), and so do the hook questions its parent can't usefully answer (above: a card headed `delegate ab12 asks: Cost cap`, the child's options and kind, no approval facts). While the parent waits (`delegate`, `delegate_result`), a guardrail approval the child opens reopens as the parent session's own approval: the same card in the parent's web page and attached terminal, with the same facts and diff, a line naming the delegate and its task (`delegate ab12 · fix the flaky spec…`, linked to its session) and the header `Approve delegate ab12's tool call?`. The options are the child's, by index; "for the session" says it is the delegate's session (the session scope keys on the child; repo and rule approvals are one shared store). The user answers once there; the parent's model never sees the approval, only one line per relayed approval in the tool's result, before the reply: `approval relayed to your user: execute: git push origin main → allowed once` (or `denied ("why")`, `dismissed (denied)`, `answered on the child`, `not delivered (the child's worker is gone)`, `refused by the child …`, `still open (your turn was stopped)`). The time the card is open doesn't count against `timeout`. While the parent waits on one child, its other running children's approvals are relayed too, oldest first, one card at a time (`+1 more delegate waiting`); each outcome comes in that child's next result.
   - The child's own card stays answerable (the first answer wins: answered there, the parent's card closes as "answered in ab12"). While relayed it says `Waiting for approval in parent ab12: answering here works too`; `chi sessions list` shows the child as `waiting (in parent ab12)` (`--format json`: `relayed_to`), and the web's bell rings for the parent's card, not the child's.
   - How the child trusts it: the parent's POST that says "answered" (Bridge `POST /session/<child>/relay`) carries no answer. The child asks its parent session's live Bridge (`POST /session/<parent>/relay/status`), which reports only what the parent's question flow took from a UI (`RelayDesk`, in memory only), and takes it only for this child, the question pending now, answered. A parent agent's answer on the relay card (a piped or marked `chi --attach PARENT`, `chi answer`) is held to `guardrails.parent_answers` (each session's own, when stricter) by the parent and again by the child.

data/docs/sub-agent.md

@@ -24,10 +24,10 @@ parent's setting, then to the child's.
 
 The other direction, chi sending a part of its work to a Claude Code session
 you already work with (to validate, as context, or with a question), is the
-[claude-peer bundle](plugins.md#the-claude-peer-bundle): Claude pairs with the
+[claude-peer bundle](bundles.md#the-claude-peer-bundle): Claude pairs with the
 chi session, chi's `claude_send` tool or `/claude` writes to Claude's inbox,
 and Claude's answer comes back as attached context. The
-[codex-peer bundle](plugins.md#the-codex-peer-bundle) does the same with a
+[codex-peer bundle](bundles.md#the-codex-peer-bundle) does the same with a
 Codex CLI session (`codex_send`, `/codex`, through `codex queue`). The peer's
 answers wake chi in a short loop (fix or disagree, send again) until it says
 `VERDICT OK` (one closing wake: chi carries on or tells you what was agreed)
@@ -45,10 +45,10 @@ chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--f
 chi answer ID --question QID --dismiss [--timeout S] [--format json]
 ```
 
-A child with a bundle setting of its own, such as a $ cap (the [cost-cap bundle](plugins.md#the-cost-cap-bundle)):
+A child with a bundle setting of its own, such as a $ cap (the [cost-cap bundle](bundles.md#the-cost-cap-bundle)):
 `chi send --new --wait --format json --set cost-cap.cap=3 -m "task"`. At the cap the wait exits 3 with the cost-cap
 question; `chi answer ID --question QID --option Continue` (or `Stop`) answers it. A cap on the child's work across
-its turns (the [work-cap bundle](plugins.md#the-work-cap-bundle)), the bound a parent that keeps answering the step
+its turns (the [work-cap bundle](bundles.md#the-work-cap-bundle)), the bound a parent that keeps answering the step
 limit's Continue doesn't otherwise have: `--set work-cap.tool_calls=400` (or `work-cap.minutes=60`, active minutes).
 
 `chi answer` waits after answering, the same way `chi send --wait` does, so the
@@ -124,10 +124,10 @@ A chi parent's `delegate_result` gets a child's step-limit question back as a
 `delegate session:` (which drops the question), or report back. It isn't
 relayed to the parent's user the way approvals are.
 
-A session at its cost cap (the [cost-cap bundle](plugins.md#the-cost-cap-bundle)) waits the same way, as a
+A session at its cost cap (the [cost-cap bundle](bundles.md#the-cost-cap-bundle)) waits the same way, as a
 question of kind `hook` with header "Cost cap" and options `Continue` and `Stop`: `--option Continue` raises the cap
 by another cap's worth and the turn goes on, `--option Stop` ends it `canceled` with `stopped_by: cost-cap`. A session at its work cap (the
-[work-cap bundle](plugins.md#the-work-cap-bundle)) asks the same, header "Work cap", the question naming the
+[work-cap bundle](bundles.md#the-work-cap-bundle)) asks the same, header "Work cap", the question naming the
 session's totals (`Work cap reached: 412 tool calls of 400 (6 turns, 47 min active, $1.20). Continue raises it to
 800.`); `stopped_by: work-cap` on Stop.
 

data/docs/system-one.md

@@ -0,0 +1,122 @@
+# System 1's saved runs
+
+System 1 is the cheap judgment model chi asks small questions: approvals
+([guardrails.md](guardrails.md#system-1-experimental)), toolkit suggestions
+([configuration.md](configuration.md#toolkits)), context candidates
+([context.md](context.md)) and bundles' own ([plugins.md](plugins.md#judgments-chijudgment-and-ctxjudge)). Each use keeps its own mode, gates and log. What they share is
+one host (`system_one.host`, `.model`, `.timeout_ms`) and one layer that saves every ask, so a later comparison or fine-tune has what
+was sent and what came of it. The runs don't leave the machine; a hosted System 1 host sees each state as it is asked.
+
+## The common layer
+
+`SystemOne::Client` asks. `SystemOne::Recording` wraps it where a use builds its
+client (`Engine#system_one_recording`): the same duck type, the same answers and
+the same raises. A cancelled ask saves its run, then raises; a run that can't be saved is
+one warn and never changes the answer. A use that needs the run's id at once passes it
+(`client.ask(..., run_id: id)`); one client serves several threads.
+
+| Judgment | Asked by | Later lines |
+|---|---|---|
+| `approvals.allow` | `GuardrailWiring#system_one_judge` | gates, acted (the judgment line's decision), labels |
+| `toolkit.suggest` | `ToolkitSuggest.judge` | acted (the log's `did`), no labels |
+| `context.candidate` | `ContextJudge.ask` | labels |
+| `<bundle>.<name>` | `SystemOne::Judgments` (`ctx.judge`, `ctx.judge_later`) | the bundle's: labels, acted |
+
+Not saved: a toolkit warm-up (it goes straight to the backend), `chi guardrails replay`,
+chi web's availability check, a scratch session's asks or anything about them, and a participant's turn (never judged by core; a bundle's ask there still goes, unsaved).
+An owner's turn in a review session is judged, so it is saved. Test runs are saved with `test_run: true`.
+
+## Bundles' judgments
+
+A bundle declares a judgment with `chi.judgment` and asks through `SystemOne::Judgments`, the Engine's (`Plugin::Host#judgments`), on the
+same `Client` and `Recording`: the API is in [plugins.md](plugins.md#judgments-chijudgment-and-ctxjudge), the settings in
+[configuration.md](configuration.md#bundles-judgments).
+
+Only bundles' judgments have settings of their own (`JudgmentSettings`). Core's take no host, model or mode here, whatever
+`system_one.judgments` says: `Record` and `Similar` are model-blind (`Record#initialize` filters by rule only), so a model swapped
+for approvals alone would inherit a clean record and could auto-allow. Before any such swap, `Record` and `Similar` have to go by model.
+
+Core's uses keep their own threads (`ToolkitSuggest::Pending`, `ContextJudge`, the approval path) and contention; only the ask-and-save
+seam is common. A bundle's `judge_later` runs on the Engine's `SideJudgments` under its full name as the kind, so `SideJudgments#join`
+at shutdown covers it, and a run cut by that one-second limit is lost. Its asks stay out of the session's spend, as all of System 1's do, and no
+cost cap covers them on a hosted host.
+
+## The store
+
+`<state dir>/system_one/runs/<judgment>/YYYY-MM-DD.jsonl` (`SystemOne::RunsStore`): one file per UTC day,
+0600 in 0700 folders, one append under `flock` per line. Each judgment's questions are stored
+once per digest pair in `versions.jsonl` beside them.
+
+A line over 16 KB has its state cut, as a string, and is marked `truncated`.
+
+Agents can't write here: `write`, `edit` and `memory_write` are denied (`system-one-runs`), a shell
+command naming the folder is `touches: chi_dirs`, and it is in `ChiDirs.protected`, so only the user
+may answer an ask about it. A label here may one day train a model.
+
+### What a run holds
+
+A `run` line: `id`, `judgment`, `at`, `instructions_digest`, `criteria_digest`, `state` as sent, `asked`,
+`origin` (`live`), `mode` (the use's own: toolkit and context build an `on` client in audit too),
+`host`, `model` (resolved), `served_model`, `answers` (raw, as the backend sent them), `usage`,
+`failure` and `failure_text`, `latency_ms`, `session_id`, `chain_link`, `session_model`, `test_run`, `truncated`.
+Nil fields are left out. A bundle's run may add `positive` and `negative`, the label values it declared.
+
+A skipped ask is a run too, written at once: `asked: false` and `skipped` (`busy`: a `judge_later` whose last one still
+runs), with its state, host and model but no answers, so a later replay can answer it.
+
+**That means prompts, commands, diffs and any secret in them are in these files.** A state is whatever the
+use sends System 1: an approval's command (up to 2000 chars), diff and earlier examples, a toolkit's
+first prompt, a context candidate's owner prompts. **check-in's sends tool output** — the calls of a turn
+since its last check-in, each cut as it is captured, and what each tool returned — the first class of data
+approvals and context never send: on a hosted `system_one.host` it reaches that host with the ask, so a
+hosted System 1 sees the machine's tool output, not just what the agent asked about.
+
+`chain_link` is the session's parent, else the session it continues. It isn't the chain's root: following a
+chain takes a session listing (`SessionChain`), too slow on an approval's path. An export splitting by chain
+follows the links.
+
+A run's id is `<judgment>/<uuid>`, carrying its judgment. Approvals use it as the judgment line's id in
+`judgments.jsonl`, so `verdict.judgment[:id]` and `/guardrails wrong` carry it with no new field; toolkit's
+and context's log lines have it as `run_id`. An id from before runs names no judgment and labels no run.
+
+### Later lines
+
+Later lines name their run by `run_id` and may sit in a later day's file, or in theory before
+the run: a join happens at read, and a line whose run is gone is dropped.
+
+- `label` {`value`, `by`, `strength`, `question`, `at`}.
+  - Approvals (`SystemOne::ApprovalLabel`, the one reading of an answer for the log and the run):
+    `allow_once`, `allow_wide`, `deny` by `user`, strong; `should_have_asked` from `/guardrails wrong` or the
+    web's **should have asked**, strong; `deny` by `parent`, weak, only where the parent could have allowed; a
+    parent's allow is no label; `none` for a cancelled ask, which is not an answer.
+  - Context: `attached`, `declined` by `command` (`/context attach|decline`, the card's buttons), `declined`,
+    `detached` by `user` (a removal seen at an owner turn's start), on the latest `judged` line's run, question
+    `about`. A chip removed after the last turn isn't seen, and an attach by hand is no label.
+  - Toolkit has none: `did: chosen` doesn't say what was picked. "Covers" stays derived in `chi toolkit report`.
+  - A bundle's: its own word, raw, by `<bundle>` or `<bundle>:<what>`, through `ctx.judgments.label`. A bundle reaches only its own runs.
+    check-in's are the card's actions that took effect (`nudge`, `keep_going`, `stop`, weak — a Nudge asks for a status, not a
+    verdict, and Keep going may be habit) and `turn_stopped` by `turn` when the turn ended with the card still open.
+- `acted` {`what`, `at`}: approvals' decision (`auto`, `asked`, `audit`), toolkit's `did`, a bundle's own word.
+- `gates` {`rule`, `rule_listed`, `self_protect_refused`, `threshold`, `at`}: approvals', at ask time,
+  since neither can be recomputed later.
+
+Labels are biased, and a later comparison must handle it: an auto-allowed call has no answer unless
+flagged, and a stored wide approval never reaches the judge at all.
+
+## Retention and deleting
+
+Runs last as long as sessions. The session sweep deletes day files older than `session.retention_days` (0: forever),
+then the oldest until the total is under 100 MB; today's stay. A judgment with no day file left loses its folder.
+
+`chi sessions delete` (and the web's delete, and `/exit --delete`) purges that session's runs and their later lines; a sweep
+doesn't, and neither does discarding a session its worker left empty. A purge can't reach text a later run of another session
+embedded: an approval's state carries earlier asks as examples.
+
+To stop saving: `system_one.runs: off` in config.yml (what's there still ages out). To delete it all:
+`rm -rf <state dir>/system_one`.
+
+## Looking at it
+
+`chi judgments ls` lists each judgment's digests, runs, labels (each run's last, per question), failures, models and size. `chi judgments report NAME
+[--days N]` gives one judgment's counts, p histogram and labels by value (each run's last, per question). Both only read.
+A use's own report stays: `chi context report`, `chi toolkit report`, `/guardrails`.

data/docs/testing.md

@@ -40,6 +40,8 @@ that way locally: `npx playwright run-server --port 3333`, then `PW_TEST_CONNECT
 
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
+`SAMAGOTCHI_TAILSCALE_CLI` points at a file that does not exist (`spec_helper.rb`), so no spec reaches a real `tailscale`; a
+`chi web --tunnel tailscale` spec writes a fake one and sets the variable.
 
 Goldens (`*_golden_spec.rb`, the prompt snapshots) hold no machine state, so they pass on any runner: no absolute
 paths (replace them with placeholders), no PATH tools (the suite pins `rg` as found, `spec_helper.rb`; an example
@@ -194,7 +196,7 @@ callback the spec can wait on), not another local fix in the spec.
 ### Talking to a real Bridge
 
 A session's Bridge answers only a request that names its secret (`X-Chi-Bridge`, from the worker's `bridge.json`;
-see [architecture.md](architecture.md)). A spec that writes its own request to a real Bridge (`Net::HTTP`, a raw
+see [internals/bridge.md](internals/bridge.md)). A spec that writes its own request to a real Bridge (`Net::HTTP`, a raw
 socket) names it too: `include BridgeAuth` (spec/support/bridge_auth.rb, required by the spec that needs it) gives
 `bridge_auth(session_dir_or_sidecar)`, the header as a Hash, and `bridge_auth_line(...)` for a raw request; or read
 `port` and `secret` from the sidecar in one go, as `WorkerLink.client` does. A client made with `BridgeClient.new`

data/lib/samagotchi/bridge.rb

@@ -23,6 +23,7 @@ require_relative "bridge/turn_accumulator"
 require_relative "session"
 require_relative "engine"
 require_relative "system_one/log"
+require_relative "system_one/approval_label"
 require_relative "session_commands"
 require_relative "queued_command"
 require_relative "steer"
@@ -815,6 +816,7 @@ module Samagotchi
       return [{}, 409, { error: "already_labelled" }] unless entry["answer"].nil?
       return [{}, 500, { error: "label_failed", detail: "could not write the System 1 label" }] unless log.label(judgment_id, "should_have_asked")
 
+      SystemOne::ApprovalLabel.save(SystemOne::Runs.for_sessions_dir(@state_dir), judgment_id, SystemOne::ApprovalLabel::WRONG)
       [{}, 200, { status: "labelled", id: judgment_id }]
     end
 

data/lib/samagotchi/bundle_command/api_calls.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../config"
+require_relative "../version"
+require_relative "../plugin/api"
+require_relative "../plugin/context"
+
+module Samagotchi
+  class BundleCommand
+    # What a plugin's source calls of the plugin API, read with Prism
+    # (`chi bundle check`'s `api` and `requires-chi-floor`). The classes are
+    # the source of truth: a name is checked against their public methods
+    # and a keyword against the method's parameters, so nothing here lists
+    # the API. It sees only calls written on a local `ctx` or `chi` itself
+    # (ctx.sessions.nope; not `s = ctx.sessions; s.nope`): a miss, never a
+    # false alarm, is what a variable costs.
+    class ApiCalls
+      # A call that isn't there, or a keyword its method doesn't take.
+      Finding = Data.define(:line, :message, :fix)
+
+      # What each API object's member gives: the only list here, of the
+      # objects behind a call (their names and keywords are their classes').
+      # Resolved on use: Sessions alone loads ~150 files.
+      MEMBERS = {
+        "Plugin::Api" => { ctx: "Plugin::Context" },
+        "Plugin::Context" => { sessions: "Plugin::Sessions", context: "Plugin::AttachedContext", http: "Plugin::Http",
+                               judgments: "Plugin::Judgments", cost: "SessionMetrics::Cost", usage: "SessionMetrics::Usage",
+                               log: "Plugin::Context::Logger" }
+      }.freeze
+      ROOTS = { ctx: "Plugin::Context", chi: "Plugin::Api" }.freeze
+
+      def initialize(source)
+        @result = Prism.parse(source)
+        @nodes = []
+        return unless @result.success?
+
+        queue = [@result.value]
+        while (node = queue.pop)
+          @nodes << node
+          queue.concat(node.compact_child_nodes)
+        end
+        @nodes.sort_by! { |node| node.location.start_offset }
+      end
+
+      # Each call's keywords, as "chi.toolkit(groups:)": the call's receiver
+      # as written, its name and the keyword (with or without parens, over
+      # lines). Nothing when the source doesn't parse.
+      # @return [Array<String>]
+      def keywords
+        calls.flat_map do |node|
+          next [] unless node.receiver && node.arguments
+
+          keyword_names(node).map { |keyword| "#{node.receiver.slice}.#{node.name}(#{keyword}:)" }
+        end
+      end
+
+      # What the source calls that this chi's API lacks, in source order.
+      # Nothing when it doesn't parse (the install's error says so). A name
+      # the source guards with respond_to? is a newer chi's, on purpose.
+      # @return [Array<Finding>]
+      def findings
+        calls.filter_map do |node|
+          owner = owner_of(node.receiver) or next
+          klass = class_named(owner)
+          if klass.public_method_defined?(node.name)
+            keyword_finding(node, klass)
+          elsif !guarded?(node.name)
+            missing_call(node, klass)
+          end
+        end
+      end
+
+      private
+
+      def calls = @nodes.grep(Prism::CallNode)
+
+      # The API class +receiver+ is an instance of, by how it is written, or nil.
+      def owner_of(receiver)
+        case receiver
+        when Prism::LocalVariableReadNode then ROOTS[receiver.name] unless shadowed?(receiver.name)
+        when Prism::CallNode then MEMBERS.dig(owner_of(receiver.receiver), receiver.name)
+        end
+      end
+
+      # A local ctx or chi the plugin set to anything but chi.ctx isn't the API.
+      def shadowed?(name)
+        @nodes.grep(Prism::LocalVariableWriteNode).any? { |write| write.name == name && write.value.slice != "chi.ctx" }
+      end
+
+      def guarded?(name)
+        calls.any? do |node|
+          next false unless node.name == :respond_to? && owner_of(node.receiver)
+
+          first = node.arguments&.arguments&.first
+          first.respond_to?(:unescaped) && first.unescaped == name.to_s
+        end
+      end
+
+      def class_named(name) = Samagotchi.const_get(name)
+
+      def missing_call(node, klass)
+        near = Config.near_names(node.name.to_s, klass.public_instance_methods(false).map(&:to_s)).first
+        call = "#{node.receiver.slice}.#{node.name}"
+        fix = near ? "did you mean #{node.receiver.slice}.#{near}? docs/plugins.md has the API" : "docs/plugins.md has the API"
+        Finding.new(line: node.location.start_line, message: "#{call} isn't in chi #{VERSION}'s plugin API", fix: fix)
+      end
+
+      # One Finding, the first keyword the method doesn't take. A method with
+      # no keywords takes a hash as an argument; one with ** takes any.
+      def keyword_finding(node, klass)
+        parameters = klass.instance_method(node.name).parameters
+        return nil if parameters.any? { |kind, _| kind == :keyrest }
+
+        taken = parameters.filter_map { |kind, name| name if %i[key keyreq].include?(kind) }.map(&:to_s)
+        return nil if taken.empty?
+
+        unknown = keyword_names(node).find { |keyword| !taken.include?(keyword) } or return nil
+        near = Config.near_names(unknown, taken).first
+        takes = "it takes #{taken.map { |name| "#{name}:" }.join(", ")}"
+        Finding.new(line: node.location.start_line, message: "#{node.receiver.slice}.#{node.name} takes no #{unknown}: in chi #{VERSION}",
+                    fix: near ? "did you mean #{near}:? #{takes}" : takes)
+      end
+
+      def keyword_names(node)
+        Array(node.arguments&.arguments).grep(Prism::KeywordHashNode).flat_map do |hash|
+          hash.elements.filter_map { |pair| pair.key.unescaped if pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode) }
+        end
+      end
+    end
+  end
+end