samagotchi 0.82.0 → 0.83.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02be0edba759be799428a67ac174beba8a77c2869f3de8f677dec9a14977ae60
-  data.tar.gz: d28e0688aec5428264fc7a48162a7f4e03ea461371cc48aba4da3c64ecf2e9d8
+  metadata.gz: 9b7fb93e6e4741b5380cfaeaa2a27d37dd326099f2d3cf568b659941e9c34930
+  data.tar.gz: bc53710bd1f4dab4d2d5d4e1eb23814f367fc47833b930fd6bd7ee3a1411423b
 SHA512:
-  metadata.gz: 1df47ccd973923c62848fef02807f3982ede1b86ebf032425c1ecd311014103286803822a290b24f117d705e3e8f845b22cb4804e90cc731a8dd48a3946a3b6f
-  data.tar.gz: 3c901380929266d60c820ebba9ad3581bdb4392f498fbb43dcef6ba157e675c100a8dba752ee27a79d464692ffb0a407b75ead89961f38c89e6551bf8a9a6ada
+  metadata.gz: 882ac69395d70f9b27e8b9922b704c1b1818ad400eeb4551dac38c905df7822d17ac43450f71b5c5a0653b0af9b45470098981f9ee25e36dc2f45a1bb2a9eeee
+  data.tar.gz: 1e982daa8adf0881d87ea82256e96565cceb09ab4d6793325a87ce0214df3355a5798c3da75f9afab30126aba7bd5f7f9facf7dfd1f032e3c2cfd9a5e4aaeed4

data/CHANGELOG.md

@@ -8,6 +8,22 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.83.0] - 2026-10-18
+
+### Added
+
+- Bundles: `ctx.cost` reads the session's spend so far (reported + estimated, side requests included).
+- The cost-cap bundle (in the core profile): a per-session $ cap that pauses the turn with Continue / Stop, `/cap`
+  to see or set it; config `bundles: cost-cap: default/child/warn_at`. Existing installs get it with `chi update`
+  (core 0.3.2, + cost-cap).
+- Docs: docs/configuration.md "When a change applies" says, per config.yml key, whether an edit applies on the
+  next turn, at worker start, at session creation or at `chi web` start.
+
+### Fixed
+
+- A delegate reply already taken as a report isn't returned again by `delegate_result` in the same turn.
+- `chi send --wait ID` with no message recognizes a finished turn's reply across time zones.
+
 ## [0.82.0] - 2026-10-18
 
 ### Added
@@ -3364,7 +3380,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.82.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.83.0...HEAD
+[0.83.0]: https://github.com/dm1try/samagotchi/compare/v0.82.0...v0.83.0
 [0.82.0]: https://github.com/dm1try/samagotchi/compare/v0.81.0...v0.82.0
 [0.81.0]: https://github.com/dm1try/samagotchi/compare/v0.80.0...v0.81.0
 [0.80.0]: https://github.com/dm1try/samagotchi/compare/v0.79.0...v0.80.0

data/README.md

@@ -78,8 +78,8 @@ Messages API, picks the
 model (or asks, when there are several), sends one test request and writes
 the config. With a config already there, it adds a `hosts:` entry and keeps
 the rest of the file. Then it installs the `core` bundles (loop-guard,
-check-in, guardrails, slow-commands, agents-md: the safety set for a small
-local model) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
+check-in, guardrails, slow-commands, agents-md, cost-cap: the safety set for a
+small local model, the cost cap inert until you set one) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
 source-links). Edit the
 file later as in [Configure](#configure); `chi bootstrap --help` has the
 options.

data/docs/architecture.md

@@ -346,6 +346,9 @@ Side requests (the idle recap, a plugin's `ctx.ask_model` such as `/btw`) are co
 `analytics.json` between turns (a running turn's end saves it). `tokens`, `model_segments` and the turn records
 stay the turns' only. `SessionMetrics#persist` is serialized (its own mutex, taken before the metrics one), so two
 threads' saves land in snapshot order.
+A bundle's `ctx.cost` reads the same sums (`SessionMetrics#cost`, a frozen `SessionMetrics::Cost`): the `tokens`
+block's `cost_sum` and `cost_estimate_sum` with the running turn's finished generations folded in, plus the `side`
+block's, so it counts what earlier workers spent too ([plugins.md](plugins.md)).
 
 The page's frequent reads of `GET /api/sessions/:id` stay light too:
 - `?tail=1&recent=1` (each turn's end, a cancel, an answer display): `{tail, session: {id, status,

data/docs/configuration.md

@@ -100,15 +100,15 @@ Behavior:
   `config: unknown key 'default.modle' (did you mean 'default.model'?)`.
   Names you choose under the maps below (host names, model ids) don't warn.
 - Environment variables and CLI flags win over config-file values.
-- An edit to the file needs no restart of `chi web`: a new session's worker
-  reads the file when it starts, and a running chi takes a changed value the
-  next time it reads that setting (a worker keeps `hosts:` and what it set up
-  at its start until it is stopped; the web's model picker lists a `hosts:`
-  edit at once). A worker gets the CLI flags of the chi that started it
-  through its environment.
-- A worker reads `hosts:` from the file as it starts, as every other setting, so a delegate (or any session
-  started later) sees a host added after its parent started. Hosts come only from config.yml: no environment
-  variable sets them.
+- An edit to the file needs no restart of `chi web`. A new worker reads the
+  file when it starts; a running worker sees only settings whose readers check
+  the file again (see [When a change applies](#when-a-change-applies)). The web
+  model picker refreshes `hosts:` when the file changes, but a running worker
+  keeps its host registry until it is restarted. A worker gets the CLI flags of
+  the chi that started it through its environment.
+- A newly started worker reads `hosts:` from the file, so a delegate (or any
+  session started later) sees a host added after its parent started. Hosts
+  come only from config.yml: no environment variable sets them.
 
 This lets you run `chi` without repeating common defaults such as model
 and llama host/port on every invocation.
@@ -125,6 +125,49 @@ any per-run `--memory` values (config baseline first, deduped). A per-run
 `--mute NAME` removes an entry from the merged list for that session (see
 "Muting a memory" in cli.md).
 
+## When a change applies
+
+The config reader checks the file's modification time and size whenever a
+setting is read. That makes a changed value available to a live reader; it
+does not reload every object that already holds a snapshot. "Worker start"
+includes a worker respawn. A running turn keeps the settings it already
+resolved.
+
+| Key | Applies | Note |
+|---|---|---|
+| `default.model` | New session | Existing sessions keep their saved model; change one with `/model`. |
+| `default.input`, `no_default_input`, `no_interrupt` | Next CLI run | These set up that run's first prompt or turn limit. |
+| `default.max_tokens`, `max_tool_output_chars`, `read.*`, `execute.*` except `execute.description`, `image.*` | Next matching request or tool use | An operation already in progress keeps its resolved limits. |
+| `server.host`, `server.port`, `server.transport`, `hosts.*` | Worker start | Includes host addresses, APIs, declared models and host-level settings. The web model picker refreshes `hosts:` on file change; a running worker does not. |
+| `server.open_timeout`, `server.read_timeout`, `server.first_token_timeout` | Worker start | The worker's clients retain the timeouts set when they were built. |
+| `model_aliases` | Next model lookup | A session keeps its resolved model unless it is explicitly switched. |
+| `models.<key>.profile` | Session start or `/model` | It is resolved when that model is selected; editing it does not switch the current model's profile by itself. |
+| Other `models.<key>.*` settings | Next turn or model lookup | Sampling, thinking, vision, context, window, price and steer settings are resolved from the file for their next use. |
+| `thinking.level` | Next turn start | A session's own `/thinking` level is saved in that session and takes precedence; a running turn keeps its level. |
+| `cache.*` | Next request or turn-end warm-up | Cache key and TTL are read for a request; warm-up is checked after a turn. |
+| `retry.max`, `retry.base_delay`, `retry.max_delay` | Worker start | The client's network retry policy is built with its HTTP client. |
+| `retry.empty_answer` | Next empty-answer retry | It is checked when a turn needs to retry an empty answer. |
+| `memories` | Worker start | The running engine holds its preload list. The config list is not saved in the session file, so a respawn reads the current list. |
+| `append_system_prompt` | Worker start for the file list | The config list is not saved in the session file. File text is read when the prompt is built; `/model` rebuilds it, while an already-built prompt is cached. CLI `--append-system-prompt` files are saved in the session. |
+| `toolkit.default`, `toolkit.child` | Session creation | The chosen toolkit is saved; changing the defaults does not move existing sessions. |
+| `toolkit.kits`, `execute.description`, `llm_context.policy` | Worker start | These are held by the engine's toolkit or tool registry. |
+| `thinking.turn_preamble`, `skip_agents_md` | Prompt rebuild | A running engine caches its built prompt; a new worker or `/model` rebuild uses the changed value. |
+| `context.*` except `context.every_seconds`, `llm_context.*` except `llm_context.policy`, `steer.cut_after`, `memory.index_warn_tokens`, `status.line` | Next matching turn, display, poll or write | Readers resolve these settings when they perform that operation. Session-specific LLM context and thinking values remain saved in the session. |
+| `context.every_seconds` | Next context poll | The poller checks it for each source that has no explicit interval. |
+| `guardrails.*` | Next tool call or approval | Guardrail rules and disable lists are reloaded when the config file changes; rule settings take effect on that evaluation. |
+| `hooks`, `bundles` | Worker start | Hooks, plugins and their bundle settings load with the engine. |
+| `recap.*` | Worker start | The engine builds its recap job once. |
+| `session.shared` | Next `chi` invocation | It selects attached-worker or in-process mode for that invocation. |
+| `session.idle_exit_minutes`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer; the other values are read for the next corresponding decision. |
+| `session.retention_*` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. |
+| `web.*` | `chi web` start | Restart `chi web` to change its bind address, port or page settings. |
+| `log.*` | Process start | Each process holds its configured log sink and level after first use; restart that process. |
+| `history.file` | Next history access | The TUI and web composer resolve its path when they read or append history. |
+| `broadcast.*` | Next `chi broadcast` | Each broadcast invocation reads its targeting and triage settings. |
+| `update.*` | Next `chi update` | The command reads which components to update when it runs. |
+| `kitty.*`, `tmux.*` | `chi desktop upgrade` or desktop update | These settings are copied into the desktop helper's launch file. |
+| `model.profile`, `reasoning_history` | Not from config.yml | These are CLI/environment settings; `models:` and `hosts:` provide their model- and host-specific forms. |
+
 ### Environment variables
 
 Every setting has an environment variable (except the ones the table marks

data/docs/hooks.md

@@ -592,7 +592,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
+- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:

data/docs/memory.md

@@ -316,7 +316,7 @@ profiles, meta bundles that install a set of them:
 
 | profile | bundles |
 |---|---|
-| `core` | loop-guard, check-in, guardrails, slow-commands, agents-md: the recommended safety set |
+| `core` | loop-guard, check-in, guardrails, slow-commands, agents-md, cost-cap: the recommended safety set |
 | `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer, codex-peer |
 
 `chi bootstrap` installs `core` and, on a terminal, offers `dev`. An existing

data/docs/plugins.md

@@ -730,6 +730,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `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.cost` | the session's spend so far, read now, as a frozen value: `total` (USD, reported + estimated, side requests included; 0.0 before any), `reported` (by providers, `usage.cost`), `estimated` (from `hosts.<name>.models` prices; a generation is one or the other, never both), `side` (recap, `/btw`, `ask_model`: their share of `total`) and `known?` (false while generations or side requests ran but none was reported or priced, so a limit on it can't be enforced; a session with some priced generations reads known, the unpriced ones counting 0). It includes the running turn's finished generations and what earlier workers of the session spent. Use its methods, not its class. Needs chi 0.83.0 |
 | `ctx.settings` | the bundle's settings, frozen |
 | `ctx.data_dir` | `$XDG_STATE_HOME/samagotchi/plugins/<bundle>/`, created on first use. A session's own state goes in `sessions/<id>.json` or `sessions/<id>/` there: chi removes it when the session is deleted, discarded or pruned |
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
@@ -1081,7 +1082,7 @@ CHANGELOG line and bumps the shipped bundles that use it. Anything else under
 
 **Stable**
 
-1. `Samagotchi::Plugin::Api` / `chi.*` as documented above, including
+1. `Samagotchi::Plugin::Api` / `chi.*` and `ctx` as documented above (`ctx.cost`'s value by its methods), including
    `Samagotchi::Plugin::ToolResult`, `Samagotchi::Plugin::ModelError` (and its
    subclass `Samagotchi::Plugin::ModelCancelled`),
    `Samagotchi::Plugin::Service::Stopped`, `Samagotchi::Plugin::Sessions::Error`
@@ -1145,6 +1146,7 @@ bundle.model_answers << "a summary"                      # the next ask_model's
 bundle.sessions.on(:children) { |all:| [] }              # ctx.sessions, scripted and recorded
 bundle.http.stub(:post, "http://127.0.0.1:9000/classify", json: { label: "safe" })   # ctx.http, never the network
 bundle.set(running: false)                               # the session's values: cwd:, messages:, cancelled: …
+bundle.set(cost: 2.5)                                    # ctx.cost: reported USD, or { reported:, estimated:, side:, known: }
 bundle.shutdown
 ```
 
@@ -1168,6 +1170,9 @@ bundle.shutdown
   **fails the test at teardown** (RSpec and Minitest adapters: after the cleanup, and only a test that passed), so a
   spec can't reach the network. With plain `Bundle.load` there is no teardown: check `bundle.http.unmatched`.
   `bundle.set(cancelled: true)` makes a call without `cancel:` raise `HttpCancelled`.
+- **`ctx.cost`** is zero and known unless the test sets it: `bundle.set(cost: 2.5)` (reported USD), a Hash of the
+  parts (`reported:`, `estimated:`, `side:`, `known:`; `total` is reported + estimated) or a callable giving either,
+  called at each read (a counting lambda shows whether the bundle read it).
 - **A hook that raises fails the call** (`Testing::HookFailed`, with the hook's error) where chi would log it and
   go on; `bundle.lenient { … }` collects them in `bundle.errors` instead.
 - **Sandbox.** A test runs with temp config, state, data and cache homes (config.yml, memories, `ctx.data_dir`, the
@@ -1542,6 +1547,57 @@ Not caught (yet):
 - loops across turns;
 - alternating calls (A, B, A, B) that each return something new.
 
+## The cost-cap bundle
+
+`chi bundle install cost-cap` installs the bundle shipped with chi (`chi bootstrap` installs it with the `core`
+profile; an existing install gets it with `chi update`). It caps what one session spends, so neither you nor the
+model has to watch `chi sessions stats`: the harness watches the money and the model never sees any of it (no tool,
+no steer, no prompt text). It is inert without a cap, and there is none by default.
+
+```yaml
+# config.yml
+bundles:
+  cost-cap:
+    default: 5.00     # USD cap for a session with none set; absent/0/off: no cap
+    child: 2.00       # for delegate children; absent: default
+    warn_at: 0.8      # tell the user (only) once at this share of the cap; 0/off: no warning
+```
+
+- **What counts:** `ctx.cost`'s total: what the provider reported (`usage.cost`), else the estimate from the
+  model's configured price (`hosts.<name>.models.<id>.price`), plus side requests (the idle recap, `/btw`,
+  `ask_model`), including what earlier workers of the session spent.
+- **When it checks:** before each generation, so before the money is spent. A generation that crosses the cap is
+  caught at the start of the next one: the overshoot is at most one generation (plus any side requests between).
+  A turn whose last generation crossed it ends normally, and the next turn's first generation asks.
+- **At `warn_at` of the cap** you get one notice, `cost-cap> $2.41 of $3.00 spent (80%)`; a raised cap warns again.
+- **At the cap** the turn pauses on a question (header "Cost cap"): `Cost cap reached: $3.04 spent of $3.00.
+  Continue raises it to $6.00.` with **Continue** (another cap's worth: $3 → $6 → $9, as many steps as it takes to
+  pass the spend, saved for the session) and **Stop** (the turn stops, `canceled` with `stopped_by: cost-cap`, and a
+  card shows the spend, reported, estimated and side). With no one to ask (`--non-interactive`) it stops.
+- **The cap of a session:** the one `/cap` or a Continue set for it, else `child:` for a delegate child, else
+  `default:`. Delegates and continued links each have their own cap; there is no family cap.
+- **A host it can't watch:** a model that reports no cost and has no configured price (a local server, a free
+  model that reports 0) reads unknown: one notice, `the $3.00 cap can't be enforced: <model> reports no cost and has
+  no price`, and it never stops for an unknown cost. A session with some priced generations counts the unpriced
+  ones as $0.
+
+**`/cap`** (works while a turn runs; the next generation reads it):
+
+- `/cap`: `cost-cap: $1.20 spent of $3.00 (reported $1.10, estimated $0.10, side $0.02)`, or `cost-cap: no cap
+  ($1.20 spent)`, with `(can't be enforced: no cost reported or priced)` when it can't be.
+- `/cap 5` or `/cap $5`: the cap (and what Continue adds) becomes $5.00 for this session. A cap at or under the
+  spend is allowed: the next generation asks.
+- `/cap off` (or `/cap 0`): no cap for this session, over the config's `default:`.
+
+A parent agent starts a session with a cap by sending `/cap N` as its first message (`chi send --new -m '/cap 3'`).
+At the cap, `chi send --wait` exits 3 with a question of kind `hook` (header "Cost cap"); `chi answer ID --question
+Q --option Continue` (or `--option 1`) goes on, `--option Stop` stops the turn ([sub-agent.md](sub-agent.md)). A
+parent may Continue: nothing restricts it, as with the step limit. A background delegate child at its cap waits on
+its own card and doesn't wake its parent ([sessions.md](sessions.md#delegating)).
+
+The state is one file per session, `<data_dir>/sessions/<session id>.json` (`{"cap": 3.0, "step": 3.0}`), removed
+with the session.
+
 ## The check-in bundle
 
 `chi bundle install check-in` installs the bundle shipped with chi (`chi

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, slow-commands, agents-md, source-links, github-pr, coordinator, claude-peer, codex-peer, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, slow-commands, agents-md, cost-cap, source-links, github-pr, coordinator, claude-peer, codex-peer, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`

data/docs/sessions.md

@@ -253,6 +253,7 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - A wait that timed out or was canceled still gets its delegate report: neither moves the parent's cursor, so the child's reply comes as a report when its turn ends. The result says so (`chi brings its reply here by itself as a delegate report …`; with `queue`, that it joins the next step or turn) and that `delegate_result` waits again only if the turn needs the reply now. A parent that gets no reports (`session.delegate_reports: off`, a `--no-shared` REPL, `--non-interactive`) is told `delegate_result <id> waits again` instead, and `wait: false`'s result says `delegate_result waits for its reply`.
 - What a wait returns, `session: <id>` then `status:` and the text, with the status words `chi send --wait --format json` uses: `answered` with the reply after a `---` line; `question` as soon as the child opens a question (the model's own, or a hook's), with the question's text, options and the `chi answer` command for it (nothing is answered for it: `chi answer`, attach or use the web, then wait again); `failed`, `canceled` or `no_answer` when the child's turn ended with nothing to say (its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `worker_gone` when the child has had no worker for 15 seconds (it crashed without saying so, or idle-exited): `delegate` with `session:` starts it again; `running` on timeout, or when the parent's own turn is canceled (the child keeps running; the next turn can wait again). A reply saved before the child's worker idle-exited is returned at once.
 - **A child's step-limit question goes back to the parent model**, not to its user: `delegate_result` returns `status: question` with the `chi answer` commands for Continue and Stop, and says the model may instead send a narrower follow-up (`delegate session:`, which drops the question) or report back. A parent's `chi answer` follows `turn.parent_continue` (see [chi as a sub-agent](sub-agent.md#the-step-limit)).
+- **A child at its cost cap** (the [cost-cap bundle](plugins.md#the-cost-cap-bundle), the child's own cap: `child:` in its settings, or `/cap`) asks a `hook` question, "Cost cap": a parent waiting on it (`delegate`, `delegate_result`) gets it back as `status: question` with the `chi answer` commands, `--option Continue` or `--option Stop`. A **background** child (`wait: false`) paused at its cap does not wake its parent: delegate reports skip hook questions (they are the user's, on the child's card) and the approval relay carries approvals only, so the child waits on its card, with the web's bell. The parent sees it at its next `delegate_result`.
 - **A child's approvals go to the parent's user** (the approval relay). While the parent waits (`delegate`, `delegate_result`), a guardrail approval the child opens reopens as the parent session's own approval: the same card in the parent's web page and attached terminal, with the same facts and diff, a line naming the delegate and its task (`delegate ab12 · fix the flaky spec…`, linked to its session) and the header `Approve delegate ab12's tool call?`. The options are the child's, by index; "for the session" says it is the delegate's session (the session scope keys on the child; repo and rule approvals are one shared store). The user answers once there; the parent's model never sees the approval, only one line per relayed approval in the tool's result, before the reply: `approval relayed to your user: execute: git push origin main → allowed once` (or `denied ("why")`, `dismissed (denied)`, `answered on the child`, `not delivered (the child's worker is gone)`, `refused by the child …`, `still open (your turn was stopped)`). The time the card is open doesn't count against `timeout`. While the parent waits on one child, its other running children's approvals are relayed too, oldest first, one card at a time (`+1 more delegate waiting`); each outcome comes in that child's next result.
   - The child's own card stays answerable (the first answer wins: answered there, the parent's card closes as "answered in ab12"). While relayed it says `Waiting for approval in parent ab12: answering here works too`; `chi sessions list` shows the child as `waiting (in parent ab12)` (`--format json`: `relayed_to`), and the web's bell rings for the parent's card, not the child's.
   - How the child trusts it: the parent's POST that says "answered" (Bridge `POST /session/<child>/relay`) carries no answer. The child asks its parent session's live Bridge (`POST /session/<parent>/relay/status`), which reports only what the parent's question flow took from a UI (`RelayDesk`, in memory only), and takes it only for this child, the question pending now, answered. A parent agent's answer on the relay card (a piped or marked `chi --attach PARENT`, `chi answer`) is held to `guardrails.parent_approvals` by the parent and again by the child.

data/docs/sub-agent.md

@@ -105,6 +105,10 @@ A chi parent's `delegate_result` gets a child's step-limit question back as a
 `delegate session:` (which drops the question), or report back. It isn't
 relayed to the parent's user the way approvals are.
 
+A session at its cost cap (the [cost-cap bundle](plugins.md#the-cost-cap-bundle)) waits the same way, as a
+question of kind `hook` with header "Cost cap" and options `Continue` and `Stop`: `--option Continue` raises the cap
+by another cap's worth and the turn goes on, `--option Stop` ends it `canceled` with `stopped_by: cost-cap`.
+
 ## Approvals
 
 A chi parent (the `delegate` tool) doesn't go through any of this: its

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

@@ -1,13 +1,15 @@
 ---
 name: core
-version: 0.3.1
+version: 0.3.2
 scope: system
 description: "Recommended safety set"
 trust_level: reviewed
-requires_chi: ">= 0.60.0"
+# Its members' highest floor (cost-cap's)
+requires_chi: ">= 0.83.0"
 includes:
 - loop-guard
 - check-in
 - guardrails
 - slow-commands
 - agents-md
+- cost-cap

data/lib/samagotchi/bundles/cost-cap/manifest.yml

@@ -0,0 +1,11 @@
+---
+name: cost-cap
+version: 0.1.0
+scope: system
+description: "A per-session $ cap: at the cap the turn pauses on Continue (another cap's worth) / Stop, a warning at 80% goes to the user only; /cap shows or sets it"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:bc6683af0063b90d6a3d7c2796bccf446043dfb1b3f07c04bd54d22d26199e1d
+# ctx.cost is new in chi 0.83.0
+requires_chi: ">= 0.83.0"

data/lib/samagotchi/bundles/cost-cap/plugin.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+# The cost-cap bundle (docs/plugins.md, The cost-cap bundle): a per-session
+# cap on what the session spends (ctx.cost: reported + estimated, side
+# requests included). Before each generation it compares the spend with
+# the cap: at warn_at of it the user (only) gets one notice, at the cap the
+# turn pauses on a question, Continue (the cap goes up by a step) or Stop
+# (the turn stops, with a card). With no one to ask it stops. The model
+# never sees any of it: no tool, no steer, no prompt text.
+#
+# Settings (config.yml, bundles: cost-cap:), read at each use from
+# ctx.settings, never at load:
+#   default: 5.00   USD cap for a session with none set; absent/0/off: none
+#   child: 2.00     for delegate children (ctx.delegate?); absent: default
+#   warn_at: 0.8    the share of the cap that warns; 0/off: no warning
+#
+# State: <data_dir>/sessions/<session id>.json, {"cap": 3.0, "step": 3.0},
+# written by /cap and by Continue; "cap": null (or false) is off for the
+# session, over the config. Without a file the cap comes from the settings.
+# The cap is resolved once per session id (ctx.delegate? parses the session
+# file) and kept until /cap or Continue writes a new one.
+require "json"
+require "fileutils"
+
+class Plugin
+  USAGE = "usage: /cap [N | $N | off] (USD; /cap alone shows the spend)"
+  OPTIONS = %w[Continue Stop].freeze
+  WARN_AT = 0.8
+
+  def initialize(_settings)
+    @mutex = Mutex.new
+    @resolved = nil        # {session:, cap:, step:}
+    @warned = nil          # [session id, cap] the share warning was given for
+    @unknown_warned = nil  # the session id the "can't be enforced" notice was given for
+  end
+
+  def register(chi)
+    chi.on(:before_generation) { |_event, ctx| check(ctx) }
+    # Only the "can't be enforced" notice: a turn of one generation (or a
+    # session's last) has no next before_generation to give it.
+    chi.on(:after_generation) { |_event, ctx| check_known(ctx) }
+    chi.command("/cap", "see or set this session's cost cap: /cap, /cap 5, /cap off", anytime: true) do |args, ctx|
+      command(args, ctx)
+    end
+  end
+
+  # The cap in USD (a positive Float) or nil (none, 0, off, false).
+  def self.amount(value)
+    number = case value
+             when Numeric then value.to_f
+             when String then value.strip.delete_prefix("$").then { |s| s.match?(/\A\d+(\.\d+)?\z/) ? s.to_f : nil }
+             end
+    number&.positive? ? number : nil
+  end
+
+  # Cents, or up to four decimals under $0.10, so a small cap (/cap 0.003)
+  # doesn't read "$0.00 spent of $0.00".
+  def self.money(value)
+    return format("$%.2f", value) if value.zero? || value.abs >= 0.1
+
+    format("$%.4f", value).sub(/(\.\d\d\d*?)0+\z/, '\1')
+  end
+
+  private
+
+  def check(ctx)
+    resolved = resolve(ctx)
+    cap = resolved[:cap]
+    return unless cap
+
+    cost = ctx.cost
+    return unenforceable(ctx, resolved[:session], cap) unless cost.known?
+
+    total = cost.total
+    return at_cap(ctx, resolved, cost) if total >= cap
+
+    share = warn_share(ctx)
+    return unless share && total >= share * cap
+    return unless first_time?(:@warned, [resolved[:session], cap])
+
+    ctx.notify("#{money(total)} of #{money(cap)} spent (#{(total / cap * 100).floor}%)", level: :warn)
+  end
+
+  def check_known(ctx)
+    resolved = resolve(ctx)
+    return unless resolved[:cap]
+
+    unenforceable(ctx, resolved[:session], resolved[:cap]) unless ctx.cost.known?
+  end
+
+  def unenforceable(ctx, session, cap)
+    return unless first_time?(:@unknown_warned, session)
+
+    ctx.notify("the #{money(cap)} cap can't be enforced: #{ctx.model || "the model"} reports no cost and has no price",
+               level: :warn)
+  end
+
+  def at_cap(ctx, resolved, cost)
+    cap = resolved[:cap]
+    raised = raised_cap(cap, resolved[:step] || cap, cost.total)
+    answer = ctx.ask_user(question: "Cost cap reached: #{money(cost.total)} spent of #{money(cap)}. " \
+                                    "Continue raises it to #{money(raised)}.",
+                          header: "Cost cap", options: OPTIONS)
+    if continue?(answer)
+      save(ctx, resolved[:session], "cap" => raised, "step" => resolved[:step] || cap)
+      ctx.notify("cap raised to #{money(raised)}")
+    else
+      stop(ctx, cap, cost)
+    end
+  end
+
+  # Another step on the cap, as many steps as it takes to pass the spend
+  # (a turn that overshot by more than a step asks once, not each step).
+  def raised_cap(cap, step, total)
+    raised = cap + step
+    raised += step while raised <= total
+    raised.round(6)
+  end
+
+  def continue?(answer)
+    return false unless answer
+
+    Array(answer[:selected]).first == "Continue" || Array(answer[:selected_indices]).first&.zero?
+  end
+
+  def stop(ctx, cap, cost)
+    return unless ctx.stop_turn("cost cap reached (#{money(cost.total)} of #{money(cap)})")
+
+    ctx.card(title: "cost-cap stopped the turn",
+             body: "Spent #{breakdown(cost)} of a #{money(cap)} cap.\n\n`/cap N` raises it, `/cap off` removes it.",
+             level: :warn)
+  end
+
+  def command(args, ctx)
+    arg = args.to_s.strip.downcase
+    return show(ctx) if arg.empty?
+
+    session = ctx.session_id
+    return "cost-cap: no session yet" unless session
+
+    if %w[off 0].include?(arg)
+      save(ctx, session, "cap" => nil)
+      return "cost-cap: no cap for this session"
+    end
+    value = arg.match?(/\A\$?\d+(\.\d+)?\z/) ? self.class.amount(arg) : nil
+    return USAGE unless value
+
+    save(ctx, session, "cap" => value, "step" => value)
+    "cost-cap: cap set to #{money(value)} (#{money(ctx.cost.total)} spent)"
+  rescue StandardError => e
+    "cost-cap: #{e.message}"
+  end
+
+  def show(ctx)
+    cost = ctx.cost
+    cap = resolve(ctx)[:cap]
+    return "cost-cap: no cap (#{money(cost.total)} spent)" unless cap
+
+    line = "cost-cap: #{money(cost.total)} spent of #{money(cap)} (#{parts(cost)})"
+    cost.known? ? line : "#{line} (can't be enforced: no cost reported or priced)"
+  end
+
+  def parts(cost) = "reported #{money(cost.reported)}, estimated #{money(cost.estimated)}, side #{money(cost.side)}"
+
+  def breakdown(cost) = "#{money(cost.total)} (#{parts(cost)})"
+
+  # The session's cap and step now: the state file's, else child: for a
+  # delegate, else default:. Cached per session id.
+  def resolve(ctx)
+    session = ctx.session_id
+    cached = @mutex.synchronize { @resolved }
+    return cached if cached && cached[:session] == session
+
+    resolved = { session: session, **(state(ctx, session) || configured(ctx)) }
+    @mutex.synchronize { @resolved = resolved }
+  end
+
+  def state(ctx, session)
+    return nil unless session
+
+    saved = JSON.parse(File.read(state_path(ctx, session)))
+    return nil unless saved.is_a?(Hash) && saved.key?("cap")
+
+    cap = self.class.amount(saved["cap"])
+    { cap: cap, step: self.class.amount(saved["step"]) || cap }
+  rescue Errno::ENOENT, JSON::ParserError
+    nil
+  end
+
+  def configured(ctx)
+    settings = ctx.settings
+    return { cap: nil, step: nil } unless settings.key?("default") || settings.key?("child")
+
+    key = settings.key?("child") && ctx.delegate? ? "child" : "default"
+    cap = self.class.amount(settings[key])
+    { cap: cap, step: cap }
+  end
+
+  def warn_share(ctx)
+    settings = ctx.settings
+    return WARN_AT unless settings.key?("warn_at")
+
+    share = settings["warn_at"]
+    share.is_a?(Numeric) && share.positive? ? share : nil
+  end
+
+  def save(ctx, session, data)
+    path = state_path(ctx, session)
+    FileUtils.mkdir_p(File.dirname(path))
+    Samagotchi::AtomicFile.write(path, "#{JSON.generate(data)}\n")
+    cap = self.class.amount(data["cap"])
+    @mutex.synchronize { @resolved = { session: session, cap: cap, step: self.class.amount(data["step"]) || cap } }
+  end
+
+  def state_path(ctx, session) = File.join(ctx.data_dir, "sessions", "#{session.gsub(/[^A-Za-z0-9_.-]/, "_")}.json")
+
+  def money(value) = self.class.money(value)
+
+  # Whether +key+ is new for the once-only notice kept in +ivar+ (and keep it).
+  def first_time?(ivar, key)
+    @mutex.synchronize do
+      next false if instance_variable_get(ivar) == key
+
+      instance_variable_set(ivar, key)
+      true
+    end
+  end
+end

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

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

data/lib/samagotchi/child_reports.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "securerandom"
 require_relative "client_id"
 require_relative "session"
 require_relative "session_inbox"
@@ -129,7 +130,7 @@ module Samagotchi
     # (DelegateWait.finish, its report variant), the cursor it moves the child to,
     # and the cursor it was read from (a commit after the model moved it
     # itself, with delegate_result, leaves it alone).
-    Report = Data.define(:child_id, :text, :before, :after, :rings) do
+    Report = Data.define(:child_id, :text, :before, :after, :rings, :claim_id) do
       def line(mark: nil) = Steer::Line.new(text: text, source: ChildReports::SOURCE, mark: mark)
       def origin = { client_id: "#{ClientId::CHILD_PREFIX}#{child_id[0, 8]}" }
     end
@@ -142,6 +143,7 @@ module Samagotchi
       @state_dir = state_dir
       @session_dir = Session.session_dir(session_id, state_dir: state_dir)
       @predecessor_dir = Session.valid_id?(predecessor) ? Session.session_dir(predecessor, state_dir: state_dir) : nil
+      Tools::DelegateCursors.clear_report_claims(@session_id, state_dir: @state_dir)
       # child id → the Report this turn took for it (rings merged).
       @taken = {}
     end
@@ -177,12 +179,16 @@ module Samagotchi
     end
 
     # The turn that took the reports was kept: move each child's cursor on
-    # (unless something else moved it since: the model's own
-    # delegate_result), then delete the rings.
+    # and delete the rings.
     def commit
       @taken.each_value do |report|
         Tools::DelegateCursors.update(@session_id, report.child_id, state_dir: @state_dir) do |cursor|
-          cursor == report.before ? report.after : cursor
+          next cursor unless cursor.report_claim&.fetch("id", nil) == report.claim_id
+
+          before = report.before.with(report_claim: nil)
+          after = report.after.with(report_claim: nil)
+          current = cursor.with(report_claim: nil)
+          current == before ? after : current
         end
         delete_rings(report.rings)
       rescue StandardError => e
@@ -193,6 +199,11 @@ module Samagotchi
 
     # The turn was rolled back: its rings stay for the next one.
     def release
+      @taken.each_value do |report|
+        Tools::DelegateCursors.update(@session_id, report.child_id, state_dir: @state_dir) do |cursor|
+          cursor.report_claim&.fetch("id", nil) == report.claim_id ? cursor.with(report_claim: nil) : cursor
+        end
+      end
       @taken = {}
     end
 
@@ -237,13 +248,19 @@ module Samagotchi
                                       timeout: 0, turn: before.turn)
       return nil unless reportable?(wait)
 
-      # A reported end is the follow-up turn's too (DelegateCursor#turn):
-      # a later wait on it would repeat its reply.
+      claim_id = before.report_claim&.fetch("id", nil) || SecureRandom.hex(16)
       after = before.with(reply_file: wait.status == :done ? wait.file : before.reply_file,
-                          turn: wait.status == :waiting_for_answer ? before.turn : nil)
+                          turn: wait.status == :waiting_for_answer ? before.turn : nil, report_claim: nil)
                     .with_baseline(ReplyWait.baseline_of(wait.session))
+      claim = { "id" => claim_id, "file" => wait.file, "cursor" => after.to_json_hash }
+      return nil unless Tools::DelegateCursors.claim_report(@session_id, child_id, expected: before, claim: claim,
+                                                            state_dir: @state_dir)
+
+      # A reported end is the follow-up turn's too (DelegateCursor#turn):
+      # a later wait on it would repeat its reply.
+      after = after.with(report_claim: claim)
       text = Tools::DelegateWait.finish(wait, child_id, timeout: 0, report: true)
-      Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings)
+      Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings, claim_id: claim_id)
     rescue ArgumentError
       nil # the child is gone
     end

data/lib/samagotchi/engine.rb

@@ -2581,7 +2581,8 @@ module Samagotchi
         # build and after a rebuild that drops them (SystemPrompt#prompt_files
         # returns [] itself: the || keeps a nil builder safe).
         prompt_files: -> { @prompt_builder&.prompt_files || [] },
-        frontend: -> { interface }
+        frontend: -> { interface },
+        cost: -> { @metrics.cost }
       )
     end
 

data/lib/samagotchi/plugin/context.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require_relative "../log"
 require_relative "../paths"
+require_relative "../session_metrics/cost"
 require_relative "../guardrails/context"
 require_relative "../idle_client"
 require_relative "service"
@@ -51,10 +52,11 @@ module Samagotchi
     # ctx.http call without cancel: uses, nil for none: an init task's own,
     # else the running turn's for work done for it (the turn's thread, or a
     # plugin handler: +handler+) until the turn has ended.
+    # +cost+ returns the session's spend now (SessionMetrics::Cost).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
-                      :cancel_controller, keyword_init: true)
+                      :cancel_controller, :cost, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -140,6 +142,11 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # @return [SessionMetrics::Cost] the session's spend so far, read now:
+      #   #total, #reported, #estimated, #side (Float USD) and #known?
+      #   (docs/plugins.md); zero and known with no session
+      def cost = @host.cost&.call || SessionMetrics::Cost.zero
+
       # @return [String, nil] the name of the session's toolkit ("full" for
       #   one from before toolkits; nil with no session)
       def toolkit = @host.toolkit&.call

data/lib/samagotchi/reply_wait.rb

@@ -181,8 +181,9 @@ module Samagotchi
            (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
            baseline && ended == baseline[:last_turn]
           file = newest_reply(id, state_dir: state_dir)
-          if file && reply_is_turns?(file, ended)
-            reply = Result.new(status: :done, text: File.read(File.join(reply_dir(id, state_dir: state_dir), file)), file: file)
+          path = File.join(reply_dir(id, state_dir: state_dir), file) if file
+          if file && reply_is_turns?(path, ended)
+            reply = Result.new(status: :done, text: File.read(path), file: file)
             reply.session = settled(session, id, state_dir: state_dir)
             return reply
           end
@@ -194,6 +195,9 @@ module Samagotchi
            !(session.status == Session::STATUS_RUNNING && session.interrupted_turn&.enqueued_id == turn) &&
            (ended = session.last_turn&.ended_at) && !ended.to_s.empty? &&
            baseline && ended == baseline[:last_turn]
+          # The turn-specific reply lookup above already found its file, if
+          # one exists. Without it, don't use the newest file as a fallback:
+          # it could belong to another turn.
           return no_reply(session, baseline, fresh: true)
         end
 
@@ -440,19 +444,13 @@ module Samagotchi
       cursor.nil? || file > cursor
     end
 
-    # Whether the reply file +file+ is the turn that ended at +ended_at+'s,
-    # not an earlier turn's: the worker records the ended_at, then writes
-    # the reply (SessionInbox.write_output: the name's timestamp is the
-    # write time, at least the ended_at); every earlier turn's file is
-    # older than the turn's end. The wait and the session run on one
-    # machine, so the name's local-time read is the writer's. A name that
-    # doesn't read as a time isn't the turn's.
-    def reply_is_turns?(file, ended_at)
-      name = file.to_s
-      return false if name.length < 23
-
-      Time.parse(ended_at.to_s) <= Time.strptime(name[0, 14], "%Y%m%d%H%M%S") + (name[14, 9].to_f / (10**9))
-    rescue ArgumentError
+    # Whether the reply file at +path+ is the turn that ended at +ended_at+'s,
+    # not an earlier turn's: the worker records ended_at before writing the
+    # reply, so its mtime is at least the turn's end and earlier replies'
+    # mtimes precede it. Unlike the filename, mtime is independent of TZ.
+    def reply_is_turns?(path, ended_at)
+      File.mtime(path) >= Time.parse(ended_at.to_s)
+    rescue ArgumentError, SystemCallError
       false
     end
 

data/lib/samagotchi/session_metrics/cost.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionMetrics
+    # The session's spend so far (SessionMetrics#cost, what a bundle's
+    # ctx.cost reads), in USD: +reported+ by providers (usage.cost) and
+    # +estimated+ from configured prices (ModelPrice.estimate: a generation
+    # is one or the other, never both), each the main loop's and the side
+    # requests' together; +side+ is the side requests' share of the total
+    # (recap, /btw, ask_model). +known+ is false while generations or side
+    # requests ran but none was reported or priced: a cap can't be enforced
+    # on such a session. A session with some priced and some unpriced
+    # generations reads known (the unpriced ones count 0).
+    # Bundles use its methods only, never this constant's name.
+    Cost = Data.define(:reported, :estimated, :side, :known) do
+      def self.zero = new(reported: 0.0, estimated: 0.0, side: 0.0, known: true)
+
+      # @param totals [Totals] the session's sums, the running turn folded in
+      # @param side [SideTotals]
+      # @return [Cost]
+      def self.of(totals, side)
+        side_reported = side.cost_sum.to_f
+        side_estimated = side.cost_estimate_sum.to_f
+        reported = totals.cost_sum.to_f + side_reported
+        estimated = totals.cost_estimate_sum.to_f + side_estimated
+        ran = (totals.prompt_sum + totals.completion_sum).positive? || side.requests.positive?
+        new(reported: reported, estimated: estimated, side: side_reported + side_estimated,
+            known: !ran || reported.positive? || estimated.positive?)
+      end
+
+      # @return [Float] reported + estimated, side requests included
+      def total = reported + estimated
+
+      def known? = known
+    end
+  end
+end

data/lib/samagotchi/session_metrics.rb

@@ -12,6 +12,7 @@ require_relative "model_price"
 require_relative "session"
 require_relative "session_metrics/totals"
 require_relative "session_metrics/model_segment"
+require_relative "session_metrics/cost"
 require_relative "session_metrics/side_totals"
 require_relative "side_usage"
 
@@ -365,6 +366,14 @@ module Samagotchi
       end
     end
 
+    # The session's spend now (ctx.cost): its turns' sums with the running
+    # turn's finished generations folded in, and its side requests.
+    # Safe from any thread.
+    # @return [Cost]
+    def cost
+      @mutex.synchronize { Cost.of(@totals.with_running(@turn), @side) }
+    end
+
     # Event sink. Safe to call from any thread; errors are isolated by the
     # caller (SessionObserver / TerminalUI) but we still guard internally.
     # @param event [Hash]

data/lib/samagotchi/testing/host.rb

@@ -2,6 +2,7 @@
 
 require_relative "../cancellation_controller"
 require_relative "../plugin/context"
+require_relative "../session_metrics/cost"
 require_relative "recorder"
 
 module Samagotchi
@@ -48,9 +49,33 @@ module Samagotchi
           toolkit: -> { recorder[:toolkit] },
           declared_tools: -> { recorder[:declared_tools] || tool_names.call },
           use_toolkit: ->(name) { recorder.use_toolkit(name, toolkits.call) },
-          cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil }
+          cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
+          cost: -> { cost(recorder[:cost]) }
         )
       end
+
+      # The parts a test may give bundle.set(cost: {...}).
+      COST_PARTS = %i[reported estimated side known].freeze
+
+      # The SessionMetrics::Cost ctx.cost returns for the recorder's +cost+
+      # value (Recorder::DEFAULTS).
+      # @return [SessionMetrics::Cost]
+      def cost(value)
+        value = value.call while value.respond_to?(:call)
+        case value
+        when nil then SessionMetrics::Cost.zero
+        when SessionMetrics::Cost then value
+        when Numeric then SessionMetrics::Cost.zero.with(reported: value.to_f)
+        when Hash
+          unknown = value.keys.map(&:to_sym) - COST_PARTS
+          raise ArgumentError, "unknown cost parts: #{unknown.join(", ")}" unless unknown.empty?
+
+          parts = value.transform_keys(&:to_sym)
+          SessionMetrics::Cost.new(reported: parts.fetch(:reported, 0).to_f, estimated: parts.fetch(:estimated, 0).to_f,
+                                   side: parts.fetch(:side, 0).to_f, known: parts.fetch(:known, true))
+        else raise ArgumentError, "cost: a number, a Hash or a callable, not #{value.inspect}"
+        end
+      end
     end
 
     # The hook runtime (Hooks::Runtime: event[:notify] and the other

data/lib/samagotchi/testing/recorder.rb

@@ -32,7 +32,10 @@ module Samagotchi
       DEFAULTS = {
         session_id: "test-session", cwd: nil, messages: [], messages_partial: false, model_name: "test:model",
         model_key: "model", toolkit: "full", declared_tools: nil, frontend: :worker, scratch: false, setup: nil,
-        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true
+        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true,
+        # ctx.cost: nil (zero), a Float (reported USD), a Hash of the parts
+        # (reported:, estimated:, side:, known:) or a callable giving one.
+        cost: nil
       }.freeze
 
       attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :answers,

data/lib/samagotchi/tools/delegate_cursor.rb

@@ -14,8 +14,9 @@ module Samagotchi
     # of the child's turn the last follow-up went to (Delegate.follow_up),
     # whose own reply a wait takes (ReplyWait's turn:); nil once that turn
     # was reported, or when unknown (a new child, an older worker).
-    DelegateCursor = Data.define(:reply_file, :last_turn, :question_id, :messages, :turn) do
-      def initialize(reply_file: nil, last_turn: nil, question_id: nil, messages: nil, turn: nil) = super
+    #   +report_claim+: a report reserved until the parent's turn is settled.
+    DelegateCursor = Data.define(:reply_file, :last_turn, :question_id, :messages, :turn, :report_claim) do
+      def initialize(reply_file: nil, last_turn: nil, question_id: nil, messages: nil, turn: nil, report_claim: nil) = super
 
       def self.empty = new
 
@@ -33,6 +34,13 @@ module Samagotchi
       end
 
       def to_json_hash = to_h.transform_keys(&:to_s).compact
+
+      def self.from_json_hash(data)
+        return empty unless data.is_a?(Hash)
+
+        new(reply_file: data["reply_file"], last_turn: data["last_turn"], question_id: data["question_id"],
+            messages: data["messages"], turn: data["turn"], report_claim: data["report_claim"])
+      end
     end
 
     # The parent's cursors, one per child, in <parent dir>/delegates.json, so
@@ -68,6 +76,40 @@ module Samagotchi
         end
       end
 
+      # Reserve a report only if the cursor read to build it is still current.
+      # @return [DelegateCursor, nil] the reserved cursor, or nil if another path moved it
+      def claim_report(parent_id, child_id, expected:, claim:, state_dir:)
+        locked(parent_id, state_dir: state_dir) do
+          all = read(parent_id, state_dir: state_dir)
+          cursor = get_from(all, child_id)
+          next nil unless cursor == expected
+
+          claimed = cursor.with(report_claim: claim)
+          all[child_id] = claimed.to_json_hash
+          write(parent_id, all, state_dir: state_dir)
+          claimed
+        end
+      end
+
+      # A new owner can retry reports left reserved by a worker that exited
+      # before committing or releasing its turn. No cursor file means no
+      # claims: the lock would create the session dir and its lock file, so
+      # an empty session would no longer count as empty.
+      def clear_report_claims(parent_id, state_dir:)
+        return unless File.exist?(path(parent_id, state_dir: state_dir))
+
+        locked(parent_id, state_dir: state_dir) do
+          all = read(parent_id, state_dir: state_dir)
+          changed = false
+          all.each_value do |data|
+            next unless data.is_a?(Hash)
+
+            changed = true if data.delete("report_claim")
+          end
+          write(parent_id, all, state_dir: state_dir) if changed
+        end
+      end
+
       # Add the cursors of +entries+ (child id → cursor fields, as #read
       # gives them) that the parent has none for; one it has is kept.
       # @return [Array<String>] the child ids added
@@ -94,11 +136,7 @@ module Samagotchi
       end
 
       def get_from(all, child_id)
-        data = all[child_id]
-        return DelegateCursor.empty unless data.is_a?(Hash)
-
-        DelegateCursor.new(reply_file: data["reply_file"], last_turn: data["last_turn"],
-                           question_id: data["question_id"], messages: data["messages"], turn: data["turn"])
+        DelegateCursor.from_json_hash(all[child_id])
       end
 
       def path(parent_id, state_dir:)

data/lib/samagotchi/tools/delegate_wait.rb

@@ -24,6 +24,7 @@ module Samagotchi
     # the wait's first look (a fast failure) still ends it. The cursors are
     # on disk (DelegateCursors), so a respawned worker doesn't repeat a reply.
     module DelegateWait
+      Advance = Data.define(:cursor, :already_reported)
       TIMEOUT_DEFAULT = 600
       POLL_INTERVAL = 0.5
       # Seconds with no worker before the child counts as gone: as long as
@@ -66,6 +67,11 @@ module Samagotchi
         reports = reports_mode(peers)
         others = relay && others_for(peers.session_id, child_id, relay, sd)
         cursor = DelegateCursors.get(peers.session_id, child_id, state_dir: sd)
+        report_claim = cursor.report_claim
+        if report_claim
+          cursor = DelegateCursor.from_json_hash(report_claim["cursor"]).with(report_claim: report_claim)
+        end
+
         baseline = cursor.baseline
         left = timeout.to_i
         outcomes = relayed_outcomes.delete(key) || []
@@ -78,7 +84,13 @@ module Samagotchi
           left -= monotonic - started
           unless wait.status == :waiting_for_answer && DelegateRelay.relayable?(relay, wait.question)
             outcomes.concat(relayed_outcomes.delete(key) || [])
-            advance(peers.session_id, child_id, wait, state_dir: sd)
+            movement = advance(peers.session_id, child_id, wait, state_dir: sd)
+            if movement&.already_reported
+              file = movement.cursor.report_claim&.fetch("file", nil) || wait.file
+              return already_reported_result(child_id, file, state_dir: sd)
+            end
+            return already_reported_result(child_id, report_claim["file"], state_dir: sd) if report_claim && wait.status == :timeout
+
             text = with_outcomes(finish(wait, child_id, timeout: timeout, reports: reports), outcomes)
             return RefText.wrap(text, reply_path(child_id, wait, state_dir: sd))
           end
@@ -159,15 +171,37 @@ module Samagotchi
       # was reported; a question keeps it. Nothing moves on a timeout or a
       # cancel.
       # @param wait [ReplyWait::Result]
-      # @return [DelegateCursor, nil] the new cursor
+      # @return [Advance, nil] the cursor and whether another path reported it
       def advance(parent_id, child_id, wait, state_dir:)
         return nil unless REPORTED.include?(wait.status) && wait.session
 
-        DelegateCursors.update(parent_id, child_id, state_dir: state_dir) do |cursor|
-          cursor = cursor.with(reply_file: wait.file) if wait.status == :done
-          cursor = cursor.with(turn: nil) unless wait.status == :waiting_for_answer
-          cursor.with_baseline(ReplyWait.baseline_of(wait.session))
+        already_reported = false
+        cursor = DelegateCursors.update(parent_id, child_id, state_dir: state_dir) do |current|
+          if (current.report_claim && current.report_claim["file"] == wait.file) ||
+             (wait.status == :done && current.reply_file == wait.file)
+            already_reported = true
+            next current
+          end
+
+          current = current.with(reply_file: wait.file) if wait.status == :done
+          current = current.with(turn: nil) unless wait.status == :waiting_for_answer
+          current.with_baseline(ReplyWait.baseline_of(wait.session))
         end
+        Advance.new(cursor: cursor, already_reported: already_reported)
+      end
+
+      def already_reported_result(child_id, file, state_dir:)
+        path = if file.to_s.empty?
+                 nil
+               else
+                 File.join(ReplyWait.reply_dir(child_id, state_dir: state_dir), file)
+               end
+        text = if path
+                 "session: #{child_id}\nstatus: reported\nThe reply was already reported to this session (file: #{File.basename(file)})."
+               else
+                 "session: #{child_id}\nstatus: reported\nThe child's latest status was already reported to this session."
+               end
+        RefText.wrap(text, path)
       end
 
       # The tool result for how the wait ended.

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.82.0"
+  VERSION = "0.83.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.82.0
+  version: 0.83.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -200,6 +200,8 @@ files:
 - lib/samagotchi/bundles/coordinator/plugin.rb
 - lib/samagotchi/bundles/coordinator/skill_coordinator.md
 - lib/samagotchi/bundles/core/manifest.yml
+- lib/samagotchi/bundles/cost-cap/manifest.yml
+- lib/samagotchi/bundles/cost-cap/plugin.rb
 - lib/samagotchi/bundles/dev/manifest.yml
 - lib/samagotchi/bundles/github-pr/manifest.yml
 - lib/samagotchi/bundles/github-pr/plugin.rb
@@ -469,6 +471,7 @@ files:
 - lib/samagotchi/session_inbox.rb
 - lib/samagotchi/session_manager.rb
 - lib/samagotchi/session_metrics.rb
+- lib/samagotchi/session_metrics/cost.rb
 - lib/samagotchi/session_metrics/model_segment.rb
 - lib/samagotchi/session_metrics/side_totals.rb
 - lib/samagotchi/session_metrics/totals.rb