samagotchi 0.152.0 → 0.154.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d208a5aecb9745a21107ab97399c7ec4901c24fd781e3ba4ec1658a69764ded
-  data.tar.gz: abc21f8bfe39f0bdc614b70b755dd3cd195d016dd305b6d3ba28b018d0b75d54
+  metadata.gz: 43fce920e24b60bc0bb9b5211dbc894f272e4f82ea55e6568698b533083f0c66
+  data.tar.gz: 5af718499f366587969cef9318c16e271fa343a69362f1ba5ed227992d2ab4d8
 SHA512:
-  metadata.gz: 1105443bb7097fd93f0ab4bb1f0f9926fbbc9c89f9d57584d12ae3ac560b726498c607c1e897416e8a17f0e150076fc7de2b2b19b0919b49ad5b40645dd3883a
-  data.tar.gz: ba009b4669d67eb24ccd15cf669f84431a1738153b721c13c18633d6b05f32cdd4bfd01d25530b18ef5ab39cbf84e0b19688691f6751884c92e0a8d412935771
+  metadata.gz: 5f3a52420f92d4335f0c156cd208b5b40d8b952a692861d2ca0e6672caea3d66bb033f6e04f0c3288fe6415ae48c63d8489ef8be6cd24c57086861b3117c7746
+  data.tar.gz: d9a8a9c3cc79549bf476f43900669ac68e212ed419c76ec362b8e9483d937eb70537f00b9d63a3e904417205dd42db069662e13127ee3cadf710b18bdc4fa058

data/CHANGELOG.md

@@ -8,6 +8,48 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.154.0] - 2026-11-07
+
+### Changed
+
+- `chi scratch` in a terminal runs attached, on a session worker of its own that saves nothing (no memory writes, no delegates, approvals for this session only). Ctrl-D, `/detach`, `/exit` or a second Ctrl-C ends it: the worker stops and the session is deleted ("Scratch session deleted."); a worker whose terminal is gone (a killed terminal) deletes it too. `chi send`, chi web and `chi --attach`/`--resume` refuse a scratch session, in one wording. `chi scratch -p TEXT --non-interactive` still runs its turn in this process.
+- `chi -v` runs attached: the terminal shows the session's debug records (raw LLM responses, tool calls and results) above the prompt, and a worker this chi starts logs at debug. A worker that was already running keeps the level it started with, and one line says so. With `--non-interactive`, `-v` still mirrors the records to stderr.
+- A session a `chi -p … --non-interactive` run has open is refused as "in use by a one-turn chi --non-interactive run or an older chi's terminal" (`chi send`, `chi note`, `chi sessions delete`/`archive`, chi web, the delegate tools), not as "open in a chi REPL".
+- `chi bundle upgrade --agent` merges the conflicts in the attached terminal.
+- chi now writes a warning to the debug log when part of its work falls back after an error (a system prompt section left out, a Bridge route or a chi web answer given empty, a session command's lookup) instead of dropping it silently: once per process for each kind, later ones at `debug`.
+
+### Removed
+
+- The in-process REPL: an interactive `chi` (plain, `-p`, `--resume`, `--attach`) always runs attached to its session's worker; `--non-interactive` runs its one turn in this process as before.
+- The `--shared` and `--no-shared` flags (they are an unknown option now) and the `session.shared` setting (config.yml warns "removed: chi always runs attached"; `SAMAGOTCHI_SESSION_SHARED` is ignored).
+- The `:repl` interface: a hook event's `interface` and a plugin's `ctx.frontend` are never `:repl` (a bundle that checks for it never matches).
+
+### Fixed
+
+- `chi scratch`: a terminal whose stream drops and reconnects no longer has its turn cancelled and its session deleted by the worker; the worker waits about 25 s with no stream before it takes the terminal as gone.
+- chi web: a diagram drawn by a block renderer is usable without a mouse: a screen reader hears that its source is behind the "Show the source" button, and a button that shows on keyboard focus zooms it to full size and back.
+- The objectives tool refuses a proposal its card's Apply would refuse (an add or reword whose text is only a status like `[done]` or only `(done when: …)`, or `done` for a dropped objective), so the model hears why instead of leaving a card that can't apply.
+- A thought the model never closed no longer reaches the continue note's "Its last answer" or decision-card's `/short`: both read the answer as you saw it, with the one rule a Check this record uses (a bundle gets it as `ctx.last_answer`). decision-card 0.2.1.
+- chi web: a reply that is only a thought the model never closed is no longer shown as an answer or taken as the session's last answer.
+
+Update with `chi update` (decision-card 0.2.1, the dev profile 0.7.7).
+
+## [0.153.0] - 2026-11-06
+
+### Added
+
+- A `web-search` bundle (`chi bundle install web-search`, in no profile): a `web_search` tool that searches the web through your own SearXNG and returns titles, URLs and snippets for `web_fetch` to read. It is declared on `full` and kits on `base: full`; on kits built on `lean` or `child` it is reachable (`find_tools` finds `chi/web_search`, `call_tool` runs it); `add: [web_search]` in a kit declares it. [docs/bundles.md](docs/bundles.md#the-web-search-bundle)
+
+### Changed
+
+- A bundle's tools (`chi.tool`) follow a toolkit's tool list as built-ins do: `full`, the kits on `base: full` (the `kits:` default) and a kit's `add:` declare them, any other kit leaves them reachable through `find_tools` / `call_tool` (deferred on `api: anthropic`), and `remove:` removes them. [docs/configuration.md](docs/configuration.md#toolkits)
+
+### Fixed
+
+- An attached context change that arrives while the worker's leaving pass is already in flight is saved as a note before the worker stops, instead of being dropped with its poller.
+
+Update with `chi update` (no installed bundle's version moved; `chi bundle install web-search` adds the new one).
+
 ## [0.152.0] - 2026-11-06
 
 ### Added
@@ -5717,7 +5759,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.152.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.154.0...HEAD
+[0.154.0]: https://github.com/dm1try/samagotchi/compare/v0.153.0...v0.154.0
+[0.153.0]: https://github.com/dm1try/samagotchi/compare/v0.152.0...v0.153.0
 [0.152.0]: https://github.com/dm1try/samagotchi/compare/v0.151.0...v0.152.0
 [0.151.0]: https://github.com/dm1try/samagotchi/compare/v0.150.0...v0.151.0
 [0.150.0]: https://github.com/dm1try/samagotchi/compare/v0.149.0...v0.150.0

data/README.md

@@ -119,7 +119,6 @@ hosts:
 
 ```sh
 chi                                       # interactive session the web UI can join too
-chi --no-shared                           # the plain in-process REPL
 chi -p "explain lib/" --non-interactive   # one turn, print the answer, exit
 chi --resume <session-id>                 # continue a saved session
 chi web --open                            # web UI: this project's sessions (--scope=all: every one)
@@ -200,7 +199,7 @@ Rules come from `config.yml` (`guardrails:`), installed bundles and hooks;
 the `guardrails` bundle (in `core`, which `chi bootstrap` installs; else
 `chi bundle install guardrails`) adds a default set (asks before `git push`,
 history rewrites, wide `rm -rf`, `curl | sh`, writes outside the repo; denies
-writes to `.git/hooks`). You answer in the REPL, the attached TUI or the web:
+writes to `.git/hooks`). You answer in the attached TUI or the web:
 once, for the session, for the repo, or for the whole rule in the repo.
 `/guardrails` lists the rules and your approvals. See [Guardrails](docs/guardrails.md).
 
@@ -209,7 +208,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [CHANGELOG](CHANGELOG.md): what changed in each release
 - [Releasing](docs/releasing.md): versions, the changelog, how a release is published
 
-- [CLI and REPL](docs/cli.md): flags, sharing a session, web UI, `/model`, status line
+- [CLI and terminal](docs/cli.md): flags, sharing a session, web UI, `/model`, status line
 - [Configuration](docs/configuration.md): `config.yml`, hosts, model server APIs, timeouts, retries, logs
 - [Memory](docs/memory.md): scopes, model-specific overlays and model notes
 - [Sessions](docs/sessions.md): storage, retention, `chi sessions`

data/bin/chi

@@ -139,7 +139,8 @@ if ARGV[0] == "web" && ARGV[1] == "push"
 end
 
 # `chi scratch`: the run options below, for a session that leaves nothing
-# behind (TerminalUI scratch:). The word goes before OptionParser sees it.
+# behind (AttachLauncher scratch:; TerminalUI's with --non-interactive). The
+# word goes before OptionParser sees it.
 scratch = ARGV[0] == "scratch"
 ARGV.shift if scratch
 
@@ -192,7 +193,7 @@ end
 
 # A scratch session is new, runs here and goes when it ends.
 if scratch
-  flag = { resume: "--resume", attach: "--attach", shared: "--shared" }.find { |key, _flag| options[key] }&.last
+  flag = { resume: "--resume", attach: "--attach" }.find { |key, _flag| options[key] }&.last
   if flag
     warn "Error: chi scratch starts a new session in this terminal and keeps nothing; it can't take #{flag}"
     exit 1
@@ -203,15 +204,19 @@ end
 # session's own level); a session-starting run's is that session's own
 # (TerminalUI, AttachLauncher), not a process setting.
 cli_overrides["thinking.level"] = options[:thinking] if web && options[:thinking]
+# -v: debug records, in this process and in a worker it spawns (Config.cli_env).
+cli_overrides["log.level"] = "debug" if options[:verbose]
 
 # Apply CLI precedence: CLI > ENV > file. Workers this chi spawns get
 # these through their env (Config.cli_env).
 Samagotchi::Config.reload!(cli_overrides: cli_overrides) unless cli_overrides.empty?
 
 # The debug log (Samagotchi::LogPath, level log.level) for every command.
-# -v (the plain REPL only): debug records, each mirrored to stderr.
+# -v: debug records; a --non-interactive one-shot mirrors each to stderr,
+# the attached TUI shows its session's above the live region (LogTail).
 require "samagotchi/log"
-Samagotchi::Log.configure(level: options[:verbose] ? :debug : nil, mirror: options[:verbose])
+Samagotchi::Log.configure(level: options[:verbose] ? :debug : nil,
+                          mirror: options[:verbose] && options[:non_interactive])
 
 # chi --remote NAME --attach ID (--resume ID, --dir DIR, -p TEXT): the
 # attached TUI on that machine's session. Nothing below runs: it checks
@@ -274,8 +279,9 @@ rescue Samagotchi::Session::AmbiguousId => e
   exit 1
 end
 
-# A `chi scratch` session a killed REPL left behind would turn into a kept
-# one if opened again; the next sweep deletes it.
+# A `chi scratch` session is its terminal's (a live one), or one a killed
+# terminal left behind, which would turn into a kept one if opened again;
+# the next sweep deletes it.
 %i[resume attach].each do |key|
   next unless options[key]
 
@@ -286,8 +292,7 @@ end
   end
   next unless leftover
 
-  require "samagotchi/launch_mode"
-  warn "Error: #{Samagotchi::LaunchMode::SCRATCH_LEFTOVER}"
+  warn "Error: #{Samagotchi::Session::SCRATCH_REFUSED}"
   exit 1
 end
 
@@ -395,12 +400,7 @@ end
 
 chi_update_hint.call
 require "samagotchi/launch_mode"
-launch, launch_note = if scratch
-                        [:repl, nil]
-                      else
-                        Samagotchi::LaunchMode.resolve(options, shared_config: Samagotchi::Config.get("session.shared"))
-                      end
-warn launch_note if launch_note
+launch = Samagotchi::LaunchMode.resolve(options)
 
 if launch == :attached
   error = Samagotchi::LaunchMode.attached_conflict(options)
@@ -411,7 +411,7 @@ if launch == :attached
 
   require "samagotchi/terminal_ui/attach_launcher"
   begin
-    ended = Samagotchi::TerminalUI::AttachLauncher.run(attach: options[:attach], shared: !options[:attach], resume: options[:resume],
+    ended = Samagotchi::TerminalUI::AttachLauncher.run(attach: options[:attach], resume: options[:resume],
                                                        prompt: options[:prompt], model: options[:model],
                                                        no_interrupt: !!options[:no_interrupt],
                                                        default_input: !options[:no_default_input],
@@ -423,7 +423,8 @@ if launch == :attached
                                                        toolkit: options[:toolkit_value],
                                                        toolkit_flags: options[:toolkit_flags] || [],
                                                        settings: options[:settings],
-                                                       parent_answers: options[:parent_answers])
+                                                       parent_answers: options[:parent_answers],
+                                                       scratch: scratch, verbose: options[:verbose])
   rescue Samagotchi::TerminalUI::AttachLauncher::Error, Samagotchi::Toolkit::Refused => e
     warn "Error: #{e.message}"
     exit 1
@@ -435,13 +436,13 @@ if launch == :attached
   exit Samagotchi::TerminalUI::AttachLauncher.exit_status(ended)
 end
 
+# --non-interactive: the -p prompt's one turn in this process (TerminalUI,
+# the one-shot host); bare, a no-op that creates no session.
 require "samagotchi/cli/exit"
 begin
   ended = Samagotchi::TerminalUI.new(
     prompt: options[:prompt],
     session_id: options[:resume],
-    no_interrupt: options[:no_interrupt] || options[:non_interactive],
-    no_default_input: options[:no_default_input],
     memories: options[:memories] || [],
     muted_memories: options[:muted] || [],
     llm_context: options[:llm_context] || {},
@@ -451,13 +452,11 @@ begin
     toolkit_flags: options[:toolkit_flags] || [],
     settings: options[:settings],
     parent_answers: options[:parent_answers],
-    non_interactive: options[:non_interactive],
     model_name: options[:model],
     scratch: scratch
   ).run
-  # `chi -p X </dev/null`: the turn failed (nothing was sent again); -p
-  # --non-interactive: the turn ended with no answer or at the iteration
-  # limit, or Ctrl-C cancelled it.
+  # The turn failed, ended with no answer or at the iteration limit, or
+  # Ctrl-C cancelled it.
   exit 1 if %i[turn_failed empty_answer iteration_limit].include?(ended)
   exit Samagotchi::CLI::Exit::INTERRUPTED if ended == :interrupted
 rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFound, Samagotchi::ModelProfile::MissingModel,
@@ -465,11 +464,11 @@ rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFo
   warn "Error: #{e.message}"
   exit 1
 rescue Samagotchi::LLM::ProviderError => e
-  # -p --non-interactive: the turn failed; its prompt is in the session.
+  # The turn failed; its prompt is in the session.
   warn "Error: #{e.summary}"
   exit 1
 rescue Samagotchi::ImageStore::Error => e
-  # -p --non-interactive: an @path image that can't be used.
+  # An @path image that can't be used.
   warn "Error: #{e.message}"
   exit 1
 end

data/docs/architecture.md

@@ -10,9 +10,9 @@ A compact visual overview of the current architecture, then the core API in pros
                        │                                          │
   ┌────────────────────┴────────────────────┐    ┌───────────────┴────────────────┐
   │                TerminalUI               │    │        Web::App (Rack)         │  ← browser UI
-  │  attached (default): AttachLauncher +   │    │  session hub · /api/events     │
+  │  interactive: AttachLauncher +          │    │  session hub · /api/events     │
   │    AttachedLoop, no Engine              │    │  /api/* · reads session files  │
-  │  REPL (--no-shared …): its own Engine   │    └───────────────┬────────────────┘
+  │  --non-interactive: its own Engine      │    └───────────────┬────────────────┘
   └────────────────────┬────────────────────┘                    │ App#relay, bridge_get,
                        │ BridgeClient (SSE + HTTP)               │ /stream proxy
                        └────────────────────┬────────────────────┘
@@ -60,7 +60,7 @@ A compact visual overview of the current architecture, then the core API in pros
 
 ```
 TerminalUI  ──  delegates  ──▶  Engine
-(REPL / render / commands)         (pure logic, no terminal)
+(one-shot host)                 (pure logic, no terminal)
         ▲                                  │
         └────────── on_event: ◀────────────┘
              (turn_started, turn_completed,
@@ -69,13 +69,14 @@ TerminalUI  ──  delegates  ──▶  Engine
 
 - **`Engine`** (`lib/samagotchi/engine.rb`) owns *all* agent logic and knows nothing
   about the terminal ([internals/engine.md](internals/engine.md)).
-- **`TerminalUI`** (`lib/samagotchi/terminal_ui.rb`) owns the REPL and rendering; it
-  delegates all core work to an `Engine`.
+- **`TerminalUI`** (`lib/samagotchi/terminal_ui.rb`) is the one-shot host: `chi -p TEXT
+  --non-interactive` (with `--resume ID` or `chi scratch` too) runs that one turn in this
+  process, its answer alone on stdout, and delegates all core work to its `Engine`. Every
+  interactive terminal is the attached one (`TerminalUI::AttachLauncher`, `AttachedLoop`).
 - The `on_event:` seam on `run_turn` exposes raw `KernelLoop` events plus the
   higher-level turn events, so any new UI can render without terminal coupling.
 - **`ComposerRoute`** (`lib/samagotchi/composer_route.rb`) decides where a line typed at
-  either terminal's prompt goes (the REPL's `steer_line` / `run_input_line`, the attached
-  `AttachedLoop::Composer#submit`): `/cut TEXT` / `/queue TEXT`, a terminal's own word, a session
+  the attached terminal's prompt goes (`AttachedLoop::Composer#submit`): `/cut TEXT` / `/queue TEXT`, a terminal's own word, a session
   command, a typo, a prompt. Each UI keeps what it does with the route. The web's
   `composer.js#routeComposerLine` decides the same; `spec/fixtures/composer_routes.json`
   holds the cases both answer (see [testing.md](testing.md)).
@@ -90,7 +91,7 @@ bin/chi ─▶ TerminalUI ─▶ Engine#run_turn ─▶ KernelLoop / ChatLoop
                                     (turn started / completed / canceled)
 ```
 
-That is the REPL; attached (the default) the session's `Worker` calls `Engine#run_turn` and the
+That is a `--non-interactive` one-shot; interactive, the session's `Worker` calls `Engine#run_turn` and the
 terminal renders the events it gets over the Bridge.
 
 ## Layers at a glance
@@ -98,7 +99,7 @@ terminal renders the events it gets over the Bridge.
 | Layer | Class(es) | Responsibility |
 |-------|-----------|----------------|
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, model↔tool loop (`run_turn`). No terminal coupling. |
-| UI | `Samagotchi::TerminalUI` | REPL (Reline), rendering, REPL commands. Delegates all core work to an `Engine`. |
+| UI | `Samagotchi::TerminalUI`, `TerminalUI::AttachLauncher` / `AttachedLoop` | `TerminalUI`: the `--non-interactive` one-shot host, its own `Engine`. The attached TUI (every interactive `chi`): a client of the session worker's Bridge, no `Engine`. |
 | Model loops | `KernelLoop` (via `LLM::NativeBackend`), `LLM::ChatLoop` | The model↔tool loop: raw prompt, or a chat API (OpenAI chat, Anthropic Messages), chosen per host (see below). |
 | Adapters | `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | Raw-prompt servers, the OpenAI chat API, Anthropic's Messages API, and the HTTP they share. |
 | Tools | `lib/samagotchi/tools/*` | Execute, read, edit, write, memory, task_*, web_fetch, delegate/delegate_result, ask_user_question, reminders, send_note, list_sessions, context_read, objectives, forget_outputs, find_tools/call_tool (the tool index), plus runtime/output-guardrails. |
@@ -109,29 +110,27 @@ terminal renders the events it gets over the Bridge.
 
 ## Entry points
 
-- `LaunchMode.resolve` picks the terminal's mode. By default (`session.shared: true`)
-  plain `bin/chi`, `-p` and `--resume ID` run attached, like `--shared`; `--no-shared`,
-  `session.shared: false`, `--non-interactive` and `--verbose` run the REPL. `--memory`
+- `LaunchMode.resolve` picks the terminal's mode: `:attached` (plain `bin/chi`, `-p`,
+  `--resume ID`, `--attach ID`, `-v`) or `:one_shot` (`--non-interactive`). `--memory`
   and `--mute` are session fields (`preloaded_memory_names`, `muted_memory_names`) the
   worker reads when it builds its `Engine`; `MutedMemories` filters the prompt's index and
   the kernel's `memory_read`.
-- The REPL → builds `TerminalUI`. `TerminalUI#run` is the single dispatch
-  for the REPL, `-p`/`--prompt`, `--non-interactive`, and `--resume`.
-- Attached (`bin/chi`, `--attach ID`, `--shared [--resume ID]`) → `TerminalUI::AttachLauncher`: no `Engine`
+- One-shot → builds `TerminalUI`: the `-p` prompt's one turn (a new session, `--resume ID`'s or
+  `chi scratch`'s) under an `OwnerLock` of kind `"tui"`; bare `--non-interactive` is a no-op.
+- Attached (`bin/chi`, `-p`, `--attach ID`, `--resume ID`) → `TerminalUI::AttachLauncher`: no `Engine`
   and no `OwnerLock`; finds or starts the session's worker and runs `TerminalUI::AttachedLoop`
   as a client of its Bridge (`BridgeClient#follow`, `post_turn`, `post_command`, `cancel`, `answer`,
   `dismiss_question`; opening the SSE connection answers `BridgeClient::StreamOpen::Opened`, `Refused` or `Unreachable`). 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`;
   `web.host: lan` adds a LAN address, `--new-token` replaces its access token).
-- `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.
+- `bin/chi sessions {list,stop,restart,archive,unarchive,delete,prune,clean,stats}` (`SessionsCommand`; not the session'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.
 - Session commands (`chi send`, `answer`, `note`, a session's `context`, `sessions list/stop/restart/archive/unarchive/delete`) →
   `SessionAccess` (`session_access.rb`): what they ask of a session goes through one backend object,
   `SessionAccess::Local` (`session_access/local.rb`) on this machine's files and workers; a `--wait`'s pre-send state
   (cursor, baseline, own turn) is `prepare_wait`'s `WaitStart`. `SessionAccess::Contract` lists which commands and flags
   run against a remote and which on this machine only.
-- 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.
+- A one-shot's `TerminalUI` builds the `Engine` in process; otherwise the session's `Worker` (`lib/samagotchi/worker.rb`, spawned by `SessionManager`) builds it.
 
 ## How chi launches itself
 
@@ -193,7 +192,7 @@ log's last 4 MB). Rows: [configuration.md](configuration.md#checking-it-chi-home
 ## 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.
+- **Single owner:** the process running a session's Engine (its worker, or a `--non-interactive` one-shot) holds a flock on `owner.lock` (`OwnerLock`); a second owner backs off, and the web answers 409 for a session a one-shot owns.
 - **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 at most once per `session.sweep_interval_hours` (default 24) 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.
@@ -207,22 +206,20 @@ agent logic and can be used without any terminal rendering; the UI is a thin lay
 | Layer | Class | Responsibility |
 |-------|-------|----------------|
 | Core | `Samagotchi::Engine` | System prompt, memory injection, tool declarations, session lifecycle, the model↔tool loop (`run_turn`). No terminal coupling. |
-| UI | `Samagotchi::TerminalUI` | Interactive REPL (Reline), rendering (ANSI, spinner, status line), REPL commands. Delegates all core work to an `Engine`. |
+| UI | `Samagotchi::TerminalUI`, `TerminalUI::AttachLauncher` / `AttachedLoop` | The attached TUI: rendering (ANSI, spinner, status line) and the terminal's own commands over the worker's Bridge. `TerminalUI`: the `--non-interactive` one-shot host, which delegates all core work to its `Engine`. |
 | Model loops and adapters | `KernelLoop`, `LLM::ChatLoop`, `Samagotchi::Client`, `LLM::OpenAIChat`, `LLM::AnthropicMessages`, `LLM::HTTP` | The model↔tool loops and the HTTP adapters they talk through (see "Model loops and adapters"). |
 | Bridge (SSE/HTTP) ([internals/bridge.md](internals/bridge.md)) | `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`, localhost-only), and it answers only a request that names its secret (`X-Chi-Bridge`, from the worker's 0600 `bridge.json`). |
 | Web (Rack) | `Samagotchi::Web::App`, `SessionManager` | Single-port `127.0.0.1:4567` control plane via `rack`+`webrick` (serve `index.html` + `/api/*`). With `web.host: lan` (or one of this machine's IPv4 addresses) the server also listens on that address, where every request needs the access token, this machine's on loopback too (`App#token_gate`: the `chi_token` cookie, on loopback a value derived from the token (`Token.loopback_cookie`), or `Authorization: Bearer`; chi web prints a `Local:` link with a one-time code; [CLI](cli.md#chi-web-on-your-phone)). Experimental: behind an auth proxy (`web.public_url`, `Web::ProxyGate`) every request needs the token, this machine's too, and one that came through the proxy also the configured identity header for the owner ([configuration.md](configuration.md#behind-an-auth-proxy)). A request goes through, in order: the Host check (`local_host_header?`: loopback names, the LAN address, the public host), the cross-site check (`cross_site?`: Origin this server's or the public origin, no `Sec-Fetch-Site` cross-site/same-site on a POST or `/api`), the frame check (`framed?`: a frame/embed/object load from another origin, 403 `framed`; every HTML answer carries `X-Frame-Options: DENY` and `frame-ancestors 'none'; frame-src 'none'`, so a page's own frames can't navigate either), the token gate (`token_gate` → `principal_for`, `proxied_principal` for a proxied request; the `?token=` / `POST /api/token` trade sets the cookie, `__Host-chi_token` through the proxy; with `web.public_url` a direct request takes Bearer only, and with it or LAN mode chi's token-less `/api/info` probe gets `probe_info`), then the route's permission (`Principal#permits?`). It talks to each worker's Bridge (`App#relay`, `bridge_get`; `/stream` proxies it) and reads the session files; no `Engine` of its own. Markdown (`web.markdown`) is rendered here only (`Web::MarkdownRenderer`): the answers it serves, card bodies, and `POST /api/render` for a text the page already shows. `App` keeps the gate, `ROUTES` and the helpers the handlers share; its handlers live in mixins it includes, each a `Web::` module with private methods: `SessionAccessRoutes` (`web/session_access_routes.rb`), `ParticipantAccess` (`web/participant_access.rb`), `ParticipantsAdmin` (`web/participants_admin.rb`), `ParticipantReview` (`web/participant_review.rb`), `MessageDisplay` (`web/message_display.rb`), `SessionShow` (`web/session_show.rb`), `SessionCreate` (`web/session_create.rb`), `SessionControl` (`web/session_control.rb`), `PushRoutes` (`web/push_routes.rb`) and `ProxyGate` (`web/proxy_gate.rb`). Exact paths in `GATE_FREE_PATHS` are served before the token gate (the fragment trade's script, and the Home Screen app's manifest, service worker and icons). `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
-  dispatch for the REPL, `-p`/`--prompt`, `--non-interactive`, and `--resume`: it
-  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.
+- `bin/chi` in one-shot mode (`--non-interactive`, see `LaunchMode` above) builds `TerminalUI`.
+  `TerminalUI#run` builds the session (new, `--resume`'s or `chi scratch`'s), runs the `-p`
+  turn with the answer alone on stdout and the session lines on stderr, and exits.
 - 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
+- `bin/chi` in attached mode (every interactive run) 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
-  renders through the same `EventRenderer` as the REPL, on an `AttachedView` that
+  renders through `EventRenderer`, on an `AttachedView` that
   draws on a `Screen`: a live region at the bottom of the terminal (activity row,
   prompt, status/notes/hints) under normal scrollback. From a turn's 3rd tool call the
   activity slot gets a second, dim row: the turn's tool tally (`TurnTally`, seeded from the
@@ -449,7 +446,7 @@ calling the `SessionAccess::Local` operation of the same name, so a remote backe
 token-gated like the rest (LAN mode: `Authorization: Bearer`), and one that takes an id is a `:session` route (an id
 that isn't one, or no such session: 404 `not_found`). Every `ROUTES` row also names who may use it, checked against
 the request's `Web::Principal` (`App#principal_for`): `owner`, or `participant` for a route a participant may use too.
-A participant (a `Web::Grants` token for one session) may use the page (`GET /`), `GET /api/info`, their session's
+A participant (a `Grants` token for one session) may use the page (`GET /`), `GET /api/info`, their session's
 show, review and filtered stream, and their turns and waits, each answered as theirs; every other route is `owner` (Permission below, and the participants routes in
 [internals/participants.md](internals/participants.md)); `spec/web/principal_spec.rb` fails on a row without one. How a request flows end to end, which checks run where and the trust
 model: [internals/remote-sessions.md](internals/remote-sessions.md).
@@ -472,7 +469,7 @@ model: [internals/remote-sessions.md](internals/remote-sessions.md).
 | `GET /api/sessions/:id?brief=1` | participant (theirs: title, status, participants) | | 200 `{brief, session: {id, status (the file's), title, display_title, project_root, working_directory, model_name, model_typed, parent_answers, owner}, pending_question}` (the file's; no messages): `Remote#show` | 404 |
 | `POST /api/sessions/:id/turn` (its 202) | owner | | the ack with `via`: `bridge` or `file` (the input file: a remote `chi send --wait` follows that turn) | |
 | `GET /api/sessions/:id/context?full=1`, `…/context/:name?full=1` | owner | | each row with `source` (`Source#to_h`, its command too; the page's rows never carry one), `snapshot` (`Snapshot#to_h`, no text) and `shadowed`, shadowed project sources included | |
-| `POST /api/sessions/:id/wake` | owner | `wait` (seconds, default and most 10: `WAKE_MAX_WAIT`) | 200 `{session_id, woke, worker: {epoch, started_at, version, features}, model_name, default_model, parent_strategy, installed}`: the live worker as is (`woke: false`), else resumed and its Bridge waited for (`Local#wake`); `default_model` and `installed` are this machine's | 409 `owned_by_tui`, `scratch` (`LaunchMode::SCRATCH_LEFTOVER`); 504 `worker_timeout` (`LaunchMode::BRIDGE_LATE`); 400 `invalid_wait`; 404 |
+| `POST /api/sessions/:id/wake` | owner | `wait` (seconds, default and most 10: `WAKE_MAX_WAIT`) | 200 `{session_id, woke, worker: {epoch, started_at, version, features}, model_name, default_model, parent_strategy, installed}`: the live worker as is (`woke: false`), else resumed and its Bridge waited for (`Local#wake`); `default_model` and `installed` are this machine's | 409 `owned_by_tui`, `scratch` (`Session::SCRATCH_REFUSED`); 504 `worker_timeout` (`LaunchMode::BRIDGE_LATE`); 400 `invalid_wait`; 404 |
 | `GET /api/sessions/:id/worker` | owner | | 200 `{session_id, live, stopped, owner: worker \| tui \| null, worker: {epoch, started_at, version, features} \| null, default_model, parent_strategy}` (`Local#worker`; never starts one; `default_model` is this machine's) | 404 |
 | `POST /api/sessions/:id/exit` | owner | `client_id` (passed on only when it is an attached TUI's, `tui:…`; any other is dropped), `delete` | 200 the worker's `{status: exiting, session_id, discard}` (`BridgeClient#request_exit`; never wakes one) | 409 `held` with the worker's `{status, reason, tasks, hint}`; 503 `not_live`; 501 `not_supported`; 504 `worker_timeout` |
 | `POST /api/sessions/:id/recap` | owner | | 200 the worker's `{enabled, saved, request, min_user_turns, session_off}` (`BridgeClient#request_recap`) | 503, 501, 504 as every relay |
@@ -593,7 +590,7 @@ credit held by in-flight requests, retried after 20 s), `OutOfCredits` (any othe
 402), `ServerError`, `AuthError`, `BadRequest` (`context_overflow?`) or `ProtocolError`. Engine keeps the turn's
 conversation (the prompt plus completed tool iterations) and emits
 `:turn_failed` with `error_kind:`, `retryable:`, `host:` and a one-line
-`summary:`, which the REPL, the attached TUI and the web show.
+`summary:`, which the attached TUI, a one-shot's stderr and the web show.
 
 **Usage and models.** A turn's token counts are `SessionMetrics`', read from the
 stream events (server counts, else a chars/4 estimate). Model lists are `LLM::ModelInfo`
@@ -628,15 +625,15 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Worker link | `worker_link.rb` (`WorkerLink`: `Live`, `Starting`, `Leaving`, `Skew`, `Stale`, `None`), `worker_sidecar.rb` (`WorkerSidecar`) | Whether a session's worker can be reached and the client for it: every Bridge client asks `WorkerLink.resolve` / `.client` / `.await` (*Worker link* above); `WorkerSidecar` is the `bridge.json` it reads. |
 | Session access | `session_access.rb` (`SessionAccess`: `NewSession`, `SetupWords`, `WaitStart`, `SessionView`, `Created`, `ContextEntry`, `ContextPush`, the errors `RemoteFailed`, `RemoteTooOld`, `Refused`, `BadRequest`), `session_access/local.rb` (`SessionAccess::Local`), `session_access/remote.rb` (`SessionAccess::Remote`), `session_access/http_transport.rb`, `session_access/web_bridge_client.rb` (`SessionAccess::WebBridgeClient`, a remote attach's worker through chi web), `session_access/dispatch.rb` (`SessionAccess::Dispatch`), `session_access/contract.rb` (`SessionAccess::Contract`), `remotes.rb` (`Remotes`), `remote_command.rb` (`chi remote`), `web/session_access_routes.rb` (`Web::SessionAccessRoutes`) | The seam between the session commands and where the sessions live: `Local` is this machine's (the `SessionManager`, `ReplyWait`, `NoteDelivery`, `ContextSources` and Bridge calls the commands made); `Remote` is another machine's, the same methods as requests to its chi web's routes of the same name (Bearer token, `HTTPTransport`), results as Local's value objects and refusals as the classes Local's callees raise, built from the fields chi web sends; waits and prefixes run on the server, a wait asked again per 30 s slice. `Dispatch` is bin/chi's front for `--remote NAME` / `CHI_REMOTE` (taken off before the subcommand lookup): it refuses what the contract table lists `local_only` (exit 2, one message) and runs the command with a `Remote` on the `Remotes` entry (`$XDG_CONFIG_HOME/samagotchi/remotes.yml`, 0600). chi web's routes answer from `Local` (*chi web's routes for the session commands* above). Checks that read this machine's config or files (vision, parent answers, the cwd's project, `SAMAGOTCHI_PARENT_SESSION`) stay in the commands and are skipped under a `Remote`, where chi web's create, turn and wait routes run the vision, parent-answers and busy checks with the server's config and the worker checks a parent's answer. See [internals/remote-sessions.md](internals/remote-sessions.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`, `context_candidates.rb` (`ContextCandidates`: proposed sources, attached on the owner's mention at a turn's start, before the worker's absorb, or in the REPL's turn; `owner_prompt.rb` decides whose words count), `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
+| Attached context | `context_sources.rb` (`ContextSources`), `context_poller.rb`, `context_absorber.rb`, `context_candidates.rb` (`ContextCandidates`: proposed sources, attached on the owner's mention at a turn's start, before the worker's absorb, or in a one-shot's turn; `owner_prompt.rb` decides whose words count), `peer_sources.rb` (`PeerSources`: the sources peer bundles declare) | External sources a session keeps fresh, and the peer loop's wakes ([context.md](context.md)). |
 | LLM context strategies | `llm_context_strategy.rb`, `llm_context_view.rb`, `llm_context_stale.rb`, `llm_context_forget.rb` | What a request sends of the history (none, stale, forget) ([internals/llm-context-forget.md](internals/llm-context-forget.md)). |
 | Session chains | `session_continue.rb` (`SessionContinue`), `session_chain.rb` (`SessionChain`) | A session that continues an earlier one. `SessionChain.opener_for` gives the text web `continue →` prefills in the new link: the previous link's own first typed message when that link continues one itself, else nil (the 201's `opener`; not saved) ([sessions.md](sessions.md)). |
 | Review sessions | `review_start.rb` (`ReviewStart`), `session_review.rb` (`SessionReview`, the session's `review` field), `review_command.rb` (`ReviewCommand`, `chi review`), `review_apply.rb` (`ReviewApply`) | A session made to be shared: idle, its subjects project files checked by `Guardrails::ReviewPaths`, a fork of a working session from its recap (`--from`); Apply quotes a participant's review turn into the owner's composer ([sessions.md](sessions.md#review-sessions), [internals/participants.md](internals/participants.md)). |
 | chi web's routes | `web/app.rb` (`Web::App`: the gate, `ROUTES`, the shared helpers), `web/message_display.rb` (`Web::MessageDisplay`: saved messages and cards as display items, `POST /api/render`), `web/session_show.rb` (`Web::SessionShow`: `GET /api/sessions/:id` with its `cards`, `tail` and `timing` re-reads, `GET …/output`, the timing payload), `web/session_create.rb` (`Web::SessionCreate`: `POST /api/sessions`, a continue, a review fork), `web/session_control.rb` (`Web::SessionControl`: answer, command, turn and images, cancel, stop, restart, archive, delete), `web/push_routes.rb` (`Web::PushRoutes`: `/api/push`, its subscriptions, prefs, test and presence), `web/block_renderer_routes.rb` (`Web::BlockRendererRoutes`: `GET /api/block_renderers` and one renderer's file, [internals/block-renderers.md](internals/block-renderers.md)) | The handlers `App`'s `ROUTES` name, in the file that holds their kind; each mixin is included in `App` and reads its helpers and ivars, so `app.send(:handle_show, …)` and the specs that stub `App` methods work as before. |
-| Web Push | `web/push.rb` (`Web::Push`: `Runtime`, `preflight!`, the `web.push.*` settings), `web/push/crypto.rb` (`Push::Crypto`: RFC 8291 aes128gcm, RFC 8292 VAPID), `web/push/store.rb` (`Push::Store`, `Store::Sub`: `web-push/vapid.pem`, `subscriptions.json`), `web/push/client.rb` (`Push::Client`, `Client::Result`), `web/push/attention.rb` (`Push::Attention`: notify.js's rules in Ruby, shared cases in `spec/fixtures/attention_cases.json`), `web/push/presence.rb` (`Push::Presence`: the pages' "in front" reports), `web/push/notifier.rb` (`Push::Notifier`, a hub subscriber with a sender thread), `web/push_routes.rb` (`Web::PushRoutes`), `web/private_files.rb` (`Web::PrivateFiles`, shared with the grants), `public/sw.js`, `public/push.js`, `public/manifest.webmanifest` | chi web pushes what the tab notifies for (approvals, questions, step-limit questions, cards, failed turns; done turns to a device that asks) to the owner's Home Screen app over an https public URL: the Notifier turns the hub's new attentions into show pushes after a hold, unless a chi web page is in front, at most 30 an hour, with one retry and a restart catch-up (`sent.json`) (each carries the keys still open, and the badge; no close push: every push shows a notification); the bell (`notifications.js`) subscribes the device, and the service worker and the page close the answered ones. See [internals/web-push.md](internals/web-push.md). |
+| Web Push | `web/push.rb` (`Web::Push`: `Runtime`, `preflight!`, the `web.push.*` settings), `web/push/crypto.rb` (`Push::Crypto`: RFC 8291 aes128gcm, RFC 8292 VAPID), `web/push/store.rb` (`Push::Store`, `Store::Sub`: `web-push/vapid.pem`, `subscriptions.json`), `web/push/client.rb` (`Push::Client`, `Client::Result`), `web/push/attention.rb` (`Push::Attention`: notify.js's rules in Ruby, shared cases in `spec/fixtures/attention_cases.json`), `web/push/presence.rb` (`Push::Presence`: the pages' "in front" reports), `web/push/notifier.rb` (`Push::Notifier`, a hub subscriber with a sender thread), `web/push_routes.rb` (`Web::PushRoutes`), `private_files.rb` (`PrivateFiles`, shared with the grants), `public/sw.js`, `public/push.js`, `public/manifest.webmanifest` | chi web pushes what the tab notifies for (approvals, questions, step-limit questions, cards, failed turns; done turns to a device that asks) to the owner's Home Screen app over an https public URL: the Notifier turns the hub's new attentions into show pushes after a hold, unless a chi web page is in front, at most 30 an hour, with one retry and a restart catch-up (`sent.json`) (each carries the keys still open, and the badge; no close push: every push shows a notification); the bell (`notifications.js`) subscribes the device, and the service worker and the page close the answered ones. See [internals/web-push.md](internals/web-push.md). |
 | chi web's updates | `web/update_check.rb` (`Web::UpdateCheck`), `web/update_ops.rb` (`Web::UpdateOps`), `web/auto_update.rb` (`Web::AutoUpdate`) | The RubyGems checker and its `update_check.json`; the install, worker-restart and chi-web-restart operations (one at a time) the owner's routes and AutoUpdate share; `update.auto: install`'s thread (install when no turn runs, then idle workers and chi web). See [configuration](configuration.md#unattended-updates-updateauto). |
 | Behind an auth proxy | `web/public_url.rb` (`Web::PublicUrl`: `web.public_url`, `web.proxy.identity_header`, `web.proxy.owner`), `web/proxy_gate.rb` (`Web::ProxyGate`, mixed into App; `RawHeaderNames`, prepended to WEBrick's request by `Web::Server`), `web/link_codes.rb` (`Web::LinkCodes`: the links' one-time codes), `proxy_trace.rb` (`ProxyTrace`), `web/public/token_fragment.js`, `web/public/auth_lost.js`, `web/tunnel.rb` + `web/tunnel/tailscale.rb` (`Web::Tunnel`, `Web::Tunnel::Tailscale`: `chi web --tunnel tailscale`, Tailscale Serve set for one run and the PublicUrl it makes) | Experimental: chi web behind an auth proxy. Every request needs the token; a proxied one's owner also needs the identity header (one clean value under one name); the `__Host-` cookie, an absolute `Location` from the public URL, https links with a one-time code in the fragment; the page's lost-sign-in banner. Bridges refuse proxy traces ([configuration.md](configuration.md#behind-an-auth-proxy)). |
-| Participants | `participants.rb` (`Participants`, the `participants.json` sidecar), `share_command.rb` (`ShareCommand`, `chi share`), `session_participants.rb`, `participants_watch.rb`, `web/grants.rb` (`Web::Grants`), `web/principal.rb` (`Web::Principal`), `web/participant_access.rb` (`Web::ParticipantAccess`: the participant's gate and routes), `web/participants_admin.rb` (`Web::ParticipantsAdmin`: the owner's invite, list, revoke, cap and Apply routes), `web/participant_review.rb` + `web/participant_view.rb` (`Web::ParticipantReview`, `Web::ParticipantView`), `web/participant_stream_filter.rb`, `guardrails/review_boundary.rb` + `guardrails/review_paths.rb` | The people or agents an owner invites to review one session through chi web: their grants and gate, what they read, their read-only review turns ([internals/participants.md](internals/participants.md), [guardrails.md](guardrails.md)). |
+| Participants | `participants.rb` (`Participants`, the `participants.json` sidecar), `share_command.rb` (`ShareCommand`, `chi share`), `session_participants.rb`, `participants_watch.rb`, `grants.rb` (`Grants`), `participant_exposure.rb` (`ParticipantExposure`), `web/principal.rb` (`Web::Principal`), `web/participant_access.rb` (`Web::ParticipantAccess`: the participant's gate and routes), `web/participants_admin.rb` (`Web::ParticipantsAdmin`: the owner's invite, list, revoke, cap and Apply routes), `web/participant_review.rb` + `web/participant_view.rb` (`Web::ParticipantReview`, `Web::ParticipantView`), `redact.rb` (`Redact`, `Redact::Viewer`: the redaction every string a participant gets passes, also the Engine's Verify quote check), `web/participant_stream_filter.rb`, `guardrails/review_boundary.rb` + `guardrails/review_paths.rb` | The people or agents an owner invites to review one session through chi web: their grants and gate, what they read, their read-only review turns ([internals/participants.md](internals/participants.md), [guardrails.md](guardrails.md)). |
 | Analytics | `analytics_file.rb` (`AnalyticsFile`), `session_metrics/totals.rb` (`SessionMetrics::Totals`), `session_metrics/model_segment.rb` (`SessionMetrics::ModelSegment`) | A session's `analytics.json` (`SessionMetrics#persist`); the sums over its turn records (`Totals`: tokens, cost, speeds, kept as running counters) and their split per model after a `/model` switch (`ModelSegment`: a run of turns on one model, the `model_segments` rows); `session_metrics/cost.rb` (`SessionMetrics::Cost`): the spend `ctx.cost` reads; `session_metrics/usage.rb` (`SessionMetrics::Usage`): the work `ctx.usage` reads. `session_metrics/side_totals.rb` (`SessionMetrics::SideTotals`) and `side_usage.rb` (`SideUsage`): the side requests' sums, apart from the turns'. |
 | Images / vision | `image_store.rb` (`ImageStore`), `vision_support.rb`, `vision_context.rb` | Stored prompt images and whether a model takes them. |
 | Toolkits | `toolkit.rb` (`Toolkit`), `toolkit_binding.rb` (`ToolkitBinding`, the Engine's seam), `toolkit_command.rb` (`/toolkit`), `tools/registry.rb` (`Registry#toolkit`, `#left_out_names`), `web/public/toolkit_chip.js` | Which registered tools a session's prompts declare: saved in the session, resolved at a turn's start (`Engine#apply_toolkit!`), named in the prompt's not-loaded line, a kit's prompt text after the appended files; `chi.toolkit` and `ctx.use_toolkit` for plugins ([configuration.md](configuration.md#toolkits)). |

data/docs/broadcast.md

@@ -24,7 +24,7 @@ selection: see [Desktop helper](desktop.md#everyone-it-concerns).
 
 The recipients are your own sessions, in every project:
 
-- a worker or a chi REPL runs them now, or their last turn ended within
+- a worker or a one-turn `chi --non-interactive` run runs them now, or their last turn ended within
   `broadcast.active_hours` (default 8). A session with no turn yet counts
   by its last save;
 - not a delegate child: its parent relays what concerns it (the
@@ -32,8 +32,8 @@ The recipients are your own sessions, in every project:
 - not a `chi scratch` session, not an archived one, and not a test run
   (unless `chi broadcast` itself runs as one, `SAMAGOTCHI_ENV=test`).
 
-A session open in a plain chi REPL (`--no-shared`) can't take notes: it is
-listed as skipped, "open in a chi REPL".
+A session a one-turn `chi -p … --non-interactive` run has can't take notes: it
+is listed as skipped, "in use by a one-turn chi --non-interactive run or an older chi's terminal".
 
 ## Tags: which sessions it concerns
 
@@ -101,7 +101,7 @@ broadcast b-7f3a1c9e  "payments API returns 500 since 14:00 (PAY-123)"
 5e1f0a77  delivered  model: yes (p 0.91)
 77aa0b3c  delivered  unchecked: triage deadline
 c0ffee12  skipped    model: no
-d00dad00  skipped    open in a chi REPL
+d00dad00  skipped    in use by a one-turn chi --non-interactive run or an older chi's terminal
 delivered 4 · skipped 2 · 1 unchecked: triage deadline
 ```
 
@@ -193,7 +193,7 @@ any shell command that runs it, once at a time, and only you may allow it
 
 | Setting | Default | What it does |
 |---|---|---|
-| `broadcast.active_hours` | `8` | A session with no worker or REPL counts when its last turn ended within this many hours. |
+| `broadcast.active_hours` | `8` | A session with no worker or one-turn run counts when its last turn ended within this many hours. |
 | `broadcast.ticket_pattern` | `\b[A-Z][A-Z0-9]+-\d+\b` | A Ruby regex for ticket ids; an invalid one warns and the default is used. |
 | `broadcast.triage_model` | recap's, else `default.model` | The triage model, a model ref (`box:qwen3.5-9b`). |
 | `broadcast.triage_host_ref` | none | A `hosts:` name for it. |

data/docs/bundle-authoring.md

@@ -119,7 +119,7 @@ end
 `questions` record effects; `bundle.answer` / `model_answers` provide `ask_user` / `ask_model` answers.
 `bundle.judgments` answers `ctx.judge` and records its asks and runs (each judgment is on in the kit, off in chi until the user sets it);
 `bundle.http.stub` stubs `ctx.http`; `bundle.question_asked(text, question:)` fires `:question_asked` and returns
-the refs; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
+the refs; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup. The kit's `ctx.declared_tools` is every tool, as on `full`; in chi a `chi.tool` is declared only on `full` and by a kit's `add:`, and on `lean` or `child` the model reaches it with `find_tools` (`chi/<name>`) and `call_tool` ([Toolkits](configuration.md#toolkits)), so `bundle.set(declared_tools: %w[read])` tests that case and the tool's description should be easy to search.
 The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
 experimental (it may change before chi 1.0). A failing matcher that meets `ENV` prints `#<the process ENV, contents not shown>`, not your keys. If a test needs a fake of chi's own (a stub of a `Samagotchi::`
 class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.