samagotchi 0.53.0 → 0.55.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1d170176f088bc87560a05b7596d57925d955011cc5818b93f5ae33ae2b1f55
-  data.tar.gz: 941c3bd879e09b78144ede81d4c6cf4724f9ca3a7ce8fa62f0174524a26f25bf
+  metadata.gz: f90692cf867e2bd082f40c2ae576604656d23169163ed5584f9221ccec528ac1
+  data.tar.gz: ac4852809e3ccdc332dd0d052e17671096eb167691cdde6f01fc2ef6e43b9870
 SHA512:
-  metadata.gz: ddc3c2d02b18137887e5e90f636b23dd3ea44461f33a723e4033d58f4cfcd9c7be3267db9cc3349aba1d3af6b73a398415696e3af2c8fdad6662704944dad189
-  data.tar.gz: bd8bded906f5e3855c8f63ab081582b601d4b5332bb10e9ed5a7dff36e185851583c95d28e8b3528ece4d8b34463cc6e65fd16bb95bf2c493de502d9efa79775
+  metadata.gz: 541c55286cdad591988db3b43af6c60480061f931b418c83ff44afe3fe62e677df638021f082ce42241bd1f0145ca3a88173f9046341e9d282351cdc92814a1c
+  data.tar.gz: ae24243b3978c3f8f87a655c50d9f446128618b63d6dc5b10923f09eef90d11fcd4bee714692d287157340029f83097476c7d057f27c8ddff98c86f30678758b

data/CHANGELOG.md

@@ -8,6 +8,55 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.55.0] - 2026-10-10
+
+### Added
+
+- Web: refs. A file tool's row (read, edit, write) and the lines of its diff open the file in your editor: they look
+  like text until hovered (a dotted underline and `↗`, a diff line's `↗ N`), and a click opens the current file at the
+  line read or edited, the diff line's line or the hunk's start. Only a viewer on this machine gets them (a loopback
+  request, or this machine on its LAN address); the phone sees plain text. `web.editor` picks the editor: `vscode`
+  (the default), `vscode-insiders`, `cursor`, `zed`, `none`, or a URL template with `{path}` and `{line}`. The
+  browser and VS Code each ask once to allow it.
+- For development: `script/affected-specs`, the spec files to run for a change (changed specs, name matches,
+  docs-reading specs, specs naming the changed class), ranked and capped. It isn't part of the gem. See
+  [docs/testing.md](docs/testing.md).
+
+### Fixed
+
+- Web: a page that joins mid-turn (or reloads during one) keeps a grep that found nothing as a muted "no match" row,
+  as it showed live; it used to lose the mark.
+
+## [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 +2461,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.53.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.55.0...HEAD
+[0.55.0]: https://github.com/dm1try/samagotchi/compare/v0.54.0...v0.55.0
+[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/bin/chi

@@ -137,7 +137,7 @@ parser = OptionParser.new do |opts|
           "every session outside a repo) or all") { |v| options[:scope] = v }
   # Accepted values of string entries that the registry doesn't type as enums.
   value_hints = { "status.line" => "on|off", "web.host" => "127.0.0.1|::1|localhost|lan|IP", "recap.sentences" => "N|N-M",
-                  "web.annotate_presets" => "text|text" }
+                  "web.annotate_presets" => "text|text", "web.editor" => "vscode|vscode-insiders|cursor|zed|none|URL" }
   # Universal config flags (implicit convention: ENV SAMAGOTCHI_* ↔ YAML dotted ↔ CLI --kebab)
   # Generated from Samagotchi::Config registry — Option A: snake leaf in YAML, kebab in CLI.
   Samagotchi::Config.cli_entries.each do |entry|
@@ -235,7 +235,8 @@ if options[:web]
   view = Samagotchi::Config.get("web.view")
   exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
                                       markdown: markdown, view: view, new_token: options[:new_token],
-                                      annotate_presets: Samagotchi::Config.get("web.annotate_presets"))
+                                      annotate_presets: Samagotchi::Config.get("web.annotate_presets"),
+                                      editor: Samagotchi::Config.get("web.editor"))
 end
 
 # --resume and --attach take a unique id prefix too, like git.

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

@@ -1094,6 +1094,34 @@ its own). The first target is a long session such as a day-long coordinator, whe
   turn that runs a layer or whose session set its strategy) and the web's chip. A woken worker's status line counts
   its saved context against the session's budget.
 
+## Opening files from chi web
+
+In `chi web`, a file tool's row (read, edit, write) and the lines of its diff are refs to that file. They look like
+text until hovered (the title gets a dotted underline and `↗`, a diff line an accent bar and `↗ N`); a click opens the
+file in your editor: a row's title at the lines it read or edited (an edit without a range at its first changed
+line, a write at line 1), a diff line at its line, a hunk header at the hunk's start. A drag that selects text isn't
+a click. `web.editor` picks what opens:
+
+```yaml
+web:
+  editor: vscode     # or vscode-insiders, cursor, zed, none
+  # editor: "idea://open?file={path}&line={line}"   # a template of your own
+```
+
+- A preset, or a URL template with `{path}` (the absolute path, each segment URL-encoded, the slashes kept) and an
+  optional `{line}` (1 when there is none). A value that is neither a preset nor has `{path}` logs a warning and
+  counts as `none`. A change needs a `chi web` restart.
+- A template that puts `{path}` in a query (`?file={path}`) gets the path's slashes unencoded; editors accept that.
+- The first click asks twice, once each: the browser asks to open the editor's links (choose "always allow"; Safari
+  and Chrome ask per origin, so another `chi web` port asks again), and VS Code asks to allow opening local files.
+- It opens the file as it is now, not the agent's copy: after later edits a diff line's number can point elsewhere,
+  and a file in a worktree that was removed won't open. The row's diff and output are what the agent saw.
+- Only a viewer on this machine gets refs: a loopback request, or this machine on its own LAN address
+  (`web.host: lan`, the LAN URL or its QR code opened here). A phone sees plain text. An SSH tunnel or a local
+  reverse proxy (`tailscale serve`) looks like loopback, so a remote viewer behind one gets refs that can't open.
+- `GET /api/sessions/:id` (and its `?tail=1`) carries `capabilities.editor` (true for such a viewer) and
+  `editor_url`, the template (null otherwise).
+
 ## All settings
 
 Every setting below takes the three forms described in
@@ -1167,8 +1195,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). |
@@ -1209,6 +1236,7 @@ described in their own sections.
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |
 | `web.view` | `stage` | yes | How `chi web` draws a turn: `stage` (the running turn pinned above the composer) or `turn` (one block per turn in the history). See [CLI](cli.md#web-views). |
 | `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
+| `web.editor` | `vscode` | yes | What a file ref in `chi web` (a file tool row's title, a diff line) opens, for a viewer on this machine: a preset (`vscode`, `vscode-insiders`, `cursor`, `zed`) or a URL template with `{path}` and an optional `{line}`; `none` turns refs off. See [Opening files from chi web](#opening-files-from-chi-web). |
 | `history.file` | state dir | | Prompt history path, shared by the TUI and the web composer. |
 | `no_interrupt` | `false` | `--no-interrupt` | Raise the step limit of a turn to 1000 (or `turn.max_iterations`, when larger); a top-level key. |
 | `no_default_input` | `false` | `--no-default-input` | Don't pre-fill `default.input`; a top-level key. |

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).