@delegance/claude-autopilot 7.10.0 → 7.11.0-pre.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.10.1 — 2026-05-13
+
+**v7.10.1 — `examples` verb.** Patch release. Closes the discoverability
+gap a new user hits between `setup` and `scaffold --from-spec`: the
+new `claude-autopilot examples` verb prints sample specs for each
+supported stack (node / python / fastapi / go / rust) so an operator
+can pipe one to a file and feed it back into the scaffolder.
+
+**New:** `claude-autopilot examples` lists all five stacks with a
+5-line preview. `claude-autopilot examples <stack>` prints the full
+spec for one stack to stdout — pipe-friendly:
+
+```bash
+claude-autopilot examples fastapi > docs/specs/my-api.md
+# edit the spec...
+claude-autopilot scaffold --from-spec docs/specs/my-api.md
+```
+
+**Bundled examples.** Five spec markdown files ship in
+`examples/specs/{node-cli,python-cli,fastapi,go-cli,rust-cli}.md` —
+one per supported scaffold target. Each shows the `## Files` section
+shape the scaffolder reads, plus a `## Goal` and `## How to use`
+section for human readers.
+
+**Package shape.** `examples/` is added to the published `files:`
+array in package.json so the directory ships in the npm tarball — the
+verb resolves spec paths via `findPackageRoot` and works under both
+source and globally installed CLI invocations.
+
 ## 7.10.0 — 2026-05-13
 
 ### Added
@@ -91,7 +120,6 @@ usage except for the bundled `tsx` deprecation warning.
   A1-A8 covering ESM/CJS safety, CLI parser scope, PATH self-pointer,
   AST audit, type-only imports, hand-rolled PATH lookup dropping the
   `which` dep, XDG state dir, npm-only --omit=optional documentation).
-
 ## 7.7.0 (2026-05-11)
 
 **v7.7.0 — Rust scaffold support.** Minor release. Promotes Rust from

package/README.md

@@ -17,8 +17,11 @@ claude-autopilot brainstorm "add SSO with SAML for enterprise tenants"
 # → writes spec (reviewed by Codex) → writes plan (reviewed by Codex) →
 # → creates branch → implements with subagents → runs migrations →
 # → runs full test + lint + type + security gate → opens PR →
-# → dispatches multi-model review → auto-fixes bugbot findings →
-# → ready to merge
+# → runs risk-tiered Codex PR review (1/2/3 passes by spec risk) →
+# → triages bugbot findings, auto-fixes real bugs, re-runs validate →
+# → merges with your configured permissions (default is admin-squash;
+#   configure branch protection + required checks if you need to enforce
+#   reviews/CI gates that the autopilot agent should not bypass)
 ```
 
 *No hosted agent. No per-seat subscription. Runs locally on your machine, against your real repo, using your API keys. Every phase is a Claude Code skill you can intervene in, rewire, or run by itself.*
@@ -50,13 +53,14 @@ Every finding came with a concrete remediation (often a code patch or named libr
 | **Cursor BugBot / CodeRabbit** | Hosted | Per-PR or seat | Vendor's model | Review only | Post-hoc |
 | **Aider / Cline** | Local CLI | Free + your API key | User's choice | None | Continuous |
 | **OpenHands / SWE-agent** | Local research | Free | User's choice | Agent decides | Rare |
-| **claude-autopilot** | **Local CLI, your repo** | **Free + your existing Claude subscription** | **Multi-model per role (Claude + Codex + Gemini)** | **Skill-per-phase, rewireable** | **Every phase, all state on disk** |
+| **claude-autopilot** | **Local CLI, your repo** | **Open source CLI + your model/API costs (Claude / Codex / Gemini / Groq / Ollama-local)** | **Multi-model per role (Claude + Codex + Gemini)** | **Skill-per-phase, rewireable** | **Every phase, all state on disk** |
 
-Three things only this product gives you:
+Four things only this product gives you:
 
-1. **Multi-model council.** Same design question goes to Claude + Codex + Gemini in parallel; a fourth model synthesizes the consensus. Different blind spots, different recommendations, one merged answer. **No other tool dispatches multi-model on a per-decision basis.**
-2. **Your code never leaves your machine.** No cloud sandbox. No SaaS markup. The `git push` that happens at the end is from your laptop. For private repos, regulated industries, or anyone who doesn't want their unfinished code on someone else's servers — this is the only autonomous-agent shape that fits.
+1. **No hosted workspace or remote sandbox.** Your repo stays on your machine. No third-party agent runtime, no SaaS-side orchestration, no per-seat markup. Model prompts (diffs, file context, design questions) are sent to whichever LLM providers you've configured (Anthropic / OpenAI / Google / Groq / Ollama-local). For a truly local-only setup, you must point _every_ model used by the entire execution path at a local endpoint: that includes the Claude Code agent runtime itself (configure a local Claude Code provider) AND the autopilot review adapter (`openai-compatible` pointed at Ollama). Pointing only the review adapter at Ollama still ships prompts/diffs to Anthropic via Claude Code. For most teams, local-only isn't the goal; "no hosted orchestration + your existing provider keys" is.
+2. **Risk-tiered review depth (policy-driven).** Specs declare `risk: low | medium | high` in frontmatter. The autopilot skill runs 1 / 2 / 3 sequential Codex passes accordingly, each with a remediation cycle in between. Enforcement is encoded in the skill (an LLM-driven instruction set, not a hard CLI gate) so it's auditable and editable: read `.claude/skills/autopilot/SKILL.md`, swap the tier rules for your codebase, expand the auto-escalation keyword list. Designed for teams that want review depth to scale with change risk instead of running forensic-grade review on every typo.
 3. **Ships as a Claude Code skill, not a competing IDE.** `/brainstorm`, `/autopilot`, `/migrate`, `/validate` are first-class Claude Code commands. As Claude Code grows, autopilot rides that adoption. You don't switch tools to use it; it's already there.
+4. **Multi-model council, available as a verb.** `claude-autopilot council` dispatches the same diff or design question to Claude + Codex + Gemini in parallel and synthesizes the consensus. Wire it into the autopilot pipeline by editing `.claude/skills/autopilot/SKILL.md` Step 7, or invoke standalone for one-off design decisions. The default pipeline uses sequential Codex review (cheaper, faster, often sufficient for routine changes); council is the higher-rigor option when you want broader model diversity.
 
 Plus the four practical differences:
 
@@ -128,9 +132,9 @@ Each phase is a Claude Code skill (`.claude/skills/<name>/SKILL.md`). You can in
 | **Migrate** | `migrate` | Dispatches to the configured migration skill (see [Migrate phase](#migrate-phase)) — runs your migration tool dev → QA → prod with per-env validation | Deterministic |
 | **Validate** | `validate` | Static rules + tests + type check + security scan + LLM review | Any |
 | **PR** | `commit-push-pr` | Opens the PR with auto-generated title, summary, and test plan | Claude |
-| **Review** | `review-2pass` / `council` | Multi-model review of the diff (critical pass + informational pass) | Multiple |
+| **Review** | `codex-pr-review` (default) or `council` (opt-in) | Sequential Codex pass on the diff with risk-tiered iteration count (1/2/3 passes for low/medium/high). Swap in `council` for parallel multi-model dispatch if you want higher rigor. | Codex (default) or multi-model |
 | **Triage** | `bugbot` | Fetches automated reviewer findings, auto-fixes real bugs, dismisses false positives | Claude |
-| **Deploy** | `deploy` | Deploys via configured adapter (`vercel` \| `fly` \| `render` \| `generic`) with optional log streaming, health check, and bounded auto-rollback (see [Deploy phase](#deploy-phase)) | Deterministic |
+| **Deploy** (opt-in) | `deploy` | Deploys via configured adapter (`vercel` \| `fly` \| `render` \| `generic`) with optional log streaming, health check, and bounded auto-rollback (see [Deploy phase](#deploy-phase)). Not on the default `/autopilot` critical path: the autopilot loop ends at merge, and your CI/CD handles prod. Invoke `claude-autopilot deploy` directly, or wire it into the autopilot skill as Step 10. | Deterministic |
 
 ### Migrate phase
 
@@ -181,11 +185,13 @@ deploy:
 
 Features that are hard or impossible to find in the competitive set:
 
-- **Multi-model council review** — dispatch the same diff to 3+ models in parallel, synthesize agreement. Catches blind spots no single model sees.
-- **Fix with test verification** — `claude-autopilot fix` runs your full test suite after every patch and reverts on failure. Safer than any tool that proposes fixes without running your tests.
-- **Bug-bot auto-triage** — watches Cursor BugBot / Copilot comments on your PR, triages each (real bug vs false positive), auto-fixes confirmed bugs, dismisses noise with explanations.
-- **Schema alignment rule** — ensures DB migrations, backend types, and frontend types stay in sync. Custom static rule, not something any competitor ships.
-- **SARIF output + GitHub Code Scanning integration** — findings appear as annotations in the PR and in the Security tab.
+- **Risk-tiered review depth (policy-driven).** Specs are tagged `risk: low | medium | high` in their frontmatter, with auto-escalation by keyword detection for sensitive categories (auth, multi-tenancy, sandboxing, billing, secrets, migrations, RLS, deploy/IAM, vector-DB tenancy — extend the list in the skill for your codebase). The pipeline runs 1 / 2 / 3 sequential Codex passes accordingly, each with a remediation cycle in between. Enforcement is encoded in `.claude/skills/autopilot/SKILL.md` (LLM-driven instructions, not a hard CLI gate), so it's auditable and editable. For teams that need hard enforcement, gate the merge step on the configured pass count by extending the skill or wrapping the CLI.
+- **Retry-loop sameness detector.** Validate / Codex / bugbot retry loops compute a failure fingerprint before consuming each retry. If the same fingerprint fires twice in a row, the pipeline halts and surfaces it to you — instead of burning the remaining retry budget on attempts that are making no progress. Available as a public subpath import (`@delegance/claude-autopilot/run-state/sameness-detector`) for embedding into your own retry loops.
+- **Multi-model council, available as a verb.** `claude-autopilot council` dispatches the same prompt to 3+ models in parallel and synthesizes the consensus. Opt-in for the autopilot pipeline (wire it into Step 7 of the autopilot skill), or invoke standalone for design decisions and architecture questions.
+- **Fix with test verification.** `claude-autopilot fix --verify` runs your full test suite after every patch and reverts on failure. Safer than any tool that proposes fixes without running your tests.
+- **Bug-bot auto-triage.** Watches Cursor BugBot / Copilot comments on your PR, triages each (real bug vs false positive), auto-fixes confirmed bugs, dismisses noise with explanations.
+- **Schema alignment rule.** Ensures DB migrations, backend types, and frontend types stay in sync. Custom static rule, not something any competitor ships.
+- **SARIF output + GitHub Code Scanning integration.** Findings appear as annotations in the PR and in the Security tab.
 
 ## Just the review layer
 

package/dist/src/cli/examples.d.ts

@@ -0,0 +1,15 @@
+/** Supported stack id → relative path under `examples/specs/`. */
+export declare const EXAMPLE_STACKS: Record<string, string>;
+/** Public stack ids in the order we want them listed. */
+export declare const EXAMPLE_STACK_IDS: readonly ["node", "python", "fastapi", "go", "rust"];
+/** Resolve the absolute on-disk path for a stack's spec file. */
+export declare function resolveExamplePath(stack: string): string | null;
+/**
+ * Run the `examples` verb. With no `stack`, prints an intro + a summary card
+ * for each stack (path + first ~5 lines of the spec). With a stack id, prints
+ * the full spec content to stdout (suitable for piping into a file).
+ *
+ * Returns the exit code so the dispatcher can `process.exit(code)`.
+ */
+export declare function runExamples(stack?: string): number;
+//# sourceMappingURL=examples.d.ts.map

package/dist/src/cli/examples.js

@@ -0,0 +1,108 @@
+// v7.7.1 — `claude-autopilot examples [<stack>]`
+//
+// Discoverability bridge between `setup` and `scaffold --from-spec`. A new
+// user runs `setup`, then `scaffold --from-spec ???` and has no idea what a
+// spec looks like. This verb prints sample specs — one per supported stack —
+// straight to stdout so the operator can pipe to a file, edit, and feed back
+// into `scaffold`.
+//
+//   claude-autopilot examples                   → list all 5 stacks
+//   claude-autopilot examples node              → print just the Node spec
+//   claude-autopilot examples fastapi > foo.md  → spec-as-template via shell
+//
+// The spec files ship in the published tarball via the `files: ["examples/"]`
+// entry in package.json. At runtime we resolve them relative to the package
+// root (found by `findPackageRoot`), so `examples` works whether the CLI is
+// run from source, the built dist/, or a globally installed `npm i -g`
+// invocation.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { findPackageRoot } from "./_pkg-root.js";
+/** Supported stack id → relative path under `examples/specs/`. */
+export const EXAMPLE_STACKS = {
+    node: 'examples/specs/node-cli.md',
+    python: 'examples/specs/python-cli.md',
+    fastapi: 'examples/specs/fastapi.md',
+    go: 'examples/specs/go-cli.md',
+    rust: 'examples/specs/rust-cli.md',
+};
+/** Public stack ids in the order we want them listed. */
+export const EXAMPLE_STACK_IDS = ['node', 'python', 'fastapi', 'go', 'rust'];
+const BOLD = (t) => `\x1b[1m${t}\x1b[0m`;
+const DIM = (t) => `\x1b[2m${t}\x1b[0m`;
+/** Resolve the absolute on-disk path for a stack's spec file. */
+export function resolveExamplePath(stack) {
+    const rel = EXAMPLE_STACKS[stack];
+    if (!rel)
+        return null;
+    const root = findPackageRoot(import.meta.url);
+    if (!root)
+        return null;
+    return path.join(root, rel);
+}
+/** Print the first N non-empty lines of a file for the listing summary. */
+function previewHead(absPath, n) {
+    try {
+        const body = fs.readFileSync(absPath, 'utf8');
+        const lines = body.split('\n');
+        const head = [];
+        for (const line of lines) {
+            head.push(line);
+            if (head.length >= n)
+                break;
+        }
+        return head.join('\n');
+    }
+    catch {
+        return '(failed to read example file)';
+    }
+}
+/**
+ * Run the `examples` verb. With no `stack`, prints an intro + a summary card
+ * for each stack (path + first ~5 lines of the spec). With a stack id, prints
+ * the full spec content to stdout (suitable for piping into a file).
+ *
+ * Returns the exit code so the dispatcher can `process.exit(code)`.
+ */
+export function runExamples(stack) {
+    if (!stack) {
+        console.log('');
+        console.log(BOLD('Sample specs for each supported stack.'));
+        console.log(DIM('Pass `examples <stack>` to print just one. Pipe to a file to use as a template:'));
+        console.log(DIM('  claude-autopilot examples node > docs/specs/my-feature.md'));
+        console.log(DIM('  claude-autopilot scaffold --from-spec docs/specs/my-feature.md'));
+        console.log('');
+        for (const id of EXAMPLE_STACK_IDS) {
+            const abs = resolveExamplePath(id);
+            if (!abs || !fs.existsSync(abs)) {
+                console.log(`${BOLD(id)}  ${DIM('(example file not found)')}`);
+                console.log('');
+                continue;
+            }
+            console.log(BOLD(id));
+            console.log(DIM(`  ${abs}`));
+            const head = previewHead(abs, 5);
+            for (const line of head.split('\n')) {
+                console.log(`  ${line}`);
+            }
+            console.log('');
+        }
+        return 0;
+    }
+    const abs = resolveExamplePath(stack);
+    if (!abs) {
+        process.stderr.write(`\x1b[31m[claude-autopilot] unknown stack "${stack}" — valid: ${EXAMPLE_STACK_IDS.join(', ')}\x1b[0m\n`);
+        return 1;
+    }
+    if (!fs.existsSync(abs)) {
+        process.stderr.write(`\x1b[31m[claude-autopilot] example file missing on disk: ${abs}\x1b[0m\n`);
+        process.stderr.write(`\x1b[2m  Did the published tarball include the "examples/" directory? See package.json "files".\x1b[0m\n`);
+        return 1;
+    }
+    const body = fs.readFileSync(abs, 'utf8');
+    process.stdout.write(body);
+    if (!body.endsWith('\n'))
+        process.stdout.write('\n');
+    return 0;
+}
+//# sourceMappingURL=examples.js.map

package/dist/src/cli/help-text.js

@@ -29,6 +29,7 @@ export const HELP_GROUPS = [
             { verb: 'init', summary: 'Scaffold guardrail.config.yaml + auto-detect migrate stack (writes .autopilot/stack.md)' },
             { verb: 'setup', summary: 'Auto-detect stack, write config, install pre-push hook' },
             { verb: 'scaffold', summary: 'Scaffold project skeleton from a spec markdown (--from-spec <path> [--stack node|python|fastapi|go|rust])' },
+            { verb: 'examples', summary: 'Print sample specs for each supported stack (use as starter templates for `scaffold --from-spec`)' },
             { verb: 'autopilot', summary: 'Multi-phase orchestrator — run scan → spec → plan → implement under one runId (v6.2.0)' },
             { verb: 'brainstorm', summary: 'Pipeline entry point (Claude Code skill — see /brainstorm)' },
             { verb: 'spec', summary: 'Spec-writing pointer (Claude Code skill — see /brainstorm)' },
@@ -213,6 +214,18 @@ export const HELP_OPTIONS = {
     claude-autopilot autopilot
     claude-autopilot autopilot --budget 25
     claude-autopilot autopilot --phases=scan,spec,plan`,
+    examples: `Options (examples):
+  [<stack>]            Optional: print only the spec for one stack (node|python|fastapi|go|rust)
+                       With no arg, lists all supported stacks with a 5-line preview each.
+
+  Behavior: read-only. Reads bundled spec files from the package's
+            \`examples/specs/\` directory and prints them to stdout. Pipe
+            to a file to use as a starter template:
+
+              claude-autopilot examples node > docs/specs/my-feature.md
+              claude-autopilot scaffold --from-spec docs/specs/my-feature.md
+
+  Exit codes: 0 success, 1 unknown stack id or missing bundled file.`,
     dashboard: `Options (dashboard):
   login                Open browser, mint API key via loopback callback
   logout               Revoke server-side, delete local config

package/dist/src/cli/index.js

@@ -226,7 +226,7 @@ These are aliases for the flat subcommands; they still work without the 'advance
 // gc, delete, doctor) are dispatched inside its case block. The singular
 // `run resume` form is handled BEFORE the default `run` -> review dispatch
 // kicks in (see disambiguation block just below).
-const SUBCOMMANDS = ['init', 'run', 'runs', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'deploy', 'brainstorm', 'spec', 'plan', 'implement', 'review', 'validate', 'autopilot', 'internal', 'help', '--help', '-h'];
+const SUBCOMMANDS = ['init', 'run', 'runs', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'deploy', 'brainstorm', 'spec', 'plan', 'implement', 'review', 'validate', 'autopilot', 'examples', 'internal', 'help', '--help', '-h'];
 const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path', 'adapter', 'ref', 'sha', 'spec', 'context', 'mode', 'phases', 'budget', 'stack'];
 // Bare invocation — no subcommand, no flags → show welcome guide
 if (args.length === 0) {
@@ -993,6 +993,17 @@ switch (subcommand) {
         process.exit(0);
         break;
     }
+    case 'examples': {
+        // v7.7.1 — `claude-autopilot examples [<stack>]`. Bridges the
+        // discoverability gap between `setup` and `scaffold --from-spec` —
+        // new users don't know what a spec looks like. Optional positional
+        // arg selects a single stack; no arg lists all five.
+        const { runExamples } = await import("./examples.js");
+        const target = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+        const code = runExamples(target);
+        process.exit(code);
+        break;
+    }
     case 'council': {
         const config = flag('config');
         const prompt = flag('prompt');

package/dist/src/core/concurrent-dispatch/budget-reservation.d.ts

@@ -0,0 +1,163 @@
+import { GuardrailError } from '../errors.ts';
+import { SerializedWriter } from '../run-state/serialized-writer.ts';
+/** Budget caps for a single run. `perRunUSD` is the hard ceiling on total
+ *  committed spend (spent + active reservations) across all concurrent
+ *  tasks. `perSubagentUSD` is the per-task hard cap that dispatch refuses
+ *  to exceed even if perRunUSD has headroom. */
+export interface BudgetCaps {
+    /** Total USD this run is allowed to commit across all subagents +
+     *  in-flight reservations. */
+    perRunUSD: number;
+    /** Hard per-subagent cap. A pre-flight estimate exceeding this rejects
+     *  dispatch; an actual cost exceeding it mid-execution triggers the
+     *  scheduler's SIGTERM path (PR 4) — this layer just emits the
+     *  `task.failed` event with `error_type: 'budget_exceeded'`. */
+    perSubagentUSD: number;
+}
+/** Per-task ledger entry. Reconstructed via `replayFromEvents` at startup
+ *  / resume. */
+export interface ReservationEntry {
+    task_id: string;
+    /** Latest reservation value (after any
+     *  `task.budget_increased_reservation` events; ABSOLUTE, not delta). */
+    reserved_usd: number;
+    /** True once `task.budget_released` has landed for this task. */
+    released: boolean;
+    /** Actual cost if `released` is true. */
+    actual_cost_usd?: number;
+}
+/** Result of replaying events.ndjson into a fresh ledger state. */
+export interface BudgetReplaySummary {
+    /** Sum of `actual_cost_usd` across released tasks. Committed against
+     *  `perRunUSD` permanently. */
+    spentTotal: number;
+    /** Sum of `reserved_usd` for tasks NOT yet released. Each task
+     *  contributes its LATEST reservation (absolute value), not the sum of
+     *  reserved + increased values. */
+    activeReservedTotal: number;
+    /** `spentTotal + activeReservedTotal`. The number the headroom check
+     *  compares against `perRunUSD`. */
+    committedTotal: number;
+    /** Per-task latest state. */
+    perTask: Map<string, ReservationEntry>;
+}
+/** Thrown by `reserve()` / `increaseReservation()` when the requested
+ *  amount would push the run over `perRunUSD`, or when a pre-flight
+ *  exceeds `perSubagentUSD`. Carries the GuardrailError code
+ *  `budget_exceeded` for upstream resume classification. */
+export declare class BudgetExceededError extends GuardrailError {
+    constructor(message: string, details: Record<string, unknown>);
+}
+export interface ReserveOptions {
+    /** Pre-flight cost estimate for the task in USD. */
+    preFlightEstimateUsd: number;
+    /** Budget caps for this run. */
+    caps: BudgetCaps;
+}
+export interface IncreaseReservationOptions {
+    /** New reservation total (NOT a delta — the absolute new value). */
+    newReservedUsd: number;
+    /** Free-form reason captured on the event. */
+    reason: string;
+    /** Budget caps for this run. */
+    caps: BudgetCaps;
+}
+export interface ReleaseOptions {
+    /** Actual cost spent by the subagent (from telemetry). */
+    actualCostUsd: number;
+}
+/**
+ * Budget reservation ledger. One instance per run, owned by the scheduler.
+ * All mutations route through the supplied `SerializedWriter` and re-replay
+ * events.ndjson under the exclusive lock so they are atomic against
+ * concurrent callers AND any other `BudgetReservation` instances pointed at
+ * the same run.
+ */
+export declare class BudgetReservation {
+    private readonly writer;
+    /** In-memory mirror of disk state, kept for fast `snapshot()` reads.
+     *  NOT authoritative — every mutating operation re-replays the on-disk
+     *  log inside the writer's exclusive lock before checking caps. Per-task
+     *  reservations stored in USD (public API); the running totals below are
+     *  in MICROS (integer-safe arithmetic). */
+    private reservations;
+    private spentMicros;
+    private activeReservedMicros;
+    constructor(writer: SerializedWriter);
+    /** Re-seed in-memory state from events.ndjson. Call on construction OR
+     *  on resume. Safe to call multiple times — overwrites the cache. */
+    hydrateFromEvents(eventsNdjsonPath: string): Promise<void>;
+    /** Read the current in-memory state. Best-effort: a concurrent writer
+     *  in another instance could make this stale until the next mutating
+     *  call re-hydrates from disk. */
+    snapshot(): BudgetReplaySummary;
+    /**
+     * Reserve budget for a task. Atomic under the writer lock:
+     *
+     *   1. HARD cap check (pre-lock): `preFlightEstimate <= caps.perSubagentUSD`
+     *   2. Acquire SerializedWriter lock
+     *   3. Re-replay events.ndjson from disk (authoritative)
+     *   4. Verify task doesn't already have an in-flight reservation
+     *   5. Verify `caps.perRunUSD - committedTotal >= preFlightEstimate`
+     *      (committedTotal = spent + active reservations)
+     *   6. If pass: append `task.budget_reserved` event + fsync
+     *      If fail: append `task.budget_halt` event + fsync, then throw
+     *   7. Release lock
+     *
+     * Throws `BudgetExceededError` on cap violations. The `task.budget_halt`
+     * variant is durable: the event lands inside the same critical section
+     * before the throw propagates, so a crash post-throw still surfaces the
+     * halt on resume.
+     */
+    reserve(taskId: string, opts: ReserveOptions): Promise<void>;
+    /**
+     * Bump an in-flight reservation to a new ABSOLUTE value. Atomic under
+     * the writer lock; re-replays disk state before checking caps.
+     * Re-checks `perRunUSD` against the NEW reservation total; halts the
+     * run with `task.budget_halt` if the bump would exceed the cap.
+     *
+     * Throws `BudgetExceededError` (with durable `task.budget_halt`) if no
+     * prior reservation exists, the bump is downward (use `release`
+     * instead), or the bump exceeds caps.
+     */
+    increaseReservation(taskId: string, opts: IncreaseReservationOptions): Promise<void>;
+    /**
+     * Release a reservation with the actual cost. Atomic under the writer
+     * lock; re-replays disk state. Moves the task's commitment from
+     * `activeReserved` to `spent`. Emits `task.budget_released` with
+     * `delta_vs_reservation_usd` (positive = under, negative = over).
+     *
+     * Note: a release with `actualCostUsd > reserved_usd` is NOT a halt —
+     * the budget was already committed at reservation time. The scheduler
+     * is expected to issue `increaseReservation` mid-flight when telemetry
+     * suggests overrun, and to emit `task.failed{error_type:'budget_exceeded'}`
+     * if the increase itself fails. This `release` just records the truth.
+     */
+    release(taskId: string, opts: ReleaseOptions): Promise<void>;
+    /** Internal: replace in-memory ledger from a replay summary (in micros).
+     *  Used by every mutating method to re-sync cache with disk under the
+     *  lock. */
+    private applyReplayMicros;
+    /**
+     * Replay events.ndjson into a fresh `BudgetReplaySummary` (decimal USD).
+     * Used by:
+     *   1. `hydrateFromEvents` — runtime cache seed on resume / startup
+     *   2. tests — to assert reconstruction is exact
+     *
+     * Internally calls `replayFromEventsMicros` and converts to USD at the
+     * boundary so external consumers see decimal numbers, but the fold itself
+     * is integer-micro arithmetic.
+     *
+     * Line parsing is lenient: blank lines are skipped, parse failures stop
+     * the walk (treated as truncated tail; the next `appendEvent` would
+     * emit `run.recovery`, and budget state stays consistent up to the
+     * last-known-good line).
+     */
+    static replayFromEvents(eventsNdjsonPath: string): BudgetReplaySummary;
+    /**
+     * Internal: micro-precision replay. Used by every mutating method INSIDE
+     * `withExclusive` so cap checks operate on integer arithmetic.
+     */
+    private static replayFromEventsMicros;
+}
+//# sourceMappingURL=budget-reservation.d.ts.map