samagotchi 0.154.1 → 0.156.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9533994f61b5607aef4d2dc6318cd6e885a0331c163643bd06d3c16f5e6f03c0
-  data.tar.gz: b768811c50bb587fcf4d16696ab69b857c75168067fd521270d871954169874e
+  metadata.gz: e545b9da4004e996e2cdee4f53d2cf0a181a47b695fbcb18ca1037e77da6b1cb
+  data.tar.gz: 10cb3b94093ab0f0e7d285a2f405577be8fc61f26029a005754a078875d8ebdc
 SHA512:
-  metadata.gz: 2064776b06d42184107924bc44391f46681d755437e2c98a2e7c24205e900aba33bd8d3d792c7cea4dd6bdbf2813870395112db7315dbec33f92e198267c4ddc
-  data.tar.gz: a826305fa133e9ca4d1bd62e112ca7464fcf932f91292dc4112286e7f8f501c167fc18ccfeeb12dd24bec649e24636c810a715417cac45f454a19b4ba56f2b05
+  metadata.gz: f20b956f443a5a04680d2a7a162e3a9d44f9b8a66d0855f2827421420a7f8a1053ad01769ff140c442fded2e6cdf58b41f0b37f6a22b7849fcb463d5fdb2b22e
+  data.tar.gz: a08049e4ab152265163ea53327655064a1c2415b19c695e03dd21d3b01488453824cb59451fb333618ed1aefc334e97b10b4780cfdee02dd916853e37069858a

data/CHANGELOG.md

@@ -8,6 +8,32 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.156.0] - 2026-11-08
+
+### Changed
+
+- An id or prefix that names no session is refused in one wording everywhere: `no session ID` (the CLI commands, `chi --resume`/`--attach`, chi web's 404s and the session tools), where some said `Session not found: ID`. A `chi --remote` command shows it the same against an older chi web.
+
+### Fixed
+
+- `chi sessions list` shows a session whose worker died mid-turn as idle, as chi web does, instead of running (the plain and the `--live`/`--cwd` listings; with `--remote`, once that chi web runs this release).
+
+Update with `chi update`.
+
+## [0.155.0] - 2026-11-07
+
+### Added
+
+- The inline-widgets bundle (in the `dev` profile, `chi update`): it teaches the model the `chi-ui` blocks chi web draws, so an answer that leaves you several things to decide comes with picks that fill your reply, and a "how does this work" answer with a walk you step through. The terminal shows the block's YAML; a delegate child and a `-p --non-interactive` run don't get it.
+- `chi bundle check` lists a bundle's prompt sections among what it registers.
+
+### Fixed
+
+- At the very start of a turn, a plugin's `ctx.turn_author`, a hook's `author:` and `/objectives` could still see the previous turn (its participant, its conversation); they now see the turn that just started.
+- chi web's session bar no longer slides its time and speed chips under the buttons with a long model name: the model name shortens, the buttons move to their own line together, and on a narrow window the ctx/speed/time chips get a line of their own instead of being cut off.
+
+Update with `chi update` (the dev profile 0.7.8, inline-widgets 0.1.0 new).
+
 ## [0.154.1] - 2026-11-07
 
 ### Fixed
@@ -5772,7 +5798,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.154.1...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.156.0...HEAD
+[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
 [0.154.0]: https://github.com/dm1try/samagotchi/compare/v0.153.0...v0.154.0
 [0.153.0]: https://github.com/dm1try/samagotchi/compare/v0.152.0...v0.153.0

data/bin/chi

@@ -459,7 +459,7 @@ begin
   # Ctrl-C cancelled it.
   exit 1 if %i[turn_failed empty_answer iteration_limit].include?(ended)
   exit Samagotchi::CLI::Exit::INTERRUPTED if ended == :interrupted
-rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFound, Samagotchi::ModelProfile::MissingModel,
+rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::Session::NotFound, Samagotchi::ModelProfile::MissingModel,
        Samagotchi::Toolkit::Refused => e
   warn "Error: #{e.message}"
   exit 1

data/docs/architecture.md

@@ -101,10 +101,11 @@ terminal renders the events it gets over the Bridge.
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, model↔tool loop (`run_turn`). No terminal coupling. |
 | UI | `Samagotchi::TerminalUI`, `TerminalUI::AttachLauncher` / `AttachedLoop` | `TerminalUI`: the `--non-interactive` one-shot host, its own `Engine`. The attached TUI (every interactive `chi`): a client of the session worker's Bridge, no `Engine`. |
 | Model loops | `KernelLoop` (via `LLM::NativeBackend`), `LLM::ChatLoop` | The model↔tool loop: raw prompt, or a chat API (OpenAI chat, Anthropic Messages), chosen per host (see below). |
+| Turn | `TurnContext`, `TurnState`, `Engine::Turn` | One turn's frozen `TurnContext` (id, session, origin, author, participant mode, controller, folders, git facts, settings, model key/name and the tool surface (`Tools::ToolSurface`) from `generate`): built by `Engine#begin_turn`, published with the running flag by `TurnState` (the only way another thread reads the running turn: `Engine#turn_context` / `#last_turn_context`), handed explicitly down the tool path (`ModelBackend#complete(context:)`, `ToolRunner#run`, `Guardrails::Gate#evaluate`, `KernelLoop#dispatch_tool_call`). `Engine::Turn` keeps only the lifecycle state ([internals/engine.md](internals/engine.md), "Turn and TurnContext"). The turn stages (`TurnStages::ToolkitSuggestion`, `TurnStages::ContextJudge`, `TurnStages::Objectives`, `TurnStages::Warmup`, `TurnStages::VerifyAnchors`, `lib/samagotchi/turn_stages/`): the steps that keep state across the turn, built from the Engine-lifetime objects and called by name from the turn's skeleton with the values of the call (a `SystemOne::Recorder`, the sessions dir), not callbacks into the Engine (internals/engine.md, "Turn stages"). |
 | Adapters | `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | Raw-prompt servers, the OpenAI chat API, Anthropic's Messages API, and the HTTP they share. |
 | Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, delegate/delegate_result, ask_user_question, reminders, send_note, list_sessions, context_read, objectives, forget_outputs, find_tools/call_tool (the tool index), plus runtime/output-guardrails. |
 | Bundles | `lib/samagotchi/memory_bundle/*`, `BundleCommand` | `chi bundle`: install/upgrade (3-way, with a text merge of edited memories), build, uninstall; the install record under `.bundles/<name>/` that the hook, guardrail and plugin loaders read ([internals/bundles.md](internals/bundles.md)). |
-| Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` forks/spawns one worker process per session; its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. The spawned process (own process group) forks the worker, which `setsid`s and is reparented to init once its starter exits (it waits until the worker holds `owner.lock`, so the spawner's `Process.detach` waiter tells a starting worker): nothing that walks the spawner's process tree reaches it (`SAMAGOTCHI_WORKER_DETACH=1`, `detach_from_spawner`). The lock's pid is the worker's; `spawn`'s `child_pid` is its starter's. |
+| Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` (`session_manager.rb`, its parts in `session_manager/`: spawn · worker_command · listing · delivery · lifecycle · removal · emptiness) forks/spawns one worker process per session. The worker process's main (owner lock, detach, signals, project env, what it does as it leaves) is `WorkerBoot` (`worker_boot.rb`), which SessionManager loads only as a worker boots (its `run_session_loop` forwarder); its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. The spawned process (own process group) forks the worker, which `setsid`s and is reparented to init once its starter exits (it waits until the worker holds `owner.lock`, so the spawner's `Process.detach` waiter tells a starting worker): nothing that walks the spawner's process tree reaches it (`SAMAGOTCHI_WORKER_DETACH=1`, `detach_from_spawner`). The lock's pid is the worker's; `spawn`'s `child_pid` is its starter's. |
 | Web | `Samagotchi::Web::App`, `Samagotchi::Web::Server`, `Samagotchi::Web::SessionHub` | Rack+WEBrick on one port, `127.0.0.1:4567` (index.html + `/api/*` + SSE); with `web.host: lan` also on this machine's LAN address, behind an access token (`Web::Lan`, `Web::Token`). The hub is chi web's projection of the session list, pushed to every tab over `GET /api/events`. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File `sessions/<uuid>.json` + sidecar `input/`/`output/`; retention 14d/500, `updated_at desc`, lazy sweep. |
 
@@ -161,10 +162,12 @@ Unchanged: `ContextProviders`' `{ruby}` (`RbConfig.ruby`: the home's ruby inside
 project env below, so a `mise env` that sets GEM_HOME reaches it), `chi bundle
 try/test/check` (`-I LIB_DIR`), hooks (in-process). The worker's boot string, `run_session_loop(id, state_dir:)` and
 `SAMAGOTCHI_BOOT_FALLBACK` stay the cross-version contract (`spec/worker_contract_spec.rb`): the home only adds the
-prelude in front. An older chi that wakes a session doesn't read home.json and starts its worker as before.
+prelude in front. The string names `SessionManager.run_session_loop`, which only forwards to
+`WorkerBoot.run_session_loop`, the worker's main; the string switches to `WorkerBoot` one release later, and the
+forwarder goes the release after that. An older chi that wakes a session doesn't read home.json and starts its worker as before.
 
 **The tools a worker runs** follow the project, not the boot, and only they do: a spawned worker
-(`WORKER_PROCESS_ENV`; never an in-process loop) calls `ProjectEnv.compute` in `run_session_loop`, after the owner
+(`WORKER_PROCESS_ENV`; never an in-process loop) calls `ProjectEnv.compute` in `WorkerBoot.run_session_loop`, after the owner
 lock and before `Worker.new`, and installs the result (`ProjectEnv.install!`; a frozen `ProjectEnv::Overlay`,
 `{key => value or nil}`). Its ENV is never written: chi's own process (LLM calls, `HostKeys`, Net::HTTP proxies,
 Config, Paths, hooks, plugins) keeps the spawner's env. The overlay is the session folder's `mise env -C DIR --json`
@@ -499,6 +502,8 @@ verbatim) and the fields its class is built from, so a remote client raises the
 `scratch` (`ArchiveRefused`: `session_id`, `reason`, `busy_id`), a restart's `held`/`not_running`/`unsupported`/
 `failed` (`RestartRefused`: `session_id`, `reason`, `version`), a continue's `continued`/`open_children`/`folder_gone`
 (`SessionContinue::Refused`: `session_id`, `reason`, `ids`) and `ambiguous_id` (`Session::AmbiguousId`: `ids`).
+A session an id names none of is `404 not_found` with `Session::NotFound`'s words (`no session X`, `#session_not_found`):
+every lookup goes through `Session.resolve!` (an id or a unique prefix), and every surface shows that one message.
 
 ## Model loops and adapters
 
@@ -519,7 +524,7 @@ on every read, never kept, since config.yml and a model listing can move it with
 
 Both return an `LLM::ModelResult` and emit the same stream events; tool calls in
 both go through `ToolRunner` (events, hooks, veto, output cap) and
-`KernelLoop#dispatch_tool_call`. Every format's built-in calls (Gemma, Qwen,
+`KernelLoop#dispatch_tool_call`, given the turn's `TurnContext` as an argument. Every format's built-in calls (Gemma, Qwen,
 chat `tool_calls`) are built by one table, `Tools::BuiltinCalls`, from the
 parsed `{name, args}` (derived from `TOOL_SCHEMAS`), so a call looks the same to
 hooks and tools whichever model made it. Both loops' `generation_chunk` carries
@@ -608,8 +613,8 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 
 | Component | Main file(s) | What it is |
 |---|---|---|
-| Worker | `worker.rb` (`worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`, `worker_wakes.rb`, `worker_task_wakes.rb`, `task_watch.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns and the wake turns nobody typed (delegate reports, a background task that finished unseen: [Finish wake](internals/background-tasks.md#finish-wake), attached context), exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). The session is saved from the turn's thread, Bridge threads and a signal's thread; `Session#save` takes a per-session lock around its snapshot and write, so an older snapshot never lands over a newer one. |
-| Config | `config.rb`, `config/restart_watch.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)); the notice a worker or chi web gets when config.yml changes a setting it reads only at its start. |
+| Worker | `worker.rb` (`worker_boot.rb`, `worker_idle_exit.rb`, `worker_inbound.rb`, `worker_signals.rb`, `worker_wakes.rb`, `worker_task_wakes.rb`, `task_watch.rb`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns and the wake turns nobody typed (delegate reports, a background task that finished unseen: [Finish wake](internals/background-tasks.md#finish-wake), attached context), exits when idle. A spawned one traps TERM, HUP and INT (`WorkerSignals`, installed by `WorkerBoot.run_session_loop` when `SAMAGOTCHI_WORKER_PROCESS=1`): the running turn stops as a Stop with reason `signal`, is saved, and the worker leaves (`:signal`, exit 0; a new worker only for input already queued). A running turn is checkpointed at its iteration boundaries (`TurnCheckpoint`, the `interrupted_turn` mark), and the next worker settles a turn its predecessor died in (`TurnCheckpoint.settle`). The session is saved from the turn's thread, Bridge threads and a signal's thread; `Session#save` takes a per-session lock around its snapshot and write, so an older snapshot never lands over a newer one. |
+| Config | `config.rb`, `config/restart_watch.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)); the notice a worker or chi web gets when config.yml changes a setting it reads only at its start. With `log.rb` it is the bottom layer: nothing it references reaches back to it, so `hosts:` and `models:` entries parse next to their types (`HostConfig.all`, `ModelSettings.all`). |
 | 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)). |
@@ -636,7 +641,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Participants | `participants.rb` (`Participants`, the `participants.json` sidecar), `share_command.rb` (`ShareCommand`, `chi share`), `session_participants.rb`, `participants_watch.rb`, `grants.rb` (`Grants`), `participant_exposure.rb` (`ParticipantExposure`), `web/principal.rb` (`Web::Principal`), `web/participant_access.rb` (`Web::ParticipantAccess`: the participant's gate and routes), `web/participants_admin.rb` (`Web::ParticipantsAdmin`: the owner's invite, list, revoke, cap and Apply routes), `web/participant_review.rb` + `web/participant_view.rb` (`Web::ParticipantReview`, `Web::ParticipantView`), `redact.rb` (`Redact`, `Redact::Viewer`: the redaction every string a participant gets passes, also the Engine's Verify quote check), `web/participant_stream_filter.rb`, `guardrails/review_boundary.rb` + `guardrails/review_paths.rb` | The people or agents an owner invites to review one session through chi web: their grants and gate, what they read, their read-only review turns ([internals/participants.md](internals/participants.md), [guardrails.md](guardrails.md)). |
 | Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows); `session_metrics/cost.rb` (`SessionMetrics::Cost`): the spend `ctx.cost` reads; `session_metrics/usage.rb` (`SessionMetrics::Usage`): the work `ctx.usage` reads. `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
-| Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
+| Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`), `tools/tool_surface.rb` (`ToolSurface#left_out`, read by the prompt and `/toolkit`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |
 | Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`), `tools/deferred_tools.rb` | `find_tools` and `call_tool`: the tools a session knows but doesn't declare one by one (an mcp bundle's servers through `chi.tool_source`, the built-ins its toolkit leaves out), searched and called by name ([plugins.md](plugins.md)). On `api: anthropic` they also go out deferred, a hit loads its matches and the model calls them by name ([internals/anthropic.md](internals/anthropic.md)). |
 | Tool output cut | `tool_output_cut.rb` (`ToolOutputCut`), `tool_output_files.rb` (`ToolOutputFiles`) | A tool's output over `max_tool_output_chars` (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)). |

data/docs/bundles.md

@@ -1358,3 +1358,24 @@ bundles:
     timeout: 120       # seconds the side request may take (a number)
     max_tokens: 300    # the side answer's limit
 ```
+
+## The inline-widgets bundle
+
+`chi bundle install inline-widgets` (or the `dev` profile) installs the bundle shipped with chi. It is written only against
+this API (`lib/samagotchi/bundles/inline-widgets/plugin.rb`) and has no settings, commands or memories: it adds two
+[prompt sections](plugins.md#chiprompt_sectionname--ctx---and-chiprompt_changed) that tell the model chi web draws
+```` ```chi-ui ```` blocks ([the blocks](internals/inline-widgets.md)).
+
+- **picks**: when an answer leaves you two or more things to decide (review findings, a plan's open questions), a row
+  per item with its options as buttons, the recommended one picked to start with, a note per row, and **Fill reply**,
+  which puts your picks in the composer. Nothing is sent until you send it.
+- **walk**: a scenario you step through: who does what, what you see, what happens behind it, with a fork's cases to
+  choose from.
+- **Where it draws**: chi web, in the answers. The terminal shows the block's YAML, and a block chi can't read stays
+  YAML with a short note under it.
+- **Where the prompt has none**: a delegate child (its parent reads the report, nobody sees it drawn) and a one-shot
+  `chi -p … --non-interactive`. `/stats` lists the sections a session's prompt holds: `picks (inline-widgets), walk
+  (inline-widgets)`.
+- **Cost**: about 2,900 characters in the stable part of the prompt, the same at every build, so the prompt cache keeps.
+- **Uninstall**: `chi bundle uninstall inline-widgets` takes the sections out of new sessions' prompts (a session you
+  have open needs `chi sessions restart ID`); blocks already in a history still draw, since the drawing is chi web's own.

data/docs/cli.md

@@ -158,7 +158,7 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   bundle chi doesn't ship), `clash` (warn: a name chi ships, or one installed from elsewhere; the sandboxed install
   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 and peer source), `hook-event` (warn: a `chi.on` event chi
+  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
   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

data/docs/guardrails.md

@@ -410,7 +410,7 @@ under the owner's guardrails, as the owner's own turns do: the rules, the
 protected paths and every approval the owner already granted apply, and an ask
 goes to the owner. It is a pair turn only when all three hold
 (`ParticipantMode.for_turn`, decided once at the turn's start:
-`GuardrailWiring#turn_mode`): the session has no `review:` key, its worker
+`GuardrailWiring#begin_turn`, into the turn's `TurnContext#participant_mode`): the session has no `review:` key, its worker
 names the `pair_turns` feature, and the participant's grant was issued with
 `mode: pair`, which chi share and the web's Invite stamp only when the warning
 they showed said their turns act. A grant from before, or one issued while an
@@ -690,7 +690,7 @@ runs with the owner's rules or System 1's auto-allows. The mode is decided once,
 at the start, from their grant's mode there (`ParticipantMode.live_for`) and
 saved on the child (`verify_fresh.mode`): `review` keeps every turn of it
 inside `ReviewBoundary` (read only), `pair` inside `PairBoundary`.
-`GuardrailWiring#turn_mode` reads the saved mode and never looks it up again,
+`GuardrailWiring#begin_turn` reads the saved mode and never looks it up again,
 and every turn of the child carries the participant as its author, whoever
 started it, so the boundary can't fall away for a turn the owner typed into it
 or for an author lookup that finds nobody (the child has no

data/docs/hooks.md

@@ -711,7 +711,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)) 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 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:

data/docs/internals/anthropic.md

@@ -36,7 +36,7 @@ Paths are under `lib/samagotchi/llm/`.
 | `anthropic_wire.rb` | `AnthropicWire`: ChatLoop's wire messages as Messages' `system` and `messages`, the two breakpoints, tool ids and names |
 | `anthropic_assembly.rb` | `AnthropicAssembly`: a response from a whole body (`.from_message`) or stream events (`#add`), its usage in the OpenAI shape |
 | `dialect.rb` | `Dialect` (`STANDARD`, `FIREWORKS`): what a provider's `/v1/messages` does differently |
-| `../tools/deferred_tools.rb` | `Tools::DeferredTools.list`: the tools a request declares deferred (Deferred tools) |
+| `../tools/deferred_tools.rb` | `Tools::DeferredTools.list`: the tools a request declares deferred, from the turn's `ToolSurface` (Deferred tools) |
 | `prompt_cache.rb` | `PromptCache.control`: the `cache_control` a breakpoint carries (`cache.ttl`) |
 | `chat_loop.rb` | `ChatLoop#replay_blocks`, `#reasoning_history`'s floor, `Run#with_thinking` (saves `anthropic_content`), `#settle_dropped_thinking!` |
 
@@ -222,10 +222,10 @@ ones: the model sees their names only when something loads them, and the API acc
 `AnthropicMessages#loads_tools?(model)` says whether a request does this: the dialect's `tool_loading`, unless the
 host refused it for that model.
 
-`ChatLoop#tool_definitions(conversation, model:)` appends them (`Tools::DeferredTools.list`) only on such an
+`ChatLoop#tool_definitions(conversation, model:)` appends them (`ToolSurface#deferred_for`) only on such an
 adapter, and only with at least one tool declared (Messages wants one). The list, per request:
 
-1. the built-ins and plugin tools the toolkit reaches (`Registry#reachable_names`), in registry order;
+1. the built-ins and plugin tools the toolkit reaches (`ToolSurface#index_only`), in registry order;
 2. the tool index's source tools while `call_tool` is declared (`ToolIndex#deferrable`, via
    `Registry::Index#deferrable`): callable, the only tool with its acts_as, a name Messages takes, no registered
    tool's name; by acts_as (`mcp_<server>_<tool>`), sorted by name;
@@ -247,7 +247,7 @@ load nothing). `KernelLoop#dispatch` passes them on (`dispatched[:loaded]`), `To
 result's `loaded:` names among them as a tool_result holding only
 `{"type": "tool_reference", "tool_name": …}` blocks (Messages takes no other content beside a reference), followed by
 a sibling text block: `Loaded: a, b. Call them directly by these names.`, then the result's text without its
-`Call one with call_tool(…)` line (`ToolIndex::CALL_HINT`; the saved result keeps it). With that line and a trailing
+`Call one with call_tool(…)` line (`Tools::IndexHint::CALL_HINT`; the saved result keeps it). With that line and a trailing
 "(call_tool works too)", Sonnet and Haiku 5.5 went through `call_tool` 2/2 live; without, 5/5 called the tool by
 name. A result whose names aren't deferred here (declared since, or no tool loading) goes as plain text. The sibling
 text is never marked; when breakpoint #2 falls on such a tool_result, it goes on its last reference.
@@ -270,7 +270,7 @@ sets `:tool_changes` for the model: the retry and every later request drop the s
 
 A direct call of a deferred tool runs whether something loaded it or not (the API doesn't check): the Engine sets
 `TurnSettings#loads_tools` from the turn's final model (after the before_turn hooks), and then `ToolRunner#run` and
-`KernelLoop#dispatch` take a reachable built-in or plugin tool by its own name (`Registry#indexed`) through the normal gate, and wrap
+`KernelLoop#dispatch` take a reachable built-in or plugin tool by its own name (`ToolSurface#entry_for`) through the normal gate, and wrap
 an MCP tool's acts_as into the `call_tool` call it stands for (`ToolIndex#wrap`): `call_tool`'s row, rules and
 approvals. A reload rebuilds that wrapped call from the saved one (`BuiltinCalls.wrap_saved`). Each such call is
 logged (`tool_direct_deferred`, with `loaded:` whether the conversation had loaded it). On `api: openai` and the

data/docs/internals/attached-context.md

@@ -144,8 +144,11 @@ source's why. `task_p < TASK_MIN` (0.5) leaves the candidate unjudged; `due?` de
 lines (never twice at one owner-prompt count; one re-ask after `reask_after_turns`; then done). No answer writes
 nothing, so the next owner prompt asks again.
 
-The driver is the Engine, not the judge: `Engine#start_context_judge` (an owner turn's start; skipped for participants,
-review sessions and a Continue) and `judge_late_candidates` (a proposal after the prompts) call `context_judge_pass`.
+The driver is the turn stage `TurnStages::ContextJudge` (`turn_stages/context_judge.rb`), not the judge:
+`Engine#prepare_turn` calls its `start(turn, recorder:)` after the toolkit suggestion settled and before `apply_toolkit!` (an owner
+turn's start; skipped for participants, review sessions and a Continue), and `Engine#judge_late_candidates` (a proposal
+after the prompts) gives its `late_candidates` the session, the owner's messages, the recorder and the sessions dir
+(none of it read with no session or in a review session); both make one pass (docs/internals/engine.md, "Turn stages").
 It first logs status changes (`ContextCandidatesLog.look`), returns at `mode: off`, builds the due `Job`s, and hands
 them to `SideJudgments` (`:context` kind: one thread, one batch per session at a time), asked at once on any host,
 the model's own server too.
@@ -153,10 +156,10 @@ the model's own server too.
 `ContextCandidateChoice.after_judged` acts on `fields["would"]` in `on` mode only: *attach* → `judge_attach` (a
 session source with `JUDGE_WHY`, no probability in the model-visible why), *offer* → one card (`offer_card`, buttons
 `/context attach NAME` and `/context decline NAME`, guarded by a `carded` log line). It re-checks that the candidate
-is still proposed, since the user may have chosen while it was asked. Cards are shown through the Engine's
-`context_choice` lambda, which holds them while a turn runs (`@context_cards_after_turn`). `choose` is the
-`/context attach|decline` command's body (`SessionCommands`), shared by the card's buttons; it refuses in a review
-session. An attach only writes the session folder: its note comes with the next between-turn delivery, never into a
+is still proposed, since the user may have chosen while it was asked. Cards are shown through the stage's choice
+lambda, which holds them while a turn runs; `run_turn`'s ensure shows them after `release_turn`
+(`show_cards_after_turn`). `choose` is the `/context attach|decline` command's body (`SessionCommands`), shared by the
+card's buttons; it refuses in a review session. An attach only writes the session folder: its note comes with the next between-turn delivery, never into a
 running turn.
 
 `ContextCandidatesLog` is `context_candidates.jsonl` beside the sessions folder (a `SideJudgments.log`: 0600, one

data/docs/internals/background-tasks.md

@@ -44,7 +44,7 @@ Behavior:
 - `execute` and `task_create` both spawn with chi's own Ruby/Bundler setup scrubbed (`TaskRuntime.sanitized_spawn_env`): `RUBYOPT` loses its `-r…bundler/setup` flags (others stay) and `RUBYLIB` and what `bundle exec` sets (`BundlerEnv::VARS`: `BUNDLE_GEMFILE`, `BUNDLE_LOCKFILE`, `BUNDLE_BIN_PATH`, `BUNDLER_VERSION`, `BUNDLER_SETUP`) are unset, so a project's `ruby -e` or `bundle exec` uses its own Gemfile, or none, when chi runs under `bundle exec`. RubyGems requires what `BUNDLER_SETUP` names at boot, whatever `RUBYOPT` says. A project's own settings (`BUNDLE_PATH`, `BUNDLE_WITHOUT`) stay. `task_create` refuses those keys in the model's `env`, its error saying to write `KEY=value cmd` in the command instead; `execute`'s `env` comes from chi's callers (`Builtins`, `!cmd`), not the model, and is set over the scrub. An `execute` handed over at its limit keeps the process it spawned, so the task runs with the same env.
 - `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent), `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown) `SAMAGOTCHI_SESSION_THINKING` (the session's own thinking level; unset when it has none) and `SAMAGOTCHI_SESSION_REASONING_HISTORY` (its own reasoning_history level, the same way). `chi self` reads the last three for its model, thinking level and reasoning history. The four are `ChildEnv::SESSION_MARKERS` (`TaskRuntime::MARKER_ENV_KEYS`), which a spawned worker unsets (`ChildEnv.unset`, merged into its spawn env). A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
 - They also pass on a set `XDG_STATE_HOME` / `XDG_CONFIG_HOME` made absolute (`Builtins.xdg_absolute`, via `Paths`), so a chi the command runs in another `cwd` (`chi send`) reads this chi's state and config. These aren't reserved: an XDG dir the model sets in `task_create`'s `env` stays its own.
-- Every runner starts from the session's project env, `ProjectEnv.tools_env`: the overlay a spawned worker computed once at boot (`SessionManager.apply_project_env` → `ProjectEnv.compute` → `ProjectEnv.install!`; its folder's `mise env`, and the chi shim's dir first on PATH so `chi` is the chi home's), less `ProjectEnv::TOOLS_DROP` (`RUBYOPT`, `RUBYLIB`, Bundler's: the scrub above sets those). Outside a worker (`ProjectEnv::NONE`) it is `{}`. The sites: `execute` and `task_create` (`Tools::Builtins#project_env`, under the markers and the model's `env`; a participant's turn gets `{}`), the user's `!cmd` (`SessionCommands#shell`), and through `ProjectEnv.spawn_env` (the scrub above, then `tools_env`: what `execute` spawns with, for the runners that don't go through it) a context source's command (`ContextFetch#env_for`) and an MCP server, under the server's own keys (`bundles/mcp/plugin.rb` `server_env`, from mcp 0.7.4; no participant rule: the server is the session's). chi's own process env is never changed, and the project env never enters the prompt. User docs: [Project env](../sessions.md#project-env); the launch side: [How chi launches itself](../architecture.md#how-chi-launches-itself).
+- Every runner starts from the session's project env, `ProjectEnv.tools_env`: the overlay a spawned worker computed once at boot (`WorkerBoot.apply_project_env` → `ProjectEnv.compute` → `ProjectEnv.install!`; its folder's `mise env`, and the chi shim's dir first on PATH so `chi` is the chi home's), less `ProjectEnv::TOOLS_DROP` (`RUBYOPT`, `RUBYLIB`, Bundler's: the scrub above sets those). Outside a worker (`ProjectEnv::NONE`) it is `{}`. The sites: `execute` and `task_create` (`Tools::Builtins#project_env`, under the markers and the model's `env`; a participant's turn gets `{}`), the user's `!cmd` (`SessionCommands#shell`), and through `ProjectEnv.spawn_env` (the scrub above, then `tools_env`: what `execute` spawns with, for the runners that don't go through it) a context source's command (`ContextFetch#env_for`) and an MCP server, under the server's own keys (`bundles/mcp/plugin.rb` `server_env`, from mcp 0.7.4; no participant rule: the server is the session's). chi's own process env is never changed, and the project env never enters the prompt. User docs: [Project env](../sessions.md#project-env); the launch side: [How chi launches itself](../architecture.md#how-chi-launches-itself).
 
 ## Finish wake
 

data/docs/internals/block-renderers.md

@@ -16,7 +16,14 @@ model. The TUI is untouched: it shows a fence as source.
    who draws what: `GET /api/block_renderers`, `:owner`. `GET /api/block_renderers/:bundle/:file` serves a file, `:owner`:
    the URL's names go through `BlockRenderers.script_path` (membership in a listed renderer's `load` before any path is
    made), then `Provenance.sha_matches?`; a changed file is 409 `renderer_changed`. ETag + `no-cache`, as static files.
-3. `block_host.js` (`createBlockHost`, wired in `app.js`; `participant.js` isn't): one `MutationObserver` per turn root,
+3. `block_watch.js` (`createBlockWatch`, made by `block_host.js`'s `createBlockHost`, wired in `app.js`; `participant.js`
+   isn't) finds and watches the blocks; `block_host.js` is its frame drawer (`createFrameDrawer`). The watcher asks an
+   ordered list of drawers, core ones first (`inline_widgets.js` for `chi-ui`: [inline-widgets.md](inline-widgets.md)), then the frame drawer, which waits for `/api/block_renderers`;
+   the first that `claims` the block's language draws it, and a language none claims is left alone. The contract
+   (`claims`, `needsDraw`, `draw`, its `reconsider`, `sessionChanged`) is in the module's header. The shared DOM
+   helpers live there too: `failBlock` and its `.block-note` (a click copies it), `holdingView`, `rejoin`, the
+   toggle's listener; frames, the cache, hang marks, size checks, the zoom and the theme redraw stay in
+   `block_host.js`. One `MutationObserver` per turn root,
    filtered to `TEXTS` (`text_roots.js`), so cards, the asking slot, question replies and delegate reports never draw, and
    every path that adds a block to a root is seen the same way. One `IntersectionObserver` per scroller, with an explicit `root`
    (with `root: null`, `rootMargin` doesn't pass an `overflow: auto` in between). Closed `<details>` fire on open. **A