@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/README.md

@@ -20,7 +20,7 @@ workspaces and premium packs delivered as private-marketplace plugins.
 
 ## Status
 
-**Current release: `0.2.0`** — recorded in [`CHANGELOG.md`](CHANGELOG.md), which is also the honest
+**Current release: `0.4.0`** — recorded in [`CHANGELOG.md`](CHANGELOG.md), which is also the honest
 account of what the release does *not* contain.
 
 This is pre-release software. The leading `0.` is meant literally: nothing here is stable yet, and
@@ -100,7 +100,13 @@ node cli/doctor.mjs examples
 
 To adopt Portulan in your own repository, `portulan init` interviews you, scans the codebase and
 drafts a workspace; `portulan doctor` validates it; `portulan compile` turns your gate policy into
-host enforcement.
+host enforcement. At a terminal, an in-repo draft offers an optional always-tier budget before writing.
+The offer covers current and projected guidance in both supported formats at your explicit ratio.
+Declining or an initially unavailable projection leaves it undeclared. After final confirmation,
+init checks the accepted cap against fresh project inputs. An insufficient cap, a newly unavailable
+measurement or a changed effective handoff cutoff stops before writing and asks you to run init again.
+The cutoff uses eligible dated Markdown handoffs; unrelated filenames cannot advance it. Invalid
+selected dates or file types, or an uninspectable series, stop record-cap adoption before writing.
 
 ## Command-line interface
 
@@ -119,7 +125,7 @@ commit, refusing any packed file that differs from its source.
 |---|---|
 | [`init`](cli/init.mjs) | Interview plus codebase scan, producing a drafted workspace |
 | [`doctor`](cli/doctor.mjs) | Validate a workspace against the Workspace Definition |
-| [`compile`](cli/compile.mjs) | Turn gates and verify recipes into host enforcement |
+| [`compile`](cli/compile.mjs) | Turn gates and verify recipes into host enforcement, guidance into host tiers, and declared persona fields into existing plugin or project agent bindings |
 | [`vendor`](cli/vendor.mjs) | Materialise a workspace where it is needed, in either direction |
 | [`index`](cli/index.mjs) | Rebuild the declared indexes over memory, handoffs and personas; print changelog fragments for a release |
 | [`upgrade`](cli/upgrade.mjs) | Migrate a workspace across Workspace Definition versions |
@@ -138,7 +144,7 @@ are not subcommands at all. [`cli/README.md`](cli/README.md), rendered from the
 | `cli/` | [The Node CLI](cli/) described above, plus its tests and the compiled-hook runners |
 | `packs/` | [Composable packs](packs/) — `stacks/`, `tools/`, `rituals/` |
 | `plugin/` | [The Claude Code adapter](plugin/): the `/portulan` boot skill |
-| `agents/` | [The three personas bound to this host's tools](agents/) — `implementer`, `reviewer`, `librarian`. A platform-fixed location; the doctrine they bind stays in [`core/personas/`](core/personas/) |
+| `agents/` | [Host bindings](agents/) for the core implementer, reviewer and librarian plus the composed supervisor and local-worker. Their charters stay in core or the contributing pack; ordinary projects bind roles under `.claude/agents/` |
 | `examples/` | [A fictional, public demo workspace](examples/) — two products, read end to end |
 | `docs/` | [`vision.md`](docs/vision.md) (the constitution), [`plan.md`](docs/plan.md) (the milestone map) and [`milestones/`](docs/milestones/) — one file per milestone from 12 on, holding amendment arguments, session notes and close evidence (milestones 0 to 11 read with `git show 8a33f9b:docs/milestones/mNN.md`) |
 | `evals/` | [The eval corpora](evals/) — golden tasks for the compiled gates and for the core skills — plus the review-loop register, the A/B corpus with its arms, graders and recorded baseline, and [`evals/releases/`](evals/releases/), the eval result each release from `0.1.3` onward carries. **No count is written here**; `git ls-files evals` derives it. _(This cell has now recorded going stale twice, and this is the second repair: it said the **graders** and the **baseline run** were *still to arrive* after both landed on 2026-08-31. The sentence that expires is always the one naming what is next, so this cell no longer names one — what is unbuilt lives in [`evals/README.md`](evals/README.md)'s own *What is NOT built yet*, which is the single carrier for it and is checked by nothing, exactly as this cell was.)_ |
@@ -173,3 +179,8 @@ channels in the order to try them, what is in scope, and what response you can a
 ## License
 
 [Apache-2.0](LICENSE) © 2026 Sleepy Panda SRL. See [`NOTICE`](NOTICE).
+
+`portulan doctor --count-tokens MODEL_ID .portulan` optionally sends the measured project always corpus
+to Anthropic for a provider token estimate, using `ANTHROPIC_API_KEY` from the environment. The
+[counting boundary](core/operating/context.md#the-always-tier-is-budgeted-in-tokens) explains exclusions,
+manual ratio assessment and why the estimate is not actual complete host usage. Verification remains offline.

package/cli/README.md

@@ -22,7 +22,7 @@ in [`../.portulan/verify/`](../.portulan/verify/), and its operator tooling in
 |---|---|
 | [`portulan.mjs`](portulan.mjs) | Portulan — the one entry point the `npx` package exposes. |
 | [`init.mjs`](init.mjs) | `portulan init`: draft a workspace for a repository that has none. |
-| [`doctor.mjs`](doctor.mjs) | `portulan doctor`: validate a workspace against the Workspace Definition. |
+| [`doctor.mjs`](doctor.mjs) | `portulan doctor`: validate a workspace and report branch-owned host tokens beside local receipts; --static skips usage records. |
 | [`compile.mjs`](compile.mjs) | `portulan compile`: compile a workspace's gate policy into host enforcement. |
 | [`vendor.mjs`](vendor.mjs) | `portulan vendor`: materialise a workspace where it is needed: into a host, or between residences. |
 | [`index.mjs`](index.mjs) | `portulan index`: regenerate the memory, handoff and scope indexes. |
@@ -37,8 +37,8 @@ Run by the hooks `compile` writes into a host's settings, never by a person.
 | File | What it is |
 |---|---|
 | [`gate.mjs`](gate.mjs) | The PreToolUse gate runner — the *explanation* half of the enforcement compiler. |
-| [`stop-gate.mjs`](stop-gate.mjs) | The Stop-gate runner — "done" is not a thing an agent may simply declare. |
-| [`advisory.mjs`](advisory.mjs) | The restart advisory — one line, once, where the agent is, and the same figure for the human. |
+| [`stop-gate.mjs`](stop-gate.mjs) | Stop-gate: bounded recipe and work checks. Hook failures need a verdict, since a crashed hook fails open. |
+| [`advisory.mjs`](advisory.mjs) | Restart comparison with explicit horizon and resume expense; unknown recovery cost stays conditional. |
 
 ### Tools and modules
 
@@ -49,34 +49,54 @@ Run as `node cli/<file>.mjs`, or imported by the files above.
 | [`ab-grade.mjs`](ab-grade.mjs) | The A/B graders — what an arm's tree says it did, and the discrimination that proves a grader read it. Not shipped. |
 | [`ab-run.mjs`](ab-run.mjs) | The A/B runner: spawns the agent turns of both arms and records the baseline they measure. Not shipped. |
 | [`ab.mjs`](ab.mjs) | The A/B arm builder — what "Portulan on" is made of, built rather than described. Not shipped. |
+| [`acquire-personas.mjs`](acquire-personas.mjs) | Acquire the frozen persona comparisons through native children; never run by a recipe. Not shipped. |
+| [`cache-risk.mjs`](cache-risk.mjs) | Potential cache risks from project files; host activation is not inferred. |
+| [`cache-stability.mjs`](cache-stability.mjs) | Prefix baseline. Not shipped. |
 | [`comments.mjs`](comments.mjs) | `comments` — the comments in a tree that record a change's history instead of what the code cannot show. |
-| [`context.mjs`](context.mjs) | What a context loads, measured: what a boot reads in full, and what the host loads into every context. |
+| [`context.mjs`](context.mjs) | Measure boot reads and the project's always tier. |
 | [`control-chars.mjs`](control-chars.mjs) | `control-chars` — the rail on bytes a reader cannot see. |
 | [`discover.mjs`](discover.mjs) | Host plugin-cache discovery: reads a host's installed-plugin record to resolve a pointer and find pack roots. |
 | [`drills.mjs`](drills.mjs) | The forced-red drill harness — every rail broken on purpose, and required to fire. |
 | [`eval-bundle.mjs`](eval-bundle.mjs) | Cut a named-recipient evaluation bundle of Portulan from a commit. Not shipped. |
 | [`finish.mjs`](finish.mjs) | The finishing command — one call closes a change: its recipes, its changelog fragment, its commit, its push. |
 | [`form.mjs`](form.mjs) | `form` — which form a consumer's records and boot are in, and the files that move them to the new one. |
+| [`frontmatter.mjs`](frontmatter.mjs) | Flat frontmatter for plugin components and host bindings. |
 | [`fuzz-shell.mjs`](fuzz-shell.mjs) | Grammar-aware fuzzing over this repository's two shell segmenters. |
 | [`goldens.mjs`](goldens.mjs) | Grade this workspace's compiled gates against a corpus of adversarial fixtures. |
+| [`guidance-files.mjs`](guidance-files.mjs) | Nested instruction ownership and atomic guidance publication. |
+| [`handoff-policy.mjs`](handoff-policy.mjs) | Handoff caps and windows. |
+| [`html-entities.mjs`](html-entities.mjs) | HTML5 named references (semicolon forms): https://html.spec.whatwg.org/entities.json Generated from Python 3 html.entities.html5. |
+| [`import-files.mjs`](import-files.mjs) | Optional project import probes. |
+| [`init-preview.mjs`](init-preview.mjs) | Project guidance preview, shared by init and instruction migration. |
 | [`inside.mjs`](inside.mjs) | Is one path inside another? One predicate, one file, no dependencies. |
+| [`instructions-journal.mjs`](instructions-journal.mjs) | One CLI split/join, bounded to its original sources. The planner proves the saved operation again. Immutable lease children serialize recovery without deleting a possibly live writer's lock. Terminal proof outlives rollback authority; unproved initialization remains for human review. |
 | [`instructions.mjs`](instructions.mjs) | `instructions` — the sections a team marks in its own instruction file, moved to on-read units and proved. |
 | [`ledger.mjs`](ledger.mjs) | What a change spends, measured from the host's own usage records. |
 | [`librarian.mjs`](librarian.mjs) | `librarian` — the scheduled pass over the curated layer: reindex, staleness, nags, demotion drafts. |
+| [`local-routing.mjs`](local-routing.mjs) | Verify the shipped operational local roles against their immutable acquired A/B record. No model. Not shipped. |
 | [`manifest.mjs`](manifest.mjs) | The two facts every tool here needs out of `package.json`, read once and in a module that imports nothing of ours. |
 | [`mutants.mjs`](mutants.mjs) | Mutation-test this repository's two gate matchers against the corpus that claims to cover them. |
+| [`normalize-personas.mjs`](normalize-personas.mjs) | Publish whitelisted numeric metadata and generic answers from the completed private persona acquisition. Not shipped. |
 | [`pack-identity.mjs`](pack-identity.mjs) | Every file `npm pack` emits is byte-identical to the tracked blob it came from. |
 | [`pack-version.mjs`](pack-version.mjs) | A change to a pack's `contributes` must move that pack's `portulan.version`. |
 | [`payload.mjs`](payload.mjs) | Every `cli/*.mjs` the npm payload carries is classified, and nothing arrives in it unclassified. Not shipped. |
+| [`persona-routing.mjs`](persona-routing.mjs) | Regrade the acquired core-persona records and check their shipped routing without a model. |
 | [`plugin-lint.mjs`](plugin-lint.mjs) | `plugin-lint` — the packaging validator. |
+| [`recipe-output.mjs`](recipe-output.mjs) | Agent output for any recipe: one green count, complete failure streams. |
+| [`recipe-runner.mjs`](recipe-runner.mjs) | Shared asynchronous recipe execution, bounded output and process-tree cleanup. |
 | [`recipe-set.mjs`](recipe-set.mjs) | The recipe set: the verify recipes a workspace yields, its own plus each composed pack's, namespaced by pack. |
 | [`release-eval.mjs`](release-eval.mjs) | Portulan — the eval result a release carries. |
-| [`review-meter.mjs`](review-meter.mjs) | The review-loop meter: the figures that bound this repository's review loop, derived from its reviews. |
+| [`review-meter.mjs`](review-meter.mjs) | The review-loop meter: the historical figures of this repository's Copilot review loop, derived from its reviews. |
+| [`ritual-contexts.mjs`](ritual-contexts.mjs) | Own native settings without inventing a gate policy. |
 | [`roster.mjs`](roster.mjs) | The cli roster: `cli/README.md`, rendered from the files it lists and never edited by hand. Not shipped. |
 | [`rule-carriers.mjs`](rule-carriers.mjs) | `rule-carriers` — the rail that keeps a reduced rule reduced. |
 | [`sessions.mjs`](sessions.mjs) | The session switches' texts: the cache-lifetime offer `init` and `upgrade` print, and the one line `doctor` reports on them. |
 | [`skill-goldens.mjs`](skill-goldens.mjs) | The core-skill golden corpus — every mandate a core skill states, bound to the live artifacts it governs, and graded. |
 | [`skills-set.mjs`](skills-set.mjs) | The registrable set: the `skills` paths a plugin manifest must declare so a composed pack's skills register. |
+| [`spend-analysis.mjs`](spend-analysis.mjs) | Class indices compare stated assumptions, never bills or route quality. |
+| [`spend-offer.mjs`](spend-offer.mjs) | Local evidence for init's optional spend declaration. |
+| [`stop-diagnostics.mjs`](stop-diagnostics.mjs) | Bounded streaming failure excerpts for the Stop recipe relay. |
+| [`stop-policy.mjs`](stop-policy.mjs) | Stop recipe deadline policy. |
 | [`symbols.mjs`](symbols.mjs) | A code file's outline, one line per symbol, and a Markdown file's, one line per heading with its size. |
 | [`telemetry.mjs`](telemetry.mjs) | The OTel emitter: the review-loop figures as OTLP/HTTP JSON, sent only when a committed config opts in. |
 | [`version-carriers.mjs`](version-carriers.mjs) | Every prose statement of the current version agrees with `package.json`. |
@@ -91,16 +111,27 @@ Node's own runner: `node --test "cli/**/*.test.mjs"`, which the `tests` recipe r
 | [`ab-grade.test.mjs`](ab-grade.test.mjs) | Tests for `ab-grade` — the A/B graders: staging, attribution, the four scenarios, the two levels and the register. |
 | [`ab-run.test.mjs`](ab-run.test.mjs) | Tests for `ab-run` — the A/B runner: isolation, the matrix, the journal, the register and the checks behind it. |
 | [`ab.test.mjs`](ab.test.mjs) | Tests for `ab` — the A/B arm builder: its disposition table, rule-2 matcher, nonces, isolation and stop probe. |
+| [`advisory-crossing.test.mjs`](advisory-crossing.test.mjs) | First recorded crossings survive delayed batches without stale Stop holds. |
+| [`advisory-dedup.test.mjs`](advisory-dedup.test.mjs) | Delayed repeats cannot replace the latest distinct request. |
+| [`advisory-host-trace.test.mjs`](advisory-host-trace.test.mjs) | The shipped host trace is evidence data; CI only replays its public counters. |
 | [`advisory.test.mjs`](advisory.test.mjs) | Tests for `advisory` — the restart advisory's one line with a tool result or at the prompt, and its figure in the status line. |
+| [`branch-freshness.test.mjs`](branch-freshness.test.mjs) | Tests for this repository's branch freshness check and trusted workflow. |
+| [`cache-inputs.test.mjs`](cache-inputs.test.mjs) | Missing cache inputs stay unpriced in reports and hooks. |
+| [`cache-risk.test.mjs`](cache-risk.test.mjs) | Project cache warnings are reports; no host state or server is consulted. |
+| [`cache-stability.test.mjs`](cache-stability.test.mjs) | Cache-prefix tests. |
 | [`checkout-refs.live.test.mjs`](checkout-refs.live.test.mjs) | A workflow that checks out MORE THAN ONCE names the ref of every checkout after the first. |
 | [`cli-roster.live.test.mjs`](cli-roster.live.test.mjs) | `cli/README.md` is exactly what ./roster.mjs renders from this directory, and the render keeps its shape. |
 | [`collisions.test.mjs`](collisions.test.mjs) | The collision contract: `init`, `new` and `vendor` answer each contracted state alike, and no fourth `collisions` exists. |
 | [`comments.test.mjs`](comments.test.mjs) | Tests for `comments`: each language's comments found exactly, and the four kinds of history told from the rest. |
 | [`compile.test.mjs`](compile.test.mjs) | Tests for `compile` — the enforcement compiler. |
+| [`context-count.test.mjs`](context-count.test.mjs) | On-demand provider counts preserve the measured corpus and remain outside offline verification. |
+| [`context-hosts.test.mjs`](context-hosts.test.mjs) | Independent project context measurements for the two guidance formats. |
 | [`context.test.mjs`](context.test.mjs) | Tests for `context` — what a boot reads and what the host loads into every context, measured. |
 | [`control-chars.test.mjs`](control-chars.test.mjs) | Tests for `control-chars` — the rail on bytes a reader cannot see. |
+| [`demo-upgrade.test.mjs`](demo-upgrade.test.mjs) | The demo's pinned bundle replacement reproduces its boot reduction without changing its workspace. |
 | [`discover.test.mjs`](discover.test.mjs) | Tests for host plugin-cache discovery. |
-| [`doctor.test.mjs`](doctor.test.mjs) | Tests for `doctor` — the Workspace Definition validator. |
+| [`doctor-lever.test.mjs`](doctor-lever.test.mjs) | Tests for doctor's savings lever. |
+| [`doctor.test.mjs`](doctor.test.mjs) | Tests for `doctor` — workspace validation, branch-owned hybrid usage and static-mode isolation. |
 | [`drills.test.mjs`](drills.test.mjs) | Tests for `drills` — the forced-red drill harness: its table, perturbation guards, pair oracle, hook rails and tree choice. |
 | [`eval-bundle.test.mjs`](eval-bundle.test.mjs) | The evaluation-bundle cutter, driven on this repository AND on real fixture repositories. |
 | [`feedback.live.test.mjs`](feedback.live.test.mjs) | The sender's field map, against the real issue forms rather than against a fixture. |
@@ -112,24 +143,42 @@ Node's own runner: `node --test "cli/**/*.test.mjs"`, which the `tests` recipe r
 | [`gate.test.mjs`](gate.test.mjs) | The PreToolUse gate runner, driven as the host drives it. |
 | [`gh-bot.test.mjs`](gh-bot.test.mjs) | The agent identity's wrapper refuses the endpoints it is not for. |
 | [`goldens.test.mjs`](goldens.test.mjs) | Tests for `goldens` — the gate-corpus rail: the exemption, both rails, every corpus refusal and the CLI. |
+| [`handoff-budget.test.mjs`](handoff-budget.test.mjs) | Handoff budget tests. |
 | [`index.test.mjs`](index.test.mjs) | Tests for `index` — the memory, handoff and scope indexes, the memory budgets, and changelog fragments. |
+| [`init-budget.test.mjs`](init-budget.test.mjs) | The init interview's declared always-tier choice. |
 | [`init.test.mjs`](init.test.mjs) | Tests for `init` — the onboarding subcommand that drafts a workspace for a repository that has none. |
+| [`instructions-journal.test.mjs`](instructions-journal.test.mjs) | Process interruption and ownership controls for CLI instruction migration. |
 | [`instructions.test.mjs`](instructions.test.mjs) | Tests for `instructions`: the sections a team marks, moved to on-read units and proved, and the join back. |
 | [`ledger.test.mjs`](ledger.test.mjs) | Tests for `ledger` — what a change spends, from the host's own usage records. |
 | [`librarian.test.mjs`](librarian.test.mjs) | Tests for `librarian` — the scheduled pass over the curated layer. |
 | [`list-quoting.live.test.mjs`](list-quoting.live.test.mjs) | Every recipe that enumerates the tree reads the pathname git actually carries. |
+| [`local-completion.test.mjs`](local-completion.test.mjs) | Local completion and fenced-code regression tests. |
+| [`local-transport.test.mjs`](local-transport.test.mjs) | Local HTTP deadlines, response bounds and compatibility tests. |
+| [`local-usage.test.mjs`](local-usage.test.mjs) | Usage, exhaustion and rollback tests. |
 | [`mutants.test.mjs`](mutants.test.mjs) | Tests for `mutants`, the mutation-census rail: its operator table, its imports, its corpus and its refusals. |
+| [`nested-instructions.test.mjs`](nested-instructions.test.mjs) | Nested guidance generation, ownership recovery and consumer parity. |
 | [`new.test.mjs`](new.test.mjs) | Tests for `new`: scaffolds that validate, written into the user's own layer and never into `core/`. |
 | [`pack-identity.test.mjs`](pack-identity.test.mjs) | Tests for the byte-identity rail: green, both findings and could-not-run, each exercised. |
+| [`pack-local-llm.test.mjs`](pack-local-llm.test.mjs) | Tests for the `tools/local-llm` pack's runner — its loopback, input-budget and rollback rails, its eval screen, dedup ranking and A/B record. |
 | [`pack-version.test.mjs`](pack-version.test.mjs) | The pack-version rail, driven on REAL git repositories rather than an injected history. |
 | [`payload.test.mjs`](payload.test.mjs) | Tests for the payload-classification rail. |
+| [`persona-acquisition.test.mjs`](persona-acquisition.test.mjs) | Check native invocation and no-resampling guards. |
+| [`persona-capture.test.mjs`](persona-capture.test.mjs) | Force acquired persona, routing and packaging rails red. |
+| [`persona-routing.test.mjs`](persona-routing.test.mjs) | Semantic controls for the acquired core-persona routing comparisons. |
+| [`persona-upgrade.test.mjs`](persona-upgrade.test.mjs) | Exercise historical persona upgrade, ownership and rollback. |
 | [`pinned-roots.live.test.mjs`](pinned-roots.live.test.mjs) | Required checks name their resolution root, and every suite whose imports reach the host's plugin record empties it. |
 | [`plugin-lint.test.mjs`](plugin-lint.test.mjs) | Tests for `plugin-lint` — the packaging validator. |
+| [`policyfree-advisory.test.mjs`](policyfree-advisory.test.mjs) | Full compilation wires advice independently of gate policy. |
 | [`portulan.test.mjs`](portulan.test.mjs) | Tests for the `npx` entry point: dispatch through an injected loader, its refusals, and its version. |
+| [`prompt-footprint.test.mjs`](prompt-footprint.test.mjs) | Owned prompt footprint regression checks. |
+| [`recipe-output.test.mjs`](recipe-output.test.mjs) | Agent recipe output controls. |
+| [`recipe-runner.test.mjs`](recipe-runner.test.mjs) | Recipe cleanup controls use isolated, test-owned process groups and late filesystem writes. |
 | [`recipe-set.live.test.mjs`](recipe-set.live.test.mjs) | The composed recipe set, against THIS repository rather than against fixtures. |
 | [`recipe-set.test.mjs`](recipe-set.test.mjs) | The recipe set — one carrier, and every reader reaches it. |
 | [`release-eval.test.mjs`](release-eval.test.mjs) | The release-eval suite, on the record layer only: `--capture` spawns every other rail, the tests that run this suite included. |
+| [`restart-resume.test.mjs`](restart-resume.test.mjs) | Bounded-run restart comparisons, recovery expense, profitability and Stop refusal controls. |
 | [`review-meter.test.mjs`](review-meter.test.mjs) | Tests for `review-meter` — the review-loop meter: arithmetic, snapshot contract, register rail, window and shaping. |
+| [`ritual-contexts.test.mjs`](ritual-contexts.test.mjs) | Ritual admission caps and total observed contexts have different units. |
 | [`rule-carriers.test.mjs`](rule-carriers.test.mjs) | Tests for `rule-carriers` — the rail that keeps a reduced rule reduced. |
 | [`sessions.test.mjs`](sessions.test.mjs) | `sessions` — the cache lifetime's offer, and `doctor`'s one line on the session switches. |
 | [`shadowed-pack.test.mjs`](shadowed-pack.test.mjs) | A shadowed pack is refused rather than picked. |
@@ -137,6 +186,9 @@ Node's own runner: `node --test "cli/**/*.test.mjs"`, which the `tests` recipe r
 | [`skill-goldens.test.mjs`](skill-goldens.test.mjs) | Tests for `skill-goldens`, the core-skill golden corpus: every refusal exercised on a fixture that trips it. |
 | [`skills-set.live.test.mjs`](skills-set.live.test.mjs) | The registrable set, against THIS repository rather than against fixtures. |
 | [`skills-set.test.mjs`](skills-set.test.mjs) | The registrable set — what a plugin manifest must declare so a composed pack's skills register. |
+| [`spend-analysis.test.mjs`](spend-analysis.test.mjs) | Numeric class analysis keeps ownership, recency and unknown metadata explicit. |
+| [`spend-offer.test.mjs`](spend-offer.test.mjs) | Init spend offers. |
+| [`stop-diagnostics.test.mjs`](stop-diagnostics.test.mjs) | Stop recipe diagnostics retain failures across noise and stream boundaries. |
 | [`stop-gate.test.mjs`](stop-gate.test.mjs) | Tests for the Stop-gate runner: its per-reason caps, the handoff date, its verdicts, the did-work signals and the tree it answers about. |
 | [`symbols.live.test.mjs`](symbols.live.test.mjs) | `symbols` against this repository: tracked code and Markdown files outline, each declaration compiles alone, and heading links land. |
 | [`symbols.test.mjs`](symbols.test.mjs) | The outline's contract, on fixtures: what each construct prints, and every refusal. |
@@ -156,4 +208,7 @@ What the tools and suites read.
 | File | What it is |
 |---|---|
 | [`eval-license.template.md`](eval-license.template.md) | Portulan Evaluation Issue (`EVAL-LICENSE.md`). Not shipped. |
+| [`finish.md`](finish.md) | Finish verification boundaries |
+| [`recipe-runner.md`](recipe-runner.md) | Recipe execution and cleanup |
+| [`spend-offer.md`](spend-offer.md) | Init's spend offer |
 | [`fixtures/`](fixtures/) | The fixtures the suites build on; each suite names the ones it reads. Not shipped. |

package/cli/advisory.mjs

@@ -1,31 +1,37 @@
 #!/usr/bin/env node
-// The restart advisory — one line, once, where the agent is, and the same figure for the human.
+// Restart comparison with explicit horizon and resume expense; unknown recovery cost stays conditional.
 //
-//   node cli/advisory.mjs tool [<figures>]      a PostToolUse hook: the line, as additionalContext, once, mid-stretch
-//   node cli/advisory.mjs prompt [<figures>]    a UserPromptSubmit hook: the same line, at the next prompt, if not said yet
-//   node cli/advisory.mjs status [<figures>]    a status-line command: the figure and the request count, on every refresh
-//   node cli/advisory.mjs stop [<figures>]      a Stop hook, where a workspace declares it: the same line as a block, once
-//
-//   <figures>  --read <m> --write-5m <m> --write-1h <m>, all three or none, and --horizon <n>: a workspace's
-//              `spend`, as `./compile.mjs` writes it; undeclared, the general multipliers and horizon.
-//
-// Exit 0 on every path: a 2 would erase the person's prompt at `UserPromptSubmit` and hold every turn's end at
-// `Stop`. What it cannot read or use, it passes over and names on stderr.
-//
-// The line rides a tool result or a prompt: a non-blocking `Stop` hook's output never reaches the model, and a
-// headless run's one prompt comes before any request. The transcript is written asynchronously, so the line may
-// come one request late, never early.
+// node cli/advisory.mjs tool|prompt|status|stop [--read m --write-5m m --write-1h m] [--horizon n] [--resume-tokens cost]
+// Undeclared prices/horizon use general figures; unknown resume cost permits conditional reports only.
+// Tool/prompt output reaches the agent; a declared Stop holds only with explicit profitable estimates.
+// Retain the first crossing in a delayed batch; Stop uses the latest estimate. Hook failures exit 0.
+// Unusable figures are named on stderr.
 
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
 
-import { HORIZON, LedgerError, SPEND_FIGURES, figureOf, foldFigures, overflowingWrite, readLine, sessionFigures } from "./ledger.mjs";
+import { HORIZON, INPUT_USAGE_MASK, inputUnusable, usageOf, contextOf, LedgerError, SPEND_FIGURES, figureOf, foldFigures, foldCanonical, overflowingWrite, readLine, readTranscript, restartSaving, sessionFigures } from "./ledger.mjs";
 
 const grouped = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-
-const STATE_VERSION = 2;
+const savingWords = (n) => grouped(Number(n.toPrecision(6)));
+
+const STATE_VERSION = 8;
+const SEEN_BYTES = 1024;
+const emptySeen = () => Buffer.alloc(SEEN_BYTES).toString("hex");
+// Membership selects exact replay; collisions never establish identity.
+function membership(bits, id, remember = false) {
+    const hash = createHash("sha256").update(id).digest();
+    let hit = true;
+    for (const at of [0, 4, 8]) {
+        const bit = hash.readUInt32LE(at) % (SEEN_BYTES * 8), mask = 1 << (bit & 7);
+        hit = Boolean(bits[bit >> 3] & mask) && hit;
+        if (remember) bits[bit >> 3] |= mask;
+    }
+    return hit;
+}
 
 const CHUNK = 1 << 16;
 
@@ -97,18 +103,64 @@ function restore(file, transcriptPath, stat) {
     }
     if (kept === null || typeof kept !== "object" || kept.v !== STATE_VERSION || kept.transcript !== transcriptPath) return null;
     if (kept.ino !== stat.ino || !isCount(kept.offset) || kept.offset > stat.size || typeof kept.tail !== "string" || !wellFormed(kept.figures)) return null;
+    if (typeof kept.comparison !== "string" || typeof kept.seen !== "string" || kept.seen.length !== SEEN_BYTES * 2 || !/^[0-9a-f]+$/.test(kept.seen)) return null;
+    if (typeof kept.freshUnsafe !== "boolean" || typeof kept.latestUnsafe !== "boolean" || ![kept.freshId, kept.latestId, kept.crossingId].every(id => id === null || typeof id === "string")) return null;
+    if (![kept.freshInput, kept.latestInput, kept.crossingInput].every(v => v === null || (Array.isArray(v) && v.length === 5 && v.every(isCount)))) return null;
+    if (!Array.isArray(kept.recentInputs) || kept.recentInputs.length > 16 || !kept.recentInputs.every(v => Array.isArray(v) && v.length === 3 && typeof v[0] === "string" && Array.isArray(v[1]) && v[1].length === 5 && v[1].every(isCount) && (isCount(v[2]) && (v[2] & INPUT_USAGE_MASK) === v[2]))) return null;
+    if (kept.crossing !== null && (!wellFormed(kept.crossing) || kept.crossing.pending || kept.crossing.compactions !== kept.figures.compactions || kept.crossing.fresh !== kept.figures.fresh || kept.crossing.requests > kept.figures.requests || kept.crossing.recent.length !== 0)) return null;
+    const seen = Buffer.from(kept.seen, "hex");
+    if ([...kept.figures.recent, kept.freshId, kept.latestId, kept.crossingId].some(id => id !== null && !membership(seen, id))) return null;
     return kept;
 }
 
-function advance(kept, transcriptPath, size) {
+const comparisonKey = ({ declared, horizon, resume }) => JSON.stringify([declared?.read ?? null, declared?.write?.["5m"] ?? null, declared?.write?.["1h"] ?? null, horizon, resume]);
+const inputOf = r => [r.uncached, r.written1h, r.written5m, r.writtenUnknown, r.read];
+const validity = () => ({ freshUnsafe: false, latestUnsafe: false, freshId: null, latestId: null, crossingId: null, freshInput: null, latestInput: null, crossingInput: null });
+const reset = (kept) => Object.assign(kept, { offset: 0, tail: "", seen: emptySeen(), figures: sessionFigures(), crossing: null, recentInputs: [], ...validity() });
+function rememberInput(state, r) {
+    if (r.id === null) return;
+    state.recentInputs = [...state.recentInputs.filter(v => v[0] !== r.id), [r.id, inputOf(r), r.usageMissing & INPUT_USAGE_MASK]].filter(v => state.figures.recent.includes(v[0])).slice(-16);
+}
+
+function replayValidity(kept, transcriptPath, spend) {
+    const transcript = readTranscript(transcriptPath, { end: kept.offset });
+    const state = { figures: sessionFigures(), crossing: null, recentInputs: [], ...validity() }, seen = Buffer.alloc(SEEN_BYTES);
+    for (const r of transcript.requests) {
+        if (r.id !== null) membership(seen, r.id, true);
+        if (r.sidechain) continue;
+        if (r.compacted) Object.assign(state, { crossing: null, ...validity() });
+        const fresh = state.figures.fresh === null || state.figures.pending || r.compacted;
+        foldCanonical(state.figures, r);
+        rememberInput(state, r);
+        const unsafe = inputUnusable(r);
+        if (fresh) { state.freshUnsafe = unsafe; state.freshId = r.id; state.freshInput = inputOf(r); }
+        state.latestUnsafe = unsafe; state.latestId = r.id; state.latestInput = inputOf(r);
+        if (state.freshUnsafe && !isCount(state.figures.fresh)) state.figures.fresh = 0;
+        if (state.latestUnsafe && !isCount(state.figures.last)) state.figures.last = 0;
+        if (state.freshUnsafe || state.latestUnsafe || state.crossing !== null) continue;
+        try {
+            const figure = figureOf(state.figures, spend);
+            if (figure !== null && figure.saving >= 0) { state.crossing = { ...state.figures, recent: [] }; state.crossingId = r.id; state.crossingInput = inputOf(r); }
+        } catch (error) { if (!(error instanceof LedgerError)) throw error; }
+    }
+    state.figures.compactions = transcript.figures.compactions;
+    state.figures.pending = transcript.figures.pending;
+    if (state.figures.pending) Object.assign(state, { crossing: null, ...validity() });
+    else if (state.crossing) state.crossing.compactions = state.figures.compactions;
+    Object.assign(kept, state, { seen: seen.toString("hex") });
+}
+
+function advance(kept, transcriptPath, size, spend) {
     if (size === kept.offset) return false;
     const fd = fs.openSync(transcriptPath, "r");
     try {
         if (kept.offset > 0 && tailBefore(fd, kept.offset) !== kept.tail) {
-            Object.assign(kept, { offset: 0, tail: "", figures: sessionFigures() });
+            reset(kept);
         }
+        const seen = Buffer.from(kept.seen, "hex");
         const start = kept.offset;
         let position = kept.offset;
+        let replay = false;
         // Joined once the newline lands: joining at every chunk would copy a long line once per chunk it spans.
         let waiting = [];
         while (position < size) {
@@ -125,12 +177,48 @@ function advance(kept, transcriptPath, size) {
             const complete = waiting.length === 0 ? bytes.subarray(0, end) : Buffer.concat([...waiting, bytes.subarray(0, end)]);
             for (const line of complete.toString("utf8").split("\n")) {
                 const read = readLine(line);
-                if (read !== null && !read.malformed) foldFigures(kept.figures, read);
+                if (read === null || read.malformed) continue;
+                const { requests, compactions } = kept.figures;
+                const fresh = kept.figures.fresh === null || kept.figures.pending;
+                const r = read.request;
+                if (r && !r.synthetic) {
+                    const repeated = r.id !== null && membership(seen, r.id, true);
+                    if (repeated && !kept.figures.recent.includes(r.id)) replay = true;
+                    if (!r.sidechain || repeated) {
+                        const input = inputOf(r);
+                        const tracked = [[kept.freshId, kept.freshInput], [kept.latestId, kept.latestInput], [kept.crossingId, kept.crossingInput]];
+                        const recent = kept.recentInputs.find(v => v[0] === r.id);
+                        if (inputUnusable(r) || (recent && (JSON.stringify(recent[1]) !== JSON.stringify(input) || recent[2] !== (r.usageMissing & INPUT_USAGE_MASK))) || (r.id !== null && tracked.some(([id, before]) => id === r.id && (JSON.stringify(before) !== JSON.stringify(input) || kept.freshUnsafe || kept.latestUnsafe)))) replay = true;
+                    }
+                }
+                foldFigures(kept.figures, read);
+                if (compactions !== kept.figures.compactions) Object.assign(kept, { crossing: null, ...validity() });
+                if (r && !r.synthetic && !r.sidechain) {
+                    rememberInput(kept, r);
+                    const unsafe = inputUnusable(r);
+                    if (requests !== kept.figures.requests) {
+                        if (fresh) { kept.freshUnsafe = unsafe; kept.freshId = r.id; kept.freshInput = inputOf(r); }
+                        kept.latestUnsafe = unsafe; kept.latestId = r.id; kept.latestInput = inputOf(r);
+                    } else if (r.id !== null && (r.usageUnsafe & 1)) {
+                        if (r.id === kept.freshId) kept.freshUnsafe = true;
+                        if (r.id === kept.latestId) kept.latestUnsafe = true;
+                    }
+                }
+                if (kept.freshUnsafe || kept.latestUnsafe) continue;
+                if (requests === kept.figures.requests || kept.crossing !== null) continue;
+                try {
+                    const figure = figureOf(kept.figures, spend);
+                    if (figure !== null && figure.saving >= 0) { kept.crossing = { ...kept.figures, recent: [] }; kept.crossingId = r.id; kept.crossingInput = inputOf(r); }
+                } catch (error) {
+                    if (!(error instanceof LedgerError)) throw error;
+                }
             }
             waiting = end + 1 < got ? [bytes.subarray(end + 1)] : [];
             kept.offset = position - (got - end - 1);
         }
         if (kept.offset !== start) kept.tail = tailBefore(fd, kept.offset);
+        kept.seen = seen.toString("hex");
+        if (replay) replayValidity(kept, transcriptPath, spend);
         return kept.offset !== start;
     } finally {
         fs.closeSync(fd);
@@ -165,19 +253,25 @@ function locate(payload, dir) {
     if (!stat.isFile()) return { why: "the transcript could not be read — it is not a file" };
     const sessionId = sessionOf(payload);
     const file = sessionId === null ? null : stateFile(sessionId, dir);
-    const kept = (file === null ? null : restore(file, transcriptPath, stat)) ?? { v: STATE_VERSION, transcript: transcriptPath, ino: stat.ino, offset: 0, tail: "", figures: sessionFigures() };
+    const kept = (file === null ? null : restore(file, transcriptPath, stat)) ?? { v: STATE_VERSION, transcript: transcriptPath, ino: stat.ino, offset: 0, tail: "", seen: emptySeen(), figures: sessionFigures(), comparison: "", crossing: null, recentInputs: [], ...validity() };
     return { transcriptPath, sessionId, stat, file, kept };
 }
 
 function refresh(found, warn, spend) {
     try {
-        if (advance(found.kept, found.transcriptPath, found.stat.size) && found.file !== null) keep(found.file, found.kept, warn);
+        const key = comparisonKey(spend);
+        const changed = found.kept.comparison !== key;
+        if (changed) { reset(found.kept); found.kept.comparison = key; }
+        if ((advance(found.kept, found.transcriptPath, found.stat.size, spend) || changed) && found.file !== null) keep(found.file, found.kept, warn);
     } catch (error) {
         return { why: `the transcript could not be read — ${error.code ?? error.message}` };
     }
     let figure;
+    if (found.kept.freshUnsafe) return { why: "fresh context usage has invalid or missing counters; comparison unavailable (compaction or completed missing fields required)" };
+    if (found.kept.latestUnsafe) return { why: "latest context usage has invalid or missing counters; comparison unavailable (valid next request or completed missing fields required)" };
     try {
         figure = figureOf(found.kept.figures, spend);
+        if (figure !== null) figure.crossing = found.kept.crossing === null ? null : figureOf(found.kept.crossing, spend);
     } catch (error) {
         if (!(error instanceof LedgerError)) throw error;
         return { why: error.message };
@@ -188,35 +282,40 @@ function refresh(found, warn, spend) {
         : { why: "no request is recorded yet", after: "the first recorded request" };
 }
 
-const FINISH = { PostToolUse: "finish the current step, then ", UserPromptSubmit: "finish what this prompt asks, then ", Stop: "" };
-
 export function adviceLine(figure, event = "UserPromptSubmit") {
     const m = figure.multipliers;
-    const assumed =
-        m.source === "declared"
-            ? "multipliers declared"
-            : `multipliers undeclared, so the general read multiplier and the ${m.recorded ? `${m.lifetime === "1h" ? "one-hour" : "five-minute"} writes the host recorded` : "five-minute write the records did not state"}`;
-    return (
-        `Portulan restart advisory: after ${grouped(figure.requests)} requests, each re-reading it, this session's context, ${grouped(figure.context)} tokens, has reached its restart threshold of ` +
-        `${grouped(figure.threshold)} = fresh context ${grouped(figure.fresh)} × (1 + write ${m.write}× / (${figure.horizon} more requests × read ${m.read}×)); ${assumed}. ` +
-        `Continuing costs more in re-reads than restarting: ${FINISH[event]}write the handoff and end the session. Said once.`
-    );
+    const horizon = `${figure.horizon} remaining (${figure.horizonDeclared ? "declared" : "default"})`;
+    const resume = figure.resume == null ? "resume cost unknown; threshold is a lower bound" : `resume ${grouped(figure.resume)} input equivalents`;
+    const comparison = figure.saving < 0 ? "Latest estimate does not favor restarting."
+        : figure.resume != null && figure.horizonDeclared
+        ? `Estimated savings ${savingWords(figure.saving)} input equivalents; consider a handoff and restart if these estimates still fit the task.`
+        : "Restart only if remaining work and recovery cost make it cheaper; finish bounded work when that costs less.";
+    const first = figure.crossing;
+    const history = first && first.requests !== figure.requests
+        ? ` First crossing: request ${grouped(first.requests)}, context ${grouped(first.context)} / threshold ${grouped(first.threshold)} (fresh ${grouped(first.fresh)}, read ${first.multipliers.read}×, write ${first.multipliers.write}×, ${first.multipliers.recorded ? "recorded" : "assumed"} ${first.multipliers.lifetime}).`
+        : "";
+    return `Portulan restart advisory: after ${grouped(figure.requests)} requests, context ${grouped(figure.context)} tokens, threshold ${grouped(figure.threshold)}; ${horizon}, read ${m.read}×, write ${m.write}× (${m.source}); ${resume}.${history} ${comparison} Said once.`;
 }
 
 export function statusLine(figure) {
     const m = figure.multipliers;
-    const multiplied = `${m.source === "declared" ? "multipliers declared" : "multipliers undeclared"}: read ${m.read}×, write ${m.write}×`;
-    const requests = `${grouped(figure.requests)} request${figure.requests === 1 ? "" : "s"}`;
-    return figure.context >= figure.threshold
-        ? `${requests} · context ${compact(figure.context)} has reached its ${compact(figure.threshold)} restart threshold: write the handoff and restart · ${multiplied}`
-        : `${requests} · context ${compact(figure.context)} of a ${compact(figure.threshold)} restart threshold · ${multiplied}`;
+    return `${grouped(figure.requests)} requests · context ${compact(figure.context)} / restart ${compact(figure.threshold)} · ${figure.horizon} remaining (${figure.horizonDeclared ? "declared" : "default"}) · ` +
+        `${figure.resume == null ? "resume cost unknown: lower bound" : `resume ${grouped(figure.resume)} input-equivalent tokens; estimated saving ${savingWords(figure.saving)}`} · ` +
+        `multipliers ${m.source}: read ${m.read}×, write ${m.write}×`;
 }
 
-function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = HORIZON } = {}) {
+export function advisoryOutput(figure, event) {
+    const line = adviceLine(figure, event);
+    return event === "Stop"
+        ? JSON.stringify({ decision: "block", reason: line })
+        : JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: line } });
+}
+
+function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = null, resume = null } = {}) {
     // Claude Code 2.1.281: a subagent's tool call carries its own `agent_id` and the main session's transcript,
     // and a subagent told to end its session would end nothing.
     if (typeof payload?.agent_id === "string" && payload.agent_id !== "") return null;
-    // A host can give a block's retry a new session id, where the held-once record would hold it again.
+    // Without the host's retry marker, rotated session ids can repeat the hold.
     if (event === "Stop" && payload?.stop_hook_active === true) return null;
     const sessionId = sessionOf(payload);
     if (sessionId === null) {
@@ -231,12 +330,13 @@ function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = n
     const record = event === "Stop" ? heldFile : toldFile;
     // Nothing written since the figures were kept, so nothing compacted: the record at the kept count answers without a read.
     if (found.stat.size === found.kept.offset && fs.existsSync(record(sessionId, found.kept.figures.compactions, dir))) return null;
-    const figure = refresh(found, warn, { declared, horizon });
+    const figure = refresh(found, warn, { declared, horizon, resume });
     if (figure.why !== undefined) {
         warn(figure.why);
         return null;
     }
-    if (figure.context < figure.threshold) return null;
+    if (figure.crossing === null) return null;
+    if (event === "Stop" && (!figure.horizonDeclared || figure.resume === null || !(figure.saving > 0))) return null;
     const mark = (file) => fs.writeFileSync(file, `${figure.context} ${figure.threshold}\n`, { flag: "wx", mode: 0o600 });
     try {
         mark(record(sessionId, figure.compactions, dir));
@@ -250,13 +350,13 @@ function once(event, payload, { dir = os.tmpdir(), warn = () => {}, declared = n
         }
         return null;
     }
-    if (event !== "Stop") return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: adviceLine(figure, event) } });
+    if (event !== "Stop") return advisoryOutput(figure, event);
     try {
         mark(toldFile(sessionId, figure.compactions, dir));
     } catch (error) {
         if (error.code !== "EEXIST") warn(`the told-once record could not be written — ${error.code ?? error.message}; the line may come once more after the block`);
     }
-    return JSON.stringify({ decision: "block", reason: adviceLine(figure, event) });
+    return advisoryOutput(figure, event);
 }
 
 export const onTool = (payload, options) => once("PostToolUse", payload, options);
@@ -266,13 +366,24 @@ export const onPrompt = (payload, options) => once("UserPromptSubmit", payload,
 export const onStop = (payload, options) => once("Stop", payload, options);
 
 /** The status line, its context the host's own last-call counts where sent: current where the transcript may lag a request. */
-export function onStatus(payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = HORIZON } = {}) {
+export function onStatus(payload, { dir = os.tmpdir(), warn = () => {}, declared = null, horizon = null, resume = null } = {}) {
     const found = locate(payload, dir);
-    const figure = found.why === undefined ? refresh(found, warn, { declared, horizon }) : found;
+    const figure = found.why === undefined ? refresh(found, warn, { declared, horizon, resume }) : found;
     if (figure.why !== undefined) return figure.after !== undefined ? `restart threshold: after ${figure.after}` : `restart threshold: not known, because ${figure.why}`;
     const usage = payload?.context_window?.current_usage;
-    const counts = usage !== null && typeof usage === "object" ? ["input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"].map((k) => usage[k]) : [];
-    if (counts.length === 3 && counts.every((n) => Number.isSafeInteger(n) && n >= 0)) figure.context = counts.reduce((a, b) => a + b, 0);
+    if (usage !== undefined && usage !== null) {
+        if (typeof usage !== "object" || Array.isArray(usage)) return "restart threshold: not known, because the current input has missing or invalid counters";
+        const current = usageOf(usage), context = contextOf(current);
+        if (!Number.isSafeInteger(context)) return "restart threshold: not known, because the current input sum is unsafe";
+        if (inputUnusable(current)) return "restart threshold: not known, because the current input has missing or invalid counters";
+        try {
+            figure.saving = restartSaving({ fresh: figure.fresh, context, horizon: figure.horizon, read: figure.multipliers.read, write: figure.multipliers.write, resume: figure.resume ?? 0 });
+        } catch (error) {
+            if (error instanceof LedgerError) return "restart threshold: not known, because the estimated saving overflows";
+            throw error;
+        }
+        figure.context = context;
+    }
     return statusLine(figure);
 }
 
@@ -284,7 +395,7 @@ function readPayload() {
     }
 }
 
-const SPEND_FLAGS = { "--read": "read", "--write-5m": "write", "--write-1h": "write", "--horizon": "requests" };
+const SPEND_FLAGS = { "--read": "read", "--write-5m": "write", "--write-1h": "write", "--horizon": "requests", "--resume-tokens": "resume" };
 
 const MULTIPLIER_FLAGS = ["--read", "--write-5m", "--write-1h"];
 
@@ -294,7 +405,7 @@ const DECIMAL = /^[0-9]+(\.[0-9]+)?(e[+-]?[0-9]+)?$/;
 /** The figures after the mode, `{ declared, horizon, fault }`, each null where absent; a partial multiplier set is undeclared whole. */
 export function spendFlags(args) {
     const values = new Map();
-    const faults = { multipliers: [], horizon: [], other: [] };
+    const faults = { multipliers: [], horizon: [], resume: [], other: [] };
     const shown = (s) => (typeof s === "string" && /^[-+.a-zA-Z0-9]+$/.test(s) ? s : JSON.stringify(s));
     for (let i = 0; i < args.length; i += 2) {
         const [flag, raw] = [args[i], args[i + 1]];
@@ -302,7 +413,7 @@ export function spendFlags(args) {
             faults.other.push(`${shown(flag)} is no flag it takes`);
             continue;
         }
-        const part = flag === "--horizon" ? faults.horizon : faults.multipliers;
+        const part = flag === "--horizon" ? faults.horizon : flag === "--resume-tokens" ? faults.resume : faults.multipliers;
         const range = SPEND_FIGURES[SPEND_FLAGS[flag]];
         const value = typeof raw === "string" && DECIMAL.test(raw) ? Number(raw) : Number.NaN;
         if (values.has(flag)) part.push(`${flag} is given twice`);
@@ -319,10 +430,12 @@ export function spendFlags(args) {
     const said = [];
     if (faults.multipliers.length) said.push(`${faults.multipliers.join(", ")}, so the multipliers are undeclared`);
     if (faults.horizon.length) said.push(`${faults.horizon.join(", ")}, so the horizon is undeclared, and ${HORIZON} requests`);
+    if (faults.resume.length) said.push(`${faults.resume.join(", ")}, so resume cost is unknown`);
     if (faults.other.length) said.push(`${faults.other.join(", ")}, so ${faults.other.length === 1 ? "it is" : "each is"} passed over with the value after it`);
     return {
         declared: missing.length === 0 && !faults.multipliers.length ? { read: values.get("--read"), write: { "5m": values.get("--write-5m"), "1h": values.get("--write-1h") } } : null,
         horizon: values.has("--horizon") && !faults.horizon.length ? values.get("--horizon") : null,
+        resume: values.has("--resume-tokens") && !faults.resume.length ? values.get("--resume-tokens") : null,
         fault: said.length ? said.join("; ") : null,
     };
 }
@@ -334,7 +447,8 @@ export function main(argv = process.argv.slice(2), { stdout = process.stdout, st
     try {
         const figures = spendFlags(argv.slice(1));
         if (figures.fault !== null) warn(`the figures after ${mode} are not all usable — ${figures.fault}`);
-        const priced = { dir, warn, declared: figures.declared, horizon: figures.horizon ?? HORIZON };
+        if (mode === "stop" && figures.fault !== null) return 0;
+        const priced = { dir, warn, declared: figures.declared, horizon: figures.horizon, resume: figures.resume };
         if (mode === "prompt" || mode === "tool" || mode === "stop") {
             const out = { tool: onTool, prompt: onPrompt, stop: onStop }[mode](input, priced);
             if (out !== null) stdout.write(`${out}\n`);