@delegance/claude-autopilot 5.5.2 → 7.2.0

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

@@ -0,0 +1,29 @@
+export interface ValidateCommandOptions {
+    cwd?: string;
+    configPath?: string;
+    /**
+     * Optional context note injected into the validate log. The actual
+     * validation work (static checks, auto-fix, tests, Codex review,
+     * bugbot triage) is owned by the Claude Code `/validate` skill; this
+     * CLI verb is the engine-wrap shell so v6 pipeline runs can checkpoint
+     * a `validate` phase entry alongside `plan` / `review`.
+     */
+    context?: string;
+    /**
+     * Where to write the validate log file. Defaults to
+     * `.guardrail-cache/validate/<timestamp>-validate.md` so it lands inside
+     * the cache that's already gitignored. The path is recorded on
+     * ValidateOutput so the engine path can persist it as `result` for
+     * replay.
+     */
+    outputPath?: string;
+    /**
+     * v6.0.5 — engine knob inputs. Same shape and precedence as scan / costs /
+     * fix / plan / review (CLI > env > config > built-in default off in
+     * v6.0.x).
+     */
+    cliEngine?: boolean;
+    envEngine?: string;
+}
+export declare function runValidate(options?: ValidateCommandOptions): Promise<number>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/src/cli/validate.js

@@ -0,0 +1,131 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { loadConfig } from "../core/config/loader.js";
+import { runPhaseWithLifecycle } from "../core/run-state/run-phase-with-lifecycle.js";
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m', red: '\x1b[31m',
+};
+const fmt = (c, t) => `${C[c]}${t}${C.reset}`;
+export async function runValidate(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
+    let config = { configVersion: 1 };
+    if (fs.existsSync(configPath)) {
+        const loaded = await loadConfig(configPath);
+        if (loaded)
+            config = loaded;
+    }
+    // INTENTIONAL DEVIATION FROM THE SPEC TABLE (preserved in v6.0.6):
+    // the v6 spec (docs/specs/v6-run-state-engine.md, line 161) lists
+    // `validate` with `idempotent: yes, hasSideEffects: no,
+    // externalRefs: sarif-artifact`. This wrap declares
+    // `idempotent: true, hasSideEffects: false` (matches the spec) but
+    // does **not** plumb a `sarif-artifact` externalRef. The reasoning:
+    // the `validate` CLI verb is an engine-wrap shell pointing at the
+    // Claude Code `/validate` skill — it does not itself emit a SARIF
+    // artifact. SARIF emission lives in `claude-autopilot run --format
+    // sarif --output <path>` (a separate verb, see help-text.ts → `run`
+    // Options block). The `sarif-artifact` externalRef is local-only file
+    // output (no remote upload), so the engine doesn't need a readback
+    // rule for it on resume — `idempotent: true` covers replay safety. If
+    // a future PR adds SARIF emission directly to this verb (or moves the
+    // `--format sarif` flag here), the wrap can add an
+    // `ctx.emitExternalRef({ kind: 'sarif-artifact', id: '<path>',
+    // observedAt: ... })` call after the file write lands. Until then, no
+    // ledger entry is needed because there's nothing to read back from.
+    const context = options.context ?? null;
+    const outputPath = options.outputPath
+        ? path.resolve(cwd, options.outputPath)
+        : path.join(cwd, '.guardrail-cache', 'validate', `${new Date().toISOString().replace(/[:.]/g, '-')}-validate.md`);
+    const validateInput = { cwd, context, outputPath };
+    // The wrapped phase body — writes a validate log stub to disk. The actual
+    // validation work (static checks → auto-fix → tests → Codex review →
+    // bugbot triage) is produced by the Claude Code `/validate` skill.
+    // Engine-off callers invoke this directly via `executeValidatePhase()`;
+    // engine-on callers route through `runPhase()`.
+    const phase = {
+        name: 'validate',
+        // Re-running the validate verb against the same context writes the same
+        // log file. Engine treats local file writes as overwrite-style — same
+        // precedent as scan's findings-cache and review's review-log.
+        idempotent: true,
+        // Local file write only — no PR comment posting, no git push, no
+        // provider-side mutation, no SARIF upload. See the long deviation note
+        // above where the engine resolution is computed for the externalRefs
+        // rationale.
+        hasSideEffects: false,
+        run: async (input) => executeValidatePhase(input),
+    };
+    // v6.0.6 — lifecycle wiring lives in `runPhaseWithLifecycle`.
+    let output;
+    try {
+        const result = await runPhaseWithLifecycle({
+            cwd,
+            phase,
+            input: validateInput,
+            config,
+            cliEngine: options.cliEngine,
+            envEngine: options.envEngine,
+            runEngineOff: () => executeValidatePhase(validateInput),
+        });
+        output = result.output;
+    }
+    catch {
+        return 1;
+    }
+    return renderValidateOutput(output, validateInput);
+}
+// ---------------------------------------------------------------------------
+// Phase body — write a validate log stub. Pure: no console output, no exit
+// codes. Returns a JSON-serializable ValidateOutput so the engine can persist
+// it as `result` on the phase snapshot. The actual validation work is
+// produced by the Claude Code `/validate` skill; this CLI verb's job is to
+// provide a checkpointable phase shell.
+// ---------------------------------------------------------------------------
+async function executeValidatePhase(input) {
+    const { context, outputPath } = input;
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    const lines = [
+        '# Validate',
+        '',
+        `Generated: ${new Date().toISOString()}`,
+        '',
+        context ? `Context: ${context}` : 'Context: (none provided)',
+        '',
+        '<!--',
+        'This is the v6 engine-wrap stub for the `validate` phase. The actual',
+        'validation work (static checks, auto-fix, tests, Codex review with',
+        'auto-fix, bugbot triage) is produced by the Claude Code `/validate`',
+        'skill. The CLI verb exists to provide a checkpointable phase shell so',
+        '`claude-autopilot runs show <id>` reflects a `validate` phase entry',
+        'when the pipeline includes one. SARIF emission lives in',
+        '`claude-autopilot run --format sarif --output <path>` (a separate',
+        'verb).',
+        '-->',
+        '',
+    ];
+    fs.writeFileSync(outputPath, lines.join('\n'), 'utf8');
+    return {
+        validateLogPath: outputPath,
+        context,
+    };
+}
+// ---------------------------------------------------------------------------
+// Render — translate ValidateOutput back to a stdout summary + exit code.
+// Lives outside the wrapped phase because it's pure presentation.
+// ---------------------------------------------------------------------------
+function renderValidateOutput(output, input) {
+    const { validateLogPath, context } = output;
+    const { cwd } = input;
+    console.log('');
+    console.log(fmt('bold', '[validate]') + ' ' + fmt('dim', context ? `context: ${context}` : 'no context provided'));
+    console.log(fmt('dim', `  → ${path.relative(cwd, validateLogPath)}`));
+    console.log('');
+    console.log(fmt('cyan', 'Note:') + fmt('dim', ' the validation pipeline lives in Claude Code (/validate skill —'));
+    console.log(fmt('dim', '       static checks, auto-fix, tests, Codex review, bugbot triage).'));
+    console.log(fmt('dim', '       SARIF emission lives in `claude-autopilot run --format sarif --output <path>`.'));
+    console.log('');
+    return 0;
+}
+//# sourceMappingURL=validate.js.map

package/dist/src/core/config/schema.d.ts

@@ -298,6 +298,15 @@ export declare const GUARDRAIL_CONFIG_SCHEMA: {
         readonly concurrency: {
             readonly type: "object";
         };
+        readonly engine: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly enabled: {
+                    readonly type: "boolean";
+                };
+            };
+        };
         readonly council: {
             readonly type: "object";
             readonly required: readonly ["models", "synthesizer"];

package/dist/src/core/config/schema.js

@@ -152,6 +152,13 @@ export const GUARDRAIL_CONFIG_SCHEMA = {
         cache: { type: 'object' },
         persistence: { type: 'object' },
         concurrency: { type: 'object' },
+        engine: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                enabled: { type: 'boolean' },
+            },
+        },
         council: {
             type: 'object',
             required: ['models', 'synthesizer'],

package/dist/src/core/config/types.d.ts

@@ -101,6 +101,17 @@ export interface GuardrailConfig {
     cache?: Record<string, unknown>;
     persistence?: Record<string, unknown>;
     concurrency?: Record<string, unknown>;
+    /**
+     * Run State Engine (v6) configuration. v6.0 ships the engine OFF by default
+     * to preserve v5.x behavior; v6.1+ flips the default to ON per
+     * `docs/specs/v6.1-default-flip.md`. The `engine.enabled` knob is the
+     * lowest-priority opt-in — env (`CLAUDE_AUTOPILOT_ENGINE`) and CLI flags
+     * (`--engine` / `--no-engine`) override it. See
+     * `src/core/run-state/resolve-engine.ts` for the precedence resolver.
+     */
+    engine?: {
+        enabled?: boolean;
+    };
     council?: {
         models: Array<{
             adapter: string;

package/dist/src/core/council/runner.d.ts

@@ -8,5 +8,14 @@ export interface CouncilRunOutput {
         costUSD: number;
     };
 }
-export declare function runCouncil(config: CouncilConfig, adapters: CouncilAdapter[], synthesizer: CouncilAdapter, prompt: string, contextDoc: string): Promise<CouncilRunOutput>;
+/** Phase 4 — bounded recursion options. The current single-shot
+ *  synthesizer never sets this; it's plumbed for future self-eat
+ *  patterns where the synthesizer recursively calls runCouncil. */
+export interface CouncilRunOptions {
+    /** Current recursion depth. Top-level callers omit this (default 0).
+     *  A synthesizer that calls runCouncil internally MUST pass
+     *  `currentDepth + 1` so the bound takes effect. */
+    currentDepth?: number;
+}
+export declare function runCouncil(config: CouncilConfig, adapters: CouncilAdapter[], synthesizer: CouncilAdapter, prompt: string, contextDoc: string, options?: CouncilRunOptions): Promise<CouncilRunOutput>;
 //# sourceMappingURL=runner.d.ts.map

package/dist/src/core/council/runner.js

@@ -32,8 +32,26 @@ async function consultWithTimeout(adapter, prompt, context, timeoutMs) {
             clearTimeout(timer);
     }
 }
-export async function runCouncil(config, adapters, synthesizer, prompt, contextDoc) {
+export async function runCouncil(config, adapters, synthesizer, prompt, contextDoc, options = {}) {
     const run_id = crypto.randomUUID();
+    const currentDepth = options.currentDepth ?? 0;
+    // -- Recursion bound (Phase 4) ------------------------------------------
+    // Strict `>` so a maxDepth of N permits N nested self-calls — i.e.
+    // depth 0 (top-level) + N inner calls. Exceeding aborts with `partial`
+    // and never recurses deeper.
+    if (typeof config.councilMaxRecursionDepth === 'number'
+        && currentDepth > config.councilMaxRecursionDepth) {
+        return {
+            result: {
+                schema_version: 1,
+                run_id,
+                status: 'partial',
+                prompt,
+                responses: [],
+            },
+            usage: { inputTokens: 0, outputTokens: 0, costUSD: 0 },
+        };
+    }
     const context = windowContext(contextDoc, config.parallelInputMaxTokens);
     const responses = await Promise.all(adapters.map(a => consultWithTimeout(a, prompt, context, config.timeoutMs)));
     const aggregateUsage = (entries) => {
@@ -61,8 +79,12 @@ export async function runCouncil(config, adapters, synthesizer, prompt, contextD
     const responseSections = successful
         .map(r => `### ${r.label}\n${r.text}`)
         .join('\n\n');
-    const synthesisDoc = `${contextDoc}\n\n---\n\n${responseSections}`;
-    const synthesisCtx = windowContext(synthesisDoc, config.synthesisInputMaxTokens);
+    // Advisor responses go in synthesisPrompt only (structured form). The
+    // context the synthesizer sees is the original conversation document
+    // re-windowed for its own token budget — keeping responseSections out of
+    // it avoids duplicating them and also avoids letting large responses
+    // squeeze contextDoc out of synthesisInputMaxTokens.
+    const synthesisCtx = windowContext(contextDoc, config.synthesisInputMaxTokens);
     const synthesisPrompt = [
         `You have received responses from multiple technical advisors on the following question:\n\n## Original Question\n\n${prompt}`,
         `## Advisor Responses\n\n${responseSections}`,

package/dist/src/core/council/types.d.ts

@@ -10,6 +10,13 @@ export interface CouncilConfig {
     minSuccessfulResponses: number;
     parallelInputMaxTokens: number;
     synthesisInputMaxTokens: number;
+    /** Phase 4 (v6) — bounded recursion for the synthesizer. If set, every
+     *  synthesizer self-call increments an internal depth counter; exceeding
+     *  this value aborts the council with `partial` status (never deeper).
+     *  Default: undefined (no bound; current single-shot synthesizer is
+     *  unaffected — the bound only matters when the synthesizer itself
+     *  recurses into runCouncil). */
+    councilMaxRecursionDepth?: number;
 }
 export type ModelResponseStatus = 'ok' | 'timeout' | 'error';
 export interface ModelResponse {

package/dist/src/core/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = 'auth' | 'rate_limit' | 'transient_network' | 'invalid_config' | 'adapter_bug' | 'user_input' | 'budget_exceeded' | 'concurrency_lock' | 'superseded' | 'no_previous_deploy';
+export type ErrorCode = 'auth' | 'rate_limit' | 'transient_network' | 'invalid_config' | 'adapter_bug' | 'user_input' | 'budget_exceeded' | 'concurrency_lock' | 'superseded' | 'no_previous_deploy' | 'not_found' | 'lock_held' | 'corrupted_state' | 'partial_write' | 'needs_human';
 export interface GuardrailErrorOptions {
     code: ErrorCode;
     retryable?: boolean;

package/dist/src/core/errors.js

@@ -4,6 +4,17 @@ const DEFAULT_RETRYABLE = {
     adapter_bug: false, user_input: false, budget_exceeded: false,
     concurrency_lock: false, superseded: false,
     no_previous_deploy: false,
+    // 404 — caller-fixable (slug typo, wrong scope). Not retryable; the
+    // resource won't materialize on its own.
+    not_found: false,
+    // v6 Run State Engine — none retry automatically; takeover/recovery is an
+    // explicit user-driven decision (--force-takeover / --force).
+    lock_held: false,
+    corrupted_state: false,
+    partial_write: false,
+    // v6.2.1 — needs_human is by definition a stop-the-pipeline signal; the
+    // user (or `--force-replay`) decides whether to retry.
+    needs_human: false,
 };
 export class GuardrailError extends Error {
     code;

package/dist/src/core/logging/redaction.d.ts

@@ -1,4 +1,17 @@
 export declare const DEFAULT_REDACTION_PATTERNS: readonly string[];
 export declare function applyRedaction(text: string, patterns: readonly string[]): string;
 export declare function containsSecret(text: string, patterns: readonly string[]): boolean;
+/**
+ * Convenience wrapper around {@link applyRedaction} that defaults to the
+ * built-in {@link DEFAULT_REDACTION_PATTERNS} list and accepts an optional
+ * caller-supplied extension. Designed for adapter `output` fields and other
+ * "last N lines" surfaces where a pattern list is rarely available at the
+ * call site (the v5.6 spec § "Log redaction" requires this for all new
+ * adapters).
+ *
+ * Pass extra patterns when the caller has loaded
+ * `config.persistence.redactionPatterns`; otherwise omit the argument and
+ * the defaults handle the well-known token shapes.
+ */
+export declare function redactLogLines(text: string, patterns?: readonly string[]): string;
 //# sourceMappingURL=redaction.d.ts.map

package/dist/src/core/logging/redaction.js

@@ -15,4 +15,24 @@ export function applyRedaction(text, patterns) {
 export function containsSecret(text, patterns) {
     return patterns.some(p => new RegExp(p).test(text));
 }
+/**
+ * Convenience wrapper around {@link applyRedaction} that defaults to the
+ * built-in {@link DEFAULT_REDACTION_PATTERNS} list and accepts an optional
+ * caller-supplied extension. Designed for adapter `output` fields and other
+ * "last N lines" surfaces where a pattern list is rarely available at the
+ * call site (the v5.6 spec § "Log redaction" requires this for all new
+ * adapters).
+ *
+ * Pass extra patterns when the caller has loaded
+ * `config.persistence.redactionPatterns`; otherwise omit the argument and
+ * the defaults handle the well-known token shapes.
+ */
+export function redactLogLines(text, patterns) {
+    if (!text)
+        return text;
+    const merged = patterns && patterns.length > 0
+        ? [...DEFAULT_REDACTION_PATTERNS, ...patterns]
+        : DEFAULT_REDACTION_PATTERNS;
+    return applyRedaction(text, merged);
+}
 //# sourceMappingURL=redaction.js.map

package/dist/src/core/migrate/schema-validator.js

@@ -54,7 +54,20 @@ function buildValidator() {
     }
     return ajv.compile(schema);
 }
-const validate = buildValidator();
+// Lazy-init: previously the validator was built at module load, which meant
+// every `claude-autopilot --version` (or any CLI invocation that imports the
+// migrate module via dispatch chain) eagerly read presets/aliases.lock.json
+// + presets/schemas/migrate.schema.json. Missing files crashed the entire
+// CLI with a stack trace before the user-facing entry point even started.
+// Rebuilding on first use also keeps tests that don't touch validation
+// from paying the AJV compile cost. Caught by the tombstone-bin test
+// (`does not leak a node stack trace when claude-autopilot is unreachable`).
+let _validate;
+function getValidator() {
+    if (_validate === undefined)
+        _validate = buildValidator();
+    return _validate;
+}
 function commandsEqual(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
@@ -99,6 +112,7 @@ export function validateStackMd(yamlSource) {
                 }],
         };
     }
+    const validate = getValidator();
     const ok = validate(parsed);
     const schemaErrors = ok ? [] : ajvErrorsToValidationErrors(validate.errors ?? []);
     const crossFieldErrors = ok ? checkDevCommandReuse(parsed) : [];

package/dist/src/core/phases/static-rules.d.ts

@@ -1,10 +1,14 @@
 import type { Finding, FixAttempt, FixStatus } from '../findings/types.ts';
 import type { GuardrailConfig } from '../config/types.ts';
 import type { ReviewEngine } from '../../adapters/review-engine/types.ts';
+export interface StaticRuleContext {
+    config?: GuardrailConfig;
+    engine?: ReviewEngine;
+}
 export interface StaticRule {
     name: string;
     severity: 'critical' | 'warning' | 'note';
-    check(touchedFiles: string[], config?: Record<string, unknown>): Promise<Finding[]>;
+    check(touchedFiles: string[], ctx?: StaticRuleContext): Promise<Finding[]>;
     autofix?(finding: Finding): Promise<FixStatus>;
 }
 export interface StaticRulesPhaseInput {

package/dist/src/core/phases/static-rules.js

@@ -42,13 +42,10 @@ export async function runStaticRulesPhase(input) {
     return { phase: 'static-rules', status, findings: preFixFindings, fixAttempts, durationMs: Date.now() - start };
 }
 async function runAllChecks(rules, files, config, engine) {
-    const ruleConfig = {
-        ...(config ? config : {}),
-        _engine: engine,
-    };
+    const ctx = { config, engine };
     const all = [];
     for (const rule of rules)
-        all.push(...(await rule.check(files, ruleConfig)));
+        all.push(...(await rule.check(files, ctx)));
     return all;
 }
 function findRuleForFinding(rules, finding) {

package/dist/src/core/run-state/budget.d.ts

@@ -0,0 +1,88 @@
+/** Default Layer 2 reserve when none is configured. Conservative — phases
+ *  without an `estimateCost` are assumed to consume at least this much,
+ *  which keeps the cap from "failing open" the moment a phase forgets to
+ *  declare its cost shape. */
+export declare const DEFAULT_CONSERVATIVE_PHASE_RESERVE_USD = 5;
+export interface BudgetConfig {
+    /** Total run cap (USD). Hard stop. Required — phases that don't want
+     *  budget enforcement should not pass a `BudgetConfig` at all. */
+    perRunUSD: number;
+    /** Per-phase cap (USD). Phases that haven't declared `estimateCost`
+     *  still pay the conservativePhaseReserve under Layer 2. Optional. */
+    perPhaseUSD?: number;
+    /** Bounded recursion for council synthesizer. Wired in
+     *  `src/core/council/runner.ts`; no effect inside `runPhase`. */
+    councilMaxRecursionDepth?: number;
+    /** Bounded autopilot self-eat rounds (per spec). Reserved field —
+     *  consumed by the autopilot orchestrator, not the runner. */
+    bgAutopilotMaxRoundsPerSelfEat?: number;
+    /** Used by Layer 2 (mandatory runtime guard) when a phase has no
+     *  `estimateCost` — represents the "we don't know how big this gets,
+     *  reserve at least this much from the cap" floor. Defaults to
+     *  `DEFAULT_CONSERVATIVE_PHASE_RESERVE_USD` when omitted. */
+    conservativePhaseReserveUSD?: number;
+    /** v6.2.0 — budget scope. `'phase'` (default) keeps the legacy
+     *  per-phase semantics where each `runPhase` invocation reasons against
+     *  its own phase budget (back-compat for single-phase wrappers like
+     *  `runPhaseWithLifecycle`). `'run'` is the orchestrator's
+     *  cross-phase mode: the actualSoFar reservoir already sums every
+     *  prior `phase.cost` event in the run, so `perRunUSD` is policed
+     *  monotonically against the WHOLE pipeline's spend.
+     *
+     *  In practice the policy math is identical between the two scopes —
+     *  Layer 1 + Layer 2 both consume `actualSoFarUSD` regardless. The
+     *  scope flag exists so the `budget.check` event tells observers
+     *  which mode produced the decision (so a CI dashboard can attribute
+     *  a reject to "run scope" vs "single-phase scope") and so future
+     *  policy changes (e.g. divergent perPhase reserves under run scope)
+     *  have a place to land without an event-shape break.
+     *
+     *  Per spec docs/specs/v6.2-multi-phase-orchestrator.md "Budget
+     *  enforcement": `checkPhaseBudget` gains `scope: 'phase' | 'run'`
+     *  (default 'phase' for back-compat). Orchestrator passes
+     *  `scope: 'run'`; per-phase callers keep the default. */
+    scope?: 'phase' | 'run';
+}
+/** The decision the runner consumes. Mirrors the `budget.check` event
+ *  payload one-to-one so wiring is trivial. */
+export interface BudgetCheck {
+    decision: 'proceed' | 'pause' | 'hard-fail';
+    phase: string;
+    phaseIdx: number;
+    /** `estimate.high` from the phase's `estimateCost` if it returned a
+     *  value; null when the phase doesn't implement estimateCost. */
+    estimatedHigh: number | null;
+    actualSoFar: number;
+    /** The reserve the policy deducted against `perRunUSD` for this phase
+     *  (the larger of `estimate.high` and `conservativePhaseReserveUSD`). */
+    reserveApplied: number;
+    /** USD remaining under `perRunUSD` after `actualSoFar` + the larger of
+     *  `estimatedHigh` and `reserveApplied`. May be negative on hard-fail. */
+    capRemaining: number;
+    reason: string;
+    /** v6.2.0 — which scope produced the decision. Echoes `BudgetConfig.scope`
+     *  back into the `budget.check` event so observers can attribute
+     *  cross-phase rejections to the orchestrator vs single-phase wrappers
+     *  passing the legacy default. */
+    scope: 'phase' | 'run';
+}
+export interface CheckPhaseBudgetOpts {
+    budget: BudgetConfig;
+    phaseName: string;
+    phaseIdx: number;
+    /** What `RunPhase.estimateCost(input)` returned, or null if absent. */
+    estimatedCost: {
+        lowUSD: number;
+        highUSD: number;
+    } | null;
+    /** Sum of every prior `phase.cost` event in the run, in USD. */
+    actualSoFarUSD: number;
+    /** When true, a `pause` decision becomes `hard-fail` (CI / `--json`
+     *  mode can't prompt for human approval). */
+    nonInteractive: boolean;
+}
+/** Policy decision for a single about-to-run phase. Pure — no IO. The
+ *  caller (`runPhase`) is responsible for emitting the `budget.check`
+ *  event with this payload and acting on the decision. */
+export declare function checkPhaseBudget(opts: CheckPhaseBudgetOpts): BudgetCheck;
+//# sourceMappingURL=budget.d.ts.map

package/dist/src/core/run-state/budget.js

@@ -0,0 +1,141 @@
+// src/core/run-state/budget.ts
+//
+// v6 Phase 4 — budget enforcement policy.
+//
+// Pure data + a pure decision function. No IO, no globals, no side effects.
+// `checkPhaseBudget` is the authoritative answer to "may this phase run?"
+// — `runPhase` consumes the result, emits a `budget.check` event with the
+// full payload, and throws `budget_exceeded` on hard-fail.
+//
+// Two-layer policy per spec (Codex CRITICAL #3 fold-in — estimates can fail
+// open, the runtime guard MUST run independently):
+//
+//   - Layer 1 (advisory)  — only fires when the phase declares
+//     `estimateCost`. Compares `actualSoFar + estimate.high` against
+//     `perRunUSD`. Pause-and-prompt (interactive) or hard-fail (CI mode)
+//     if it would exceed.
+//   - Layer 2 (mandatory) — ALWAYS runs. Compares `actualSoFar +
+//     conservativePhaseReserveUSD` against `perRunUSD`. Phases without
+//     estimates therefore still trigger budget gates. Default reserve is
+//     $5 (overridable in config).
+//   - `perPhaseUSD` gate — if set AND the larger of the per-phase estimate
+//     or reserve would push this phase's cost over the per-phase cap,
+//     applies the same pause/hard-fail rule.
+//
+// Spec: docs/specs/v6-run-state-engine.md "Budget enforcement".
+/** Default Layer 2 reserve when none is configured. Conservative — phases
+ *  without an `estimateCost` are assumed to consume at least this much,
+ *  which keeps the cap from "failing open" the moment a phase forgets to
+ *  declare its cost shape. */
+export const DEFAULT_CONSERVATIVE_PHASE_RESERVE_USD = 5;
+/** Policy decision for a single about-to-run phase. Pure — no IO. The
+ *  caller (`runPhase`) is responsible for emitting the `budget.check`
+ *  event with this payload and acting on the decision. */
+export function checkPhaseBudget(opts) {
+    const { budget, phaseName, phaseIdx, estimatedCost, actualSoFarUSD, nonInteractive, } = opts;
+    // v6.2.0 — `'phase'` (default for back-compat) vs `'run'` (orchestrator).
+    // The math is intentionally identical between the two; `actualSoFarUSD`
+    // is already the cross-phase sum produced by `sumRunCost` in
+    // phase-runner.ts. The flag exists so the `budget.check` event tells
+    // observers which scope generated the decision and so future policy
+    // tweaks (e.g. divergent perPhase reserves under run scope) have a
+    // place to land without an event-shape break.
+    const scope = budget.scope ?? 'phase';
+    const reserveFloor = typeof budget.conservativePhaseReserveUSD === 'number'
+        ? budget.conservativePhaseReserveUSD
+        : DEFAULT_CONSERVATIVE_PHASE_RESERVE_USD;
+    // The reserve actually deducted is the larger of "what the phase says
+    // it will cost (high end)" and "the conservative floor we always apply".
+    // This is the core of Codex CRITICAL #3 — even if estimateCost is
+    // present and tiny, the floor still applies, and even if estimateCost
+    // is absent, the floor still applies.
+    const estimatedHigh = estimatedCost?.highUSD ?? null;
+    const reserveApplied = Math.max(estimatedHigh ?? 0, reserveFloor);
+    const projected = actualSoFarUSD + reserveApplied;
+    const capRemaining = budget.perRunUSD - projected;
+    // Layer 1 — ADVISORY using the explicit estimate. Runs FIRST so a precise
+    // estimate produces a precise reason ("estimate would exceed cap") instead
+    // of falling through to Layer 2's conservative-floor wording. Only fires
+    // when an estimate is present AND would push us past perRunUSD on its own.
+    // (Bugbot LOW on PR #89 caught the prior ordering, where Layer 2 always
+    // ran first and Layer 1 was provably unreachable since `reserveApplied =
+    // max(estimatedHigh, floor) >= estimatedHigh`.)
+    if (estimatedHigh !== null && actualSoFarUSD + estimatedHigh > budget.perRunUSD) {
+        const decision = nonInteractive ? 'hard-fail' : 'pause';
+        return {
+            decision,
+            phase: phaseName,
+            phaseIdx,
+            estimatedHigh,
+            actualSoFar: actualSoFarUSD,
+            reserveApplied,
+            capRemaining: budget.perRunUSD - (actualSoFarUSD + estimatedHigh),
+            reason: `advisory estimate would exceed run cap — actual ` +
+                `$${fmtUSD(actualSoFarUSD)} + estimate.high ` +
+                `$${fmtUSD(estimatedHigh)} > perRunUSD $${fmtUSD(budget.perRunUSD)}`,
+            scope,
+        };
+    }
+    // Layer 2 — MANDATORY floor against perRunUSD. Catches the case where the
+    // estimate is missing (Layer 1 didn't fire) OR present-but-tiny (estimate
+    // alone fits, but the conservative reserve floor pushes over). This is the
+    // safety net that prevents phases without `estimateCost` from sneaking
+    // past the cap.
+    if (projected > budget.perRunUSD) {
+        const decision = nonInteractive ? 'hard-fail' : 'pause';
+        return {
+            decision,
+            phase: phaseName,
+            phaseIdx,
+            estimatedHigh,
+            actualSoFar: actualSoFarUSD,
+            reserveApplied,
+            capRemaining,
+            reason: `run cap exceeded — actual $${fmtUSD(actualSoFarUSD)} + reserve ` +
+                `$${fmtUSD(reserveApplied)} = $${fmtUSD(projected)} > perRunUSD ` +
+                `$${fmtUSD(budget.perRunUSD)}`,
+            scope,
+        };
+    }
+    // perPhaseUSD gate — independent of the run cap. Applies the same
+    // reserve logic but compares against the per-phase cap.
+    if (typeof budget.perPhaseUSD === 'number' && reserveApplied > budget.perPhaseUSD) {
+        const decision = nonInteractive ? 'hard-fail' : 'pause';
+        return {
+            decision,
+            phase: phaseName,
+            phaseIdx,
+            estimatedHigh,
+            actualSoFar: actualSoFarUSD,
+            reserveApplied,
+            capRemaining,
+            reason: `per-phase cap exceeded — reserve $${fmtUSD(reserveApplied)} > ` +
+                `perPhaseUSD $${fmtUSD(budget.perPhaseUSD)}`,
+            scope,
+        };
+    }
+    return {
+        decision: 'proceed',
+        phase: phaseName,
+        phaseIdx,
+        estimatedHigh,
+        actualSoFar: actualSoFarUSD,
+        reserveApplied,
+        capRemaining,
+        reason: estimatedHigh !== null
+            ? `within budget — projected $${fmtUSD(projected)} of $${fmtUSD(budget.perRunUSD)}`
+            : `within budget (no estimate, applied $${fmtUSD(reserveApplied)} ` +
+                `reserve floor) — projected $${fmtUSD(projected)} of ` +
+                `$${fmtUSD(budget.perRunUSD)}`,
+        scope,
+    };
+}
+/** Format a USD amount with 2 decimal places for human-readable reasons.
+ *  Kept local — the run-state module doesn't have a shared formatter and
+ *  budget reasons are the only consumer. */
+function fmtUSD(n) {
+    // toFixed(2) returns "0.00" for 0; we keep the trailing zeros so the
+    // reason strings line up visually in CLI output.
+    return n.toFixed(2);
+}
+//# sourceMappingURL=budget.js.map