samagotchi 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d6348260d3f666ffbfc0b8c3f10a51a2c64c3a30ce9cbd5a5c1280fa0325306
-  data.tar.gz: 0cad64155e27a000a49c82e89778d69804fc609526418c1e03846a32d2fb864c
+  metadata.gz: 6abdccc8a805a545ad1e27898b3caf43516d16ef1b7832444bac7b6e0a4b5e63
+  data.tar.gz: 8c0e0f354030f8ad954afdfd9dff96ef54d0b1fdd79d8df190cf494a8a32b18d
 SHA512:
-  metadata.gz: b9a1f022f8a225c517e3160d0d512fbb5a97750c32a6df7769bbcb91ddff5534c5b12f540c4ef80871d8e4f2f80d460c71cd56107476435a69d54cef0ef78395
-  data.tar.gz: 419a527ffca2330de67b42544f619db872c06388ded821d3bc5e7f17f07a488a7adf96ce56d55032a53c4bc21e6076d32af398c0b8aff15c48e651e6596e7873
+  metadata.gz: 36530955a235e3d73adaa4496545c12f6abea21daf1ff0a40eaba9477c22e1e7007dced1a500912878164c0a9f1a9ec76b45d4d8a34709473d8c496b1d53ce69
+  data.tar.gz: 125d6ab7dd048082ff6296d663803da9d6a8073c7ead520f2264ec4cc27c28d29bdb772addd47f2be39b9aa497308ef09236bd5e3e1bc43854341970fc8e6a6e

data/CHANGELOG.md

@@ -8,6 +8,58 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-04
+
+### Added
+
+- The web shows an `execute` command as the steps a person reads: `cd X &&` becomes an "in X" tag, `| head -20` a
+  chip, `echo "=== x ==="` a label, a heredoc a collapsed "EOF · N lines" chip; the collapsed row's title is the
+  first step `+N`. A `raw` toggle shows the whole command; anything the parser can't read shows as before.
+- `execute` takes an optional `description` ("what the command does, in a few words"), written by the model; it
+  becomes the tool row's title in the web and replaces the cut command in the terminal's tool line. Turn it off
+  with `execute.description: false`.
+- Every generation logs its prompt-cache counts (`prompt=`, `cached=`, `cache_write=`), and `/stats` shows cache
+  writes next to cached tokens.
+- A generation cut mid-thinking (loop-guard, a plugin's stop, a steer) or ended at the provider's output cap keeps
+  the last 20k chars of its thinking in the session's folder, `thinking_tails.jsonl`, so an archived session holds
+  the loop it was archived for. The model never sees it.
+- Turn records count `cuts` (generations a plugin cut) and `capped` (generations that hit the output cap), and
+  `/stats` shows them as "thinking cuts" and "output cap hits": `retries` counts network retries only.
+
+### Changed
+
+- On macOS, `execute`, `task_create` and `!cmd` run commands in `/bin/zsh` emulating sh (with bash's `{1..3}`,
+  `[[ =~ ]]` groups and echo escapes kept) instead of `/bin/sh`, which is bash 3.2 there and failed on an apostrophe
+  in a heredoc inside `"$( )"`: `git commit -m "$(cat <<'EOF' … it's … EOF )"` now works. Linux keeps
+  `/bin/sh`; see [background tasks](docs/internals/background-tasks.md).
+- loop-guard's cut notice (bundle 0.3.3) quotes the looping sentence: `thinking repeats itself ("Let me write the
+  tool call.", one sentence ×8, 33k chars, 63 s): cut`.
+- The system prompt puts what every session shares first and the per-session lines (model, working directory,
+  session) last, and plugin tools come in a fixed order, so a new session reuses the server's prompt cache: on a
+  local llama.cpp or Splash server its first answer starts in about 0.5 s instead of 4–6 s, and on Claude via
+  OpenRouter a new session reads the shared part from the cache (about 7× cheaper to start).
+- Chat hosts (`api: openai`) are no longer asked for `temperature: 0.0`: chi sends no temperature unless one is
+  configured, so each model runs at its provider's default (as native llama.cpp hosts already did). Greedy decoding
+  made DeepSeek v4.1-flash loop in its thinking. The idle recap and `/btw` follow suit. Set `sampling: {temperature:
+  …}` on a `hosts:` or `models:` entry to pin one; the empty-answer retry still runs at 0.6 unless one is set.
+
+### Fixed
+
+- loop-guard (bundle 0.3.3) cuts thinking that loops in a cycle of 7 or 8 short sentences, or with a longer
+  sentence ("I'll write the spec file now.") in the cycle: 48 sentences in a row with 12 or fewer different ones are
+  a loop. New settings `thinking.window_sentences` (48) and `thinking.window_distinct` (12).
+- A steer row names chi's senders in words: the web's row and trail flash and the terminal's nudged line say
+  `parent agent`, `chi send` and `plugin` instead of the raw `parent_agent` / `chi_send` / `plugin_send`.
+- Thinking off on Gemma 4 no longer warns that off wasn't honoured: its empty thought (whitespace alone) is not
+  counted as thinking.
+- An OpenRouter 402 whose `metadata.reason` is `weight_exceeds_budget` (the request alone is larger than the
+  key's credit budget) fails at once as `request too large for the credit budget on host <name>: …; lower
+  max_tokens (default.max_tokens) or raise the key's credit limit`, instead of being retried as credit held by
+  in-flight requests. Other 402s are unchanged.
+
+Update with `chi update`: loop-guard moves to 0.3.3 (the window rule and the quoted cut notice). Restart `chi web`
+and running sessions afterwards (`chi sessions restart ID`).
+
 ## [0.24.0] - 2026-10-04
 
 ### Added
@@ -1342,7 +1394,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.24.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/dm1try/samagotchi/compare/v0.24.0...v0.25.0
 [0.24.0]: https://github.com/dm1try/samagotchi/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/dm1try/samagotchi/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/dm1try/samagotchi/compare/v0.21.0...v0.22.0

data/docs/architecture.md

@@ -184,12 +184,18 @@ engine.system_prompt     # fully built system prompt string
 engine.session           # current session (Engine owns create/resume)
 ```
 
-The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance,
-AGENT.md, the working directory, **the model** (`Model: this session runs on
-<ref> (host …; model key …)` and a line telling the model to answer "which model
-are you" from it, not from training), the session id and log, the memory indexes,
-the identity and the preloaded memories. It is built once per loop and rebuilt only
-by a model switch (or changed tools), so the model line costs no KV churn.
+The system prompt (`SystemPrompt#build`) is the base prompt, then rg guidance, the
+identity and the preloaded memories, AGENT.md, the memory indexes, and last **the
+model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
+the model to answer "which model are you" from it, not from training), the working
+directory and the session id and log (Gemma's native tool declarations still follow).
+The order is for the servers' prompt caches, which reuse only an exact token prefix:
+what every session shares first, what changes least before what changes more, the
+per-session lines last, so a new session reuses everything above them. It is built
+once per loop and rebuilt only by a model switch (or changed tools), so the model
+line costs no KV churn.
+The full request layout, what breaks the cache and the rules for changes:
+[internals/prompt-caching.md](internals/prompt-caching.md).
 
 #### Subscribing to the live stream (and the bridge)
 
@@ -275,11 +281,12 @@ The metrics in `/state`, `/snapshot`, `/stats` and the SSE `snapshot`/`reset` fr
 newest turn the worker finished and any it hasn't saved yet (at most 20 turns), with their tool
 calls and the running turn's finished ones. The full history is the session's `analytics.json`,
 which `SessionMetrics#persist` rewrites after each turn; the web server merges the two by id.
-The totals' `tokens` block adds the cached and reasoning sums, the cost, the decode time and tokens
+The totals' `tokens` block adds the cached, cache-write and reasoning sums, the cost, the decode time and tokens
 behind the average speed (`avg_decode_tps`) and the last speeds (`last_decode_tps`,
 `last_prefill_tps`, `tps_source`: `server` or `estimate`). Each `generation_completed` event
-carries the generation's `speed` (`{decode_tps, source}`, null without one) and those running
-`tokens`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
+carries the generation's `speed` (`{decode_tps, source}`, null without one), its own prompt-cache
+counts (`prompt_tokens`, `cached_tokens`, `cache_write_tokens`: null when the server reported no writes) and
+those running `tokens`: the Engine closes the generation in `SessionMetrics#finish_generation` before relaying
 it, so the web's info bar updates per generation without parsing chunk payloads.
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:

data/docs/cli.md

@@ -420,9 +420,10 @@ file and index line stay as they are; only this session doesn't see it.
 `/help` lists the commands this session takes, the installed bundles' too, each
 with a line on what it does. `/stats` shows the session's numbers: turns, tool
 calls (by tool, with errors), iterations, tokens in/out summed over every
-request (with the cached and reasoning tokens when the server reports them),
-the decode speed, generation latency, cancellations, retries, context used
-and window, the prompt profile and the model the server says it ran, and the
+request (with the cached tokens, the cache writes and the reasoning tokens when the server reports them),
+the decode speed, generation latency, cancellations, retries (the network's),
+thinking cuts (generations a plugin such as loop-guard cut) and output cap hits
+(generations that ended at the provider's cap), context used and window, the prompt profile and the model the server says it ran, and the
 cost when the provider reports one (OpenRouter's `usage.cost`; no prices are
 guessed). The speed line is the last generation's and the session's average
 (weighted by tokens): llama.cpp reports it exactly (`87 tok/s out, 1.9k tok/s

data/docs/configuration.md

@@ -369,9 +369,9 @@ after an idle exit) gets that process's environment, so put a lasting choice in
 
 ## Sampling
 
-chi asks chat hosts (`api: openai`) for greedy decoding (`temperature: 0.0`) and sends native hosts no sampling
-fields, so their server's defaults apply (llama.cpp: temperature 0.8). `sampling:` on a `hosts:` entry or a `models:`
-entry sets request fields for the model's turns:
+chi sends no sampling fields by default, to chat hosts (`api: openai`) or native ones, so each model runs at its
+provider's defaults (llama.cpp: temperature 0.8; vLLM takes them from the model's `generation_config.json`).
+`sampling:` on a `hosts:` entry or a `models:` entry sets request fields for the model's turns:
 
 ```yaml
 hosts:
@@ -394,15 +394,16 @@ models:
 - A `models:` entry's fields win over its host's, field by field (the host can set a penalty and the model move only
   the temperature). The entry is found the way `profile:` is (the name as typed, alias-resolved or without its host
   prefix).
-- `temperature: null` (or `~`) sends no temperature, so the provider's default applies (vLLM takes it from the
-  model's `generation_config.json`).
+- `temperature: null` (or `~`) in a model's entry takes back a host's temperature, so the provider's default applies;
+  it also keeps the empty-answer retry (below) at that default.
 - Fields chi sets itself are refused with a warning: `model`, `messages`, `prompt`, `stream`, `stream_options`,
   `tools`, `tool_choice`, `stop`, `n_predict`, `max_tokens`, `n`, `parallel_tool_calls`, `response_format`,
   `cache_prompt`. A `sampling:` that isn't a map warns and is skipped.
-- Greedy decoding can make a heavily quantized thinking model loop in its reasoning ("Let me write the reply…"
-  for minutes) or end with an empty answer. Qwen's own advice for its thinking models is `temperature: 0.6,
-  top_p: 0.95` (not greedy), with `presence_penalty` between 0 and 2 against endless repetition.
-- The idle recap and side questions keep their own short, deterministic settings.
+- Greedy decoding (`temperature: 0`) can make a thinking model loop in its reasoning ("Let me write the reply…"
+  for minutes) or end with an empty answer; set it only for a model you have watched. Qwen's own advice for its
+  thinking models is `temperature: 0.6, top_p: 0.95`, with `presence_penalty` between 0 and 2 against endless
+  repetition.
+- The idle recap and side questions don't use `sampling:`; they send their own short output cap and no temperature.
 
 `/model` shows what applies (`sampling: temperature=0.6 presence_penalty=1.5 (hosts.work)`), and each request's
 `stream` line in the debug log carries a `sampling=` field with what was sent. The fields are read every turn, so a
@@ -514,10 +515,14 @@ gateway that spreads requests over several providers can key on it to keep one c
 prompt caches hit and every turn is answered by the same model. Servers that don't know the header ignore it.
 
 Chat requests for a Claude model (an id containing `claude`, such as `anthropic/claude-sonnet-5.5`) on a remote
-OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the system message and on the last
-message), so each step reads the earlier prompt from Anthropic's cache instead of paying for it again; the debug
+OpenAI-compatible host get two prompt-cache breakpoints (`cache_control` on the system prompt and on the last
+message), so each step reads the earlier prompt from Anthropic's cache instead of paying for it again. The system
+prompt goes as two text parts, the breakpoint after the first: everything sessions share, then the model, working
+directory and session lines, so a new session reads the shared part from the cache as well; the debug
 log's line shows `cache=on`. Nothing to configure. A provider behind a gateway may still not cache: check the
-cached tokens in `/stats`.
+cached tokens in `/stats`. Each request's own counts are in the debug log's `generation_completed` line:
+`prompt=` (its prompt tokens), `cached=` (read from the server's cache) and `cache_write=` (written to it, when the
+server reports writes); recap and side requests log theirs as `recap request_usage`.
 
 ## Llama Model Routing
 
@@ -616,6 +621,8 @@ Transient network failures are retried automatically with exponential backoff.
 - An HTTP 402 about credit held by in-flight requests (OpenRouter reserves credit for each running request, so
   one session's long request can make another's fail) is retried like a 429, 20s apart unless `Retry-After`
   says otherwise: with the default `retry.max` that is about 100s. With `retry.max: 0` it fails at once.
+  Not when its `metadata.reason` is `weight_exceeds_budget`: that request alone is larger than the key's credit
+  budget, so it fails at once (lower `default.max_tokens` or raise the key's limit).
 - A refused connection (nothing listening) is not retried: the turn fails at once with `can't reach host <name> at
   <address> (connection refused) — is the server running?`.
 - A stream that has already produced output is never retried (the retry would repeat it); it fails the turn.
@@ -671,7 +678,7 @@ message (before, a failed llama.cpp `/completion` ended the turn as
 | connection | reset, timed out, dropped mid-stream; refused | yes (network retry), not mid-stream; refused: no |
 | rate limited | HTTP 429 | yes, honouring `Retry-After` |
 | credits held | HTTP 402 "… in-flight requests" | yes, after 20s (or `Retry-After`) |
-| credits | any other HTTP 402: out of credits | no |
+| credits | any other HTTP 402: out of credits; one whose `metadata.reason` is `weight_exceeds_budget` (the request alone is over the key's budget: lower `default.max_tokens`) | no |
 | server | HTTP 5xx, llama.cpp's mid-stream `error:` event | 500/502/503/504/529 only |
 | auth | HTTP 401/403 | no |
 | bad request | other 4xx; a prompt larger than the context window, whatever the status | no |
@@ -912,6 +919,7 @@ described in their own sections.
 | `execute.preview_bytes` | `12288` | yes | |
 | `execute.telemetry_threshold_pct` | `80` | yes | |
 | `execute.timeout_sec` | `120` | yes | Seconds one `execute` command may run before it is stopped. |
+| `execute.description` | `true` | | `execute` offers the model an optional `description` (a few words on what the command does), shown as the tool row's title in `chi web` and in place of the command in the TUI's tool line. `false`: the parameter isn't declared, and rows show the command's first step. |
 | `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`. |

data/docs/hooks.md

@@ -399,7 +399,7 @@ stripped of surrounding whitespace, except file text, an edit's
 
 | Tool | `content:` from | `path:` from | Own fields |
 |------|-----------------|--------------|------------|
-| `execute` | `command` | — | `cwd` |
+| `execute` | `command` | — | `description`, `cwd` |
 | `read` | `path` | — | `start_line`, `end_line` |
 | `write` | — | `path` | `content` |
 | `edit` | — | `path` | `old_text`, `new_text`, `start_line`, `end_line` |

data/docs/internals/background-tasks.md

@@ -17,6 +17,7 @@ Recommended workflow:
 
 Behavior:
 
+- `execute`, `task_create` and the `!cmd` shell bang run the command in a non-login shell: `/bin/sh -c` on Linux; on macOS, when `/bin/zsh` is there, `/bin/zsh --emulate sh +o ignore_braces +o sh_glob -o bash_rematch +o bsd_echo -c` (macOS's `/bin/sh` is bash 3.2, which can't parse an apostrophe in a heredoc inside `"$( )"`, the usual commit message shape). That mode reads no rc files and keeps POSIX word splitting, unmatched globs left as is, `{1..3}`, `[[ … =~ (…) ]]` with `BASH_REMATCH`, arrays, `$'…'`, `&>` and echo expanding `\t`. Bash-only builtins and variables (`shopt`, `BASH_VERSION`, `${!prefix*}`, `read -p`) are not there.
 - Task metadata and output are persisted under `tmp/tasks/`.
 - Task listing is workspace-scoped (current project only).
 - `task_get` returns metadata and `output_path`; use `read` for output contents.

data/docs/internals/prompt-caching.md

@@ -0,0 +1,94 @@
+# Prompt caching: how a request is laid out, and how to keep it cache-friendly
+
+A model server reuses work only for the **exact token prefix** it has already seen. Change one token and
+everything after it is computed again (prefill). The local models we run (hybrid Qwen 3.6 / Ornith on llama.cpp
+and Splash) can only resume from a **restore point near the end** of an earlier prompt, not from any shared
+prefix. Anthropic (Claude via OpenRouter) caches only up to an explicit `cache_control` breakpoint. So the order
+of what chi sends decides what a new turn, or a new session, has to pay for.
+
+Measured with prompt-cache slice 1 (2026-10-04, fresh sessions, ~7.7k-token prompt):
+
+| Server | Before | After |
+|---|---|---|
+| Ornith on llama.cpp | 0 tokens reused, 6.4 s prefill per session | 94% reused, 0.5 s |
+| Splash Qwen 3.6 | 3.8 s | 97% reused from the 3rd session, 0.27 s |
+| Sonnet via OpenRouter | full cache write, $0.024 per session | reads the stable part, $0.0035 |
+
+## The layers of a request
+
+From the first token to the last. Every layer is a prefix of the next request's layers, unless something in the
+right-hand column happens.
+
+```
+ shared by every session ──────────────────────────────────────────────────  breaks it
+┌──────────────────────────────────────────────────────────────────────────┐
+│ tools        built-ins, then plugin tools sorted by (bundle, name)       │  a tool added/changed,
+│              (chat: the `tools` field; native: the model's template)     │  /model, a profile change
+├──────────────────────────────────────────────────────────────────────────┤
+│ SYSTEM, stable part                         SystemPrompt#system_prompt_with_index
+│   [native thinking token] base prompt                                    │
+│   rg guidance                                                            │  /thinking level,
+│   system identity (+ model overlay)                                      │  /model, editing a
+│   explicit (preloaded) memories                                          │  memory / AGENT.md
+│   AGENT.md                                                               │  (picked up by a new
+│   project + system memory indexes                                        │  process or a rebuild)
+│                         ◄── remote Claude: cache_control breakpoint #1   │
+├──────────────────────────────────────────────────────────────────────────┤
+│ SYSTEM, volatile tail (per session, least → most changing)               │
+│   Model: this session runs on …                                          │  another session
+│   working directory (location)                                           │  (expected: only
+│   session id + log                                                       │  this tail differs)
+│   [Gemma 4 native only: tool declarations after all of it]               │
+└──────────────────────────────────────────────────────────────────────────┘
+ shared by every turn of this session ─────────────────────────────────────
+┌──────────────────────────────────────────────────────────────────────────┐
+│ history      user / assistant / tool messages, APPEND-ONLY               │  !rollback, a failed or
+│              (images: the newest N, ImagePlan)                           │  cancelled turn's tail,
+│                         ◄── remote Claude: breakpoint #2 on the last     │  the image window
+│                             non-system message                           │  sliding, history
+├──────────────────────────────────────────────────────────────────────────┤  sanitizing (thinking
+│ tail notes   reminders, turn notes, steers (system/user messages)        │  stripped per spec)
+│ new prompt   this turn's user message                                    │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+- The system prompt is built **once per loop** and rebuilt only on `@prompt_builder.reset!`: a model switch
+  (`Engine#switch_model!`), a plugin's `tools_changed!`, or a profile change. A per-turn rebuild would
+  break everything below it.
+- On remote Claude, `LLM::PromptCache.mark` sends the system message as two text parts. The stable part carries
+  breakpoint #1, so a **new session** reads it from the cache. The last non-system message carries breakpoint
+  #2, so the **next request in the session** reads everything up to it. Mid and tail system messages never take
+  a breakpoint. The split point comes from `SystemPrompt#stable_length` via the message's `cache_split:`, which
+  never goes on the wire.
+- Side requests (idle recap, `/btw`) go through `IdleClient` with their own short system prompt. On a
+  single-slot local server they can push the session's prefix out of the cache. Fixing that is slice 2 of the
+  plan (R4 `id_slot`, R2 turn-end warm-up).
+
+## Rules for changes
+
+1. **Stable first, volatile last.** Anything that differs between sessions or turns (ids, paths, times, the
+   model line, counters) goes at the very end of the system prompt, ordered by how often it changes. Never put
+   a per-session value in the stable part. A guard spec checks that model, location and session are the last
+   sections (`spec/system_prompt_model_spec.rb`).
+2. **History is append-only.** Never rewrite an earlier message. Add a note at the tail instead. If a model's
+   spec forces a rewrite (e.g. stripping previous-turn thinking), accept the re-prefill and note it.
+3. **Deterministic order.** Tools, memory lists and anything else that's rendered from a hash or a set needs a
+   fixed sort. Plugin tools are sorted by (bundle, name) whatever order their plugins finished starting in
+   (R5a).
+4. **Don't rebuild the system prompt per turn.** Rebuild only when its content really changed (`reset!`).
+5. **Measure.** Every generation logs `prompt=`, `cached=` and, where the provider reports it, `cache_write=`
+   on its `generation_completed` log line. `/stats` shows "cached N (P%)" and "cache writes". A change that
+   drops `cached=` on the second fresh session is a regression. Update the prompt snapshot fixtures with
+   `UPDATE_PROMPTS=1` and read the diff: a cache-friendly change moves sections, it doesn't reorder per run.
+
+## Server-side settings worth knowing
+
+- **Splash:** `--persistent-cache` (with `--max-cache-disk`) keeps restore points across restarts. Splash learns
+  a new branch point on the 2nd session, so the 3rd one gets the full reuse.
+- **llama.cpp:** a single slot is shared by everything sent to it. `--parallel N` and `--cache-ram` give side
+  requests room without evicting the session. `--ctx-checkpoints` controls how many restore points a hybrid
+  model keeps.
+- **OpenRouter / Anthropic:** the default cache TTL is 5 minutes. Provider routing (which upstream serves a
+  request) also decides whether a cache is there to hit.
+
+Still to come: side requests on their own slot, a turn-end warm-up, image-window batches and longer remote TTLs.

data/docs/plugins.md

@@ -847,14 +847,20 @@ stream](hooks.md#watching-the-stream)) and cuts it:
   thinking has short sentences too ("Hmm.", "Fine."), but spread out or all
   different (code lines); a longer sentence ends the run, and lines inside a
   ```` ``` ```` code block don't count.
+- Any `window_sentences` sentences in a row, short or long, holding at most
+  `window_distinct` different ones are a loop too: a cycle of 7 or 8 short
+  sentences, or one where a longer sentence ("I'll write the spec file
+  now.") keeps ending the short run. Real thinking holds 40 or more
+  different sentences in any 48; DeepSeek's write loops hold 4 to 9.
 - 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`
+   again, with a hidden note that it was cut off. The user sees the loop's
+   first sentence quoted,
+   `loop-guard> thinking repeats itself ("Wait, the count of the letter r…", 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 stopped by loop-guard") with a card that quotes the repeated
@@ -869,6 +875,12 @@ the first loop ends the turn as stopped by loop-guard, with the notice and
 no card. `action: stop` stops the turn at the first loop; `action: notify` only
 warns, once per generation.
 
+The cut thinking never goes back to the model, but its last 20k chars are kept
+in the session's folder, `thinking_tails.jsonl` (with a generation that ran to
+the provider's output cap, or that a stop_turn ended): an archived session
+keeps them. A turn's record counts its cuts and cap hits (`cuts`, `capped` in
+`analytics.json`; `/stats` shows "thinking cuts" and "output cap hits").
+
 ```yaml
 bundles:
   loop-guard:
@@ -885,6 +897,8 @@ bundles:
       min_words: 5            # shorter sentences only count toward a short run
       short_run: 24           # this many short sentences in a row…
       short_distinct: 6       # …with at most this many different ones is a loop
+      window_sentences: 48    # any this many sentences in a row…
+      window_distinct: 12     # …with at most this many different ones is a loop
       forget_after: 10        # good steps in a row that forget a loop; 0: never
 ```
 

data/docs/testing.md

@@ -15,6 +15,18 @@ bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
+## Worktrees
+
+Each fix or feature gets its own worktree next to the main checkout:
+
+```sh
+script/worktree NAME [-b BRANCH]   # ../samagotchi-NAME off main, branch NAME unless -b; prints the path
+```
+
+It runs `git worktree add ../samagotchi-NAME -b BRANCH main`, then `npm ci --prefer-offline` in it, so
+`npm test` and `npm run e2e` work there right away (Ruby gems and Playwright's browsers are shared: nothing else
+to install). It refuses when the folder or the branch already exists.
+
 ## Integration specs
 
 Examples tagged `:integration` (`spec/integration/`, the "with LLM access" part of `spec/hooks/integration_spec.rb`)

data/lib/samagotchi/bundles/loop-guard/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: loop-guard
-version: 0.3.2
+version: 0.3.3
 scope: system
 description: "Breaks loops: the same tool call with the same result again and again in one turn is denied with advice (after a few denies the turn stops with a card), and thinking that repeats itself while it streams is cut and the model asked again"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:27b135c462d8462313edaa1faa90f3104a1bff3c421d6965e9e71955f347d55b
+  sha256: sha256:8cf255cd1cc0846a759fcf70144af53bfc634c9d5c766981ce0ef5e476749e0a
 requires_chi: ">= 0.6.0"

data/lib/samagotchi/bundles/loop-guard/plugin.rb

@@ -56,12 +56,20 @@ require "digest"
 #   too ("Hmm.", "Fine."), but spread out, or in runs of different ones
 #   (code lines); a sentence of min_words or more ends the run, one with no
 #   letters or digits neither counts nor ends it. Lines inside a ``` code
-#   block are not short sentences.
+#   block are not short sentences;
+# - a low-diversity window: among the last window_sentences sentences of any
+#   length, at most window_distinct different ones (exact, normalized). It
+#   sees a cycle too long for the short run (7-8 short sentences), or one
+#   where a longer sentence keeps ending the run ("Go. OK. I'll write the
+#   spec file now. Go."). Real thinking holds 40+ different sentences in
+#   any 48 (the lowest seen: 42); a loop holds under 10. Lines inside a ```
+#   code block don't count.
 # Nothing triggers before min_chars of thinking. O(new chars) per feed.
 class ThinkingWatch
   DEFAULTS = { "watch" => true, "action" => "retry", "min_chars" => 2000, "repeats" => 3, "max_period" => 6,
                "similarity" => 0.5, "min_span_sentences" => 6, "min_span_chars" => 600, "max_same" => 8,
-               "min_words" => 5, "short_run" => 24, "short_distinct" => 6, "forget_after" => 10 }.freeze
+               "min_words" => 5, "short_run" => 24, "short_distinct" => 6, "window_sentences" => 48,
+               "window_distinct" => 12, "forget_after" => 10 }.freeze
   ACTIONS = %w[retry stop notify].freeze
   MAX_CARRY = 400
   # One sentence again and again needs this much more alike than a cycle.
@@ -81,7 +89,7 @@ class ThinkingWatch
     out["watch"] = !%w[false no off 0].include?(raw["watch"].to_s.downcase) if raw.key?("watch")
     out["action"] = raw["action"].to_s if ACTIONS.include?(raw["action"].to_s)
     %w[min_chars repeats max_period min_span_sentences min_span_chars max_same min_words short_run
-       short_distinct].each do |key|
+       short_distinct window_sentences window_distinct].each do |key|
       number = Integer(raw[key].to_s, exception: false)
       out[key] = number if number&.positive?
     end
@@ -104,6 +112,8 @@ class ThinkingWatch
     @min_words = settings["min_words"]
     @short_run = settings["short_run"]
     @short_distinct = settings["short_distinct"]
+    @window_sentences = settings["window_sentences"]
+    @window_distinct = settings["window_distinct"]
     @same_similarity = [@similarity + SAME_MARGIN, 0.95].min
     @carry = +""
     @window = [] # the last max_period + 1 sentences
@@ -112,6 +122,8 @@ class ThinkingWatch
     @counts = Hash.new(0)
     @short_count = 0  # short sentences in a row
     @short_window = [] # the last short_run of them, [key, text]
+    @recent = [] # the last window_sentences sentences, [key, text]
+    @recent_counts = Hash.new(0) # key => times in @recent
     @in_code = false
     @thinking_chars = 0
   end
@@ -153,7 +165,8 @@ class ThinkingWatch
     end
     words = text.downcase.gsub(/[^[:alnum:]]+/, " ").split
     short = short_loop(text.strip, words) unless @in_code
-    return (short if @thinking_chars >= @min_chars) if words.length < @min_words
+    window = window_loop(text.strip, words) unless @in_code
+    return (@thinking_chars >= @min_chars ? short || window : nil) if words.length < @min_words
 
     key = words.join(" ")
     sentence = Sentence.new(text: text.strip, words: words.map(&:hash).uniq,
@@ -164,7 +177,27 @@ class ThinkingWatch
     @window.shift if @window.length > @max_period + 1
     return nil if @thinking_chars < @min_chars
 
-    cycle || (same >= @max_same ? Loop.new(period: 1, times: same, sentences: [sentence.text], chars: nil) : nil)
+    cycle || (same >= @max_same ? Loop.new(period: 1, times: same, sentences: [sentence.text], chars: nil) : nil) || window
+  end
+
+  # The last window_sentences sentences (any length) hold at most
+  # window_distinct different ones: a loop. Its sentences are the most
+  # frequent first.
+  def window_loop(text, words)
+    return nil if words.empty?
+
+    key = words.join(" ")
+    @recent << [key, text]
+    @recent_counts[key] += 1
+    if @recent.length > @window_sentences
+      old, = @recent.shift
+      @recent_counts.delete(old) if (@recent_counts[old] -= 1).zero?
+    end
+    return nil if @recent.length < @window_sentences || @recent_counts.size > @window_distinct
+
+    texts = @recent.to_h # key => its last text
+    top = @recent_counts.sort_by { |_key, n| -n }.first(3).map { |key, _n| texts[key] }
+    Loop.new(period: @recent_counts.size, times: @window_sentences / @recent_counts.size, sentences: top, chars: nil)
   end
 
   def short_loop(text, words)
@@ -276,14 +309,17 @@ class Plugin
     @watch_done = true
     what = "#{found.period == 1 ? "one sentence" : "#{found.period} sentences"} ×#{found.times}, " \
            "#{(@watch.thinking_chars / 1000.0).round}k chars, #{(event[:elapsed_ms].to_i / 1000.0).round} s"
+    # The notices quote the loop's sentences on one line (a short cycle
+    # whole), as the stop card does.
+    quoted = "\"#{cut(found.sentences.first(3).join(" ").gsub(/\s+/, " "))}\", #{what}"
     case @thinking["action"]
     when "notify"
-      ctx.notify("thinking repeats itself (#{what})", level: :warn)
+      ctx.notify("thinking repeats itself (#{quoted})", level: :warn)
     when "retry"
       @thinking_loops += 1
       return stop_thinking(ctx, found, what) if @thinking_loops > 1
 
-      ctx.notify("thinking repeats itself (#{what}): cut", level: :warn) if ctx.stop_generation("its thinking kept repeating itself")
+      ctx.notify("thinking repeats itself (#{quoted}): cut", level: :warn) if ctx.stop_generation("its thinking kept repeating itself")
     else
       stop_thinking(ctx, found, what)
     end

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.24.0
+version: 0.25.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files: