@event4u/agent-config 9.21.0 → 9.22.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Bootstrap shim for the event4u agent-config suite. This plugin ships ONLY the dispatcher hooks plus one install-pointer skill — ALL content (skills, rules, commands) is installed via `npx -y @event4u/agent-config init`, which writes the file projection AND registers the same hooks in ~/.claude/settings.json. DEPRECATED as a content channel; kept so the marketplace listing stays discoverable and existing installs keep working hooks.",
-    "version": "9.21.0",
+    "version": "9.22.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -294,6 +294,41 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 > that forces a new era split (`# Era: 9.19.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [9.22.0](https://github.com/event4u-app/agent-config/compare/9.21.0...9.22.0) (2026-08-05)
+
+### Release highlights
+
+<!-- Curated head: fill before merge, keep it under 10 lines, and leave `_none_` where it is genuinely the answer. The generated log below is unchanged. -->
+- **Behaviour changes:** _none_
+- **Default changes + migration:** _none_
+- **Security and correctness:** _none_
+- **Honest nulls:** _none_
+- **Known limitations:** _none_
+
+### Features
+
+* **worktree:** classify every worktree safe/review/live in one pass ([ac42fa6](https://github.com/event4u-app/agent-config/commit/ac42fa6c041db0343b6363472541a2fdf3815c3c))
+* **bench:** report which arm the dropped pairs came from ([9230102](https://github.com/event4u-app/agent-config/commit/9230102868bd25a20aa2e30e35a9e57d45c0051c))
+* **bench:** fail the sweep on an unproven arm, a swapped model, or an overrun ([490a5e5](https://github.com/event4u-app/agent-config/commit/490a5e5995db3e2f49676d7df5a0db41bf8e3926))
+* **bench:** record which model actually answered each run ([5ea6b60](https://github.com/event4u-app/agent-config/commit/5ea6b60cb850e10299fe66c4c9e8aa0fd612772f))
+* **bench:** the activation audit the invalid-nulls incident needed ([2630c48](https://github.com/event4u-app/agent-config/commit/2630c481b834b192c974cf828b72b2b3a3304b81))
+
+### Bug Fixes
+
+* **bench:** validate the sweep cap before probing for the host CLI ([4aee1d8](https://github.com/event4u-app/agent-config/commit/4aee1d8aa02598db80d0cad819fe85618558dc53))
+
+### Documentation
+
+* **roadmap:** promote worktree hygiene on the fired disk trigger, record the baseline ([78d5b7a](https://github.com/event4u-app/agent-config/commit/78d5b7ab2691b7cb75e094fa724e5a3eaa5d2f06))
+* **worktree:** route whole-checkout sweeps through the inventory mode ([3ba4c55](https://github.com/event4u-app/agent-config/commit/3ba4c556a7eee4256be3378bd67aa962b884dede))
+* **roadmap:** name why Measurement A cannot run, and correct my own scope ruling ([460dfb0](https://github.com/event4u-app/agent-config/commit/460dfb0c5e2d96e8deb831638684f501522661d2))
+* **bench:** withdraw the interactions degradation rule — measured, then falsified ([56d3fe3](https://github.com/event4u-app/agent-config/commit/56d3fe3b1433c69419a7d118c567ea2581a0a0d2))
+* **roadmap:** close the UI-track prerequisites and name the real blocker ([e8fa469](https://github.com/event4u-app/agent-config/commit/e8fa46953df5afacfb402a6d8468b44b72155191))
+* **bench:** pre-register the UI-track tier and lane measurements ([3a8b601](https://github.com/event4u-app/agent-config/commit/3a8b6017965bc9eed189c1971f28a6212b9dc3d3))
+* **roadmap:** record prerequisite work that moves no checkbox ([ad3bd4e](https://github.com/event4u-app/agent-config/commit/ad3bd4e9903e81ef38e647a6cbddacbd95f4f282))
+
+Tests: 11091 (+57 since 9.21.0)
+
 ## [9.21.0](https://github.com/event4u-app/agent-config/compare/9.20.0...9.21.0) (2026-08-05)
 
 ### Release highlights

package/dist/agent-src/commands/worktree/cleanup.md

@@ -31,6 +31,23 @@ never force-removes.
 `git worktree list --porcelain` — target the worktree(s) named by the
 user, or every non-main worktree when asked to "clean up".
 
+For a whole-checkout sweep, get the classified set in one pass instead of
+running the per-worktree gate by hand:
+
+```bash
+./scripts-run src/scripts/worktree_cleanup_check inventory        # counts + review reasons
+./scripts-run src/scripts/worktree_cleanup_check inventory --plan # commands for the safe set
+```
+
+`safe` = on a branch, merged into the trunk, clean, in a conventional
+worktree root, and no git activity for 48 h. `review` carries its
+disqualifying reason; `live` means another session may hold it. The mode
+reports only — running the plan is a bulk deletion needing the user's
+explicit this-turn approval per
+[`non-destructive-by-default`](../../../rules/non-destructive-by-default.md).
+Present the safe set as a list and wait; a bulk sweep never inherits a
+single earlier approval.
+
 ### 2. Per candidate, run the gates IN ORDER
 
 Run the deterministic gate helper (edge-case-tested: detached HEAD,

package/dist/agent-src/commands/worktree/status.md

@@ -29,6 +29,12 @@ git worktree list --porcelain
 ```
 
 One report block per worktree (skip the main working tree unless asked).
+Above roughly a dozen worktrees a per-worktree block stops being readable —
+lead with the aggregate instead, then block only what the user asks about:
+
+```bash
+./scripts-run src/scripts/worktree_cleanup_check inventory
+```
 
 ### 2. Per worktree, gather
 

package/dist/agent-src/skills/worktree-lifecycle/SKILL.md

@@ -128,6 +128,28 @@ step (`scope-control`); never force-delete (`-D`) as part of cleanup.
 Cross-worktree scope-lock overlaps are scanned via
 `worktree_cleanup_check scope-overlap` (surfaced by `/worktree status`).
 
+**Whole-checkout sweeps.** Worktrees accumulate one per branch and are never
+removed on merge; `git worktree prune` only clears registrations whose
+directory is already gone, so it does nothing for the live ones. Classify the
+whole set in one pass rather than gate-checking by hand:
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/scripts/worktree_cleanup_check.ts inventory [repo] [--json|--plan]
+```
+
+`safe` requires all of: on a branch, merged into the trunk, clean, inside a
+conventional worktree root (`.claude/worktrees/` or `.worktrees/`), and no git
+activity for 48 h. `review` keeps its disqualifying reason so the next sweep
+starts from a shorter list; `live` means another session may hold it. A
+worktree outside the conventional roots is never `safe` — sitting beside the
+repo it can be mistaken for a sibling package, so its removal stays a
+judgement call.
+
+The mode reports only. `--plan` prints `git worktree remove` plus
+`git branch -d` (never `-D`) for the safe set; **running it is a bulk deletion
+needing the user's explicit this-turn approval**
+(`non-destructive-by-default`), which a single earlier approval never covers.
+
 ## Host-native mapping
 
 | Host capability | Use |

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.21.0"
+agent_config_version: "9.22.0"
 
 # --- Project identity ---
 project:

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-08-05T03:10:28Z`
+- Generated: `2026-08-05T05:32:20Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -1977,7 +1977,7 @@
     },
     {
       "category": "command",
-      "checksum": "sha256:6efc669962a6f31d36731708ef37977505c8eaf29d4c9a6ef488037eed42ec1a",
+      "checksum": "sha256:e0e438bb85349bc013a609e6def8d70e7b749dcd97adff313d5db535987f7e95",
       "install": {
         "default": true,
         "removable": false
@@ -2055,7 +2055,7 @@
     },
     {
       "category": "command",
-      "checksum": "sha256:0e0fcdddceaa2fe3c2ef63f8a6557182f310da33a04cfb53199fb20cebed0f26",
+      "checksum": "sha256:68e5e30c2c90957615582840f804ce957bf1708319029b378ea97e384d05a1e8",
       "install": {
         "default": true,
         "removable": false
@@ -14220,7 +14220,7 @@
     },
     {
       "category": "skill",
-      "checksum": "sha256:66795187ffedce5896afb29d5c2794d7de0d55c7e2849b5bb001722bb0ba6975",
+      "checksum": "sha256:6031d5e7109a96a5a105ac91ea80c0df66d9934594a11d0c3efcf8b596cc48cf",
       "install": {
         "default": true,
         "removable": false
@@ -14259,7 +14259,7 @@
       "workspaces": []
     }
   ],
-  "checksum": "sha256:d766f7f17140ce6b648e68821c9403c0bf478609a1ea925e85501c5994002a05",
+  "checksum": "sha256:acdebb0b72b50f8026c14b11df8706155fb82ba5c44cff7fa47b6e019052d156",
   "deprecations": [
     {
       "key": "tier",
@@ -14402,7 +14402,7 @@
       "reason": "scaffold template for ticket-bundle tickets (ADR-101); carries no runtime frontmatter — emit-tickets fills it in per ticket"
     }
   ],
-  "generated_at": "2026-08-05T03:10:28Z",
+  "generated_at": "2026-08-05T05:32:20Z",
   "packs": [
     {
       "artefact_count": 117,

package/dist/discovery/discovery-manifest.json.sha256

@@ -1 +1 @@
-4b795a51a6574b400b90053e476daf9aac787dd71aa03ca8be86ad3f2913ea3e  discovery-manifest.json
+afd8d19ae939ff4cc011583591c8ae9f88601d301d808874f41cfb43f0d1122a  discovery-manifest.json

package/dist/discovery/discovery-manifest.summary.md

@@ -1,6 +1,6 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-08-05T03:10:28Z`
+- Generated: `2026-08-05T05:32:20Z`
 - Scanner: `c24312e116f8`
 - Artefacts: **594**
 - Unassigned: **0**

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-08-05T03:10:28Z`
+- Generated: `2026-08-05T05:32:20Z`
 - Orphan artefacts: **0**
 
 > An orphan is an artefact whose declared pack has no other members.

package/dist/discovery/packs.json

@@ -1,6 +1,6 @@
 {
-  "checksum": "sha256:d766f7f17140ce6b648e68821c9403c0bf478609a1ea925e85501c5994002a05",
-  "generated_at": "2026-08-05T03:10:28Z",
+  "checksum": "sha256:acdebb0b72b50f8026c14b11df8706155fb82ba5c44cff7fa47b6e019052d156",
+  "generated_at": "2026-08-05T05:32:20Z",
   "packs": [
     {
       "always_on": false,

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-08-05T03:10:28Z`
+- Generated: `2026-08-05T05:32:20Z`
 - Workspaces tracked: **10**
 - Human-review-required artefacts: **3**
 

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
-  "checksum": "sha256:d766f7f17140ce6b648e68821c9403c0bf478609a1ea925e85501c5994002a05",
-  "generated_at": "2026-08-05T03:10:28Z",
+  "checksum": "sha256:acdebb0b72b50f8026c14b11df8706155fb82ba5c44cff7fa47b6e019052d156",
+  "generated_at": "2026-08-05T05:32:20Z",
   "scanner_version": "c24312e116f8",
   "workspaces": [
     {

package/dist/mcp/registry-manifest.json

@@ -9,7 +9,7 @@
     "homepage": "https://event4u-app.github.io/agent-config",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "9.21.0"
+    "version": "9.22.0"
   },
   "registries": [
     {

package/dist/mcp/server.json

@@ -9,12 +9,12 @@
       "transport": {
         "type": "stdio"
       },
-      "version": "9.21.0"
+      "version": "9.22.0"
     }
   ],
   "repository": {
     "source": "github",
     "url": "https://github.com/event4u-app/agent-config"
   },
-  "version": "9.21.0"
+  "version": "9.22.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.21.0",
+    "version": "9.22.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/scripts/_lib/bench_ab_activation.ts

@@ -0,0 +1,368 @@
+/**
+ * Measurement-integrity primitives for the bench:ab v2 paired sweep.
+ *
+ * Implements deltas #1–#4 of the S0.3 harness-feasibility spike
+ * (`agents/evidence/investigations/solution-minimalism-phase0-spikes.md`
+ * § "Deltas required before a paid run") — the four cheap ones the roadmap's
+ * Phase-3 halt note says "land before any spend".
+ *
+ * Why this exists at all: the sweep has ALREADY produced a full set of invalid
+ * nulls once. Clones lived inside the repo, so the `vanilla` arm inherited the
+ * package through project scope and every prior null was void
+ * (`bench_ab_v2_run.ts` § arm-isolation note). The fix at the time was a `/tmp`
+ * path constant with no runtime assertion behind it, and the only activation
+ * field on a trial record — `injected_chars` — is the `String.length` of a file
+ * the harness itself wrote. It proves nothing about the model, and it is `0` by
+ * construction for the `package` arm, which arrives through global settings.
+ * If the plugin were disabled or version-drifted mid-sweep, every treatment run
+ * would silently degrade to `vanilla` and the report would look identical.
+ *
+ * Everything here is pure and host-free so it can be unit-tested without a
+ * model call. The sweep wires it in `bench_ab_v2_run.ts`.
+ */
+
+/** Four-bucket usage split as reported by the Claude CLI JSON envelope. */
+export interface TokensBreakdown {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens: number;
+    cache_creation_input_tokens: number;
+}
+
+/** Per-1M-token rates for one pricing tier (mirrors `_lib/bench_cost.TierRates`). */
+export interface TierRates {
+    input: number;
+    output: number;
+    cache_write: number;
+    cache_read: number;
+}
+
+/**
+ * How an arm is supposed to reach the model.
+ *
+ * - `plugin` — the package rides global settings (`setting_sources: null`).
+ *   Invisible to `injected_chars`; only the prompt footprint can see it.
+ * - `text`   — an `--append-system-prompt-file` injection the harness wrote.
+ * - `none`   — the baseline: settings scoped away AND no text injection.
+ */
+export type ExpectedInjection = 'plugin' | 'text' | 'none';
+
+/**
+ * `unknown` is deliberately not a violation: an errored or budget-capped run
+ * carries a zeroed usage block, so its footprint says nothing. Attrition is
+ * reported separately (delta #5) rather than laundered into an integrity fail.
+ */
+export type ActivationVerdict = 'ok' | 'violation' | 'unknown';
+
+export interface Activation {
+    expected: ExpectedInjection;
+    prompt_tokens: number;
+    injected_chars: number;
+    verdict: ActivationVerdict;
+    reason: string;
+}
+
+export interface ActivationViolation {
+    task_id: string;
+    seed: number;
+    arm: string;
+    kind: 'text-injection-missing' | 'text-injection-unexpected' | 'collapsed-to-baseline' | 'model-mismatch';
+    detail: string;
+}
+
+export interface ActivationAudit {
+    checked: number;
+    skipped: number;
+    violations: ActivationViolation[];
+}
+
+/**
+ * Minimum prompt-footprint ratio a plugin-bearing arm must hold over the paired
+ * baseline run before the pair is believed.
+ *
+ * Calibrated DOWNWARD from the three stored sweeps in S0.3's cost sheet, whose
+ * observed treatment/vanilla total-token ratios were 4.68× (sonnet, `package`),
+ * 1.71× (haiku, `rules-kernel-dc`) and 6.79× (haiku, `package`). 1.2 sits below
+ * the smallest of those by a wide margin on purpose: this flags a COLLAPSE to
+ * baseline — a disabled or drifted plugin — never ordinary run-to-run variance.
+ * Raising it toward the observed values would start failing legitimate runs;
+ * lowering it toward 1.0 would stop catching the failure it exists for.
+ */
+export const ACTIVATION_MIN_LIFT_RATIO = 1.2;
+
+/**
+ * The footprint an injection actually moves: everything the model was fed.
+ *
+ * Output tokens are excluded — they measure how much the model wrote, which a
+ * bigger system prompt does not reliably change, so including them would blur
+ * the very signal this audit reads.
+ */
+export function prompt_tokens(b: TokensBreakdown | Record<string, never> | null | undefined): number {
+    if (!b) {
+        return 0;
+    }
+    const t = b as Partial<TokensBreakdown>;
+    return _int(t.input_tokens) + _int(t.cache_read_input_tokens) + _int(t.cache_creation_input_tokens);
+}
+
+/** Classify an arm spec into the injection channel it is supposed to use. */
+export function expected_injection(spec: { setting_sources: string | null; inject: string | null }): ExpectedInjection {
+    if (spec.inject) {
+        return 'text';
+    }
+    return spec.setting_sources === null ? 'plugin' : 'none';
+}
+
+/**
+ * Per-trial verdict — the direction that IS decidable from one run.
+ *
+ * A text injection is checked both ways: an arm that declares one must carry
+ * it, and an arm that declares none must not. The plugin direction needs the
+ * paired baseline and is handled by `audit_activation`.
+ */
+export function activation_verdict(args: {
+    expected: ExpectedInjection;
+    tokens_breakdown: TokensBreakdown | Record<string, never> | null | undefined;
+    injected_chars: number;
+    errored: boolean;
+}): Activation {
+    const pt = prompt_tokens(args.tokens_breakdown);
+    const base = { expected: args.expected, prompt_tokens: pt, injected_chars: args.injected_chars };
+    if (args.errored || pt === 0) {
+        return { ...base, verdict: 'unknown', reason: 'errored or zero usage — footprint unreadable' };
+    }
+    if (args.expected === 'text' && args.injected_chars <= 0) {
+        return { ...base, verdict: 'violation', reason: 'text arm carried no injection' };
+    }
+    if (args.expected !== 'text' && args.injected_chars > 0) {
+        return {
+            ...base,
+            verdict: 'violation',
+            reason: `${args.expected} arm carried a ${args.injected_chars}-char injection`,
+        };
+    }
+    return { ...base, verdict: 'ok', reason: 'expected channel present' };
+}
+
+/**
+ * Cross-arm audit over a finished (or partial) record set — the plugin
+ * direction plus every per-trial verdict already stamped on the records.
+ *
+ * A pair is only judged when BOTH sides are readable; unreadable pairs are
+ * counted as `skipped`, never silently passed.
+ */
+export function audit_activation(
+    records: readonly Record<string, unknown>[],
+    opts: { baseline_arm: string; lift_arms: readonly string[]; min_ratio?: number },
+): ActivationAudit {
+    const minRatio = opts.min_ratio ?? ACTIVATION_MIN_LIFT_RATIO;
+    const violations: ActivationViolation[] = [];
+    let checked = 0;
+    let skipped = 0;
+
+    for (const rec of records) {
+        const taskId = String(rec['id'] ?? '');
+        const arms = _dict(rec['arms']);
+
+        for (const [arm, runsRaw] of Object.entries(arms)) {
+            for (const run of _list(runsRaw)) {
+                const act = _dict(run['activation']);
+                if (act['verdict'] === 'violation') {
+                    const reason = String(act['reason'] ?? '');
+                    violations.push({
+                        task_id: taskId,
+                        seed: _int(run['seed']),
+                        arm,
+                        kind: reason.includes('no injection') ? 'text-injection-missing' : 'text-injection-unexpected',
+                        detail: reason,
+                    });
+                }
+                const mc = _dict(run['model_check']);
+                if ('ok' in mc && !_truthy(mc['ok'])) {
+                    violations.push({
+                        task_id: taskId,
+                        seed: _int(run['seed']),
+                        arm,
+                        kind: 'model-mismatch',
+                        detail: String(mc['reason'] ?? ''),
+                    });
+                }
+            }
+        }
+
+        const baseBySeed = new Map<number, number>();
+        for (const run of _list(arms[opts.baseline_arm])) {
+            const pt = _runPromptTokens(run);
+            if (!_truthy(run['errored']) && pt > 0) {
+                baseBySeed.set(_int(run['seed']), pt);
+            }
+        }
+
+        for (const arm of opts.lift_arms) {
+            for (const run of _list(arms[arm])) {
+                const seed = _int(run['seed']);
+                const basePt = baseBySeed.get(seed);
+                const armPt = _runPromptTokens(run);
+                if (_truthy(run['errored']) || basePt === undefined || armPt === 0) {
+                    skipped += 1;
+                    continue;
+                }
+                checked += 1;
+                if (armPt < basePt * minRatio) {
+                    violations.push({
+                        task_id: taskId,
+                        seed,
+                        arm,
+                        kind: 'collapsed-to-baseline',
+                        detail:
+                            `prompt footprint ${armPt} vs baseline ${basePt} ` +
+                            `(ratio ${(armPt / basePt).toFixed(2)} < ${minRatio}) — ` +
+                            'the treatment surface may not have reached the model',
+                    });
+                }
+            }
+        }
+    }
+
+    return { checked, skipped, violations };
+}
+
+// ── delta #3 — model-id verification ────────────────────────────────────────
+
+/**
+ * Aliases the Claude CLI resolves server-side to whatever is current.
+ *
+ * A stored report already contains the bare alias `"sonnet"`, which makes that
+ * report unreproducible: nothing in it records which model actually answered.
+ */
+export const BARE_MODEL_ALIASES: readonly string[] = ['default', 'haiku', 'opus', 'sonnet', 'sonnet[1m]'];
+
+/** True when `model` is an alias rather than a pinned, reproducible id. */
+export function is_bare_alias(model: string): boolean {
+    return BARE_MODEL_ALIASES.includes(model.trim().toLowerCase());
+}
+
+/** Drop a trailing `-YYYYMMDD` build stamp so `claude-x-1` == `claude-x-1-20250101`. */
+export function normalize_model_id(model: string): string {
+    return model.trim().toLowerCase().replace(/-\d{8}$/, '');
+}
+
+/**
+ * Compare the requested model against the ids the CLI actually billed.
+ *
+ * `models_seen` comes from the envelope's `modelUsage` keys — the only place
+ * the run states which model answered. An empty list is `ok`: some envelopes
+ * omit the block, and refusing there would fail runs for a reporting gap
+ * rather than a real mismatch.
+ */
+export function verify_model_id(requested: string, models_seen: readonly string[]): { ok: boolean; reason: string } {
+    if (is_bare_alias(requested)) {
+        return { ok: false, reason: `requested model "${requested}" is a bare alias — pin a full model id` };
+    }
+    if (models_seen.length === 0) {
+        return { ok: true, reason: 'envelope reported no model usage — nothing to contradict' };
+    }
+    const want = normalize_model_id(requested);
+    const seen = models_seen.map(normalize_model_id);
+    if (seen.every((s) => s === want)) {
+        return { ok: true, reason: `billed model matches ${requested}` };
+    }
+    return {
+        ok: false,
+        reason: `requested ${requested} but envelope billed ${[...new Set(models_seen)].sort().join(', ')}`,
+    };
+}
+
+// ── delta #4 — sweep-level cost ─────────────────────────────────────────────
+
+/** Map a full model id onto a `pricing.yaml` tier, or null when unrecognised. */
+export function tier_for_model(model: string): string | null {
+    const m = model.toLowerCase();
+    for (const tier of ['haiku', 'sonnet', 'opus']) {
+        if (m.includes(tier)) {
+            return tier;
+        }
+    }
+    return null;
+}
+
+/**
+ * Price one run's four buckets separately.
+ *
+ * The buckets differ in price by up to 125×, so a single blended rate over the
+ * summed total is not an approximation — it is a different number.
+ */
+export function cost_usd(b: TokensBreakdown | Record<string, never> | null | undefined, rates: TierRates): number {
+    if (!b) {
+        return 0;
+    }
+    const t = b as Partial<TokensBreakdown>;
+    return (
+        (_int(t.input_tokens) * rates.input +
+            _int(t.output_tokens) * rates.output +
+            _int(t.cache_creation_input_tokens) * rates.cache_write +
+            _int(t.cache_read_input_tokens) * rates.cache_read) /
+        1_000_000
+    );
+}
+
+/**
+ * Cumulative sweep spend with a hard cap.
+ *
+ * `--max-budget-usd` is per RUN (default 1.0), so a 30×4×3 sweep at `--budget
+ * 3.5` has a $1,260 ceiling with nothing to stop it. This is the sweep-level
+ * counterpart: the first run that pushes cumulative spend over the cap aborts
+ * the sweep instead of discovering the overrun on the invoice.
+ */
+export class SweepBudget {
+    private _spent = 0;
+
+    constructor(
+        readonly cap_usd: number | null,
+        private readonly rates: TierRates | null,
+    ) {}
+
+    get spent_usd(): number {
+        return this._spent;
+    }
+
+    /** Add one run's cost; return an abort reason when the cap is crossed. */
+    add(b: TokensBreakdown | Record<string, never> | null | undefined): string | null {
+        if (!this.rates) {
+            return null;
+        }
+        this._spent += cost_usd(b, this.rates);
+        if (this.cap_usd !== null && this._spent > this.cap_usd) {
+            return `sweep budget abort: cumulative $${this._spent.toFixed(2)} > cap $${this.cap_usd.toFixed(2)}`;
+        }
+        return null;
+    }
+}
+
+// ── internals ───────────────────────────────────────────────────────────────
+
+function _int(v: unknown): number {
+    return typeof v === 'number' && Number.isFinite(v) ? Math.trunc(v) : 0;
+}
+
+function _dict(v: unknown): Record<string, unknown> {
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+
+function _list(v: unknown): Record<string, unknown>[] {
+    return Array.isArray(v) ? (v as Record<string, unknown>[]) : [];
+}
+
+function _truthy(v: unknown): boolean {
+    return Boolean(v);
+}
+
+/**
+ * Prompt footprint of one trial record — the stamped `activation` block when
+ * the sweep wrote one, else recomputed from the preserved breakdown (delta #2),
+ * so the audit also reads reports written before the stamp existed.
+ */
+function _runPromptTokens(run: Record<string, unknown>): number {
+    const stamped = _int(_dict(run['activation'])['prompt_tokens']);
+    return stamped > 0 ? stamped : prompt_tokens(run['tokens_breakdown'] as TokensBreakdown | undefined);
+}