@delegance/claude-autopilot 7.10.1 → 7.11.0-pre.2

package/dist/src/core/concurrent-dispatch/budget-reservation.js

@@ -0,0 +1,642 @@
+// src/core/concurrent-dispatch/budget-reservation.ts
+//
+// Budget reservation ledger for concurrent subagent dispatch. PR 3 of 6 of
+// the v7.11.0 concurrent subagent execution spec — the budget half of the
+// "event + budget atomicity" layer.
+//
+// What problem does this solve?
+//
+//   A naive concurrent dispatcher would read the current spend, decide
+//   "remaining budget is $5, this subagent costs ~$2, dispatch it", and
+//   write `task.started` — but TWO dispatches running this logic in parallel
+//   could both observe $5 remaining, both pass the check, and over-spend.
+//
+//   The fix is to make (replay → check → append) atomic. Every reserve /
+//   release / increase routes through the per-run `SerializedWriter`'s
+//   `withExclusive` API, which holds an exclusive file lock for the full
+//   critical section. Under that lock we re-replay events.ndjson from disk
+//   (authoritative source) BEFORE the budget check, so even a second
+//   `BudgetReservation` instance (or a second scheduler process) sees the
+//   first instance's appended reservation before its own check runs.
+//
+// Budget accounting model (corrected after Codex pass 1):
+//
+//   We track three running totals (internally as INTEGER MICROS to avoid
+//   floating-point drift; see "Why integer micros" below):
+//
+//     spentTotal       = sum of `task.budget_released.actual_cost_usd`
+//                        — money the subagent actually spent and we now
+//                        commit against the run cap.
+//
+//     activeReservedTotal = sum of (reserved_usd) for tasks whose latest
+//                           event is `task.budget_reserved` or
+//                           `task.budget_increased_reservation` (NOT yet
+//                           released). The latest increase REPLACES the
+//                           prior reserved value (absolute, not delta).
+//
+//     committedTotal   = spentTotal + activeReservedTotal
+//
+//   The headroom check is `caps.perRunUSD - committedTotal >= newReservation`.
+//   Releasing a task: spentTotal += actualCost; activeReservedTotal -=
+//   reserved. Net effect: a $6 reservation released with $6 actual spend
+//   moves $6 from "active reserved" to "spent" — total commitment is
+//   unchanged. Earlier the naive `in_flight = reserved - released_actual`
+//   model would have left $0 committed, allowing the run to over-spend.
+//
+// Why replay events.ndjson on every reserve?
+//
+//   The single-scheduler-per-run contract is enforced upstream (by the
+//   per-run lock in `lock.ts` + cross-process repo lock from PR 2), so in
+//   well-behaved deployments the in-memory cache and disk state agree.
+//
+//   But the file lock alone doesn't prevent stale-cache reasoning if a
+//   second `BudgetReservation` instance is created (e.g. test bug, a
+//   resumed run that didn't `hydrateFromEvents`, or a future BullMQ
+//   worker design). Authoritative replay inside the lock is the
+//   correctness floor; the cache is just an optimisation.
+//
+//   Cost: O(n) read of events.ndjson per reserve, where n = number of
+//   events so far. Acceptable up to ~100k events per run; if we ever push
+//   beyond that we can add a `budget-state-cache.json` checkpoint.
+//
+// Why integer micros (Codex pass 1, WARN #6)?
+//
+//   JS `number` is IEEE-754 double, so naive USD arithmetic accumulates
+//   error: `0.1 + 0.2 === 0.30000000000000004`. Over thousands of
+//   reservations this drift can flip a cap check the wrong way. We store
+//   all internal totals as integer micros (1 USD = 1_000_000 micros).
+//   Range: `Number.MAX_SAFE_INTEGER / 1_000_000 ≈ $9.007e9` — way more
+//   than any plausible per-run budget. Public API still accepts and emits
+//   decimal USD; we convert at the boundary via `Math.round(usd *
+//   1_000_000)` (input) and `micros / 1_000_000` (output).
+//
+// What this file is NOT:
+//
+//   * The dispatch loop — that's PR 4 (#191). This file exports the API
+//     PR 4 calls to gate dispatch.
+//   * A spend tracker for the v6 run-state engine's `phase.cost` events —
+//     those remain unchanged. Reservations live alongside `phase.cost`.
+//
+// Spec:
+//   docs/superpowers/specs/2026-05-19-v7.11.0-concurrent-subagent-execution-design.md
+//   sections "Budget reservation semantics" + "Integration with run-state
+//   engine (v6)".
+import * as fs from 'node:fs';
+import { GuardrailError } from "../errors.js";
+// ---- Micros conversion helpers -------------------------------------------
+// 1 USD = 1_000_000 micros. `Math.round` uses round-half-away-from-zero (NOT
+// banker's rounding); for budget enforcement at the boundary where every
+// reservation is a fresh value, the rounding mode is symmetric and inputs
+// rarely land exactly on a half-micro, so the simpler primitive is fine.
+// (Inputs are also `Number.isFinite` and `>= 0` validated upstream — see
+// `assertNonNegativeFiniteUsd`.) Range: `Number.MAX_SAFE_INTEGER /
+// 1_000_000 ≈ $9.007e9` — more than any plausible per-run cap.
+const MICROS_PER_USD = 1_000_000;
+function usdToMicros(usd) {
+    return Math.round(usd * MICROS_PER_USD);
+}
+function microsToUsd(micros) {
+    return micros / MICROS_PER_USD;
+}
+/** Max USD value we will accept at the public API. Above this, the
+ *  integer-micros representation could exceed `Number.MAX_SAFE_INTEGER`
+ *  and arithmetic would lose precision — making cap comparisons
+ *  unreliable. `MAX_SAFE_INTEGER / MICROS_PER_USD ≈ $9.007e9` which is
+ *  more than any plausible per-run budget for a CLI tool. */
+const MAX_USD = Number.MAX_SAFE_INTEGER / MICROS_PER_USD;
+/** Reject NaN, Infinity, negative, and out-of-safe-range USD inputs at the
+ *  public API boundary before they reach the micros conversion.
+ *
+ *  Codex pass 2 CRITICAL #2 — `NaN > anything` is false so a NaN
+ *  preFlightEstimate would slip past the hard cap, and `usdToMicros(NaN)`
+ *  returns NaN which then corrupts every subsequent comparison.
+ *
+ *  Codex pass 3 WARN — values above MAX_USD would lose precision once
+ *  converted to micros and aggregated, breaking exact cap comparisons. */
+function assertNonNegativeFiniteUsd(label, value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new GuardrailError(`${label}: must be a finite non-negative number (got ${String(value)})`, {
+            code: 'user_input',
+            provider: 'concurrent-dispatch',
+            details: { label, value },
+        });
+    }
+    if (value > MAX_USD) {
+        throw new GuardrailError(`${label}: must be <= $${MAX_USD} (got ${String(value)}) — exceeds safe-integer micros range`, {
+            code: 'user_input',
+            provider: 'concurrent-dispatch',
+            details: { label, value, maxUsd: MAX_USD },
+        });
+    }
+}
+/** 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 class BudgetExceededError extends GuardrailError {
+    constructor(message, details) {
+        super(message, {
+            code: 'budget_exceeded',
+            provider: 'concurrent-dispatch',
+            details,
+        });
+    }
+}
+/**
+ * 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 class BudgetReservation {
+    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). */
+    reservations = new Map();
+    spentMicros = 0;
+    activeReservedMicros = 0;
+    constructor(writer) {
+        this.writer = writer;
+    }
+    /** Re-seed in-memory state from events.ndjson. Call on construction OR
+     *  on resume. Safe to call multiple times — overwrites the cache. */
+    async hydrateFromEvents(eventsNdjsonPath) {
+        const replay = BudgetReservation.replayFromEventsMicros(eventsNdjsonPath);
+        this.applyReplayMicros(replay);
+    }
+    /** 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() {
+        return {
+            spentTotal: microsToUsd(this.spentMicros),
+            activeReservedTotal: microsToUsd(this.activeReservedMicros),
+            committedTotal: microsToUsd(this.spentMicros + this.activeReservedMicros),
+            perTask: new Map(this.reservations),
+        };
+    }
+    /**
+     * 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.
+     */
+    async reserve(taskId, opts) {
+        // Input validation (Codex pass 2 CRITICAL #2). Reject NaN/Infinity/
+        // negative BEFORE the hard-cap check — `NaN > x` is false in JS so a
+        // NaN estimate would otherwise sail past the cap and corrupt every
+        // downstream comparison.
+        assertNonNegativeFiniteUsd(`task.${taskId}: preFlightEstimateUsd`, opts.preFlightEstimateUsd);
+        assertNonNegativeFiniteUsd('caps.perRunUSD', opts.caps.perRunUSD);
+        assertNonNegativeFiniteUsd('caps.perSubagentUSD', opts.caps.perSubagentUSD);
+        if (opts.preFlightEstimateUsd > opts.caps.perSubagentUSD) {
+            throw new BudgetExceededError(`task.${taskId}: pre-flight estimate $${opts.preFlightEstimateUsd.toFixed(2)} exceeds perSubagentUSD cap of $${opts.caps.perSubagentUSD.toFixed(2)}`, {
+                task_id: taskId,
+                preFlightEstimateUsd: opts.preFlightEstimateUsd,
+                perSubagentUSD: opts.caps.perSubagentUSD,
+                violation: 'per_subagent_hard_cap',
+            });
+        }
+        const preflightMicros = usdToMicros(opts.preFlightEstimateUsd);
+        const perRunMicros = usdToMicros(opts.caps.perRunUSD);
+        await this.writer.withExclusive(async ({ writeEvent, eventsNdjsonPath }) => {
+            // Authoritative replay INSIDE the lock — defends against stale
+            // cache when multiple BudgetReservation instances share an event
+            // file. Also rebuilds our own cache so the next snapshot() call
+            // reflects disk state.
+            const disk = BudgetReservation.replayFromEventsMicros(eventsNdjsonPath);
+            this.applyReplayMicros(disk);
+            // Codex pass 2 CRITICAL #1: `task.budget_halt` is documented as the
+            // terminal record. Once it lands for a task, no later mutating
+            // event for that task is allowed. (Run-wide halt enforcement lives
+            // at the scheduler layer — this guard prevents the same-task
+            // resurrection class of bug.)
+            if (disk.haltedTaskIds.has(taskId)) {
+                throw new GuardrailError(`task.${taskId}: cannot reserve; task is terminally halted`, {
+                    code: 'adapter_bug',
+                    provider: 'concurrent-dispatch',
+                    details: { task_id: taskId, terminal_state: 'budget_halt' },
+                });
+            }
+            // Codex pass 2 WARN #5: task_ids are immutable across their
+            // lifecycle. A released task cannot be re-reserved under the same
+            // id — caller must use a new id (or future attempt_id model).
+            const existing = this.reservations.get(taskId);
+            if (existing) {
+                throw new GuardrailError(existing.released
+                    ? `task.${taskId}: cannot re-reserve a released task_id; use a new id`
+                    : `task.${taskId}: already has an in-flight reservation`, {
+                    code: 'adapter_bug',
+                    provider: 'concurrent-dispatch',
+                    details: { task_id: taskId, released: existing.released },
+                });
+            }
+            const committedMicros = this.spentMicros + this.activeReservedMicros;
+            const remainingMicros = perRunMicros - committedMicros;
+            if (remainingMicros < preflightMicros) {
+                // Halt: emit the terminal record THEN throw. The event lands
+                // first so resume classifies this correctly even if the throw
+                // propagates past a crash boundary.
+                const remainingUsd = microsToUsd(remainingMicros);
+                await writeEvent({
+                    event: 'task.budget_halt',
+                    task_id: taskId,
+                    budget_remaining_usd: remainingUsd,
+                    preflight_estimate_usd: opts.preFlightEstimateUsd,
+                });
+                throw new BudgetExceededError(`task.${taskId}: remaining budget $${remainingUsd.toFixed(2)} below pre-flight estimate $${opts.preFlightEstimateUsd.toFixed(2)} (perRunUSD=$${opts.caps.perRunUSD.toFixed(2)}, spent=$${microsToUsd(this.spentMicros).toFixed(2)}, active=$${microsToUsd(this.activeReservedMicros).toFixed(2)})`, {
+                    task_id: taskId,
+                    preFlightEstimateUsd: opts.preFlightEstimateUsd,
+                    perRunUSD: opts.caps.perRunUSD,
+                    spentTotalUsd: microsToUsd(this.spentMicros),
+                    activeReservedTotalUsd: microsToUsd(this.activeReservedMicros),
+                    remaining: remainingUsd,
+                    violation: 'per_run_cap_at_reserve',
+                });
+            }
+            // Reservation approved. Append event + update cache.
+            const remainingAfterMicros = remainingMicros - preflightMicros;
+            await writeEvent({
+                event: 'task.budget_reserved',
+                task_id: taskId,
+                reserved_usd: opts.preFlightEstimateUsd,
+                run_budget_remaining_after_reservation_usd: microsToUsd(remainingAfterMicros),
+            });
+            this.reservations.set(taskId, {
+                task_id: taskId,
+                reserved_usd: opts.preFlightEstimateUsd,
+                released: false,
+            });
+            this.activeReservedMicros += preflightMicros;
+        });
+    }
+    /**
+     * 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.
+     */
+    async increaseReservation(taskId, opts) {
+        // Input validation (Codex pass 2 CRITICAL #2).
+        assertNonNegativeFiniteUsd(`task.${taskId}: newReservedUsd`, opts.newReservedUsd);
+        assertNonNegativeFiniteUsd('caps.perRunUSD', opts.caps.perRunUSD);
+        assertNonNegativeFiniteUsd('caps.perSubagentUSD', opts.caps.perSubagentUSD);
+        // Pre-lock validation that doesn't depend on on-disk state.
+        if (opts.newReservedUsd > opts.caps.perSubagentUSD) {
+            throw new BudgetExceededError(`task.${taskId}: increased reservation $${opts.newReservedUsd.toFixed(2)} exceeds perSubagentUSD cap of $${opts.caps.perSubagentUSD.toFixed(2)}`, {
+                task_id: taskId,
+                newReservedUsd: opts.newReservedUsd,
+                perSubagentUSD: opts.caps.perSubagentUSD,
+                violation: 'per_subagent_hard_cap_on_increase',
+            });
+        }
+        const newReservedMicros = usdToMicros(opts.newReservedUsd);
+        const perRunMicros = usdToMicros(opts.caps.perRunUSD);
+        await this.writer.withExclusive(async ({ writeEvent, eventsNdjsonPath }) => {
+            const disk = BudgetReservation.replayFromEventsMicros(eventsNdjsonPath);
+            this.applyReplayMicros(disk);
+            if (disk.haltedTaskIds.has(taskId)) {
+                throw new GuardrailError(`task.${taskId}: cannot increase reservation; task is terminally halted`, {
+                    code: 'adapter_bug',
+                    provider: 'concurrent-dispatch',
+                    details: { task_id: taskId, terminal_state: 'budget_halt' },
+                });
+            }
+            const prior = this.reservations.get(taskId);
+            if (!prior || prior.released) {
+                throw new GuardrailError(`task.${taskId}: cannot increase reservation; no in-flight reservation found`, {
+                    code: 'adapter_bug',
+                    provider: 'concurrent-dispatch',
+                    details: { task_id: taskId },
+                });
+            }
+            const priorReservedMicros = usdToMicros(prior.reserved_usd);
+            if (newReservedMicros <= priorReservedMicros) {
+                throw new GuardrailError(`task.${taskId}: increaseReservation must raise the cap (prior=$${prior.reserved_usd.toFixed(2)}, new=$${opts.newReservedUsd.toFixed(2)})`, {
+                    code: 'user_input',
+                    provider: 'concurrent-dispatch',
+                    details: {
+                        task_id: taskId,
+                        priorReservedUsd: prior.reserved_usd,
+                        newReservedUsd: opts.newReservedUsd,
+                    },
+                });
+            }
+            const deltaMicros = newReservedMicros - priorReservedMicros;
+            const projectedCommittedMicros = this.spentMicros + this.activeReservedMicros + deltaMicros;
+            if (projectedCommittedMicros > perRunMicros) {
+                const remainingMicros = perRunMicros - (this.spentMicros + this.activeReservedMicros);
+                await writeEvent({
+                    event: 'task.budget_halt',
+                    task_id: taskId,
+                    budget_remaining_usd: microsToUsd(remainingMicros),
+                    preflight_estimate_usd: microsToUsd(deltaMicros),
+                });
+                throw new BudgetExceededError(`task.${taskId}: increase reservation by $${microsToUsd(deltaMicros).toFixed(2)} would commit $${microsToUsd(projectedCommittedMicros).toFixed(2)} vs perRunUSD cap of $${opts.caps.perRunUSD.toFixed(2)} (spent=$${microsToUsd(this.spentMicros).toFixed(2)}, active=$${microsToUsd(this.activeReservedMicros).toFixed(2)})`, {
+                    task_id: taskId,
+                    priorReservedUsd: prior.reserved_usd,
+                    newReservedUsd: opts.newReservedUsd,
+                    delta: microsToUsd(deltaMicros),
+                    perRunUSD: opts.caps.perRunUSD,
+                    spentTotalUsd: microsToUsd(this.spentMicros),
+                    activeReservedTotalUsd: microsToUsd(this.activeReservedMicros),
+                    projectedCommittedUsd: microsToUsd(projectedCommittedMicros),
+                    violation: 'per_run_cap_at_increase',
+                });
+            }
+            // Bump approved. Append event + update cache.
+            await writeEvent({
+                event: 'task.budget_increased_reservation',
+                task_id: taskId,
+                prior_reserved_usd: prior.reserved_usd,
+                new_reserved_usd: opts.newReservedUsd,
+                reason: opts.reason,
+            });
+            prior.reserved_usd = opts.newReservedUsd;
+            this.activeReservedMicros += deltaMicros;
+        });
+    }
+    /**
+     * 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.
+     */
+    async release(taskId, opts) {
+        // Input validation (Codex pass 2 CRITICAL #2). Also catches NaN
+        // which would otherwise propagate through micros into spentTotal.
+        assertNonNegativeFiniteUsd(`task.${taskId}: actualCostUsd`, opts.actualCostUsd);
+        const actualMicros = usdToMicros(opts.actualCostUsd);
+        await this.writer.withExclusive(async ({ writeEvent, eventsNdjsonPath }) => {
+            const disk = BudgetReservation.replayFromEventsMicros(eventsNdjsonPath);
+            this.applyReplayMicros(disk);
+            // NOTE: release() is INTENTIONALLY allowed after task.budget_halt.
+            // Codex pass 3 CRITICAL #2: if increaseReservation triggered the
+            // halt, the task still has an active reservation that must be
+            // finalized (or it permanently strands activeReservedMicros for
+            // the run). The terminal-halt guard applies only to operations
+            // that would create NEW state for the task (reserve,
+            // increaseReservation). release records actual spend and clears
+            // the active reservation — it is the legitimate finalizer.
+            const prior = this.reservations.get(taskId);
+            if (!prior) {
+                throw new GuardrailError(`task.${taskId}: cannot release; no reservation found`, {
+                    code: 'adapter_bug',
+                    provider: 'concurrent-dispatch',
+                    details: { task_id: taskId },
+                });
+            }
+            if (prior.released) {
+                throw new GuardrailError(`task.${taskId}: reservation already released`, {
+                    code: 'adapter_bug',
+                    provider: 'concurrent-dispatch',
+                    details: { task_id: taskId },
+                });
+            }
+            const priorReservedMicros = usdToMicros(prior.reserved_usd);
+            const deltaMicros = priorReservedMicros - actualMicros;
+            await writeEvent({
+                event: 'task.budget_released',
+                task_id: taskId,
+                actual_cost_usd: opts.actualCostUsd,
+                delta_vs_reservation_usd: microsToUsd(deltaMicros),
+            });
+            prior.released = true;
+            prior.actual_cost_usd = opts.actualCostUsd;
+            // Move commitment from "active reserved" to "spent". Net effect on
+            // committedTotal: prior.reserved_usd was reserved, now actualCost
+            // is spent — committedTotal changes by (actualCost - reserved_usd).
+            // If actualCost < reserved: committed goes DOWN (we free unused
+            // reservation). If actualCost == reserved: no change. If actualCost
+            // > reserved: committed goes UP (the overspend is recorded).
+            this.activeReservedMicros -= priorReservedMicros;
+            this.spentMicros += actualMicros;
+        });
+    }
+    /** 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. */
+    applyReplayMicros(replay) {
+        this.reservations = replay.perTask;
+        this.spentMicros = replay.spentMicros;
+        this.activeReservedMicros = replay.activeReservedMicros;
+    }
+    // -------------------------------------------------------------------------
+    // Replay — pure, no IO beyond reading the events file. Static so resume
+    // and tests can call it without instantiating a writer.
+    // -------------------------------------------------------------------------
+    /**
+     * 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) {
+        const micros = BudgetReservation.replayFromEventsMicros(eventsNdjsonPath);
+        return {
+            spentTotal: microsToUsd(micros.spentMicros),
+            activeReservedTotal: microsToUsd(micros.activeReservedMicros),
+            committedTotal: microsToUsd(micros.spentMicros + micros.activeReservedMicros),
+            perTask: micros.perTask,
+        };
+    }
+    /**
+     * Internal: micro-precision replay. Used by every mutating method INSIDE
+     * `withExclusive` so cap checks operate on integer arithmetic.
+     */
+    static replayFromEventsMicros(eventsNdjsonPath) {
+        const perTask = new Map();
+        const haltedTaskIds = new Set();
+        let spentMicros = 0;
+        let activeReservedMicros = 0;
+        if (!fs.existsSync(eventsNdjsonPath)) {
+            return { spentMicros, activeReservedMicros, perTask, haltedTaskIds };
+        }
+        const raw = fs.readFileSync(eventsNdjsonPath, 'utf8');
+        if (!raw) {
+            return { spentMicros, activeReservedMicros, perTask, haltedTaskIds };
+        }
+        const lines = raw.split('\n');
+        // Always skip the final element of `split('\n')`:
+        //   - File ending in '\n' → trailing '' is dropped (no JSON to parse).
+        //   - Truncated tail (no '\n') → the last partial line is untrusted
+        //     and dropped because we can't guarantee it's a complete JSON
+        //     object. The next appendEvent will emit `run.recovery`.
+        // Both branches resolve to `lines.length - 2`, hence the bare
+        // expression (no conditional). Bugbot flagged the prior ternary as
+        // dead code — correct call.
+        const lastIdx = lines.length - 2;
+        for (let i = 0; i <= lastIdx; i++) {
+            const line = lines[i];
+            if (!line)
+                continue;
+            let ev;
+            try {
+                ev = JSON.parse(line);
+            }
+            catch {
+                // Mid-file corruption — stop the walk. The events file is the
+                // source of truth; this fold is best-effort and conservative
+                // (we keep state up to the last valid line).
+                break;
+            }
+            if (!ev || typeof ev !== 'object' || typeof ev.event !== 'string')
+                continue;
+            switch (ev.event) {
+                case 'task.budget_reserved': {
+                    // Codex pass 3 CRITICAL #1: halt is terminal — reserving a
+                    // halted task_id post-halt is a corruption signal.
+                    if (haltedTaskIds.has(ev.task_id)) {
+                        throw new GuardrailError(`replay: task.${ev.task_id} has task.budget_reserved AFTER task.budget_halt (corrupt ledger)`, {
+                            code: 'adapter_bug',
+                            provider: 'concurrent-dispatch',
+                            details: {
+                                task_id: ev.task_id,
+                                event: 'task.budget_reserved',
+                                terminal_state: 'budget_halt',
+                            },
+                        });
+                    }
+                    // Bugbot pass 3: duplicate task.budget_reserved for the same
+                    // task_id would silently inflate activeReservedMicros (the
+                    // runtime guard in reserve() prevents this from happening on
+                    // happy paths — only corrupt logs can produce it). Fail closed.
+                    if (perTask.has(ev.task_id)) {
+                        throw new GuardrailError(`replay: task.${ev.task_id} has duplicate task.budget_reserved (corrupt ledger)`, {
+                            code: 'adapter_bug',
+                            provider: 'concurrent-dispatch',
+                            details: { task_id: ev.task_id, event: 'task.budget_reserved' },
+                        });
+                    }
+                    const entry = {
+                        task_id: ev.task_id,
+                        reserved_usd: ev.reserved_usd,
+                        released: false,
+                    };
+                    perTask.set(ev.task_id, entry);
+                    activeReservedMicros += usdToMicros(ev.reserved_usd);
+                    break;
+                }
+                case 'task.budget_increased_reservation': {
+                    if (haltedTaskIds.has(ev.task_id)) {
+                        throw new GuardrailError(`replay: task.${ev.task_id} has task.budget_increased_reservation AFTER task.budget_halt (corrupt ledger)`, {
+                            code: 'adapter_bug',
+                            provider: 'concurrent-dispatch',
+                            details: {
+                                task_id: ev.task_id,
+                                event: 'task.budget_increased_reservation',
+                                terminal_state: 'budget_halt',
+                            },
+                        });
+                    }
+                    const entry = perTask.get(ev.task_id);
+                    if (!entry) {
+                        // Log gap — the reserved event is missing. Treat the
+                        // increase's new value as the baseline so cache reflects
+                        // disk; resume will surface this elsewhere.
+                        perTask.set(ev.task_id, {
+                            task_id: ev.task_id,
+                            reserved_usd: ev.new_reserved_usd,
+                            released: false,
+                        });
+                        activeReservedMicros += usdToMicros(ev.new_reserved_usd);
+                        break;
+                    }
+                    // `new_reserved_usd` is the ABSOLUTE new reservation, so we
+                    // adjust the running total by the delta from prior, not by
+                    // adding the new value. (Codex pass 1 flagged the prior
+                    // comment as ambiguous; the implementation here is the
+                    // intended semantics.)
+                    const priorMicros = usdToMicros(entry.reserved_usd);
+                    const newMicros = usdToMicros(ev.new_reserved_usd);
+                    entry.reserved_usd = ev.new_reserved_usd;
+                    activeReservedMicros += newMicros - priorMicros;
+                    break;
+                }
+                case 'task.budget_released': {
+                    const entry = perTask.get(ev.task_id);
+                    if (!entry) {
+                        // Released without reservation — record the phantom entry
+                        // so resume can detect it. We DO count the actual cost
+                        // against `spentMicros` because the money was spent; the
+                        // missing reservation is a separate corruption signal.
+                        perTask.set(ev.task_id, {
+                            task_id: ev.task_id,
+                            reserved_usd: 0,
+                            released: true,
+                            actual_cost_usd: ev.actual_cost_usd,
+                        });
+                        spentMicros += usdToMicros(ev.actual_cost_usd);
+                        break;
+                    }
+                    // Bugbot pass 3: duplicate task.budget_released would
+                    // double-subtract from activeReservedMicros and double-add to
+                    // spentMicros. Fail closed — runtime release() rejects on
+                    // `prior.released` so corrupt logs are the only path.
+                    if (entry.released) {
+                        throw new GuardrailError(`replay: task.${ev.task_id} has duplicate task.budget_released (corrupt ledger)`, {
+                            code: 'adapter_bug',
+                            provider: 'concurrent-dispatch',
+                            details: { task_id: ev.task_id, event: 'task.budget_released' },
+                        });
+                    }
+                    entry.released = true;
+                    entry.actual_cost_usd = ev.actual_cost_usd;
+                    // Move commitment from "active reserved" to "spent".
+                    activeReservedMicros -= usdToMicros(entry.reserved_usd);
+                    spentMicros += usdToMicros(ev.actual_cost_usd);
+                    break;
+                }
+                case 'task.budget_halt': {
+                    // Halt is a terminal record for the task. Track so later
+                    // mutating calls can refuse (Codex pass 2 CRITICAL #1). Note
+                    // that halt does NOT free or change accounting totals — the
+                    // task that triggered the halt may not have ever reserved
+                    // (over-cap reserve writes halt without reserving).
+                    haltedTaskIds.add(ev.task_id);
+                    break;
+                }
+                default:
+                    // Other event types don't affect budget ledger state.
+                    break;
+            }
+        }
+        return { spentMicros, activeReservedMicros, perTask, haltedTaskIds };
+    }
+}
+//# sourceMappingURL=budget-reservation.js.map