samagotchi 0.141.0 → 0.142.0

data/docs/memory.md

@@ -225,7 +225,7 @@ memory's line are left out), so their size is paid on every request. Nothing cap
 or trims them; chi measures them (tokens estimated as characters /
 `context.chars_per_token`) and shows the size:
 
-- `chi self` has a `memory index` row:
+- `chi self` has a `memory index` row (and a `big memories` row, see [A memory's size](#a-memorys-size)):
   `system ~2.0k tokens (54 lines), project ~1.4k tokens (35 lines)`, with
   `, over 2500` inside the parentheses for a scope over
   `memory.index_warn_tokens`.
@@ -252,6 +252,36 @@ may each get it. Bundle installs and uninstalls and hand edits
 change index lines without a note; `chi self`'s row shows where an index
 stands.
 
+## A memory's size
+
+`memory_read` returns a memory whole: `max_tool_output_chars` does not cut it (see [Tool output
+guardrails](internals/tool-output-limits.md#the-runners-cut-max_tool_output_chars)), so each read of a memory pays its
+size. Two limits stay:
+
+- `memory.read_max_chars` (default `0`, no fixed cap) caps a `memory_read` result at that many characters.
+- An overflow guard: with that at 0 and a known context window, a result over half the window is cut. A context
+  overflow fails the turn and rolls its work back, and a retry repeats the read. With an unknown window there is no guard.
+  It checks one result, not the context already used.
+
+A cut result ends with `[cut: N of M chars; the rest is in the memory's .md file in <dir>: read it with start_line]`;
+`read` the file with `start_line` for the rest.
+
+`memory.entry_warn_tokens` (default `5000`, about 20K characters at the default `context.chars_per_token`; `0` turns it
+off) is the size a write may take one memory to before the model is told. When a `memory_write` with content, or a
+`write`/`edit` on a memory file, takes a memory from at or under the limit to over it, the tool result ends with one note
+(a memory that did not exist counts as 0, so a first big write gets it):
+
+> Note: memory 'NAME' is now ~N tokens (over memory.entry_warn_tokens 5000), paid on each read. When you next have a moment, tighten it; split out only parts that are read separately, since each new memory adds an index line to every prompt. Don't remove or merge memories unless the user asks.
+
+Once per crossing, as the index's note: a write while the memory is already over gets none. None for a
+description-only write, a remove, the verbatim `index` write, a model overlay, a `model_notes_*` memory (it has its own
+warning), a bundle install or a hand edit. It is independent of `memory.index_warn_tokens`: with that at 0 this note
+still comes, and a write that crosses both has both notes. Nothing is said when a memory is read: that would repeat on
+every read. `chi self` has a `big memories` row instead: the memories over the limit in both scopes, largest first
+(5, then `+N more`), `none` when there are none, a bundle's tagged `from <bundle>` (the shipped
+`config_modification_protocol` is over on every install; the fix is upstream's). This is how a
+memory already over the limit gets seen.
+
 ## Skills
 
 A **skill** is a memory named `skill_<name>` that holds the steps of a

data/docs/plugins.md

@@ -787,6 +787,11 @@ file can't make itself a peer's, and uninstalling the bundle ends it.
 Subclasses of `Samagotchi::Plugin::Peer` (below) declare their `OUTBOX`
 source. Needs chi 0.67.0 (guard it with `chi.respond_to?(:peer_source)`).
 
+### `chi.judgment(name, questions:, positive: nil, negative: nil, shared_host: :skip)`
+
+A cheap System 1 question this bundle asks with `ctx.judge` or `ctx.judge_later`: see
+[Judgments](#judgments-chijudgment-and-ctxjudge).
+
 ### `chi.ctx`
 
 The plugin's context (the `ctx` its handlers get), for `register` itself:
@@ -844,6 +849,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason; true when it stopped one now. In a `:before_tool_call` block it also denies that call |
 | `ctx.stop_generation(reason)` | cut the generation that is streaming: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
 | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
+| `ctx.judge(name, state:)`, `ctx.judge_later(name, state:) { |result| … }`, `ctx.judgments` | a cheap System 1 question this bundle declared, saved as a run: see [Judgments](#judgments-chijudgment-and-ctxjudge) |
 | `ctx.http` | an HTTP client for calling services (`get`, `post_json`, `request`): see [Calling services](#calling-services-ctxhttp) |
 | `ctx.sessions` | fork, send to, read, list and stop other sessions: see [Other sessions](#other-sessions-ctxsessions) |
 | `ctx.toolkit` | the name of the session's toolkit (`full` for a session from before toolkits); nil with no session |
@@ -983,6 +989,104 @@ Each call counts in the session's side requests, under the bundle's name: `/stat
 web's ctx tooltip (`2 (btw 1, recap 1) · …`), with its tokens and its cost (reported, else estimated from the target
 model's price), never in the session's own totals.
 
+## Judgments: `chi.judgment` and `ctx.judge`
+
+A judgment is a small question for [System 1](system-one.md), the cheap judgment model: a yes/no with a probability, a
+choice, or a score, in about the time a tool call takes. Where `ctx.ask_model` gets free text from the session's model,
+a judgment gets a number from the model the user set for this, and every ask is saved, so a later comparison or
+fine-tune has what was sent and what came of it. It is chi's own layer (approvals use the same `Client` and runs) and
+gives a bundle no new power. Needs chi 0.142.0 (guard it with `chi.respond_to?(:judgment)`).
+
+```ruby
+def register(chi)
+  chi.judgment "progress", questions: { "progress" => { type: "noul", instructions: "Is this turn still making progress?" } },
+                           positive: "keep_going", negative: "stop", shared_host: :skip
+
+  chi.on(:after_tool_call) do |_event, ctx|
+    @run = ctx.judge_later("progress", state: { prompt: @prompt, calls: @calls }) do |result|
+      next if result.no_judgment? || result.audit?
+
+      ctx.notify("this turn looks stuck") if result.p < 0.2
+    end
+  end
+
+  chi.command("/going", "Say the turn is fine") do |_args, ctx|
+    ctx.judgments.label(@run, "keep_going", by: "command")
+    nil
+  end
+end
+```
+
+**It is off until the user says so.** The full name is `<bundle>.<name>` (`check-in.progress`), and it asks nothing until
+config.yml's [`system_one.judgments`](configuration.md#bundles-judgments) gives it a mode, `audit` or `on`, which it can
+also give a host and a model of its own. Neither `audit` nor `on` changes anything by itself: `result.audit?` is the bundle's
+to honour (in audit, look and don't act). A full name is dot-separated words of a-z, 0-9, `_` and `-`, so a bundle whose
+name has a capital or a dot fails to load on this call. `approvals`, `context`, `guardrails` and `toolkit` as a first word and
+`.replay` at the end are core's.
+
+`chi.judgment`:
+
+- `questions:` is a map of id to `{type:, instructions:, criteria:}`: `"noul"`, `"choice"` (criteria: `{name => description or
+  nil}`) or `"score"` (criteria: a list of levels). Or a callable given `ctx`, called at each ask, where they vary per
+  session. A plain map is checked when declared, a bad one failing the plugin's load; a callable's result at each ask, raising there.
+- `positive:` and `negative:` name the label values that say the answer was right and wrong (a word or a list). They
+  are saved in each run for a later comparison, and don't limit `label`.
+- `shared_host:` says what to do while a turn runs on the same local server (the same `hosts:` entry or the same URL
+  root, and not a remote one), where an ask evicts the turn's cached prompt: `:skip`, the default, saves the run with `asked: false`, so a
+  later replay can answer it; `:ask` asks anyway. Between turns and on a remote host, it asks either way. A turn's hooks count as in the
+  turn, `:after_turn` and `:session_end` too: an ask there would still evict the prefix the next turn wants.
+
+`ctx.judge(name, state:)` asks and waits, at most `system_one.timeout_ms`. `name` is as declared, without the bundle.
+`state:` is a String, Hash or Array: what the question is about, sent to the System 1 host and saved as sent (bytes that
+aren't UTF-8 replaced). It stops when the turn is stopped, as `ctx.http` does. **It returns a Result, and doesn't raise for
+anything that goes wrong on the way:**
+
+| On the Result | |
+|---|---|
+| `no_judgment?` | no answers |
+| `answers` | `{id => answer}`: `.noul`, `.choice`, `.score` (a score is the probability-weighted level index, not a level number), `.level` (the name of the most likely level, when the response has a legend), `.confidence`, `.probabilities` |
+| `p(id)` | a `noul` question's probability of yes (nil for no answer, or another type); no id: the only question's |
+| `audit?`, `mode` | the judgment's mode: `"off"`, `"audit"` or `"on"` |
+| `run_id` | for `ctx.judgments`; nil when no run was saved |
+| `reason` | why there's no answer, below; nil with answers |
+
+| `reason` | When | A run? |
+|---|---|---|
+| `:off` | no mode set | no |
+| `:no_host` | no `system_one.host`, nor one of its own, or a config still on the moved `guardrails.system_one` keys | no |
+| `:no_session` | no session bound yet | no |
+| `:failed` | the host couldn't be reached, timed out, refused, or sent something unusable | yes, with `failure` |
+| `:cancelled` | the turn was stopped during the ask | yes, with `failure: "cancelled"` |
+| `:shared_host` | `shared_host: :skip`, and a turn is running on it | yes, `asked: false` |
+| `:busy` | `judge_later` only: this judgment's last one still runs | yes, `asked: false` |
+
+An undeclared name or a bad `state:` (not a String, Hash or Array, or nested too deep) raises `ArgumentError`, as `ask_model` does for a bad model, and so does `ctx.judge` in a
+`:generation_progress` handler, whose stream it would hold.
+
+`ctx.judge_later(name, state:) { |result| … }` asks on its own thread and **returns the run's id at once** (nil when no run will be
+saved). One per judgment runs at a time. The block is optional, and gets the Result once, on another thread, however
+the ask went, also when nothing was asked. A block that raises is logged.
+
+- **The block's `ctx.*` act on the session as it is then**, not as the handler's event: the turn may have ended, or the
+  worker moved to another session. Compare `ctx.session_id` with the one you started from before acting.
+- A `judge_later` still running when chi shuts down gets a second, then it and its run are lost. On `chi -p
+  --non-interactive` this is the usual end of a slow ask.
+- Snapshot what you need: the block sees only what it closes over.
+
+`ctx.judgments.label(run_id, value, by: nil, strength: nil, question: nil)` saves what came of a run, as a later line on it;
+`ctx.judgments.acted(run_id, what)` saves what the bundle did about it. Both return whether they saved anything. `value`
+and `what` are the bundle's own words (up to 200 characters), mapped only at analysis. `by:` says what said it, always after
+the bundle's name (`check-in:card`). `strength:` is `"strong"` (the user said so) or `"weak"` (they may have clicked out of habit).
+A `nil` id saves nothing and isn't an error, so a run that wasn't saved needs no check; an id of anything this bundle didn't declare raises `ArgumentError`.
+
+**What's saved.** A run holds the state as sent: prompts, commands and whatever else the bundle put there, in the
+user's state dir, for as long as sessions last ([System 1's saved runs](system-one.md)). Nothing is saved for a scratch
+session or in a participant's turn, later lines included (those asks still go to the host). `system_one.runs: off` stops all of it.
+
+**Cost.** A judgment stays out of the session's spend, as all of System 1's do, and **a bundle's judgments on a hosted host aren't under a
+cost cap**. At about $0.000015 a question that's accepted; ask at a human pace all the same, not per stream batch. The tokens a host reports are
+saved in the run (`usage`).
+
 ## Calling services: `ctx.http`
 
 ```ruby
@@ -1313,6 +1417,11 @@ bundle.notices.map(&:text)                               # also cards, steers, s
 bundle.questions.last.effects                            # an ask_user's tags as given: { "Continue" => :spend }
 bundle.answer({ selected: "yes" })                       # the next ask_user's answer
 bundle.model_answers << "a summary"                      # the next ask_model's answer
+bundle.judgments.answer("progress", noul: 0.9)           # ctx.judge's answer from now on; question: for one of several, or a block given the state
+bundle.judgments.fail("progress")                        # a failed backend; mode("progress", "off"), no_host("progress"), shared_host_busy too
+bundle.judgments.wait                                    # judge_later's threads and blocks are done
+bundle.judgments.asks.last.state                         # the asks that reached System 1: name, state, questions, cancel
+bundle.judgments.runs("progress").last["asked"]          # the runs as chi saves them; labels("progress"), acted_lines("progress") too
 bundle.sessions.on(:children) { |all:| [] }              # ctx.sessions, scripted and recorded
 bundle.http.stub(:post, "http://127.0.0.1:9000/classify", json: { label: "safe" })   # ctx.http, never the network
 bundle.set(running: false)                               # the session's values: cwd:, messages:, cancelled: …
@@ -1958,6 +2067,18 @@ and goes with the session; another session starts from config.yml:
 | `/checkin mode ask` / `nudge` / `notify` | the mode |
 | `/checkin nudge` / `later` / `stop` | the card's actions, also by hand |
 
+**Asking System 1 (audit).** Each check-in also asks the cheap judgment model
+`check-in.progress` — "Is this turn still making progress toward what the user
+asked?" — on a side thread, with the owner's prompt, the calls since the last
+check-in (each cut as it is captured, about 4 KB in all), the count and the
+elapsed time. It is off until you give it a mode in
+[`system_one.judgments`](configuration.md#bundles-judgments), and nothing is
+acted on: the answer is saved, and so is what the user then did with the card
+(`nudge`, `keep_going`, `stop`, or `turn_stopped` when the card was still open
+when the turn ended), as a label on that run for a later look. The card, the
+nudge and the notice are the same either way. See
+[System 1's saved runs](system-one.md).
+
 ## The slow-commands bundle
 
 `chi bundle install slow-commands` installs the bundle shipped with chi (`chi
@@ -2651,7 +2772,7 @@ for one model family, loaded into the prompt only for the models a note's
   prefix and against its model key, case-insensitively, and `*` also matches
   `/`: `*deepseek-v4*` covers `deepseek/deepseek-v4.1-flash` on any provider,
   MLX and GGUF names, but not `deepseek-ai/DeepSeek-R1-Distill-Qwen-32B`.
-- **Tested.** `spec/model_ids.yml` lists real id forms and the exact notes
+- **Tested.** `lib/samagotchi/bundles/model-notes/spec/model_ids.yml` lists real id forms and the exact notes
   each loads (negative rows included); the spec installs the bundle and
   resolves each through `sandbox.model_notes_for`
   ([Testing a bundle](#testing-a-bundle-experimental)). It also checks each

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)). 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).
 
 **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.

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` (`shared_host`, or `busy` for a `judge_later` whose last one still
+runs), with its state, host and model but no answers, so a later replay can answer it with no eviction today.
+
+**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/bundles/check-in/manifest.yml

@@ -1,10 +1,13 @@
 ---
 name: check-in
-version: 0.2.4
+version: 0.3.0
 scope: system
 description: "Checks on a long turn: after N tool calls with no answer, a card asks the user (Nudge / Keep going / Stop), or the model is nudged to say what it has found"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:42fe075c664d256ecb8623b76a25d5c389e42c0534a41c56fe17b073d521e095
-requires_chi: ">= 0.3.0"
+  sha256: sha256:fbb7165631c8a8096d900511a95874fe61e72ad8c6f1b45c5c829a285084f25b
+requires_chi: ">= 0.142.0"
+# check-in.progress asks System 1 (chi.judgment, new in 0.142.0): the marker
+# below raises the floor at the release (docs/releasing.md), since chi on main
+# is 0.141.0 and would otherwise refuse its own bundle.