samagotchi 0.156.0 → 0.158.0

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:`:
@@ -1440,10 +1471,12 @@ test run (`SAMAGOTCHI_ENV`, `RACK_ENV`, `CI`). The day is stamped in `$XDG_STATE
 If an AGENTS.md file is present in the project root, samagotchi injects its
 contents into the system prompt under a "Project specific description:" section.
 The project root is the top of the git work tree chi runs in (a linked
-worktree's own checkout), or the current directory outside a repository.
+worktree's own checkout), or of the folder marked by `chi project init` it runs
+in (see [Projects without git](memory.md#projects-without-git)); outside both,
+the current directory.
 
-Started in a subdirectory, chi loads the chain: every AGENTS.md from the work
-tree top down to the current directory, outermost first. The first keeps the
+Started in a subdirectory, chi loads the chain: every AGENTS.md from the
+project's top down to the current directory, outermost first. The first keeps the
 plain header; each further one is headed with its directory, e.g. "Project
 specific description for pkg/:". Outside a repository only the current
 directory's AGENTS.md is read. Edits are picked up by a new process or a
@@ -1774,8 +1807,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.
 
@@ -2094,7 +2127,7 @@ are never sent to; `chi web push rm ID` removes them. From the Mac: `chi web pus
 shows a recent delivery (Apple keeps accepting pushes for it): if one stops getting notifications, switch it off and on
 there; the new subscription replaces the dead one.
 
-- **What a tap opens**: the session, in its own project's view (the all view for a session in no repo), whichever
+- **What a tap opens**: the session, in its own project's view (the all view for a session in no project: no repository or marked folder), whichever
   project the app was showing; an open app window moves there.
 - **What is sent**: the session's name and the reason ("needs approval", "needs an answer", "hit its step limit",
   "needs you", "turn failed", "done in N s"), never the question or the command, as the tab's notification on the
@@ -2336,9 +2369,10 @@ 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). |
+| `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 project (no repository or marked folder) 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). |
 | `web.participants.expires` | `7d` | | How long a participant's link lasts unless `chi share --expires` says otherwise: `Nh` or `Nd`, 1h to 30d. See [participants](internals/participants.md). |
 | `web.participants.cap` | `2.0` | | What a participant's turns, and the side calls they cause, may cost you in dollars unless `chi share --cap` says otherwise ($0 to $1000); at the cap their next comment is refused (429 `cap_reached`) and you get a notice. `chi share cap ID P DOLLARS` changes one grant's. |
 | `web.participants.queue` | `3` | | How many of a participant's turns may wait behind their running one (0 to 20); one more is refused (429 `too_many_turns`). |

data/docs/context.md

@@ -71,10 +71,12 @@ A source belongs to one session, or to a project:
 
 - A **session** source (`chi context add NAME … <id>`) is that session's
   alone and runs in the session's folder (the worktree it started in).
-- A **project** source (`--project`, inside a git repository) has **one
-  snapshot shared by every session of the project**: all worktrees of a repo
+- A **project** source (`--project`, inside a git repository or a folder
+  marked by `chi project init`) has **one snapshot shared by every session of
+  the project**: all worktrees of a repo (or subfolders of a marked folder)
   share the project, and the command runs in the project root (the main
-  checkout; the session's folder when the root is a bare git dir). Whichever
+  checkout, or the marked folder; the session's folder when the root is a bare
+  git dir). Whichever
   worker is due runs it; the others read the snapshot.
 
 So anything that depends on the branch or the checkout (a PR, `git status`,

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, which chi no longer loads) 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
@@ -1432,7 +1433,7 @@ run*, *Run as is*, *Deny*; with no one to ask (`--non-interactive`) or a
 dismissed question it rejects. A real near name (a folder `jondoe` next to
 user `johndoe`, a login one letter from another) is caught too: list it under
 `ignore:`. The hook is `on_error: log`: a bug in it warns and lets the call
-through. As with every bundle hook, a running worker picks it up after its
+through. As with every plugin, a running worker picks it up after its
 next start.
 
 The system prompt names the home directory once, with the advice to write
@@ -1441,7 +1442,8 @@ it as `~` or `$HOME`, so the model rarely has to spell it.
 ## An external guard: chi-nah
 
 [chi-nah](https://github.com/dm1try/chi-nah) is a bundle kept in its own repo (`chi bundle install
-https://github.com/dm1try/chi-nah`). Its `before_tool_call` hook asks
+https://github.com/dm1try/chi-nah`). Its plugin's `before_tool_call` hook (`chi.on`, chi-nah 0.2.0;
+0.1.x shipped it as a class-file hook, which chi no longer loads: `chi bundle upgrade chi-nah`) asks
 [nah](https://github.com/manuelschipper/nah)'s deterministic guards about every `execute`, `task_create`,
 `read`, `write` and `edit`: a call nah blocks (secret exfiltration, `rm -rf ~`, `git reset --hard`,
 `curl | sh`…) is denied with the guard's name and how the user pauses it (`nah nap <guard>`); everything
@@ -1449,10 +1451,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`, 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
+  plugin a sha256 that differs from the installed one) makes chi deny
+  every tool call. (An older chi's class-file bundle hooks don't load at all,
+  `fail_closed` or not: a not-required failure, [hooks.md](hooks.md#class-file-hooks-are-retired).) 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,
+`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
@@ -437,13 +438,13 @@ sources' refs in the reply that asks, and in the question's text and options).
 
 ## Settings
 
-A hook class whose `initialize` takes an argument gets its settings: **one
+A hook class (a config hook's; a plugin's class the same way, [plugins.md](plugins.md)) whose `initialize` takes an argument gets its settings: **one
 positional Hash with string keys** (`def initialize(settings = {})`;
 `initialize(**kw)` is not supported). A class whose `initialize` takes none
 is built bare. Defaults belong in the hook.
 
 ```yaml
-bundles:                 # per bundle, by name, for its hooks
+bundles:                 # per bundle, by name, for its plugin
   known-names:
     names: [jonathandoe]
     mode: reject
@@ -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.
@@ -472,22 +477,10 @@ once in the UI.
 Hook failures never break the engine loop — each hook is wrapped in its own
 try/catch.
 
-A bundle's `hooks/*.rb` file that **raises** tells you once per hook in a
-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):
-         it denies every tool call it guards, and its next failures are in each denial's reason
-```
-
-The label names the file, the bundle and the event, so one line per hook: a
-hook on a stream can't nag. `on_error` still decides what happens at every
-firing — `skip` logs nothing, `log` warns each time (a stream hook at most
-once a minute), a fail_closed `before_tool_call` hook denies the call — the
-notice is only added on top. A config hook (config.yml's own files) keeps its
-behaviour: no notice, just the log. A UI that joins later reads the same lines
-from `Engine#plugin_warning`.
+A plugin's `chi.on` handler that **raises** tells you once per hook in a
+worker, on the plugins' surface ([plugins.md](plugins.md)). A config hook
+(config.yml's own files) keeps its behaviour: no notice, just the log. A UI
+that joins later reads the same lines from `Engine#plugin_warning`.
 
 In the [bundle test kit](plugins.md#testing-a-bundle-experimental) a hook that raises raises
 `Testing::HookFailed` out of the call that fired it, under every `on_error`.
@@ -655,70 +648,46 @@ declared tool's call, with no `via:`; a direct `mcp_fs_read` fires as the `call_
 stands for (`tool: "call_tool"`, `args: {"tool" => "fs/read", "args" => {…}}`), as if the model
 had called `call_tool`.
 
-## Bundle Hooks (unified workflow bundle)
-
-Bundles can ship executable guardrails alongside memories. A bundle with hooks lives as a directory with a `hooks/` subdirectory (flat, basename-keyed):
-
-```
-my-bundle/
-  manifest.yml
-  identity.md
-  hooks/
-    guardrails.rb   # class Guardrails; def call(event); ...; end; end
-    audit.rb
-```
-
-`manifest.yml` may carry an optional `hooks:` map (both `files:` and `hooks:` are optional; a bundle may carry only one):
+## Bundle hooks
 
-```yaml
-name: code-review-workflow
-version: 1.0.0
-scope: project
-files:
-  identity.md: sha256:abc...
-hooks:
-  guardrails.rb:
-    sha256: 1234...
-    event: before_tool_call
-    on_error: fail_closed   # skip (default) | log | fail_closed (before_tool_call only)
-    priority: 10
-  audit.rb:
-    sha256: 5678...
-    event: after_tool_call
-    on_error: log
-    priority: 100
-trust_level: reviewed        # reviewed | trusted | experimental (default)
-requires_chi: ">= 0.12.0"    # optional: a gem-style requirement, as for plugins
-needs: [gh]                  # optional: outside commands the memories use (docs/memory.md#bundles-that-need-outside-commands)
-```
+A bundle hooks events from its `plugin.rb` with `chi.on` (next to its
+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, and `chi.on(:before_tool_call,
+on_error: :fail_closed)` makes a guard that fails closed.
 
-Notes:
-
-- Hook key = basename (flat under `hooks/`). No subdirs in v1.
-- `event` is required for auto-registration; a hook with no event is skipped.
-- `events: [after_turn, question_asked]` (a list, in place of `event:`) registers the hook for each event it
-  names: **one** instance serves them all (its state is shared), and `#call` tells them apart by
-  `event[:type]`. `event:` and `events:` together, or an `events:` that isn't a non-empty list of event names,
-  is refused at install (`hooks: <file>: …`). `on_error: fail_closed` applies to its `before_tool_call`
-  registration only. Needs chi newer than 0.97.0 (an older chi installs the hook with no event and never loads
-  it): set `requires_chi`.
-- `sha256` is integrity (not authenticity). No signing in v1. Install records the sha256 of the copied file; at `Engine.new` a hook whose file differs is not loaded (reinstall the bundle after editing one by hand).
-- Hook code is the bundle author's source of truth: on upgrade, hooks are overwritten; if the installed file was locally modified, a warning is emitted (`was locally modified; overwriting`).
-- `on_error` defaults to `skip` for every event, `:before_tool_call` included: a raising hook is silent and the call goes ahead. `log` warns. `fail_closed` (only on `:before_tool_call`; on any other event it acts as `skip`) denies the call the hook raised on. Choose `fail_closed` for a hook that is a guardrail, whose failure should stop tool calls rather than let them through.
-- `requires_chi`: when this chi doesn't meet it, none of the bundle's hooks load (each is reported, `not loaded: it requires chi …`), as for a [plugin](plugins.md#loading-and-when-it-fails).
-- A `fail_closed` `:before_tool_call` hook is required: if it is missing, fails to load, its sha256 differs or chi doesn't meet the bundle's `requires_chi`, chi denies every tool call until it is fixed.
+- Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order. Bundle hooks are process-scoped: they survive the per-turn `clear_hooks` (only plain hooks are cleared).
+- Settings: the plugin's class gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship YAML rules in `guardrails/*.yml`; see [Guardrails](guardrails.md#the-guardrails-bundle).
-- 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)).
-- 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:
-
-- `chi bundle install <source>` copies the hook files its manifest's `hooks:` map lists (only those; with no `hooks:` map, every `hooks/*.rb`) to `$XDG_CONFIG_HOME/samagotchi/memories/.bundles/<name>/hooks/` (`$XDG_CONFIG_HOME` defaults to `~/.config`) and persists metadata + `trust_level` + `source_commit` (git HEAD) to provenance. `install --dev <dir>` links them to `<dir>`'s files instead, with no sha256 check ([cli.md](cli.md#writing-a-bundle-new-test-check)).
-- `Engine.new` loads `config.yml` hooks first, then bundle hooks via `MemoryBundle::Provenance.each_installed(holding: :hooks)` → `Hooks::BundleLoader.load`. Bundle hooks are process-scoped (they survive the per-turn `clear_hooks`; only plain hooks are cleared). Experimental bundles emit a one-line startup warning.
-- `chi bundle status`, `diff`, `uninstall`, `build` are hook-aware (counts, metadata, removal).
+- 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 runs its plugin at `Engine` startup. Only install bundles you trust, as you would a gem.
+
+### Class-file hooks are retired
+
+Bundles used to ship hooks as class files: `hooks/*.rb` with a `hooks:` map in
+`manifest.yml` (`event:`, `on_error:`, `priority:`, `sha256:`). chi no longer
+installs or loads them:
+
+- Installing or upgrading a source that has a `hooks:` entry or a `hooks/*.rb`
+  file is refused (`hooks: class-file bundle hooks are retired: …`), its
+  `--dry-run` too; `chi bundle check` reports it as `hooks-retired`. An empty
+  `hooks: {}` is fine.
+- A bundle an older chi installed with hooks keeps its memories, rules, plugin
+  and scripts. Its hooks don't load: the first turn says so (`hooks (bundle X)
+  failed to load (class-file bundle hooks are retired: …)`, not a required
+  failure, so tool calls still run), `chi bundle status X` lists them under
+  `Hooks (N): not loaded`, and `chi update` adds a `hooks-retired` row for a
+  bundle chi doesn't ship.
+- The next install or upgrade from a source without hooks removes the old
+  `hooks/` (an edited hook, or a file the record doesn't know, is copied to
+  the trash first; a dev link never): `Removed (chi no longer loads
+  class-file bundle hooks): hooks/x.rb`, and the dry run and `chi update`'s
+  plan say so. `chi bundle uninstall` still removes them the same way.
+- To port one, move the class's `#call` into a `chi.on(event)` block of the
+  bundle's `plugin.rb` (one block per event; `on_error: :fail_closed` for a
+  fail_closed guard, with `plugin: required: true` in the manifest), then drop
+  `hooks/` and `hooks:`. known-names 0.2.0, source-links 0.7.0 and chi-nah 0.2.0
+  are ported examples.
 
 ## The source-links bundle
 
@@ -726,7 +695,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:
@@ -801,7 +771,7 @@ source is skipped whole (its partial matches are discarded) with a warning,
 and the others still report. An entry with neither `prefix:` nor `pattern:`,
 or a pattern that does not compile, is skipped with a warning at load. The
 hook is `on_error: log`: a bug in it warns and the turn is unaffected. As with
-every bundle hook, a running worker picks it up after its next start.
+every plugin, a running worker picks it up after its next start.
 
 ### Placeholders, and the project's own repo
 

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`),
@@ -69,7 +125,7 @@ the "asking again" and steer-cut rows, ✂ rows and questions (with how they wer
   comes mid-turn but isn't the turn's (an anytime command's, such as `/btw`) goes after that turn (`during`), and so does a
   between-turns notice. A card with an earlier card's id replaces it in place and keeps its anchor. A `list` with no messages
   (`?cards=1`'s bodies, `chi bundle try`'s trace) has no `turns_since` and no `opening_id`.
-- **The stamp.** Next to `turns_since`, an entry lists `opening_id` (`CardPlaces#opening_of`): the id of the opening its count
+- **The stamp.** Next to `turns_since`, an entry lists `opening_id` (`CardPlaces#opening_of`, one `Steer.opening_stamp` rule with the recap's): the id of the opening its count
   reaches, the one it comes after: a prompt's `turn_id` (a wake note's too), or `/continue no`'s reason line's `opening_id`. It is
   resolved at `list` time from the same anchor (an entry's own turn often has no bubble: a Continue, a failed or rolled-back turn),
   so the stamp and the count always name one place, and the page finds it by the bubble (`card_stamps.js`: `data-turn-id`, or `data-opening-id` on a wake's note or a reason line), not by counting
@@ -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