samagotchi 0.5.1 → 0.7.0

data/docs/architecture.md

@@ -110,7 +110,7 @@ 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}` → retention & ordering (`Session.prune`, `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,delete,prune,clean}` (`SessionsCommand`; not the REPL's `SessionCommands`) → retention & ordering (`Session.prune`, `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.
 
 ## Session retention & ordering
@@ -275,6 +275,13 @@ its model turns keep their `tool_calls` and tool results their `tool_call_id`,
 so later requests and resumed sessions pair them. It has its own system prompt
 (no raw-prompt tool declarations; the tools go as JSON schemas).
 
+`Engine#build_stream_event_handler` is the one seam both loops' streams pass
+through: with a `:generation_progress` hook registered it feeds a
+`Hooks::StreamWatch` each chunk's thinking and text after the UIs had it. A
+hook's `stop_generation` cancels the generation's own controller (a child of
+the turn's, `CancellationController#generation`), and each loop takes the cut
+as an empty answer and asks again.
+
 **Adapters.** `Client` (raw-prompt servers) and `LLM::OpenAIChat` (one per host,
 `HostRegistry#adapter_for`) share `LLM::HTTP`: timeouts, TLS for https, a line
 reader for streamed bodies, the retry loop (`retry.*`; network errors, 429 and

data/docs/cli.md

@@ -14,12 +14,12 @@
 - `chi web [--port 4567] [--open] [--scope=all]` — start the Web UI (single localhost port session control plane) on this git project's sessions (`--scope=all`, or a folder in no repo: every session); if a chi web already runs on the port, print (with `--open`, open) its page for this folder and exit. Something else on the port (an older chi web too) exits 1 with "port N is in use"
 - `chi web --web-host lan` — the Web UI on your home network too, for your phone: a link with an access token and its QR code (see [chi web on your phone](#chi-web-on-your-phone)); `chi web --new-token` replaces the token
 - `chi web --web-markdown` — opt in to sanitized Markdown rendering for completed assistant messages
-- `chi web --web-view stage|chat` — draw turns with the stage view (the running turn pinned above the composer) or as the classic row of bubbles instead of the default turn view (each turn as one block of steps, the running one at the bottom); `?view=turn|stage|chat` on the page URL overrides it (see [Web views](#web-views))
+- `chi web --web-view turn` — draw turns with the turn view (each turn as one block of steps, the running one at the bottom of the history) instead of the default stage view (the running turn pinned above the composer); `?view=stage|turn` on the page URL overrides it (see [Web views](#web-views))
 - `chi sessions list|stop|archive|unarchive|delete|prune|clean` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md))
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
 - `chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; see [Starting a session](sessions.md#starting-a-session))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text to live sessions as context notes (see [Desktop helper](desktop.md))
-- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles
+- `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles; `chi self --model` prints only the model a new session starts on (the desktop helper's hint)
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs (see [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle))
 
@@ -420,26 +420,25 @@ its code; a prompt copies the text as you typed it.
 
 ### Web views
 
-`web.view` picks how the page draws a turn: `turn` (the default, below),
-`stage` (the running turn pinned above the composer, below) or `chat` (the
-classic row of bubbles: one thinking block, one activity panel and one
-answer bubble per generation).
+`web.view` picks how the page draws a turn: `stage` (the default: the
+running turn pinned above the composer, below) or `turn` (each turn as one
+block of steps in the history, the running one at the bottom, below).
 
 ```sh
-chi web --web-view stage     # or chat; turn is the default
+chi web --web-view turn      # stage is the default
 ```
 
-The setting also supports `SAMAGOTCHI_WEB_VIEW=stage` or the global config:
+The setting also supports `SAMAGOTCHI_WEB_VIEW=turn` or the global config:
 
 ```yaml
 web:
-  view: stage
+  view: turn
 ```
 
-`?view=turn`, `?view=stage` or `?view=chat` on the page URL picks the view
-for that page load, whatever the config says; the parameter is dropped
-when you switch between the project and all-sessions views. The terminal
-UIs are not affected.
+`?view=stage` or `?view=turn` on the page URL picks the view for that page
+load, whatever the config says; the parameter is dropped when you switch
+between the project and all-sessions views. The terminal UIs are not
+affected.
 
 **The stage view** pins the running turn above the composer, in its own
 card, so it stays on screen without scrolling: a status row (what it is

data/docs/configuration.md

@@ -538,6 +538,9 @@ unless `sampling:` sets one; the REPL prints `↻ empty answer, asking again (1/
 the step. `retry.empty_answer` (default `1`, at most `3`, env `SAMAGOTCHI_RETRY_EMPTY_ANSWER`, no CLI flag) is how
 many times per turn; `0` ends the turn at the empty answer as before. An answer cut because the context is full
 (90 % or more) is not retried. When the retries run out the turn ends with "(the model returned an empty answer)".
+A generation a plugin cuts while it streams (loop-guard's thinking watch, or any `stop_generation`,
+[hooks.md](hooks.md#watching-the-stream)) uses the same budget: `↻ cut by loop-guard, asking again (1/1)`, and with
+none left the turn ends as cancelled (hook).
 
 Assist-mode UX:
 
@@ -684,6 +687,23 @@ hosts:
 `models:` wins over `hosts:`. On a native host, `vision: true` skips only the
 modalities check: without a media marker the prompt can't carry an image.
 
+## Desktop helper: agents in kitty
+
+The desktop helper (`chi desktop`) can also paste into agent CLIs (claude,
+codex, …) running in [kitty](https://sw.kovidgoyal.net/kitty/) windows. It
+lists them only with `kitty.listen_on` set: copy the value of `listen_on` from
+your `kitty.conf` as it is (kitty must also have `allow_remote_control` on).
+
+```yaml
+kitty:
+  listen_on: unix:/tmp/kitty.${KITTY_PID}   # as in kitty.conf; unset = no kitty targets
+  binary: /Applications/kitty.app/Contents/MacOS/kitty   # the default
+  agents: [claude, codex]   # the programs listed; "*" = every window
+```
+
+The helper reads these from its launch file: after editing them run
+`chi desktop upgrade` (or `chi update`). See [Desktop helper](desktop.md#agents-in-kitty).
+
 ## Project specific description
 
 If an AGENT.md file is present in the project root, samagotchi injects its
@@ -753,6 +773,9 @@ described in their own sections.
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
 | `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |
 | `update.desktop` | `true` | | `false`: `chi update` leaves the desktop helper alone (`--no-desktop`). |
+| `kitty.listen_on` | none | | The desktop helper's kitty socket, copied from `kitty.conf`; unset = no kitty targets. See "Desktop helper: agents in kitty". |
+| `kitty.binary` | `/Applications/kitty.app/Contents/MacOS/kitty` | | The kitty the helper runs `kitty @` with. |
+| `kitty.agents` | `claude\|codex\|gemini\|aider\|opencode\|cursor-agent\|amp\|goose` | | Foreground programs whose kitty windows the helper lists, `\|`-separated (a YAML list works too); `*` lists every window. |
 | `read.truncate_at_bytes` | `65536` | yes | A `read` result larger than this is cut to a preview. |
 | `read.preview_bytes` | `12288` | yes | Size of that preview. |
 | `read.hard_max_bytes` | `2097152` | yes | Largest file `read` opens. |
@@ -763,7 +786,7 @@ described in their own sections.
 | `web.port` | `4567` | `--port` | `chi web`'s port. See [CLI](cli.md). |
 | `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token (`chi web --new-token` replaces it). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |
-| `web.view` | `turn` | yes | How `chi web` draws a turn: `turn` (one block per turn), `stage` (the running turn pinned above the composer) or `chat` (the row of bubbles). See [CLI](cli.md#web-views). |
+| `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). |
 | `history.file` | state dir | | Prompt history path. |
 | `no_interrupt` | `false` | `--no-interrupt` | Raise the tool-call limit of a turn to 1000; a top-level key. |

data/docs/desktop.md

@@ -20,6 +20,8 @@ sessions. Keys:
 - **⏎** sends a message: `chi send -m <the line>` with the text as quoted context above it. With the line empty,
   the text is the message.
 - **⌘⏎** sends a note: `chi note`, the line (if any) then the text.
+- **⌥⏎** pastes into an agent in a kitty window without pressing Enter (see [Agents in kitty](#agents-in-kitty));
+  it is not a newline.
 - **⇧⏎** is a newline, in either field. Esc closes.
 
 The list shows the sessions a worker runs now, then, under a "recent" divider, up to 3 stopped ones (dimmed, with
@@ -32,7 +34,9 @@ The first row, **New session in <folder>** (⌘0), starts a session with the mes
 <folder>`, so it shows in `chi web` at once (see [Starting a session](sessions.md#starting-a-session)). The folder is
 that of the most recently updated live session, else of the newest recent one, else your home folder. It is ticked
 alone (ticking it clears the sessions and the reverse) and is preselected when no session is live. ⌘⏎ on it beeps: a
-note needs a session. After the send the panel shows `started <id>…` for 3 s.
+note needs a session. After the send the panel shows `started <id>…` for 3 s. On its right, in grey, the row names
+the model the new session starts on (`chi self --model`: `default.model` from config.yml, or its env override); it
+is left out when none is configured.
 
 A session open in a `chi --no-shared` REPL isn't listed: it takes no notes or messages.
 
@@ -62,6 +66,53 @@ thumbnails sit under the message line, 48 px high, the file name as a tooltip; h
   the panel closes; files from Finder are sent as they are, never touched. A send with images may take up to 30 s
   (converting, a worker starting) before the panel gives up.
 
+## Agents in kitty
+
+The panel can also send to agent CLIs (claude, codex, gemini, aider, …) running in
+[kitty](https://sw.kovidgoyal.net/kitty/) windows, next to chi sessions. kitty only, through its remote control;
+off until you set it up:
+
+1. In `kitty.conf`, remote control on and a socket: `allow_remote_control yes` and a `listen_on unix:…` line.
+2. Copy that `listen_on` value as it is into chi's config.yml:
+
+   ```yaml
+   kitty:
+     listen_on: unix:/tmp/kitty.${KITTY_PID}
+   ```
+
+   `kitty.agents` picks the programs listed (default `claude|codex|gemini|aider|opencode|cursor-agent|amp|goose`, a
+   YAML list works too; `"*"` lists every window, shells too), `kitty.binary` the kitty to run (default
+   `/Applications/kitty.app/Contents/MacOS/kitty`). See [Configuration](configuration.md#desktop-helper-agents-in-kitty).
+3. Run `chi desktop upgrade` (or `chi update`): the helper reads these from its launch file, so **after every edit of
+   `kitty:`** run it again. No rebuild when only the settings changed.
+
+The helper finds the sockets itself: kitty adds `-<pid>` to a `listen_on` path from kitty.conf (and fills in
+`{kitty_pid}`), `~` and variables the helper knows are expanded, others (`${KITTY_PID}`) stay as written, as kitty
+keeps them. Several kitty instances all count. Only `unix:` sockets work.
+
+The panel lists the windows whose foreground program is one of the agents under a **kitty** divider, between live
+and recent sessions: "claude · <its title>", the folder below, a terminal icon, and a ⌘ number like the sessions.
+With the settings on but no agent running, one dim line says "no agents in kitty". A window counts when a foreground
+process's program is an agent, also as the script of `node …/codex` (that match is untested for codex and gemini).
+
+- **⏎** pastes into every chosen window and presses Enter: the text as a `> ` quote, a blank line, your message, then
+  one image path per line. Chosen together with chi sessions, each gets the message and the panel shows one line
+  ("Sent. · sent to claude · samagotchi").
+- **⌥⏎** only pastes (no Enter), and only when every chosen target is a kitty window: build up several screenshots,
+  each with its own line, then press Enter in kitty. The footer shows **Paste ⌥⏎** instead of Note then.
+- **⌘⏎** with a kitty window chosen beeps: "Notes are for chi sessions". ⌥⏎ with a chi session: "Paste only is
+  for kitty windows".
+- **Images:** a screenshot or other image data is copied to `$TMPDIR/chi-helper-sent/<uuid>.png` (or `.tiff`) and
+  its path pasted; the agent reads it from there (claude attaches it as `[Image #1]`). These files are deleted a week
+  later, at the helper's next start. Finder files are pasted with their own path, `'…'`-quoted when they hold spaces.
+- The paste arrives as one bracketed paste, so the agent takes newlines as text (claude shows long ones as
+  `[Pasted text]`). With `agents: "*"` beware of a program that doesn't turn bracketed paste on: the newlines would
+  act as Enter.
+- No delivery confirmation: before pasting, the helper checks the window is still there ("window closed" if not);
+  it can't know whether the agent read it. The 16 KB cap is chi's; a kitty window takes more.
+- Focus goes back to the app you came from, as for sessions. The last choice (kitty windows too) is preselected
+  while listed; ⌘ numbers shift as windows come and go.
+
 ## Install
 
 ```sh

data/docs/hooks.md

@@ -52,14 +52,15 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), messages: [...] (the history before this turn) }` |
 | `:after_turn` | After a turn completed or was cancelled (not after one that failed) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
 | `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
-| `:after_generation` | After LLM returns (both loops) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
+| `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
+| `:generation_progress` | While the response streams, in batches (see [Watching the stream](#watching-the-stream)) | `{ type: :generation_progress, iteration: N, thinking: "..." (new since the last fire), text: "..." (new visible text), thinking_chars: N, text_chars: N (this generation so far), elapsed_ms: N }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
 | `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." }` |
 | `:session_end` | After every turn (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
 
 Every event also carries the hook runtime (next section): `hook:` (the label
 of the hook about to run) and the callables `notify:`, `ask_user:`,
-`stop_turn:`, `steer:`.
+`stop_turn:`, `steer:`, `stop_generation:`.
 
 `messages:` is a **read-only copy**: a frozen array of copied message hashes
 (`{role:, content:, …}`). A hook that mutates it, or its strings, gets
@@ -69,8 +70,9 @@ cheap).
 ## What a hook can do: the runtime
 
 Besides reading (and, on `:before_tool_call`, voting on) its event, a hook
-can talk to the user, and to the running turn, through four callables the
-registry puts on every event:
+can talk to the user, and to the running turn, through the callables the
+registry puts on every event (`stop_generation`, the fifth, is in
+[Watching the stream](#watching-the-stream)):
 
 ```ruby
 class Watchful
@@ -114,12 +116,75 @@ known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 A steer is saved in the session as `{role: "user", kind: "steer", source:
 "<bundle>", content: "…"}`; the model reads only its text, as a user turn.
 Its `source` is the hook's bundle (a config or turn hook's label otherwise).
+The user's own lines typed into a running turn are saved as `{role: "user",
+kind: "input", content: "…"}`: part of that turn, not a turn of their own.
 
 Timing: a notice from `:after_turn` or `:session_end` shows after the turn's
 end line. A question from `:before_tool_call` shows **before** the tool
 line (the gate runs first), so its text should name the call. The notices
 are also logged (`turn` tag, `hook_notice`).
 
+## Watching the stream
+
+`:generation_progress` sees a model response **while it streams**: the
+thinking and the visible text, on both the raw-prompt path (llama.cpp
+`/completion`, `/v1/completions`) and the chat path (`api: openai`). It fires
+for the turn's own generations only (not a plugin's `ctx.ask_model`, not a
+recap).
+
+When it fires: once 2000 new chars (thinking + text) are pending, or once a
+second has passed since the last fire with anything pending. It is checked
+as each chunk arrives (there is no timer), so a silent stream fires nothing.
+There is no fire at the end of a generation (`:after_generation` sees the
+whole response), and none after the turn or the generation was cancelled.
+A 240k-char thinking gives about 120 fires.
+
+`thinking` holds what the model streamed as thinking: `reasoning_content`
+on the chat path, a Qwen `<think>` block on the raw-prompt path. Some
+thinking arrives as `text` instead: Gemma 4's on the raw-prompt path (it has
+no close marker), and a chat provider's that puts `<think>` inside the
+answer's content. Tool-call bodies are left out of `text`. With streaming off
+(`stream: false` on a chat host) there are no chunks, so no fires.
+
+**Keep it fast.** The hook runs on the turn's thread, inside the HTTP read:
+while it runs, tokens wait in the socket (nothing is lost). A hook over
+100 ms logs `stream_hook_slow` (warn, with its label and the ms) once per
+turn. Don't ask questions or call the model from it: `event[:ask_user]`
+returns nil at once here, and `ctx.ask_model` would hold the stream for its
+whole answer. A hook that never returns hangs the turn, as any hook does. A
+plugin's block that raises is logged (`plugin_hook_failed`) at most once a
+minute.
+
+Two ways to act:
+
+- `event[:stop_turn].call(reason)`: as anywhere, a warn notice and the turn
+  ends cancelled (hook). The socket closes at once.
+- `event[:stop_generation].call(reason)`: cut **this generation** only. The
+  turn goes on: the model is asked again with a hidden note ("your last
+  reply was cut off by <bundle>: <reason>. Don't start the same reasoning
+  again; …") at the retry temperature, and the UIs print `↻ cut by
+  <bundle>, asking again (1/1)`. True when a streaming generation was cut
+  now; false with none streaming, once it was cut, after a cancel, and from
+  `:after_turn` / `:session_end`.
+
+What a cut is, in detail:
+
+- It is an empty answer made early: it uses the `retry.empty_answer` budget
+  ([configuration.md](configuration.md#llama-network-retry-behavior)). With
+  no retry left (`retry.empty_answer: 0`, or already used), the turn ends
+  cancelled (hook): "✕ turn canceled (hook)".
+- It shows nothing by itself: post your own notice (`event[:notify]`) to say
+  why. The bundle and the reason go into the note the model reads and the
+  log (`generation_stopped`).
+- Queued input (the user's line, or a hook's `steer`) goes in place of the
+  hidden note, as for an empty answer; then there is no `↻` line.
+- The cut generation is not kept: its thinking and any visible text it had
+  streamed go with it (the retry answers anew). `:after_generation` doesn't
+  fire for it, and its token usage is lost (the stream never sent its last
+  chunk). A client that joins the running turn still sees its thinking in
+  the turn so far until the turn ends.
+- A Stop from the user right after a cut is a plain cancel.
+
 ## Presenting the answer (display only)
 
 `:after_turn` carries one more callable, `present:`. It changes how the

data/docs/plugins.md

@@ -311,6 +311,34 @@ This is a bundle hook, the same as a `hooks/*.rb` file. See
 `plugin.rb (bundle my-bundle)`. The block may take only the event. If it
 raises, the error is logged and the hook is skipped.
 
+#### Watching the stream
+
+`chi.on(:generation_progress)` sees a response while it streams, in batches
+(2000 chars or a second), and `event[:stop_generation]` (or
+`ctx.stop_generation`) cuts it while the turn goes on: the model is asked
+again. The rules (the thread it runs on, keeping it fast, what a cut does)
+are in [hooks.md](hooks.md#watching-the-stream).
+
+```ruby
+class Plugin
+  LIMIT = 50_000
+
+  def register(chi)
+    chi.on(:generation_progress) do |event, ctx|
+      next if event[:thinking_chars] < LIMIT
+
+      # Once per generation: a cut generation fires no more.
+      if event[:stop_generation].call("it thought for over #{LIMIT / 1000}k chars")
+        ctx.notify("thinking too long (#{event[:elapsed_ms] / 1000} s): cut", level: :warn)
+      end
+    end
+  end
+end
+```
+
+loop-guard's thinking watch is built on this ([The loop-guard
+bundle](#the-loop-guard-bundle)).
+
 ### `chi.service(name, eager: false) { |svc| … }`
 
 A long-lived thing the plugin keeps for the session: a server process, a
@@ -439,6 +467,7 @@ session's life, and each read gives the session as it is now.
 | `ctx.cancelled?` | whether the running turn was cancelled (a long tool should stop) |
 | `ctx.steer(text)` | put text into the running turn, like a hook's `event[:steer]`: its own user message at the loop's next boundary, shown as `my-bundle> nudged: …`. Returns true when queued, false with no turn running (it never starts one; that is `ctx.sessions`' send). Dropped (logged) if the model answers or the turn ends first. Safe from any thread: an anytime command, a hook, your own |
 | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason, like a hook's `event[:stop_turn]`; true when it stopped one now |
+| `ctx.stop_generation(reason)` | cut the generation that is streaming, like a hook's `event[:stop_generation]`: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
 | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
 | `ctx.sessions` | fork, send to and read other sessions: see [Other sessions](#other-sessions-ctxsessions) |
 
@@ -706,7 +735,9 @@ bundles:
 
 `chi bundle install loop-guard` installs the bundle shipped with chi. It is
 written only against this API (`lib/samagotchi/bundles/loop-guard/plugin.rb`),
-with `chi.on` hooks, and has no memory file.
+with `chi.on` hooks, and has no memory file. It guards two kinds of loop:
+repeated tool calls (below) and [thinking that repeats
+itself](#thinking-that-repeats-itself).
 
 A local model can run the same tool call again and again in one turn: each
 step's thinking starts over, so it never notices it already tried. (A real
@@ -749,12 +780,76 @@ bundles:
 Its hooks run at the default priority (100), after known-names (50), so in
 known-names' `correct` mode loop-guard keys the corrected call.
 
+### Thinking that repeats itself
+
+A model can also go in circles inside one generation: its thinking says the
+same few sentences again and again ("Wait, let me check once more…") for
+minutes, until the provider's output cap ends it with no answer. loop-guard
+watches the thinking while it streams ([Watching the
+stream](hooks.md#watching-the-stream)) and cuts it:
+
+- The thinking is cut into sentences; short ones (under `min_words`) are
+  skipped. Two sentences count as the same when their words and word pairs
+  mostly match (`similarity`), so a reworded round ("Hmm, …", a synonym, a
+  swapped clause) still counts.
+- A loop is a cycle of 1 to `max_period` sentences seen `repeats` times in a
+  row, over at least `min_span_sentences` sentences and `min_span_chars`
+  chars; or one sentence `max_same` times anywhere in the generation. One
+  sentence over and over must be near-identical (`similarity` + 0.4), and a
+  longer cycle must hold different sentences: a list of templated sentences
+  ("Now I need to open the file <path> and …" for 14 paths) is no loop.
+- Nothing triggers before `min_chars` of thinking. The watch sees a loop
+  within one batch (2000 chars, or a second) of its third cycle.
+
+What happens (`action: retry`, the default):
+
+1. The first loop in a turn: the generation is cut and the model asked
+   again, with a hidden note that it was cut off. The user sees
+   `loop-guard> thinking repeats itself (3 sentences ×3, 4k chars, 8 s): cut`
+   and `↻ cut by loop-guard, asking again (1/1)`.
+2. If the retry loops too, the turn is stopped ("stopped the turn: …", "✕
+   turn canceled (hook)") with a card that quotes the repeated sentences.
+
+The cut uses the `retry.empty_answer` budget: with `retry.empty_answer: 0`
+the first loop ends the turn as cancelled (hook), with the notice and no
+card. `action: stop` stops the turn at the first loop; `action: notify` only
+warns, once per generation.
+
+```yaml
+bundles:
+  loop-guard:
+    thinking:
+      watch: true             # false: the tool-call guard only
+      action: retry           # retry (cut, ask again; then stop) | stop | notify
+      min_chars: 2000         # thinking this long before anything triggers
+      repeats: 3              # a cycle seen this many times is a loop
+      max_period: 6           # cycles of up to this many sentences
+      similarity: 0.5         # 0..1, how alike two sentences must be to count as the same
+      min_span_sentences: 6   # a loop spans at least this many sentences…
+      min_span_chars: 600     # …and this many chars
+      max_same: 8             # one sentence this many times in one generation is a loop
+      min_words: 5            # shorter sentences are ignored
+```
+
+Not watched:
+
+- thinking that arrives as answer text: Gemma 4 on the raw-prompt path (no
+  close marker), a chat provider that puts `<think>` in the content;
+- a chat host with streaming off (no chunks);
+- loops in the visible answer;
+- a runaway without sentences, such as an endless comma list of numbers: it
+  ends at the output cap as an empty answer, which `retry.empty_answer`
+  retries after the fact.
+
+A real small model's circular re-checking that repeats one sentence 8 times
+is cut even if it would have found an answer later; `max_same` sets how
+patient that is.
+
 Not caught (yet):
 
 - near-duplicates, such as `find . -name 'config*'` after `'config.yml'`;
 - loops across turns;
-- alternating calls (A, B, A, B) that each return something new;
-- thinking that goes in circles inside one long generation.
+- alternating calls (A, B, A, B) that each return something new.
 
 ## The check-in bundle
 

data/docs/sessions.md

@@ -50,7 +50,7 @@ chi sessions clean --dry-run                     # every test session, whatever
 chi sessions clean --dry-run --days 7            # test sessions older than 7 days
 ```
 
-`--dry-run` is the safe preview. Web has no prune endpoint; use the CLI.
+`--dry-run` is the safe preview. `--keep N` keeps the N newest sessions that stay: one that goes anyway (a leftover scratch session, one left empty, one older than `--days`) takes no place in the count. Web has no prune endpoint; use the CLI.
 
 `chi sessions list` shows each session's saved recap, its first sentence without the "The user was…" opening (as on the web cards), in place of its last prompt, cut to 60 characters; a session with no recap shows its last prompt. A delegated session's row ends with `↳ <parent's short id>` (plain and `--live`; `--format json` has `parent_id`); rows keep their `updated_at` order, so a parent may be on another page than its children. After the status, `ctx 12%` says how full the context was after the session's last counted turn (from its `analytics.json`; blank when no turn had a server count or the window is unknown; `ctx_pct` in `--format json`). The web's session cards show it quietly too (`12%`), and a session's ctx meter shows it on load, before its next turn streams.
 
@@ -175,8 +175,8 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 
 The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; nothing checks the host serves it, so an unknown one fails the child's first turn). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail like an `execute` result. Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (a `↳` chip on its card, `delegated by` in its info bar, listed right after its parent in the all-sessions view) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
 
-- `delegate(task, model:, session:, wait:, timeout:)`: starts a child and, by default, waits for its reply (`wait: false` returns at once, so several children can run side by side; `timeout`, default 600 s, leaves a slow child running). With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one.
-- `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child. The reply comes back once; a later call waits for the next one.
+- `delegate(task, model:, session:, wait:, timeout:)`: starts a child and, by default, waits for its reply (`wait: false` returns at once, so several children can run side by side; `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting). With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one.
+- `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one.
 - What a wait returns, `session: <id>` then `status:` and the text: `done` with the reply after a `---` line; `waiting_for_answer` as soon as the child opens a question or a guardrail approval (nothing is answered for it: attach or use the web, then wait again); `canceled` when the parent's own turn is canceled (the child keeps running; the next turn can wait again); `no_reply` when the child's turn ended with nothing to say (canceled, failed or empty: its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `running` on timeout. A reply saved before the child's worker idle-exited is returned at once.
 - Every child starts with the shipped `delegated` system memory preloaded (`preloaded_memory_names: ["system/delegated"]`; `--mute delegated` would hide it): put everything in the final reply, don't delegate further, don't write memories or change config, stay in the folder. Its system prompt also says `Delegated by session <parent id>`. The parent's own `--mute` list does not carry over.
 - Limits: a child cannot `delegate` (depth 1; the tool refuses), and one session may have at most `session.max_children` (default `4`, env `SAMAGOTCHI_SESSION_MAX_CHILDREN`) children running at a time, counted from the session files (a finished or idle-exited child does not count; one whose worker is still starting does, for 15 s). A refused call creates no session. Nothing stops children with the parent: `chi sessions stop ID` does.

data/lib/samagotchi/bridge/card_store.rb

@@ -2,14 +2,18 @@
 
 module Samagotchi
   class Bridge
-    # The last cards (Engine#show_card) and hook notices (:hook_notice),
-    # for a UI that joins later: the Bridge's snapshot[:cards]. A
-    # persistent observer, like TurnAccumulator.
+    # The last cards (Engine#show_card), hook notices (:hook_notice) and
+    # load warnings (:guardrail_warning), for a UI that joins later: the
+    # Bridge's snapshot[:cards]. A persistent observer, like TurnAccumulator.
     #
     # A turn's own notice (no between_turns) is in_turn like a turn's card,
     # with the step it came in: +iteration+ and +calls+, the calls of that
     # iteration started before it (a before_tool_call hook's notice comes
-    # before its call's row, so the web puts it above row calls + 1).
+    # before its call's row, so the web puts it above row calls + 1). The
+    # loop's "asking again" row (:empty_answer_retry, after an empty or cut
+    # answer) is kept the same way, and so is a question the turn asked
+    # (:question_requested), with how it was answered or cancelled, so a
+    # reload draws the resolved card where it was.
     #
     # A card with an earlier card's id replaces it where it was. Each entry
     # says where it belongs as the recap does: +turns_since+, the turns
@@ -81,6 +85,15 @@ module Samagotchi
           settle_during(after_turn: true)
         when :card then add_card(event)
         when :hook_notice then add_notice(event)
+        # What failed to load (guardrails, plugins): before the first turn
+        # this worker runs, where it showed live.
+        when :guardrail_warning then push({ type: :guardrail_warning, message: event[:message], label: event[:label] }
+                                            .compact.merge(in_turn: false, turns: @turns_done))
+        when :empty_answer_retry then add_turn_row(event.slice(:type, :attempt, :of, :stopped_by)) if @running
+        when :question_requested
+          add_turn_row({ type: :question, pending_question: Marshal.load(Marshal.dump(event[:pending_question])) }) if @running
+        when :question_answered then resolve_question(event[:id], answer: event[:answer])
+        when :question_cancelled then resolve_question(event[:id], cancelled: true, reason: event[:reason])
         end
       end
 
@@ -113,10 +126,22 @@ module Samagotchi
         if event[:between_turns] || !@running
           push(notice.merge(in_turn: false, turns: @turns_done))
         else
-          push(notice.merge(in_turn: true, turns: @turns_done, iteration: @iteration, calls: @calls).compact)
+          add_turn_row(notice)
         end
       end
 
+      # A row of the running turn's current step.
+      def add_turn_row(row)
+        push(row.merge(in_turn: true, turns: @turns_done, iteration: @iteration, calls: @calls).compact)
+      end
+
+      def resolve_question(id, **outcome)
+        entry = @entries.reverse_each.find do |e|
+          e[:type] == :question && e.dig(:pending_question, :id).to_s == id.to_s
+        end
+        entry&.merge!(Marshal.load(Marshal.dump(outcome.compact)))
+      end
+
       def push(entry)
         @entries << entry
         @entries.shift while @entries.size > @capacity

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -2,6 +2,7 @@
 
 require_relative "../kernel_loop"
 require_relative "../steer"
+require_relative "turn_notice"
 
 module Samagotchi
   class Bridge
@@ -33,8 +34,11 @@ module Samagotchi
       end
 
       # @return [Hash, nil] a copy of the turn in progress: prompt, origin,
-      #   continue, ordered parts (thinking / text / tool / input / steer / reminder / hook_notice),
-      #   pending_question and the last event_seq folded in
+      #   continue, ordered parts (thinking / text / tool / input / steer /
+      #   reminder / notice), pending_question and the last event_seq folded
+      #   in. A notice part holds the event of one of the turn's rows
+      #   (TurnNotice: a hook's notice, an empty-answer retry, a question and
+      #   its answer), which a UI replays through its live handler.
       def current_turn
         @mutex.synchronize { @turn && Marshal.load(Marshal.dump(@turn)) }
       end
@@ -173,13 +177,12 @@ module Samagotchi
           end
         when :reminder_injected
           parts << { kind: "reminder", reminders: Array(event[:reminders]).map(&:dup) }
-        when :hook_notice
-          parts << { kind: "hook_notice", hook: event[:hook].to_s, text: event[:text].to_s, level: event[:level].to_s }
         when :question_requested
           @turn[:pending_question] = event[:pending_question]&.dup
         when :question_answered, :question_cancelled
           @turn[:pending_question] = nil
         end
+        parts << { kind: "notice", event: TurnNotice.slice(event) } if TurnNotice.notice?(event)
       end
 
       def append_text(iteration, kind, text)

data/lib/samagotchi/bridge/turn_notice.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Bridge
+    # The events a running turn shows as rows of its own (not text, thinking
+    # or a tool call): a hook's notice, the loop asking again after an empty
+    # or cut answer, a question and how it was answered. A UI that joins the
+    # turn mid-way (TurnAccumulator's "notice" part) and one that reloads a
+    # finished turn (CardStore) get the event back with the fields listed
+    # here, and draw it with the handler that drew it live, where it was.
+    module TurnNotice
+      FIELDS = {
+        hook_notice: %i[hook text level],
+        empty_answer_retry: %i[iteration attempt of stopped_by],
+        question_requested: %i[pending_question],
+        question_answered: %i[id answer],
+        question_cancelled: %i[id reason]
+      }.freeze
+
+      module_function
+
+      # @return [Boolean] whether +event+ is one of a turn's rows
+      def notice?(event)
+        FIELDS.key?(event[:type])
+      end
+
+      # The event as a UI replays it: its type (a String, as JSON has it)
+      # and the fields it had, deep-copied.
+      # @return [Hash]
+      def slice(event)
+        fields = event.slice(*FIELDS.fetch(event[:type]))
+        copy = Marshal.load(Marshal.dump(fields))
+        { type: event[:type].to_s, **copy }
+      end
+    end
+  end
+end