substrate-ai 0.20.64 → 0.20.65

package/dist/src/modules/recovery-engine/index.d.ts

@@ -0,0 +1,1101 @@
+import { CoreEvents, DatabaseAdapter, TypedEventBus } from "../../../index-c924O9mj.js";
+import { z } from "zod";
+
+//#region packages/sdlc/dist/verification/findings.d.ts
+/**
+* VerificationFinding — structured per-issue payload emitted by verification checks.
+*
+* Replaces the ad-hoc "stuff everything into VerificationResult.details" pattern
+* that preceded it: every downstream consumer (retry prompts, run manifest,
+* post-run analysis) used to string-parse a free-form blob that the emitting
+* check never promised a schema for. With findings, each issue is an
+* addressable record the pipeline can act on individually.
+*
+* The {command, exitCode, stdoutTail, stderrTail} optional fields are reserved
+* primarily for Phase 2 runtime probes — they cost nothing on the current four
+* Tier A checks (which leave them undefined) but let probe output flow through
+* the same shape without a second refactor.
+*/
+/**
+* Severity of a single verification finding.
+*
+* - `error` → verification check returns `fail` (the aggregate status of the
+*   containing VerificationResult is `fail`).
+* - `warn`  → verification check returns `warn`.
+* - `info`  → a finding captured for diagnostic/telemetry purposes that does
+*   not itself raise the containing VerificationResult's status.
+*/
+/**
+ * VerificationFinding — structured per-issue payload emitted by verification checks.
+ *
+ * Replaces the ad-hoc "stuff everything into VerificationResult.details" pattern
+ * that preceded it: every downstream consumer (retry prompts, run manifest,
+ * post-run analysis) used to string-parse a free-form blob that the emitting
+ * check never promised a schema for. With findings, each issue is an
+ * addressable record the pipeline can act on individually.
+ *
+ * The {command, exitCode, stdoutTail, stderrTail} optional fields are reserved
+ * primarily for Phase 2 runtime probes — they cost nothing on the current four
+ * Tier A checks (which leave them undefined) but let probe output flow through
+ * the same shape without a second refactor.
+ */
+/**
+ * Severity of a single verification finding.
+ *
+ * - `error` → verification check returns `fail` (the aggregate status of the
+ *   containing VerificationResult is `fail`).
+ * - `warn`  → verification check returns `warn`.
+ * - `info`  → a finding captured for diagnostic/telemetry purposes that does
+ *   not itself raise the containing VerificationResult's status.
+ */
+type VerificationFindingSeverity = 'error' | 'warn' | 'info';
+/**
+ * One structured issue emitted by a verification check.
+ *
+ * `category` is the stable machine-readable identifier consumers filter/group
+ * on (e.g. `'build-error'`, `'ac-missing-evidence'`, `'phantom-review'`,
+ * `'trivial-output'`). New categories should be introduced alongside the
+ * check that emits them.
+ */
+interface VerificationFinding {
+  /** Stable machine-readable category (e.g. `'build-error'`). */
+  category: string;
+  /** Severity classification for aggregate-status computation. */
+  severity: VerificationFindingSeverity;
+  /** Single-line human-readable summary. */
+  message: string;
+  /** The command that produced this finding, if any. Reserved primarily for Phase 2 runtime probes. */
+  command?: string;
+  /** Exit status of `command`, if applicable. */
+  exitCode?: number;
+  /** Last ≤ 4 KiB of stdout from `command`, if captured. */
+  stdoutTail?: string;
+  /** Last ≤ 4 KiB of stderr from `command`, if captured. */
+  stderrTail?: string;
+  /** Wall-clock milliseconds the producing action took. */
+  durationMs?: number;
+  /**
+   * Story 60-15: when this finding came from a runtime-probe failure,
+   * records who authored the failing probe (`'probe-author'` if Epic 60
+   * Phase 2's probe-author phase appended it, `'create-story-ac-transfer'`
+   * for the legacy AC-transfer path). Absent for findings from other
+   * checks (build, phantom-review, ac-evidence, etc.). Persisted on the
+   * stored finding so post-run analysis can compute byAuthor breakdowns
+   * and the catch-rate KPI's per-author attribution.
+   */
+  _authoredBy?: 'probe-author' | 'create-story-ac-transfer';
+  /**
+   * Story 66-7: when this finding has category
+   * `runtime-probe-placeholder-not-substituted`, carries the escaped
+   * placeholder token (e.g. `<UNKNOWN_VAR>`) that was not substituted
+   * before probe execution. Absent for all other finding categories.
+   */
+  unrecognizedPlaceholder?: string;
+} //#endregion
+//#region packages/sdlc/dist/verification/types.d.ts
+
+/**
+ * source-ac-shellout-npx-fallback — Story 67-3, obs_2026-05-03_023 fix #3.
+ *
+ * Severity: warn. Emitted by SourceAcShelloutCheck when a bare `npx <package>`
+ * invocation (without `--no-install`) is detected in a story-modified source file.
+ * A bare `npx <package>` without `--no-install` falls through to the public npm
+ * registry on first use if the package binary is not locally installed —
+ * a dependency-confusion attack vector.
+ */
+
+/**
+ * Result returned by a single VerificationCheck.run() invocation.
+ *
+ * `details` is a human-readable rendering, preserved for any consumer that
+ * already reads it. `findings` (story 55-1) is the structured per-issue
+ * surface — downstream consumers (retry prompts, run manifest, post-run
+ * analysis) should prefer it. Checks that emit findings should derive
+ * `details` via `renderFindings(findings)` so the two stay in sync.
+ */
+interface VerificationResult {
+  status: 'pass' | 'warn' | 'fail';
+  details: string;
+  duration_ms: number;
+  /** Structured per-issue payload. Optional for backward compatibility with
+   * checks and consumers that pre-date story 55-1. */
+  findings?: VerificationFinding[];
+}
+/**
+ * Per-check result included in a VerificationSummary.
+ * Extends VerificationResult with the check's name.
+ */
+interface VerificationCheckResult extends VerificationResult {
+  checkName: string;
+}
+/**
+ * Aggregated summary for a single story's verification pipeline run.
+ *
+ * AC4: contains storyKey, array of per-check results, worst-case overall status,
+ * and total duration.
+ */
+interface VerificationSummary {
+  storyKey: string;
+  checks: VerificationCheckResult[];
+  /** Worst-case aggregate: fail > warn > pass. */
+  status: 'pass' | 'warn' | 'fail';
+  duration_ms: number;
+} //#endregion
+//#region packages/sdlc/dist/events.d.ts
+
+/**
+ * Interface that all verification check implementations must satisfy.
+ *
+ * AC1: name, tier ('A' | 'B'), and run(context) method.
+ * Tier A checks are static analysis; Tier B checks may use cross-story context.
+ */
+/**
+ * Structured escalation diagnosis from `orchestrator:story-escalated`.
+ * Carries classification and recommended action for the escalation.
+ */
+interface EscalationDiagnosis {
+  issueDistribution: 'concentrated' | 'widespread';
+  severityProfile: 'blocker-present' | 'major-only' | 'minor-only' | 'no-structured-issues';
+  totalIssues: number;
+  blockerCount: number;
+  majorCount: number;
+  minorCount: number;
+  affectedFiles: string[];
+  reviewCycles: number;
+  recommendedAction: 'retry-targeted' | 'split-story' | 'human-intervention';
+  rationale: string;
+}
+/**
+ * A single finding from `solutioning:readiness-failed`.
+ */
+interface SolutioningFinding {
+  category: string;
+  severity: string;
+  description: string;
+  affected_items: string[];
+}
+/**
+ * Phase-level timing breakdown from `story:metrics`.
+ * Keys are phase names (e.g., "dev-story", "code-review"), values are elapsed milliseconds.
+ */
+type StoryPhaseBreakdown = Record<string, number>;
+/**
+ * Complete typed map of all SDLC orchestrator events.
+ * Intersection with CoreEvents so TypedEventBus<SdlcEvents> includes all core event keys.
+ */
+type SdlcEvents = CoreEvents & {
+  /** Implementation orchestrator has started processing story keys */
+  'orchestrator:started': {
+    storyKeys: string[];
+    pipelineRunId?: string;
+  };
+  /** A story phase has started within the implementation orchestrator */
+  'orchestrator:story-phase-start': {
+    storyKey: string;
+    phase: string;
+    pipelineRunId?: string;
+  };
+  /** A story phase has completed within the implementation orchestrator */
+  'orchestrator:story-phase-complete': {
+    storyKey: string;
+    phase: string;
+    result: unknown;
+    pipelineRunId?: string;
+  };
+  /** A story has completed the full pipeline with SHIP_IT verdict */
+  'orchestrator:story-complete': {
+    storyKey: string;
+    reviewCycles: number;
+  };
+  /** A story has been escalated after exceeding max review cycles */
+  'orchestrator:story-escalated': {
+    storyKey: string;
+    lastVerdict: string;
+    reviewCycles: number;
+    issues: unknown[];
+    /** Structured diagnosis with classification and recommended action (Story 22-3) */
+    diagnosis?: EscalationDiagnosis;
+  };
+  /** A non-fatal warning occurred during story processing */
+  'orchestrator:story-warn': {
+    storyKey: string;
+    msg: string;
+  };
+  /** Zero-diff detection gate: dev-story reported COMPLETE but git diff is empty (Story 24-1) */
+  'orchestrator:zero-diff-escalation': {
+    storyKey: string;
+    reason: string;
+  };
+  /** Implementation orchestrator has finished all stories */
+  'orchestrator:complete': {
+    totalStories: number;
+    completed: number;
+    escalated: number;
+    failed: number;
+  };
+  /** Implementation orchestrator has been paused */
+  'orchestrator:paused': Record<string, never>;
+  /** Implementation orchestrator has been resumed */
+  'orchestrator:resumed': Record<string, never>;
+  /** Periodic heartbeat emitted every 30s during pipeline execution */
+  'orchestrator:heartbeat': {
+    runId: string;
+    activeDispatches: number;
+    completedDispatches: number;
+    queuedDispatches: number;
+  };
+  /** Watchdog detected no progress for an extended period */
+  'orchestrator:stall': {
+    runId: string;
+    storyKey: string;
+    phase: string;
+    elapsedMs: number;
+    /** PIDs of child processes at time of stall detection */
+    childPids: number[];
+    /** Whether any child process was actively running (not zombie) */
+    childActive: boolean;
+  };
+  /** Plan generation has started */
+  'plan:generating': {
+    agent: string;
+    description: string;
+  };
+  /** Plan generation has completed */
+  'plan:generated': {
+    taskCount: number;
+    estimatedCost: number;
+  };
+  /** Plan was approved by the user */
+  'plan:approved': {
+    taskCount: number;
+  };
+  /** Plan was rejected by the user */
+  'plan:rejected': {
+    reason: string;
+  };
+  /** Plan is being refined based on feedback */
+  'plan:refining': {
+    planId: string;
+    feedback: string;
+    currentVersion: number;
+  };
+  /** Plan refinement completed successfully */
+  'plan:refined': {
+    planId: string;
+    newVersion: number;
+    taskCount: number;
+  };
+  /** Plan was rolled back to a previous version */
+  'plan:rolled-back': {
+    planId: string;
+    fromVersion: number;
+    toVersion: number;
+    newVersion: number;
+  };
+  /** Plan refinement failed */
+  'plan:refinement-failed': {
+    planId: string;
+    currentVersion: number;
+    error: string;
+  };
+  /** Readiness check has completed — emitted for all verdicts (READY, NEEDS_WORK, NOT_READY) */
+  'solutioning:readiness-check': {
+    runId: string;
+    verdict: 'READY' | 'NEEDS_WORK' | 'NOT_READY';
+    coverageScore: number;
+    findingCount: number;
+    blockerCount: number;
+  };
+  /** Readiness check returned NOT_READY — solutioning phase will not proceed to implementation */
+  'solutioning:readiness-failed': {
+    runId: string;
+    verdict: 'NOT_READY';
+    coverageScore: number;
+    findings: SolutioningFinding[];
+  };
+  /**
+   * Emitted when a dev-story timeout has partial work on disk and the
+   * orchestrator captures it as a checkpoint for retry (Story 39-5).
+   */
+  'story:checkpoint-saved': {
+    /** Story key that timed out with partial work */
+    storyKey: string;
+    /** Number of files modified before the timeout */
+    filesCount: number;
+    /** Approximate byte length of the git diff captured */
+    diffSizeBytes: number;
+  };
+  /**
+   * Emitted when the orchestrator dispatches a checkpoint retry for a story
+   * that timed out with partial work (Story 39-6).
+   */
+  'story:checkpoint-retry': {
+    /** Story key being retried */
+    storyKey: string;
+    /** Number of files modified in the partial work captured at checkpoint */
+    filesCount: number;
+    /** Retry attempt number (always 2 — first retry after initial timeout) */
+    attempt: number;
+  };
+  /** Build verification command failed with non-zero exit or timeout */
+  'story:build-verification-failed': {
+    storyKey: string;
+    exitCode: number;
+    /** Build output (stdout+stderr), truncated to 2000 chars */
+    output: string;
+  };
+  /** Build verification command exited with code 0 */
+  'story:build-verification-passed': {
+    storyKey: string;
+  };
+  /** Non-blocking warning: modified .ts files export shared interfaces referenced by cross-module tests */
+  'story:interface-change-warning': {
+    storyKey: string;
+    modifiedInterfaces: string[];
+    potentiallyAffectedTests: string[];
+  };
+  /** Per-story metrics snapshot emitted when a story reaches a terminal state (Story 24-4) */
+  'story:metrics': {
+    storyKey: string;
+    wallClockMs: number;
+    phaseBreakdown: StoryPhaseBreakdown;
+    tokens: {
+      input: number;
+      output: number;
+    };
+    reviewCycles: number;
+    dispatches: number;
+  };
+  /** A pipeline phase has started (emitted by full pipeline path for NDJSON visibility) */
+  'pipeline:phase-start': {
+    phase: string;
+    ts: string;
+  };
+  /** A pipeline phase has completed (emitted by full pipeline path for NDJSON visibility) */
+  'pipeline:phase-complete': {
+    phase: string;
+    ts: string;
+  };
+  /** Pre-flight build check failed before any stories were dispatched */
+  'pipeline:pre-flight-failure': {
+    exitCode: number;
+    /** Build output (stdout+stderr), truncated to 2000 chars */
+    output: string;
+  };
+  /** Contract verification found a mismatch between declared export/import contracts */
+  'pipeline:contract-mismatch': {
+    /** Story key that declared the export for this contract */
+    exporter: string;
+    /** Story key that declared the import for this contract (null if no importer found) */
+    importer: string | null;
+    /** TypeScript interface or Zod schema name (e.g., "JudgeResult") */
+    contractName: string;
+    /** Human-readable description of the mismatch */
+    mismatchDescription: string;
+  };
+  /** Consolidated contract verification summary (emitted once per verification pass) */
+  'pipeline:contract-verification-summary': {
+    /** Number of contract declarations verified (current sprint only) */
+    verified: number;
+    /** Number of stale declarations pruned (from previous epics) */
+    stalePruned: number;
+    /** Number of real mismatches found */
+    mismatches: number;
+    /** 'pass' if zero mismatches, 'fail' otherwise */
+    verdict: 'pass' | 'fail';
+  };
+  /** Dolt merge conflict detected when merging a story branch into main */
+  'pipeline:state-conflict': {
+    storyKey: string;
+    conflict: unknown;
+  };
+  /**
+   * Emitted at pipeline startup when the repo-map symbol index is detected as stale.
+   */
+  'pipeline:repo-map-stale': {
+    /** SHA stored in the repo-map meta (last index update) */
+    storedSha: string;
+    /** Current HEAD commit SHA */
+    headSha: string;
+    /** Number of files in the stored index */
+    fileCount: number;
+  };
+  /** Project profile may be outdated relative to the actual project structure */
+  'pipeline:profile-stale': {
+    /** Human-readable message describing the staleness indicators found */
+    message: string;
+    /** List of staleness indicators detected */
+    indicators: string[];
+  };
+  /**
+   * Emitted when classifyAndPersist() successfully persists a finding from
+   * a failing story. Used by observability and monitoring consumers.
+   */
+  'pipeline:finding-captured': {
+    storyKey: string;
+    runId: string;
+    rootCause: string;
+  };
+  /**
+   * Emitted when a file overlap is detected between a pending story and a
+   * completed story, but no namespace collision exists. Dispatch proceeds
+   * normally after this event (non-blocking warning).
+   */
+  'pipeline:dispatch-warn': {
+    storyKey: string;
+    completedStoryKey: string;
+    overlappingFiles: string[];
+  };
+  /**
+   * Emitted when the dispatch gate cannot resolve a conflict and places the
+   * story in the `gated` phase for operator review. Dispatch does not proceed.
+   */
+  'pipeline:story-gated': {
+    storyKey: string;
+    conflictType: string;
+    reason: string;
+    completedStoryKey?: string;
+  };
+  /**
+   * Emitted after each individual verification check completes (pass, warn, or fail).
+   * AC5: payload matches VerificationCheckResult fields plus storyKey.
+   */
+  'verification:check-complete': {
+    storyKey: string;
+    checkName: string;
+    status: 'pass' | 'warn' | 'fail';
+    details: string;
+    duration_ms: number;
+  };
+  /**
+   * Emitted once per story after all verification checks have run.
+   * AC5: payload is the full VerificationSummary for the story.
+   */
+  'verification:story-complete': VerificationSummary;
+  /**
+   * Emitted when reconcile-from-disk successfully completes a reconciliation.
+   * Foundation primitive for Epic 70 / 73 automated Path A recovery.
+   */
+  'pipeline:reconcile-from-disk': {
+    runId: string;
+    /** Story keys that were transitioned to status='complete' */
+    affectedStories: string[];
+    /** Whether all validation gates passed before reconciling */
+    gatesPassed: boolean;
+    /** Whether the operator confirmed the reconciliation (false = --yes flag used) */
+    operatorConfirmed: boolean;
+    durationMs: number;
+  };
+  /**
+   * Emitted when a validation gate fails during reconcile-from-disk.
+   * No Dolt mutation occurs after this event.
+   */
+  'pipeline:reconcile-gate-failed': {
+    runId: string;
+    /** Name of the gate that failed (e.g. 'build', 'typecheck:gate', 'test:fast') */
+    failedGate: string;
+    /** Tail of subprocess stderr captured at gate failure (~64KB max, UTF-8) */
+    stderrTail?: string;
+    /** Tail of subprocess stdout captured at gate failure (~64KB max, UTF-8) */
+    stdoutTail?: string;
+    durationMs: number;
+  };
+}; //#endregion
+//#region packages/sdlc/dist/run-model/per-story-state.d.ts
+
+//# sourceMappingURL=events.d.ts.map
+/**
+ * Schema for a single per-story state entry in the run manifest.
+ *
+ * Field semantics:
+ * - `status`: High-level consumer-facing status (state-machine value). Use this
+ *   for state-machine decisions and display.
+ * - `phase`: Raw orchestrator `StoryPhase` string (e.g., `'IN_DEV'`, `'IN_REVIEW'`).
+ *   Informational only — do NOT compare this field in state-machine logic.
+ * - `started_at`: ISO-8601 timestamp when the story entered an active phase.
+ * - `completed_at`: ISO-8601 timestamp when the story reached a terminal state.
+ * - `verification_result`: Verification pipeline result (populated by story 52-7).
+ * - `cost_usd`: Accumulated cost in USD (populated at terminal transition).
+ */
+declare const PerStoryStateSchema: z.ZodObject<{
+  status: z.ZodUnion<readonly [z.ZodLiteral<"pending">, z.ZodLiteral<"dispatched">, z.ZodLiteral<"in-review">, z.ZodLiteral<"complete">, z.ZodLiteral<"failed">, z.ZodLiteral<"escalated">, z.ZodLiteral<"recovered">, z.ZodLiteral<"verification-failed">, z.ZodLiteral<"gated">, z.ZodLiteral<"skipped">, z.ZodLiteral<"verification-stale">, z.ZodString]>;
+  phase: z.ZodString;
+  started_at: z.ZodString;
+  completed_at: z.ZodOptional<z.ZodString>;
+  verification_result: z.ZodOptional<z.ZodObject<{
+    storyKey: z.ZodString;
+    checks: z.ZodArray<z.ZodObject<{
+      checkName: z.ZodString;
+      status: z.ZodEnum<{
+        warn: "warn";
+        pass: "pass";
+        fail: "fail";
+      }>;
+      details: z.ZodString;
+      duration_ms: z.ZodNumber;
+      findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        category: z.ZodString;
+        severity: z.ZodEnum<{
+          error: "error";
+          warn: "warn";
+          info: "info";
+        }>;
+        message: z.ZodString;
+        command: z.ZodOptional<z.ZodString>;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+        stdoutTail: z.ZodOptional<z.ZodString>;
+        stderrTail: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        _authoredBy: z.ZodOptional<z.ZodEnum<{
+          "probe-author": "probe-author";
+          "create-story-ac-transfer": "create-story-ac-transfer";
+        }>>;
+      }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    status: z.ZodEnum<{
+      warn: "warn";
+      pass: "pass";
+      fail: "fail";
+    }>;
+    duration_ms: z.ZodNumber;
+    annotations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      findingCategory: z.ZodString;
+      judgment: z.ZodEnum<{
+        "confirmed-defect": "confirmed-defect";
+        "false-positive": "false-positive";
+        "probe-bug": "probe-bug";
+      }>;
+      probeName: z.ZodOptional<z.ZodString>;
+      note: z.ZodOptional<z.ZodString>;
+      createdAt: z.ZodString;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>>;
+  cost_usd: z.ZodOptional<z.ZodNumber>;
+  review_cycles: z.ZodOptional<z.ZodNumber>;
+  dispatches: z.ZodOptional<z.ZodNumber>;
+  retry_count: z.ZodOptional<z.ZodNumber>;
+  dev_story_signals: z.ZodOptional<z.ZodObject<{
+    result: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"completed">, z.ZodLiteral<"failed">, z.ZodLiteral<"partial">, z.ZodString]>>;
+    ac_met: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ac_failures: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    files_modified: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tests: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"pass">, z.ZodLiteral<"fail">, z.ZodLiteral<"unknown">, z.ZodString]>>;
+  }, z.core.$strip>>;
+  probe_author_triggered_by: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"event-driven">, z.ZodLiteral<"state-integrating">, z.ZodLiteral<"both">, z.ZodString]>>;
+  verification_re_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type PerStoryState = z.infer<typeof PerStoryStateSchema>;
+
+//#endregion
+//#region packages/sdlc/dist/run-model/recovery-history.d.ts
+//# sourceMappingURL=per-story-state.d.ts.map
+/**
+ * A single recovery attempt recorded in the run manifest.
+ *
+ * `attempt_number` is 1-indexed: 1 = first retry, NOT the initial dispatch.
+ * The initial dispatch of a story is never recorded as a RecoveryEntry.
+ *
+ * `strategy` is free-form (e.g., `'retry-with-context'`, `'re-scope'`).
+ *
+ * `cost_usd` is the cost of THIS single retry attempt only — NOT cumulative.
+ * Cumulative per-story retry cost is tracked in `CostAccumulation.per_story`.
+ */
+declare const RecoveryEntrySchema: z.ZodObject<{
+  story_key: z.ZodString;
+  attempt_number: z.ZodNumber;
+  strategy: z.ZodString;
+  root_cause: z.ZodString;
+  outcome: z.ZodUnion<readonly [z.ZodLiteral<"retried">, z.ZodLiteral<"escalated">, z.ZodLiteral<"skipped">, z.ZodString]>;
+  cost_usd: z.ZodNumber;
+  timestamp: z.ZodString;
+}, z.core.$strip>;
+type RecoveryEntry = z.infer<typeof RecoveryEntrySchema>;
+/**
+ * Accumulated retry cost data for a pipeline run.
+ *
+ * `per_story` maps story_key → sum of all RecoveryEntry.cost_usd for that
+ * story. It does NOT include the initial dispatch cost, which is tracked in
+ * `PerStoryState.cost_usd`.
+ *
+ * `run_total` is the sum of all RecoveryEntry.cost_usd values in the run
+ * (i.e., total retry cost only, not total run cost).
+ *
+ * An empty `{ per_story: {}, run_total: 0 }` is the valid initial value.
+ */
+declare const CostAccumulationSchema: z.ZodObject<{
+  per_story: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  run_total: z.ZodNumber;
+}, z.core.$strip>;
+type CostAccumulation = z.infer<typeof CostAccumulationSchema>;
+
+//#endregion
+//#region packages/sdlc/dist/run-model/types.d.ts
+//# sourceMappingURL=recovery-history.d.ts.map
+/**
+ * A pending supervisor proposal awaiting user confirmation.
+ */
+interface Proposal {
+  /** Unique proposal ID. */
+  id: string;
+  /** ISO-8601 timestamp when the proposal was created. */
+  created_at: string;
+  /** Short description of what is being proposed. */
+  description: string;
+  /** Proposal type (e.g. 'retry', 'fix', 'escalate'). */
+  type: string;
+  /** Story key this proposal pertains to, if any (snake_case legacy field). */
+  story_key?: string;
+  /** Additional payload data for the proposal. */
+  payload?: Record<string, unknown>;
+  /** Story key this proposal pertains to (camelCase, Recovery Engine primary). */
+  storyKey?: string;
+  /** Root cause classification for the failure (e.g. 'scope-violation'). */
+  rootCause?: string;
+  /** Number of retry attempts made before proposing. */
+  attempts?: number;
+  /** Human-readable suggested action for the operator. */
+  suggestedAction?: string;
+  /** Keys of stories that share files with this story (blast radius). */
+  blastRadius?: string[];
+}
+/**
+ * Full data shape for a run manifest stored on disk.
+ *
+ * All fields are required; optional values use `null`.
+ * `per_story_state` is typed as `Record<string, PerStoryState>` (story 52-4).
+ * Each key is a story key (e.g., '52-1'); the value tracks full per-story
+ * lifecycle state for manifest consumers across Epics 52–54.
+ */
+interface RunManifestData {
+  /** Unique run identifier (UUID). */
+  run_id: string;
+  /** CLI flags used to start this run. */
+  cli_flags: Record<string, unknown>;
+  /** Explicit story scope (empty = all pending stories). */
+  story_scope: string[];
+  /**
+   * Pipeline run status. Authoritative source — Dolt `pipeline_runs.status`
+   * is the degraded fallback. Consumers MUST read this field first.
+   */
+  run_status?: 'running' | 'completed' | 'failed' | 'stopped';
+  /**
+   * Number of supervisor-triggered restarts for this run.
+   * Authoritative source — Dolt `run_metrics.restarts` is the degraded fallback.
+   */
+  restart_count?: number;
+  /** PID of the attached supervisor process, or null if none. */
+  supervisor_pid: number | null;
+  /** Session ID of the supervisor process, or null if none. */
+  supervisor_session_id: string | null;
+  /** Per-story state keyed by story key (story 52-4). */
+  per_story_state: Record<string, PerStoryState>;
+  /** Log of recovery attempts for this run (Story 52-8). */
+  recovery_history: RecoveryEntry[];
+  /** Accumulated retry cost data (Story 52-8). */
+  cost_accumulation: CostAccumulation;
+  /** Pending proposals awaiting confirmation. */
+  pending_proposals: Proposal[];
+  /**
+   * Human-readable reason the run was stopped (e.g. 'killed_by_user').
+   * Set by the SIGTERM/SIGINT handler (Story 58-7). Absent on pre-58-7 manifests.
+   */
+  stopped_reason?: string;
+  /**
+   * ISO-8601 timestamp when the run was stopped.
+   * Set by the SIGTERM/SIGINT handler (Story 58-7). Absent on pre-58-7 manifests.
+   */
+  stopped_at?: string;
+  /**
+   * Monotonic write counter. Incremented on every successful `write()`.
+   * Used to detect which file is newer after a mid-rename crash.
+   */
+  generation: number;
+  /** ISO-8601 timestamp when the manifest was first created. */
+  created_at: string;
+  /** ISO-8601 timestamp of the most recent write. */
+  updated_at: string;
+}
+
+//#endregion
+//#region packages/sdlc/dist/run-model/cli-flags.d.ts
+//# sourceMappingURL=types.d.ts.map
+/**
+ * Zod schema for the CLI flags persisted in the run manifest.
+ *
+ * All fields are optional — only flags explicitly provided on the CLI are written.
+ * `halt_on` defaults to `'none'` at write time; `cost_ceiling` is omitted when not provided.
+ */
+declare const CliFlagsSchema: z.ZodObject<{
+  stories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  halt_on: z.ZodOptional<z.ZodEnum<{
+    none: "none";
+    all: "all";
+    critical: "critical";
+  }>>;
+  cost_ceiling: z.ZodOptional<z.ZodNumber>;
+  agent: z.ZodOptional<z.ZodString>;
+  skip_verification: z.ZodOptional<z.ZodBoolean>;
+  events: z.ZodOptional<z.ZodBoolean>;
+  non_interactive: z.ZodOptional<z.ZodBoolean>;
+  halt_skipped: z.ZodOptional<z.ZodBoolean>;
+  halt_skipped_decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    decisionType: z.ZodString;
+    severity: z.ZodString;
+    defaultAction: z.ZodString;
+    reason: z.ZodString;
+    skippedAt: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strip>;
+type CliFlags = z.infer<typeof CliFlagsSchema>;
+
+//#endregion
+//#region packages/sdlc/dist/run-model/run-manifest.d.ts
+//# sourceMappingURL=cli-flags.d.ts.map
+/**
+ * Minimal interface for Dolt query access needed by the degraded-mode fallback.
+ * Consumers inject a real `DatabaseAdapter` (from @substrate-ai/core) or null.
+ */
+interface IDoltAdapter {
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/**
+ * Typed, atomic file-backed run manifest.
+ *
+ * Each instance is bound to a specific run ID and base directory.
+ * Use `RunManifest.create()` to initialize a new manifest,
+ * or `RunManifest.read()` to load an existing one.
+ */
+declare class RunManifest {
+  readonly runId: string;
+  readonly baseDir: string;
+  /** Optional Dolt adapter for degraded-mode fallback on read. */
+  private doltAdapter;
+  /**
+   * Serializes all write operations on this instance to prevent lost-update races.
+   * Initialized to a resolved promise; each enqueued operation chains off the tail.
+   */
+  private _writeChain;
+  constructor(runId: string, baseDir?: string, doltAdapter?: IDoltAdapter | null);
+  get primaryPath(): string;
+  get bakPath(): string;
+  get tmpPath(): string;
+  /**
+   * Read this manifest from disk (multi-tier fallback).
+   *
+   * Delegates to `RunManifest.read()` with this instance's runId, baseDir,
+   * and doltAdapter. Primarily used by `SupervisorLock` (and tests that mock it).
+   *
+   * @throws ManifestReadError if all sources fail
+   */
+  read(): Promise<RunManifestData>;
+  /**
+   * Atomically update specific fields in the manifest.
+   *
+   * Reads the current manifest, merges in the provided partial data (shallow
+   * merge), then writes the result atomically. Generation is incremented and
+   * `updated_at` is refreshed by `write()`.
+   *
+   * Callers should pass only the fields they intend to change. Do NOT use this
+   * to change `run_id` or `created_at` — those are immutable after creation.
+   *
+   * @throws ManifestReadError if the current manifest cannot be read
+   */
+  update(partial: Partial<Omit<RunManifestData, 'generation' | 'updated_at'>>): Promise<void>;
+  /**
+   * Append `fn` to the per-instance write chain so all write operations execute
+   * strictly sequentially, preventing lost-update races on concurrent callers.
+   *
+   * The chain itself never rejects (errors are swallowed on the chain side);
+   * the returned promise resolves or rejects exactly when `fn` settles, so
+   * fire-and-forget `.catch()` callers still receive failure signals.
+   */
+  private _enqueue;
+  /**
+   * Raw implementation of the atomic manifest write.
+   * Must only be called from within an `_enqueue`-d function to maintain
+   * the serialization invariant.
+   *
+   * Sequence:
+   *   1. Auto-increment `generation`, set `updated_at`
+   *   2. Serialize to JSON and validate round-trip
+   *   3. Ensure baseDir exists (mkdir -p)
+   *   4. Write to `.tmp` via open → write → datasync → close (fsync)
+   *   5. If primary exists, copy to `.bak`
+   *   6. Rename `.tmp` → primary path
+   */
+  private _writeImpl;
+  /**
+   * Atomically write the manifest to disk.
+   *
+   * Enqueues the write via `_enqueue` so concurrent calls are serialized.
+   * The returned promise resolves when this call's write completes.
+   */
+  write(data: Omit<RunManifestData, 'generation' | 'updated_at'>): Promise<void>;
+  /**
+   * Return a bound `RunManifest` instance without performing any file I/O.
+   *
+   * Use `open()` when you want to call instance methods (`read()`, `patchCLIFlags()`)
+   * on an existing run without reading the manifest upfront.
+   *
+   * ```typescript
+   * await RunManifest.open(runId, runsDir).patchCLIFlags(cliFlags)
+   * ```
+   */
+  static open(runId: string, baseDir?: string, doltAdapter?: IDoltAdapter | null): RunManifest;
+  /**
+   * Raw implementation — must only be called from within `_enqueue`.
+   */
+  private _patchCLIFlagsImpl;
+  /**
+   * Read the current manifest (or create a minimal default), merge the provided
+   * CLI flags into `cli_flags`, and write the result atomically.
+   *
+   * Enqueues the operation via `_enqueue` so concurrent calls are serialized.
+   * Non-fatal: callers should wrap in try/catch and log a warning on failure.
+   * The pipeline must not abort if manifest write fails.
+   */
+  patchCLIFlags(flags: CliFlags): Promise<void>;
+  /**
+   * Raw implementation — must only be called from within `_enqueue`.
+   */
+  private _patchStoryStateImpl;
+  /**
+   * Atomically upsert the per-story lifecycle state for a single story key.
+   *
+   * Reads the current manifest (or creates a minimal default if absent),
+   * shallowly merges `updates` into `per_story_state[storyKey]`, and writes
+   * the result atomically via a single `write()` call.
+   *
+   * Fields not included in `updates` on an existing entry are preserved unchanged.
+   *
+   * Enqueues the operation via `_enqueue` so concurrent calls are serialized.
+   * Non-fatal: callers MUST wrap in `.catch((err) => logger.warn(...))`.
+   * The pipeline must never abort due to a manifest write failure.
+   *
+   * @param storyKey - Story key (e.g. '52-4')
+   * @param updates  - Partial PerStoryState fields to merge
+   */
+  patchStoryState(storyKey: string, updates: Partial<PerStoryState>): Promise<void>;
+  /**
+   * Raw implementation — must only be called from within `_enqueue`.
+   */
+  private _patchRunStatusImpl;
+  /**
+   * Atomically update the run-level status fields in the manifest.
+   *
+   * Reads the current manifest (or creates a minimal default if absent),
+   * merges the provided status updates at the top level, and writes the
+   * result atomically via a single `write()` call.
+   *
+   * Enqueues the operation via `_enqueue` so concurrent calls are serialized
+   * (preserves the single-writer guarantee from Epic 57-1).
+   * Non-fatal: callers MUST wrap in `.catch((err) => logger.warn(...))`.
+   *
+   * @param updates - Top-level status fields to merge (run_status, stopped_reason, stopped_at)
+   */
+  patchRunStatus(updates: {
+    run_status?: RunManifestData['run_status'];
+    stopped_reason?: string;
+    stopped_at?: string;
+  }): Promise<void>;
+  /**
+   * Raw implementation — must only be called from within `_enqueue`.
+   */
+  private _appendRecoveryEntryImpl;
+  /**
+   * Atomically append a recovery entry and update cost accumulation.
+   *
+   * Reads the current manifest, appends `entry` to `recovery_history[]`,
+   * increments `cost_accumulation.per_story[entry.story_key]` by `entry.cost_usd`,
+   * increments `cost_accumulation.run_total` by `entry.cost_usd`, then writes
+   * atomically via a single `write()` call.
+   *
+   * Enqueues the operation via `_enqueue` so concurrent calls are serialized.
+   * Non-fatal: callers MUST wrap in `.catch((err) => logger.warn(...))`.
+   * The pipeline must never abort due to a manifest write failure.
+   *
+   * `entry.cost_usd` is the cost of this single retry attempt only (NOT cumulative).
+   * Cumulative per-story retry cost is tracked in `cost_accumulation.per_story`.
+   *
+   * @param entry - Recovery entry to append (attempt_number is 1-indexed)
+   */
+  appendRecoveryEntry(entry: RecoveryEntry): Promise<void>;
+  /**
+   * Raw implementation — must only be called from within `_enqueue`.
+   */
+  private _appendProposalImpl;
+  /**
+   * Atomically append a proposal to `pending_proposals`, deduplicating by storyKey.
+   *
+   * If a proposal with the same `storyKey` (or `story_key`) is already present in
+   * `pending_proposals`, the call is a silent no-op (idempotent). This guards
+   * against duplicate proposals from concurrent or repeated recovery invocations.
+   *
+   * Enqueues the operation via `_enqueue` so concurrent calls are serialized.
+   * Non-fatal: callers MUST wrap in `.catch((err) => logger.warn(...))`.
+   * The pipeline must never abort due to a manifest write failure.
+   *
+   * Story 73-1 (Recovery Engine). Canonical manifest helper per AC3.
+   *
+   * @param proposal - Proposal to append (id, created_at, description, type + Epic 73 fields)
+   */
+  appendProposal(proposal: Proposal): Promise<void>;
+  /**
+   * Create a new manifest with `generation: 0` and write it.
+   * Returns a bound `RunManifest` instance.
+   */
+  static create(runId: string, initialData: Omit<RunManifestData, 'generation' | 'updated_at' | 'created_at'>, baseDir?: string, doltAdapter?: IDoltAdapter | null): Promise<RunManifest>;
+  /**
+   * Read a manifest from disk with multi-tier fallback.
+   *
+   * Attempts sources in order:
+   *   1. Primary `.json`
+   *   2. Backup `.json.bak`  (preferred over primary if generation is higher)
+   *   3. Temporary `.json.tmp`
+   *   4. Dolt degraded reconstruction (if doltAdapter is provided)
+   *
+   * Generation tiebreak: if `.bak` has a higher `generation` than primary,
+   * `.bak` is preferred (indicates primary was overwritten mid-rename).
+   *
+   * @throws ManifestReadError if all sources fail
+   */
+  static read(runId: string, baseDir?: string, doltAdapter?: IDoltAdapter | null): Promise<RunManifestData>;
+}
+
+//#endregion
+//#region src/modules/recovery-engine/index.d.ts
+//# sourceMappingURL=run-manifest.d.ts.map
+/**
+ * Failure information passed to the Recovery Engine.
+ */
+interface RecoveryFailure {
+  /** Root cause classification (e.g. 'build-failure', 'scope-violation'). */
+  rootCause: string;
+  /** Raw findings from the verification summary. */
+  findings?: unknown[];
+  /** Narrative diagnosis text to prepend to the retry prompt (Tier A). */
+  diagnosis?: string;
+}
+/**
+ * Retry budget for the current story.
+ */
+interface RecoveryBudget {
+  /** Remaining retry attempts. 0 = budget exhausted. */
+  remaining: number;
+  /** Maximum retry attempts configured for this run. */
+  max: number;
+}
+/**
+ * Input for `runRecoveryEngine`.
+ * Modelled on StaleVerificationRecoveryInput from cross-story-race-recovery.ts (Epic 70).
+ */
+interface RecoveryEngineInput {
+  /** Run ID for event emission and manifest access. */
+  runId: string;
+  /** Story key that failed. */
+  storyKey: string;
+  /** Failure information (root cause, findings, diagnosis). */
+  failure: RecoveryFailure;
+  /** Retry budget for the current story. */
+  budget: RecoveryBudget;
+  /** Typed event bus for emitting recovery lifecycle events. */
+  bus: TypedEventBus<SdlcEvents>;
+  /** RunManifest instance for state reads and writes. */
+  manifest: RunManifest;
+  /**
+   * Database adapter for Dolt persistence and work-graph dependency queries.
+   * Used by back-pressure logic to query story_dependencies.
+   */
+  adapter: DatabaseAdapter;
+  /**
+   * Engine mode — 'linear' disables work-graph dependency resolution and pauses
+   * all pending dispatches when >= 2 proposals exist.
+   */
+  engine?: 'linear' | 'graph';
+  /**
+   * Keys of stories still pending/dispatched at the time of recovery invocation.
+   * Used by back-pressure logic to compute pause/continue sets.
+   */
+  pendingStoryKeys?: string[];
+}
+/**
+ * Discriminated result union returned by `runRecoveryEngine`.
+ * The orchestrator reads this result and acts accordingly (AC9).
+ */
+type RecoveryEngineResult = {
+  /** Tier A: re-dispatch with enriched prompt. */
+  action: 'retry';
+  attempt: number;
+  retryBudgetRemaining: number;
+  /** Enriched prompt with diagnosis + findings prepended (ready for dispatcher). */
+  enrichedPrompt?: string;
+} | {
+  /** Tier B: re-scope proposal appended. Apply back-pressure. */
+  action: 'propose';
+  storyKey: string;
+  pendingProposalsCount: number;
+  /** Story keys whose dispatch should be paused (depend on a proposed story). */
+  pause?: string[];
+  /** Story keys that can continue (independent of proposed stories). */
+  continue?: string[];
+  /** When true (linear mode): pause ALL remaining dispatches. */
+  pauseAll?: boolean;
+} | {
+  /** Tier C: operator intervention required (Decision Router / Story 73-2 prompt). */
+  action: 'halt';
+} | {
+  /** Safety valve: >= 5 proposals — halt the entire run (exit 1). */
+  action: 'halt-entire-run';
+  pendingProposalsCount: number;
+};
+/**
+ * Classify a failure into a recovery action tier.
+ *
+ * Pure function — no imports from I/O modules, no side effects.
+ * The action handler (`runRecoveryEngine`) owns all I/O.
+ *
+ * Classification rules:
+ *   1. HALT root causes → 'halt' always
+ *   2. PROPOSE root causes → 'propose' always (structural, not retry-able)
+ *   3. RETRY root causes:
+ *      - budget.remaining > 0 → 'retry'
+ *      - budget.remaining <= 0 → 'propose' (exhausted, escalate)
+ *   4. Unknown root cause → 'propose' (safe default)
+ *
+ * @param failure - Failure with rootCause field
+ * @param budget  - Retry budget with remaining count
+ * @returns 'retry' | 'propose' | 'halt'
+ */
+declare function classifyRecoveryAction(failure: Pick<RecoveryFailure, 'rootCause'>, budget: RecoveryBudget): 'retry' | 'propose' | 'halt';
+/**
+ * Recovery Engine action handler.
+ *
+ * Consumes a halt decision (failure + budget) and applies tiered recovery:
+ *
+ *   Tier A (retry): emits recovery:tier-a-retry, returns enriched prompt for re-dispatch.
+ *   Tier B (propose): appends Proposal to RunManifest.pending_proposals, applies back-pressure.
+ *   Tier C (halt): emits recovery:tier-c-halt, returns halt action for Decision Router.
+ *
+ * Safety valve: if pending_proposals.length >= 5 after any Tier B append,
+ * emits pipeline:halted-pending-proposals and returns halt-entire-run.
+ *
+ * Back-pressure:
+ *   >= 2 proposals + work graph: pauses dependent stories, continues independent ones.
+ *   >= 2 proposals + linear mode: pauses ALL remaining dispatches.
+ *
+ * Idempotency: re-invoking on a story already in pending_proposals is a no-op
+ * (handled inside RunManifest.appendProposal via storyKey deduplication).
+ *
+ * Canonical helper discipline: all manifest reads/writes via RunManifest class.
+ * No direct JSON file access. No new aggregate manifest formats.
+ *
+ * @param input - Recovery engine input (see RecoveryEngineInput)
+ * @returns Recovery action result for the orchestrator to act on
+ */
+declare function runRecoveryEngine(input: RecoveryEngineInput): Promise<RecoveryEngineResult>;
+
+//#endregion
+//# sourceMappingURL=index.d.ts.map
+
+export { RecoveryBudget, RecoveryEngineInput, RecoveryEngineResult, RecoveryFailure, classifyRecoveryAction, runRecoveryEngine };
+//# sourceMappingURL=index.d.ts.map