samagotchi 0.141.0 → 0.143.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d6c521351f86a38243b9757eff32df1745e88d2be1158684ba029e85f16b9e1
-  data.tar.gz: 99c0f5f7b2356a58a36f4d38330a17d95decdc64446e26ee55f38d3b5794b3ba
+  metadata.gz: 0403d20c85725cdd309a9b0ff24cc997c3effd60f37e42c9258de568b5e89944
+  data.tar.gz: aa1345c31e6d3ee3dbf578d6ed7298ec98f5c32caf67f304b75ac3caf3f2f886
 SHA512:
-  metadata.gz: 7b735c84997b1a4c035c6d3c0f7baf6035f4f29bd400e6bce116ecaf5fe06c0d2b304fe19a8447a523833bf71cfe9829193d6c8fcb136f42e7a5f900e4f7a30f
-  data.tar.gz: 0705cdf1abb1716a40f38c396b020442b44c2d985911f4d945362f0d2a83bde088c0699f660c8dce791edd666b83529e7d991e642703ceb023558caaa128c394
+  metadata.gz: 528d2c989d71eb722a9e66ede6c2ddd4a57387e74842034bf019a671abb2f3b7d50cb759c8628f6d86d611434a6772a9a3fc75f5886d7f42eea98f3b54bcef1c
+  data.tar.gz: d5078148478d31d778cb973d8ae7dac52696e5cfa9909f96b5ea33185d3c920f067aeea64417b7f64de1785047fc74f9c24bca3f4d4bfda75b792342c712ae22

data/CHANGELOG.md

@@ -7,6 +7,108 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.143.0] - 2026-11-01
+
+### Added
+
+- `chi update` checks the bundles chi doesn't ship, such as one from GitHub, against the new chi, and adds a row for each warning or error: a `requires_chi` it fails, a plugin or
+  hook that no longer loads, a `ctx` call the API lacks, a reference to chi's internals. It never changes them, and these rows don't fail the update (`--json`: a new `level` field). `--no-bundles` skips
+  it, and `--dry-run` with a newer gem to install says `not checked`, as only that chi could answer. See [docs/cli.md](docs/cli.md#updating).
+- `chi bundle check` warns (`api`) on a `ctx.*` or `chi.*` call, or a keyword, that this chi's API lacks, at its line:
+  `ctx.settingz`, `ctx.sessions.nope`, `ctx.card(titel:)`. It reads the plugin's source, so a path no test runs counts too.
+- `ctx.session_dir`: a session's own folder for a bundle, created on use, removed with the session, so a bundle no longer
+  builds that path itself. cost-cap, work-cap and check-in now keep their state there (`state.json`); a running session's
+  file moves in by itself. `chi update` gets them (cost-cap 0.2.4, work-cap 0.1.4, check-in 0.3.1).
+- A manifest may list `settings:`, the keys config.yml's `bundles: <name>:` takes, with `session_settings:`' types. A key it rules out warns
+  when a session starts, in every UI, and so does a `bundles:` name no installed bundle has. Only a warning: the session goes on.
+  The shipped bundles with settings list theirs (`chi update`).
+- A plugin's `chi.on` handler that raises now tells you, once per event in a worker, in the TUI and the web
+  (`plugins> plugin.rb (bundle x) before_turn hook failed (…)`). Before, only the log knew. The hook is still skipped, and the log
+  still has each failure.
+- A bundle's `hooks/*.rb` file that raises now tells you the same way, once per hook in a worker, whatever its `on_error` —
+  including the default `skip`, which logged nothing at all. A guard bundle that broke (`chi-nah`, say) used to fail quietly;
+  now `plugins> guard.rb (bundle chi-nah) before_tool_call hook failed (…)` says so. `on_error` still decides logging and
+  the deny; the notice is only added, and config.yml's own hooks are unchanged.
+
+### Changed
+
+- With System 1 on the model's own local server, its asks now run during your turn as on any other host: toolkit suggestions (audit, the
+  deferred switch and the worker's warm-up, all skipped there before), context candidates (held to the turn's end before) and bundles' judgments (skipped before).
+  Measured on Splash, they don't push out the session's cached prompt. Each costs the running generation about 0.15 s.
+
+### Removed
+
+- `shared_host:` on `chi.judgment`, the `:shared_host` reason, and `shared_host_busy` in the bundle test kit: a bundle still passing `shared_host:` fails to load, with an
+  `ArgumentError`. check-in 0.3.1 no longer passes it, so run `chi update`.
+
+### Fixed
+
+- `chi sessions delete` now also drops the session's lines from `context_candidates.jsonl` (its `judged` lines keep 200
+  characters of its prompts), as it already purges that session's System 1 runs.
+- A reply that is only a tool call the host could not read is now caught when the block has nothing inside it
+  (`<function=task_list></function>`, `<tool_call>{"name":"x"}</tool_call>`), and its close must be the tag that opened it.
+- A Stop that arrives on a reply that is only a tool call the host could not read ends the turn cancelled. It used to fail
+  it with "the reply came back as a ... block the host could not read, twice in a row".
+- With `update.auto: install`, "chi updated to X" counts the sessions the old chi web restarted (it said 0 of them), and a run
+  chi web is restarted in the middle of still tries the sessions it had left.
+- With `update.auto: install`, an error in one step (a full disk, a hiccup reading the sessions) no longer stops automatic updates until
+  chi web restarts: the step is tried again 5 minutes later.
+- With `update.auto: install` and `update.restart: idle`, sessions that were busy or recently used at the update really are tried again for
+  a day, as documented. They used to stay on the old chi once chi web had restarted. The extra tries respect the idle rule, and the page only hears of one that restarts a session.
+- A hung `chi update` run by chi web (the **Update** button, `update.auto: install`) is stopped after 30 minutes and reported as failed. It used to answer "update running" to every later update until chi web restarted.
+- Web: a hash that names no session (`#/`, or none) while one is open now leaves it, as the **+** button does. It used to change
+  only the URL: the page kept showing that session, and Send went into it.
+- `chi bundle check`'s `requires-chi-floor` knows the calls and keywords it was missing: `ctx.context.propose`, `candidates`, `withdraw` and
+  `left_behind`, `ctx.review?`, `ctx.continues`, `ctx.context.attach(movable:)` and others, so a bundle using them with a lower `requires_chi` is told.
+- `/context attach` and `/context decline`, typed in or from audit or off mode, no longer show a "closed" card when no offer card was open.
+- Web: on a phone, a Revise stub's "superseded by vN" stays readable, so two stubs that open with the same line can be told apart.
+
+Update with `chi update` (the core profile 0.4.2): check-in 0.3.1, cost-cap 0.2.4 and work-cap 0.1.4 keep their state in `ctx.session_dir`, and check-in no longer passes `shared_host:` (the older check-in 0.3.0 fails to load on this chi until it is updated). btw, agents-md, claude-peer, codex-peer, coordinator, github-pr, known-names, loop-guard, mcp, ruby, skills, slow-commands and source-links only list their settings or have small fixes.
+
+## [0.142.0] - 2026-11-01
+
+### Added
+
+- System 1's asks are saved, so a later comparison or fine-tune has what was sent, answered and done: approvals, toolkit
+  suggestions and context candidates, with the user's answers as labels, under `<state dir>/system_one/runs/`, 0600 and
+  local only. They hold prompts, commands and diffs, as sent. They last as long as sessions (`session.retention_days`, 100 MB
+  in all), `chi sessions delete` purges a session's, and `system_one.runs: off` stops it. `chi judgments ls` and
+  `chi judgments report NAME [--days N]` show what's there. See docs/system-one.md.
+- Bundles can ask System 1 cheap questions of their own: `chi.judgment` declares one, `ctx.judge` and `ctx.judge_later` ask it,
+  `ctx.judgments.label` says what came of it, and each ask saves a run. Each is off until you set its mode under
+  `system_one.judgments`, which may also give it its own host and model (core's judgments take neither). Bundles' judgments stay out of
+  the session's spend, so no cost cap covers them on a hosted host. The test kit has `bundle.judgments`. See docs/plugins.md (Judgments).
+- check-in asks System 1 `check-in.progress` at every check-in ("is this turn still making progress toward what the user asked?"),
+  off until you set its mode. The turn's prompt, the calls since the last check-in, the count and the elapsed time go, and what you
+  then did with the card is saved as a label on that run. Nothing is acted on: the card, the nudge and the notice are as they were.
+  It is the first use to send tool output to System 1 (docs/system-one.md). `chi update` gets it (check-in 0.3.0).
+
+### Changed
+
+- `memory_read` reads a memory whole: `max_tool_output_chars` no longer cuts it, so a skill or memory over 10,000 characters
+  arrives complete (before, the end was lost and "read it in parts" had no parts). `memory.read_max_chars` (default `0`, no
+  fixed cap) caps it if you want one. A result over half a known context window is still cut, since an overflow would roll
+  the turn back. A cut now says where the rest is: the memory's `.md` file, read with `start_line`.
+- A write that takes a memory over `memory.entry_warn_tokens` (default `5000` tokens) ends with a note to tighten it, once
+  per crossing (`0` turns it off); `chi self` has a `big memories` row for the ones already over. See docs/memory.md.
+- **Edit your config:** System 1's shared settings moved out of `guardrails.system_one`, with no alias:
+  `guardrails.system_one.host` → `system_one.host`, `.model` → `system_one.model`, `.timeout_ms` →
+  `system_one.timeout_ms`. `mode`, `rules`, `threshold` and `min_record` stay where they are. Until all of them have moved chi warns
+  at start, nothing is judged and nothing auto-allows: approvals ask you, and toolkit suggestions and context candidates
+  ask nothing. Move `model` rather than deleting it: with no model set, the host's first model would answer under approvals'
+  existing record. Restart workers on an older chi after the edit. See docs/configuration.md.
+
+### Fixed
+
+- A reply that was only a tool call written as text, which the host couldn't read, ended the turn as if it were the answer:
+  exit 0, work left uncommitted. The chat loop now asks again once with a hidden note; two in a row fail the turn visibly
+  and keep its earlier steps. Seen with Flash Next.
+- A System 1 `score` answer was dropped: the host sends `score` as the probability-weighted level index (a fraction,
+  not a level number), and chi only accepted a whole number. The score is kept as sent and `answer.level` names the
+  level with the most probability. See docs/guardrails.md (System 1).
+
+Update with `chi update` (check-in 0.3.0, the core profile 0.4.1).
+
 ## [0.141.0] - 2026-10-31
 
 ### Added
@@ -967,7 +1069,7 @@ Update with `chi update` (the system bundle 0.118.0), then restart `chi web`.
 - `/exit` in an attached terminal **asks what to do with what still runs** when only things you can stop keep the
   worker up (reminders, a watched background task, a delegate with a live worker): keep running in the background,
   stop them and exit, or go back. Anything else that holds the worker (a running turn, queued prompts, another UI)
-  still refuses as before, and a delegate never holds the idle exit. See [cli.md](docs/cli.md#attached-terminal).
+  still refuses as before, and a delegate never holds the idle exit. See [cli.md](docs/cli.md#sharing-a-session).
 - The web's `stop session` asks the same first: a sheet (a bottom sheet on a phone) counts what still runs and offers
   **Stop all**, **Stop session only** (the stop as it was: background tasks and delegates keep running) or
   **Cancel**; with nothing to stop it is one tap as before. See [Sessions](docs/sessions.md).
@@ -1606,7 +1708,7 @@ Update with `chi update`.
   and active minutes across turns, the bound a session whose step-limit Continue keeps being answered otherwise
   lacks. At a cap the turn pauses on Continue / Stop, the question naming the session's totals; `/workcap` shows or
   sets it, `chi send --new --set work-cap.tool_calls=400` caps a child. Inert until a cap is set. See
-  [docs/plugins.md](docs/plugins.md#the-work-cap-bundle).
+  [docs/bundles.md](docs/bundles.md#the-work-cap-bundle).
 
 ### Fixed
 
@@ -1742,7 +1844,7 @@ Update with `chi update` (the system bundle 0.95.0), then restart `chi web`.
 - The `model-notes` bundle (0.1.0, in the `dev` profile, now 0.7.0): reviewed model notes, for now
   `model_notes_deepseek` for DeepSeek V4 / V4.1 (`models: *deepseek-v4*`). A same-name note you already have is
   skipped and keeps loading; to take the bundle's, remove yours and install again. See
-  [docs/plugins.md](docs/plugins.md#the-model-notes-bundle).
+  [docs/bundles.md](docs/bundles.md#the-model-notes-bundle).
 
 ### Changed
 
@@ -3566,7 +3668,7 @@ Update with `chi update` (mcp 0.6.1).
   instructions. Guardrail rules on `mcp_<server>_<tool>` names still match (`mcp_call` acts as that tool), and the
   question names `<server>: <tool>`; approvals stored under the old names don't carry over. Hooks and loop-guard's
   `ignore_tools` see `mcp_call`. `/mcp` lists the tools as `<server>/<tool>` and says what every request carries.
-  Needs chi 0.37.0. See [docs/plugins.md](docs/plugins.md#the-mcp-bundle).
+  Needs chi 0.37.0. See [docs/bundles.md](docs/bundles.md#the-mcp-bundle).
 
 ### Fixed
 
@@ -3618,7 +3720,7 @@ Update with `chi update` (mcp 0.5.1).
   rebuild (the split, your decisions, its verdicts, follow-ups), its status in the index description, and resumes
   from it in a new session after checking git and the session list; `/coordinate resume` picks up an open handoff.
   When the work is done it marks the handoff DONE and asks whether to remove it. See
-  [docs/plugins.md](docs/plugins.md#the-coordinator-bundle).
+  [docs/bundles.md](docs/bundles.md#the-coordinator-bundle).
 - The guardrails bundle (0.8.0) asks before every memory removal (`memory-remove`, once at a time). Guardrail rules
   take `memory: remove`.
 - In the web, a file reference in an answer (`lib/foo.rb:28`, `lib/foo.rb:28-34`, in inline code too) links to that
@@ -3627,7 +3729,7 @@ Update with `chi update` (mcp 0.5.1).
   at the PR's head. Display only; `bundles: github-pr: line_links: false` turns it off (github-pr 0.2.0; run
   `chi update`). See [docs/context.md](docs/context.md#line-links).
 - `/mcp` shows roughly how many tokens each MCP server's tool definitions take in every request, and the total
-  (mcp 0.5.0; run `chi update`). See [docs/plugins.md](docs/plugins.md#the-mcp-bundle).
+  (mcp 0.5.0; run `chi update`). See [docs/bundles.md](docs/bundles.md#the-mcp-bundle).
 
 ### Fixed
 
@@ -5379,7 +5481,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.141.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.143.0...HEAD
+[0.143.0]: https://github.com/dm1try/samagotchi/compare/v0.142.0...v0.143.0
+[0.142.0]: https://github.com/dm1try/samagotchi/compare/v0.141.0...v0.142.0
 [0.141.0]: https://github.com/dm1try/samagotchi/compare/v0.140.0...v0.141.0
 [0.140.0]: https://github.com/dm1try/samagotchi/compare/v0.139.1...v0.140.0
 [0.139.1]: https://github.com/dm1try/samagotchi/compare/v0.139.0...v0.139.1

data/README.md

@@ -218,10 +218,11 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals
 - [Hooks](docs/hooks.md): plugin hooks and bundle hooks
 - [Plugins](docs/plugins.md): bundle plugins (commands, tools, hooks)
+- [Bundles](docs/bundles.md): what each shipped bundle does (btw, mcp, cost-cap, claude-peer, skills…), its commands and settings
 - [Writing a bundle](docs/bundle-authoring.md): `chi bundle new`, `test`, `check`, `try`, `install --dev`
 - [Testing](docs/testing.md): specs, affected specs, lint, worktrees
 - [Architecture](docs/architecture.md): Engine, TerminalUI, bridge, web
-- Internals: [Engine](docs/internals/engine.md), [Gemma 4 contract](docs/internals/gemma4-contract.md), [prompt caching](docs/internals/prompt-caching.md), [context telemetry](docs/internals/context-telemetry.md), [LLM context: forget layer](docs/internals/llm-context-forget.md), [replay benchmark](docs/internals/llm-context-bench.md), [live runs](docs/internals/llm-context-live.md), [tool output limits](docs/internals/tool-guardrails.md), [background tasks](docs/internals/background-tasks.md), [bundles](docs/internals/bundles.md), [Anthropic Messages API](docs/internals/anthropic.md)
+- Internals: [Engine](docs/internals/engine.md), [Gemma 4 contract](docs/internals/gemma4-contract.md), [prompt caching](docs/internals/prompt-caching.md), [context telemetry](docs/internals/context-telemetry.md), [LLM context: forget layer](docs/internals/llm-context-forget.md), [replay benchmark](docs/internals/llm-context-bench.md), [live runs](docs/internals/llm-context-live.md), [tool output limits](docs/internals/tool-output-limits.md), [background tasks](docs/internals/background-tasks.md), [bundles](docs/internals/bundles.md), [Anthropic Messages API](docs/internals/anthropic.md)
 
 ## Development
 

data/bin/chi

@@ -97,6 +97,8 @@ SUBCOMMANDS = {
   "guardrails" => ["samagotchi/guardrails_command", "GuardrailsCommand"],
   # audit suggestions for which toolkit fits a session's first prompt
   "toolkit" => ["samagotchi/toolkit_report_command", "ToolkitReportCommand"],
+  # System 1's saved asks on this machine (ls, report)
+  "judgments" => ["samagotchi/judgments_command", "JudgmentsCommand"],
   # other machines' chi web, for chi --remote NAME (add, ls, rm)
   "remote" => ["samagotchi/remote_command", "RemoteCommand"],
   # the chi home: the Ruby every chi launch boots (set, doctor)

data/docs/architecture.md

@@ -209,7 +209,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, the model↔tool loop (`run_turn`). No terminal coupling. |
 | UI | `Samagotchi::TerminalUI` | Interactive REPL (Reline), rendering (ANSI, spinner, status line), REPL commands. Delegates all core work to an `Engine`. |
 | Model loops and adapters | `KernelLoop`, `LLM::ChatLoop`, `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | The model↔tool loops and the HTTP adapters they talk through (see "Model loops and adapters"). |
-| Bridge (SSE/HTTP) | `Samagotchi::Bridge`, `SessionManager` | The **single live client transport**: an SSE read stream + HTTP POST turn/cancel/answer surface that attaches to a worker's existing `Engine` via `Engine#subscribe`. Every session worker starts it (bound `127.0.0.1`, localhost-only), and it answers only a request that names its secret (`X-Chi-Bridge`, from the worker's 0600 `bridge.json`). |
+| Bridge (SSE/HTTP) ([internals/bridge.md](internals/bridge.md)) | `Samagotchi::Bridge`, `SessionManager` | The **single live client transport**: an SSE read stream + HTTP POST turn/cancel/answer surface that attaches to a worker's existing `Engine` via `Engine#subscribe`. Every session worker starts it (bound `127.0.0.1`, localhost-only), and it answers only a request that names its secret (`X-Chi-Bridge`, from the worker's 0600 `bridge.json`). |
 | Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). With `web.host: lan` (or one of this machine's IPv4 addresses) the server also listens on that address, where every request needs the access token, this machine's on loopback too (`App#token_gate`: the `chi_token` cookie, on loopback a value derived from the token (`Token.loopback_cookie`), or `Authorization: Bearer`; chi web prints a `Local:` link with a one-time code; [CLI](cli.md#chi-web-on-your-phone)). Experimental: behind an auth proxy (`web.public_url`, `Web::ProxyGate`) every request needs the token, this machine's too, and one that came through the proxy also the configured identity header for the owner ([configuration.md](configuration.md#behind-an-auth-proxy)). A request goes through, in order: the Host check (`local_host_header?`: loopback names, the LAN address, the public host), the cross-site check (`cross_site?`: Origin this server's or the public origin, no `Sec-Fetch-Site` cross-site/same-site on a POST or `/api`), the frame check (`framed?`: a frame/embed/object load from another origin, 403 `framed`; every HTML answer carries `X-Frame-Options: DENY` and `frame-ancestors 'none'`), the token gate (`token_gate` → `principal_for`, `proxied_principal` for a proxied request; the `?token=` / `POST /api/token` trade sets the cookie, `__Host-chi_token` through the proxy; with `web.public_url` a direct request takes Bearer only, and with it or LAN mode chi's token-less `/api/info` probe gets `probe_info`), then the route's permission (`Principal#permits?`). It talks to each worker's Bridge (`App#relay`, `bridge_get`; `/stream` proxies it) and reads the session files; no `Engine` of its own. Markdown (`web.markdown`) is rendered here only (`Web::MarkdownRenderer`): the answers it serves, card bodies, and `POST /api/render` for a text the page already shows. `App` keeps the gate, `ROUTES` and the helpers the handlers share; its handlers live in mixins it includes, each a `Web::` module with private methods: `SessionAccessRoutes` (`web/session_access_routes.rb`), `ParticipantAccess` (`web/participant_access.rb`), `ParticipantsAdmin` (`web/participants_admin.rb`), `ParticipantReview` (`web/participant_review.rb`), `MessageDisplay` (`web/message_display.rb`), `SessionShow` (`web/session_show.rb`), `SessionCreate` (`web/session_create.rb`), `SessionControl` (`web/session_control.rb`), `PushRoutes` (`web/push_routes.rb`) and `ProxyGate` (`web/proxy_gate.rb`). Exact paths in `GATE_FREE_PATHS` are served before the token gate (the fragment trade's script, and the Home Screen app's manifest, service worker and icons). `bin/chi web` entrypoint. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File-based `~/.local/state/samagotchi/sessions/<uuid>.json` + sidecar `input/`/`output/`; retention (14d/500) + ordering (`updated_at desc`). |
 
@@ -315,286 +315,15 @@ engine.session_state_snapshot   # => { status:, message_count:, last_prompt:, ev
 
 `Engine#subscribe` is the seam the SSE bridge (`Samagotchi::Bridge`) rides on. The bridge
 is the **single live transport** and runs **inside the forked session worker** (the same
-process that already owns the `Engine`); every worker starts it, and it exposes:
-
-- `GET  /session/:id/stream` — SSE stream of engine + kernel events, each with an
-  `id: <event_seq>-<epoch>` cursor (the epoch is drawn per worker's Bridge, since `event_seq` starts
-  over in each worker; snapshots and `/state` carry it as `event_id`); resume via `Last-Event-ID` /
-  `?from_seq=` (a plain `event_seq` is still accepted); a `: ping` heartbeat keeps idle proxies alive;
-  too-old reconnects, and cursors from another worker's epoch, receive a `reset` marker carrying
-  `session_state_snapshot`. `?snapshot=1` joins with a snapshot frame instead of a replay;
-  `?client_id=` names whose stream it is (`Bridge#open_streams_except`, used by `POST /exit`).
-  Each event goes out as clients get it (`Bridge::ClientEvent.project`, in `SSEWriter#write_event`, live
-  and replayed alike); `generation_chunk`, `tool_call_started` and `turn_completed` are projected to the
-  contracts below. The ring retains raw events for replay and `?raw=1`.
-  `?raw=1` writes events as the engine emitted them, for debugging on the worker's port: `chi web`'s
-  `/api/sessions/:id/stream` never passes it on (`Web::App#stream_query`).
-  An attached terminal's stream (`EventStream` with `rediscover:`) looks for the session's live
-  worker whenever it drops: a new one (a restart) is followed from its snapshot, and the terminal
-  sends its requests there (`worker_changed`); it gives up after ~12 s, or at once when the session
-  was stopped.
-
-  The wire chunk (the contract; the engine's own event keeps the provider's `payload` and the raw `content`):
-
-  ```
-  event: generation_chunk
-  data: {"type":"generation_chunk","iteration":2,"text":"…","thinking":"",
-         "tool_call":true,                                   // only when set
-         "counts":{"prompt_tokens":489,"completion_tokens":12,
-                   "total_tokens":501,"context_window_tokens":32768},  // only when the server reported counts
-         "event_seq":812}
-  ```
-
-  A `tool_call_started` frame keeps its row fields but omits the model's `call`:
-
-  ```
-  event: tool_call_started
-  data: {"type":"tool_call_started","iteration":2,"call_index":1,"tool":"write",
-         "params":"path=notes.txt","event_seq":812}
-  ```
-
-  A `turn_completed` frame omits `result`; `turn_summary.output` carries the answer:
-
-  ```
-  event: turn_completed
-  data: {"type":"turn_completed","turn_summary":{"output":"Done."},
-         "display_pending":false,"event_seq":813}
-  ```
-
-  `counts` is `ContextUsage.normalize` of the provider's payload without `ctx_pct` (normalize computes it
-  without the session's LLM context budget; a client counts `total_tokens` against the window or budget, as
-  `ContextStatus#generation_done` does for the TUI) and with its nil keys left out: cumulative for the
-  request, a missing key means unknown (never 0), `prompt_tokens` includes cached tokens, and
-  `context_window_tokens` is there only when the payload reported a window itself (llama.cpp's `/completion`
-  doesn't: the client uses `generation_started`'s). Unknown provider fields never cross; a field is added here
-  when a client needs it, never as a catch-all bag. Details: [internals/context-telemetry.md](internals/context-telemetry.md).
-- `POST /session/:id/turn` — fire-and-forget turn creation; returns `202` with an `enqueued_id`
-  (delivery is at-least-once via the worker's file-IPC input path — it never calls `run_turn`
-  across the HTTP boundary). Only the bridge's own session: another id, in the path or the body's
-  `session_id`, is `404 unknown_session`. Inspect results through the read surface, not the turn response.
-  An optional `deadline` (epoch seconds; `BridgeClient` sends 5/6 of its read timeout ahead) makes
-  a request read after it (a worker frozen by sleep or SIGSTOP) answer `408 deadline_passed` and
-  not run: a client that timed out has said the message was not sent. `/answer`,
-  `/question/dismiss`, `/command`, `/turn/dequeue` and `/exit` take the same `deadline` (a command is
-  checked with the event log held, as a turn is), and the Bridge logs `turn_expired`, `answer_expired`,
-  `dismiss_expired`, `command_expired`, `dequeue_expired` or `exit_expired`. The web app answers either
-  kind of timeout with `504 worker_timeout` ("… so the command was not run"). `/cancel` and `/recap` take none.
-  The web relays answer, dismiss, command and cancel the same way (`App#relay`): a 408 or a read
-  timeout is `504 worker_timeout`; a Bridge 404 for a route an older worker lacks is
-  `501 not_supported` with the restart hint; a Bridge `404 unknown_session`, no bridge or a
-  refused connection is `503 not_live`.
-- `POST /session/:id/cancel` — cancel the running turn; `202`, or `409` when none runs.
-- `POST /session/:id/recap` — `/recap` in an attached TUI: `200 {enabled, saved, request,
-  min_user_turns}` (`{enabled: false, session_off}` without recaps; `session_off` when the session's own
-  `/recap off` turned it off); a new recap is asked for at once and
-  arrives as `:recap_ready`. Answers mid-turn too.
-- `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
-  answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
-  (`chi answer`, a parent agent) the answer is checked by `Guardrails::ParentPolicy` in
-  `QuestionDesk#answer`: the question carries each option's effect (`effects`, set by its asker:
-  `Approval.payload`, `ContinueOffer`, `Relay.card`; derived for an untagged one) and `user_only`,
-  and an option beyond the worker's `guardrails.parent_answers` (tightened by the session's own
-  `parent_answers`: `ParentPolicy.for_session`) is `403 parent_answer_refused` (with its `reason`),
-  the question still open. `chi answer` makes the same check first, from the session file.
-- `POST /session/:id/question/dismiss` — leave the question unanswered (an approval: denied);
-  `200`, or `409` when it is no longer pending.
-- `POST /session/:id/tasks/stop` — `{task_id}`: stop a background task as the user
-  (`TaskRuntime.stop_task by: "user"`, the web's stop-task button on a running `task_wait`;
-  web route `POST /api/sessions/:id/tasks/:task_id/stop`). Only a task this conversation's
-  `task_create` started, or an `execute` handed over as a task at its limit (`TaskRuntime.created_ids_in` on the
-  saved messages, or the running turn's accumulator); answers once the
-  task is gone: `200 {status, stop_reason, task_id}`, `404 task_not_found`, `409 not_running`.
-  The worker names it in its sidecar features (`task_stop`).
-- `POST /session/:id/turn/dequeue` — `{enqueued_id, client_id?, deadline?}`: take back a queued message
-  (one that waits for the running turn's end: `--queue`, Alt+Enter, `/queue TEXT`, or a message
-  with images) before a turn takes it (web route `POST /api/sessions/:id/turn/:enqueued_id/dequeue`,
-  the × on a queued bubble; `/unqueue` in the attached TUI). Under the event log, like its enqueue:
-  `SessionInbox.take_queued_input` writes a tombstone (`input/removed/<enqueued_id>`, for `ReplyWait`'s
-  `turn:`), claims the file as the drain does (one rename wins; a lost claim takes the tombstone back),
-  deletes it, and the Bridge announces `:turn_dequeued`. `200 {status: "removed", enqueued_id, prompt}`, `409 already_started`
-  (a turn took it), `409 not_queued` (a next-step message: a drain may merge it any moment), `404
-  unknown_enqueued_id`. It never wakes the worker. The worker names it in its sidecar features (`unqueue`).
-  A worker's start prunes the `input/removed/` and `input/settled/` tombstones older than a week
-  (`SessionInbox::TOMBSTONE_MAX_AGE`, log `tombstones_pruned`); otherwise they go with the session dir.
-- `POST /session/:id/relay` — the approval relay, on a delegated child's worker
-  (`{action, relay_id, question_id}`): `opened` / `closed` (with a `reason`) set or clear the
-  pending question's `relayed_to` mark (`QuestionDesk#annotate`, `:question_relay`); `answered`
-  makes the child ask its parent's Bridge for the answer (`RelayVerifier`) and take it only for
-  this child and the question pending now. `200`, `409` no longer pending, `403` a parent agent's
-  pick beyond the child's own `guardrails.parent_answers` and session `parent_answers` (`parent_answer_refused`; the
-  relay card in the parent was held to the parent's), `422 relay_unverified` (the question
-  stays open).
-- `POST /session/:id/relay/status` — on a parent's worker, `{relay_id}`: what its `RelayDesk`
-  (memory only) holds for that relay (`child_id`, `child_question_id`, `state`, `answer`, `by`);
-  `404` for an unknown id. A POST with a body because routes match exact paths.
-- `POST /session/:id/command` — a session command (`/model`, `/models`, `!rollback`, `!cmd`,
-  `/continue`) for the worker loop; `202` with a `command_id` its `:command_ran` names, `400` when
-  the line isn't one. A `:command_ran` carries `thinking`, `reasoning_history` and `llm_context`
-  (the summaries the next turn runs under) when the command changed them or the model, and
-  `confirm: {line, text}` when a `/thinking` or `/reasoning-history` change from a `web:` or `tui:`
-  client asks first (`CacheConfirm`; nothing changed, `line` applies it).
-- `POST /session/:id/exit` — ask the worker to exit now (`{client_id:, delete?, restart?, deadline?}`; `delete`:
-  `/exit --delete`, no recap written; `restart: true`: hand the session to a new worker on the newest chi
-  installed, `200 {status: "restarting"}`; an empty session's `exiting` carries `discard: true`). The worker checks with
-  the event log held (`WorkerIdleExit#hold_for_request`): `200 {status: "exiting"}` and it leaves
-  like an idle exit, or `409 {status: "held", reason:}` with `turn_running`, `input_queued`,
-  `continue_offered`, `client_connected` (a stream not named by the asker), `reminders`,
-  `background_tasks` (with `tasks: [{id, command}]`: the running tasks a finish wake watches), `starting`, or
-  `leaving_exit` / `leaving_delete` / `leaving_restart` when another client's exit of another kind is already taken
-  (`Worker#claim_exit`, claimed before a stop-all; the words are `WorkerIdleExit::LEAVING_WORDS`). A second exit of
-  the kind already taken is answered `200` as that one.
-- `GET  /session/:id/state` — `session_state_snapshot` (JSON).
-- `GET  /session/:id/stats` — `Engine#stats_snapshot` for attached `/stats`: the metrics, with the context window and prompt profile asked from the server before the first turn.
-- `GET  /session/:id/snapshot` — the snapshot frame's content as one request (the web server renders
-  the messages itself, then streams from its `event_seq`). Read by the web's full show
-  (`GET /api/sessions/:id`, `?parts=1`) and the plugin's `list_sessions`; every message is copied.
-- `GET  /session/:id/tail` — the page's light re-read (`Bridge#tail_frame`): `session_state_snapshot`,
-  `working_directory` (the session's folder, which the web checks the answer's file refs against),
-  `answer` (the last message a UI shows as an answer, `AnswerTail`: the one message, copied alone),
-  `cards` (`CardStore#list`; a card an earlier worker showed during a turn comes back read-only, with no
-  actions: its turn no longer runs), `event_seq`, `event_id`, all taken in one event-log hold; no message
-  list, so it costs the same however long the session is. `?turn_id=` answers that turn's answer
-  (an unknown or missing id: the newest); the only route that reads its query.
-- No browser: only chi's own clients talk to a Bridge. A request with an `Origin` header, a `Sec-Fetch-Site`
-  other than `none`, or a `Host` that isn't loopback (a DNS-rebound page) is `403 cross_origin`
-  (`Bridge#browser_request?`, before any route); there is no CORS and no `OPTIONS` route. The browser reaches a
-  worker only through `chi web`. A request carrying any trace a proxy adds (`ProxyTrace`: `X-Forwarded-*`,
-  `Forwarded`, `X-Real-IP`, `X-Auth-Request-*`, `Cf-*`…, underscore twins too) is `403 proxied`
-  (`Bridge#proxied_request?`): an auth proxy that forwards every local port and adds such a header doesn't reach a
-  worker.
-- **The secret.** Every request, on every route (the stream, the reads such as `state` and `stats`, the writes, and
-  an unknown path), names the Bridge's secret in `X-Chi-Bridge`; one without it, or with another one, is
-  `403 bridge_secret` with one session-specific message (`BridgeSecret.refused`): "session ID's worker refused
-  this chi's request (it didn't name its secret): a chi web or terminal started before chi was updated can't
-  reach it; restart chi web, re-attach with `chi --attach ID`, or restart the worker with `chi sessions restart
-  ID`." `chi sessions restart` can also recover when the worker cannot be asked: TERM + resume if disk shows no
-  running turn, pending question or approval, queued input, or running background task. The check is after the
-  browser and proxy checks and before any route (`Bridge#secret_ok?`,
-  `OpenSSL.secure_compare`). No route is left open: what the reads show is the session itself. Only a request that
-  got past it counts as client activity, so a refused one (an older chi web's polls) never holds the idle exit. Each Bridge makes its own (`SecureRandom.hex(32)`, 64 hex
-  characters) when it starts and writes it to `bridge.json`, which is 0600 from the moment it exists
-  (`AtomicFile` creates the temporary file with that mode, then renames it), so only this machine's user can read
-  it: a forward that adds no proxy header, or another local account, reaches the port but not a session. Clients get
-  it only from the sidecar: `WorkerLink.client`/`.await` and `BridgeClient.for_sidecar` take the port and the secret from the
-  same read (chi web makes its client from the sidecar for every request, the attached terminal again on a
-  `worker_changed`), so a respawned worker's new one is used and nothing passes a port by hand. A worker from before
-  the secret writes none and asks for none; a chi web or attached terminal from before it sends none, so a worker
-  the newer chi started refuses it until it is restarted. A client tells that refusal from a route's own 403
-  (`BridgeClient::Response#secret_refused?`) and shows the one message: chi web's relays answer 502 `bridge_secret`,
-  `chi answer` and a parent's approval relay say it instead of "refused", and an event stream ends with reason
-  `bridge_secret` once rediscovery finds no newer worker (the attached terminal's closing line), never retrying in
-  silence; chi web's stream proxy answers 502 `bridge_secret`, never passing the refusal on as frames. The secret is never logged (a refusal logs
-  `secret_refused` with the path, at most once a minute), never in an event, a reply, `/api/info` or a session
-  file, and `WorkerSidecar`, `BridgeClient` and `Bridge` leave it out of `#inspect`.
-
-The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` frames
-(`SessionMetrics#snapshot`) carry the session's totals and only the recent timing records: the
-newest turn the worker finished and any it hasn't saved yet (at most 20 turns), with their tool
-calls and the running turn's finished ones. The full history is the session's `analytics.json`,
-which `SessionMetrics#persist` rewrites after each turn; the web server merges the two by id.
-The totals' `tokens` block adds the cached, cache-write and reasoning sums, the reported cost (`cost_sum`) and the
-estimated one (`cost_estimate_sum`, from `hosts.<name>.models` prices; 0 for none), the decode time and tokens
-behind the average speed (`avg_decode_tps`) and the last speeds (`last_decode_tps`,
-`last_prefill_tps`, `tps_source`: `server` or `estimate`). `model_segments` (always present) splits those sums
-by model after a `/model` switch: one row per run of consecutive turns on one model (`SessionMetrics::ModelSegment`,
-keyed on the turn records' `model_ref`), in order, with its turns, token and cost sums, speeds and the switch's prefill
-(`prefill_tokens`, `prefill_cost_estimate`: the sums of its turn records' `switch_prefill_tokens` and
-`switch_prefill_cost_estimate`, [sessions.md](sessions.md)); `[]` with one model, the oldest rows folded into one (`folded_segments`)
-past 6; a running turn counts in its model's row (`ended_at` null). The rows add up to `tokens`. They are derived from
-the records, never read back. Each `generation_completed` event
-carries the generation's `speed` (`{decode_tps, source}`, null without one), its own prompt-cache
-counts (`prompt_tokens`, `cached_tokens`, `cache_write_tokens`: null when the server reported no writes) and
-those running `tokens` and `model_segments`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
-it, so the web's info bar updates per generation without parsing chunk payloads.
-Side requests (the idle recap, a plugin's `ctx.ask_model` such as `/btw`) are counted apart, in a `side` block
-(only when there were any; `SessionMetrics::SideTotals`: requests, token sums, `cost_sum` null until reported,
-`cost_estimate_sum` from the target host's price, `by_kind`): `IdleClient` hands each reply's usage to its
-`on_usage:` callback, `Engine#note_side_usage`, which folds it (`SessionMetrics#add_side`) and announces
-`:side_usage` (`kind`, the whole `side` block) under the event lock, so the blocks arrive in fold order, then saves
-`analytics.json` between turns (a running turn's end saves it). `tokens`, `model_segments` and the turn records
-stay the turns' only. `SessionMetrics#persist` is serialized (its own mutex, taken before the metrics one), so two
-threads' saves land in snapshot order.
-A bundle's `ctx.cost` reads the same sums (`SessionMetrics#cost`, a frozen `SessionMetrics::Cost`): the `tokens`
-block's `cost_sum` and `cost_estimate_sum` with the running turn's finished generations folded in, plus the `side`
-block's, so it counts what earlier workers spent too ([plugins.md](plugins.md)). Its `ctx.usage` reads the work
-(`SessionMetrics#usage`, a frozen `SessionMetrics::Usage`): the snapshot's `turns`, `tool_calls_total` /
-`tool_calls_by_tool` and `iterations_total`, and `active_ms`, the generations' `gen_ms` plus the finished tool
-records' `duration_ms` (tallied per tool as they are counted; `ask_user_question`'s, a wait on the user, left out).
-
-The page's frequent reads of `GET /api/sessions/:id` stay light too:
-- `?tail=1&recent=1` (each turn's end, a cancel, an answer display): `{tail, session: {id, status,
-  used_memory_names}, messages: [the answer, with its display and display_refs (re-read on an `answer_display` with a display or refs)], markdown_warning, timing}`, from the worker's `/tail`
-  alone (no session file parsed, no `analytics.json`); `timing` carries the worker's recent records
-  and `turn_count` (finished turns). The page merges the records by id (`timing.js mergeTiming`) and
-  finishes the ended turn's own line by its `turn_id` (sent as `&turn_id=`, which also picks that
-  turn's answer). A tail read's timing is always the newest turn's; `recent=1` is accepted and not needed.
-  The page binds an answer's `display_refs` to its bubble (`answer_refs.js`: on a reload's render and on this
-  read's re-render) and pairs them with the bubble's links and text before the `path:line` scan. A question's
-  refs (`pending_question.refs`, `:question_asked`) pair the same way (`markdown_place.js` `linkRefsIn`/`pairRefsIn`):
-  `question_requested` (or a snapshot's pending question) keeps them on the asking step's gen
-  (`turn_model.js` `questionRefs`) before the card draws, so the stage's asking slot (`stage_slots.js`
-  `drawAsking(text, refs)`) pairs them on its raw draw and again after its markdown swap; the card pairs its
-  question text and its kept reply (`question_cards.js`); the step's closed `.gen-text` takes them
-  (`turn_block.js`; on a reload its `data-answer-at`, the message's `display_refs`) and `linkTextRefs` pairs it at
-  the turn's end and after a reload. A closed step's text is markdown too with `web.markdown` on: a reload's
-  from its message's `html` (`turn_block.js` `textTemplate`), a live turn's from `POST /api/render` on its step's
-  first open after the turn's end (`markdown_place.js` `renderStepTexts`, which pairs its refs again after the
-  swap); the text as written stays on it as `data-copy-source` (`stepText`, a reloaded card's kept reply). A file ref outside the
-  session's folder is dropped, as a reload drops it: the folder `/tail` names, else (an older worker) the hub's
-  session list entry's, else (refs to check, no hub entry) the session file's; with no folder known at all, every
-  file ref is dropped rather than shown unchecked.
-  A plugin tool's row refs (`refs`, `RowRefs`) ride its tool events and, on a reload, its part (saved as
-  `tool_refs`); `turn_block.js` binds them to the row's title (`refs.js bindRowRefs`: the first on the title,
-  the others in its menu).
-- `?timing=1`: the whole timing (`analytics.json` merged with the worker's `/state`) and
-  `turn_count`, when the page's merge came up short.
-- `?cards=1`: the cards, from `/tail`; the session file is only stat'ed for the 404.
-
-The stage view's working set (`web.working_set`) has its own read, `GET /api/sessions/:id/working_set`: the
-`WorkingSet` projection (`{items, at, running}`: each file, memory and URL live, stale or forgotten, with its tokens)
-of the worker's `/snapshot` messages, else the session file, under the session's LLM context strategy; while a turn
-runs, the snapshot's `working_set` (the running turn's last event, which the messages lag) when it has one. Its live form
-is the `:working_set_updated` event, which always wins over a GET's answer it overtook. The page overlays it on the
-set it builds from its tool rows ([internals/working-set.md](internals/working-set.md)).
-
-A worker without `/tail` (an older chi; `404 not_found`) is read through `/snapshot` in the same
-shape; any other failure (no worker, a 500, a timeout) reads the disk, trimmed to the newest
-turn's records.
-
-Every route goes through `Bridge#dispatch`: an id other than the bridge's own session is
-`404 unknown_session`, and a handler that raises answers `500 bridge_error` (logged as
-`handler_failed`) rather than dropping the connection.
-
-The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
-for client discovery, with the Bridge's secret (see above).
-
-**Worker link.** Every client asks `WorkerLink` (`worker_link.rb`) whether a session's worker can be reached, never
-reading `bridge.json` or probing a port itself: `WorkerLink.resolve(session_dir, unlink:, owner:)` answers a typed
-outcome. The rule is the owner lock plus the sidecar's `pid`; there is no port probe (a port can be reused by another
-session's Bridge, a free lock is the kernel's proof the worker died). In order: no lock holder, or a chi REPL's: a
-sidecar is `Stale(:lock_free)` (removed with `unlink: true`, only if it is still the file that was read and the lock,
-read again just before, is still free: a worker that took it meanwhile is resolved as that worker), else `None`;
-a holder with no kind yet: `Starting`; a leaving worker: `Leaving` (marked before its Bridge stops, on every way out:
-`Worker#teardown` marks it too, with `TEARDOWN_LEAVE_WAIT`); a worker whose sidecar names no port or another
-pid than the holder's (a worker that has not written its own yet): `Starting`, `stuck` once it has held the lock
-past `START_LIMIT` (30 s) with none; a sidecar whose `protocol` is newer than `WorkerLink::PROTOCOL`: `Skew` (a
-newer worker; never driven, `wake` answers 409 `worker_newer`); else `Live` (its sidecar; `#client` makes the one
-`BridgeClient`). A sidecar with no `pid` is an older worker's: the lock alone says it is live. `owner:` is the
-holder as the caller already read it (nil: free), so one read serves a summary and its status. `WorkerLink.client` is
-the Live's client or nil; `WorkerLink.await` polls for a new worker's Live (an `until:` check tells a restart's
-successor from the old worker); chi web's `App#worker_link` / `#await_worker_link` wrap them. The Bridge writes
-`pid` and `protocol` with its port and removes its sidecar on stop only when the file still carries its epoch.
-
-`chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
-(503 `not_live` for no worker, a leaving or stuck worker, or an unreachable Bridge; 502 `worker_newer` for skew and
-`bridge_error` / `bridge_secret` for a refused Bridge; 200 only after the Bridge answers; full history of any session
-is served by `GET /api/sessions/:id/output`). It opens the Bridge before answering and gives the one opened socket to
-`App#proxy_stream_body` / `ProxyStreamBody`, which closes it when the body or hijacked client ends. The owner's stream
-is a byte pipe; the body gives it the request's frame filter (`App#stream_filter`: nil for the owner; for a participant, and the owner's participant view
-`?as=participant`, a `Web::ParticipantStreamFilter`, which cuts the Bridge's chunks into frames and writes each again
-from `Web::ParticipantView.event`'s allowlist, dropping every other event; only `from_seq` and `snapshot` reach the
-Bridge; [internals/participants.md](internals/participants.md#what-a-participant-sees)). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
-an earlier worker gets the `reset` snapshot, not a replay.
+process that already owns the `Engine`); every worker starts it. It keeps what a client that joins late needs
+(`RingBuffer` of recent events, `TurnAccumulator` for the turn in progress, `CardStore` for cards and notices), writes
+each client's stream with an `SSEWriter` (`id: <event_seq>-<epoch>` cursors, a `snapshot` or `reset` frame when a
+cursor cannot be replayed), and answers HTTP routes: `GET /session/:id/stream`, `state`, `snapshot`, `tail`, `stats`
+and the writes `POST …/turn`, `cancel`, `answer`, `command`, `exit` and more. Only chi's own clients reach it (never a
+browser; a proxy trace is refused), and every request names the Bridge's secret from the 0600 `bridge.json`. `chi web`
+proxies the stream and relays the writes. The routes, wire shapes, replay rules, refusals and the worker link
+(`WorkerLink`: whether a session's worker can be reached) are in [internals/bridge.md](internals/bridge.md).
+
 
 **Session hub.** The cross-session layer (which sessions exist, who owns them, what changed)
 never pulls from the page: `chi web` runs one `Samagotchi::Web::SessionHub` (a thread inside
@@ -636,7 +365,8 @@ The owner's update routes publish progress and results as `chi_update` events wi
 `version` and may include a progress line. The hub retains the latest event for a reconnecting
 tab's snapshot. `POST /api/update` decides itself whether this install can take a gem
 (`UpdateCheck.blocked_reason`: a checkout, Bundler, an unwritable gem dir → 409 `update_blocked`), so
-it holds with `update.notify: off`; a child that prints no rows fails with its own last line, and a
+it holds with `update.notify: off`; a child that prints no rows fails with its own last line, a child still running after
+30 minutes (`UpdateOps::UPDATE_TIMEOUT`; it has a process group of its own) is stopped with what it started and fails the same way, and a
 done install refreshes the hub's installed version (`SessionHub#refresh_installed`) before its `done`.
 Worker restarts target every worker older than the version installed now (refreshed the same way)
 and publish per-session results. Only one of an install, a worker restart pass and a web restart runs
@@ -656,17 +386,23 @@ and installs it through `UpdateOps#install(wait: true, auto: true)` when the ins
 runs, no hub summary has `status: running` or a `pending_question`, and the version isn't in `auto_failed` or
 already in the `auto` record (one automatic try per version). Its frames carry `auto: true` (the page: "Automatic
 chi update in progress", "(automatic)" in the sheet's title). Its record is `update_check.json`'s `auto`:
-`{version, from, at, kept, phase: installed|workers|web|done|failed, workers: {restarted, left}, detail, pushed}`.
+`{version, from, at, kept, phase: installed|workers|web|retrying|done|failed, workers: {restarted, left}, detail, pushed}`,
+in Ruby the value object `Web::AutoUpdateRecord`, which owns that shape (`from_h`, `to_store`).
 With `update.restart: never` the run ends at the install (`chi_notice` `installed`). With `idle` it goes on
-(`phase` `installed` → `workers` → `web` → `done`): `UpdateOps#restart_workers(select:)` over the stale workers whose
+(`phase` `installed` → `workers` → `web` → `retrying` → `done`): `UpdateOps#restart_workers(select:)` over the stale workers whose
 summary is idle with no question and `updated_at` at least 10 minutes old (`QUIET`; the others are `skipped` rows;
-the worker's own atomic refusal still applies), the left ones retried each step for 24 h (`RETRY_FOR`); then, with no
+the worker's own atomic refusal still applies); then, with no
 turn running, `Server.restart_preflight` (the restart's command with `--version`, 20 s, killed on a timeout; it must
 print a chi at least the release) and, if it passes, the record's `phase: web` is written **before**
 `UpdateOps#restart_web`. A failed preflight, or a refused restart, publishes `restart_failed` and ends the run
 (`failed`). `AutoUpdate#stop` waits `STOP_WAIT` (25 s, longer than the preflight's timeout) for its thread, and a
 preflight that ends after a stop leads to nothing (no `web`, no exec): the next start takes the run up again. The restarted chi web's AutoUpdate (first step after 5 s) finds `phase: web`, checks it runs the
-release, counts the workers once more and publishes `updated`, then `done`. Results reach the phone as `chi_notice`
+release, counts the workers once more and publishes `updated`, then `done`, or `retrying` while workers are left. Those are
+retried each step until none is left or 24 h (`RETRY_FOR`) have passed since the install, under the same filter, and from
+whichever chi web is up (`workers` before the restart, `retrying` after it, and a restart mid-retry reads it from the
+record). The time is checked before each pass, so a run always ends. A later pass is `quiet:`: no `chi_update` frames (each
+is a sticky toast) unless a worker restarts, and no further `chi_notice`. `retrying` isn't an open phase for the install
+gate: a newer release installs under its usual gate, and its record replaces this one, its own passes taking the workers over. A step that raises is logged (`auto_update_failed`) and taken again at the next poll; each one saves the record before it publishes, so the owner hears it once. Results reach the phone as `chi_notice`
 hub events (`SessionHub#publish_notice`), see [internals/web-push.md](internals/web-push.md).
 
 The page's scope is in its URL, and the server picks the default: `?dir=<folder>` is that folder's
@@ -873,11 +609,11 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Bundle authoring | `bundle_command.rb` (`BundleCommand`), `bundle_command/{scaffold,check,test_run}.rb`, `bundle_command/try/{run,sandbox,trace}.rb`, `testing.rb` + `testing/` (the test kit) | `chi bundle new`, `check`, `test` and `try`, and the kit a bundle's tests load it with ([bundle-authoring.md](bundle-authoring.md), [internals/bundles.md](internals/bundles.md)). |
 | Session config (`--set`) | `session_config.rb` (`SessionConfig`, `SessionConfig::Settings`) | A session's own settings as one value (`Session#settings`, `SessionSetup#settings`): `core`, the `--set KEY=VALUE` values of the core keys marked `session: true` (`Config::Entry`), typed by `Config.coerce!` and read first through `Config.get(key, session:)` (`RecapSetup`; `Engine#session=` rebuilds the recap job, `IdleScheduler#replace_job`), file key `config_settings`; `bundles`, the `--set BUNDLE.KEY=VALUE` values, checked against the manifest's `session_settings:`, laid over `bundles: <name>:` in `ctx.settings` ([plugins.md](plugins.md)), file key `bundle_settings`. `SessionConfig.clash` refuses a bundle setting named like a core one (install, `chi bundle check`). See [configuration.md](configuration.md#per-session-settings). |
 | Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb`, `plugin/context.rb` (`ctx`), `plugin/http.rb` + `plugin/http_transport.rb` (`ctx.http`), `plugin/card.rb` (`Plugin::Card`) | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources; what its handlers get as `ctx` ([plugins.md](plugins.md)). |
-| Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([plugins.md](plugins.md#the-claude-peer-bundle)). |
+| Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([bundles.md](bundles.md#the-claude-peer-bundle)). |
 | Shipped bundles | `bundles/` (`mcp`, `github-pr`, `loop-guard`, `skills`, `source-links`, …) | Bundles that ship with chi. |
 | Hooks | `hooks/registry.rb` (`Hooks::Registry`), `hooks/loader.rb`, `hook_routes.rb` (`HookRoutes`), `event_routes.rb` (`EventRoutes`) | Hook registration and dispatch; what a hook or plugin does beyond reading its event (notice, question, stop, steer) routed to the UIs (cards and notices through one set of routes) ([hooks.md](hooks.md)). |
 | Guardrails | `guardrails.rb`, `guardrails/shell_lex.rb`, `guardrails/data_readers.rb`, `guardrails/rules.rb`, `guardrails/protected_paths.rb`, `guardrails/parent_policy.rb` + `guardrails/parent_approvals.rb`, `guardrail_wiring.rb` | The gate before every tool call: shell lexing (and the commands that only read a heredoc as data), YAML rules, the core checks on chi's own files, approvals, what a parent agent may answer (`guardrails.parent_answers`) ([guardrails.md](guardrails.md)). |
-| System 1 | `system_one.rb`, `system_one/` (`SystemOne::Client`, `ApprovalQuestion`, `Log`, `Record`, `SelfProtect`, `Similar`, the backends), `guardrail_wiring.rb` (`GuardrailWiring#request_approval`), `guardrails_command.rb` (`chi guardrails replay`) | The approval judge: a model's `p` for each ask, logged to `judgments.jsonl` with the user's answer; in `on` mode an ask on a listed rule with a clean record is allowed once without the user. Labelled by `/guardrails wrong` (`SessionCommands`) and the web's **should have asked** (the Bridge's `POST guardrails/wrong`) ([guardrails.md](guardrails.md#system-1-experimental)). |
+| System 1 | `system_one.rb`, `system_one/` (`SystemOne::Client`, `Recording`, `Runs`, `ApprovalQuestion`, `Log`, `Record`, `SelfProtect`, `Similar`, the backends), `guardrail_wiring.rb` (`GuardrailWiring#request_approval`), `guardrails_command.rb` (`chi guardrails replay`) | The approval judge: a model's `p` for each ask, logged to `judgments.jsonl` with the user's answer; in `on` mode an ask on a listed rule with a clean record is allowed once without the user. Labelled by `/guardrails wrong` (`SessionCommands`) and the web's **should have asked** (the Bridge's `POST guardrails/wrong`) ([guardrails.md](guardrails.md#system-1-experimental)). Every core ask goes through `SystemOne::Recording`, saved as a run under `<state dir>/system_one/runs/` (`Runs`, `RunsStore`, `ApprovalLabel`, `judgments_command.rb`: [system-one.md](system-one.md)). |
 | Delegation | `tools/delegate.rb`, `tools/delegate_result.rb`, `tools/delegate_wait.rb`, `child_reports.rb`, `tools/delegate_relay.rb`, `relay_desk.rb`, `relay_verifier.rb`, `relay_watcher.rb` | Child sessions a session starts and waits on, and their approval relay ([sessions.md](sessions.md#delegating)). |
 | send / broadcast | `send_command.rb` (`SendCommand`), `broadcast_command.rb` (`BroadcastCommand`), `broadcast/` | `chi send` and `chi broadcast` ([broadcast.md](broadcast.md), [sub-agent.md](sub-agent.md)). |
 | Worker link | `worker_link.rb` (`WorkerLink`: `Live`, `Starting`, `Leaving`, `Skew`, `Stale`, `None`), `worker_sidecar.rb` (`WorkerSidecar`) | Whether a session's worker can be reached and the client for it: every Bridge client asks `WorkerLink.resolve` / `.client` / `.await` (*Worker link* above); `WorkerSidecar` is the `bridge.json` it reads. |
@@ -896,7 +632,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
 | Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`), `tools/deferred_tools.rb` | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). On `api: anthropic` they also go out deferred, a hit loads its matches and the model calls them by name ([internals/anthropic.md](internals/anthropic.md)). |
-| Tool output cut | `tool_output_cut.rb` (`ToolOutputCut`), `tool_output_files.rb` (`ToolOutputFiles`) | A tool's output over `max_tool_output_chars`, cut by the tool's policy; an execute's whole output saved in the session's `tool_output/` folder ([internals/tool-guardrails.md](internals/tool-guardrails.md)). |
+| Tool output cut | `tool_output_cut.rb` (`ToolOutputCut`), `tool_output_files.rb` (`ToolOutputFiles`) | A tool's output over `max_tool_output_chars` (a `memory_read`'s: `memory.read_max_chars`, 0 = none, plus a guard at half a known window), cut by the tool's policy; an execute's whole output saved in the session's `tool_output/` folder ([internals/tool-output-limits.md](internals/tool-output-limits.md)). |
 | Steer delivery | `steer.rb` (`Steer`), `delivery.rb` (`Delivery`), `steer_cut.rb` (`SteerCut`), `generation_phase.rb`, `waiting_steer.rb`, `steer_cut_after.rb` (`SteerCutAfter`), `cut_policy.rb` (`CutPolicy`) | A message for a running turn: at the next boundary, cutting a thinking-only generation, or queued for the turn's end ([internals/engine.md](internals/engine.md)). |
 | Prompt files | `prompt_files.rb` (`PromptFiles`) | The AGENTS.md chain (root → cwd) and the appended files the system prompt carries. |
 | Model settings | `effective_model.rb` (`EffectiveModel`, `ModelChoice`), `model_profile.rb` (`ModelProfile`), `model_settings.rb`, `sampling_settings.rb`, `model_catalog.rb` (`ModelCatalog`), `model_notes.rb` (`ModelNotes`) | The effective model's settings as one snapshot per read, a model's prompt format, its `models:` entry, its request parameters, the pickable model rows (`chi models`, `/api/models`), the notes its prompt loads. |