@phnx-labs/agents-cli 1.20.17 → 1.20.18

package/dist/lib/budget/enforce.js

@@ -0,0 +1,151 @@
+import { actualCost } from '../pricing/index.js';
+/** Convert a resolved BudgetConfig + prior ledger spend into the caps the watcher needs. */
+export function capsFromConfig(cfg, prior) {
+    return {
+        perRun: cfg.per_run,
+        perDay: cfg.per_day,
+        perProject: cfg.per_project,
+        perAgent: cfg.per_agent,
+        priorDaySpend: prior?.daySpend ?? 0,
+        priorProjectSpend: prior?.projectSpend ?? 0,
+        priorAgentDaySpend: prior?.agentDaySpend ?? {},
+    };
+}
+/**
+ * Create a live spend watcher. `onBreach` fires at most once, on the first
+ * event that pushes any active cap from at-or-under to over. After it fires the
+ * watcher keeps accumulating (so `runSpend()` stays accurate for the final
+ * ledger record) but never calls `onBreach` again.
+ */
+export function makeLiveSpendWatcher(args) {
+    const { caps, onBreach } = args;
+    let run = 0;
+    // Cross-vendor accumulators, seeded with pre-run ledger spend.
+    let day = caps.priorDaySpend ?? 0;
+    let project = caps.priorProjectSpend ?? 0;
+    const agentDay = {};
+    for (const [k, v] of Object.entries(caps.priorAgentDaySpend ?? {})) {
+        if (typeof v === 'number')
+            agentDay[k] = v;
+    }
+    let didBreach = false;
+    let disposed = false;
+    function checkBreach(agent) {
+        if (caps.perRun !== undefined && run > caps.perRun) {
+            return { cap: 'per_run', limit: caps.perRun, spend: run, runSpend: run };
+        }
+        if (caps.perDay !== undefined && day > caps.perDay) {
+            return { cap: 'per_day', limit: caps.perDay, spend: day, runSpend: run };
+        }
+        if (caps.perProject !== undefined && project > caps.perProject) {
+            return { cap: 'per_project', limit: caps.perProject, spend: project, runSpend: run };
+        }
+        if (agent && caps.perAgent && caps.perAgent[agent] !== undefined) {
+            const limit = caps.perAgent[agent];
+            if ((agentDay[agent] ?? 0) > limit) {
+                return { cap: 'per_agent', limit, spend: agentDay[agent], agent, runSpend: run };
+            }
+        }
+        return null;
+    }
+    return {
+        feedUsage(event) {
+            if (disposed)
+                return;
+            const { usd } = actualCost(event.model ?? '', {
+                inputTokens: event.inputTokens ?? 0,
+                outputTokens: event.outputTokens ?? 0,
+                cacheReadTokens: event.cacheReadTokens,
+                cacheCreationTokens: event.cacheCreationTokens,
+            });
+            if (usd <= 0)
+                return;
+            const agent = event.agent ? String(event.agent) : undefined;
+            run += usd;
+            day += usd;
+            project += usd;
+            if (agent)
+                agentDay[agent] = (agentDay[agent] ?? 0) + usd;
+            if (didBreach)
+                return;
+            const breach = checkBreach(agent);
+            if (breach) {
+                didBreach = true;
+                onBreach(breach);
+            }
+        },
+        runSpend: () => run,
+        breached: () => didBreach,
+        dispose() {
+            disposed = true;
+        },
+    };
+}
+/**
+ * Incrementally extract usage events from a stream-json chunk. Buffers a partial
+ * trailing line across calls (returned in `rest`), parses each complete line,
+ * and yields one UsageEvent per line that carries token counts. Provider shapes
+ * handled: Claude/`--json` assistant turns (`message.usage` with
+ * `input_tokens`/`output_tokens`/`cache_*_input_tokens`) and the flatter
+ * `usage.record` shape (`usage.input_tokens`/`output`). Lines that aren't JSON
+ * or carry no usage are skipped — this never throws on agent output.
+ */
+export function extractUsageEvents(chunk, pending, fallbackModel, fallbackAgent) {
+    const combined = pending + chunk;
+    const lines = combined.split('\n');
+    const rest = lines.pop() ?? '';
+    const events = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed[0] !== '{')
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const ev = usageFromObject(obj, fallbackModel, fallbackAgent);
+        if (ev)
+            events.push(ev);
+    }
+    return { events, rest };
+}
+function usageFromObject(obj, fallbackModel, fallbackAgent) {
+    // Claude emits a final `type:"result"` event carrying a TOP-LEVEL cumulative
+    // `usage` that already sums every per-turn `message.usage`. Counting both the
+    // per-turn turns AND this cumulative total double-counts a multi-turn run
+    // (~2x). The canonical session parser (src/lib/session/parse.ts) reads usage
+    // ONLY from `message.usage` and extracts nothing from the result line — mirror
+    // that here: skip result lines entirely for usage.
+    if (obj?.type === 'result')
+        return null;
+    // Claude stream-json assistant turn.
+    const mu = obj?.message?.usage;
+    if (mu && (typeof mu.input_tokens === 'number' || typeof mu.output_tokens === 'number')) {
+        return {
+            agent: fallbackAgent,
+            model: obj.message.model ?? fallbackModel,
+            inputTokens: mu.input_tokens ?? 0,
+            outputTokens: mu.output_tokens ?? 0,
+            cacheReadTokens: mu.cache_read_input_tokens,
+            cacheCreationTokens: mu.cache_creation_input_tokens,
+        };
+    }
+    // Flatter usage.record / usage shape (Codex / `usage.record`). The result-line
+    // guard above already excludes Claude's cumulative result usage, so this only
+    // matches genuine per-event usage records.
+    const u = obj?.usage;
+    if (u && (typeof u.input_tokens === 'number' || typeof u.output === 'number' || typeof u.output_tokens === 'number')) {
+        return {
+            agent: fallbackAgent,
+            model: obj.model ?? u.model ?? fallbackModel,
+            inputTokens: u.input_tokens ?? u.inputOther ?? 0,
+            outputTokens: u.output_tokens ?? u.output ?? 0,
+            cacheReadTokens: u.cache_read_input_tokens,
+            cacheCreationTokens: u.cache_creation_input_tokens,
+        };
+    }
+    return null;
+}

package/dist/lib/budget/ledger.d.ts

@@ -0,0 +1,61 @@
+/** A single spend observation. Append-only; never mutated in place. */
+export interface SpendEntry {
+    /** Run identifier — groups multiple usage observations from one dispatch. */
+    runId: string;
+    /** Agent id (claude, codex, ...). The cross-vendor attribution key. */
+    agent: string;
+    /** Project key (absolute path or repo slug). Empty string when unknown. */
+    project: string;
+    /** Local calendar day, YYYY-MM-DD. */
+    day: string;
+    /** Model id as reported by the stream (may carry vendor prefix / date suffix). */
+    model: string;
+    inputTok: number;
+    outputTok: number;
+    /** Combined cache read + creation tokens (kept as one field for the ledger). */
+    cacheTok: number;
+    /** USD cost of THIS observation, via actualCost() at write time. */
+    costUsd: number;
+    /** Where the spend came from: local run, teams teammate, or cloud dispatch. */
+    source: 'run' | 'teams' | 'cloud';
+    /** ISO timestamp of the observation. */
+    ts: string;
+}
+/** Token bundle for a single observation (matches session/parse usage fields). */
+export interface UsageObservation {
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+/** Default ledger path: <history>/spend/ledger.jsonl. */
+export declare function defaultLedgerPath(): string;
+/** Local YYYY-MM-DD for a Date (defaults to now). Local, not UTC — caps are a human-day notion. */
+export declare function localDay(d?: Date): string;
+/**
+ * Append one spend observation. Computes `costUsd` from the usage via the
+ * canonical pricing module (unpriced models contribute $0). Returns the written
+ * entry. Creates the spend dir on first write.
+ */
+export declare function recordSpend(input: {
+    runId: string;
+    agent: string;
+    project?: string;
+    model: string;
+    usage: UsageObservation;
+    source: SpendEntry['source'];
+    ts?: Date;
+}, ledgerPath?: string): SpendEntry;
+/** Load every entry. Skips malformed lines (a half-written final line never breaks a rollup). */
+export declare function loadLedger(ledgerPath?: string): SpendEntry[];
+/** Total USD spend on a given local day across ALL agents (cross-vendor). */
+export declare function spendForDay(day: string, ledger?: SpendEntry[]): number;
+/** Total USD spend on a given day for ONE agent (per-agent cap accounting). */
+export declare function spendForAgentDay(agent: string, day: string, ledger?: SpendEntry[]): number;
+/** Total USD spend attributed to an agent across all time. */
+export declare function spendForAgent(agent: string, ledger?: SpendEntry[]): number;
+/** Total USD spend attributed to a project across all time (cross-vendor). */
+export declare function spendForProject(project: string, ledger?: SpendEntry[]): number;
+/** Total USD spend for a single run id (all of its usage observations). */
+export declare function spendForRun(runId: string, ledger?: SpendEntry[]): number;

package/dist/lib/budget/ledger.js

@@ -0,0 +1,107 @@
+/**
+ * Append-only spend ledger (issue #346).
+ *
+ * Every dispatched run that produces token usage records one JSONL line under
+ * `<history>/spend/ledger.jsonl`. The ledger is the shared artifact #323's
+ * `agents cost` can later read for $ rollups, so the entry shape stays clean
+ * and stable: one record = one usage observation attributed to a run.
+ *
+ * `costUsd` is computed at write time via the canonical pricing module
+ * (lib/pricing) so the ledger is self-contained — a reader never needs the
+ * pricing table to sum spend. Rollups (`spendForDay`/`spendForAgent`/...) are
+ * pure folds over the file; for the modest line counts a developer accrues this
+ * is plenty fast, and there's no index to corrupt.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHistoryDir } from '../state.js';
+import { actualCost } from '../pricing/index.js';
+/** Default ledger path: <history>/spend/ledger.jsonl. */
+export function defaultLedgerPath() {
+    return path.join(getHistoryDir(), 'spend', 'ledger.jsonl');
+}
+/** Local YYYY-MM-DD for a Date (defaults to now). Local, not UTC — caps are a human-day notion. */
+export function localDay(d = new Date()) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+/**
+ * Append one spend observation. Computes `costUsd` from the usage via the
+ * canonical pricing module (unpriced models contribute $0). Returns the written
+ * entry. Creates the spend dir on first write.
+ */
+export function recordSpend(input, ledgerPath = defaultLedgerPath()) {
+    const ts = input.ts ?? new Date();
+    const cacheTok = (input.usage.cacheReadTokens ?? 0) + (input.usage.cacheCreationTokens ?? 0);
+    const { usd } = actualCost(input.model, {
+        inputTokens: input.usage.inputTokens ?? 0,
+        outputTokens: input.usage.outputTokens ?? 0,
+        cacheReadTokens: input.usage.cacheReadTokens,
+        cacheCreationTokens: input.usage.cacheCreationTokens,
+    });
+    const entry = {
+        runId: input.runId,
+        agent: input.agent,
+        project: input.project ?? '',
+        day: localDay(ts),
+        model: input.model,
+        inputTok: input.usage.inputTokens ?? 0,
+        outputTok: input.usage.outputTokens ?? 0,
+        cacheTok,
+        costUsd: usd,
+        source: input.source,
+        ts: ts.toISOString(),
+    };
+    fs.mkdirSync(path.dirname(ledgerPath), { recursive: true });
+    fs.appendFileSync(ledgerPath, JSON.stringify(entry) + '\n');
+    return entry;
+}
+/** Load every entry. Skips malformed lines (a half-written final line never breaks a rollup). */
+export function loadLedger(ledgerPath = defaultLedgerPath()) {
+    if (!fs.existsSync(ledgerPath))
+        return [];
+    const out = [];
+    for (const line of fs.readFileSync(ledgerPath, 'utf-8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.costUsd === 'number')
+                out.push(parsed);
+        }
+        catch {
+            // Tolerate a torn final line; everything before it is intact.
+        }
+    }
+    return out;
+}
+function sum(entries, pred) {
+    let total = 0;
+    for (const e of entries)
+        if (pred(e))
+            total += e.costUsd;
+    return total;
+}
+/** Total USD spend on a given local day across ALL agents (cross-vendor). */
+export function spendForDay(day, ledger = loadLedger()) {
+    return sum(ledger, (e) => e.day === day);
+}
+/** Total USD spend on a given day for ONE agent (per-agent cap accounting). */
+export function spendForAgentDay(agent, day, ledger = loadLedger()) {
+    return sum(ledger, (e) => e.agent === agent && e.day === day);
+}
+/** Total USD spend attributed to an agent across all time. */
+export function spendForAgent(agent, ledger = loadLedger()) {
+    return sum(ledger, (e) => e.agent === agent);
+}
+/** Total USD spend attributed to a project across all time (cross-vendor). */
+export function spendForProject(project, ledger = loadLedger()) {
+    return sum(ledger, (e) => e.project === project);
+}
+/** Total USD spend for a single run id (all of its usage observations). */
+export function spendForRun(runId, ledger = loadLedger()) {
+    return sum(ledger, (e) => e.runId === runId);
+}

package/dist/lib/budget/preflight.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Pre-flight cost estimate + gate (issue #346).
+ *
+ * Before a run spawns we estimate its cost and decide whether to allow it. The
+ * estimate's token basis comes from recent ledger averages for the same agent
+ * (the most accurate signal we have), falling back to a prompt-character
+ * heuristic when there's no history. Cost is computed via the canonical pricing
+ * module — never reimplemented here.
+ *
+ * `enforcePreflight` is the decision: with `on_exceed: block`, if launching
+ * this run would push any cap (per_run / per_day / per_agent / per_project)
+ * over the line, it denies. With `on_exceed: warn` it always allows but reports
+ * the projected overrun.
+ */
+import type { BudgetConfig } from '../types.js';
+import type { SpendEntry } from './ledger.js';
+/** A pre-flight cost estimate for one run. */
+export interface RunEstimate {
+    /** Estimated USD for this run. 0 when the model is unpriced. */
+    estUsd: number;
+    /** How the token count was derived. */
+    basis: 'ledger-average' | 'prompt-heuristic' | 'none';
+    /** True when the model resolved to a priced entry. */
+    priced: boolean;
+    estInputTokens: number;
+    estOutputTokens: number;
+}
+/**
+ * Estimate the cost of a run. When the ledger has prior runs for this agent we
+ * use their average input/output tokens; otherwise we fall back to a
+ * prompt-character heuristic. `recentAvgTokens` lets callers inject a
+ * precomputed average (e.g. from a scoped ledger) for testability.
+ */
+export declare function estimateRunCost(args: {
+    agent: string;
+    model: string;
+    mode?: string;
+    promptChars?: number;
+    recentAvgTokens?: {
+        input: number;
+        output: number;
+    };
+    ledger?: SpendEntry[];
+}): RunEstimate;
+/** Average input/output tokens per RUN for an agent, from the ledger. Null when no history. */
+export declare function ledgerAverageTokens(agent: string, ledger: SpendEntry[]): {
+    input: number;
+    output: number;
+} | null;
+/** Decision returned by the pre-flight gate. */
+export interface PreflightDecision {
+    /** Whether the run may proceed. */
+    allow: boolean;
+    /** Whether the caller must interactively confirm (estimate >= require_confirm_over). */
+    needsConfirm: boolean;
+    /** Human reason when blocked or confirming. */
+    reason?: string;
+    /** Which cap blocked, if any. */
+    blockedCap?: 'per_run' | 'per_day' | 'per_agent' | 'per_project';
+    /** Projected day spend if this run lands at its estimate. */
+    projectedDaySpend: number;
+    /** Projected project spend if this run lands at its estimate. */
+    projectedProjectSpend: number;
+}
+/** Current spend snapshot the gate compares the estimate against. */
+export interface LedgerState {
+    /** Agent this snapshot is for (used to pick the matching per_agent cap). */
+    agent: string;
+    daySpend: number;
+    projectSpend: number;
+    agentDaySpend: number;
+}
+/** Read the ledger snapshot the gate needs for `agent` / `project` / today. */
+export declare function ledgerStateFor(agent: string, project: string, ledger?: SpendEntry[]): LedgerState;
+/**
+ * The pre-flight gate. Projects this run's estimate on top of current spend and
+ * decides allow/deny. `on_exceed: warn` never blocks (allow:true) but still
+ * reports the projected overrun via `reason`. A hard block sets allow:false —
+ * `--yes` MUST NOT override it (the caller enforces that; this function only
+ * reports the truth).
+ */
+export declare function enforcePreflight(cfg: BudgetConfig, state: LedgerState, est: RunEstimate): PreflightDecision;
+/** Build a one-line human estimate banner for `agents run` preamble. */
+export declare function formatEstimateBanner(agent: string, model: string, est: RunEstimate): string;
+/** Result of the high-level run gate consumed by `agents run` / teams / cloud. */
+export interface PreflightGateResult {
+    /** True when no caps are configured — budget feature dormant, nothing to do. */
+    dormant: boolean;
+    cfg: BudgetConfig;
+    estimate: RunEstimate;
+    decision: PreflightDecision;
+    banner: string;
+}
+/**
+ * High-level pre-flight gate: resolve the effective budget for `cwd`, estimate
+ * the run, and evaluate every cap. Returns `dormant:true` (and skips all work)
+ * when no caps are set, so the gate is zero-cost for users who never configure
+ * a budget. The CLI layer decides how to act on `decision` (print banner,
+ * confirm, or block + exit non-zero).
+ */
+export declare function runPreflightGate(args: {
+    agent: string;
+    model: string;
+    mode?: string;
+    prompt?: string;
+    project: string;
+    cwd?: string;
+    ledger?: SpendEntry[];
+}): PreflightGateResult;
+export type { SpendEntry };

package/dist/lib/budget/preflight.js

@@ -0,0 +1,200 @@
+import { estimateCost, formatUsd } from '../pricing/index.js';
+import { loadLedger, spendForDay, spendForAgentDay, spendForProject, localDay } from './ledger.js';
+import { resolveBudgetConfig, hasAnyCap } from './config.js';
+/** Roughly 4 characters per token — the standard coarse heuristic for English text. */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Output is typically a multiple of the visible prompt for an agentic run
+ * (tool calls, file reads, reasoning). 6x is a deliberately conservative
+ * lower bound so the estimate doesn't wildly under-report and wave through a
+ * run that then blows the cap on its first turn.
+ */
+const HEURISTIC_OUTPUT_MULTIPLIER = 6;
+/**
+ * Estimate the cost of a run. When the ledger has prior runs for this agent we
+ * use their average input/output tokens; otherwise we fall back to a
+ * prompt-character heuristic. `recentAvgTokens` lets callers inject a
+ * precomputed average (e.g. from a scoped ledger) for testability.
+ */
+export function estimateRunCost(args) {
+    const ledger = args.ledger ?? loadLedger();
+    let estInputTokens = 0;
+    let estOutputTokens = 0;
+    let basis = 'none';
+    const avg = args.recentAvgTokens ?? ledgerAverageTokens(args.agent, ledger);
+    if (avg && (avg.input > 0 || avg.output > 0)) {
+        estInputTokens = avg.input;
+        estOutputTokens = avg.output;
+        basis = 'ledger-average';
+    }
+    else if (args.promptChars && args.promptChars > 0) {
+        estInputTokens = Math.ceil(args.promptChars / CHARS_PER_TOKEN);
+        estOutputTokens = estInputTokens * HEURISTIC_OUTPUT_MULTIPLIER;
+        basis = 'prompt-heuristic';
+    }
+    const { usd, modelMatched } = estimateCost(args.model, {
+        inputTokens: estInputTokens,
+        outputTokens: estOutputTokens,
+    });
+    return {
+        estUsd: usd,
+        basis: estInputTokens === 0 && estOutputTokens === 0 ? 'none' : basis,
+        priced: modelMatched !== null,
+        estInputTokens,
+        estOutputTokens,
+    };
+}
+/** Average input/output tokens per RUN for an agent, from the ledger. Null when no history. */
+export function ledgerAverageTokens(agent, ledger) {
+    const runs = new Map();
+    for (const e of ledger) {
+        if (e.agent !== agent)
+            continue;
+        const acc = runs.get(e.runId) ?? { input: 0, output: 0 };
+        acc.input += e.inputTok;
+        acc.output += e.outputTok;
+        runs.set(e.runId, acc);
+    }
+    if (runs.size === 0)
+        return null;
+    let input = 0;
+    let output = 0;
+    for (const r of runs.values()) {
+        input += r.input;
+        output += r.output;
+    }
+    return { input: Math.round(input / runs.size), output: Math.round(output / runs.size) };
+}
+/** Read the ledger snapshot the gate needs for `agent` / `project` / today. */
+export function ledgerStateFor(agent, project, ledger) {
+    const entries = ledger ?? loadLedger();
+    const today = localDay();
+    return {
+        agent,
+        daySpend: spendForDay(today, entries),
+        projectSpend: spendForProject(project, entries),
+        agentDaySpend: spendForAgentDay(agent, today, entries),
+    };
+}
+/**
+ * The pre-flight gate. Projects this run's estimate on top of current spend and
+ * decides allow/deny. `on_exceed: warn` never blocks (allow:true) but still
+ * reports the projected overrun via `reason`. A hard block sets allow:false —
+ * `--yes` MUST NOT override it (the caller enforces that; this function only
+ * reports the truth).
+ */
+export function enforcePreflight(cfg, state, est) {
+    const projectedDaySpend = state.daySpend + est.estUsd;
+    const projectedProjectSpend = state.projectSpend + est.estUsd;
+    const projectedAgentDaySpend = state.agentDaySpend + est.estUsd;
+    const warnOnly = cfg.on_exceed === 'warn';
+    const breaches = [];
+    if (cfg.per_run !== undefined && est.estUsd > cfg.per_run) {
+        breaches.push({
+            cap: 'per_run',
+            reason: `estimated ${formatUsd(est.estUsd)} exceeds per_run cap ${formatUsd(cfg.per_run)}`,
+        });
+    }
+    if (cfg.per_day !== undefined && projectedDaySpend > cfg.per_day) {
+        breaches.push({
+            cap: 'per_day',
+            reason: `projected day spend ${formatUsd(projectedDaySpend)} exceeds per_day cap ${formatUsd(cfg.per_day)}`,
+        });
+    }
+    if (cfg.per_project !== undefined && projectedProjectSpend > cfg.per_project) {
+        breaches.push({
+            cap: 'per_project',
+            reason: `projected project spend ${formatUsd(projectedProjectSpend)} exceeds per_project cap ${formatUsd(cfg.per_project)}`,
+        });
+    }
+    const agentCap = cfg.per_agent?.[state.agent];
+    if (agentCap !== undefined && projectedAgentDaySpend > agentCap) {
+        breaches.push({
+            cap: 'per_agent',
+            reason: `projected agent day spend ${formatUsd(projectedAgentDaySpend)} exceeds per_agent cap ${formatUsd(agentCap)}`,
+        });
+    }
+    // require_confirm_over only governs interactive confirm, not a hard block.
+    let needsConfirm = cfg.require_confirm_over !== undefined && est.estUsd >= cfg.require_confirm_over;
+    // Unpriced model + active caps: the estimate is $0 because we have no price
+    // for this model, so NONE of the per_run/per_day caps above can ever trip and
+    // we'd silently wave the run through. Never $0-wave-through (#346): when caps
+    // are set but the model is unpriced, require confirmation so the user is told
+    // the cap cannot be enforced for this model rather than getting a false pass.
+    if (!est.priced && hasAnyCap(cfg) && breaches.length === 0) {
+        needsConfirm = true;
+        return {
+            allow: true,
+            needsConfirm: true,
+            reason: `model is unpriced — budget caps cannot be enforced for this run (estimate is $0); confirm to proceed`,
+            projectedDaySpend,
+            projectedProjectSpend,
+        };
+    }
+    if (breaches.length > 0) {
+        const first = breaches[0];
+        return {
+            allow: warnOnly,
+            needsConfirm: warnOnly ? needsConfirm : false,
+            reason: first.reason,
+            blockedCap: first.cap,
+            projectedDaySpend,
+            projectedProjectSpend,
+        };
+    }
+    return {
+        allow: true,
+        needsConfirm,
+        reason: needsConfirm
+            ? `estimated ${formatUsd(est.estUsd)} is at or above confirm threshold ${formatUsd(cfg.require_confirm_over)}`
+            : undefined,
+        projectedDaySpend,
+        projectedProjectSpend,
+    };
+}
+/** Build a one-line human estimate banner for `agents run` preamble. */
+export function formatEstimateBanner(agent, model, est) {
+    const cost = est.priced ? formatUsd(est.estUsd) : 'unpriced';
+    const basisLabel = est.basis === 'ledger-average'
+        ? 'recent average'
+        : est.basis === 'prompt-heuristic'
+            ? 'prompt size'
+            : 'no basis';
+    return `[budget] est. ${cost} for this ${agent} run (${model}, ${basisLabel})`;
+}
+/**
+ * High-level pre-flight gate: resolve the effective budget for `cwd`, estimate
+ * the run, and evaluate every cap. Returns `dormant:true` (and skips all work)
+ * when no caps are set, so the gate is zero-cost for users who never configure
+ * a budget. The CLI layer decides how to act on `decision` (print banner,
+ * confirm, or block + exit non-zero).
+ */
+export function runPreflightGate(args) {
+    const cfg = resolveBudgetConfig(args.cwd);
+    const ledger = args.ledger ?? loadLedger();
+    const estimate = estimateRunCost({
+        agent: args.agent,
+        model: args.model,
+        mode: args.mode,
+        promptChars: args.prompt?.length,
+        ledger,
+    });
+    const banner = formatEstimateBanner(args.agent, args.model, estimate);
+    if (!hasAnyCap(cfg)) {
+        return {
+            dormant: true,
+            cfg,
+            estimate,
+            decision: {
+                allow: true,
+                needsConfirm: false,
+                projectedDaySpend: 0,
+                projectedProjectSpend: 0,
+            },
+            banner,
+        };
+    }
+    const state = ledgerStateFor(args.agent, args.project, ledger);
+    const decision = enforcePreflight(cfg, state, estimate);
+    return { dormant: false, cfg, estimate, decision, banner };
+}

package/dist/lib/checkpoint.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Harness-level loop checkpoint (issue #332).
+ *
+ * A checkpoint is the durable harness state for a `--loop` run: it records the
+ * iteration count, the pinned session id, the prompt being re-injected, and the
+ * loop config — everything `--resume-checkpoint` needs to continue a run that a
+ * SIGTERM, timeout, or machine sleep killed mid-flight.
+ *
+ * This is NOT provider-side state. `--session-id` resumes Claude's *conversation*
+ * (server-side); a checkpoint resumes the *harness* (iteration count, loop
+ * variables, prompt chain) — the part Claude's own resume cannot recover.
+ *
+ * Atomic write (temp + rename) mirrors `writeRunMeta` in routines.ts so a crash
+ * mid-write never leaves a half-written checkpoint that `readCheckpoint` would
+ * choke on. `readCheckpoint` returns null on a missing or corrupt file (mirrors
+ * `readRunMeta`) — a corrupt checkpoint is a "start fresh", never a throw.
+ */
+import type { AgentId } from './types.js';
+import type { LoopConfig, LoopSignal } from './loop.js';
+/** Durable harness state for a looped run, serialized to checkpoint.json. */
+export interface Checkpoint {
+    /** runId == the run directory name under getRunsDir(). */
+    id: string;
+    agent: AgentId;
+    version?: string;
+    /** The prompt re-injected each iteration. */
+    prompt?: string;
+    /** Pinned Claude session id so a resume continues the same conversation. */
+    sessionId?: string;
+    /** Iterations COMPLETED so far. A resume starts at iteration + 1. */
+    iteration: number;
+    /** The loop config governing termination. */
+    loop: LoopConfig;
+    /** Last loop-signal read, if any (for audit / resume context). */
+    loopSignal?: LoopSignal;
+    /** Cumulative tokens consumed across all iterations so far. */
+    cumulativeTokens?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Path to a run's checkpoint file: <runsDir>/<runId>/checkpoint.json. */
+export declare function checkpointPath(runId: string): string;
+/**
+ * Write a checkpoint atomically (temp file + rename). The rename is atomic on a
+ * single filesystem, so a reader never observes a partially written file.
+ * Mirrors the durable-write contract of `writeRunMeta`.
+ */
+export declare function writeCheckpoint(c: Checkpoint, file?: string): void;
+/**
+ * Read a checkpoint from disk. Returns null if the file is missing or its
+ * contents are not valid JSON — corruption means "no resumable state", which
+ * the caller treats as a fresh start. Mirrors `readRunMeta`.
+ */
+export declare function readCheckpoint(file: string): Checkpoint | null;