samagotchi 0.91.0 → 0.93.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4a20c3555c1f3e592919853f9dc59a5067e7e42251d11dad2f3be844f118f90
-  data.tar.gz: 817bb797b870985aeb21789377eae7770225265d03c527bb9218a1ecd3c2376e
+  metadata.gz: 7fb0f158cad212e0caef1636e67b16290dd85d750a906a04e409adf9c29511ea
+  data.tar.gz: e1ff65cd0228751f4adcd8601492a952070cc59d415d324e7908fdd3f998e61e
 SHA512:
-  metadata.gz: 74b69c624e9e43882940e48bdf00d0bedb1172fd53f4094c30ef4250e15a4e7ae9fedba4fc9704b923d3b622bcad47950432d450c1c3c219f42a54186dacad58
-  data.tar.gz: ac112286f3eaa6364bd68cee410e4b580f8246215222a17ecd3781f2980d828eb12d47cc3b64c800e201f9a81662a0c2ee61627a1c485e4249f409c771b65744
+  metadata.gz: b58b31c103e24a12b880dbeeae67be626b85b8478c87a19ba9e36440d10e07b34b3f4d615d5f3fceb5518a76172643736efc66263646cc0f75c919186b597bda
+  data.tar.gz: 05e2fc82913cafd6bc7a80fb0bc625b8f235b9008a78955b146a857e8f2b6c9e9b7c6c5a5717f31c2df32f14b17e4bc98781e68f8d160b95a657c1071dd85484

data/CHANGELOG.md

@@ -8,6 +8,91 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.93.0] - 2026-10-20
+
+### Changed
+
+- A session open in a chi REPL is refused with one message everywhere: `session ID is open in a chi REPL; close it
+  there first` (chi web's stop, restart, turn and command, `chi sessions stop|restart`, chi send). Before, some
+  places said `owned by an interactive TUI`.
+- Plugins: `ctx.http` turns only network, TLS and provider errors into `HttpError`; any other error (a bug in chi)
+  is logged with its backtrace and raised as it is, instead of looking like a failed request. In the bundle test
+  kit, `bundle.questions` entries are `Samagotchi::HookQuestion` values (same fields as before).
+
+### Fixed
+
+- Guardrail rules' `command:` keeps a `cat`/`tee` heredoc body after an `exec` that sends the shell's output to a
+  file (`exec >run.sh; cat <<EOF …`, `exec 3>run.sh; cat <<EOF >&3 …`, also inside `{ }`, `if`, a function, or
+  with `exec {fd}>file` / `3<>file`): the body may be run later, as with `cat <<EOF >run.sh`; before, it was left
+  out as data.
+- A config.yml that doesn't parse (saved mid-edit) no longer tells a worker or chi web that every start-only setting
+  changed and needs a restart: it warns once that the file doesn't parse, and the settings are compared again once
+  it does.
+- A background delegate's relayed approval is reported to the parent's model as `approval relayed to your user:
+  execute: git push → …`, as a waiting parent already got it; before, it read `hook question relayed…` with an
+  empty label. A relayed question from a delegate's own delegate is named by its header (`Cost cap`), not the
+  outer card's `delegate ab12 asks: Cost cap`.
+- `chi send --wait` on a queued image message that is removed (unqueued) as the wait looks no longer returns the
+  running turn's reply: the removal writes its tombstone before it takes the file, so the wait reads it as removed.
+
+Update with `chi update` (the system bundle 0.93.0), then restart `chi web`.
+
+## [0.92.0] - 2026-10-19
+
+### Added
+
+- A bundle's manifest can type its session settings (`session_settings: {cap: number}`: `number`, `boolean`,
+  `string` or `any`); `--set` and `POST /api/sessions` refuse a value of another type (exit 2 / 400), and a
+  `string` key keeps its text as given.
+
+### Changed
+
+- `--set BUNDLE.KEY=VALUE` (and `bundle_settings` strings in `POST /api/sessions`) type values as config.yml does:
+  for a bundle that lists its keys plainly (or types them `any`), `yes`/`on` are now `true`, `no` is now `false`
+  (any case: `No`, `ON`), and `.5`, `5.`, `1e3` are now numbers; before they reached the plugin as text. A bundle
+  that wants the text types the key `string`.
+- Test kit: `Samagotchi::Testing::Install.run(...).registered` is an `Install::Registered` value
+  (`registered.commands`, `.tools`, `.hooks`, `.inits`, `.toolkits`, `.tool_sources`, `.peer_sources`), its commands
+  and hooks `Install::Command` / `Install::Hook` values, not a Hash of arrays: a bundle spec reading
+  `registered[:commands]` needs `registered.commands`.
+- Test kit: `Install::Result#ok?` is gone; `result.failures.empty?` says the same.
+
+### Fixed
+
+- A Ctrl-C during a turn keeps what the turn did, as a Stop does: its finished tool calls and their results stay in
+  the session with the cancel note (a call it cut short reads as interrupted), so the next turn knows what already
+  ran and the note lists the background tasks the turn started. `chi bundle try --timeout` now shows that turn's
+  tool calls with their arguments.
+- `chi --help` lists `chi sessions restart`, `chi bundle trash` and the bundle authoring subcommands (`new`, `test`,
+  `check`, `try`).
+- Web: removing a queued message (its ×) and opening another session before the worker answered no longer puts the
+  removed text into that session's composer; a toast names the session it came from and stays until
+  dismissed, with Copy for the full text.
+- Web: images added to the composer while a message with images was still uploading or sending stay after it is sent,
+  instead of vanishing with the sent ones.
+- Web: when the model list can't be read, the start page says so in a toast (a new session starts on the default
+  model) instead of just leaving out the model picker.
+- `--set cost-cap.cap=.5` and `=1e1` set a cap (they were read as text and turned the cap off); `--set
+  cost-cap.cap=five` is refused (exit 2) instead of silently running without a cap. A `cap:`, `child:` or `default:`
+  in config.yml that isn't a number (or is infinite, `1e400`) now warns once, and a bad `cap:`/`child:` falls back to
+  the next one. Run `chi update` (cost-cap 0.2.1).
+- An attached-context wake turn stopped before the model call keeps its note as a plain one and pauses wakes until
+  you write, as delegate and task wake turns do; it left the note marked as a turn's start.
+- A background task that finished just as the idle worker was about to exit still wakes the session (the worker
+  stays up for its wake); one that finished before the worker left for another reason is a note for the next turn.
+  A task whose turn you stopped no longer keeps the worker up or holds `/exit`.
+- `chi send --wait` on a session command delivered as a file reads the command's real outcome (failed, or canceled
+  when it was refused mid-turn or dropped), not always completed, and says so as the command's ("the command
+  failed"), not a turn's.
+- `chi bundle try` no longer signals its child's process group after the child exited (the group id may name
+  another process by then), and no longer waits 0.1 s after every run. A `--timeout` stops the background tasks the
+  turn started along with the child, and the delegate workers and tasks a run leaves behind are stopped before the
+  sandbox is deleted.
+- `chi bundle check` warns (`clash`) about an installed bundle of the same name whose record can't be read, instead
+  of skipping the clash check without a word.
+
+Update with `chi update` (the system bundle 0.92.0, cost-cap 0.2.1, core 0.3.4), then restart `chi web`.
+
 ## [0.91.0] - 2026-10-19
 
 ### Added
@@ -3549,7 +3634,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.91.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.93.0...HEAD
+[0.93.0]: https://github.com/dm1try/samagotchi/compare/v0.92.0...v0.93.0
+[0.92.0]: https://github.com/dm1try/samagotchi/compare/v0.91.0...v0.92.0
 [0.91.0]: https://github.com/dm1try/samagotchi/compare/v0.90.0...v0.91.0
 [0.90.0]: https://github.com/dm1try/samagotchi/compare/v0.89.0...v0.90.0
 [0.89.0]: https://github.com/dm1try/samagotchi/compare/v0.88.0...v0.89.0

data/README.md

@@ -80,7 +80,8 @@ the config. With a config already there, it adds a `hosts:` entry and keeps
 the rest of the file. Then it installs the `core` bundles (loop-guard,
 check-in, guardrails, slow-commands, agents-md, cost-cap: the safety set for a
 small local model, the cost cap inert until you set one) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
-source-links). Edit the
+source-links, github-pr, coordinator, claude-peer, codex-peer, ruby; see
+[Bundle profiles](docs/memory.md#bundle-profiles-core-and-dev)). Edit the
 file later as in [Configure](#configure); `chi bootstrap --help` has the
 options.
 
@@ -216,8 +217,10 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals
 - [Hooks](docs/hooks.md): plugin hooks and bundle hooks
 - [Plugins](docs/plugins.md): bundle plugins (commands, tools, hooks)
+- [Writing a bundle](docs/bundle-authoring.md): `chi bundle new`, `test`, `check`, `try`, `install --dev`
+- [Testing](docs/testing.md): specs, affected specs, lint, worktrees
 - [Architecture](docs/architecture.md): Engine, TerminalUI, bridge, web
-- Internals: [Engine](docs/internals/engine.md), [Gemma 4 contract](docs/internals/gemma4-contract.md), [prompt caching](docs/internals/prompt-caching.md), [context telemetry](docs/internals/context-telemetry.md), [LLM context: forget layer](docs/internals/llm-context-forget.md), [replay benchmark](docs/internals/llm-context-bench.md), [live runs](docs/internals/llm-context-live.md), [tool output limits](docs/internals/tool-guardrails.md), [background tasks](docs/internals/background-tasks.md)
+- Internals: [Engine](docs/internals/engine.md), [Gemma 4 contract](docs/internals/gemma4-contract.md), [prompt caching](docs/internals/prompt-caching.md), [context telemetry](docs/internals/context-telemetry.md), [LLM context: forget layer](docs/internals/llm-context-forget.md), [replay benchmark](docs/internals/llm-context-bench.md), [live runs](docs/internals/llm-context-live.md), [tool output limits](docs/internals/tool-guardrails.md), [background tasks](docs/internals/background-tasks.md), [bundles](docs/internals/bundles.md), [Anthropic Messages API](docs/internals/anthropic.md)
 
 ## Development
 

data/bin/chi

@@ -95,13 +95,13 @@ parser = OptionParser.new do |opts|
            chi bootstrap [HOST[:PORT]|URL]  first setup: find the model server, write config.yml
            chi scratch [options]            a one-time session in this terminal: nothing is kept
            chi web [--port PORT] [--open] [--scope=all]   the web UI
-           chi sessions <list|stop|archive|unarchive|delete|prune|clean|stats>
+           chi sessions <list|stop|restart|archive|unarchive|delete|prune|clean|stats>
            chi note [--source NAME] [-m TEXT] ID...|--all   background context for sessions
            chi broadcast [-m TEXT] [--all] [--dry-run] | log | deliver   a note for every session it may concern
            chi context <add|push|ls|show|refresh|rm|mute|unmute>   live external text attached to sessions
            chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
            chi answer ID --question QID --option N   answer a question a session waits on
-           chi bundle <install|upgrade|uninstall|status|diff|list|build>
+           chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try>
            chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
            chi models [--format json] [TEXT]   the models --model takes, from every host
            chi self                         version, paths, model and bundles
@@ -126,8 +126,8 @@ parser = OptionParser.new do |opts|
   # as --tool's negation); this is its help line.
   opts.separator "        --no-tool NAME               Leave this tool out of the toolkit (repeatable; a comma list too)"
   opts.on("--set BUNDLE.KEY=VALUE", "A bundle setting for this session, over config.yml's bundles: (repeatable; a key the " \
-                                  "bundle's manifest lists in session_settings:; numbers, true, false and off are typed, the rest is text; " \
-                                  "saved in the session: --set cost-cap.cap=3)") do |v|
+                                  "bundle's manifest lists in session_settings:; numbers and booleans (true, off, no) are typed, the rest is " \
+                                  "text; a value of the wrong type is refused; saved in the session: --set cost-cap.cap=3)") do |v|
     (options[:sets] ||= []) << v
   end
   opts.on("--parent-answers LEVEL", "What a parent agent may answer on this session's questions: " \
@@ -267,14 +267,14 @@ end
 # --parent-answers: a level in any case (no abbreviations), else a usage
 # error, as chi send's.
 if options[:parent_answers]
-  require "samagotchi/guardrails/parent_policy"
+  require "samagotchi/guardrails/parent_levels"
   levels = Samagotchi::Guardrails::ParentPolicy::ORDER
-  word = options[:parent_answers].strip.downcase
-  unless levels.include?(word)
+  level = Samagotchi::Guardrails::ParentPolicy.parse_level(options[:parent_answers])
+  unless levels.include?(level)
     warn "Error: --parent-answers takes #{levels.join(", ")}, not #{options[:parent_answers]}"
     exit 2
   end
-  options[:parent_answers] = word
+  options[:parent_answers] = level
 end
 if options[:parent_answers] && web
   warn "Error: --parent-answers is a new session's (chi --parent-answers, chi send --new --parent-answers), not chi web's"

data/docs/architecture.md

@@ -301,10 +301,10 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   An optional `deadline` (epoch seconds; `BridgeClient` sends 5/6 of its read timeout ahead) makes
   a request read after it (a worker frozen by sleep or SIGSTOP) answer `408 deadline_passed` and
   not run: a client that timed out has said the message was not sent. `/answer`,
-  `/question/dismiss` and `/command` take the same `deadline` (a command is checked with the event
-  log held, as a turn is), and the Bridge logs `turn_expired`, `answer_expired`, `dismiss_expired`
-  or `command_expired`. The web app answers either kind of timeout with `504 worker_timeout`
-  ("… so the command was not run"). `/cancel`, `/recap` and `/exit` take none.
+  `/question/dismiss`, `/command`, `/turn/dequeue` and `/exit` take the same `deadline` (a command is
+  checked with the event log held, as a turn is), and the Bridge logs `turn_expired`, `answer_expired`,
+  `dismiss_expired`, `command_expired`, `dequeue_expired` or `exit_expired`. The web app answers either
+  kind of timeout with `504 worker_timeout` ("… so the command was not run"). `/cancel` and `/recap` take none.
   The web relays answer, dismiss, command and cancel the same way (`App#relay`): a 408 or a read
   timeout is `504 worker_timeout`; a Bridge 404 for a route an older worker lacks is
   `501 not_supported` with the restart hint; a Bridge `404 unknown_session`, no bridge or a
@@ -330,13 +330,13 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   saved messages, or the running turn's accumulator); answers once the
   task is gone: `200 {status, stop_reason, task_id}`, `404 task_not_found`, `409 not_running`.
   The worker names it in its sidecar features (`task_stop`).
-- `POST /session/:id/turn/dequeue` — `{enqueued_id, client_id?}`: take back a queued message
+- `POST /session/:id/turn/dequeue` — `{enqueued_id, client_id?, deadline?}`: take back a queued message
   (one that waits for the running turn's end: `--queue`, Alt+Enter, `/queue TEXT`, or a message
   with images) before a turn takes it (web route `POST /api/sessions/:id/turn/:enqueued_id/dequeue`,
   the × on a queued bubble; `/unqueue` in the attached TUI). Under the event log, like its enqueue:
-  `SessionInbox.take_queued_input` claims the file as the drain does (one rename wins), deletes it,
-  leaves a tombstone (`input/removed/<enqueued_id>`, for `ReplyWait`'s `turn:`), and the Bridge
-  announces `:turn_dequeued`. `200 {status: "removed", enqueued_id, prompt}`, `409 already_started`
+  `SessionInbox.take_queued_input` writes a tombstone (`input/removed/<enqueued_id>`, for `ReplyWait`'s
+  `turn:`), claims the file as the drain does (one rename wins; a lost claim takes the tombstone back),
+  deletes it, and the Bridge announces `:turn_dequeued`. `200 {status: "removed", enqueued_id, prompt}`, `409 already_started`
   (a turn took it), `409 not_queued` (a next-step message: a drain may merge it any moment), `404
   unknown_enqueued_id`. It never wakes the worker. The worker names it in its sidecar features (`unqueue`).
 - `POST /session/:id/relay` — the approval relay, on a delegated child's worker
@@ -356,11 +356,13 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   (the summaries the next turn runs under) when the command changed them or the model, and
   `confirm: {line, text}` when a `/thinking` or `/reasoning-history` change from a `web:` or `tui:`
   client asks first (`CacheConfirm`; nothing changed, `line` applies it).
-- `POST /session/:id/exit` — ask the worker to exit now (`{client_id:}`). The worker checks with
+- `POST /session/:id/exit` — ask the worker to exit now (`{client_id:, delete?, restart?, deadline?}`; `delete`:
+  `/exit --delete`, no recap written; `restart: true`: hand the session to a new worker on the newest chi
+  installed, `200 {status: "restarting"}`; an empty session's `exiting` carries `discard: true`). The worker checks with
   the event log held (`WorkerIdleExit#hold_for_request`): `200 {status: "exiting"}` and it leaves
   like an idle exit, or `409 {status: "held", reason:}` with `turn_running`, `input_queued`,
   `continue_offered`, `client_connected` (a stream not named by the asker), `reminders`,
-  `background_tasks` (with `tasks: [{id, command}]`: tasks a finish wake watches) or `starting`.
+  `background_tasks` (with `tasks: [{id, command}]`: the running tasks a finish wake watches) or `starting`.
 - `GET  /session/:id/state` — `session_state_snapshot` (JSON).
 - `GET  /session/:id/stats` — `Engine#stats_snapshot` for attached `/stats`: the metrics, with the context window and prompt profile asked from the server before the first turn.
 - `GET  /session/:id/snapshot` — the snapshot frame's content as one request (the web server renders
@@ -581,22 +583,24 @@ 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`, `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` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
+| 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. |
 | 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. |
-| Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb` | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources ([plugins.md](plugins.md)). |
+| 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)). |
+| Bundle session settings | `bundle_session_settings.rb` (`BundleSessionSettings`) | A session's own `--set BUNDLE.KEY=VALUE` values, checked against the manifest's `session_settings:`, laid over `bundles: <name>:` in `ctx.settings` ([plugins.md](plugins.md)). |
+| Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb`, `plugin/context.rb` (`ctx`), `plugin/http.rb` + `plugin/http_transport.rb` (`ctx.http`), `plugin/card.rb` (`Plugin::Card`) | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources; what its handlers get as `ctx` ([plugins.md](plugins.md)). |
 | Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([plugins.md](plugins.md#the-claude-peer-bundle)). |
 | Shipped bundles | `bundles/` (`mcp`, `github-pr`, `loop-guard`, `skills`, `source-links`, …) | Bundles that ship with chi. |
 | Hooks | `hooks/registry.rb` (`Hooks::Registry`), `hooks/loader.rb`, `hook_routes.rb` (`HookRoutes`), `event_routes.rb` (`EventRoutes`) | Hook registration and dispatch; what a hook or plugin does beyond reading its event (notice, question, stop, steer) routed to the UIs (cards and notices through one set of routes) ([hooks.md](hooks.md)). |
-| Guardrails | `guardrails.rb`, `guardrails/shell_lex.rb`, `guardrails/rules.rb`, `guardrail_wiring.rb` | The gate before every tool call: shell lexing, YAML rules, approvals ([guardrails.md](guardrails.md)). |
-| Delegation | `tools/delegate.rb`, `tools/delegate_result.rb`, `tools/delegate_wait.rb`, `child_reports.rb`, `relay_desk.rb` | Child sessions a session starts and waits on, and their approval relay ([sessions.md](sessions.md#delegating)). |
+| Guardrails | `guardrails.rb`, `guardrails/shell_lex.rb`, `guardrails/data_readers.rb`, `guardrails/rules.rb`, `guardrails/protected_paths.rb`, `guardrails/parent_policy.rb` + `guardrails/parent_approvals.rb`, `guardrail_wiring.rb` | The gate before every tool call: shell lexing (and the commands that only read a heredoc as data), YAML rules, the core checks on chi's own files, approvals, what a parent agent may answer (`guardrails.parent_answers`) ([guardrails.md](guardrails.md)). |
+| Delegation | `tools/delegate.rb`, `tools/delegate_result.rb`, `tools/delegate_wait.rb`, `child_reports.rb`, `tools/delegate_relay.rb`, `relay_desk.rb`, `relay_verifier.rb`, `relay_watcher.rb` | Child sessions a session starts and waits on, and their approval relay ([sessions.md](sessions.md#delegating)). |
 | send / broadcast | `send_command.rb` (`SendCommand`), `broadcast_command.rb` (`BroadcastCommand`), `broadcast/` | `chi send` and `chi broadcast` ([broadcast.md](broadcast.md), [sub-agent.md](sub-agent.md)). |
 | Idle work | `idle_scheduler.rb` (`IdleScheduler`), `idle_recap.rb` (`IdleRecap`), `idle_reminders.rb` | One poller for an idle session's recap and reminders. |
 | Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
 | Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. `SessionChain.opener_for` gives the text web `continue →` prefills in the new link: the previous link's own first typed message when that link continues one itself, else nil (the 201's `opener`; not saved) ([sessions.md](sessions.md)). |
-| 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/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
+| 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/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)). |
 | Tool index | `tools/tool_index.rb` (`Tools::ToolIndex`) | `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)). |

data/docs/bundle-authoring.md

@@ -57,7 +57,8 @@ plugin:
 
 `plugin.rb` defines `class Plugin` with `register(chi)`; `initialize(settings)` (optional) gets config.yml
 `bundles: my-bundle:` as a Hash with string keys, once, when the plugin loads. A value a session may set
-(`chi --set my-bundle.KEY=V`, listed in the manifest's `session_settings:`) is read from `ctx.settings` at call
+(`chi --set my-bundle.KEY=V`, listed in the manifest's `session_settings:`, typed with `{KEY: number}` so a
+value of another type is refused) is read from `ctx.settings` at call
 time. `chi bundle check --set KEY=VALUE` gives the sandboxed load a setting.
 
 ## What a hook sees

data/docs/cli.md

@@ -83,9 +83,9 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   or with anchors gets the lines printed to paste instead. `--dry-run` shows
   what it would write.
 - **The bundles.** Unless writing the config failed, it installs the system
-  bundle and the `core` profile (loop-guard, check-in, guardrails, slow-commands), one line
+  bundle and the `core` profile (loop-guard, check-in, guardrails, slow-commands, agents-md, cost-cap), one line
   each; on a terminal it then asks `Also install dev (known-names, mcp, btw,
-  skills, source-links)? [y/N]`. Run again, it installs nothing new: a bundle
+  skills, source-links, github-pr, coordinator, claude-peer, codex-peer, ruby)? [y/N]`. Run again, it installs nothing new: a bundle
   you uninstalled stays out ([Bundle profiles](memory.md#bundle-profiles-core-and-dev)).
   A bundle that fails to install makes the exit 1. `--dry-run` says what it
   would install.
@@ -151,8 +151,8 @@ one experimental JSON object to stdout and human trace lines to stderr; its keys
 `interactive_blocked`, `used_memories`, `tokens` (`prompt`, `completion`), `cost`, `cost_is_estimate`, `model`,
 `sandbox`, `denied` (1-based tool indexes), `stderr_tail` (last 4,000 characters) and `timed_out`. A run past
 `--timeout` is interrupted like a Ctrl-C and still prints the trace it got to, with `timed_out: true` (text output:
-the trace lines, then `timed out after N seconds` on stderr). That turn's messages aren't saved, so its tool calls
-come from their timing records: name, status and duration, with empty `args`. Exit status: 2 for usage,
+the trace lines, then `timed out after N seconds` on stderr). That turn keeps its tool calls, as a Ctrl-C does, so
+they show with their `args`; a call the interrupt cut short has status `interrupted`. Exit status: 2 for usage,
 1 for install/turn failure or timeout, 130 for Ctrl-C, otherwise the child's status.
 
 `try` runs the bundle's code and the model's tools with your real HOME, account and keys. Its temporary working
@@ -280,7 +280,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). See "Thinking" in configuration.md. |
 | `--toolkit NAME`, `--tool NAME`, `--no-tool NAME` | A new session's toolkit, the tools its prompts declare: `full` (every built-in), `lean`, `child`, one of config's `toolkit.kits` or a bundle's (without `--toolkit`: config's `toolkit.default`), with tools declared on top of it (`--tool`) or left out (`--no-tool`); both repeatable, a comma list too. Saved in the session as given; a respawned worker, a fork and a continue keep it. Ignored with `--attach`/`--resume` (one line, as `--memory`); `/toolkit` changes it. Not on `chi web` (config's `toolkit.default` covers its sessions). See [Toolkits](configuration.md#toolkits). |
 | `--parent-answers LEVEL` | A new session's own `guardrails.parent_answers` (`hard`, `standard` or `soft`): what a parent agent may answer on its questions. It may only tighten config.yml's: the stricter of the two applies, and a looser one is saved as given with a warning (`--parent-answers soft is looser than config.yml's guardrails.parent_answers: standard; standard applies`). Saved in the session; a respawned worker, a fork and a continue keep it, a `delegate` child takes its parent's. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. Only you loosen it: `/parent-answers` in the terminal or the web. See [Guardrails](guardrails.md#answers-from-a-parent-agent). |
-| `--set BUNDLE.KEY=VALUE` | A bundle setting for a new session (repeatable; a later one of the same key wins), laid over config.yml's `bundles: <bundle>:` in what the bundle's plugin reads (`ctx.settings`): `--set cost-cap.cap=3`. The value is typed simply: an integer (`3`, `-1`) or a decimal (`2.5`) is a number, `true` is true, `false` and `off` are false, anything else stays the text as given (`010`, `0x10`, `3:30`, `No`, `null`). For cost-cap, `0`, a negative number or `off` is no cap. Only a key the installed bundle's manifest lists in `session_settings:` is taken: a bundle that isn't installed (or whose plugin doesn't load), a key it doesn't list (a record installed before the bundle listed it says to run `chi update` or `chi bundle upgrade NAME`), or another shape (`--set foo`, `--set a.b.c=1`) is an error naming what it takes, exit 2, nothing started. Saved in the session; a respawned worker, a fork and a continue keep it, a delegate child doesn't. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. See [Per-session settings](plugins.md#per-session-settings). |
+| `--set BUNDLE.KEY=VALUE` | A bundle setting for a new session (repeatable; a later one of the same key wins), laid over config.yml's `bundles: <bundle>:` in what the bundle's plugin reads (`ctx.settings`): `--set cost-cap.cap=3`. The value is typed simply: an integer (`3`, `-1`) or a decimal (`2.5`, `.5`, `1e1`) is a number, `true`, `yes` and `on` are true, `false`, `no` and `off` are false (any case, as in config.yml), anything else stays the text as given (`010`, `0x10`, `3:30`, `y`, `null`), and so does every value of a key the manifest types `string`. For cost-cap, `0`, a negative number or `off` is no cap. Only a key the installed bundle's manifest lists in `session_settings:` is taken, with a value of the type it gives the key: a bundle that isn't installed (or whose plugin doesn't load), a key it doesn't list (a record installed before the bundle listed it says to run `chi update` or `chi bundle upgrade NAME`), a value of another type (`--set cost-cap.cap=five`), or another shape (`--set foo`, `--set a.b.c=1`) is an error naming what it takes, exit 2, nothing started. Saved in the session; a respawned worker, a fork and a continue keep it, a delegate child doesn't. Ignored with `--attach`/`--resume` (one line, as `--toolkit`); refused with `chi web`. See [Per-session settings](plugins.md#per-session-settings). |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
 | `--append-system-prompt FILE` | Put `FILE`'s text into the system prompt, after AGENTS.md and before the memory indexes (repeatable; relative to the shell's directory). Added after the config.yml `append_system_prompt:` list. A missing or unreadable file is an error, exit 1. Saved in the session, so a respawned worker, a fork and a continue keep it; ignored with `--attach`/`--resume` (one line, as `--memory`). See [Appended prompt files](configuration.md#appended-prompt-files). |

data/docs/configuration.md

@@ -118,7 +118,9 @@ Besides the settings sections, the file holds maps that are read by their
 own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
 "Images"), `model_aliases:`, `hooks:` (see [Hooks](hooks.md)),
 `guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
-settings for its hooks, see [Hooks: Settings](hooks.md#settings)),
+settings for its hooks, see [Hooks: Settings](hooks.md#settings); a session's own
+`--set BUNDLE.KEY=VALUE`, for a key the bundle's manifest lists in `session_settings:`, lays over them, see
+[Per-session settings](plugins.md#per-session-settings)),
 `memories:` and `append_system_prompt:` (see "Appended prompt files"). Their entry names (host names, model ids, aliases) are yours to
 choose. The `memories:` list is the persistent baseline for preloaded memory entries —
 the same name shape as `--memory` (bare name or `scope/name`), merged under

data/docs/context.md

@@ -249,8 +249,8 @@ you're away from the terminal. All of these must hold:
 - the session's worker is up and idle: no turn running, nothing queued, no
   question or continue offer waiting, not just started;
 - under `session.max_wakes` turns in a row with no message from you (the
-  budget delegate reports use too; a turn that failed pauses wakes until you
-  write);
+  budget delegate reports and finished background tasks use too; a turn that
+  failed, or was stopped before the model call, pauses wakes until you write);
 - the source hasn't woken the session in the last 10 minutes (a peer
   source has its own limit instead: below).
 
@@ -266,7 +266,9 @@ notifications count it as a finished turn however short.
 A wake turn that fails goes back to before it and keeps its note as a
 plain one; the model reads `[SYSTEM: the previous turn failed before any
 answer: … The wake turn for the change in attached context <name> was not
-answered; chi starts no other wake turn until the user writes.]`.
+answered; chi starts no other wake turn until the user writes.]`. One
+stopped before the model call (a Stop, a `before_turn` hook's cancel) goes
+back the same way, its note plain, and pauses wakes too.
 
 ### Peer sources: the peer loop
 

data/docs/guardrails.md

@@ -336,11 +336,10 @@ the `<<TAG` word and the terminator line stay in the text, so a rule on
 anything else (`bash`, an interpreter, `ssh`, a wrapper), an unquoted one
 whose body holds `$(…)` or backticks, a piped one, a file-writing
 `cat`/`tee` (a `>&2` or `>&-` writes no file; `>& file` does), a
-here-string and an unterminated heredoc all stay in it. An fd opened
-earlier and written to by number (`exec 3>r.sh; cat <<E >&3`) isn't
-followed, so that body counts as data: out of scope here, which is
-chi-nah's job for a model that goes looking. Approvals, the approval
-question and hooks see the whole command.
+here-string and an unterminated heredoc all stay in it, and so does every
+`cat`/`tee` body after an `exec` that sent the shell's output to a file
+(`exec >r.sh; cat <<E`, `exec 3>r.sh; cat <<E >&3`). Approvals, the
+approval question and hooks see the whole command.
 
 `memory: remove` matches a `memory_write` with `remove: true` (it moves a
 memory into the bundle trash). Nothing else asks about it: a memory's file is

data/docs/hooks.md

@@ -590,7 +590,7 @@ hooks:
     event: after_tool_call
     on_error: log
     priority: 100
-trust_level: reviewed        # reviewed | experimental (default)
+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)
 ```
@@ -608,12 +608,12 @@ 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 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 [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.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 [Plugins](plugins.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 [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Plugins](plugins.md#the-ruby-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
+- Shipped bundles (each 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 [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.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 [Plugins](plugins.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 [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Plugins](plugins.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Plugins](plugins.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Plugins](plugins.md#the-coordinator-bundle)) and `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Plugins](plugins.md#the-claude-peer-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.
+- `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).
 

data/docs/internals/background-tasks.md

@@ -38,7 +38,7 @@ Behavior:
 
 A task the model leaves running (it ends its turn: "I'll check when it's finished") is reported when it ends, so the result doesn't wait for the user's next message. `session.task_wakes` (env `SAMAGOTCHI_SESSION_TASK_WAKES`): `wake` (default), `queue` or `off` (no watch, as before).
 
-- **The watch** (`TaskWatch`, `task_watch.rb`) is the Worker's, in memory: the in-process REPL (`--no-shared`) has none, and a crash loses it (those tasks behave as before). The Worker's Engine observer feeds it the raw `:tool_call_completed` events, the input `Bridge#own_task_ids` reads too. A `task_create` result and an `execute` hand-over add the task (`TaskRuntime.created_id`: a `task_id:` the command printed doesn't count), the hand-over's limit kept for the note. What shows the model the end removes it: a `task_wait` with a final status, or with `wait_result: pattern_matched` (the model chose its own "done" marker); a `task_get` with a final status; any `task_stop`. `task_list` and a `read` of `output.log` don't: a model that read the log still gets the wake once. Tasks a tool starts inside an anytime command (`/btw` and the like) reach the same observer, so they are watched too.
+- **The watch** (`TaskWatch`, `task_watch.rb`) is the Worker's (`WorkerTaskWakes`, `worker_task_wakes.rb`, which writes the notes; the Worker runs the wake turn), in memory: the in-process REPL (`--no-shared`) has none, and a crash loses it (those tasks behave as before). The Worker's Engine observer feeds it the raw `:tool_call_completed` events, the input `Bridge#own_task_ids` reads too. A `task_create` result and an `execute` hand-over add the task (`TaskRuntime.created_id`: a `task_id:` the command printed doesn't count), the hand-over's limit kept for the note. What shows the model the end removes it: a `task_wait` with a final status, or with `wait_result: pattern_matched` (the model chose its own "done" marker); a `task_get` with a final status; any `task_stop`. `task_list` and a `read` of `output.log` don't: a model that read the log still gets the wake once. Tasks a tool starts inside an anytime command (`/btw` and the like) reach the same observer, so they are watched too.
 - **The idle tick**: with something watched, each idle pass (after delegate reports, before due reminders) refreshes the watched records (`TaskRuntime.get_record`, one `ps` per running task) and takes the finished ones, keeping only the ids the conversation still holds (`TaskRuntime.created_ids_in`: a `!rollback` or a restored turn may have dropped the result that started one; an LLM context strategy can't, since its stale and forget stubs are drawn in the request, never written over the saved result). A note that can't be written puts its task back for the next pass. An empty watch costs nothing. A task that finishes during a turn and is still unseen when the turn ends wakes on the next idle pass. One the user stopped with the web's stop-task button is dropped without a note.
 - **The note** is a context note under its own header (`ContextNote::TASK_HEADER`; `TaskFinishNote`), `note_id: task-<id>`, `source: task <id8>`:
 
@@ -56,7 +56,7 @@ A task the model leaves running (it ends its turn: "I'll check when it's finishe
 - **The wake turn**: the first finished task runs a continue turn from client `task:<id>` (`last_turn.origin: "task"`, labelled `task <id8> finished` in the TUI and the web; the web's bell rings at its end however short), whose first message is the note (`turn_start`, `turn_id`, written before the turn's checkpoint so a restore keeps it). It counts toward `session.max_wakes` with the other wakes (`WorkerWakes#task_open?`: no continue offer, not paused, past the 2 s start grace). Several tasks finishing together: one wake turn, the others plain notes before it.
 - **A plain note instead** (the same text without the last two lines, no turn start), written at once, with `queue`, the budget spent (the UIs hear `N finished background tasks noted; the model reads them with your next message` once per human input, the flag shared with the other wakes), wakes paused, a continue offer waiting, input queued, an exit asked for, or a **note-only** task: one started or waited on in a turn the user stopped (reasons `user`, `manual`, `ctrl_c`), since a wake telling the model to carry on would undo that Stop. A prompt's turn takes the finished ones as plain notes first.
 - **Failure**: a wake turn that fails and kept nothing, or is stopped and restored, turns its note back into the plain one (`WorkerInbound#unmark_wake`, as for a context wake) and pauses wakes until the user writes.
-- **Idle exit**: with `wake`, a watched task still running holds the worker's idle exit and `/exit` (`WorkerIdleExit`'s `:background_tasks`; the 409 lists the tasks, `{id, command}`, with a `hint` on stopping them, and the attached terminal names them and says to use the web's stop-task button or ask for `task_stop`), as reminders do. With `queue` they don't: nothing would wake for the end, so keeping the worker up isn't worth it; a task that ends after the worker left gets no note (the model sees its end at its next look, as before). A forgotten dev server keeps the worker up until it is stopped; a crash of that server wakes the session.
+- **Idle exit**: with `wake`, a watched task holds the worker's idle exit (`WorkerIdleExit`'s `:background_tasks`) until its wake is taken: while it runs, and once it finished until the next idle pass takes it (`TaskWatch#holding`, in memory, no `ps`), so one that ends between the pass's look and the exit's check still wakes the session. A still-running one holds `/exit` too (`TaskWatch#running`; the 409 lists the tasks, `{id, command}`, with a `hint` on stopping them, and the attached terminal names them and says to use the web's stop-task button or ask for `task_stop`), as reminders do. A note-only task holds neither (no wake would come for it), nor does one whose note, or the look for it (the conversation's task ids unreadable), failed 3 times (`TaskWatch::MAX_FAILURES`: it is still tried at each look, but can't keep the worker up for good). With `queue` nothing holds: nothing would wake for the end, so keeping the worker up isn't worth it. As the worker leaves (any exit but a stop, a signal or an `/exit --delete`), the tasks that finished since the last look are written as plain notes; a task that ends after the worker left gets no note (the model sees its end at its next look, as before). A forgotten dev server keeps the worker up until it is stopped; a crash of that server wakes the session.
 - **The tool descriptions**: a worker's `execute` and `task_create` say "if you end your turn before it finishes, chi tells you when it does" (left out under `off` and in the REPL), fixed when the worker builds its Engine.
 
 Work that needs a model, not a shell command, goes to a child chi session instead: `delegate` / `delegate_result` have the same shape (start, then wait) and return only the child's final reply; see [Sessions: Delegating](../sessions.md#delegating).

data/docs/internals/bundles.md

@@ -22,9 +22,9 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 
 | Piece | Role |
 |---|---|
-| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check`; runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
+| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check/try` (`install --dev`: the Installer's `dev:`, links and `Provenance::DEV_SHA`); runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
 | `BundleCommand::Check` (bundle_command/check.rb) | `chi bundle check [PATH] [--fix] [--set K=V]`: a bundle being written, checked as an install takes it (docs/cli.md lists the codes); parses the manifest from `Shas.parseable` (a placeholder sha is a `sha` finding, not a YAML error), reads the user's installed bundles only for `clash`, and installs and loads through `Testing::Install` in a `Testing::Sandbox` with `force: true`, the log's echoes swallowed |
-| `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: filtered-config `Sandbox` installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output (tool records the messages lack, from a turn a `--timeout` interrupt cut, become rows without args; `Run::Result#timed_out` becomes `timed_out`). `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers. |
+| `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: `Command` (its flags, help and checks) drives the rest and `Render` prints the trace; a filtered-config `Sandbox` (its folders a `SandboxLayout`, the layout `Testing::Sandbox` uses too) installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards (`Bridge::CardStore.saved`, as the web does) and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output (a turn a `--timeout` interrupt cut keeps its calls like a Ctrl-C, the one cut short answered as interrupted, so its rows come from the saved calls too; `Run::Result#timed_out` becomes `timed_out`). `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers (`ChildEnv`, the scrub a session's worker spawn uses too). The child runs in its own process group: a `--timeout` sends it INT, then `ProcessGroup.stop` (the groups its processes started too); after any exit the group is signalled only while a straggler is still in it, never a reaped group. `Sandbox#stop_leftovers` (before the trace, and in `cleanup`) stops what left the child's tree, found by the sandbox's own records: a delegate's worker by its session's `owner.lock`, a task by its running `task.json` whose pid still leads its group. |
 | `BundleCommand::Scaffold` (bundle_command/scaffold.rb) | `chi bundle new NAME`: the starting files (block-form `plugin:` entry, `requires_chi` at this chi, a kit test that passes as written); the manifest's shas are filled through `Shas.refresh` |
 | `BundleCommand::TestRun` (bundle_command/test_run.rb) | `chi bundle test`: `RbConfig.ruby -I <chi's lib>` on `test/**/*_test.rb` (Minitest) or `spec/` (RSpec, as `rake bundles:specs`), under `Bundler.with_unbundled_env` when Bundler's runtime is loaded |
 | `Shas` (shas.rb) | a manifest's `sha256:` lines: `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / hook / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |
@@ -32,7 +32,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `SourceIdentity` (source.rb) | what a source is, for comparing two installs of one name: `shipped:<dir>` (any gem or checkout), `git:<url>` (no `#ref`, trailing `/` or `.git`), `path:<realpath>`; nil when it can't place one |
 | `PreparedSource` (source.rb) | one source normalized once (dir, owned, git commit): `BundleCommand` reads the bundle's name from its `manifest.yml` (the name for every kind of source, a git URL too) and hands it to the Installer (`prepared:`), so a source is cloned or extracted once per command |
 | `MemoryFiles` | which top-level `*.md` files of a bundle are its memories (`.select`: the `files:` list, else all but README/LICENSE and the like), `.unshipped` (listed, not shipped) and `.symlinks` (skipped: a symlink is never a memory) |
-| `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, recorded at install in `manifest.json` for `BundleSessionSettings` to check) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
+| `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `BundleSessionSettings` to check) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
 | `Installer` | one install/upgrade/dry run of one bundle (below) |
 | `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
 | `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |
@@ -63,7 +63,7 @@ The checks live in `Hooks::BundleLoader.load` and `Plugin::Loader.load_bundle`;
 plugin file: build, `register`, `commit!`), which raise instead of logging: the bundle test kit
 (`Samagotchi::Testing::Bundle`) loads a bundle's source through them, unchecked. `Samagotchi::Testing::Install` is the
 checked path in a sandbox: the Installer, then `ExtensionLoad` (bundle hooks, then `load_plugins`), returning the
-Installer's warnings, this bundle's load failures and what it registered (`Install.registered`, also the parity
+Installer's warnings, this bundle's load failures and what it registered (`Install.registered`, an `Install::Registered` value, also the parity
 spec's shape). A load failure carries `LoadFailures::Failure#location` (the first backtrace frame inside the
 bundle, or a SyntaxError's own line), which `Install` maps from the installed copy (`.bundles/<name>/plugin/`,
 `hooks/`) back to the source dir.

data/docs/internals/engine.md

@@ -97,11 +97,14 @@ StandardError in run_turn:
 Interrupt (Ctrl-C; the REPL only: a worker traps INT, see the signal row below):
   → if turn.ended: re-raised only
   → turn.controller.cancel!(:ctrl_c)
-  → end_turn(turn, "canceled"): ctrl_c_messages keeps turn.messages with TurnNote.cancelled(:ctrl_c)
-     # Both loops work on their own copy of the conversation, and Interrupt is not a
-     # StandardError, so nothing attaches the loop's conversation: only what the Engine
-     # built before the loop (system head, history, reminders, the prompt) survives.
-     # Tasks the turn started are missed in the cancel note for the same reason.
+  → end_turn(turn, "canceled"): ctrl_c_messages keeps the loop's conversation, else turn.messages
+     # (it came before the loop), with TurnNote.cancelled(:ctrl_c) at the tail.
+     # Both loops attach their conversation to the Interrupt as to a failure
+     # (LLM::FailedTurn.attach), so the turn's finished iterations stay, as after a Stop,
+     # and the cancel note names the tasks the turn started. One mid-tool is answered:
+     # ToolResponse.run_batch gives every call left an interrupted result (the native
+     # loop's batch entry joins them after the finished ones), so no call is kept without
+     # its result. A half-streamed reply is not kept (a Stop keeps it, [interrupted]).
   → :turn_canceled {cancellation_reason: :ctrl_c, duration_ms}
   → re-raised (the caller decides whether to exit)
 
@@ -191,7 +194,8 @@ KernelLoop#run(messages, max_iterations:, on_stream_event:, cancel_controller:,
 ```
 
 `turn.conversation` is the loop's own copy, not the Engine's `turn.messages`. A failure attaches it to the error
-(`LLM::FailedTurn.attach`), so `Engine#failed_messages` can keep it; a Ctrl-C does not (see Error paths).
+(`LLM::FailedTurn.attach`), so `Engine#failed_messages` can keep it; an Interrupt (Ctrl-C) too, for
+`Engine#ctrl_c_messages` (see Error paths).
 
 ### ChatLoop (the chat APIs)
 
@@ -468,7 +472,9 @@ TUI. Errors in the sink or an observer are caught; they never break the turn.
 
 `Engine#announce` puts an event that belongs to no turn (`ANNOUNCEABLE_EVENTS`: `turn_enqueued`, `turn_dequeued`
 (a queued message taken back before it ran, `{enqueued_id, client_id}`: the remover's), `card`,
-`hook_notice`, `guardrail_warning`, `plugin_init_started`, and more) to the observers only.
+`hook_notice`, `guardrail_warning`, `plugin_init_started`, and more) to the observers only. `:side_usage`
+(`{kind, side}`: a side request's usage, the recap's, `/btw`'s or `ask_model`'s, and the session's side sums) goes
+to the observers the same way from `Engine#note_side_usage` (any thread), without being announceable.
 
 Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 
@@ -491,6 +497,8 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:tool_dispatch_started` / `:tool_dispatch_completed` | around a batch | `{iteration, call_count}` |
 | `:tool_call_started` | before a call runs | Engine event includes `call` (see ToolRunner); the Bridge's SSE frame omits it |
 | `:tool_call_completed` | after a call ran | see ToolRunner |
+| `:question_requested` / `:question_answered` / `:question_cancelled` | `QuestionDesk`: a question is asked (an approval, `ask_user_question`, a hook's or plugin's `ask_user`, the step-limit Continue), answered, or withdrawn | `{pending_question}` / `{id, answer}` / `{id, reason}` |
+| `:plugin_init_wait` | a turn waits for plugin init tasks that provide tools (`PluginTasks`) | `{tasks: [{bundle, id, label}]}` |
 | `:used_memories_updated` | a memory was read, and after the loop | `{used_memory_names, read_names?}` |
 | `:hook_notice` | a hook's or plugin's notify during a turn | `{hook, text, level}` (announced with `between_turns: true` outside a turn) |
 | `:guardrail_warning` | a guardrails line during a turn | `{message}` |
@@ -561,6 +569,11 @@ Model probes (per turn):
 Plugins and hook files register hooks on hook points (see "Hook points" above, and docs/hooks.md). Every fire
 puts the hook runtime on the event: `event[:hook]` (the hook's label) and five helpers, which call the Engine's
 `Hooks::Runtime` (built by `HookRoutes`, `hook_routes.rb`, which routes each to the UIs). A plugin's `ctx` has the same ones (`ctx.notify`, `ctx.steer`, ...).
+A question takes keywords only at that plugin-facing edge (`event[:ask_user]`, `ctx.ask_user`); from there it is one
+`HookQuestion` (`hook_question.rb`: the question, its options, header, freeform flag, the hook's label and its
+label => effect map) through `Hooks::Runtime#ask_user` / `Plugin::Host#ask_user`, `Engine#hook_ask_user` and
+`HookRoutes#ask_user` to `QuestionDesk#ask_for_hook`, which turns the effects into the pending question's per-option
+tags. The bundle test kit records the same value (`Testing::Recorder#questions`).
 
 | Helper | What it does | Used by |
 |---|---|---|
@@ -681,7 +694,7 @@ prompt starts with what the server has cached).
    and config.yml hooks survive.
 3. **Each loop works on its own copy of the conversation.** The Engine's `turn.messages` is what it sent. After
    a normal end or a Stop it keeps `result.conversation`; after a failure, the copy attached with
-   `FailedTurn.attach`; after a Ctrl-C, only `turn.messages`.
+   `FailedTurn.attach` (a Ctrl-C's too); `turn.messages` only when it ended before the loop.
 4. **Events are the contract.** UIs read events, not internal state. `on_event` is per turn; observers are
    persistent.
 5. **A stable system prompt for the cache.** `SystemPrompt#build` caches the prompt per Engine, keyed by
@@ -739,6 +752,7 @@ Paths are under `lib/samagotchi/`.
 | `hooks/registry.rb` | Hook registry, fire order, `Hooks::Runtime` |
 | `hook_routes.rb` | `HookRoutes`: the Engine's routes for a hook's or plugin's notice (`:hook_notice`, `fallback_for:`), question, stop and steer, and the guardrails' after-load line |
 | `question_desk.rb`, `pending_question.rb`, `question_answer.rb` | `QuestionDesk`: the one open question (ask, post, answer, cancel, relay mark); `PendingQuestion` and `QuestionAnswer`, its values (Hashes only in events, Bridge JSON, the session file and the hook/plugin `ask_user` result) |
+| `hook_question.rb` | `HookQuestion`: a hook's or plugin's `ask_user` question as one value, from the runtime/host edge to `QuestionDesk#ask_for_hook` |
 | `event_routes.rb` | `EventRoutes`: where a card (`Engine#show_card`), a notice (`HookRoutes#notify`) and a guardrails line (`#guardrail_notify`, turn or between turns only) go: held while the plugins load, an anytime command's, an init task's, a running turn's event, else announced or held for `holding_announcements` |
 | `engine_peers.rb`, `peer_sources.rb` | `Engine::PeerView` (what the kernel's peer tools see of the Engine) and `Engine::RelayPeer` (a delegate's approval relay); `PeerSources`: the attached context sources a peer bundle declares as its peer's answers (`chi.peer_source`) |
 | `extension_load.rb` | What an Engine loads at start: config.yml and bundle hooks, plugins, `bundles:` settings; events held while plugins load |
@@ -749,3 +763,8 @@ Paths are under `lib/samagotchi/`.
 | `turn_checkpoint.rb` | `TurnCheckpoint`: a worker's running turn saved at the loop's iteration boundaries (`Session#turn_checkpoint`), so a killed worker loses at most `INTERVAL` of it |
 | `context_status.rb` | `ContextStatus`: one turn's context tracking (the status line's value, the `:context_status` event, the model's guidance line) ([context-telemetry.md](context-telemetry.md)) |
 | `session_manager.rb` | Background session processes (workers) and their IPC |
+| `worker_wakes.rb` | `WorkerWakes`: a worker's wake budget for the turns nobody typed (`session.max_wakes`) |
+| `task_watch.rb`, `task_finish_note.rb` | `TaskWatch`: the background tasks a worker's session started that the model hasn't seen finish; `TaskFinishNote`: the note one leaves when it does ([background-tasks.md](background-tasks.md#finish-wake)) |
+| `side_usage.rb` | `SideUsage`: one side request's usage (a recap, `ctx.ask_model`), folded into the session's side sums (`:side_usage`) |
+| `bridge/client_event.rb` | `Bridge::ClientEvent.project`: what an SSE client gets for an engine event ([architecture.md](../architecture.md)) |
+| `guardrails/parent_policy.rb` | `Guardrails::ParentPolicy`: which options of a question a parent agent may pick (`guardrails.parent_answers`) |