samagotchi 0.53.0 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1d170176f088bc87560a05b7596d57925d955011cc5818b93f5ae33ae2b1f55
-  data.tar.gz: 941c3bd879e09b78144ede81d4c6cf4724f9ca3a7ce8fa62f0174524a26f25bf
+  metadata.gz: 143c9195fbbe50c8f8193c76815004f30354a01d2e1ec7d5019e70bc79c376df
+  data.tar.gz: c1047a49f05415f8ea9a2789cf32ecc2f6edbcbf5bbfa432a8b919bd193ae360
 SHA512:
-  metadata.gz: ddc3c2d02b18137887e5e90f636b23dd3ea44461f33a723e4033d58f4cfcd9c7be3267db9cc3349aba1d3af6b73a398415696e3af2c8fdad6662704944dad189
-  data.tar.gz: bd8bded906f5e3855c8f63ab081582b601d4b5332bb10e9ed5a7dff36e185851583c95d28e8b3528ece4d8b34463cc6e65fd16bb95bf2c493de502d9efa79775
+  metadata.gz: 12b4e73421655936e2d3183e7839f4a8580b1d2b93633cff098170540e2c98ba61cf02c847a4af8b5e19a59424f15691a81d0b38195640263773bdccf2e8b3d3
+  data.tar.gz: bf03f5dab6f9d7e30d37531127dfb88e48e779eb65f271de703f12566d728bbe869a0d3a935d33932afff4556c09b21bfe4d3d95f4b72c131bfc0521a41bf4b9

data/CHANGELOG.md

@@ -8,6 +8,36 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.54.0] - 2026-10-10
+
+### Changed
+
+- Web: the ctx chip is always shown and updates on every request (it used to appear only once the context crossed
+  20/40/60/80%): `ctx ?` before a session's first request, with a tooltip saying why, on session cards too. The
+  attached TUI's status line gets the same fresh number each request; the model's own `[CONTEXT: …]` line still
+  comes only on a rise into a guidance bucket.
+- Web: a denied approval's summary line reads `<tool>: <command> → Denied`; the typed reason shows in full in the
+  card body (expand the card) instead of being cut off in the summary.
+- A grep-family search that found nothing (`grep`/`rg`/`ag`/`pgrep` exiting 1 with no stderr) is no longer a
+  failed tool call: it doesn't count in the turn's "(N failed)", the session's tool errors or the skills bundle's
+  "fix the skill" nudge, and the web row shows a done mark with a muted "no match". The model still sees
+  `exit: 1 (no output)`. Turns saved before keep their "error". (skills bundle 0.1.7; run `chi update`.)
+
+### Removed
+
+- The `context.status_cadence` setting (config key, `--status-cadence` flag, `SAMAGOTCHI_CONTEXT_STATUS_CADENCE`):
+  the context status now streams on every request, so nothing reads it. A config.yml that still lists it gets a
+  startup warning (`config: unknown key 'context.status_cadence'`) and otherwise loads.
+
+### Fixed
+
+- `chi -p "/cut TEXT" --non-interactive` (and `/queue TEXT`) runs `TEXT` as the turn's prompt, the same as the idle
+  REPL does, instead of feeding the model the literal `/cut` / `/queue` words; a bare `/cut` / `/queue` is still
+  refused, as before.
+- `chi bundle install` / `upgrade` no longer warns "Checksum mismatch for hook <file>: expected ..., got …" for a
+  hook whose manifest entry declares no `sha256` (or a `hooks/*.rb` the manifest doesn't list); a declared sha256 that
+  differs still warns. (Since 0.53.0.)
+
 ## [0.53.0] - 2026-10-10
 
 ### Changed
@@ -2412,7 +2442,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.53.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.54.0...HEAD
+[0.54.0]: https://github.com/dm1try/samagotchi/compare/v0.53.0...v0.54.0
 [0.53.0]: https://github.com/dm1try/samagotchi/compare/v0.52.0...v0.53.0
 [0.52.0]: https://github.com/dm1try/samagotchi/compare/v0.51.0...v0.52.0
 [0.51.0]: https://github.com/dm1try/samagotchi/compare/v0.50.0...v0.51.0

data/README.md

@@ -202,7 +202,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Configuration](docs/configuration.md): `config.yml`, hosts, model server transports, timeouts, retries, logs
 - [Memory](docs/memory.md): scopes, model-specific overlays and model notes
 - [Sessions](docs/sessions.md): storage, retention, `chi sessions`
-- [Attached context](docs/context.md): `chi context`, sources, scopes, waking, the github-pr bundle, safety
+- [Attached context](docs/context.md): `chi context`, sources, scopes, recipes (a file, a note, a stream), waking, the github-pr bundle, safety
 - [Broadcast](docs/broadcast.md): `chi broadcast`, who a note reaches, tags, triage, what a session gets, the triage log
 - [chi as a sub-agent](docs/sub-agent.md): `chi send --wait --format json`, `chi answer`, instructions for a parent agent
 - [Desktop helper](docs/desktop.md): `chi desktop`, the macOS "Send to chi" Service and hotkey

data/docs/architecture.md

@@ -6,48 +6,51 @@ A compact visual overview of the current architecture, then the core API in pros
 ## System map
 
 ```
-                          ┌─────────────────────────────────────────┐
-                          │               bin/chi                    │
-                          │           (CLI entry point)             │
-                          └───────────────────┬─────────────────────┘
-                                              │
-                     ┌──────────────────────────┴──────────────┐
-                     │           TerminalUI                     │  ← REPL (Reline),
-                     │   render · status line · REPL commands   │    rendering, commands
-                     └──────────────────────────┬──────────────┘
-                                                  │ delegates
-                      ┌───────────────────────────┴───────────────────────┐
-                      │                    Engine (core logic)             │
-                      │   system prompt · memory injection                  │
-                      │   tool declarations · session lifecycle           │
-                      │   model↔tool loop — `run_turn`                    │
-                      └───────────────────────────┬───────────────────────┘
-                                                  │ delegates
-                     ┌────────────────────────────┴──────────────┐
-                     │             Web::App (Rack)                │ ← browser UI
-                     │   session hub · /api/events · /api/*        │   via SessionManager file IPC
-                     └───────────────────────────┬───────────────┘
-                                                   │
-        ┌───────────────────────────────┬──────────┴───────────────┬──────────────────┐
-        │                                 │                          │                  │
-  ┌─────┴─────┐                   ┌───────┴───────────┐    ┌────────┴───────┐  ┌───────┴────────┐
-  │ KernelLoop │◀── drives────────▶│     Model API      │    │    Session      │  │ SessionManager │
-  │  (the loop)│                   │   (LLM HTTP call)   │    │  (state,       │  │  (bg workers)  │
-  └─────┬──────┘                   └─────────────────────┘    │  history)      │  └────────────────┘
-      │                                                          └──────────────────┘  └────────────────┘
-      │ run_turn events (turn_started, turn_completed,
-      │ turn_canceled, raw KernelLoop events)
-      ▼
+            bin/chi (CLI entry point)                        bin/chi web
+                       │                                          │
+  ┌────────────────────┴────────────────────┐    ┌───────────────┴────────────────┐
+  │                TerminalUI               │    │        Web::App (Rack)         │  ← browser UI
+  │  attached (default): AttachLauncher +   │    │  session hub · /api/events     │
+  │    AttachedLoop, no Engine              │    │  /api/* · reads session files  │
+  │  REPL (--no-shared …): its own Engine   │    └───────────────┬────────────────┘
+  └────────────────────┬────────────────────┘                    │ App#relay, bridge_get,
+                       │ BridgeClient (SSE + HTTP)               │ /stream proxy
+                       └────────────────────┬────────────────────┘
+                                            ▼
+                      ┌─────────────────────┴─────────────────────┐
+                      │ Worker (one process per session) + Bridge │ ← forked/spawned by
+                      │ input queue · idle exit · owner.lock      │   SessionManager
+                      └─────────────────────┬─────────────────────┘
+                                            │ builds, runs turns
+                      ┌─────────────────────┴─────────────────────┐
+                      │            Engine (core logic)            │
+                      │  system prompt · memory injection         │
+                      │  tool declarations · session lifecycle    │
+                      │  model↔tool loop — `run_turn`             │
+                      └─────────────────────┬─────────────────────┘
+                                            │
+        ┌───────────────────────────────────┴──────────────────────────┐
+        │                                   │                          │
+  ┌─────┴──────┐                  ┌─────────┴──────────┐      ┌────────┴─────────┐
+  │ KernelLoop │◀──── drives ────▶│     Model API      │      │     Session      │
+  │ / ChatLoop │                  │  (LLM HTTP call)   │      │ (state, history) │
+  └─────┬──────┘                  └────────────────────┘      └──────────────────┘
+        │
+        │ run_turn events (turn_started, turn_completed,
+        │ turn_canceled, raw KernelLoop events)
+        ▼
   ┌──────────────────────────────────────────────────────────────────────────────────┐
-  │                                       Tools                                         │
-  │  execute · read · edit · write · memory · web_fetch · task_create/get/list/          │
-  │  task_stop/wait                                                                    │
-  │  declared via tool_declarations.rb                                                 │
+  │                                      Tools                                       │
+  │  execute · read · edit · write · memory_read/write · web_fetch ·                 │
+  │  task_create/get/list/stop/wait · delegate · delegate_result · ask_user_question │
+  │  register_reminder/cancel_reminder/list_reminders · send_note · list_sessions ·  │
+  │  context_read · forget_outputs (+ bundle plugin tools)                           │
+  │  declared via tool_declarations.rb                                               │
   └──────────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
   ┌──────────────────────────────────────────────────────────────────────────────────┐
-  │                                   Persistence                                      │
+  │                                   Persistence                                    │
   │   Project:  ~/.config/samagotchi/memories/projects/<repo>_<hash>/ (per git repo) │
   │   System:   ~/.config/samagotchi/memories/                                       │
   └──────────────────────────────────────────────────────────────────────────────────┘
@@ -81,6 +84,9 @@ bin/chi ─▶ TerminalUI ─▶ Engine#run_turn ─▶ KernelLoop ──┬─
                                     (turn started / completed / canceled)
 ```
 
+That is the REPL; attached (the default) the session's `Worker` calls `Engine#run_turn` and the
+terminal renders the events it gets over the Bridge.
+
 ## Layers at a glance
 
 | Layer | Class(es) | Responsibility |
@@ -89,8 +95,9 @@ bin/chi ─▶ TerminalUI ─▶ Engine#run_turn ─▶ KernelLoop ──┬─
 | UI | `Samagotchi::TerminalUI` | REPL (Reline), rendering, REPL commands. Delegates all core work to an `Engine`. |
 | Model loops | `KernelLoop` (via `LLM::NativeBackend`), `LLM::ChatLoop` | The model↔tool loop: raw prompt or OpenAI chat API, chosen per host (see below). |
 | Adapters | `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::HTTP` | Raw-prompt servers, the OpenAI chat API, and the HTTP both share. |
-| Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, plus runtime/output-guardrails. |
-| Background | `Samagotchi::SessionManager` | Builds `Engine` directly (no terminal rendering) for workers. |
+| Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, delegate/delegate_result, ask_user_question, reminders, send_note, list_sessions, context_read, forget_outputs, plus runtime/output-guardrails. |
+| Bundles | `lib/samagotchi/memory_bundle/*`, `BundleCommand` | `chi bundle`: install/upgrade (3-way merge), build, uninstall; the install record under `.bundles/<name>/` that the hook, guardrail and plugin loaders read ([internals/bundles.md](internals/bundles.md)). |
+| Background | `Samagotchi::Worker`, `Samagotchi::SessionManager` | `SessionManager` forks/spawns one worker process per session; its `Worker` builds the `Engine` and `Bridge` (no terminal rendering) and runs queued turns. |
 | Web | `Samagotchi::Web::App`, `Samagotchi::Web::Server`, `Samagotchi::Web::SessionHub` | Rack+WEBrick single-port `127.0.0.1:4567` (index.html + `/api/*` + SSE). The hub is chi web's projection of the session list, pushed to every tab over `GET /api/events`. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File `sessions/<uuid>.json` + sidecar `input/`/`output/`; retention 14d/500, `updated_at desc`, lazy sweep. |
 
@@ -110,15 +117,16 @@ bin/chi ─▶ TerminalUI ─▶ Engine#run_turn ─▶ KernelLoop ──┬─
   `dismiss_question`). The worker runs in the session's `working_directory`, so `!cmd` and
   the tools don't depend on where the terminal attached from.
 - `bin/chi web` → builds `Web::Server` (Rack+WEBrick on `127.0.0.1:4567`, `--port`/`SAMAGOTCHI_WEB_PORT`, `--open`).
-- `bin/chi sessions {list,stop,delete,prune,clean}` (`SessionsCommand`; not the REPL's `SessionCommands`) → retention & ordering (`SessionRetention`, `updated_at desc`, dry-run, test-only); `stop` is `SessionManager.stop_session(wait:)`, which waits for the worker to release `owner.lock`; `delete` (`SessionDeleteCommand`) is `SessionManager.delete_session(stop:)`, which the TUI's `/exit --delete` and the web's `DELETE /api/sessions/:id` use too.
-- `--prompt`, `--non-interactive`, and `SessionManager` workers build `Engine` directly.
+- `bin/chi sessions {list,stop,restart,archive,unarchive,delete,prune,clean,stats}` (`SessionsCommand`; not the REPL's `SessionCommands`) → retention & ordering (`SessionRetention`, `updated_at desc`, dry-run, test-only); `stop` is `SessionManager.stop_session(wait:)`, which waits for the worker to release `owner.lock`; `delete` (`SessionDeleteCommand`) is `SessionManager.delete_session(stop:)`, which the TUI's `/exit --delete` and the web's `DELETE /api/sessions/:id` use too.
+- In REPL mode `TerminalUI` builds the `Engine` in process (`-p` and `--non-interactive` too);
+  otherwise the session's `Worker` (`lib/samagotchi/worker.rb`, spawned by `SessionManager`) builds it.
 
 ## Session retention & ordering
 
 - **Files:** `~/.local/state/samagotchi/sessions/<uuid>.json` + `<uuid>/input|output|owner.lock|bridge.json` (XDG-aware), and the `<uuid>/stopped` and `<uuid>/archived` marker files.
 - **Single owner:** the process running a session's Engine (worker or in-process TUI) holds a flock on `owner.lock` (`OwnerLock`); a second owner backs off, and the web answers 409 for a TUI-owned session.
 - **Status:** `status` is turn state (`idle`/`running`); liveness is the lock. A stop is the `<uuid>/stopped` marker (`Session.mark_stopped`; a resume removes it), which `Session.load` and `.summary_from_file` read as status `stopped`, so no other process rewrites a worker's session file.
-- **Retention:** 14 days / 500 cap (env `SAMAGOTCHI_SESSION_RETENTION_DAYS`/`MAX_COUNT`, optional `KEEP_STATUS`), live-owner guard, only when `*.json` present; lazy sweep ≤1/24h from the session hub's full-probe tick (and on `GET /api/sessions`, which the page no longer calls) & `Dashboard#render_list`, manual via `bin/chi sessions prune --dry-run`.
+- **Retention:** 14 days / 500 cap (env `SAMAGOTCHI_SESSION_RETENTION_DAYS`/`MAX_COUNT`, optional `KEEP_STATUS`), live-owner guard, only when `*.json` present; lazy sweep ≤1/24h from the session hub's full-probe tick (and on `GET /api/sessions`, which the page no longer calls), manual via `bin/chi sessions prune --dry-run`.
 - **Ordering:** `Session.list(sort:,order:,limit:,offset:)` and `GET /api/sessions?sort=&order=&limit=&offset=` default `updated_at desc`; Web UI sort/filter/pagination.
 - **Test hygiene:** `test_run` flag when `SAMAGOTCHI_ENV=test`/`RACK_ENV=test`/`CI`, targetable via `prune --test-only` / `clean`.
 
@@ -133,7 +141,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 | UI | `Samagotchi::TerminalUI` | Interactive REPL (Reline), rendering (ANSI, spinner, status line), REPL commands. Delegates all core work to an `Engine`. |
 | Model loops and adapters | `KernelLoop`, `LLM::ChatLoop`, `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::HTTP` | The model↔tool loops and the HTTP adapters they talk through (see "Model loops and adapters"). |
 | Bridge (SSE/HTTP) | `Samagotchi::Bridge`, `SessionManager` | The **single live client transport**: an SSE read stream + HTTP POST turn/cancel/answer surface that attaches to a worker's existing `Engine` via `Engine#subscribe`. Every session worker starts it (bound `127.0.0.1`, no auth, localhost-only). |
-| Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`; `/stream` proxies each session's Bridge). `bin/chi web` entrypoint. |
+| Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). It talks to each worker's Bridge (`App#relay`, `bridge_get`; `/stream` proxies it) and reads the session files; no `Engine` of its own. `bin/chi web` entrypoint. |
 | Sessions | `Samagotchi::Session`, `SessionManager` | File-based `~/.local/state/samagotchi/sessions/<uuid>.json` + sidecar `input/`/`output/`; retention (14d/500) + ordering (`updated_at desc`). |
 
 - `bin/chi` in REPL mode (see `LaunchMode` above) builds `TerminalUI`. `TerminalUI#run` is the single
@@ -141,7 +149,7 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
   builds the working session once, runs a single prompt turn when `-p` is given,
   then either exits (`--non-interactive`) or drops into the REPL carrying the
   post-turn conversation.
-- `SessionManager` background workers build `Engine` directly (no terminal rendering).
+- A session's `Worker` (spawned by `SessionManager`) builds its `Engine` (no terminal rendering).
 - `bin/chi` in attached mode (the default, `--attach`, `--shared`) builds no `Engine`: `TerminalUI::AttachLauncher` finds
   or starts the worker, and `TerminalUI::AttachedLoop` is a client of its Bridge
   (`BridgeClient#follow` for events, `post_turn`/`cancel`/`answer` for input). It
@@ -168,18 +176,23 @@ engine.run_turn(session, "hello", on_event: nil)   # => LLM::ModelResult (`.outp
 forwards the raw `KernelLoop` events unchanged (the low-level contract) and adds a few
 higher-level events so UIs get clean turn boundaries without inferring them:
 
-- `:turn_started` — `{ session_id:, prompt: }`
-- `:turn_completed` — `{ result: }` (the final `LLM::ModelResult`)
-- `:turn_canceled` — `{ cancellation_reason:, cancelled_by: }` (`cancelled_by`: the bundle or hook label that
+- `:turn_started` — `{ session_id:, prompt:, turn_id: }` (plus `continue: true` for a continue
+  turn, `images:` with the prompt's image refs)
+- `:turn_completed` — `{ result:, turn_summary:, display_pending: }` (`result`: the final
+  `LLM::ModelResult`; `display_pending`: `after_turn` hooks may still present the answer)
+- `:turn_canceled` — `{ cancellation_reason:, cancelled_by:, duration_ms: }` (`cancelled_by`: the bundle or hook label that
   stopped it, for `cancellation_reason: :hook`; else nil)
 
+A turn started with `origin:` carries it on each of these (and `:turn_failed`).
+
 Every event is a `Hash` with a `:type` symbol key; the sink must not raise (the Engine
 rescues sink errors). A new UI (web, API) supplies its own `on_event` and
 renders whatever it needs from the stream + final `Result`. The public Engine API:
 
 ```ruby
-engine.run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil) # nil: turn.max_iterations
-engine.run(session: nil, prompt: "...", on_event: nil)   # create/resume session + run
+engine.run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, # nil: turn.max_iterations
+                max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
+                images: [], id: nil)
 engine.system_prompt     # fully built system prompt string
 engine.session           # current session (Engine owns create/resume)
 ```
@@ -240,6 +253,9 @@ process that already owns the `Engine`); every worker starts it, and it exposes:
   `501 not_supported` with the restart hint; a Bridge `404 unknown_session`, no bridge or a
   refused connection is `503 not_live`.
 - `POST /session/:id/cancel` — cancel the running turn; `202`, or `409` when none runs.
+- `POST /session/:id/recap` — `/recap` in an attached TUI: `200 {enabled, saved, request,
+  min_user_turns}` (`{enabled: false}` without recaps); a new recap is asked for at once and
+  arrives as `:recap_ready`. Answers mid-turn too.
 - `POST /session/:id/answer` — answer the pending question; `200`, `409` when another client
   answered first or it is gone, `400` for an invalid selection. With `client_id: "cli:answer"`
   (`chi answer`, a parent agent) an allow on an approval beyond the worker's
@@ -318,8 +334,8 @@ Every route goes through `Bridge#dispatch`: an id other than the bridge's own se
 The per-session port is OS-assigned (bound to `0`) and published to a `bridge.json` sidecar
 for client discovery. `chi web`'s `GET /api/sessions/:id/stream` proxies this bridge
 (503 `not_live` when the worker is not running; full history of any session is served by
-`GET /api/sessions/:id/output`). Resume/ring-buffer state is **in-memory** (v1) — durable
-cross-process resume is a staged next step, not part of v1.
+`GET /api/sessions/:id/output`). Resume/ring-buffer state is **in-memory**, per worker: a cursor from
+an earlier worker gets the `reset` snapshot, not a replay.
 
 **Session hub.** The cross-session layer (which sessions exist, who owns them, what changed)
 never pulls from the page: `chi web` runs one `Samagotchi::Web::SessionHub` (a thread inside
@@ -394,9 +410,10 @@ its own). An empty answer with a `length` stop and the context 90 % full or
 more is not asked again (a full window, not a thinking loop); with no finish
 reason it is. Both also keep one `ContextStatus` per turn: before each request
 it estimates how full the window is (the server's last count plus what the turn
-appended since), emits `:context_status` on a bucket change, and on a rise past
-the second threshold puts the model's own `[CONTEXT: …]` line on the tail as a
-system message (docs/internals/context-telemetry.md).
+appended since), emits `:context_status` on every request (so the web and the
+attached TUI get a fresh number each time), and on a rise past the second
+threshold puts the model's own `[CONTEXT: …]` line on the tail as a system
+message (docs/internals/context-telemetry.md).
 
 **Adapters.** `Client` (raw-prompt servers) and `LLM::OpenAIChat` (one per host,
 `HostRegistry#adapter_for`) share `LLM::HTTP`: timeouts, TLS for https, a line
@@ -421,3 +438,26 @@ server (`/props`), then the host's model list, then config.
 **Keys.** A host's API key comes only from the environment variable its
 `api_key_env:` names; it never reaches config.yml, `HOSTS_JSON`, `chi self`,
 logs or events.
+
+## Other components
+
+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`) | A session's background process: builds the `Engine` and `Bridge`, runs queued turns, exits when idle. |
+| Config | `config.rb` | Every setting as an `Entry`: env, config.yml and CLI layers ([configuration.md](configuration.md)). |
+| 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/loader.rb` | What a bundle's plugin registers: tools, commands, hooks, services ([plugins.md](plugins.md)). |
+| 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 registration and dispatch ([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)). |
+| 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` | External sources a session keeps fresh ([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. |
+| Analytics | `analytics_file.rb` (`AnalyticsFile`) | A session's `analytics.json` (`SessionMetrics#persist`). |
+| Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
+| Desktop | `desktop.rb`, `desktop/macos.rb`, `desktop_command.rb` | `chi desktop`, the macOS "Send to chi" helper ([desktop.md](desktop.md)). |

data/docs/configuration.md

@@ -1167,8 +1167,7 @@ described in their own sections.
 | `llm_context.policy` | the subtask-boundaries line | | The sentence `forget_outputs`' description carries (the `forget` layer): "Tidy at subtask boundaries: once a subtask is done, forget its tool outputs and note what it established; keep anything you'll still edit against." Blank: none. Read when a session starts. |
 | `context.chars_per_token` | `4.0` | yes | Estimate ratio when the server reports no usage. |
 | `memory.index_warn_tokens` | `2500` | yes | The tokens one scope's memory index (project or system; sent with every prompt) may hold before a `memory_write`, `write` or `edit` that takes it over gets a note asking the model to tighten long index descriptions; `0`: no note. Estimated as characters / `context.chars_per_token`. `memory:` is its own section, not the `memories:` preload list. See [Memory](memory.md). |
-| `context.status_thresholds` | `20,40,60,80` | yes | Percentages that trigger a status. |
-| `context.status_cadence` | `0` | yes | Also every N rounds; `0` = thresholds only. |
+| `context.status_thresholds` | `20,40,60,80` | yes | Percentages that put the estimate into a bucket; the rise into a guidance bucket (from the second up) leaves the model its own `[CONTEXT: …]` line, and the bucket decides the guidance. |
 | `context.every_seconds` | `300` | | How often an attached context source's command runs when it has no `--every` (seconds, at least 30). See [Attached context](context.md). |
 | `context.wake` | `true` | yes | A source whose update says `wake: true` may start a turn in a live, idle session (one per source per 10 minutes, within `session.max_wakes`); `false`: updates wait as notes for the next turn. See [Waking](context.md#waking). |
 | `thinking.turn_preamble` | `true` | yes | Ask a `qwen36` model to open its thinking with a short `TURN:` line (the step label). |

data/docs/context.md

@@ -25,7 +25,8 @@ update.
 - **A command** (`--cmd CMD`): chi runs it every `--every` seconds (at least
   30; default `context.every_seconds`, 300) while the session's worker is up.
 - **Pushed** (`--push`): nothing runs; `chi context push NAME` (stdin, or
-  `-m TEXT`) sets its text. Only a pushed source takes a push: a command
+  `-m TEXT`) sets its text, as plain text or the same JSON a command prints
+  ([below](#the-command-contract)). Only a pushed source takes a push: a command
   source's text is its command's.
 - **A URL** (`chi context add URL`): an installed bundle's provider turns it
   into a command source (name, command, hint, interval). The `github-pr`
@@ -38,19 +39,24 @@ for up to 60 s; stdout is the text (up to 1 MiB), stderr goes to the debug
 log. It gets two variables:
 
 - `SAMAGOTCHI_CONTEXT_NAME`: the source's name;
-- `SAMAGOTCHI_CONTEXT_PREVIOUS`: the path of the last snapshot (JSON with
-  `text`), absent the first time, so the script can say what changed.
+- `SAMAGOTCHI_CONTEXT_PREVIOUS`: the path of the last snapshot, absent the
+  first time, so the script can say what changed. It is JSON: `text` (missing
+  while every run so far failed), `summary`, `fetched_at`, `error` and a few
+  more. Only the text is kept from your output: an extra key of yours (a
+  cursor) isn't there next time.
 
 Its output is either:
 
 - **plain text**: all of it is the text; chi's summary is
-  `content changed (+12/−3 lines)`. It never wakes the session.
-- **JSON**, an object with a string `text`:
+  `content changed (+12/−3 lines)` (`12 lines of text` the first time). It never wakes the session.
+- **JSON**: output that starts with `{` and parses as an object with a string
+  `text` (anything else is plain text):
   ```json
   {"text": "...the full text...", "summary": "2 new comments; checks failing", "wake": true, "hint": "optional new hint"}
   ```
   `summary` (one line, up to 200 characters) goes into the update note;
-  `wake: true` asks for a turn ([Waking](#waking)). Unknown keys are ignored.
+  `wake: true` asks for a turn ([Waking](#waking)); `hint` replaces the
+  source's hint until a later output gives another. Unknown keys are ignored.
 
 A non-zero exit, a timeout, more than 1 MiB or empty output is a failed
 fetch: the last good text stays, and the agent hears once, at the first
@@ -84,7 +90,7 @@ web) without touching the other sessions.
 
 ```
 chi context add NAME (--cmd CMD | --push) [--every SECONDS] [--why TEXT] [--hint TEXT] TARGET
-chi context add URL [--why TEXT] TARGET          a URL an installed bundle's provider knows
+chi context add URL [--why TEXT] [--hint TEXT] TARGET   a URL an installed bundle's provider knows
 chi context push NAME [-m TEXT] [TARGET]         new text for a --push source (stdin without -m)
 chi context ls [TARGET] [--format json]
 chi context show NAME [--json] [TARGET]
@@ -95,11 +101,100 @@ chi context mute|unmute NAME ID...               a project source, for one sessi
 
 `TARGET` is session ids (or unique prefixes) or `--project`. Inside a chi
 session (its `execute`) the default is that session. `NAME` is `a-z`, `0-9`
-and `-`, up to 40 characters.
+and `-`, up to 40 characters, starting with a letter or digit
+(`subscriptions` is taken).
 
 In a session, `/context` lists what is attached (as `context_read` does
 with no name).
 
+## Recipes
+
+Anything that prints text is a source.
+
+```sh
+# a file you keep editing
+chi context add todo --cmd 'cat ~/notes/todo.md' --every 60 --why "my running todo" --project
+
+# an Apple Note (macOS asks once to let chi control Notes)
+chi context add plan --cmd "osascript -e 'tell application \"Notes\" to get plaintext of note \"Plan\"'" --project
+
+# pushed by something else: a Shortcut, a cron job, the clipboard
+chi context add clip --push --project
+pbpaste | chi context push clip --project
+```
+
+### A stream: chat, a log, a feed
+
+A source's text is a snapshot, not a log: each run replaces it. For
+something that only grows (a chat channel, CI events, a log), let the script
+keep a window of the latest items and fetch only what's new. chi keeps no
+state for the script apart from the last text, so the cursor lives in the
+text: each item is a line starting with its id, and the script reads the
+newest id from `SAMAGOTCHI_CONTEXT_PREVIOUS`.
+
+```ruby
+#!/usr/bin/env ruby
+# chat-feed: the last KEEP items of a stream, fetching only the new ones.
+require "json"
+
+KEEP = 50
+LINE = /\A#(?<id>\S+) /   # each item is one line: "#<id> 14:02 @ann: text"
+
+# Swap this for the real thing (Slack's conversations.history with oldest:,
+# a log file, an RSS feed…). Here: items from a JSONL file, one per line.
+def fetch_since(since_id)
+  File.readlines(ARGV.fetch(0), chomp: true).map { JSON.parse(_1) }
+      .select { since_id.nil? || _1["id"].to_s > since_id }
+end
+
+prev_path = ENV["SAMAGOTCHI_CONTEXT_PREVIOUS"]
+prev = prev_path && JSON.parse(File.read(prev_path))["text"]  # absent or no text: first run
+old_lines = prev.to_s.lines(chomp: true).grep(LINE)
+since_id = old_lines.last&.match(LINE)&.[](:id)
+
+new_items = fetch_since(since_id)
+new_lines = new_items.map { "##{_1["id"]} #{_1["ts"]} @#{_1["author"]}: #{_1["text"].tr("\n", " ")}" }
+lines = (old_lines + new_lines).last(KEEP)
+
+summary =
+  if new_items.empty? then "no new messages"
+  else "#{new_items.size} new from #{new_items.map { "@#{_1["author"]}" }.uniq.join(", ")}"
+  end
+wake_word = ENV["FEED_WAKE_ON"]
+wake = !wake_word.nil? && new_items.any? { _1["text"].include?(wake_word) }
+
+puts JSON.generate(text: lines.empty? ? "(no messages yet)" : lines.join("\n"), summary:, wake:)
+```
+
+```sh
+chi context add chat --cmd "FEED_WAKE_ON=@me ~/bin/chat-feed ~/chat.jsonl" --why "team chat" --project
+```
+
+What makes it work:
+
+- **Nothing new, same text.** The script prints the old window again, the
+  hash doesn't change, and the agent hears nothing.
+- **The window keeps it small.** The text has to stay under 1 MiB, and a
+  small model's context window is smaller still.
+- **The summary gives counts and authors, never the words** ("3 new from
+  @ann, @bob"), like the github-pr bundle's: other people's words reach the
+  agent only when it reads the text, framed as third-party.
+- **Wake rarely.** A busy channel that wakes on every message keeps a
+  session (and its bill) running; wake on what is meant for you.
+- **A failed run keeps the last text**, so the next run picks up from the
+  last good cursor.
+- **Edits and deletions aren't seen.** An id already in the window isn't
+  fetched again.
+
+The cursor lives in the text because chi keeps nothing else from the output.
+A script that wants it out of the text keeps its own file (say under
+`$XDG_STATE_HOME/<your tool>/`, by `$SAMAGOTCHI_CONTEXT_NAME`). Two sessions
+with a session source of the same name would share that file.
+
+An attached source feeds the sessions you attach it to. To drop an item and
+let chi find the sessions it concerns, pipe it to
+[`chi broadcast`](broadcast.md) instead.
+
 ## What the agent sees
 
 Notes join the conversation **between turns** (a change during a turn waits
@@ -226,7 +321,7 @@ project root, working directory, branch, PR URL, main checkout or worktree,
 model), `attached` and `declined` (with the seconds since the offer), and
 `first_prompt` (the first 160 characters of every session's first message,
 offered or not; a fork's first after the conversation it started from, once;
-not scratch sessions or delegate children). Over 1 MB it is
+not scratch sessions or delegate children). Over 1 MiB it is
 renamed to `offers.ndjson.1` (one old file is kept). Only you can read it
 (0600), and nothing leaves your machine.
 

data/docs/internals/background-tasks.md

@@ -24,6 +24,6 @@ Behavior:
 - `task_get` returns metadata and `output_path`; use `read` for output contents.
 - `task_wait` accepts `timeout`, `tail_lines` (maximum 100), and `done_pattern` (a regular expression string).
 - `task_create` accepts `env` as a JSON object string for deterministic overrides such as `PATH`; use an absolute interpreter path when that is simpler. Ruby/Bundler isolation variables remain protected.
-- `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent) and `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown). `chi self` reads the latter for its `model` row. A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
+- `execute` and `task_create` export chi's own markers into the command, set over the model's `env` (which can't set them: `Error: env key is reserved`): `SAMAGOTCHI_PARENT_SESSION` (the session's id, `chi` without one; a chi started there answers as a parent agent), `SAMAGOTCHI_SESSION_MODEL` (the resolved ref the session runs on, read at each call so it follows `/model`; unset when unknown) and `SAMAGOTCHI_SESSION_THINKING` (the session's own thinking level; unset when it has none). `chi self` reads the last two for its model and thinking level. The three are `TaskRuntime::MARKER_ENV_KEYS` (and `SessionManager::SESSION_MARKER_ENV`, which a spawned worker unsets). A session's worker never inherits them from whoever started it (a `chi send` run by another session's `execute`): its other commands (a user's `!cmd`, an MCP server, a context command) have none.
 
 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

@@ -0,0 +1,73 @@
+# Memory bundles: install, upgrade and build
+
+How `lib/samagotchi/memory_bundle/` turns a bundle (a dir, git URL, zip or tar holding `manifest.yml`, `*.md`
+memories and optional `hooks/`, `guardrails/`, a plugin file and `scripts/`) into installed state, and back. The
+user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memory.md#what-a-bundle-owns) and
+[plugins.md](../plugins.md).
+
+## Where things live
+
+```
+<scope memories dir>/            MemoryPaths.scope_dir: system ~/.config/samagotchi/memories,
+                                 project <system>/projects/<project key>
+  *.md, index.md                 the bundle's memories, one managed index line each ("· from <bundle>")
+<system memories>/.bundles/      MemoryPaths.bundles_dir
+  <name>/manifest.json           the install record (Provenance#write, read as InstalledBundle)
+  <name>/bases/                  each file as installed: the base of the next upgrade's 3-way merge
+  <name>/hooks/ guardrails/ plugin/ scripts/
+  .trash/<name>-<stamp>/         files an uninstall or upgrade took away (Trash), never deleted
+```
+
+## Components
+
+| Piece | Role |
+|---|---|
+| `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash`; runs the Installer, prints its summary, runs the conflict agent step |
+| `SourceNormalizer` (source.rb) | source → local dir; a git/zip/tar extract is *owned* and removed after the install |
+| `Manifest` | parses/validates `manifest.yml` (files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers) and writes it (`Manifest.write`, for Builder) |
+| `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` |
+| `Provenance` | the `.bundles/<name>/` dir: `#write` the record + bases, `#record` → `InstalledBundle`, `.each_installed`, `.claimants` (which bundles own a file) |
+| `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty) |
+| `Builder` | `chi bundle build`: memories (+ the installed bundle's hooks, rules, plugin, scripts) → zip/tar/dir |
+| `Profile` | meta bundles (`includes:`): install the members, record which |
+| `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |
+| `Uninstaller`, `Trash`, `Status`, `Listing` | remove, keep removed files, `chi bundle status`, `chi bundle list` |
+| `IndexUpdater`, `IndexSync` | the managed `index.md` lines (Installer; and the write/edit tools for memories) |
+
+Readers of the installed state: `Hooks::BundleLoader` (Engine), `GuardrailWiring#bundle_rules`, `Plugin::Loader`,
+`ContextProviders` (scripts), `BundleNeeds` (index markers). Each goes through `Provenance.each_installed` / `#record`
+and checks the recorded sha256 (and `requires_chi`) before loading.
+
+## Installer#run, in order
+
+The order matters: warnings print in it, and a plugin/script the manifest names but the bundle lacks raises
+`InstallError` after the memories are already copied.
+
+1. `load_source`: normalize, read `manifest.yml` (strict: a missing/invalid one raises; non-strict: a warning).
+2. `resolve_target`: scope = CLI > manifest > `system`.
+3. `install_memories`, per `*.md`: an upgrade 3-way merges the files the bundle owns (`merge_memory`), a dry run only
+   classifies (`preview_memory`), a plain install writes new files and skips existing ones (`skip_existing`). A
+   same-name file the bundle didn't write is the user's: skipped and never recorded (`@owned`). Model overlays
+   (`<name>.<key>.md`) get no index line (`note_overlay`).
+4. `AssetInstaller#run`: hooks (manifest-listed, else every `hooks/*.rb`), prune dropped hooks, hook checksums,
+   guardrails, plugin, scripts; each set replaces the previous version's. requires_chi warnings for hooks/rules.
+5. An upgrade's `prune_dropped_files`: unchanged → trash; edited → kept (`kept_pruned`); owned by another bundle → kept.
+6. `verify_memory_checksums` (strict), `warn_missing_needs`.
+7. `write_provenance` (manifest, not a dry run): bases come from the incoming file, except where the user's edit was
+   kept (kept/noop/conflict/kept_pruned, or a re-install's skipped edit): those keep the old base, so the next
+   upgrade still sees the edit.
+8. `detect_placeholders`.
+
+Results are `@results` (file → `{status:, reason:}`), summarised by `#summary`. An upgrade with conflicts keeps an
+owned source dir alive (`#source_dir`) until `#cleanup_source!`, because the conflict agent reads the incoming
+files; `Provenance#resolve_conflicts` then moves the resolved files' bases forward.
+
+## Builder#run, in order
+
+`select_memories` (all but `index.md`/hidden; with `--files` the named ones + their overlays, else leaving out files
+another installed bundle owns) → `checksum_memories` → `installed_parts` (`Builder::InstalledParts`: the same-name
+installed bundle's hooks, rules, plugin, scripts, context providers, else the scope dir's `hooks/`/`guardrails/`) →
+`stage_files` + `write_manifest` in a temp dir → `write_out` (zip, tar, tgz, or a new/empty dir). An installed
+profile's name is refused (`refuse_profile!`): a build can't remake its includes.

data/docs/internals/context-telemetry.md

@@ -5,7 +5,7 @@ web/SSE clients) as a `:context_status` stream event. The telemetry itself is
 not injected into the model's conversation; what the model gets is one short
 line, as a tail system message (`kind: context`), when usage rises into a bucket
 whose guidance asks it to change how it works (from the second threshold, 40%
-by default, up; never on a fall or a cadence tick, and not again for a bucket a
+by default, up; never on a fall, and not again for a bucket a
 resumed session's line already names):
 
 `[CONTEXT: about 55% of the context window is in use (estimated; bucket=40plus). context moderate — prefer targeted and range reads over full-file dumps]`
@@ -19,8 +19,12 @@ carries a `status` string using this prefix:
 
 Emission behavior:
 
-- A status is emitted when estimated usage crosses configured threshold buckets.
-- Optional cadence-based updates can also be enabled every N rounds.
+- The estimate is emitted on every request (both loops, before each request),
+  so the web and the attached TUI get a fresh number each time.
+- The model's own `[CONTEXT: …]` line is still gated: it is left only on a rise
+  into a guidance bucket (from the second threshold up), never on a fall or a
+  cadence tick, and not again for a bucket a resumed session's line already
+  names.
 - This is warn-only behavior (no automatic history truncation).
 - When the model server reports real `usage` fields in the stream payload, the
   telemetry uses those actual token counts (prefixed `src=server`) instead of the
@@ -55,5 +59,4 @@ Configuration:
 - `SAMAGOTCHI_CONTEXT_STATUS` (`true` by default): set to `false` or `0` to disable telemetry.
 - `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` / `context.window_tokens`: context window size for when the server doesn't report one. chi asks llama.cpp for its real window first (`/props`, the per-slot `n_ctx`); this setting only fills in when it can't (mlx, oMLX, server down), and 256000 is the last resort.
 - `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN` (default `4.0`): heuristic ratio for char-to-token estimation.
-- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` (default `20,40,60,80`): comma-separated threshold percentages.
-- `SAMAGOTCHI_CONTEXT_STATUS_CADENCE` (default `0`): emit every N rounds in addition to threshold crossings.
+- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` (default `20,40,60,80`): comma-separated threshold percentages. The buckets' guidance still gates the model's own `[CONTEXT: …]` line; nothing else reads `context.status_cadence` (it was removed once the event streamed on every request).