samagotchi 0.21.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d794c2749a0f1293cb16d7afeb7e023f38dd8798532e4dcb2d0e9fcb575af1
-  data.tar.gz: 8ade3692c344214cc8cdbe90c1fb8539242639f7cbf8707c751a8d2b02f9548a
+  metadata.gz: 236e301c873eb2b96520aeeb3e7668e535f50174b1afb94d28a149cef161d418
+  data.tar.gz: adc3281cace9460e307abe5abc33719041863898e848f10b290d5d2d3e4c93d5
 SHA512:
-  metadata.gz: b3eb054e3b0dd3ded63ef8de4bfff37d8d36971dbe02107ac2e30114fadc12563807d4c7bdc4d3fdf8b801a7bd8250fcb5e73a547604b0feba7382abfdff0ee7
-  data.tar.gz: 168c3cfef2a37c4f5e3f6e2782b614a546f8307793e41af0efe200b2afa8d100b725889e5bb8fcf520fa7c2a0be18faa4cedb10a9ddf573bedac162a1404f133
+  metadata.gz: 6e97629a0a1459a7c9b403a495aea87807f4b2570421e369a56a01afd140830b8284e7d25a86132f14ebdab95275913f66caa8aea48680d23b507dec9d57b519
+  data.tar.gz: 284540411644a596492ad2d91c36eecb23f8eb435b95e06781e387b4933a6210680e15b6d79f035b1abd029b726aa9489bdee39816a9d509bfb7a1810b92b00e

data/CHANGELOG.md

@@ -8,6 +8,65 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-10-04
+
+### Changed
+
+- chi no longer strips the blank lines Splash before 1.2.0 put at the start of an answer (incoai/splash#254, fixed
+  in Splash 1.2.0): upgrade Splash with `brew upgrade incoai/tap/splash`.
+- Requests to OpenRouter send `max_tokens: 32768` (a request's own limit, as a recap's, still wins). OpenRouter
+  holds each running request's estimated cost against the balance, counting the output `max_tokens` allows (a
+  fixed per-request cap without one), so concurrent requests hit "would exceed your available credits given your
+  current in-flight requests" (402) sooner without a limit. `default.max_tokens` raises or lowers that limit.
+- `default.n_predict` is renamed `default.max_tokens` (env `SAMAGOTCHI_DEFAULT_MAX_TOKENS`, flag
+  `--default-max-tokens`), with no alias: an old `n_predict:` in config.yml warns as an unknown key. It now
+  limits chat turns on OpenAI-compatible hosts too, sent as `max_tokens` on any host; it was used only by native
+  hosts (where it is still sent as llama.cpp's `n_predict`).
+
+### Fixed
+
+- A Ctrl-C (or SIGTERM) while chi loads bundle hooks and plugins stops chi again; before, it was logged as a
+  failed hook and chi carried on. A hook's or plugin's own error, `exit` or syntax error is still only reported.
+- A continue turn that fails before it begins (its session save, say) asks the step-limit question again
+  instead of crashing the session's worker.
+- Native Gemma 4 prompts follow Gemma 4's chat template: turns end with `<turn|>` (not Gemma 3's
+  `<end_of_turn>`, which Gemma 4 reads as plain text), so the stop sequence matches; tool results stay
+  inside the model's turn as `response:NAME{value:…}` blocks, one per call; tools are declared in the
+  template's compact form at the end of the system turn; an answer's thought is dropped once the next
+  user turn starts; and thinking off prefills Gemma's empty thought channel.
+
+Update with `chi update`: btw 0.1.2, check-in 0.2.2, known-names 0.1.5, loop-guard 0.3.2, mcp 0.4.2, skills 0.1.6 and
+source-links 0.3.3 move (code style only, no behaviour change). If your config.yml has `default: n_predict:`, rename it
+to `max_tokens:`. Restart `chi web` and running sessions afterwards (`chi sessions restart ID`).
+
+## [0.22.0] - 2026-10-04
+
+### Added
+
+- Claude models on OpenAI-compatible hosts (OpenRouter) use Anthropic's prompt cache: chat requests mark the
+  system message and the last message with `cache_control`, so each step reads the earlier prompt from the
+  cache (about a tenth of the price) instead of paying for all of it again. The log line shows `cache=on`.
+
+### Changed
+
+- An HTTP 402 is no longer a "rejected the request" bad request. OpenRouter's "would exceed your available
+  credits given your current in-flight requests" (credit reserved by another running request) is retried like a
+  429, 20s apart (about 100s with the default `retry.max`), instead of failing the turn at once; any other 402
+  fails as `out of credits on host <name>: …; add credits, then send again`, with `error_kind` `credits`.
+- `chi answer --option Continue --text "…"` is accepted: the text joins the continued turn as a steer (marked as the parent agent's for `chi answer`), instead of being refused.
+- The Continue answer's text keeps its line breaks in the continued turn's steer, and it is dropped (logged
+  `steer_dropped why=not_begun`) when the continue turn fails before it begins or a typed `/continue no` answered
+  the offer first, instead of joining whatever turn ran next.
+- `chi answer --format json` says `"answered_here": false` when the question was no longer open (answered
+  elsewhere, or another one waits now): it still waits for what comes next, but the JSON no longer reads as if
+  the given answer went in.
+- `chi send --wait` and `chi answer` with `--format json` say why a turn stopped: a failed turn adds `error_kind`
+  (the provider error's kind, e.g. `credits`, `server`) and `retryable`, a canceled one `cancel_reason` (`user`,
+  `hook`, `ctrl_c`, `manual`) and `stopped_by` (the hook, e.g. `loop-guard`), when known. The session's
+  `last_turn` records them.
+
+Update with `chi update` (no bundle versions moved). Restart `chi web` and running sessions afterwards (`chi sessions restart ID`).
+
 ## [0.21.0] - 2026-10-04
 
 ### Added
@@ -1245,7 +1304,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.21.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.23.0...HEAD
+[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
 [0.21.0]: https://github.com/dm1try/samagotchi/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/dm1try/samagotchi/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/dm1try/samagotchi/compare/v0.18.1...v0.19.0

data/bin/chi

@@ -72,6 +72,7 @@ cli_overrides = {}
 # Strict kebab enforcement: --recap_base_url is unknown (OptionParser would otherwise accept _ as -)
 ARGV.each do |arg|
   next unless arg.start_with?("--") && arg.include?("_")
+
   # Allow --no-interrupt etc. already dash; underscore is always rejected for config flags
   # We check raw ARGV before OptionParser normalizes
   base = arg.split("=", 2).first
@@ -108,7 +109,7 @@ parser = OptionParser.new do |opts|
   opts.on("--[no-]shared", "Run the session in a background worker and attach to it, so `chi web` can share it (the default, config session.shared; with --resume: that session); --no-shared runs a plain in-process REPL") { |v| options[:shared] = v }
   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 }
+          "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("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
@@ -133,13 +134,14 @@ parser = OptionParser.new do |opts|
     next if entry.key == "web.port" # already handled as --port
     next if entry.key == "default.model" # alias --model above
     next if entry.key == "web.markdown" # handled below with explicit inverse flags
+
     case entry.type
     when :bool
       # --[no-]: a bool that defaults to on is only useful switched off.
-      opts.on("--[no-]#{entry.cli_flag.delete_prefix('--')}", "Set #{entry.key} (bool, default #{entry.default ? 'on' : 'off'}) [env #{entry.env_key}]") { |v| cli_overrides[entry.key] = v }
+      opts.on("--[no-]#{entry.cli_flag.delete_prefix("--")}", "Set #{entry.key} (bool, default #{entry.default ? "on" : "off"}) [env #{entry.env_key}]") { |v| cli_overrides[entry.key] = v }
     when :integer, :float, :string, :enum
       desc = "Set #{entry.key} [env #{entry.env_key}]"
-      desc += " (#{entry.enum_values.join('|')})" if entry.type == :enum
+      desc += " (#{entry.enum_values.join("|")})" if entry.type == :enum
       desc += " (#{value_hints[entry.key]})" if value_hints.key?(entry.key)
       desc += "; only without a hosts: config" if %w[server.host server.port].include?(entry.key)
       desc += "; hosts: entries without a transport use it" if entry.key == "server.transport"
@@ -257,7 +259,10 @@ if options[:memories] || options[:muted]
   end
   memory_exists = lambda do |raw|
     scope, name = raw.split("/", 2)
-    scope, name = nil, raw unless name && Samagotchi::Tools::VALID_SCOPES.include?(scope)
+    unless name && Samagotchi::Tools::VALID_SCOPES.include?(scope)
+      scope = nil
+      name = raw
+    end
     !Samagotchi::Tools::MemoryRead.call(name, scope: scope).start_with?("Error:")
   end
   cli_memories = (options[:memories] || []).flat_map { |m| m.split(",") }.map(&:strip).reject(&:empty?)

data/docs/architecture.md

@@ -392,8 +392,9 @@ output) and cancel. Cancel closes the in-flight socket from the
 `CancellationController` listener, so it works on any thread.
 
 **Errors.** A failed request raises an `LLM::ProviderError` of one kind:
-`ConnectionError` (`RetryExhausted`), `RateLimited`, `ServerError`, `AuthError`,
-`BadRequest` (`context_overflow?`) or `ProtocolError`. Engine keeps the turn's
+`ConnectionError` (`RetryExhausted`), `RateLimited` (`CreditsHeld`: a 402 about
+credit held by in-flight requests, retried after 20 s), `OutOfCredits` (any other
+402), `ServerError`, `AuthError`, `BadRequest` (`context_overflow?`) or `ProtocolError`. Engine keeps the turn's
 conversation (the prompt plus completed tool iterations) and emits
 `:turn_failed` with `error_kind:`, `retryable:`, `host:` and a one-line
 `summary:`, which the REPL, the attached TUI and the web show.

data/docs/configuration.md

@@ -308,8 +308,8 @@ prompt profile (see "Prompt profile" below). How the selector reaches the reques
   (`model: Field required`) without it, so samagotchi forwards the selector
   resolved to the exact id listed in the server's `/v1/models` — matched by exact
   (case-insensitive) first, then substring, then passed through unchanged. That
-  resolved id is usually prefixed (e.g. `mlx-community--gemma-3-4b-it-4bit`), so a
-  short selector such as `gemma-3-4b-it-4bit` is what you set in
+  resolved id is usually prefixed (e.g. `mlx-community--gemma-4-e4b-it-4bit`), so a
+  short selector such as `gemma-4-e4b-it-4bit` is what you set in
   `default.model`. An unknown selector passes through raw and oMLX 404s,
   listing its available models; if `/v1/models` is unreachable, samagotchi falls
   back to the raw selector and lets the server decide (its own 400/404). Either
@@ -513,6 +513,12 @@ Every chat request carries the session's id as a `Session-Id` header (next to `U
 gateway that spreads requests over several providers can key on it to keep one conversation on one provider, so
 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
+log's line shows `cache=on`. Nothing to configure. A provider behind a gateway may still not cache: check the
+cached tokens in `/stats`.
+
 ## Llama Model Routing
 
 To explicitly route requests to a named model in llama.cpp, set:
@@ -529,7 +535,7 @@ With several `hosts:`, `host:model` (or an alias naming a host) pins the host.
 An unqualified model name goes to the default host when its `/models` list has
 that exact id, else to the first host in `hosts:` order whose list has it, else
 to the default host. Only exact ids count, never a substring: `/model gemma` on
-a box that lists `gemma-3-12b` needs `box:gemma` or the exact id. The lists are
+a box that lists `gemma-4-26b` needs `box:gemma` or the exact id. The lists are
 known only after `/models` ran (nothing is fetched before the first turn), so
 until then an unqualified name goes to the default host; use `host:model` to pin
 one. A **remote** host (an `https` url or a public address; see "Remote or local") keeps its model
@@ -607,6 +613,9 @@ Transient network failures are retried automatically with exponential backoff.
 - Retry scope: transient network errors (timeouts, reset connections, EOF/socket reachability failures),
   HTTP 429 and HTTP 500/502/503/504/529. A `Retry-After` header replaces the backoff delay; one longer than
   60s is not waited out and the error is reported instead.
+- 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.
 - 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.
@@ -653,6 +662,8 @@ 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 |
 | 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 |
@@ -826,7 +837,7 @@ described in their own sections.
 |---|---|---|---|
 | `default.model` | (required) | `--model` | The model a new session starts with; `host:model` pins a host. |
 | `default.input` | none | | Text pre-filled at the first prompt (a trailing space is kept); `--no-default-input` skips it. See [CLI](cli.md). |
-| `default.n_predict` | server's | yes | Most tokens one generation may produce (native hosts). |
+| `default.max_tokens` | server's | yes | Most tokens one generation may produce (`n_predict` on a native llama.cpp host; OpenRouter: 32768 when unset). |
 | `model.profile` | none | `--profile` | Prompt profile for every model (`qwen36`, `gemma4`); env and CLI only. See "Prompt profile". |
 | `server.transport` | `llama_cpp` | yes | `llama_cpp`, `mlx` or `omlx`; see "Model Server Transport". |
 | `server.host` | `localhost` | yes | The model server when there is no `hosts:` map. |

data/docs/releasing.md

@@ -52,7 +52,7 @@ as the GitHub release body.
 | `rake bundles:check` | Sha lines match; a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: raise it if the change uses anything new. |
 | `rake release:draft_changelog` | A draft Unreleased section from the commit subjects since the last tag, grouped. Stdout only. |
 | `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG. No commit. |
-| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, `bundles:check`, rspec + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
+| `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, `bundles:check`, `rake lint` (RuboCop), rspec + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |
 | `rake release:notes[X.Y.Z]` | Prints the CHANGELOG section (default: the current VERSION). |
 
 ## Runbook

data/docs/sessions.md

@@ -172,7 +172,7 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 - `--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). A failure before the wait (no such session, a busy one) is `error` too. A usage error (exit 2) prints no JSON.
+- `--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).
 - 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/sub-agent.md

@@ -37,7 +37,7 @@ Exit codes, both commands:
 | 0 | `not_continued` | (`chi answer`) a Stop answered the step-limit question; the turn's work so far stays |
 | 3 | `question` | chi waits for an answer: `question`, `answer_with` |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
-| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it) |
+| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web or `chi sessions stop`; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -59,8 +59,11 @@ A turn that runs out of steps (`turn.max_iterations`, default 100) before it
 answers waits as a question of kind `continue` (`"limit": 100`, options
 `Continue` and `Stop`). `answer_with` continues it:
 `chi answer ID --question QID --option Continue`, and the continued turn's
-reply (or its next question) comes back on that same wait. To stop it:
-`--option Stop`, with `--text "why"` for the model (Continue takes no text);
+reply (or its next question) comes back on that same wait. With
+`--text "…"` the text joins the continued turn as a steer (as a `chi send -m`
+into a running turn does, marked as coming from the parent agent), so one
+answer continues and redirects it. To stop it:
+`--option Stop`, with `--text "why"` for the model;
 that wait ends with `status: not_continued`, exit 0, and the turn's work so far
 stays in the session. A message instead (`chi send ID -m "…"`) drops the
 question and starts a new turn. It can't be dismissed.
@@ -132,7 +135,9 @@ answers from any local process.
 - `chi send --wait ID` with no message waits past a question already reported
   (the step-limit question too), until someone answers it.
 - An answer to a question that is no longer open (you answered it in the web
-  first) isn't sent; `chi answer` says so and waits for what comes next.
+  first) isn't sent; `chi answer` says so and waits for what comes next. Its
+  JSON then has `"answered_here": false` (absent when the answer went in), so
+  an `answered` status there is someone else's answer's turn, not yours.
 - `chi send --wait` and `chi answer` don't read stdin unless it's a pipe or a
   file. Agent shells usually pass `/dev/null`, which is fine.
 
@@ -165,7 +170,8 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
 - `status: running` (exit 4): still working. Wait again:
   `chi send --wait --format json --timeout 500 <session_id>`.
 - `question.kind: continue`: chi ran out of steps before it answered. If it is
-  getting somewhere, continue it (`answer_with`, `--option Continue`); if not,
+  getting somewhere, continue it (`answer_with`, `--option Continue`, with
+  `--text "…"` to steer it on the way); if not,
   stop it (`--option Stop --text "why"`, exit 0, status `not_continued`) or send
   a narrower follow-up instead. Ask your user when unsure.
 - Anything else (exit 1): report `detail` to your user. `chi --attach <session_id>`

data/docs/testing.md

@@ -4,8 +4,14 @@
 bundle exec parallel_rspec -n 8   # Ruby specs, in parallel (or plain: bundle exec rspec)
 npm test                          # web frontend specs
 npm run e2e                       # web UI happy paths in Chromium, fake model (once: npx playwright install chromium)
+bundle exec rake lint             # RuboCop: no offenses (CI runs it)
 ```
 
+Run `bundle exec rubocop -a` on the files you changed before committing: every enabled style cop follows the
+code's own style and has a safe autocorrect, so `-a` fixes them. What it leaves is a Lint finding (a possible
+bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:disable Cop -- why`).
+`.rubocop.yml` says why each cop that is off is off.
+
 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).
 

data/lib/samagotchi/answer_command.rb

@@ -34,7 +34,8 @@ module Samagotchi
         with it), then waits for what comes next and prints it as chi send
         --wait does.
         --question QID  the question's id (chi send --wait prints it); a
-                        question no longer open is not answered
+                        question no longer open is not answered (the JSON
+                        says "answered_here": false)
         --option N|LABEL
                         an option, by number (1-based) or label; repeat
                         on a multi-select question
@@ -47,7 +48,8 @@ module Samagotchi
         An approval (a guardrail's ask) can be denied here: deny it, and
         tell your user; allowing it is the user's. With
         guardrails.parent_approvals: once, "Allow once" is let through.
-        A step-limit question (kind continue): --option Continue, or
+        A step-limit question (kind continue): --option Continue [--text
+        STEER] (the text joins the continued turn as a steer), or
         --option Stop [--text WHY] (exit 0, status not_continued); it
         can't be dismissed.
         Exit: 0 answered, 1 failed, refused or the worker is gone, 2
@@ -82,12 +84,14 @@ module Samagotchi
       options = parsed.options
       return usage_error("give one session id") unless parsed.args.size == 1
       return usage_error("--question QID is required (chi send --wait prints it)") if options[:question].to_s.strip.empty?
+
       if options[:dismiss]
         return usage_error("--dismiss takes no --option or --text") if !options[:options].empty? || options[:text]
       elsif options[:options].empty? && options[:text].nil?
         return usage_error("nothing to answer with: --option, --text or --dismiss")
       end
       return usage_error("--format takes text or json") if options[:format] && !FORMATS.include?(options[:format])
+
       if options[:timeout]
         options[:timeout] = Float(options[:timeout], exception: false)
         return usage_error("--timeout takes seconds") unless options[:timeout]&.positive?
@@ -153,7 +157,7 @@ module Samagotchi
     # (Guardrails::ParentApprovals, with this process's config.yml). A
     # Deny, text alone or a dismissal always passes: each one denies. The
     # worker checks it again with its own config.
-    def approval_refusal(pending, selected, id)
+    def approval_refusal(pending, selected, _id)
       offered = Array(pending[:options]).map(&:to_s)
       indices = selected.map { |label| offered.index(label) }
       reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: Guardrails::ParentApprovals.setting)
@@ -168,7 +172,7 @@ module Samagotchi
 
     # A step-limit question can't be left unanswered: the turn waits on it.
     def not_dismissable(pending)
-      "the step-limit question can't be dismissed: answer #{Array(pending[:options]).join(' or ')} " \
+      "the step-limit question can't be dismissed: answer #{Array(pending[:options]).join(" or ")} " \
         "(--option Stop --text WHY stops it)"
     end
 
@@ -214,9 +218,11 @@ module Samagotchi
     end
 
     # The question was answered elsewhere (the web first), or another one
-    # waits now: said, then what comes next is waited for.
+    # waits now: said, then what comes next is waited for (the JSON says
+    # answered_here: false).
     # @return [nil]
     def not_open(qid)
+      @answered_here = false
       error_line("#{command_name}: question #{qid} is no longer open; not answered here, waiting for what comes next")
       nil
     end

data/lib/samagotchi/bootstrap/config_writer.rb

@@ -15,7 +15,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
-      Error = Class.new(StandardError)
+      class Error < StandardError
+      end
 
       # kind: :new (a fresh file), :appended, :exists (the host is already
       #   there as +existing+; nothing written), :snippet (a file chi can't

data/lib/samagotchi/bootstrap/probe.rb

@@ -18,7 +18,7 @@ module Samagotchi
     # port answers at once instead of after chi's usual backoff.
     class Probe
       # The ports `chi bootstrap` with no target tries on localhost.
-      LOCAL_PORTS = { 8080 => "llama.cpp", 11434 => "Ollama", 1234 => "LM Studio", 8000 => "vLLM" }.freeze
+      LOCAL_PORTS = { 8080 => "llama.cpp", 11_434 => "Ollama", 1234 => "LM Studio", 8000 => "vLLM" }.freeze
       DEFAULT_PORT = 8080
       # Connect and read seconds for /props and /v1/models: a remote https
       # handshake needs more than Client#server_props' 1 s / 2 s.

data/lib/samagotchi/bootstrap_command.rb

@@ -193,7 +193,7 @@ module Samagotchi
     def describe(result)
       if result.native?
         build = result.props["build_info"].to_s
-        @stdout.puts("found: llama.cpp at #{result.candidate.root}#{build.empty? ? "" : " (build #{build})"}")
+        @stdout.puts("found: llama.cpp at #{result.candidate.root}#{" (build #{build})" unless build.empty?}")
       else
         @stdout.puts("found: an OpenAI-compatible API at #{result.candidate.base}")
       end
@@ -406,7 +406,7 @@ module Samagotchi
         shown.first(PICK_SHOWN).each_with_index { |item, i| @stdout.puts(format("  %2d) %s", i + 1, item)) }
         more = shown.size - PICK_SHOWN
         @stdout.puts("  … #{more} more: type part of a name to narrow the list") if more.positive?
-        @stdout.print("#{noun} (number#{items.size > PICK_SHOWN ? " or text" : ""}, empty to stop): ")
+        @stdout.print("#{noun} (number#{" or text" if items.size > PICK_SHOWN}, empty to stop): ")
         answer = @stdin.gets.to_s.strip
         return nil if answer.empty?
 

data/lib/samagotchi/bridge/bounded_queue.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "thread"
-
 module Samagotchi
   class Bridge
     # A thread-safe bounded FIFO used to decouple the turn thread (which

data/lib/samagotchi/bridge/sse_writer.rb

@@ -217,8 +217,6 @@ module Samagotchi
           "\r\n"
         )
         io.flush
-      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
-        raise
       end
 
       # Serialise one SSE event: an `id:` line (the replay cursor), an optional
@@ -232,15 +230,11 @@ module Samagotchi
         JSON.generate(data).each_line { |line| lines << "data: #{line.chomp}" }
         io.write(lines.join("\r\n") + "\r\n\r\n")
         io.flush
-      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
-        raise
       end
 
       def write_heartbeat(io)
         io.write(": ping\r\n\r\n")
         io.flush
-      rescue Errno::EPIPE, Errno::ECONNRESET, IOError
-        raise
       end
 
       # Emit a control frame carrying the current snapshot so a client that

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -230,8 +230,8 @@ module Samagotchi
         if Events::TURN_END.include?(type)
           @turn = nil
           @merged_origins = []
-        else
-          @turn[:event_seq] = event[:event_seq] if event[:event_seq]
+        elsif event[:event_seq]
+          @turn[:event_seq] = event[:event_seq]
         end
       end
 

data/lib/samagotchi/bridge.rb

@@ -481,7 +481,7 @@ module Samagotchi
       %w[GET snapshot] => :handle_snapshot,
       %w[GET tail] => :handle_tail
     }.freeze
-    ROUTE_PATH = %r|\A/session/([^/]+)/(.+)\z|u
+    ROUTE_PATH = %r{\A/session/([^/]+)/(.+)\z}u
 
     # @return [Array(Symbol, String), nil] the handler and the session id, or
     #   nil when no route takes this method and path
@@ -509,7 +509,7 @@ module Samagotchi
     # /recap in an attached TUI: the saved recap, and a new one asked for at
     # once (it arrives as :recap_ready). Answers mid-turn too.
     # 200 {enabled:, saved:, request:, min_user_turns:}. Returns [headers, status, body].
-    def handle_recap(session_id, _body = nil)
+    def handle_recap(_session_id, _body = nil)
       recap = @engine.recap
       return [{}, 200, { enabled: false }] unless recap
 
@@ -519,7 +519,7 @@ module Samagotchi
 
     # Cancel the active turn on this session's engine, if any.
     # Returns [headers, status, body].
-    def handle_cancel(session_id, body)
+    def handle_cancel(_session_id, body)
       # Optional reason from JSON body
       reason = :manual
       if body && !body.strip.empty?
@@ -546,6 +546,7 @@ module Samagotchi
       unless parsed.is_a?(Hash)
         return [{ "Allow" => "POST" }, 400, { error: "invalid_json" }]
       end
+
       qid = fetched(parsed, "id")
       selected = fetched(parsed, "selected")
       freeform = fetched(parsed, "freeform")
@@ -556,6 +557,7 @@ module Samagotchi
       if qid.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400, { error: "missing_fields", detail: "id required" }]
       end
+
       deadline = fetched(parsed, "deadline")
       return BAD_DEADLINE unless deadline_valid?(deadline)
       return deadline_passed("answer") if expired?("answer_expired", deadline, sid: session_id, id: qid)
@@ -722,6 +724,7 @@ module Samagotchi
         @on_exit_request.call(client_id, **options)
       end
       return deadline_passed("exit request") if reason == :expired
+
       if reason.nil?
         return [{}, 200, { status: "restarting", session_id: @session_id }] if restart
 
@@ -745,7 +748,7 @@ module Samagotchi
     # dropped with 408 deadline_passed. It is checked with the event log held,
     # right before the write, so nothing that holds the log (an exit check)
     # can delay an accepted turn past it. No deadline (an older client): taken.
-    def handle_post_turn(session_id, body)
+    def handle_post_turn(_session_id, body)
       parsed = parse_json(body)
       unless parsed.is_a?(Hash)
         return [{ "Allow" => "POST" }, 400, { error: "invalid_json" }]
@@ -801,7 +804,7 @@ module Samagotchi
 
     # Read-only snapshot surface. AC #4: too-old reconnects re-derive state
     # from here.
-    def handle_state(session_id, _body = nil)
+    def handle_state(_session_id, _body = nil)
       state = @engine.session_state_snapshot
       [{}, 200, { session_id: @session_id, session_state_snapshot: state.merge(event_id: event_id(state[:event_seq])) }]
     end
@@ -809,7 +812,7 @@ module Samagotchi
     # /stats for an attached client: the metrics, with the window and prompt
     # profile asked from the server when no turn has reported them yet (so,
     # unlike /state, it may wait on one short /props GET).
-    def handle_stats(session_id, _body = nil)
+    def handle_stats(_session_id, _body = nil)
       [{}, 200, { session_id: @session_id, metrics: @engine.stats_snapshot }]
     end
 
@@ -817,7 +820,7 @@ module Samagotchi
     # the messages elsewhere (the web server strips and formats them): it then
     # streams from the snapshot's event_seq, and the ring replays what came
     # after (or the stream resets). Returns [headers, status, body].
-    def handle_snapshot(session_id, _body = nil)
+    def handle_snapshot(_session_id, _body = nil)
       [{}, 200, snapshot_frame]
     end
 
@@ -825,7 +828,7 @@ module Samagotchi
     # that turn's answer (a queued turn's page re-reads late). The one
     # handler that gets the query (#dispatch); an older worker's route
     # ignores it and sends the newest answer.
-    def handle_tail(session_id, _body = nil, query = nil)
+    def handle_tail(_session_id, _body = nil, query = nil)
       turn_id = query && URI.decode_www_form(query).to_h["turn_id"].to_s
       [{}, 200, tail_frame(turn_id: turn_id.to_s.empty? ? nil : turn_id)]
     rescue ArgumentError
@@ -885,7 +888,7 @@ module Samagotchi
       headers = {}
       content_length = 0
       while (line = io.gets)
-        break if line == "\r\n" || line == "\n"
+        break if ["\r\n", "\n"].include?(line)
 
         key, value = line.split(":", 2)
         next unless key

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -47,7 +47,7 @@ module Samagotchi
         @client = client
         @rediscover = rediscover
         params = []
-        params << ["snapshot", "1"] if snapshot
+        params << %w[snapshot 1] if snapshot
         params << ["client_id", client_id] if client_id
         @query = params.empty? ? "" : "?#{URI.encode_www_form(params)}"
         @reconnect_delays = reconnect_delays
@@ -138,7 +138,7 @@ module Samagotchi
             @on_event.call(event)
           end
         end
-      rescue EOFError, IOError, SystemCallError
+      rescue IOError, SystemCallError # EOFError is an IOError
         yielded ? :events : :unreachable
       ensure
         detach(sock)

data/lib/samagotchi/bridge_client.rb

@@ -287,7 +287,7 @@ module Samagotchi
           end
           chunk = sock.readpartial(4096)
           yield chunk
-        rescue EOFError, IOError, Errno::ECONNRESET, Errno::ECONNREFUSED
+        rescue IOError, Errno::ECONNRESET, Errno::ECONNREFUSED # EOFError is an IOError
           break
         end
       ensure