samagotchi 0.91.0 → 0.92.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4a20c3555c1f3e592919853f9dc59a5067e7e42251d11dad2f3be844f118f90
-  data.tar.gz: 817bb797b870985aeb21789377eae7770225265d03c527bb9218a1ecd3c2376e
+  metadata.gz: c6797c1728cd7acf0fc6d82e0aa5a1e6f6b65d6af6b5c69869f34c722d2176b0
+  data.tar.gz: a140559d9438ab5f16a6096b1f949280d67bfc062026c334544b9b312f9b9656
 SHA512:
-  metadata.gz: 74b69c624e9e43882940e48bdf00d0bedb1172fd53f4094c30ef4250e15a4e7ae9fedba4fc9704b923d3b622bcad47950432d450c1c3c219f42a54186dacad58
-  data.tar.gz: ac112286f3eaa6364bd68cee410e4b580f8246215222a17ecd3781f2980d828eb12d47cc3b64c800e201f9a81662a0c2ee61627a1c485e4249f409c771b65744
+  metadata.gz: 28133e65ee4aed6e07f685a2b65045c0c157306e406eb02836c8e9549c80d9d99391edc087d6eb711e0f522c21be3d0c83276804a73d0f4f03e6d91c379b569c
+  data.tar.gz: fdc100fd5b8f528b3f2fbce1e4ca25c1817a811c1fb0d32369e7c0ceb36e426c546f0819e41fefea3b7ddfdebfe7e9de0d9209faefe2177421f41b4acb30c701

data/CHANGELOG.md

@@ -8,6 +8,62 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [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 +3605,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.91.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.92.0...HEAD
+[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: " \

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,7 +330,7 @@ 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:
@@ -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. |
+| 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` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
 | 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/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}` |
@@ -681,7 +689,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
@@ -749,3 +757,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`) |

data/docs/internals/tool-guardrails.md

@@ -27,6 +27,14 @@ Telemetry uses existing context estimation settings:
 - `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` (`context.window_tokens`)
 - `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN` (`context.chars_per_token`)
 
+Line ranges (`read` and `edit`; env only, no config key):
+
+- `SAMAGOTCHI_READ_END_OPTIONAL` / `SAMAGOTCHI_EDIT_END_OPTIONAL` (default `true`): a `start_line` without
+  `end_line` means "to the end of the file"; `false` makes it an error.
+- `SAMAGOTCHI_READ_ALLOW_OOR_END` / `SAMAGOTCHI_EDIT_ALLOW_OOR_END` (default `true`): an `end_line` past the end is
+  clamped to the last line and the result says so; `false` makes it `Error: range out of bounds`. A `start_line`
+  past the end is always an error.
+
 ## Execute Tool Output Guardrails
 
 The `execute` tool applies the same guardrail model to command output:
@@ -64,8 +72,8 @@ built-in name; a tool with none gets `:head`):
 everything else the cap leaves, so a larger `max_tool_output_chars` keeps a longer tail. Both are snapped to whole
 lines when that keeps at least half of each. execute's stdout and stderr blocks are cut each on its own (stdout gets
 about two thirds of the room when both are long, a block that needs less gives the rest to the other); the `exit:`
-line is always kept. The whole stays within the cap; a cap too small for a tail of `ToolOutputCut::MIN_TAIL` (200)
-characters gets the `:head` cut, and so does one whose gap lines leave no room for that tail (checked with the
+line is always kept. The whole stays within the cap; a cap under three times `ToolOutputCut::MIN_TAIL` (200), so
+under 600 characters, gets the `:head` cut, and so does one whose gap lines leave no room for a 200-char tail (checked with the
 file's planned path before anything is written): nothing is saved then, and the event has no `output_file:`.
 
 The gap line says what was left out and where the whole output is:

data/docs/memory.md

@@ -308,6 +308,12 @@ for a file another bundle installed.
   with neither and no terminal it keeps your edits and says so. Kept edits
   exit 2; `chi bundle diff NAME FILE` shows the base, and `--force` takes
   the bundle's version.
+- **A dev install** (`chi bundle install --dev PATH`) links the hooks, rules,
+  plugin and scripts to `PATH` but still copies the memories at install, so
+  an edit to one of them in `PATH` isn't seen until the next install.
+- **The rest of the manifest** (`plugin:`, `requires_chi`, `session_settings:`,
+  `context_providers:`, `requires_chi_next`) is in
+  [Plugins](plugins.md) and [internals/bundles.md](internals/bundles.md).
 
 ## Bundle profiles: core and dev