@delegance/claude-autopilot 5.2.2 → 6.2.2

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

@@ -206,6 +206,40 @@ export declare const GUARDRAIL_CONFIG_SCHEMA: {
             };
             readonly additionalProperties: false;
         };
+        readonly deploy: {
+            readonly type: "object";
+            readonly required: readonly ["adapter"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly adapter: {
+                    readonly enum: readonly ["vercel", "generic"];
+                };
+                readonly project: {
+                    readonly type: "string";
+                };
+                readonly team: {
+                    readonly type: "string";
+                };
+                readonly target: {
+                    readonly enum: readonly ["production", "preview"];
+                };
+                readonly deployCommand: {
+                    readonly type: "string";
+                };
+                readonly watchBuildLogs: {
+                    readonly type: "boolean";
+                };
+                readonly rollbackOn: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly enum: readonly ["healthCheckFailure", "smokeTestFailure"];
+                    };
+                };
+                readonly healthCheckUrl: {
+                    readonly type: "string";
+                };
+            };
+        };
         readonly 'schema-alignment': {
             readonly type: "object";
             readonly properties: {
@@ -264,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

@@ -112,6 +112,24 @@ export const GUARDRAIL_CONFIG_SCHEMA = {
             },
             additionalProperties: false,
         },
+        deploy: {
+            type: 'object',
+            required: ['adapter'],
+            additionalProperties: false,
+            properties: {
+                adapter: { enum: ['vercel', 'generic'] },
+                project: { type: 'string' },
+                team: { type: 'string' },
+                target: { enum: ['production', 'preview'] },
+                deployCommand: { type: 'string' },
+                watchBuildLogs: { type: 'boolean' },
+                rollbackOn: {
+                    type: 'array',
+                    items: { enum: ['healthCheckFailure', 'smokeTestFailure'] },
+                },
+                healthCheckUrl: { type: 'string' },
+            },
+        },
         'schema-alignment': {
             type: 'object',
             properties: {
@@ -134,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

@@ -1,4 +1,5 @@
 import type { SchemaAlignmentConfig } from '../schema-alignment/types.ts';
+import type { DeployConfig } from '../../adapters/deploy/types.ts';
 export interface AdapterReference {
     adapter: string;
     options?: Record<string, unknown>;
@@ -92,9 +93,25 @@ export interface GuardrailConfig {
         };
     };
     'schema-alignment'?: SchemaAlignmentConfig;
+    /**
+     * Deploy phase configuration. Optional — when absent, the deploy phase is a
+     * no-op. See `src/adapters/deploy/types.ts` for the full DeployConfig shape.
+     */
+    deploy?: DeployConfig;
     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';
+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

@@ -3,6 +3,18 @@ const DEFAULT_RETRYABLE = {
     auth: false, rate_limit: true, transient_network: true, invalid_config: false,
     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/detector-rules.js

@@ -38,6 +38,7 @@ export const DETECTION_RULES = [
         requireAll: ['prisma/schema.prisma'],
         excludeIf: ['prisma/migrations'],
         defaultSkill: 'migrate@1',
+        defaultCommand: { exec: 'prisma', args: ['db', 'push'] },
         promptOnSelect: true,
     },
     {
@@ -58,6 +59,7 @@ export const DETECTION_RULES = [
         requireAny: ['drizzle.config.ts', 'drizzle.config.js'],
         excludeIf: ['drizzle/migrations'],
         defaultSkill: 'migrate@1',
+        defaultCommand: { exec: 'drizzle-kit', args: ['push'] },
         promptOnSelect: true,
     },
     {
@@ -76,6 +78,9 @@ export const DETECTION_RULES = [
         confidence: 'high',
         requireAll: ['go.mod', 'migrate'],
         defaultSkill: 'migrate@1',
+        // Conventional invocation; users with non-standard layouts will edit
+        // the generated stack.md (e.g. different -path or DSN flag).
+        defaultCommand: { exec: 'migrate', args: ['-database', '$DATABASE_URL', '-path', 'migrations', 'up'] },
         promptOnSelect: false,
     },
     {
@@ -132,6 +137,7 @@ export const DETECTION_RULES = [
         requireAll: [],
         requireAny: ['ormconfig.json', 'ormconfig.ts', 'ormconfig.js', 'data-source.ts'],
         defaultSkill: 'migrate@1',
+        defaultCommand: { exec: 'typeorm', args: ['migration:run'] },
         promptOnSelect: true,
     },
     {

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

@@ -12,6 +12,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
 import * as yaml from 'js-yaml';
 import { requirePackageRoot } from "../../cli/_pkg-root.js";
 // Resolve presets/ relative to the canonical package root so this works under
@@ -28,6 +29,12 @@ function loadStableIds() {
 }
 function buildValidator() {
     const ajv = new Ajv({ strict: false, allErrors: true });
+    // Register standard formats (date-time, uri, email, etc.) so the schema's
+    // `format: "date-time"` constraint is actually validated rather than warned-
+    // about-and-ignored on every CLI invocation. Pre-5.2.3 every command printed:
+    //   "unknown format \"date-time\" ignored in schema at path #/.../detected_at"
+    // — twice, since the validator is built lazily in two paths.
+    addFormats(ajv);
     const stableIds = loadStableIds();
     // Custom keyword: validates that the value is one of the registered stable IDs.
     ajv.addKeyword({
@@ -47,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);
 }
@@ -92,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