samagotchi 0.51.0 → 0.52.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f93eddaef9e07210789382afa552868d94a39b0bca798bb7c0c5a8d4e23cc693
-  data.tar.gz: 61f1005b2dd4efcdfba5379622193e79c7bfd305a4eac651827830a54399d1c9
+  metadata.gz: 98660ef911df1f010a45ded3190d0017793fc4e01c1229860ab523a7d2825ffd
+  data.tar.gz: 2c1eab9152f8fba6efa7507d17dde3deb54a0e5bbd26a56a61f23f54d3d38a15
 SHA512:
-  metadata.gz: d6ea69e71620afeca9b1813fef569c9f39742d1dbf0d28ca9aa2675c0445ef5b397bdd44fd3b6d544dc3ba07a131771136e7d2163669d13925a0d952b69df175
-  data.tar.gz: 9abd2290def4fd2bc5b12e9ea0c5fe722c2b4a8ead03044a8944108a43e3105325fc7bf854e5dd5bba3641fb1e0c0c2047835aa4e5ddeef91013ccf115244a0c
+  metadata.gz: d85715550f95d875ced247c2642c04183507fbb2d85bf6f1201e62a3fb2471ba27c27a110dee57046a716a38e139acd8aaf5dbc7ea0ded2051c486056bb115fb
+  data.tar.gz: 25591f45d69afe94d02ebabfce8887cfb126bf0c1b21ed74cc172ecbcfe881990f3431f43cde1b5b2c8801684102f628afbf4446bc2acab77fc50ef2ca6ff7f7

data/CHANGELOG.md

@@ -8,6 +8,50 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.52.0] - 2026-10-10
+
+### Added
+
+- `/thinking` shows the thinking level the next turn runs at and where it came from; `/thinking off|low|medium|high`
+  sets the session's own level (saved with the session, first in the order), `/thinking default` unsets it. A change
+  waits for the turn's end, and the reply says what it costs the prompt cache. `/model` and `/stats` show
+  `low (session)`; a continue and a plugin's fork keep the level, a delegate starts without it.
+- Web: a `think` chip in the session bar and on the start page shows the thinking level (`think low · session`); a
+  click opens a level select that runs `/thinking` (the start page's choice is for the next new chat only).
+- `chi send --new --thinking LEVEL` starts the session with its own thinking level (refused beside `--continues`,
+  which takes the previous link's).
+
+### Changed
+
+- `chi --thinking LEVEL` on a run that starts or resumes a session sets that session's own level (saved, above
+  `SAMAGOTCHI_THINKING_LEVEL`) instead of the process's; `default` unsets it. `chi web --thinking` stays a default for
+  the workers it spawns, below a session's own.
+- `llm_context.budget_tokens` (and a model's or host's `llm_context_budget_tokens`) takes `64k` and `off` like
+  `/llm-context budget`, with the same range (4k to 10M); a budget out of range warns and is ignored.
+- Web: a turn's step is one lit-html template for the live page and a reload (lit-html 3.3.3 vendored in
+  `web/public/vendor/`, no build step). A live step no longer keeps an empty narration element, and a plain answer's
+  thinking block is drawn fresh from the same template.
+
+### Fixed
+
+- Web: the info bar's session clock ticks during a session's first turn (a session started from the start page
+  showed a frozen `session 0ms`).
+- Web: `/cut TEXT` in the composer sends TEXT as a cut, as in a terminal and `chi send --cut` (it was refused as "not a
+  session command"); with no turn running it is TEXT as a normal turn. `/queue TEXT` during a turn says it isn't
+  available in the web yet, instead of that error.
+- Web: command bubbles (`/help`, `/model`, `/llm-context` …) stay in place when a `!cmd` or `!rollback` redraws the
+  conversation; a reload still drops them (only a `!cmd`'s output is saved).
+- Web: a reloaded turn whose messages carry no parts keeps "(called as bash)" on its rows (from the tool records).
+- A turn posted with `delivery: "queue"` (the Bridge's and the web's `POST …/turn`) is refused with 400
+  `delivery_unavailable` until queueing is built, instead of being acked as queued and then merged at the running
+  turn's next step. No chi client sends it.
+- An attached terminal runs `/queue TEXT` at the open prompt (no turn running) as a turn, as the plain REPL and the
+  docs say, instead of refusing it; it is refused only while a turn runs.
+- A `hosts:` entry that fails while it is read is ignored on its own with a warning naming it, instead of every host
+  silently dropping (in the process and in its workers); a failure outside the entries is logged.
+- A `/thinking`, `/model` or `/llm-context` queued during a turn no longer lets the turn-end warm-up prefill a prompt
+  the change then throws away.
+
 ## [0.51.0] - 2026-10-10
 
 ### Added
@@ -2343,7 +2387,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.51.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.52.0...HEAD
+[0.52.0]: https://github.com/dm1try/samagotchi/compare/v0.51.0...v0.52.0
 [0.51.0]: https://github.com/dm1try/samagotchi/compare/v0.50.0...v0.51.0
 [0.50.0]: https://github.com/dm1try/samagotchi/compare/v0.49.0...v0.50.0
 [0.49.0]: https://github.com/dm1try/samagotchi/compare/v0.48.0...v0.49.0

data/README.md

@@ -210,7 +210,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Hooks](docs/hooks.md): plugin hooks and bundle hooks
 - [Plugins](docs/plugins.md): bundle plugins (commands, tools, hooks)
 - [Architecture](docs/architecture.md): Engine, TerminalUI, bridge, web
-- Internals: [Gemma 4 contract](docs/internals/gemma4-contract.md), [context telemetry](docs/internals/context-telemetry.md), [tool output limits](docs/internals/tool-guardrails.md), [background tasks](docs/internals/background-tasks.md)
+- Internals: [Engine](docs/internals/engine.md), [Gemma 4 contract](docs/internals/gemma4-contract.md), [prompt caching](docs/internals/prompt-caching.md), [context telemetry](docs/internals/context-telemetry.md), [LLM context: forget layer](docs/internals/llm-context-forget.md), [replay benchmark](docs/internals/llm-context-bench.md), [live runs](docs/internals/llm-context-live.md), [tool output limits](docs/internals/tool-guardrails.md), [background tasks](docs/internals/background-tasks.md)
 
 ## Development
 

data/bin/chi

@@ -116,8 +116,9 @@ parser = OptionParser.new do |opts|
   opts.on("--model NAME", "Model for this run, not saved (overrides --resume's; config default.model) [env SAMAGOTCHI_DEFAULT_MODEL]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
   opts.on("--profile NAME", Samagotchi::ModelProfile::NAMES,
           "Prompt profile for every model in this run (#{Samagotchi::ModelProfile::NAMES.join("|")}) [alias for --model-profile]") { |p| cli_overrides["model.profile"] = p }
-  opts.on("--thinking LEVEL", Samagotchi::Thinking::LEVELS.map(&:to_s), "How much the model thinks this run: off|low|medium|high|default (outranks config.yml; " \
-                              "sessions already running keep theirs) [env SAMAGOTCHI_THINKING_LEVEL]") { |l| cli_overrides["thinking.level"] = l }
+  opts.on("--thinking LEVEL", Samagotchi::Thinking::LEVELS.map(&:to_s), "This session's own thinking level: off|low|medium|high|default (saved in the session, " \
+                              "before the model's; default unsets it; /thinking changes it). With chi web: the default for the sessions " \
+                              "its workers run, below a session's own [env SAMAGOTCHI_THINKING_LEVEL]") { |l| options[:thinking] = l }
   opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
   opts.on("--mute NAME", "Hide a memory from this session: not in the prompt, refused by memory_read (repeatable; a comma list too)") { |m| (options[:muted] ||= []) << m }
   opts.on("--llm-context LAYERS", "This session's own LLM context strategy: none, or layers such as stale,forget (saved in the session, " \
@@ -198,6 +199,11 @@ if scratch
   end
 end
 
+# --thinking: chi web's is a default for the workers it spawns (below a
+# 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]
+
 # 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?
@@ -333,7 +339,8 @@ if launch == :attached
                                                        default_input: !options[:no_default_input],
                                                        memories: options[:memories] || [],
                                                        muted_memories: options[:muted] || [],
-                                                       llm_context: options[:llm_context] || {})
+                                                       llm_context: options[:llm_context] || {},
+                                                       thinking: options[:thinking])
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
@@ -351,6 +358,7 @@ begin
     memories: options[:memories] || [],
     muted_memories: options[:muted] || [],
     llm_context: options[:llm_context] || {},
+    thinking: options[:thinking],
     non_interactive: options[:non_interactive],
     model_name: options[:model],
     scratch: scratch

data/docs/architecture.md

@@ -65,7 +65,7 @@ TerminalUI  ──  delegates  ──▶  Engine
 ```
 
 - **`Engine`** (`lib/samagotchi/engine.rb`) owns *all* agent logic and knows nothing
-  about the terminal.
+  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`.
 - The `on_event:` seam on `run_turn` exposes raw `KernelLoop` events plus the

data/docs/cli.md

@@ -186,7 +186,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--no-shared` | Run the plain in-process REPL for this run. |
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
 | `--model NAME` | Use this model for the run (overrides the configured default and a resumed session's model). |
-| `--thinking LEVEL` | How much the model thinks this run: `off`, `low`, `medium`, `high` or `default` (env `SAMAGOTCHI_THINKING_LEVEL`), over the config's levels. A session already running keeps its own. See "Thinking" in configuration.md. |
+| `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). See "Thinking" in configuration.md. |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
 | `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
@@ -290,12 +290,12 @@ of UIs at once: the Web UI and attached terminals (`chi`, `--resume`,
 `--attach`). They all see the same turns as they happen, and any of them can send
 a prompt, also while a turn runs (it merges into that turn as steering: the model
 is told it is a steer and who sent it). Steering waits for the model's next step
-and cuts nothing. `/cut TEXT` in a terminal (or `chi send --cut`) asks for a cut:
+and cuts nothing. `/cut TEXT` in a terminal or the web composer (or `chi send --cut`) asks for a cut:
 once the model has streamed only thinking for `steer.cut_after` seconds (default
 20), now or while your message waits, that generation is cut and the step starts again with your message, marked
 `↪ cut in for your message` (see
-[configuration.md](configuration.md#llama-network-retry-behavior)). The web
-composer doesn't cut yet. The
+[configuration.md](configuration.md#messages-during-a-running-turn-steer-and-cut)). The web
+composer has no `/queue` yet (it says so and sends nothing). The
 first answer to an `ask_user_question` wins; the other UIs close their widget.
 An empty answer dismisses the question in every UI. The model is then told
 not to go ahead with what it asked about, or change anything else, and to wait.
@@ -483,6 +483,20 @@ the same values on its `llm context:` line. The web's info bar shows them as the
 through `/llm-context`. See "LLM context: a session's own strategy" in
 [configuration.md](configuration.md).
 
+`/thinking` shows the thinking level the next turn runs at and where it came
+from (`session`, `--thinking` / `SAMAGOTCHI_THINKING_LEVEL`, `models: <key>`,
+`hosts.<name>`, `thinking.level`). `/thinking off|low|medium|high` sets the
+session's own level, which comes first; `/thinking default` unsets it. It is
+saved with the session (a `--resume`, a continue and `/model` keep it) and
+applies from the next turn's start; the reply says what the change costs the
+prompt cache: the whole prompt on native Gemma 4 (its `<|think|>` starts the
+prompt), only the tail on native Qwen, and other request fields on a chat host
+(a local llama.cpp or Splash server keeps its cache; a hosted API such as
+OpenRouter → Claude or OpenAI may restart its own). `/thinking` alone answers
+mid-turn too; a change sent while a turn runs waits for the turn's end, and
+skips that turn's warm-up. `/stats` shows the level on its `thinking:` line.
+See "Thinking" in [configuration.md](configuration.md).
+
 ### Typing during a turn
 
 The prompt stays open while a turn runs, in an attached terminal and in the plain
@@ -503,16 +517,17 @@ REPL alike:
   cut).
 - `/queue TEXT` (plain REPL only) runs TEXT as a turn of its own after this
   one: `(queued: runs after this turn)`. An attached terminal says
-  `(/queue isn't available in an attached session yet)` and sends nothing.
+  `(/queue isn't available in an attached session yet)` and sends nothing (the web
+  composer: `(/queue isn't available in the web yet; …)`).
   At the open prompt (no turn running) `/cut TEXT` and `/queue TEXT` run TEXT
   as a normal prompt.
 - Commands answer, wait or are refused, by what they do:
   - At once, beside the turn: `/stats`, `/recap`, `/help`, `/context`, a
     plugin's anytime command (`/btw`), and the commands that only show
-    something: `/models` (with a filter too), and `/model`, `/llm-context` and
-    `/guardrails` alone.
+    something: `/models` (with a filter too), and `/model`, `/llm-context`,
+    `/thinking` and `/guardrails` alone.
   - After the turn: the ones that change something (`/model X`, `/model clear`,
-    `/llm-context strategy …`, `/guardrails revoke N`) and `!cmd`, whose output
+    `/llm-context strategy …`, `/thinking LEVEL`, `/guardrails revoke N`) and `!cmd`, whose output
     joins the conversation. `(queued: runs after this turn)` says so at once (the
     web draws the command's bubble dashed, with the same words, until it ran);
     when the turn ends they run in the order sent, a prompt sent before one

data/docs/configuration.md

@@ -470,13 +470,38 @@ models:
 - `default` sends nothing: the provider's or the chat template's own default, which is chi's behaviour without the
   setting. For some hybrid models that default is *no* thinking (DeepSeek V3.1 on OpenRouter); `medium` turns it on.
   `on` isn't a level.
-- Order, first set wins: `--thinking LEVEL` or `SAMAGOTCHI_THINKING_LEVEL`, then the `models:` entry (found the way
-  `profile:` is), then the `hosts:` entry, then `thinking.level` in the file, then `default`. Anything else than a
-  level warns once and counts as unset.
-- The flag reaches the sessions that start with it; a session already running keeps its level. `models:` levels
-  and `thinking.level` in the file are read every turn; a host's `thinking:` reaches a worker when it starts, as
-  its `sampling:` does (`chi sessions stop` to change it).
-- `/model` shows the level and where it came from (`thinking: off (models: qwen3.6-35b-a3b)`), `chi self` too.
+- Order, first set wins: the session's own level, then the process default (`chi web --thinking LEVEL`, or
+  `SAMAGOTCHI_THINKING_LEVEL`), then the `models:` entry (found the way `profile:` is), then the `hosts:` entry, then
+  `thinking.level` in the file, then `default`. Anything else than a level warns once and counts as unset.
+- **A session's own level** (`off`, `low`, `medium`, `high`) is saved in the session (its file's `"thinking"`), so a
+  `--resume`, a respawned worker, a continue (the next link of a chain) and `/model` keep it; a plugin's fork copies
+  it, a delegate child starts without it (it runs at its model's level). Set it with:
+  - `/thinking LEVEL` in the session (`/thinking default` unsets it, `/thinking` alone shows the level and where it
+    came from);
+  - `chi --thinking LEVEL` on a run that starts or resumes a session (the REPL, `-p`, `--resume`, an attached one);
+  - `chi send --new --thinking LEVEL`;
+  - the web's `think` chip, in the session bar and on the start page (`POST /api/sessions` takes `"thinking": "low"`;
+    anything that isn't a level answers `400 invalid_thinking`).
+- `chi web --thinking LEVEL` is the default for the sessions its workers run, below a session's own. A session started
+  with only the env (`SAMAGOTCHI_THINKING_LEVEL=low chi send --new …`) loses the level when a worker without that env
+  (`chi web`'s, say) wakes it later: use `chi send --new --thinking low`.
+- A level is fixed for a turn: a change takes effect at the next turn's start. `/thinking LEVEL` sent while a turn
+  runs waits for its end (as `/model X` does), and holds off that turn's warm-up. What a change costs the prompt cache,
+  which `/thinking` says:
+
+  | Backend | A level change |
+  |---|---|
+  | native Qwen (`qwen36`) | only the prompt's tail (the empty thought after the cue) |
+  | native Gemma 4 (`gemma4`) | the whole prompt is read again: `<\|think\|>` starts the system prompt |
+  | chat host, local llama.cpp or Splash | other request fields; the server keeps its cache (a Gemma template re-reads it all) |
+  | chat host, OpenRouter → Claude | thinking params are part of the cached prefix: the cache restarts |
+  | chat host, OpenRouter → OpenAI reasoning | an effort change rewrites hidden instructions: the prefix is lost |
+
+- `models:` levels and `thinking.level` in the file are read every turn; a host's `thinking:` reaches a worker when
+  it starts, as its `sampling:` does (`chi sessions stop` to change it).
+- `/model` shows the level and where it came from (`thinking: off (models: qwen3.6-35b-a3b)`, `thinking: low
+  (session)`), `/stats` on its `thinking:` line, `chi self` too (a session's own level first when run from its
+  commands).
 - The idle recap and plugins' side questions always ask with thinking off, whatever the level.
 
 What each backend gets:
@@ -765,14 +790,6 @@ no made-up answer is saved.
 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).
-A message for a running turn goes in at its next step and cuts nothing. A message sent as a cut (`/cut TEXT` in a
-terminal, `chi send --cut`) cuts the model's generation once it has streamed only thinking for `steer.cut_after`
-seconds (default `20`, env `SAMAGOTCHI_STEER_CUT_AFTER`, `0` = never; counted from its first thinking token, so the
-wait for a busy server doesn't count) and still does, and the model starts the step again with the message
-(`↪ cut in for your message`). One that comes earlier cuts once the thinking passes `steer.cut_after`, unless the
-step ends first and the message goes in there. The web composer and a parent agent never ask for a cut. Such a cut spends no `retry.empty_answer` attempt and sends no
-hidden note; only the cut thinking is lost. A generation that has streamed visible text or a tool call is never cut,
-and a plugin's steer (`ctx.steer`, `ctx.sessions.send`) never cuts.
 
 Assist-mode UX:
 
@@ -781,6 +798,29 @@ Assist-mode UX:
   `stream dropped`), the wait, and the retry of all there will be.
 - If retry attempts are exhausted, the submitted prompt is restored into the input editor so you can edit and resubmit.
 
+## Messages during a running turn: steer and cut
+
+A message for a running turn goes in at its next step and cuts nothing. A message sent as a cut (`/cut TEXT` in a
+terminal or the web composer, `chi send --cut`) cuts the model's generation once it has streamed only thinking for `steer.cut_after`
+seconds (default `20`, env `SAMAGOTCHI_STEER_CUT_AFTER`, `0` = never; counted from its first thinking token, so the
+wait for a busy server doesn't count) and still does, and the model starts the step again with the message
+(`↪ cut in for your message`). One that comes earlier cuts once the thinking passes `steer.cut_after`, unless the
+step ends first and the message goes in there. A plain message (from the web composer, `chi send` without `--cut`,
+a parent agent) never asks for a cut. Such a cut spends no `retry.empty_answer` attempt and sends no hidden note; only
+the cut thinking is lost. A generation that has streamed visible text or a tool call is never cut, and a plugin's steer
+(`ctx.steer`, `ctx.sessions.send`) never cuts.
+
+`/queue TEXT` in the plain REPL runs TEXT as a turn of its own after the running one; the attached terminal and the web
+don't queue yet, and a request that asks the Bridge or the web for `delivery: "queue"` is refused (400
+`delivery_unavailable`).
+
+`steer.cut_after` (default `20`, env `SAMAGOTCHI_STEER_CUT_AFTER`):
+
+```yaml
+steer:
+  cut_after: 20   # seconds of thinking-only output before a cut may land; 0 = never
+```
+
 ## Server errors
 
 An error status or a server's error event fails the turn with the server's
@@ -961,7 +1001,7 @@ without it: no ids, no tool, the same prompt.
 
 ```yaml
 llm_context:
-  budget_tokens: 64000        # optional: the [CONTEXT: …] lines count against 64k, not the window
+  budget_tokens: 64k          # optional (64000, 64k; 4k to 10M): the [CONTEXT: …] lines count against 64k, not the window
 models:
   deepseek-v4.1-flash:
     llm_context_strategy: [stale, forget]
@@ -1122,7 +1162,7 @@ described in their own sections.
 | `models.<key>.llm_context_apply`, `hosts.<name>.llm_context_apply` | none | | A model's or host's `llm_context.apply`. |
 | `llm_context.stale_edits` | `false` | | Opt-in, experimental: `stale` also stubs a read that a later successful edit or write of the file superseded. |
 | `llm_context.protect_steps` | `3` | | `stale` never stubs a read of a file edited or written in the last N steps (tool batches; counted across the whole conversation, not only the turn). `0` turns the protection off. Under `forget`, `forget_outputs` refuses an output from the last N steps, and a read of a file edited or written in them unless the forget keeps some of its lines. |
-| `llm_context.budget_tokens` | none | | A soft context budget in tokens (e.g. `64000`); off when unset or `0`. When set, the context status buckets (`context.status_thresholds`) count against it instead of the window (the smaller of the two), so the `[CONTEXT: …]` lines, `payoff`'s top bucket and, under `forget`, the `forget_outputs` offers come under it. A session's own (`--llm-context-budget`, `/llm-context budget`; `off` there wins over the model's), then `models.<key>.llm_context_budget_tokens` and `hosts.<name>.llm_context_budget_tokens` come first. |
+| `llm_context.budget_tokens` | none | | A soft context budget in tokens (`64000` or `64k`, 4k to 10M, as `/llm-context budget` takes it); off when unset, `0` or `off`; a value out of range warns and is ignored. When set, the context status buckets (`context.status_thresholds`) count against it instead of the window (the smaller of the two), so the `[CONTEXT: …]` lines, `payoff`'s top bucket and, under `forget`, the `forget_outputs` offers come under it. A session's own (`--llm-context-budget`, `/llm-context budget`; `off` there wins over the model's), then `models.<key>.llm_context_budget_tokens` and `hosts.<name>.llm_context_budget_tokens` come first. |
 | `models.<key>.llm_context_budget_tokens`, `hosts.<name>.llm_context_budget_tokens` | none | | A model's or host's `llm_context.budget_tokens`. |
 | `llm_context.policy` | the subtask-boundaries line | | The sentence `forget_outputs`' description carries (the `forget` layer): "Tidy at subtask boundaries: once a subtask is done, forget its tool outputs and note what it established; keep anything you'll still edit against." Blank: none. Read when a session starts. |
 | `context.chars_per_token` | `4.0` | yes | Estimate ratio when the server reports no usage. |
@@ -1132,7 +1172,7 @@ described in their own sections.
 | `context.every_seconds` | `300` | | How often an attached context source's command runs when it has no `--every` (seconds, at least 30). See [Attached context](context.md). |
 | `context.wake` | `true` | yes | A source whose update says `wake: true` may start a turn in a live, idle session (one per source per 10 minutes, within `session.max_wakes`); `false`: updates wait as notes for the next turn. See [Waking](context.md#waking). |
 | `thinking.turn_preamble` | `true` | yes | Ask a `qwen36` model to open its thinking with a short `TURN:` line (the step label). |
-| `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't. See "Thinking". |
+| `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't; a session's own level outranks them all, and `--thinking` sets it on a session run (on `chi web` it sets this). See "Thinking". |
 | `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
 | `hosts.<name>.models` | none | | The model ids a host serves whatever its `/v1/models` lists: a map of ids, or a plain list. See "Models a host serves but doesn't list". |
 | `hosts.<name>.models.<id>.served` | none | | The models the host may answer that id with (exact ids, any case), or `any`: no served-model warning for those. See "Models a host serves but doesn't list". |
@@ -1146,7 +1186,7 @@ described in their own sections.
 | `retry.base_delay` | `0.5` | yes | |
 | `retry.max_delay` | `8.0` | yes | |
 | `retry.empty_answer` | `1` | | Times a turn asks again after an empty answer (at most 3, `0` = off). See "Llama Network Retry Behavior". |
-| `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message sent as a cut (`/cut TEXT`, `chi send --cut`) cuts it; other messages go in at the next step; `0` = never. See "Llama Network Retry Behavior". |
+| `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message sent as a cut (`/cut TEXT`, `chi send --cut`) cuts it; other messages go in at the next step; `0` = never. See [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
 | `turn.max_iterations` | `100` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
 | `turn.parent_continue` | `true` | | Whether a parent agent (`chi answer`) may answer Continue to a session's step-limit question; `false`: Stop only. config.yml only: no environment variable. See [Sub-agent](sub-agent.md) and [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |

data/docs/memory.md

@@ -250,6 +250,17 @@ for a file another bundle installed.
   installed bundle owns is left out with a line (`Left out identity.md:
   installed by bundle samagotchi-system (name it to include it)`); naming it
   in `FILES...` includes it.
+  `--name NAME`, `--version VER` and `--description DESC` go into the
+  bundle's manifest, and `--out PATH` picks where it goes (`.zip`, `.tar.gz`,
+  `.tgz` or `.tar` gives that archive, any other path a directory; default
+  `<name>.zip`).
+- **An upgrade that meets your edits.** `chi bundle upgrade` updates a file
+  you didn't edit and keeps one you did (a conflict), then asks on a
+  terminal whether to launch a chi session that merges the two (`/exit`
+  when done). `--agent` launches it without asking, `--no-agent` never does;
+  with neither and no terminal it keeps your edits and says so. Kept edits
+  exit 2; `chi bundle diff NAME FILE` shows the base, and `--force` takes
+  the bundle's version.
 
 ## Bundle profiles: core and dev
 

data/docs/plugins.md

@@ -140,7 +140,8 @@ end
 
 `/help` (itself an anytime command) lists every command the session knows:
 chi's own, each bundle's with the bundle's name, and the terminal UIs' own
-(`/stats`, `/exit`, `/detach` …), marked `terminal only` or `attached only`.
+(`/stats`, `/exit`, `/detach` …), marked where they run: `terminal only`,
+`attached only`, `repl only`, or `terminal and web only` (`/cut`).
 It works in all three UIs.
 
 ### `chi.tool(name, description, params:, schema:, label:, preview:, targets:) { |args, ctx| … }`

data/docs/sessions.md

@@ -181,12 +181,16 @@ chi send --new --continues last:3fa2 -m "new day"      # the next link of 3fa2's
 ```
 
 - `--new` takes no ids (one new session per call). `--dir DIR` is its folder, and so its project (default the current one); `--model M` its model (default the configured one). A host config.yml doesn't have is refused before anything is spawned (exit 1). A `host:id` whose id that host's last saved list doesn't have (`~/.local/state/samagotchi/model_lists.json`, what `chi models` / `/models` / the web last listed for that host, at most a week old) gets one warning line on stderr, with up to three close ids as a hint (`did you mean: gemma-small?`), and the session starts anyway: some hosts serve ids they don't list (a one-model llama.cpp server takes any name). A saved list older than 10 minutes that misses the id is re-listed once (that one host, capped at 5 s) before the warning: the list can be stale by content, e.g. a one-model server reloaded with another model; a list re-listed that way names the typed id, nothing is said. A list younger than 10 minutes is taken at its word (a host that serves ids it never lists would otherwise pay the re-list on every launch). A re-list that fails, times out or lists nothing falls back to the saved list. An id its host declares under `hosts.<name>.models` (see [configuration](configuration.md#models-a-host-serves-but-doesnt-list)) is never warned about or re-listed. A bare id (no `host:`) isn't checked that way — routing sends it to whichever host lists or declares it — and with no saved list for the host nothing is said; a wrong id then fails the worker's first turn.
+- `--thinking LEVEL` (with `--new`) gives the new session its own thinking level (`off`, `low`, `medium`, `high`;
+  `default` gives it none), saved in it and first in the order. A level from the env
+  (`SAMAGOTCHI_THINKING_LEVEL=low chi send --new …`) only reaches the worker this call spawns: when the session's
+  worker is woken later (by `chi web`, a delivery) without that env, the level is gone. Use `--thinking`.
 - `--new` prints `<full id>  started` on stdout. With `--wait` that line (and the `sent` line for an existing session) goes to stderr, so stdout is exactly the answer: the reply of the turn the message started, in full. It is the worker's `output/` file, the same one `delegate` reads; a turn that ends with only tool calls and no text has none.
 - `--wait` takes one session: `--new` or one id. A session with a running turn is refused (`busy: a turn is running; wait or attach`, exit 1): the message would run after it, and its reply would come back as the answer.
 - Exit codes with `--wait`: 0 answered; 3 the turn waits for an answer from you (a question, a hook's question, a guardrail approval, or the step-limit question: see [chi as a sub-agent](sub-agent.md#the-step-limit)), and the session keeps waiting: stderr gets the whole question (`waiting for an answer (approval): …`, its text, the numbered options, whether free text is allowed) and how to answer it (`chi answer ID --question QID --option N`, or `chi --attach ID`, the web); 4 `--timeout S` passed with the turn still running (it goes on; wait again); 1 the turn ended without a reply (canceled, failed or empty), the worker failed or vanished, or the session was stopped; 130 on Ctrl-C, which leaves the turn running (`still running: chi --attach ID`). There is no default timeout.
 - `--format json` (with `--wait`) prints one JSON object on stdout however the wait ends, for a script or a parent agent (see [chi as a sub-agent](sub-agent.md)): `{"status":"answered","session_id":…,"text":…}`; `{"status":"question",…,"question":{"id","kind","header","text","options","multi_select","allow_freeform","approval"},"answer_with":"chi answer ID --question QID --option N"}`, where `kind` is `question` (the model's), `hook` or `approval` (with the tool, command, cwd, rule, reason and offered scopes); `{"status":"running",…,"detail":…}` (exit 4, and on Ctrl-C); and `failed`, `canceled`, `no_answer`, `error`, `worker_gone` or `stopped` with a `detail` line (exit 1); `failed` adds `error_kind` and `retryable`, `canceled` adds `cancel_reason` and `stopped_by`, when known. A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
 - `--wait ID` with no message (no `-m`, nothing piped) sends nothing: it waits for the session's next reply and prints and exits as above. A running session is fine (that is the point), so after exit 3, 4 or 130 an agent waits again this way while the user answers in the web or `chi --attach`; the question pending when it starts doesn't count again. An idle session with no worker waits until something wakes one. With `--new`, or two ids, it is a usage error (exit 2).
-- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model and LLM context, so `--dir`, `--model` and `--llm-context*` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1.
+- `--continues ID` (with `--new`) starts the next link of that session's chain instead (see *Session chains*): in its folder, on its model, LLM context and thinking level, so `--dir`, `--model`, `--llm-context*` and `--thinking` are refused beside it; `ID` may be a prefix or `last:ID`, the chain's latest link. Without a message the new link starts idle; `--wait` then has nothing to wait for (a usage error). It prints `<full id>  started (continues 3fa2c1d0)`, with `; 2 delegates moved` inside the parentheses when open delegates moved to it; a refusal (continued already, naming the next link; an open delegate that can't move; a turn running) is `chi send: refused: …`, exit 1.
 - The 16 KiB cap applies: `git diff | chi send --new …` on a big diff is refused; name the branch in the message instead and let the session read it.
 - A session nobody attaches to stalls at its first question or guardrail ask until someone answers it (`chi answer`, the web, `chi --attach`), and its worker stays up meanwhile: it doesn't idle-exit while a question waits (`chi sessions list` shows it as `waiting`; `chi sessions stop ID` frees it). Otherwise it idle-exits after `session.idle_exit_minutes` like any worker. These are ordinary sessions: delete them like any other.
 

data/docs/testing.md

@@ -15,6 +15,10 @@ 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).
 
+The web specs run in plain node. One that renders with lit-html (`turn_view.js`, `vendor/lit-html.js`) needs a DOM:
+`import "./dom_shim.js";` as its first import (happy-dom, a devDependency only, never shipped; about 0.3 s per spec
+file that loads it). The shim's `htmlOf(nodes)` and `canon(html)` compare markup without lit's marker comments.
+
 ## Worktrees
 
 Each fix or feature gets its own worktree next to the main checkout:
@@ -70,7 +74,8 @@ a model that follows tool instructions: a small model may fail some of them.
 strategies (freed tokens, wrongly forgotten outputs, one-step re-reads, re-prefilled tokens; for `forget_outputs` a
 model's answers to chi's offer, with its call rate and notes). It is opt-in: the suite
 runs its code only on small synthetic sessions, never on yours. See
-[internals/llm-context-bench.md](internals/llm-context-bench.md).
+[internals/llm-context-bench.md](internals/llm-context-bench.md). `script/llm_context_live.rb` runs chi itself on
+real tasks under each strategy (needs a model; costs tokens): [internals/llm-context-live.md](internals/llm-context-live.md).
 
 ## The model notes report
 

data/lib/samagotchi/bootstrap/config_writer.rb

@@ -6,6 +6,7 @@ require "fileutils"
 require "ipaddr"
 require_relative "../atomic_file"
 require_relative "../config"
+require_relative "../yaml_lines"
 
 module Samagotchi
   module Bootstrap
@@ -15,6 +16,8 @@ module Samagotchi
     # comments), after a backup, and is checked by parsing it again: every
     # other key must be unchanged, or the backup goes back.
     class ConfigWriter
+      include YAMLLines
+
       class Error < StandardError
       end
 
@@ -33,7 +36,6 @@ module Samagotchi
       end
 
       HOSTS_LINE_RE = /\Ahosts:[ \t]*(#.*)?\z/
-      DEFAULT_INDENT = 2
       SERVER_TRANSPORTS = ConfigFile::VALID_TRANSPORTS_FOR_CONFIG
 
       # The host part of a name: localhost/127.x → local, another IP → lan,
@@ -157,9 +159,7 @@ module Samagotchi
         original = File.binread(@path).force_encoding(Encoding::UTF_8)
         return snippet(name, fields) unless data.is_a?(Hash) && !anchors?(original)
 
-        eol = original.include?("\r\n") ? "\r\n" : "\n"
-        lines = original.split(/(?<=\n)/)
-        lines[-1] = "#{lines[-1]}#{eol}" if lines.any? && !lines[-1].end_with?("\n")
+        lines, eol = lines_of(original)
         hosts_at = lines.index { |line| line.chomp.match?(HOSTS_LINE_RE) }
         return snippet(name, fields) if hosts_at.nil? && data.key?("hosts")
 
@@ -207,28 +207,14 @@ module Samagotchi
       # before trailing blank lines and comments shallower than an entry.
       # @return [index, entry indent, field indent step]
       def block_end(lines, hosts_at)
-        stop = hosts_at + 1
-        stop += 1 while stop < lines.length && inside_block?(lines[stop])
+        stop = block_stop(lines, hosts_at)
         children = lines[(hosts_at + 1)...stop].reject { |line| blank_or_comment?(line) }
         child = children.first ? indent(children.first) : DEFAULT_INDENT
         field = children.find { |line| indent(line) > child }
         step = field ? indent(field) - child : child
-        at = stop
-        at -= 1 while at > hosts_at + 1 && (lines[at - 1].strip.empty? || (comment?(lines[at - 1]) && indent(lines[at - 1]) < child))
-        [at, child, step]
-      end
-
-      def inside_block?(line)
-        return true if line.strip.empty?
-        return false if line.start_with?("---", "...")
-
-        line.start_with?(" ", "\t") || comment?(line)
+        [insert_at(lines, hosts_at, stop, child), child, step]
       end
 
-      def blank_or_comment?(line) = line.strip.empty? || comment?(line)
-      def comment?(line) = line.lstrip.start_with?("#")
-      def indent(line) = line[/\A */].length
-
       def entry_lines(name, fields, child, step)
         ["#{" " * child}#{name}:\n", *fields.map { |key, value| "#{" " * (child + step)}#{key}: #{scalar(value)}\n" }]
       end
@@ -316,23 +302,6 @@ module Samagotchi
         false
       end
 
-      def parse(text) = YAML.safe_load(text, permitted_classes: [], aliases: false)
-
-      # Anchors and aliases: chi's reader refuses aliases, and an insert
-      # can't know what an anchor shares.
-      def anchors?(text)
-        stack = [Psych.parse_stream(text)]
-        until stack.empty?
-          node = stack.pop
-          return true if node.is_a?(Psych::Nodes::Alias) || (node.respond_to?(:anchor) && node.anchor)
-
-          stack.concat(Array(node.children)) if node.respond_to?(:children)
-        end
-        false
-      rescue Psych::Exception
-        true
-      end
-
       def backup_path(real)
         stamp = @now.call.utc.strftime("%Y%m%dT%H%M%SZ")
         candidate = "#{real}.bak-#{stamp}"

data/lib/samagotchi/bridge/ring_buffer.rb

@@ -40,11 +40,6 @@ module Samagotchi
         end
       end
 
-      # Whether any buffered event could satisfy a reconnect from +from_seq+.
-      def has_any_after?(from_seq:)
-        @mutex.synchronize { @events.any? { |e| e[:seq] > from_seq } }
-      end
-
       # @return [Integer, nil] the highest seq buffered so far.
       def last_seq
         @mutex.synchronize { @events.last&.[](:seq) }

data/lib/samagotchi/bridge.rb

@@ -21,6 +21,7 @@ require_relative "session"
 require_relative "engine"
 require_relative "guardrails/parent_approvals"
 require_relative "session_commands"
+require_relative "queued_command"
 require_relative "steer"
 require_relative "image_store"
 require_relative "log"
@@ -62,10 +63,6 @@ module Samagotchi
     MAX_BODY_BYTES = 1_000_000
     # A request's deadline (see #handle_post_turn) that isn't epoch seconds.
     BAD_DEADLINE = [{ "Allow" => "POST" }, 400, { error: "bad_deadline", detail: "deadline must be epoch seconds" }].freeze
-    # A request's delivery (see #handle_post_turn) that isn't a string. An
-    # unknown string is not an error: it is the default, as a missing one is.
-    BAD_DELIVERY = [{ "Allow" => "POST" }, 400,
-                    { error: "bad_delivery", detail: "delivery must be a string" }].freeze
 
     # @param engine [Samagotchi::Engine] the owning engine (must already live
     #   in this process)
@@ -290,12 +287,11 @@ module Samagotchi
     #   basename): it runs once that file is taken (Worker#on_command)
     # @return [String] its command_id
     def queue_command(line, client_id: nil, card: false, after_file: nil)
-      command = { command_id: SecureRandom.uuid, client_id: client_id, line: line.to_s.strip }
       # A card's action (the step-limit question's answer): the UIs leave
       # its line out.
-      command[:card] = true if card
+      command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card)
       @engine.synchronize_events { queue_command_locked(command, after_file: after_file) }
-      command[:command_id]
+      command.command_id
     end
 
     private
@@ -726,18 +722,17 @@ module Samagotchi
     # :command_queued, unless +deadline+ has passed. Returns [headers,
     # status, body]: 202 with its command_id, or 408.
     def queue_command_request(session_id, line, client_id:, deadline: nil, card: false)
-      command = { command_id: SecureRandom.uuid, client_id: client_id, line: line }
       # A card's action: the UIs leave its line out (the card is the echo).
-      command[:card] = true if card
+      command = QueuedCommand.mint(line, client_id: client_id, card: card)
       queued = @engine.synchronize_events do
-        next false if expired?("command_expired", deadline, sid: session_id, client_id: command[:client_id])
+        next false if expired?("command_expired", deadline, sid: session_id, client_id: command.client_id)
 
         queue_command_locked(command)
         true
       end
       return deadline_passed("command") unless queued
 
-      [{}, 202, { status: "accepted", command_id: command[:command_id], session_id: @session_id }]
+      [{}, 202, { status: "accepted", command_id: command.command_id, session_id: @session_id }]
     end
 
     # With the event log held. +on_command+ answers what it did with the
@@ -752,7 +747,7 @@ module Samagotchi
               when :queue then { waits: "turn_end" }
               else {}
               end
-      @engine.announce(type: :command_queued, **command, **marks)
+      @engine.announce(type: :command_queued, **command.event_fields, **marks)
     end
 
     # A client asks the worker to exit now (`/exit` in the attached TUI), or
@@ -832,7 +827,9 @@ module Samagotchi
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
       raw_delivery = fetched(parsed, "delivery")
-      return BAD_DELIVERY unless raw_delivery.nil? || raw_delivery.is_a?(String)
+      if (refused = Delivery.refusal(raw_delivery))
+        return [{ "Allow" => "POST" }, 400, refused]
+      end
 
       delivery = Delivery.parse(raw_delivery)
 

data/lib/samagotchi/broadcast/recipients.rb

@@ -46,8 +46,7 @@ module Samagotchi
         return false unless (time(row[:updated_at]) || Time.at(0)) >= cutoff
 
         session = Session.summary_from_file(Session.session_file(row[:id], state_dir: state_dir))
-        last_turn = session&.last_turn
-        ended = last_turn.is_a?(Hash) ? time(last_turn["ended_at"] || last_turn[:ended_at]) : nil
+        ended = time(session&.last_turn&.ended_at)
         (ended || time(row[:updated_at])) >= cutoff
       end
       private_class_method :active_since?