samagotchi 0.44.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 684d8e5c169b4ce5df4cd21c4c46d0ef8524230e530d3e90ec2076f5b674e905
-  data.tar.gz: 54dbaf8bd2ad38b78e16aca155414748491912bdaebe1069f128e6182df7bfe5
+  metadata.gz: 0fb03f917133e78236dfb0bf16eae6c21b00ec2fb3720501d6c1982aeb9dc220
+  data.tar.gz: b3edff20b87e1f954c6079cd0315ab64559a5814f9a64e92e215fedc745a2778
 SHA512:
-  metadata.gz: de459298c279f571db785d374e1752a58060d26a13c4f7a6d22f8c4e4a5c82acbcffecd5784712eda405908cc3a8fd7bf1526952878b3791017088ebb62f120e
-  data.tar.gz: a99cf35d53b0a9fb7b3ed568a73d3383252ba334e4c8efd50efd9d97ded3cb716432fd51ee069e066ce3d21d137f1fadf49e20f2b99e9a769e430c8274278a64
+  metadata.gz: 96b8d90741656cae236454b5f1b56f49e77ad1a511eb81cdc31594b311031b57363993091ae0df70cf78c6f346a2b6b867896b53e0093ae2e59671146cd12eb6
+  data.tar.gz: 6041ee413db16da9147f763f83cfabcf91e0c62ea95380fa8ae454aab9e242b646501fafdd2ed5071008b4b218ad740c585517ee1e3cd0fb84531cb36a43d59d

data/CHANGELOG.md

@@ -8,6 +8,123 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.46.0] - 2026-10-09
+
+### Added
+
+- `hosts.<name>.models:` declares the model ids a host serves whatever its `/v1/models` lists (a gateway's
+  round-robin ids), as a map of ids or a plain list. A declared `host:id` is never warned about or re-listed at
+  `chi send --new` and delegate spawns, and a bare id routes to its declaring host as if listed, before any
+  `/models` and in workers too. Two hosts declaring one id warn at start. See "Models a host serves but doesn't
+  list" in [docs/configuration.md](docs/configuration.md).
+- Declared `hosts.<name>.models` ids show first under their host in `/models` (as `rr/x (config)`, outside the 20
+  per host, also on a host that lists nothing), `chi models` (plain names; `--format json` adds `configured: true`)
+  and `GET /api/models` (`configured: true`). A host that doesn't answer shows none of them.
+- `hosts.<name>.models.<id>.price: {input, output, cache_read?, cache_write?}` (USD per 1M tokens) estimates the
+  cost of a generation whose provider reports none, or reports 0. A reported non-zero cost always wins. The estimate
+  is saved apart (`cost_estimate` per turn, `cost_estimate_sum` in the totals). See "Prices" in
+  [docs/configuration.md](docs/configuration.md).
+- `hosts.<name>.models.<id>.served: [ids]` (or `any`) names the models a gateway may answer a round-robin id with.
+  Those are no longer marked as served by another model (the web's `⚠`, the status line's `(served; asked …)`,
+  `/model`'s `served:`, `/stats`' "(asked for …)"); one it doesn't name still is.
+- An estimated cost shows with `~`: `/stats` (`$0.42 reported + ~$0.12 from hosts.<name>.models prices`) and the
+  ctx tooltip on the info bar and the session cards (`cost: ~$0.54 ($0.42 reported, ~$0.12 estimated)`).
+- The web model picker lists a host's declared ids first under it, noted `config` (the default model keeps
+  `default`), with `served by config (hosts.<name>.models)` in the row's tooltip.
+
+### Fixed
+
+- A chat generation whose stream dropped mid-answer (a read timeout or a reset after deltas had shown) failed the
+  whole turn: the chat loop now drops the partial reply and asks again for the same step, from the same
+  conversation, at most twice, reporting each ask-again as `generation_retrying`, as the transport's retries do.
+  A cancel, a provider error, a first-token timeout and a connection refused still fail as before, and a step whose
+  retries run out fails the turn with the same error. Each ask-again waits the transport's backoff (`retry.*`),
+  which a cancel cuts short, and `retry.max` caps the asks-again (`retry.max: 0` turns them off). Its
+  `generation_retrying` carries `restarted: true`: the web's live step, the TUI's activity line, a reload in the
+  middle of the turn and the stream hooks drop the partial reply, so the answer shows once.
+- `task_stop` could signal an unrelated process group whose leader reused a finished task's pid. A task now records
+  its process's start time, and a pid that started at another time is not signalled (the task ends as failed).
+- A delegate's report merged into a reminder or continue turn was lost when the turn failed past its loop (the
+  turn's own end, say): the turn kept only its start, yet the report counted as read. Its ring now stays, and the
+  next turn brings it.
+- A delegate wait that relayed a child's approval ran to its timeout when the child ended its turn with no reply
+  while the answer was being posted; it now ends there.
+- Chi Helper: a send that ended after the panel was reopened wrote its "sent"/"failed" line into the new panel, and
+  a success could close it; like a broadcast, it now leaves the new open alone.
+- `chi -p … --non-interactive` hung forever when the model asked a question (`ask_user_question`) while its stdin
+  was a pipe that stayed open (`sleep 30 | chi -p …`, a parent holding stdin): it waited for an answer line. Nobody
+  can answer there, as for an approval: the question is dismissed at once (one line on stderr), the model finishes
+  its reply, and stdin is never read. Piped answers without `--non-interactive` (`printf '2\n' | chi --no-shared -p
+  …`) work as before.
+
+## [0.45.0] - 2026-10-08
+
+### Added
+
+- Plugins: `ctx.fork?` says whether the session is a fork (`ctx.sessions.fork`: it has a parent and isn't a
+  delegate child). See [docs/plugins.md](docs/plugins.md).
+
+### Changed
+
+- Commands sent while a turn runs no longer all answer `busy`. Those that only show something answer at once
+  (`/models`, and `/model`, `/llm-context` and `/guardrails` alone). Those that change something (`/model X`,
+  `/llm-context strategy …`, `/guardrails revoke N`) and `!cmd` run after the turn, in the order sent with the
+  prompts: the terminals say `(queued: runs after this turn)`, the web draws the command's bubble dashed until it
+  ran (after a reload too), and the web's `llm ctx` chip can Set mid-turn. A `!cmd` waiting after a canceled or
+  failed turn is dropped, so the turn's `!rollback` stays open, and one still waiting when the worker stops is
+  answered `dropped`. `!rollback` and `/continue` stay refused (`busy: Ctrl-C the turn first, then !rollback`).
+  `/archive` typed during a turn archives once it ends, in the REPL and an attached terminal. `chi --attach ID
+  --model X` on a running turn waits for its end. See "Typing during a turn" in [docs/cli.md](docs/cli.md).
+
+### Fixed
+
+- `/stats`, `/model` and the web named no model notes for a fresh session (a REPL's before the first turn, a new
+  web or worker session), though its first turn's prompt carries them; they now name the notes that prompt will
+  load. A session whose prompt carried none keeps saying so.
+- `chi self`'s `model notes` row resolved a note's model overlay from the process's `XDG_CONFIG_HOME` while it
+  read the note itself from the env it was given, so the row could count no overlay (or another config's); it now
+  reads both from the same env, and passes the fallback key the session's prompt does, so a model typed as an
+  alias whose note overlay is keyed by the alias's name shows it — the row agrees with the notes the session's prompt loads.
+- In the plain REPL a session command typed at a continue offer (other than `/continue`) was read as an invalid
+  answer and lost; it now runs and the offer stays open, as in a worker.
+- A session command sent as a message behind queued prompts (`chi send -m "/model x"` after `chi send -m "task"`)
+  could be answered `busy` by the next queued prompt's turn instead of running before it; it now runs once its
+  own message's turn comes.
+- The web's ctx meter under an LLM context budget smaller than the window (`llm_context.budget_tokens`) read the
+  percentage of the window after a reload (`ctx 12%`) where live it read the budget's (`ctx 25%`); it now counts
+  against the budget both ways, as the `[CONTEXT: …]` line and the status line do, and a generation's final counts
+  no longer flip it back to the window mid-turn. The ctx tooltip's context line says so: `context: ~16.0k of the
+  64.0k budget, 128.0k window (server)`.
+- The web's strip of latest sessions, back from All sessions with the pointer still on it, could keep a waiting
+  family behind other cards until the pointer moved: an update that came while All sessions opened was drawn in
+  the order held for the pointer.
+- github-pr 0.3.1: in `auto_attach: offer` mode a forked session (`/btw keep`, a plugin's fork) now gets its
+  `first_prompt` row in `offers.ndjson` (its first prompt after the conversation it started from), as a new
+  session does; it got none.
+- A resumed or attached session (`chi --resume`, `chi --attach`) drew a turn that failed with its steps kept as its
+  prompt and tool rows followed by an earlier step's text, as if that were the answer; the join now draws the line
+  the live view left (`✕ turn failed: HTTP 500: boom · 2.0s`, then `  partial progress kept; !rollback restores the
+  pre-turn state` when the steps stayed) after the rows, with no answer text, as the web does.
+- The web's stage trail: when the ✂ row of an applied LLM context edit landed in its step inside the
+  closed cloud it was out of sight and, unlike a hook's notice, flashed nothing. It now flashes in the
+  trail for a few seconds, as its row reads (`✂ forgot 2 outputs, stubbed 1 stale read · frees ~4.1k
+  tokens (paid off)`), as a hook notice does.
+- The web's stage trail: when a message cut a generation that was still thinking, its row (`↪ cut in
+  for your message`, `… a message sent with chi send`, `… the parent agent's message`) landed in its
+  step inside the closed cloud and, out of sight, flashed nothing. It now flashes in the trail for a
+  few seconds, as its row reads, as the ✂ row and a hook notice do.
+- `chi send --new --model` and `delegate` warned `host 'h' doesn't list model 'x'` for an id the host serves, when
+  the on-disk model list still named the model a one-model server served before it was reloaded: a saved list
+  older than 10 minutes that misses the id now re-lists that one host once (bounded at 5 s) and judges again
+  against what it lists now, saving the fresh ids. A list from the last 10 minutes is taken at its word, so a host
+  that serves ids it never lists (a gateway's round-robin aliases) is not asked on every launch; a re-list that
+  fails, times out or lists nothing warns from the saved list.
+- The session lists' `ctx %` (the web's session cards, `chi sessions list` and its `ctx 12%` column, the
+  `list_sessions` tool's `ctx_pct`) and `/stats`' `context used:` still divided by the window when the session's
+  LLM context budget (`llm_context.budget_tokens`) was smaller, where the live meter counts the smaller of the
+  two; they now count the same way, and `/stats` says so: `context used:     16000 tokens (25.0% of the 64000
+  budget)`.
+
 ## [0.44.0] - 2026-10-08
 
 ### Added
@@ -2026,7 +2143,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.44.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.46.0...HEAD
+[0.46.0]: https://github.com/dm1try/samagotchi/compare/v0.45.0...v0.46.0
+[0.45.0]: https://github.com/dm1try/samagotchi/compare/v0.44.0...v0.45.0
 [0.44.0]: https://github.com/dm1try/samagotchi/compare/v0.43.0...v0.44.0
 [0.43.0]: https://github.com/dm1try/samagotchi/compare/v0.42.0...v0.43.0
 [0.42.0]: https://github.com/dm1try/samagotchi/compare/v0.41.0...v0.42.0

data/docs/architecture.md

@@ -287,7 +287,8 @@ 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, cache-write and reasoning sums, the cost, the decode time and tokens
+The totals' `tokens` block adds the cached, cache-write and reasoning sums, the reported cost (`cost_sum`) and the
+estimated one (`cost_estimate_sum`, from `hosts.<name>.models` prices; 0 for none), 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), its own prompt-cache

data/docs/cli.md

@@ -85,12 +85,15 @@ small -> box:gemma-small         # an alias and the ref it resolves to
 $ chi models qwen                # only the names containing "qwen" (any case)
 ```
 
+- A host's ids declared under `hosts.<name>.models` (see
+  [configuration](configuration.md#models-a-host-serves-but-doesnt-list)) come first under that host, listed or not,
+  as plain names like any other.
 - A default-host id is bare, except one with a `:` (`qwen3:8b`), which is written `<host>:qwen3:8b` so it can't
   read as a host name. An id that an alias of the same name hides is left out.
 - Each run lists anew (no cache); `--timeout S` caps the wait for the hosts (default 4 s). A host that fails or doesn't
   answer in time is noted on stderr (`chi models: box: no answer in 4 s`).
 - `--format json` prints one object: `default` (and `default_typed` when it was set as an alias), `default_host`,
-  `models` (`name`, `host`, `id`), `aliases` (`name`, `ref`, `host`) and `warnings`. The desktop helper's model
+  `models` (`name`, `host`, `id`, and `configured: true` on an id declared under `hosts.<name>.models`), `aliases` (`name`, `ref`, `host`) and `warnings`. The desktop helper's model
   chooser reads it.
 - Exit 0 when any host listed its models, 1 when none did (the default is still printed), 2 on a usage error.
 
@@ -245,6 +248,9 @@ Notes:
   then `chi: the session is kept with your prompt; continue it with: chi
   --resume ID` (exit 1). Ctrl-C saves the session with the prompt and a
   cancel note and exits 130.
+  Nobody can answer there: an approval is denied, and a question the model
+  asks (`ask_user_question`) is dismissed at once (one line on stderr), never
+  read from stdin, so the model finishes its reply.
 
 ### Scratch sessions
 
@@ -429,9 +435,11 @@ request (with the cached tokens, the cache writes, the re-prefilled tokens and t
 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 memory indexes the session's prompt holds ([Memory](memory.md#the-indexs-size)), the model notes it carried (`model notes:      model_notes_deepseek (system, 612 chars)`, none without any; [Memory](memory.md#model-notes)), 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
+(generations that ended at the provider's cap), context used and window (the used figure is counted against the smaller of the window and the session's LLM context budget, and says so: `context used:     16000 tokens (25.0% of the 64000 budget)`), the memory indexes the session's prompt holds ([Memory](memory.md#the-indexs-size)), the model notes it carried (`model notes:      model_notes_deepseek (system, 612 chars)`, none without any; [Memory](memory.md#model-notes)), the prompt profile and the model the server says it ran, and the
+cost when the provider reports one (OpenRouter's `usage.cost`), and the cost
+estimated from a price under `hosts.<name>.models` when it reports none or 0,
+marked `~` (`cost:             $0.42 reported + ~$0.12 from hosts.<name>.models prices (this session only)`;
+see "Prices" in [configuration](configuration.md#prices)). 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
 prompt (last, server)`); for other servers it is estimated from the first
 streamed chunk to the end and marked `~` (`~64 tok/s out (last, estimate)`).
@@ -451,7 +459,8 @@ saved with the session and applies from the next turn's start; the reply says
 what it costs: `forget` on or off re-reads the whole prompt once, `stale` turned
 on stages the reads already superseded as one batch under the apply rule, and a
 layer turned off sends its stubs whole again (turning it back on brings them
-back). It runs between turns (a worker answers `busy` mid-turn). `/stats` shows
+back). `/llm-context` alone answers mid-turn too; a change sent while a turn runs
+waits for the turn's end (see *Typing during a turn*). `/stats` shows
 the same values on its `llm context:` line. The web's info bar shows them as the
 `llm ctx` chip (`llm ctx stale,forget · session`), whose popover sets them
 through `/llm-context`. See "LLM context: a session's own strategy" in
@@ -468,11 +477,28 @@ REPL alike:
   A line that comes after the turn's last step runs as the next turn, and so
   does one sent after Ctrl-C: it doesn't merge into the turn being cancelled.
   Reminder turns take merged lines too.
-- `/stats` and `/recap` answer at once, and in an attached terminal so do `/help`
-  and a plugin's anytime command (`/btw`). Other commands (`!cmd`, `/model`, `/models`,
-  `!rollback`, `/continue`, `/guardrails`) say `busy: wait for the turn to end`
-  and go back into the prompt, so Enter runs them once the turn ends. A
-  one-word `/word` no command answers (`/modle`) is not steering text either:
+- 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.
+  - After the turn: the ones that change something (`/model X`, `/model clear`,
+    `/llm-context strategy …`, `/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
+    running first and one sent after it running after. A `/model X` sent
+    mid-turn doesn't change the running turn, nor a line merged into it later.
+    After a canceled or failed turn a waiting `!cmd` is dropped
+    (`turn canceled: !ls not run; send it again`): running it would close the
+    `!rollback` the turn left; the others still run. A command still waiting
+    when the session's worker stops is answered `dropped` too.
+  - Refused: `!rollback` (`busy: Ctrl-C the turn first, then !rollback`),
+    `/continue` and a plugin's command that isn't anytime
+    (`busy: wait for the turn to end`). The line goes back into the prompt, so
+    Enter runs it once the turn ends.
+
+  A one-word `/word` no command answers (`/modle`) is not steering text either:
   the hint prints and the line is dropped.
 - A question (`ask_user_question`, a guardrails approval) turns the prompt into
   a yellow `? ` and lists its choices under it, fitted to the terminal; only a
@@ -486,6 +512,10 @@ REPL alike:
   (`/exit --delete` deletes the session then too). In an
   attached terminal it detaches at once and the turn goes on in the worker
   (`/exit` then says the worker stays up: a turn is running).
+- `/archive` mid-turn archives once the turn ends:
+  `(archives after this turn; Ctrl-C cancels it)` in the plain REPL,
+  `(archives after this turn)` in an attached terminal, which also waits for
+  the commands queued behind the turn.
 
 With stdin that isn't a terminal (a pipe), the REPL reads a line only between
 turns.
@@ -712,7 +742,7 @@ In interactive assist mode, you can switch the request model without restarting:
 - `/model`: show the effective model (and default when diverged: `runtime model: <effective> (default: <default>, profile=<name>, <source>)`, e.g. `profile=qwen36, server (chat_template)`). When the session's prompt carries model notes the line ends with `; notes: model_notes_deepseek (system, 612 chars)`; a switch's `runtime model set to …` names the new model's ([Memory](memory.md#model-notes)).
 - `/model clear` (or `default`/`none`/`off`): clear the session override, reverting to the configured default.
 - `/guardrails`: the guardrail rules (by source), what failed to load, and your stored approvals, numbered; `/guardrails revoke N` removes approval N (see [Guardrails](guardrails.md)).
-- `/models`: list model ids aggregated across all `hosts:` (an alias shows next to its id: a bare alias on every host listing the id, a `host:model` one only under its host; grouped `host (host:port):` with per-host `unreachable` warnings, e.g. an unset `api_key_env`; lists cached 60s, 10 minutes for a remote host; lazy — no startup prefill). At most 20 ids per host, then `… and N more`; `/models <text>` lists every id containing `<text>` (any case), e.g. `/models qwen` on OpenRouter.
+- `/models`: list model ids aggregated across all `hosts:` (an alias shows next to its id: a bare alias on every host listing the id, a `host:model` one only under its host; grouped `host (host:port):` with per-host `unreachable` warnings, e.g. an unset `api_key_env`; lists cached 60s, 10 minutes for a remote host; lazy — no startup prefill). Ids the host declares under `hosts.<name>.models` come first, as `rr/x (config)`, and don't count toward the cap. At most 20 ids per host, then `… and N more`; `/models <text>` lists every id containing `<text>` (any case), e.g. `/models qwen` on OpenRouter.
 
 Notes:
 
@@ -815,7 +845,8 @@ status> model=Qwen3.6-35B | ⑂ 2 running · 1 waiting | ctx=8.1% (under20) | me
 ```
 
 - `model=`: the model in use, `(default: …)` beside it when it isn't the config's default, and
-  `model=<served> (served; asked <name>)` when the server said it served another model.
+  `model=<served> (served; asked <name>)` when the server said it served another model (not for one its host's
+  `hosts.<name>.models.<id>.served` names; see [configuration](configuration.md#models-a-host-serves-but-doesnt-list)).
 - `↳ <id>`: the session that delegated this one.
 - `⑂ …`: this session's delegate children (forks aren't counted): how many run and how many wait
   for an answer; only the counts there are, nothing when none does (`/children` has the rest:

data/docs/configuration.md

@@ -413,6 +413,41 @@ models:
 `SAMAGOTCHI_HOSTS_JSON`, and reads `models:` from the config file each turn: after changing a host's `sampling:`,
 stop the session's worker (`chi sessions stop`) for it to take effect.
 
+## Prices
+
+A provider that reports no cost (`usage.cost`), or reports 0, can still be priced: give the model a price under
+the host that serves it, in USD per 1M tokens.
+
+```yaml
+hosts:
+  work:
+    url: https://gateway.example/v1
+    api: openai
+    models:
+      rr/deepseek-v4.1:
+        price: {input: 0.27, cache_read: 0.07, output: 1.10}
+  openrouter:
+    url: https://openrouter.ai/api/v1
+    api: openai
+    models:
+      qwen/qwen3.8-27b: {price: {input: 0.10, output: 0.40}}   # a listed id, here only for its price
+```
+
+- `input` and `output` are required; `cache_read` and `cache_write` are optional. Each is a number >= 0; a price
+  missing one of the required two, or with a value that isn't a number >= 0, warns at start and is ignored.
+- An unset rate is the input rate: that overstates cached reads, and understates Anthropic cache writes (billed
+  1.25x input for the 5 min cache, 2x for 1 h). Set them when it matters.
+- A price is per host, since one model can cost differently on two hosts. It is looked up by the model the session
+  asked for (its host and id), never by the model the host says it served.
+- Each generation with the server's token counts is estimated as uncached prompt × `input` + cached reads ×
+  `cache_read` + cache writes × `cache_write` + completion × `output`, over 1M. A generation with only estimated
+  counts (characters / 4, no usage from the server) isn't priced.
+- A reported cost wins: a generation with a non-zero `usage.cost` is never estimated. A reported 0 with a price is
+  estimated (a gateway that bills elsewhere reports 0); the 0 is kept as the reported cost.
+- The estimate is saved apart from the reported cost (`cost_estimate` per turn, `cost_estimate_sum` in the
+  session's totals in `analytics.json`) and shows with a `~`.
+- A server that sends no cached counts has its whole prompt priced at `input`: an overestimate.
+
 ## Thinking
 
 How much a model thinks before it answers. One level, `off`, `low`, `medium`, `high` or `default`, set per model,
@@ -555,11 +590,12 @@ When `default.model` is unset or blank, Samagotchi fails fast with a clear start
 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
+to the default host. A host's declared ids (`hosts.<name>.models`, below) count
+as listed. Only exact ids count, never a substring: `/model gemma` on
 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
+until then an unqualified name goes to the default host, unless a host declares
+it; use `host:model` to pin one. A **remote** host (an `https` url or a public address; see "Remote or local") keeps its model
 list for 10 minutes (60s for local hosts).
 
 **The context window** (what the context status and `ctx=` count against) comes from,
@@ -608,6 +644,59 @@ alias, `/model`, `chi send --new --model`, the web's new-session model and a
 delegate's model. Any other unknown prefix (`nosuch:x`) is sent to the default
 host as the model id.
 
+### Models a host serves but doesn't list
+
+A gateway can serve ids its `/v1/models` never lists (round-robin aliases such
+as `rr/deepseek-v4.1`). Declare them under the host:
+
+```yaml
+hosts:
+  work:
+    url: https://gateway.example/v1
+    api: openai
+    api_key_env: WORK_API_KEY
+    models:
+      rr/deepseek-v4.1:
+      rr/qwen3.8-27b:
+```
+
+A plain list says the same: `models: [rr/deepseek-v4.1, rr/qwen3.8-27b]`. Ids are
+full ids (no globs), matched case-insensitively. A declared id is known on its
+host whatever the host lists:
+
+- `work:rr/deepseek-v4.1` never gets the "host 'work' doesn't list model" warning,
+  and the host isn't re-listed for it (`chi send --new --model`, delegates).
+- A bare `rr/deepseek-v4.1` goes to `work` as if `work` listed it, also before
+  any `/models` and in a session's worker. When several hosts list or declare an
+  id, the default host wins if it is one of them, else the first in `hosts:`
+  order; two hosts declaring one id get a warning at start saying which one a
+  bare id goes to. `host:id` still pins a host.
+
+**A gateway that answers with another model.** A round-robin id is served by one
+of its targets, and the reply names that one (`fireworks/deepseek-v4.1`), so chi
+marks every turn as served by another model than asked (the web's `⚠`, the status
+line's `(served; asked …)`, `/model`'s `served:`). `served:` lists the models the
+host may answer with, as exact ids (any case), or `any`:
+
+```yaml
+hosts:
+  work:
+    models:
+      rr/deepseek-v4.1:
+        served: [fireworks/deepseek-v4.1, baseten/deepseek-v4.1]
+      rr/qwen3.8-27b:
+        served: any
+```
+
+A served model it names is no mismatch: the web and the status line keep the name
+you asked for, and `/stats` names the served model without "(asked for …)". One it
+doesn't name is still marked. `any` gives that check up for the id.
+
+**Root `models:` vs `hosts.<name>.models:`.** The root `models:` holds settings
+by model name (sampling, thinking, window, profile…), on whatever host the model
+runs on; it says nothing about which host serves a model. `hosts.<name>.models:`
+says which models that host serves. Keep settings in the root one.
+
 ### Model aliases
 
 `model_aliases:` maps a name to a model id or `host:model`. An alias works
@@ -641,12 +730,17 @@ Transient network failures are retried automatically with exponential backoff.
   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.
+- A stream that has already produced output is never retried at the transport (the retry would repeat it). The
+  chat loop (an OpenAI-compatible host) drops the partial reply and asks again for the whole step, from the same
+  conversation, at most twice (at most `retry.max` times when that is smaller: `retry.max: 0` turns it off), after
+  the same backoff, reported as a retry (`↻ retrying (stream dropped) …`); once those run out the turn fails with
+  the error, as before. A refusal, a first-token timeout, a provider error and a cancel are never retried this way.
 - Cancellation (`Ctrl-C`) is never retried.
 
 Configuration:
 
-- `retry.max` (default `5`, env `SAMAGOTCHI_RETRY_MAX`): number of retries after the first failed attempt.
+- `retry.max` (default `5`, env `SAMAGOTCHI_RETRY_MAX`): number of retries after the first failed attempt; it also
+  caps a dropped stream's asks-again (at most 2), and `0` turns those off too.
 - `retry.base_delay` (default `0.5`, env `SAMAGOTCHI_RETRY_BASE_DELAY`): backoff base delay in seconds.
 - `retry.max_delay` (default `8.0`, env `SAMAGOTCHI_RETRY_MAX_DELAY`): cap for backoff delay in seconds.
 
@@ -1036,6 +1130,9 @@ described in their own sections.
 | `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". |
 | `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". |
+| `hosts.<name>.models.<id>.price` | none | | The model's price on that host, USD per 1M tokens: `input`, `output`, optional `cache_read` and `cache_write`. Estimates the cost a provider doesn't report. See "Prices". |
 | `hosts.<name>.remote` | by address | | `true`/`false`: treat the host as a remote provider or a local server. See "Remote or local". |
 | `max_tool_output_chars` | `10000` | yes | Characters of each tool output kept in the conversation (both loops); a longer one is cut and ends with `[cut: N of M chars; read it in parts]`. A top-level key (see below). |
 | `cache.warmup` | `auto` | | `auto`: after a turn, send the next turn's prompt (up to the next message) to a local llama.cpp host on the native loop, so the next turn prefills only its message; never a remote or `api: openai` host. `off`: never. See [prompt caching](internals/prompt-caching.md#the-turn-end-warm-up). |

data/docs/context.md

@@ -225,7 +225,8 @@ later when an offer is wanted: one JSON line per event, `offered` (session,
 project root, working directory, branch, PR URL, main checkout or worktree,
 model), `attached` and `declined` (with the seconds since the offer), and
 `first_prompt` (the first 160 characters of every session's first message,
-offered or not; not scratch sessions or delegate children). Over 1 MB it is
+offered or not; a fork's first after the conversation it started from, once;
+not scratch sessions or delegate children). Over 1 MB it is
 renamed to `offers.ndjson.1` (one old file is kept). Only you can read it
 (0600), and nothing leaves your machine.
 

data/docs/internals/background-tasks.md

@@ -19,6 +19,7 @@ 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/`.
+- A task record keeps its process's pid and start time (`pid_started`). Before `task_stop` signals, the pid must still lead its own process group and must not have started at another time; otherwise the pid was reused by another process, nothing is signalled and the task ends as failed. A start time that can't be read at that moment (a failed `ps`) falls back to the group check, as does a record without `pid_started` (from an older chi). `task_get`, `task_list` and `task_wait`'s polls check the group only (no `ps` per poll).
 - Task listing is workspace-scoped (current project only).
 - `task_get` returns metadata and `output_path`; use `read` for output contents.
 - `task_wait` accepts `timeout`, `tail_lines` (maximum 100), and `done_pattern` (a regular expression string).

data/docs/internals/engine.md

@@ -293,7 +293,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 | `:context_status` | the window's fill crossed a bucket | `{iteration, ...}` |
 | `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source}` (native adds `profile`, `profile_source`) |
 | `:generation_chunk` | each streamed chunk | `{iteration, content, text, thinking, payload, tool_call?}` |
-| `:generation_retrying` | the transport retries the request | `{iteration, ...}` (the retry's fields) |
+| `:generation_retrying` | the transport retries the request, or the chat loop asks again for a step whose stream dropped mid-answer (`restarted: true`: what the step streamed is void, and the web's live step, the TUI's activity line, the Bridge's TurnAccumulator and the stream hooks' watch start it over) | `{iteration, attempt, max_retries, next_delay, error_class, error_message, status, restarted?}` |
 | `:generation_completed` | a generation ended, or was cut | `{iteration, content_length, thinking_chars, served_model, requested_model, finish_reason, ...}`; a cut adds `stopped_by`, `stop_reason`; the Engine adds `speed`, `tokens` |
 | `:generation_cancelled` | the turn was cancelled mid-loop | `{iteration, reason, stopped_by}` |
 | `:empty_answer_retry` | an empty, cut or malformed answer is asked again | `{iteration, attempt, of, finish_reason, thinking_chars, stopped_by?, malformed?}` |

data/docs/internals/llm-context-live.md

@@ -0,0 +1,111 @@
+# The llm_context live runs
+
+`script/llm_context_live.rb` runs chi itself on real coding tasks under each LLM context strategy and scores the
+sessions. The replay benchmark ([llm-context-bench.md](llm-context-bench.md)) scores stored sessions offline. These
+runs close the loop: the model lives with the strategy for a whole task, so they measure what the replay can't, such
+as whether a forgotten output comes back as a re-read and whether a note narrows the scope (context strategies P6).
+It is a development tool under `script/` and isn't shipped with the gem. It calls a paid model, so it is opt-in: the
+specs drive it with fakes on synthetic data.
+
+```sh
+ruby script/llm_context_live.rb validate TASKS ROOT                     # no model
+ruby script/llm_context_live.rb run TASKS ROOT --model openrouter:deepseek/deepseek-v4.1-flash \
+     [--tasks T1,T3] [--arms none,stale,stale_forget] [--samples 3] [--budget 64000|off] [--cap 8] [--jobs 3] [--limit 9]
+ruby script/llm_context_live.rb report ROOT [--json]
+ruby script/llm_context_live.rb grade|collect TASKS ROOT RUN...          # again, for runs already done
+```
+
+`TASKS` (a YAML file) and `ROOT` (where the runs and results go) live outside the repo. They hold task prompts and
+session files, and no session text goes into the repo, scrubbed or not.
+
+## Tasks
+
+A task is a real merged fix, replayed from its parent commit. The fix's spec changes are held back and graded
+afterwards.
+
+```yaml
+source_repo: /path/to/samagotchi
+tasks:
+  T1:
+    fix: 545a3562            # the run's repo is its parent
+    size: S
+    turns:                   # one chi turn each; {repo} is the run's repo path
+      - "In {repo} … find the cause and plan the fix. Don't edit yet."
+      - "Implement the plan and run the specs."
+    hidden: [spec/broadcast/triage_spec.rb]       # optional: the fix's *_spec.rb
+    regression: [spec/broadcast/triage_spec.rb]   # optional: the hidden ones' paths
+    fix_files: [lib/samagotchi/broadcast/triage.rb, spec/broadcast/triage_spec.rb]  # optional: what the fix changed
+```
+
+A file at `hidden/<task id>/<path>` beside the tasks file stands in for that hidden spec. Use it when the fix's spec
+pins a detail that another correct fix would get differently, such as an exact page size; the override keeps only the
+contract.
+
+`validate` checks each task's hidden specs: they must fail at the fix's parent and pass at the fix.
+
+## A run
+
+Each task × arm × sample is a run in `ROOT/runs/<task>-<arm>-s<n>/`:
+
+1. **prepare:** `git archive <fix>^` into `repo/`, then a fresh git repo with one base commit. It writes chi's config
+   in `config/` (the model's host copied from `--hosts-config`, default the user's config.yml; `turn.max_iterations:
+   150`; `recap: false`; `llm_context.apply: payoff`, no `stale_edits`). State goes in `state/`, and it runs `chi
+   bundle install loop-guard`. Every chi and rspec command gets `SAMAGOTCHI_ENV=test`, the run's `XDG_STATE_HOME`
+   and `XDG_CONFIG_HOME`, and no inherited `SAMAGOTCHI_HOSTS_JSON` (the smoke-run isolation).
+2. **run (Driver):** `chi send --new --wait --format json --dir repo --model M --llm-context <arm>
+   --llm-context-budget <N|off>` with the first turn, then each later turn into the same session. The arms are
+   `none`, `stale` and `stale_forget` (`stale,forget`). The tasks use two turns, because forget is offered at turn
+   ends. The driver answers questions as a parent agent would:
+   - the model's first question gets "use your judgement" (option 1 when it takes no text), and later ones are
+     dismissed;
+   - an approval is denied;
+   - the step-limit question gets Stop: there is no Continue, since the limit is part of the task.
+
+   A turn waits at most 45 minutes. Afterwards the session is stopped with `chi sessions stop`, then `pkill -f
+   <the run's state dir>`. Nothing is ever killed by a pid read from a file.
+3. **collect:** the numbers below, read before grading, and `diff.patch` (the work against the base commit).
+4. **grade (Grader):** the hidden specs are copied in as `<name>_p6hidden_spec.rb` and run in one `bundle exec rspec`
+   with the regression specs (the model's own copies), then removed. Pass means rspec exits 0 with at least one
+   example. The working tree is graded: nothing needs committing.
+
+The result goes to `ROOT/results/<run>.json`. A rerun skips runs that have a result, and starts over any run that
+has none.
+
+## Cost
+
+Each run's cost (OpenRouter's reported `cost`, summed over the turn records) goes to `ROOT/ledger.jsonl`. No run
+starts once the ledger reaches `--cap` (default $8). With `--jobs N` the runs in flight can pass the cap by what they
+spend. A payment error (chi send's `error_kind` `credits` or `credits_held`, or a 402 / over_budget in the detail)
+ends that run at once and writes `ROOT/STOP`, and no further run starts until someone removes it. The account's own
+key limit stays the hard stop.
+
+## What it scores
+
+Per run (`Collector`), from the session file, `analytics.json` and the repo:
+
+- **success:** the grade, plus a manual 0/1/2 in `ROOT/grades.yml` (`T1-none-s1: {grade: 2, note: …}`);
+- **steps, tool calls, edits, commits:** `ModelNotesReport::SessionReader`;
+- **reads, re-reads, re-reads after a stub** (by kind): `LLMContextBench::Replay#read_counts`. A re-read reads a
+  path the session read before. It counts as after a stub when an earlier read of that path had an applied stub
+  whose cause came before it: a forget's cause is its `forget_outputs` call, a stale stub's the read that superseded
+  it;
+- **stale stubs, forget calls, forgotten ids and their tokens:** `Replay#stubs` (chars/4);
+- **tokens:** prompt tokens sent (summed over requests), cached, re-prefilled and completion tokens, and the cost,
+  from the turn records;
+- **peak context:** the largest prompt of any turn (`prompt_tokens_max` on the turn record);
+- **scope:** distinct files read, files read and files changed outside the fix's set, and diff lines;
+- **wall time.**
+
+`report` gives each task × arm its pass count, manual grades, step-limit stops, and every metric's median with its
+min–max spread. It also gives the gate: `stale_forget` against `none`. Per task, a metric is better when
+`stale_forget`'s median is below `none`'s whole spread, worse when above it, and the same otherwise. The gate passes
+when, on both re-reads and scope (files read + files changed outside), the better tasks outnumber the worse, and
+`stale_forget` passed at least as many runs as `none`.
+
+## Limits
+
+- Three samples a cell is little. Read nothing into a difference inside one arm's spread.
+- Tokens from `Replay` are chars/4, and those from the turn records are the server's.
+- A Splash host may not report cached tokens or cost (they read 0).
+- The fix's spec file is copied in whole, so its old examples run twice: once hidden and once as the model left
+  them.

data/docs/plugins.md

@@ -94,8 +94,9 @@ commands it knows.
 
 #### `anytime: true`
 
-A normal command waits for its turn: typed while a turn runs, it is refused
-as busy (the REPL puts it back into the prompt). An `anytime: true` command
+A plugin's normal command waits for its turn: typed while a turn runs, it is
+refused as busy (the REPL puts it back into the prompt; a plugin command can't
+ask to run after the turn, as the built-in `/model X` does). An `anytime: true` command
 runs **at once, on its own thread, beside the running turn**, and the turn
 goes on:
 
@@ -504,6 +505,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.repo_root` | the git checkout holding `cwd`, or nil |
 | `ctx.scratch?` | whether the session is a `chi scratch` one (deleted when it ends) |
 | `ctx.delegate?` | whether the session is a delegate child: a task another session handed over |
+| `ctx.fork?` | whether the session is a fork (`ctx.sessions.fork`): it has a parent but isn't a delegate child, and started from a conversation, so its first prompt isn't its first user message |
 | `ctx.model` | the model the session runs on now: its resolved ref (`host:id`), right after `/model` too |
 | `ctx.model_key` | that model's memory overlay key (`<name>.<key>.md`, what `memory_write current_model_only` writes) |
 | `ctx.settings` | the bundle's settings, frozen |