samagotchi 0.156.0 → 0.157.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e545b9da4004e996e2cdee4f53d2cf0a181a47b695fbcb18ca1037e77da6b1cb
-  data.tar.gz: 10cb3b94093ab0f0e7d285a2f405577be8fc61f26029a005754a078875d8ebdc
+  metadata.gz: e6e6add2f9511492180ba39e11ebbcd9da6a703e5325facfc9ddc24bd22bc2eb
+  data.tar.gz: e426d754c3306c361fe54d1fde2475502e3121b2ab1a5caecad92712165056e1
 SHA512:
-  metadata.gz: f20b956f443a5a04680d2a7a162e3a9d44f9b8a66d0855f2827421420a7f8a1053ad01769ff140c442fded2e6cdf58b41f0b37f6a22b7849fcb463d5fdb2b22e
-  data.tar.gz: a08049e4ab152265163ea53327655064a1c2415b19c695e03dd21d3b01488453824cb59451fb333618ed1aefc334e97b10b4780cfdee02dd916853e37069858a
+  metadata.gz: a0026bf97c1ef84a78f181283c712490f1961972d49c10e2559fe29d2047d599223837c328a96b15aa382208d47f5d78a723842b575a624bfa992b71130a6082
+  data.tar.gz: 0f6e09c9abd81b9e218677b47373215a91788b735fb7c515d4ea72b563d9875ea836438a4b1b019ddf4d480418954363dcbe0bd01b23a545a59a864484f6f437

data/CHANGELOG.md

@@ -8,6 +8,48 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.157.0] - 2026-11-08
+
+### Added
+
+- `web.reload_check` (off by default): chi web checks each finished turn against a reload of it and logs `reload_mismatch` with the kinds that differed and the known divergences that explain them (no content).
+- A bundle's plugin can guard tool calls fail-closed: `chi.on(:before_tool_call, on_error: :fail_closed)` denies the call its block raised on, and a plugin its manifest marks `required: true` (under `plugin:`) that fails to load (an edited file, an unmet `requires_chi`, a raise) makes chi deny every tool call until it is fixed, as a fail-closed bundle hook does. `chi bundle check` warns about a fail-closed hook whose plugin isn't marked required (docs/plugins.md).
+
+### Changed
+
+- `/llm-context`, `/stats` and the web's LLM context chip name where a value came from as the other settings do: `session` and `hosts.NAME` (were `the session` and `hosts entry 'NAME'`).
+- `chi sessions list` prints one line wherever it runs: the `--live`, `--cwd` and `--format text` listings and `chi --remote NAME sessions list` show the plain list's state (`idle`, not `live`) and description (no folder prefix), and the plain list's footer. The plain list's `ctx N%` now rounds as the picker and chi web round it (it could read 1% apart).
+- A delegating parent's wait says `worker_gone` 5 s after a child's worker dies (was 15 s); a child whose worker never starts is reported `worker_gone` ("its worker did not start") after the 30 s boot limit (or the wait's timeout, if shorter: then the child shows as `running`, as for any wait that timed out).
+- In chi web, a long tool output's hover shows the same cut live as after a reload (the first 2000 characters of a file read, the start and end of other output).
+- A turn nobody typed (a reminder, an attached context change, a finished task, a delegate report) has an id of its own, `wake-` and 16 hex digits: `chi send --wait --format json` names it as the `turn_id`, and the `--turn` hints carry it.
+- `chi send --wait -m` to a session left running by a worker that died names the message's own id as the `turn_id` in `--format json`, where it named the running turn's.
+- `chi bundle install` of a bundle already installed from a source that moved on now takes the new text of each memory you never edited, as `chi bundle upgrade` would, and records the new version; a memory you edited is still kept (`--force` or `chi bundle upgrade` brings the bundle's changes).
+- The known-names and source-links bundles hook through their plugin (known-names 0.2.0, source-links 0.7.0); `chi update` installs them. Nothing changes in what they do.
+
+### Fixed
+
+- A `delegate` follow-up that the child's ending turn didn't take gets its own turn's reply, not the ended turn's.
+- `chi send --wait` with no message on a wake turn (a reminder, a context change, a task's finish, a delegate report) names its `turn_id`, ends `canceled` (`worker_stopped`) when its worker dies in it, and `--turn` waits for it.
+- A message or a delegate follow-up merged into a running turn as a steer waits for that turn's reply or end, which the worker now records, not for the session's next reply (a newer turn's could answer for it).
+- `chi bundle uninstall` asks for `--force` before taking a memory you edited that has no base copy (chi compares it with the checksum its install recorded; with neither, it counts as edited), as it does for any edited file; it used to move it to the trash without asking.
+- `chi bundle status` says `modified` for an edited memory that has no base copy; it said `ok` while the next upgrade left the file behind.
+- `chi update`'s plan names every edited hook, rule, plugin file and script it replaces or removes, as its `Copied to the trash first` line does; it left out edited scripts and hooks installed with no recorded sha, and its row now says `a copy goes to the trash first` instead of `it wasn't loading`.
+- `chi bundle install --dry-run` and `chi bundle upgrade --dry-run` report hooks, rules, the plugin and scripts as the real run does (`Would update`, `Would install`, `Up to date`); a changed hook showed as skipped, an unchanged rule or plugin as would install, and scripts not at all.
+- `chi bundle install core --dry-run` (a profile's dry run) no longer names a hook it would replace as your own kept file.
+- `chi bundle upgrade --dry-run` lists a memory that already has the bundle's text as up to date, as the upgrade itself does; it listed it as skipped.
+- `chi bundle upgrade` (and `chi update`'s plan) leaves behind a memory that `chi bundle status` calls `modified` but whose base copy equals it, as it does any edit it can't merge; it replaced the file with the bundle's text and kept no copy.
+- `chi bundle upgrade` (and `chi update`'s plan) takes the bundle's new text for a memory you never edited that has no base copy (chi compares it with the checksum its install recorded), as for any unedited memory; it left the file behind as a conflict while `chi bundle status` called it `ok`.
+- A bundle memory whose bytes don't match the manifest's `files:` sha now warns `Checksum mismatch` when `chi bundle upgrade` (or a re-install from a source that moved on) brings its new text or merges it into your edit, as a first install does: a bad download warns on an upgrade too. A `--dry-run` checks the bundle's file it would write, a memory or a hook, so it warns as the real run does and no longer blames a memory you edited (`install --force --dry-run`) or the hook an upgrade would replace. `chi update` and `chi bootstrap` show these warnings on the bundle's row (a system bundle install, update or restore, and a shipped bundle's update); they dropped them.
+- A system bundle memory chi puts back after you deleted it is checked against the manifest's `files:` sha too, and warns `Checksum mismatch` when its bytes differ, as an installed one does.
+- A context window given with `--context-window-tokens` to a one-shot run (`-p … --non-interactive`) is named `cli`, not `config`, where its source shows: the debug log, and chi web's context tooltip for that session.
+- A tool row's duration is the same live, after a reload and in the attached terminal (each timed the call with its own clock).
+- chi web draws a finished turn after a reload or a reconnect exactly as it drew it live: the empty answer's "asking again" row stays in its step, a failed turn keeps its last step, a card the turn showed comes back where it was, and the reminders that went into a turn are shown. Turns from before this release, or run by a worker not yet restarted, show as before.
+- `chi --attach` shows the last turn's tool rows as they ran (status, duration, retries).
+- A saved recap is placed after the turn it covers, by that turn's id, where counting turns could put it a turn off (after a check-in, for one).
+- In chi web, a turn that fails after its tool steps shows the same time on its timing line live as after a reload (the turn record's, as a canceled turn does).
+
+Update with `chi update` (known-names 0.2.0, source-links 0.7.0).
+
 ## [0.156.0] - 2026-11-08
 
 ### Changed
@@ -5798,7 +5840,8 @@ 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.156.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.157.0...HEAD
+[0.157.0]: https://github.com/dm1try/samagotchi/compare/v0.156.0...v0.157.0
 [0.156.0]: https://github.com/dm1try/samagotchi/compare/v0.155.0...v0.156.0
 [0.155.0]: https://github.com/dm1try/samagotchi/compare/v0.154.1...v0.155.0
 [0.154.1]: https://github.com/dm1try/samagotchi/compare/v0.154.0...v0.154.1

data/bin/chi

@@ -263,6 +263,7 @@ if options[:web]
   exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
                                       markdown: markdown, new_token: options[:new_token], tunnel: options[:tunnel],
                                       working_set: Samagotchi::Config.get("web.working_set"),
+                                      reload_check: Samagotchi::Config.get("web.reload_check"),
                                       annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
                                       editor: Samagotchi::Config.get("web.editor"),
                                       start_dir: options[:start_dir] || Samagotchi::Config.get("web.start_dir"),

data/docs/architecture.md

@@ -428,14 +428,15 @@ each `<id>/` folder (recap.json, bridge.json, the stopped and archived markers),
 moved through `Session.summary_from_file`. Liveness is probed, since a killed owner leaves no
 file trace: the owner lock every tick for the sessions the projection believes owned, and every
 session every 10 s, so a `kill -9` shows within a second. The summary (`Web::SessionSummary`,
-shared with `/api/sessions` and the session view) carries `owner`, `project_root` and
+shared with `/api/sessions` and the session view; built on the session's `SessionRow`, the one row every list
+reads, so the page, `chi sessions list` and `/children` agree on status, liveness and a waiting question) carries `owner`, `project_root` and
 `bridge_up` (`WorkerLink` answers Live: a worker holds the lock and its sidecar names its pid; the page attaches its stream on it), and
 from that sidecar `worker_version` (the chi the worker runs) and `worker_features`
 (`Bridge::FEATURES`, what a client may ask of it beyond the routes: `restart`, `task_stop`, `reparent`, `unqueue`,
 `delivery`, a worker that queues a message for after the turn; `SessionManager.deliver_turn` and
 the attached TUI refuse a queue to a worker without it, which would steer; `turn_ids`, a worker whose running
 turn's mark, continue turn and Stop carry the turn's `enqueued_id`, which `chi answer`, `chi send --wait` with no
-message and `delegate_result` rely on through `ReplyWait.own_turn`). A worker's Bridge snapshot
+message and `delegate_result` rely on through `ReplyWait.own_turn` (a wake or reminder turn has one too, worker-minted `wake-…`; a steer's merge is recorded in `input/merged/`, read by `ReplyWait::Poll#follow_merge`); every wait's binding is one `ReplyWait::Target`, built by its caller's constructor). A worker's Bridge snapshot
 names its `chi_version` too.
 `POST/DELETE /api/sessions` and `/stop` rescan the session before answering (`SessionHub#touch`).
 `GET /api/sessions` is the hub's projection too (its sort, paging and total). `Server` always builds
@@ -457,7 +458,7 @@ model: [internals/remote-sessions.md](internals/remote-sessions.md).
 | Route | Permission | Body / params | Answer | Refusals |
 |---|---|---|---|---|
 | `GET /api/sessions/resolve?id=` | owner | an id or a unique prefix | 200 `{id}` | 404 `not_found`; 400 `ambiguous_id` with `ids` |
-| `GET /api/sessions/summaries` | owner | `dir` (a folder: its project; none: every project), `cwd`, `live=1`, `archived=1`, `tests=0`, `sort`, `order`, `limit` | 200: the rows `chi sessions list` prints (`SessionManager.session_summaries`: `status`, `live`, `busy`, `owner`, `recap`, `ctx_pct`, `waiting`, `waiting_id`, `title`, `preview`, …) | 400 `invalid_dir`, `invalid_cwd` |
+| `GET /api/sessions/summaries` | owner | `dir` (a folder: its project; none: every project), `cwd`, `live=1`, `archived=1`, `tests=0`, `sort`, `order`, `limit` | 200: the rows `chi sessions list` prints (`SessionRow#to_summary_h`, 28 keys in a fixed order: `status`, `live`, `busy`, `owner`, `recap`, `ctx_pct`, `waiting`, `waiting_id`, `title`, `preview`, …) | 400 `invalid_dir`, `invalid_cwd` |
 | `GET /api/projects?dir=` | owner | optional page-scope folder | 200: project rows (`Web::ProjectList`: the hub's projects plus the start project) with counts, roots, default/current marks; no `dir`: no current project | 400 `invalid_dir`; 503 `no_hub` |
 | `POST /api/sessions` (more fields) | owner | `toolkit`, `tools`, `no_tools`, `parent_answers`; `client_id` (`cli:send`/`cli:answer`: the first line is checked as chi send checks it); `check_vision: true` (images follow) | 201 adds `model_warning`, `parent_answers_warning` (a level looser than config.yml's, capped) and `first_turn_id` (the id the prompt it starts with gets for its turn; null for an `idle` create) | 400 `invalid_toolkit`, `invalid_parent_answers`, `invalid_continues` (beside `continues`); 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
 | `POST /api/sessions/:id/turn` (more fields) | owner | `client_id` as above; `check_vision: true` with `images` | as before | 403 `parent_answers_refused`, `parent_continue_refused`; 422 `no_vision` |
@@ -509,8 +510,9 @@ every lookup goes through `Session.resolve!` (an id or a unique prefix), and eve
 
 A model ref (`--model`, `/model`, `default.model`, an alias's target) is parsed
 by one pure resolver, `ModelRef.parse` (host prefix, alias), given the configured
-hosts and aliases; `HostRegistry` routes a name that names no host (its model
-index after `/models`) and builds the `ModelTarget`.
+hosts and aliases; `HostRegistry` (one per process for commands and chi web:
+`HostRegistry.current`) routes a name that names no host (its model index after
+`/models`) and builds the `ModelTarget`.
 
 Engine picks the loop from the effective model's host: `EffectiveModel.of` resolves it (`HostRegistry#resolve`)
 on every read, never kept, since config.yml and a model listing can move it without a `/model`
@@ -618,6 +620,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Paths | `paths.rb` (`Paths`) | The XDG base dirs chi's files live under, read from the env on every call: `Paths.state_home` (`$XDG_STATE_HOME`, else `~/.local/state`) and `Paths.config_home` (`$XDG_CONFIG_HOME`, else `~/.config`), both defaults under `Dir.home`; a blank variable counts as unset, a relative one is made absolute from the current directory. `Paths.tilde` shows a path with `~` for the home folder. `SessionManager` hands a spawned worker the spawner's `XDG_STATE_HOME` / `XDG_CONFIG_HOME`, when set, made absolute, so a relative one isn't read from the session's folder. |
 | MemoryBundle | `memory_bundle.rb`, `memory_bundle/{installer,builder,installed_bundle,plugin_ref,bundle_hook}.rb` (`Installer`, `Builder`, `InstalledBundle`, `PluginRef`, `BundleHook`) | Installing, building and reading bundles of memories, hooks and plugins. |
 | 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 file | `session.rb` (`Session`, `Session::FIELDS`), `session_field.rb` (`SessionField`), `session_paths.rb` (`SessionPaths`), `session_setup.rb` (`SessionSetup`) | A session's `<uuid>.json`: one `SessionField` row per key (default, cast, what the file gets; the codec on its type), from which `Session.new`, `.from_h` and `#to_h` are built; `SessionPaths` is where the file and the session's dir are and the id rule, a leaf `Session` extends (so `ArchiveStore`, `ContextSources` and `ParticipantMode` name no `Session`); `SessionSetup` the settings a fork and a continue carry, applied by member name. See [sessions.md](sessions.md#session-file). |
 | 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 ([bundles.md](bundles.md#the-claude-peer-bundle)). |
@@ -634,7 +637,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
 | Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. `SessionChain.opener_for` gives the text web `continue →` prefills in the new link: the previous link's own first typed message when that link continues one itself, else nil (the 201's `opener`; not saved) ([sessions.md](sessions.md)). |
 | Review sessions | `review_start.rb` (`ReviewStart`), `session_review.rb` (`SessionReview`, the session's `review` field), `review_command.rb` (`ReviewCommand`, `chi review`), `review_apply.rb` (`ReviewApply`) | A session made to be shared: idle, its subjects project files checked by `Guardrails::ReviewPaths`, a fork of a working session from its recap (`--from`); Apply quotes a participant's review turn into the owner's composer ([sessions.md](sessions.md#review-sessions), [internals/participants.md](internals/participants.md)). |
-| chi web's routes | `web/app.rb` (`Web::App`: the gate, `ROUTES`, the shared helpers), `web/message_display.rb` (`Web::MessageDisplay`: saved messages and cards as display items, `POST /api/render`), `web/session_show.rb` (`Web::SessionShow`: `GET /api/sessions/:id` with its `cards`, `tail` and `timing` re-reads, `GET …/output`, the timing payload), `web/session_create.rb` (`Web::SessionCreate`: `POST /api/sessions`, a continue, a review fork), `web/session_control.rb` (`Web::SessionControl`: answer, command, turn and images, cancel, stop, restart, archive, delete), `web/push_routes.rb` (`Web::PushRoutes`: `/api/push`, its subscriptions, prefs, test and presence), `web/block_renderer_routes.rb` (`Web::BlockRendererRoutes`: `GET /api/block_renderers` and one renderer's file, [internals/block-renderers.md](internals/block-renderers.md)) | The handlers `App`'s `ROUTES` name, in the file that holds their kind; each mixin is included in `App` and reads its helpers and ivars, so `app.send(:handle_show, …)` and the specs that stub `App` methods work as before. |
+| chi web's routes | `web/app.rb` (`Web::App`: the gate, `ROUTES`, the shared helpers), `web/message_display.rb` (`Web::MessageDisplay`: saved messages and cards as display items, `POST /api/render`), `web/session_show.rb` (`Web::SessionShow`: `GET /api/sessions/:id` with its `cards`, `tail` and `timing` re-reads, `GET …/output`, the timing payload), `web/session_create.rb` (`Web::SessionCreate`: `POST /api/sessions`, a continue, a review fork), `web/session_control.rb` (`Web::SessionControl`: answer, command, turn and images, cancel, stop, restart, archive, delete), `web/push_routes.rb` (`Web::PushRoutes`: `/api/push`, its subscriptions, prefs, test and presence), `web/block_renderer_routes.rb` (`Web::BlockRendererRoutes`: `GET /api/block_renderers` and one renderer's file, [internals/block-renderers.md](internals/block-renderers.md)), `web/reload_check_route.rb` (`Web::ReloadCheckRoute`: `POST /api/sessions/:id/reload_check`, the opt-in `web.reload_check`'s counts from the page's `reload_check.js`, 204 and one `reload_checked` log line, with `reload_mismatch`, its `kinds`, `excused` (ACCEPTED ids) and `explained` when the turn read otherwise after a reload; the worker's version is chi web's own view, its sidecar) | The handlers `App`'s `ROUTES` name, in the file that holds their kind; each mixin is included in `App` and reads its helpers and ivars, so `app.send(:handle_show, …)` and the specs that stub `App` methods work as before. |
 | Web Push | `web/push.rb` (`Web::Push`: `Runtime`, `preflight!`, the `web.push.*` settings), `web/push/crypto.rb` (`Push::Crypto`: RFC 8291 aes128gcm, RFC 8292 VAPID), `web/push/store.rb` (`Push::Store`, `Store::Sub`: `web-push/vapid.pem`, `subscriptions.json`), `web/push/client.rb` (`Push::Client`, `Client::Result`), `web/push/attention.rb` (`Push::Attention`: notify.js's rules in Ruby, shared cases in `spec/fixtures/attention_cases.json`), `web/push/presence.rb` (`Push::Presence`: the pages' "in front" reports), `web/push/notifier.rb` (`Push::Notifier`, a hub subscriber with a sender thread), `web/push_routes.rb` (`Web::PushRoutes`), `private_files.rb` (`PrivateFiles`, shared with the grants), `public/sw.js`, `public/push.js`, `public/manifest.webmanifest` | chi web pushes what the tab notifies for (approvals, questions, step-limit questions, cards, failed turns; done turns to a device that asks) to the owner's Home Screen app over an https public URL: the Notifier turns the hub's new attentions into show pushes after a hold, unless a chi web page is in front, at most 30 an hour, with one retry and a restart catch-up (`sent.json`) (each carries the keys still open, and the badge; no close push: every push shows a notification); the bell (`notifications.js`) subscribes the device, and the service worker and the page close the answered ones. See [internals/web-push.md](internals/web-push.md). |
 | chi web's updates | `web/update_check.rb` (`Web::UpdateCheck`), `web/update_ops.rb` (`Web::UpdateOps`), `web/auto_update.rb` (`Web::AutoUpdate`) | The RubyGems checker and its `update_check.json`; the install, worker-restart and chi-web-restart operations (one at a time) the owner's routes and AutoUpdate share; `update.auto: install`'s thread (install when no turn runs, then idle workers and chi web). See [configuration](configuration.md#unattended-updates-updateauto). |
 | Behind an auth proxy | `web/public_url.rb` (`Web::PublicUrl`: `web.public_url`, `web.proxy.identity_header`, `web.proxy.owner`), `web/proxy_gate.rb` (`Web::ProxyGate`, mixed into App; `RawHeaderNames`, prepended to WEBrick's request by `Web::Server`), `web/link_codes.rb` (`Web::LinkCodes`: the links' one-time codes), `proxy_trace.rb` (`ProxyTrace`), `web/public/token_fragment.js`, `web/public/auth_lost.js`, `web/tunnel.rb` + `web/tunnel/tailscale.rb` (`Web::Tunnel`, `Web::Tunnel::Tailscale`: `chi web --tunnel tailscale`, Tailscale Serve set for one run and the PublicUrl it makes) | Experimental: chi web behind an auth proxy. Every request needs the token; a proxied one's owner also needs the identity header (one clean value under one name); the `__Host-` cookie, an absolute `Location` from the public URL, https links with a one-time code in the fragment; the page's lost-sign-in banner. Bridges refuse proxy traces ([configuration.md](configuration.md#behind-an-auth-proxy)). |
@@ -646,11 +649,13 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | 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. |
+| Model settings | `effective_model.rb` (`EffectiveModel`, `ModelChoice`), `model_lookup.rb` (`ModelLookup`: every layer's input), `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. |
 | Session settings | `session_setting.rb` (`SessionSetting`), `session_model_settings.rb` (`SessionModelSettings`), `level_setting_command.rb` (`/thinking`, `/reasoning-history`), `llm_context_command.rb`, `toolkit_command.rb`, `thinking_notices.rb` (`ThinkingNotices`) | A session's own llm_context, thinking, reasoning_history and toolkit: their chips (session state, `/stats`, `:command_ran`, the web), the commands that set them, the thinking level's notices. |
 | Dialects | `llm/dialect.rb` (`LLM::Dialect`) | What an `api: anthropic` provider's `/v1/messages` does differently (`dialect: fireworks`) ([internals/anthropic.md](internals/anthropic.md)). |
 | Logging | `log.rb` (`Log`), `log_subscriber.rb` (`LogSubscriber`), `log_path.rb` (`LogPath`), `log_line.rb` | The debug log: tagged records, a session's event trail, where the file goes ([configuration.md](configuration.md#debug-log-file)). |
 | Stores | `reminder_store.rb` (`ReminderStore`), `recap_store.rb` (`RecapStore`) | A session's reminders, and its idle recap (`recap.json`). |
+| Reply waits | `reply_wait.rb` (`ReplyWait`, `GONE_AFTER`: the one dead-worker rule), `reply_wait/poll.rb` (`ReplyWait::Poll`, one look per poll), `reply_wait/target.rb` (`ReplyWait::Target`: which turn a wait binds, cursor, baseline, `owner_grace`; `first_message`, `message`, `wait_only`, `answer`, `participant`, `from_cursor`), `reply_wait/liveness.rb` (`ReplyWait::Liveness`: one owner and link read per look; `#owner?` for gone, `#worker_owned?` for an open question) | `chi send --wait`, `chi answer`, a participant's wait, the delegate tools and delegate reports wait through `ReplyWait.call(id, **target.to_h, …)` ([sub-agent.md](sub-agent.md)). |
+| Session rows | `session_row.rb` (`SessionRow`) | A session as the lists see it: scalar facts only, built by `SessionManager.session_rows` (one owner, link, recap and analytics read each), `#to_summary_h` the summaries route's body and `.from_summary_h` a remote's rows read back, `#cli_line` the one `chi sessions list` line, `.running_or_starting?` the delegates' and Verify fresh's "running" (a 15 s grace for a worker on its way). A leaf: never session_manager or web. |
 | Setup and update | `bootstrap_command.rb`, `bootstrap/`, `update_command.rb`, `gem_update.rb` | `chi bootstrap` (first config.yml, system bundle, core profile) and `chi update` (the gem, shipped bundles, the macOS helper). |
 | Process groups | `process_group.rb` (`ProcessGroup`) | A command in a process group of its own, stopped as a group (TERM, grace, KILL): execute, tasks, context fetches, the mcp bundle's servers. |
 | Desktop | `desktop.rb`, `desktop/macos.rb`, `desktop_command.rb`, `desktop/macos/*.swift` | `chi desktop`, the macOS "Send to chi" helper ([desktop.md](desktop.md)). The helper's Swift side: the panel (`Panel.swift`), the chi CLI runner (`ChiRunner.swift`), the session rows and the chi calls a send makes (`Sessions.swift`: `SendPlan`; `ChiHelper --sessions` and `--send-plan` are their CLI seams), agent terminals behind `AgentTerminal` (`AgentTerminal.swift`, `Kitty.swift`, `Tmux.swift`; `ChiHelper --agents` is their CLI seam). |

data/docs/bundles.md

@@ -4,7 +4,9 @@ What each shipped bundle does for you, its commands, settings and files. A bundl
 the plugin API ([plugins.md](plugins.md)); install, upgrade and the `chi bundle` commands are in
 [plugins.md](plugins.md#the-bundle-commands) and [cli.md](cli.md). Two shipped bundles are documented with the
 feature they belong to: **source-links** in [hooks.md](hooks.md#the-source-links-bundle) and **known-names** in
-[guardrails.md](guardrails.md#the-known-names-bundle).
+[guardrails.md](guardrails.md#the-known-names-bundle). Both hook events from their `plugin.rb` with `chi.on`
+(known-names on `before_tool_call`, priority 50; source-links on `after_turn` and `question_asked`, priority 90), as
+every shipped bundle with code does; before known-names 0.2.0 and source-links 0.7.0 they shipped a `hooks/*.rb` file.
 
 ## The btw bundle
 

data/docs/cli.md

@@ -17,7 +17,7 @@
 - `chi web push ls [--format json]`, `chi web push rm ID`, `chi web push test [ID]` — the phones chi web pushes to (see [Phone notifications](configuration.md#phone-notifications-web-push)): list them (short id, label, origin, added, last delivery, done turns, last error; `stale` for one made on another public URL than chi web's now: never sent to), remove one, or send a test notification to ID or to every device not stale. chi web need not run; nothing printed holds a device's push address or keys. A usage error exits 2; a store others can read, a corrupt one, an unknown device or a failed test push exit 1. This machine only: `chi --remote X web push` exits 2
 - `chi web --web-markdown` / `--no-web-markdown` — opt in to, or opt out of, sanitized Markdown rendering for completed assistant messages, the stage's asking text and a resolved question card's reply (`web.markdown`, off by default; `--no-web-markdown` turns a config's `web.markdown: true` off for this run)
 - `chi web --no-web-working-set` — turns the stage view's working set off (on by default; `--web-working-set` turns a config's `web.working_set: false` back on): what each turn brought into the model's context, in the stage and under each finished turn; `?working_set=1|0` on the page URL overrides it (see [The working set](#the-working-set))
-- `chi sessions list|stop|restart|archive|unarchive|delete|prune|clean|stats` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)). `stats ID` prints a session's cost, tokens and progress, and its own settings (`--set`; a `settings:` line), from a live worker's `GET stats`, else its saved `analytics.json` (`--format json` one object, with `settings`), without running a model turn. A usage error (an unknown subcommand or flag, a flag missing its value, `stop`, `restart` or `delete` with no ids, a bad `list --format` or `--scope`, a `--days`, `--keep` or `--limit` that isn't a whole number) exits 2; an unknown or refused session exits 1
+- `chi sessions list|stop|restart|archive|unarchive|delete|prune|clean|stats` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md)); one line per session (`<id>  <state>  <ctx>  <updated_at>  <text> [flags]  ↳ …  ↪ …`) and one footer (`N session(s) (sort=… order=…)`, or the project note) for the plain list, the `--live`/`--cwd` text and `--remote`. `stats ID` prints a session's cost, tokens and progress, and its own settings (`--set`; a `settings:` line), from a live worker's `GET stats`, else its saved `analytics.json` (`--format json` one object, with `settings`), without running a model turn. A usage error (an unknown subcommand or flag, a flag missing its value, `stop`, `restart` or `delete` with no ids, a bad `list --format` or `--scope`, a `--days`, `--keep` or `--limit` that isn't a whole number) exits 2; an unknown or refused session exits 1
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
 - `chi broadcast [-m TEXT] [--all] [--dry-run]`, `chi broadcast log [--last N] [--format json]`, `chi broadcast deliver BROADCAST_ID (ID|PREFIX)...` — share one piece of information (TEXT or stdin) with every session it may concern, as a context note from `broadcast` (see [Broadcast](broadcast.md))
 - `chi context <add|push|ls|show|refresh|rm|mute|unmute> …` — attach live external text to sessions (a command chi runs every so often, or text pushed in); the model gets a short note when it changes and reads it with `context_read`; `chi context add <URL>` attaches a GitHub PR with the github-pr bundle; `chi context push NAME -m TEXT` (the long form is `--message TEXT`) gives a `--push` source its new text, read from stdin when no `-m` is given (see [Attached context](context.md))
@@ -159,7 +159,7 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   then forces), `install` (each Installer warning, a `needs` one as warn, and each plugin or hook load failure at
   the source `file:line`; skipped while a placeholder sha is unfilled), `registered` (info: each command, tool,
   hook with its priority, init, toolkit, tool source, peer source and prompt section), `hook-event` (warn: a `chi.on` event chi
-  never fires), `settings` (warn: a `--set` the manifest's `settings:` rules out, as config.yml's `bundles:` is told), `api` (warn: a `ctx.*` / `chi.*` call or a keyword this chi's API lacks, read from the source with
+  never fires), `fail-closed` (warn: a `chi.on(..., on_error: :fail_closed)` in a plugin whose manifest `plugin:` lacks `required: true`, so a load failure would not deny tool calls; not on an installed bundle's re-check), `settings` (warn: a `--set` the manifest's `settings:` rules out, as config.yml's `bundles:` is told), `api` (warn: a `ctx.*` / `chi.*` call or a keyword this chi's API lacks, read from the source with
   Prism against the API's own classes, on a path that never runs too; written on a local `ctx` / `chi` itself, so a
   `s = ctx.sessions` variable isn't followed; a name the plugin guards with `respond_to?` is left), `boundary` (warn: a `Samagotchi::` name outside "Stable for bundles"; a shipped bundle's listed
   exceptions aside. On an installed bundle (`chi update`) only a name this chi no longer has is a row: the constant
@@ -339,8 +339,9 @@ Also shipped, not installed: dev (mcp, skills, source-links) (chi bundle install
   the merge itself, and `--force` replacing the file. A dry run and an automatic update
   (`update.auto`) show it and leave it, and so does a failed row or one with no place
   for it (a skipped system bundle). A memory that can't be read at a
-  newer version fails that bundle's row with the file's name. Hooks, rules and the plugin are replaced; an edited one didn't
-  load anyway (its sha no longer matched), the row says it was replaced, and
+  newer version fails that bundle's row with the file's name. Hooks, rules, the plugin and scripts are replaced. One
+  whose bytes are neither what the install recorded (nothing recorded counts as edited) nor the new version's is
+  edited: the row says `replaced edited hooks/x (a copy goes to the trash first)` (`would replace` in the plan), and
   a copy goes to the bundle trash first (`chi bundle trash`; `hooks/x`,
   `guardrails/x`, `plugin/x`, `scripts/x` inside the dir).
   A bundle of the same name from elsewhere (a zip, git) is skipped ("not from
@@ -801,8 +802,8 @@ also offline (from the saved records). `/recap` is in
 Switch](#runtime-model-switch-assist-mode).
 
 `/llm-context` shows the LLM context strategy, apply rule and budget the next
-turn runs under, each with where it came from (`the session`, `models: <key>`,
-`hosts entry '<name>'`, `llm_context.*`), and the session's own values.
+turn runs under, each with where it came from (`session`, `models: <key>`,
+`hosts.<name>`, `llm_context.*`), and the session's own values.
 `/llm-context strategy <none|stale|stale,forget> apply <payoff|next_request|turn_end>
 budget <tokens|64k|off>` sets the session's own (any of the three, in one line;
 `default` unsets one), and `/llm-context reset` unsets them all. A change is
@@ -1527,8 +1528,8 @@ CHI_REMOTE=studio chi context push claude-outbox ab12 < answer.json
 - `send --new` needs `--dir`, that machine's absolute path (no folder of this
   one is guessed); `--toolkit`, `--set` and `--parent-answers` are checked
   against that machine's config and bundles. `sessions list` lists every
-  project's sessions there (`--scope=project --cwd DIR` one project's) in the
-  `--live` text form. `context` takes the session ids (no default session),
+  project's sessions there (`--scope=project --cwd DIR` one project's), each
+  on the same line a list here prints. `context` takes the session ids (no default session),
   and a URL resolves through that machine's bundles.
 - That machine's config.yml decides what it checks for `send` and `answer`:
   a parent agent's `/continue yes` and options (`guardrails.parent_answers`),

data/docs/configuration.md

@@ -105,7 +105,9 @@ Behavior:
 - A key chi doesn't read warns at start, with the closest known key:
   `config: unknown key 'default.modle' (did you mean 'default.model'?)`.
   Names you choose under the maps below (host names, model ids) don't warn.
-- Environment variables and CLI flags win over config-file values.
+- Environment variables and CLI flags win over config-file values. A model's
+  own settings (`models:`, `hosts:`) layer in between: see
+  [Where a model setting comes from](#where-a-model-setting-comes-from).
 - An edit to the file needs no restart of `chi web`. A new worker reads the
   file when it starts; a running worker sees only settings whose readers check
   the file again (see [When a change applies](#when-a-change-applies)). The web
@@ -148,7 +150,7 @@ or `chi web` restart.
 | `default.model` | New session | Existing sessions keep their saved model; change one with `/model`. |
 | `default.input`, `no_default_input`, `no_interrupt` | Next CLI run | These set up that run's first prompt or turn limit. |
 | `default.max_tokens`, `max_tool_output_chars`, `memory.read_max_chars`, `read.*`, `execute.*` except `execute.description`, `image.*` | Next matching request or tool use | An operation already in progress keeps its resolved limits. |
-| `server.host`, `server.port`, `hosts.*` | Worker start | Includes host addresses, APIs, declared models and host-level settings. The web model picker refreshes `hosts:` on file change; a running worker does not. |
+| `server.host`, `server.port`, `hosts.*` | Worker start | Includes host addresses, APIs, declared models and host-level settings. Commands (`chi self`, `chi models`, the session lists) and chi web (its model picker, the session cards) read `hosts:` as it is now; a running worker keeps the hosts it started with until it restarts. |
 | `server.open_timeout`, `server.read_timeout`, `server.first_token_timeout` | Worker start | The worker's clients retain the timeouts set when they were built. |
 | `model_aliases` | Next model lookup | A session keeps its resolved model unless it is explicitly switched. |
 | `models.<key>.profile` | Session start or `/model` | It is resolved when that model is selected; editing it does not switch the current model's profile by itself. |
@@ -229,6 +231,35 @@ A few environment variables are not settings (no config.yml key, no flag):
 - `SAMAGOTCHI_LOG_STRICT=1`: an unknown log tag or a malformed log event raises instead of being dropped. The spec
   suite sets it, and a bundle's tests keep it (`Samagotchi::Testing::Sandbox`).
 
+## Where a model setting comes from
+
+A model's settings come in layers, and the first one set wins. Every surface reads them the same way: a turn,
+`/model` and `/stats`, `chi self`, the web's chips and the start page's ⚙ panel, and a session list's ctx %. A
+`models:` entry is looked up under each name the model goes by, the most specific first: the name as typed (an
+alias), the alias's target (`host:id`), the part after a host prefix, then the id the host is asked for.
+
+| Setting | Order, first set wins |
+|---|---|
+| `thinking` | the session's own (`/thinking`, `chi --thinking`) → `chi web --thinking` or `SAMAGOTCHI_THINKING_LEVEL` → `models:` → `hosts.<name>.thinking` → `thinking.level` in config.yml → `default` |
+| `reasoning_history` | the session's own (`/reasoning-history`) → `SAMAGOTCHI_REASONING_HISTORY` → `models:` → `hosts.<name>` → the api's default (`all` on `api: anthropic`, else `turn`) |
+| `steer_cut_after` | `SAMAGOTCHI_STEER_CUT_AFTER` → `models:` → `hosts.<name>` → `steer.cut_after` in config.yml → 20 |
+| `profile` | `--profile` or `SAMAGOTCHI_MODEL_PROFILE` → `models:` (an unknown profile warns, and the next name is tried) → `hosts.<name>.profile` → the server's chat template → the name → `qwen36` |
+| `sampling` | merged: `hosts.<name>.sampling`, then `models:` over it, key by key |
+| `vision` | `models:` → `hosts.<name>.vision` → what the server or the host's model list says |
+| `window_tokens` | the server's `n_ctx` → the host's model list → `models:` → `hosts.<name>.window_tokens` → `context.window_tokens` (`--context-window-tokens`, `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` or config.yml) → 256000 |
+| `llm_context_strategy`, `llm_context_apply`, `llm_context_budget_tokens` | each on its own: the session's own (`/llm-context`, `chi --llm-context…`) → `models:` → `hosts.<name>` → `llm_context.*` (`SAMAGOTCHI_LLM_CONTEXT_…` or config.yml) → the default |
+
+Two rules, both intended:
+
+- For thinking, reasoning_history, steer_cut_after and the profile, a process-wide override (a flag or an
+  environment variable) beats the model's own setting: it runs every model one way for a while.
+- For the window and the LLM context, the global key is the fallback whatever sets it: an environment variable
+  or a flag there doesn't beat a model's or a host's setting. (`steer.cut_after` from config.yml, too, comes after
+  the host's.)
+
+Where a value came from is named as `session`, `models: KEY`, `hosts.NAME`, or the config key or environment
+variable that set it.
+
 ## Model Server API
 
 Chi talks to a model server over HTTP in one of two ways, set by the host's `api:`:
@@ -1774,8 +1805,8 @@ its own). The first target is a long session such as a day-long coordinator, whe
   budget don't ask: they only decide when a batch goes in, and each batch's break comes as designed (`next_request`
   with staged edits pending moves a break the old rule makes by the end of the next turn anyway). The chip's Set and
   `--llm-context` on an attached or resumed session send `--yes`.
-- **Where to see it:** `/llm-context` (each value and where it came from: `the session`, `models: <key>`,
-  `hosts entry '<name>'`, `llm_context.*`), `/stats` (`llm context:`), the turn log (an `llm_context` record per
+- **Where to see it:** `/llm-context` (each value and where it came from: `session`, `models: <key>`,
+  `hosts.<name>`, `llm_context.*`), `/stats` (`llm context:`), the turn log (an `llm_context` record per
   turn that runs a layer or whose session set its strategy) and the web's chip. A woken worker's status line counts
   its saved context against the session's budget.
 
@@ -2336,6 +2367,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token, asked of this machine's 127.0.0.1 too (its `Local:` link carries a one-time code; `chi web --new-token` replaces the token). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |
 | `web.working_set` | `true` | yes | The stage view's working set: the files, memories and URLs a turn brought into the model's context, in a rail in the stage, a footprint as each finished turn's block summary and a `set N` chip in place of the mem chip; `false` brings the mem chip back. `?working_set=1` or `?working_set=0` on the page URL overrides it for that page load. See [CLI: the working set](cli.md#the-working-set). |
+| `web.reload_check` | `false` | yes | Opt-in: once each finished turn has moved into the history, the page reads the session again (one full read per turn end), draws that turn as a reload would and compares the two, strictly: a known divergence counts as a mismatch too. `chi web` logs one `reload_checked` line per check and a `reload_mismatch` line naming the kinds that differed, `excused` (the known divergences, `history_shape.js` `ACCEPTED`, that would explain them) and `explained` (all of them had one), with `turn_id`, `drawn` (the turn came back from its drawing, so a mismatch with `drawn: true` is a drawing bug) and the worker's version: counts only, never content. The count is `grep -c reload_mismatch` over `grep -c reload_checked` in chi web's log, split by `excused`. Cards are left out: a reload places them after the render, which the check doesn't run (the e2e reload checks compare them). Every open owner tab runs the check; `chi web` logs a turn's first report only, and starts over when it restarts. |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
 | `web.editor` | `vscode` | yes | What a file ref in `chi web` (a file tool row's title, a diff line) opens, for a viewer on this machine: a preset (`vscode`, `vscode-insiders`, `cursor`, `zed`) or a URL template with `{path}` and an optional `{line}`; `none` turns refs off. See [Opening files from chi web](#opening-files-from-chi-web). |
 | `web.start_dir` | the folder `chi web` runs in | | The folder `chi web` starts in (`chi web --start-dir DIR` for one run): its page (the printed link, a bare `/`, the LAN link and QR code, the Home Screen app) opens on that folder's project, outside a repo on every session, and a new session from the all view starts there; the header's project picker switches projects. `~` and a relative path (resolved from your home folder) work; one that isn't a folder stops `chi web` from starting. `chi web` never changes its own folder. See [CLI](cli.md). |

data/docs/guardrails.md

@@ -1392,7 +1392,8 @@ denies every call until the bundle is reinstalled.
 chi bundle install known-names    # or chi bundle install dev
 ```
 
-installs one `before_tool_call` hook and a short memory. A local model that
+installs a plugin with one `before_tool_call` hook (`chi.on`, priority 50; a
+`hooks/known_names.rb` file before known-names 0.2.0) and a short memory. A local model that
 once misspells a name inside a path (`jonathandoe` → `jonathndoe`)
 keeps copying the wrong spelling from its context, and every call after
 that fails. The hook knows the right names and compares strings: the
@@ -1449,10 +1450,13 @@ else goes to chi's own rules. It needs nah installed; see its README for the set
 
 ## Failing closed
 
-- A config hook with `required: true`, or a bundle `before_tool_call` hook with
-  `on_error: fail_closed`, that fails to load (missing, syntax error, or for a
-  bundle hook a sha256 that differs from the installed one) makes chi deny
-  every tool call. One that raises when called denies that call.
+- A config hook with `required: true`, a bundle `before_tool_call` hook with
+  `on_error: fail_closed`, or a bundle plugin its manifest marks `required: true`
+  (`plugin:` `required: true`, for a `chi.on(:before_tool_call, on_error:
+  :fail_closed)` guard, chi 0.157.0 or newer, [plugins.md](plugins.md#a-guard-that-fails-closed-on_error-fail_closed)),
+  that fails to load (missing, syntax error, an unmet `requires_chi`, or for a
+  bundle's file a sha256 that differs from the installed one) makes chi deny
+  every tool call. A fail-closed hook that raises when called denies that call.
 - Other hooks stay fail-open; a load failure is a warning.
 - Every load failure is shown once, at the start of the first turn
   (`guardrails> …` in the terminal, a red line on the web).

data/docs/hooks.md

@@ -145,8 +145,9 @@ they must never spend or permit. See
 [Guardrails](guardrails.md#answers-from-a-parent-agent). `effects:` needs a
 chi newer than 0.85.0 (an older one raises on the keyword).
 
-`event[:hook]` is the label the notices carry: `known_names.rb (bundle
-known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
+`event[:hook]` is the label the notices carry: `plugin.rb (bundle
+known-names)` for a plugin's `chi.on` hook (`<file> (bundle <name>)` for a bundle's `hooks/*.rb`),
+`audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
 `event[:notify]` also takes `fallback_for:`, what the line stands in for, so
@@ -465,6 +466,10 @@ change), as for every hook.
   (missing file, syntax error), chi denies every tool call and says why; if it
   raises as a `before_tool_call` hook, that call is denied. See
   [Guardrails](guardrails.md#failing-closed).
+- A plugin's `chi.on(:before_tool_call, on_error: :fail_closed)` (chi 0.157.0 or newer) is
+  the same for a bundle: a raise denies that call, and a plugin its manifest
+  marks `required: true` that fails to load denies every call. See
+  [plugins.md](plugins.md#a-guard-that-fails-closed-on_error-fail_closed).
 
 A hook that fails to load is reported as a `[samagotchi:hooks]` warning and
 once in the UI.
@@ -477,7 +482,7 @@ worker, on the plugins' surface, whatever its `on_error` (the same notice a
 `chi.on` handler gets):
 
 ```
-plugins> guardrail guardrails.rb (bundle known-names) before_tool_call hook failed (RuntimeError: boom):
+plugins> guardrail guardrails.rb (bundle my-guard) before_tool_call hook failed (RuntimeError: boom):
          it denies every tool call it guards, and its next failures are in each denial's reason
 ```
 
@@ -711,7 +716,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each but web-search in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Bundles](bundles.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Bundles](bundles.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Bundles](bundles.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Bundles](bundles.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Bundles](bundles.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Bundles](bundles.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Bundles](bundles.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Bundles](bundles.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Bundles](bundles.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Bundles](bundles.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Bundles](bundles.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Bundles](bundles.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Bundles](bundles.md#the-claude-peer-bundle)), `chi bundle install model-notes` (memories: reviewed model notes, see [Bundles](bundles.md#the-model-notes-bundle)), `chi bundle install decision-card` (a plugin: a long answer's question as a card, see [Bundles](bundles.md#the-decision-card-bundle)), `chi bundle install inline-widgets` (a plugin: prompt sections that teach the `chi-ui` blocks chi web draws, see [Bundles](bundles.md#the-inline-widgets-bundle)) and `chi bundle install web-search` (a plugin: a `web_search` tool through your SearXNG, in no profile, see [Bundles](bundles.md#the-web-search-bundle)).
+- Shipped bundles (each but web-search in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a plugin's `before_tool_call` hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a plugin's `after_turn` and `question_asked` hook: links source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Bundles](bundles.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Bundles](bundles.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Bundles](bundles.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Bundles](bundles.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Bundles](bundles.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Bundles](bundles.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Bundles](bundles.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Bundles](bundles.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Bundles](bundles.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Bundles](bundles.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Bundles](bundles.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Bundles](bundles.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Bundles](bundles.md#the-claude-peer-bundle)), `chi bundle install model-notes` (memories: reviewed model notes, see [Bundles](bundles.md#the-model-notes-bundle)), `chi bundle install decision-card` (a plugin: a long answer's question as a card, see [Bundles](bundles.md#the-decision-card-bundle)), `chi bundle install inline-widgets` (a plugin: prompt sections that teach the `chi-ui` blocks chi web draws, see [Bundles](bundles.md#the-inline-widgets-bundle)) and `chi bundle install web-search` (a plugin: a `web_search` tool through your SearXNG, in no profile, see [Bundles](bundles.md#the-web-search-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:
@@ -726,7 +731,8 @@ Lifecycle:
 chi bundle install source-links    # or chi bundle install dev
 ```
 
-installs one `after_turn` hook and a short memory. When the model's answer
+installs a plugin with one hook on `after_turn` and `question_asked` (`chi.on`, priority 90; a
+`hooks/source_links.rb` file before source-links 0.7.0) and a short memory. When the model's answer
 mentions a known source ref — a JIRA ticket, a GitHub issue, an internal
 wiki page — the web links it in the answer (below), and every UI shows one
 line right after the message:

data/docs/internals/bridge.md

@@ -16,6 +16,7 @@ rescues its own errors: an observer must never break the running turn.
 | `RingBuffer` | `ring_buffer.rb` | The last `ring_capacity` (256) raw events by `event_seq`, in memory, for a reconnect's replay. The capture observer feeds it. |
 | `TurnAccumulator` | `turn_accumulator.rb` | The turn in progress, folded from events. |
 | `CardStore` | `card_store.rb` | The last cards and notices, saved in `cards.json`, each anchored to its turn. |
+| `TurnDrawings` | `turn_drawings.rb` | Each finished turn as live drew it (`turn_drawings.jsonl`): written by the accumulator's `on_turn_end` hook, read by chi web's show. |
 | `CardPlaces` | `card_places.rb` | Pure: where `CardStore`'s entries sit in the messages the page draws (`turns_since`, and the `opening_id` stamp). |
 | `PendingCard` | `pending_card.rb` | `pending_card.json` `{id:, bundle:}`: the running turn's open card with actions (check-in's Nudge), written and removed with that card, so chi web's hub, which watches files and not workers, can notify. |
 
@@ -27,12 +28,19 @@ whose seq a cursor is) and its **secret**; both are published in `bridge.json` (
 
 A joining UI must draw a turn already half done, and the ring may have dropped its early events. The accumulator
 folds the event log into one hash, `current_turn`: the prompt, `turn_id`, origin, `at`, and ordered `parts`
-(generation, thinking, text, tool, input, steer, reminder, notice), plus `pending_question`. A tool part keeps its
-row fields (`ToolRowFields`), its output cut head-and-tail at `ToolOutputCut::WEB_PREVIEW_CHARS` so a joined row is the
-row a reload draws, and `elapsed_ms` while it runs (the accumulator times running calls itself, `clock:`). A
+(generation, thinking, text, tool, input, steer, reminder, notice, card), plus `pending_question`. A tool part keeps its
+row fields (`ToolRowFields`), its `tool_id`, its output cut head-and-tail at `ToolOutputCut::WEB_PREVIEW_CHARS` so a
+joined row is the row a reload draws, `elapsed_ms` while it runs (the accumulator times running calls itself, `clock:`)
+and, once finished, the event's `duration_ms` (its own clock only for an older worker's event that has none). A
 `notice` part holds the event of a row that is neither text nor a tool call (`TurnNotice::FIELDS`: a hook's notice,
 the "asking again" row, a steer's cut, a ✂ row, a question and its answer), so a join replays it through the handler
-that drew it live.
+that drew it live. A `card` part is a card the turn showed in its step (`in_turn`), its latest version in its first
+one's place; `replay_events` and `join_events` skip it (a running turn's join takes its cards from CardStore), and
+only `replay_events(turn, cards: true)` (a finished turn's drawing) replays it as its `card` event.
+
+At the terminal event, before clearing, the accumulator hands a deep copy of the turn and the end event to its
+`on_turn_end:` hook (the Bridge's `TurnDrawings#append`). The hook runs under the accumulator's mutex and the
+observer lock, so it never calls back in; an error is logged (`turn_end_hook_failed`) and the fold goes on.
 
 The turn is cleared on its terminal event (`Events::TURN_END`), the same event that brings its messages into the
 session, so a snapshot shows a turn in exactly one of the two places. Beside the turn it keeps what a snapshot also
@@ -40,10 +48,58 @@ needs and the messages lag: `queued` turns (`:turn_enqueued` until started, merg
 the idle `recap` (until a turn starts), a pending `continue_offer`, and the running turn's `working_set`.
 
 Three other users: `replay_events(turn)` turns a `current_turn` back into the live events that would have drawn it
-(the web's `snapshotEvents` replays them; `spec/shared/turn_snapshot.json` pins both sides); `messages_of` gives a
+(the attached TUI's join); `join_events` is the page's unfold of the same turn plus the queue behind it (its
+`turn_started` also carries `at`, `cut_after` and every author key, then a `turn_enqueued` per queued prompt and a
+`command_queued` per waiting command), which chi web's `GET /api/sessions/:id` sends as `replay` from the worker's
+snapshot (`from_wire` symbolizes it), so any worker's snapshot gives the page the same events
+(`spec/shared/turn_snapshot.json` pins it against turn_events.js `snapshotEvents`, the page's own fallback for one
+release); `messages_of` gives a
 plugin's `ctx.messages` the turn so far (`Engine#running_turn_messages`); `participant_turn?` tells `POST /turn` that
 a participant's review turn runs, so the owner's input queues behind it.
 
+## TurnDrawings
+
+A reload or a reconnect draws a finished turn from what live drew, not rebuilt from its saved messages: the
+accumulator's final fold of the turn (its parts in order, in-turn cards included) and the end event's display keys
+(`TurnDrawings::END_KEYS`), one JSON line per turn in `<session dir>/turn_drawings.jsonl`
+(`{v: 1, turn_id, kind, from, to, from_digest, to_digest, drawing, end}`, `TurnDrawings::Line`).
+
+- **The range comes from the Engine.** The end event's `kept_from`/`kept_to` (`Engine#end_turn`) name the turn's own
+  messages, `kept[from...to]`. No range (an older worker, a turn that kept nothing) or an empty one writes no line,
+  and the turn draws as before.
+- **Validity.** A line holds while the messages reach `to` and `messages[from]` and `messages[to - 1]` digest as the
+  line says (`TurnDrawings.digest`: role, content and time, one canonical form for the live symbol-keyed messages
+  and the saved, scrubbed ones). A rollback, a rolled-back failure or a prompt handed back drops it. Of overlapping
+  valid lines (a rollback, then a re-run that said the same) and of one turn id's lines, the newest wins
+  (`TurnDrawings.valid`).
+- **Writing.** The accumulator calls `TurnDrawings#append` at the end event, inside the observer delivery, so the
+  line is on disk before a stream writer (subscribed later) gets the end frame. That departs from SessionObserver's
+  "enqueue-only" note, as CardStore's save does: one append per turn end. It writes `"\n"` first when the file's last
+  byte isn't one (a torn line from a crash), then the line in one write; a failure is logged (`turn_drawing_failed`).
+  A part's output is the accumulator's cut (`WEB_PREVIEW_CHARS`); a diff is the one the saved `tool_diffs` have
+  (`TextDiff`'s cut); images are refs.
+- **Reading.** `TurnDrawings.read(dir)` skips an unknown `v`, a torn or broken line and one missing a field, and is
+  cached by the file's path, size and mtime. `#last` is the newest line this worker wrote or started from.
+- **The snapshot.** `Bridge#snapshot` (the snapshot and reset frames, `GET /snapshot`) adds `last_turn_drawing:
+  {drawing, end}`, `#last` as the file has it, not unfolded, when it holds against the snapshot's messages and its `to`
+  is their size (the last exchange); it is absent otherwise (no turn yet, a rollback, a Continue's note after it, a line
+  of another version, one over the 1 MB a restart reads back: `TurnDrawings.sendable?`). An attaching TUI unfolds it (`TerminalUI::JoinReplay`, `TurnAccumulator.replay_events`) and draws
+  that turn's rows through its `EventRenderer`, as a running turn's join does, then the end event's cancel or failure
+  line, else the saved answer; without it (or for a drawing that isn't the last prompt's turn: a reminder's, a
+  Continue's) the rows are rebuilt from the messages as before. `chi --remote` attaches through chi web's stream proxy,
+  which relays an owner's frames byte for byte, the field included. A participant never gets it: its stream's snapshot
+  is bare (`ParticipantView`). An older TUI ignores the field; an older worker sends none.
+- **The show.** chi web's full read with `?parts=1&drawings=1` (the page's) stamps each display item of a kind a
+  drawing draws (the opening, steps, steers, merged lines, the empty answer) in a valid range with `drawn: <turn_id>`
+  and drops its `parts` (its ✂ marks stay as `marks: {tool_id => edit}`), and sends `turn_drawings: {turn_id =>
+  {events, end}}`: `TurnAccumulator.replay_events(drawing, cards: true)`, the one unfold, in Ruby. A context note in
+  a range and a `!cmd`'s record are not stamped. Without `drawings=1` (an older page) the read is what it was.
+  CardStore lists an in-turn entry's turn as `of_turn`, so the page leaves a drawn turn's own rows and cards to its
+  drawing (`cards_place.js`). A live worker whose sidecar features lack `turn_drawings` (`TurnDrawings::FEATURE`:
+  an older one lists no `of_turn`) gets no drawings in the show: its turns all draw as before.
+- **Compat.** An older worker writes nothing (its turns fall back); an older chi web never opens the file. A fork
+  or a continue copies no drawings: its turns fall back. A one-shot run (no Bridge) writes none.
+
 ## CardStore
 
 The cards a plugin or the Engine shows (`Engine#show_card`), hook notices, load warnings (`:guardrail_warning`),
@@ -77,6 +133,9 @@ the "asking again" and steer-cut rows, ✂ rows and questions (with how they wer
   first while that line is still in the run, so a later release can drop the count. No stamp (the page counts `turns_since`) for
   an entry before every opening, after a line an older chi wrote with no id, or from a version 1 file (`base_since`). A rollback
   keeps today's rule: a rolled-back turn's cards name the opening before it.
+  The saved recap carries the same stamp: `saved_recap`'s `opening_id` (`RecapPlace.opening_id`, the id of the last
+  opening its `covered` messages hold, read at read time, so `recap.json` is unchanged), which the page places it after
+  (`recap_stamp.js`); an older worker's `saved_recap` has none, and the page counts `turns_since`.
 - **A turn that leaves nothing** is read, not told: an in-turn entry not `current` whose turn has no opening in the messages
   (a `!rollback`, a failed turn with nothing kept, a prompt stopped before the model) lists as a between-turns entry at its
   place, a card without its actions and a hook's notice without its step; its other rows, having no step to sit in, aren't
@@ -195,6 +254,22 @@ The Bridge exposes:
          "params":"path=notes.txt","event_seq":812}
   ```
 
+  Both tool events carry the run's `tool_id` (`ToolIds`, the id its output is saved under in the session's
+  `tool_ids`, handed out before the batch runs), and `tool_call_completed` carries `duration_ms`: the call's time from
+  the `tool_call_started` emit to its own, less an approval's `waited_ms`, rounded first (SessionMetrics' tool record
+  definition). It is the one duration every UI shows: the web's live row, the tool record a reload draws, the attached
+  terminal's line; each keeps its own clock only for an older worker's event without it. A long output's
+  `tool_call_completed` also carries `preview`: `ToolOutputCut.preview` of the capped output at `WEB_PREVIEW_CHARS`
+  (a `read`'s head, any other tool's head and tail), the text a reload's row has from the saved output
+  (`MessageParts#tool_part`; spec/tool_preview_parity_spec.rb pins the two). The web row and the accumulator's part
+  take it; the TUI keeps `output`.
+
+  An end event (`turn_completed`, `turn_canceled`, `turn_failed`) of a turn that kept messages carries `kept_from` and
+  `kept_to`: the turn's own messages are `messages[kept_from...kept_to]` of the session it leaves (`Engine#end_turn`;
+  `kept_from` is the conversation's size under the system head the turn may have added, before its reminders and
+  prompt). Small integers on the event only, never on a message; no client draws them (`Bridge::TurnDrawings` reads
+  them). An older worker's end event has neither.
+
   A `turn_completed` frame omits `result`; `turn_summary.output` carries the answer:
 
   ```
@@ -256,7 +331,9 @@ The Bridge exposes:
   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
+  A worker's start prunes the `input/removed/` and `input/settled/` tombstones and the drain's merge records
+  (`input/merged/<enqueued_id>` = `{into, at}`, written by `Worker#pending_input_drain` before it deletes a file it
+  merges; their own directory, which a 0.156 waiter never reads) 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