stageflow 0.8.0 → 0.12.0

package/dist/mcp/controlTools.js

@@ -3,6 +3,7 @@ import { mapRetryStageFailure, mapStartFailure, } from "../server/operatorResult
 import { parseAskOperatorAnswer } from "../tools/askOperator.js";
 import { textResult } from "./toolResults.js";
 import { projectWaitingGates } from "./waitingGates.js";
+import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 export function registerControlTools(server, deps) {
     const { manager, store } = deps;
     server.registerTool("list_waiting", {
@@ -36,6 +37,30 @@ export function registerControlTools(server, deps) {
         }
         return textResult({ ok: true });
     });
+    server.registerTool("decide_feedback_loop", {
+        description: "Resolve a feedback-loop wait_for_human decision (extend, continue, or abandon). Same semantics as POST /api/runs/:id/stages/:stageId/feedback-decision.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+            decision: z.enum(["extend", "continue", "abandon"]),
+            loopId: z.string().optional(),
+            reason: z.string().optional(),
+        }),
+    }, async ({ runId, stageId, decision, loopId, reason }) => {
+        const result = await manager.decideFeedbackLoop(runId, stageId, {
+            decision,
+            ...(loopId !== undefined ? { loopId } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+        });
+        if (!result.ok) {
+            return textResult({ error: result.reason, status: result.status }, true);
+        }
+        return textResult({
+            ok: true,
+            effect: result.effect,
+            loopId: result.loopId,
+        });
+    });
     server.registerTool("list_stage_events", {
         description: "List persisted stage log events for a run stage (optional attempt filter). Prefer over bloating get_run.",
         inputSchema: z.object({
@@ -66,6 +91,53 @@ export function registerControlTools(server, deps) {
             return textResult({ error: message, status: notFound ? 404 : 500 }, true);
         }
     });
+    server.registerTool("get_stage_verification", {
+        description: "Read every execution attempt for a stage, including durable completion-check results and their evidence. Use this to understand an automatic repair or a failed verification.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        try {
+            return textResult(await readStageVerificationHistory(store, runId, stageId));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const notFound = /not found|no such/i.test(message);
+            return textResult({ error: message, status: notFound ? 404 : 500 }, true);
+        }
+    });
+    server.registerTool("recover_manual_stage", {
+        description: "Explicitly approve one fresh attempt for a manual-recovery stage after a completion verification failure. Optional guidance is recorded and supplied to the agent with the failed-check evidence.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+            guidance: z.string().max(4_000).optional(),
+        }),
+    }, async ({ runId, stageId, guidance }) => {
+        const result = await manager.recoverManualStage(runId, stageId, guidance);
+        if (!result.ok) {
+            return textResult({ ...mapRetryStageFailure(result), status: result.status }, true);
+        }
+        return textResult({
+            runId: result.runId,
+            stageId: result.stageId,
+            attemptIndex: result.attemptIndex,
+        });
+    });
+    server.registerTool("stop_manual_recovery", {
+        description: "Record the operator's decision to leave a manual-recovery stage failed. This is terminal for that stage; start a fresh run to try again later.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        const result = await manager.stopManualRecovery(runId, stageId);
+        if (!result.ok) {
+            return textResult({ error: result.reason, status: result.status }, true);
+        }
+        return textResult(result);
+    });
     server.registerTool("get_envelope", {
         description: "Read the full StageEnvelope for a run stage (latest attempt). Returns 404 when absent.",
         inputSchema: z.object({

package/dist/mcp/waitingGates.d.ts

@@ -1,10 +1,11 @@
-import type { RunStore, RunSummary, StageSnapshot } from "../runstore/port.js";
+import type { RunDetail, RunStore, RunSummary, StageSnapshot } from "../runstore/port.js";
 type WaitingSummarySource = Pick<RunSummary, "run_id" | "waiting_stage_id" | "waiting_stage_ids" | "waiting_kind" | "waiting_summary" | "waiting_prompt_id" | "waiting_artifacts" | "waiting_questions">;
 export declare function projectWaitingGate(opts: {
     runId: string;
     stageId: string;
     stage: StageSnapshot;
     summary: WaitingSummarySource;
+    activeFeedbackLoop?: RunDetail["active_feedback_loop"];
 }): Record<string, unknown>;
 export declare function projectWaitingGates(store: RunStore, opts?: {
     runId?: string;

package/dist/mcp/waitingGates.js

@@ -1,5 +1,5 @@
 export function projectWaitingGate(opts) {
-    const { runId, stageId, stage, summary } = opts;
+    const { runId, stageId, stage, summary, activeFeedbackLoop } = opts;
     const prompt = stage.pending_prompt;
     const item = {
         runId,
@@ -36,6 +36,21 @@ export function projectWaitingGate(opts) {
             item.waiting_questions = summary.waiting_questions;
         }
     }
+    if ((item.waiting_kind === "feedback_loop_decision" ||
+        activeFeedbackLoop?.state === "waiting_for_human") &&
+        activeFeedbackLoop !== undefined) {
+        item.feedback_loop_id = activeFeedbackLoop.loop_id;
+        if (activeFeedbackLoop.deferred_send_back?.target !== undefined) {
+            item.deferred_target = activeFeedbackLoop.deferred_send_back.target;
+        }
+        if (item.waiting_kind === undefined) {
+            item.waiting_kind = "feedback_loop_decision";
+        }
+        if (item.waiting_summary === undefined) {
+            item.waiting_summary =
+                "Feedback loop limit reached — extend, continue, or abandon";
+        }
+    }
     return item;
 }
 function projectGatesForRun(detail, summary) {
@@ -51,6 +66,7 @@ function projectGatesForRun(detail, summary) {
             stageId,
             stage,
             summary,
+            activeFeedbackLoop: detail.active_feedback_loop,
         }));
     }
     return items;

package/dist/package-meta.d.ts

@@ -1 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
+export declare const PACKAGE_VERSION = "0.12.0";

package/dist/package-meta.js

@@ -1 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
+export const PACKAGE_VERSION = "0.12.0";

package/dist/projection/projectRun.d.ts

@@ -1,4 +1,4 @@
-import type { RunDetail, StageSnapshot } from "../runstore/port.js";
+import type { FeedbackLoopHistory, FeedbackLoopRecord, RunDetail, StageSnapshot } from "../runstore/port.js";
 import type { PipelineTrackProjection, RunSummary } from "../runstore/port.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
@@ -13,6 +13,7 @@ export type StageProjection = {
         payload?: Record<string, unknown>;
         fork_choice?: string[];
         clone_forks?: CloneForkItem[];
+        feedback_loop?: StageEnvelope["feedback_loop"];
     } | null;
     artifacts: string[];
     last_at?: string;
@@ -39,6 +40,8 @@ export type RunProjection = {
     waiting_questions?: RunSummary["waiting_questions"];
     failed_stage_id?: RunSummary["failed_stage_id"];
     failed_reason?: RunSummary["failed_reason"];
+    active_feedback_loop?: FeedbackLoopRecord;
+    feedback_loops: FeedbackLoopHistory[];
 };
 export declare function projectRun(detail: RunDetail): RunProjection;
 export { projectRun as projectRunForMcp };

package/dist/projection/projectRun.js

@@ -41,6 +41,10 @@ export function projectRun(detail) {
         ...(detail.failed_reason !== undefined
             ? { failed_reason: detail.failed_reason }
             : {}),
+        ...(detail.active_feedback_loop !== undefined
+            ? { active_feedback_loop: detail.active_feedback_loop }
+            : {}),
+        feedback_loops: detail.feedback_loops ?? [],
         stages: detail.stages.map((stage) => ({
             stage_id: stage.stage_id,
             status: stage.status,
@@ -58,6 +62,9 @@ export function projectRun(detail) {
                     ...(stage.envelope.clone_forks !== undefined
                         ? { clone_forks: stage.envelope.clone_forks }
                         : {}),
+                    ...(stage.envelope.feedback_loop !== undefined
+                        ? { feedback_loop: stage.envelope.feedback_loop }
+                        : {}),
                 }
                 : null,
             artifacts: stage.artifacts,

package/dist/prompt/feedbackLoopContext.d.ts

@@ -0,0 +1,2 @@
+import type { FeedbackLoopContext, StageSessionMode } from "../agent/port.js";
+export declare function formatFeedbackLoopContext(ctx: FeedbackLoopContext, sessionMode?: StageSessionMode): string;

package/dist/prompt/feedbackLoopContext.js

@@ -0,0 +1,17 @@
+function resolveFeedbackSessionMode(ctx, sessionMode) {
+    if (sessionMode === "new_session" || sessionMode === "feedback_resume") {
+        return sessionMode;
+    }
+    return ctx.replay_session === "new_session" ? "new_session" : "feedback_resume";
+}
+export function formatFeedbackLoopContext(ctx, sessionMode) {
+    const mode = resolveFeedbackSessionMode(ctx, sessionMode);
+    const continuity = mode === "new_session"
+        ? "starting a fresh agent session"
+        : "continuing the prior agent session";
+    return [
+        "Feedback Loop Context:",
+        `Session mode: ${mode} (${continuity})`,
+        JSON.stringify(ctx, null, 2),
+    ].join("\n");
+}

package/dist/prompt/priorEnvelope.d.ts

@@ -1,2 +1,2 @@
-import type { StageEnvelope } from "../types/envelope.js";
-export declare function formatPriorEnvelope(priorEnvelope: StageEnvelope | null, priorEnvelopes?: StageEnvelope[]): string;
+import type { StageEnvelope, TerminalEnvelope } from "../types/envelope.js";
+export declare function formatPriorEnvelope(priorEnvelope: StageEnvelope | null, priorEnvelopes?: StageEnvelope[], priorEnvelopesByStage?: Record<string, TerminalEnvelope | TerminalEnvelope[]>): string;

package/dist/prompt/priorEnvelope.js

@@ -1,4 +1,7 @@
-export function formatPriorEnvelope(priorEnvelope, priorEnvelopes) {
+export function formatPriorEnvelope(priorEnvelope, priorEnvelopes, priorEnvelopesByStage) {
+    if (priorEnvelopesByStage !== undefined) {
+        return `Prior envelopes by stage (declaration order):\n${JSON.stringify(priorEnvelopesByStage, null, 2)}`;
+    }
     if (priorEnvelopes !== undefined && priorEnvelopes.length > 0) {
         return `Prior envelopes (${priorEnvelopes.length} clones, clone-list order):\n${JSON.stringify(priorEnvelopes, null, 2)}`;
     }

package/dist/runstore/pipelineDagSnapshot.d.ts

@@ -8,6 +8,7 @@ export declare function appendCloneInstances(snapshot: RunPipelineDagSnapshot, i
     catalogId: string;
     predecessorId: string;
     count: number;
+    startAt?: number;
 }): {
     snapshot: RunPipelineDagSnapshot;
     instanceIds: string[];

package/dist/runstore/pipelineDagSnapshot.js

@@ -1,10 +1,15 @@
+import { hydrateResolvedNeeds } from "../config/pipelineNeeds.js";
 import { mintCloneInstanceIds } from "./stageInstanceId.js";
 export function buildPipelineDagSnapshotFromLoaded(loaded) {
     const gate_kinds = {};
+    const clone_input_schema = {};
     for (const stage of loaded.stages) {
-        if (stage.gate_kinds?.length) {
+        if (stage.gate_kinds !== undefined) {
             gate_kinds[stage.id] = stage.gate_kinds;
         }
+        if (stage.clone_input_schema !== undefined) {
+            clone_input_schema[stage.id] = stage.clone_input_schema;
+        }
     }
     return {
         stage_ids: [...loaded.pipeline.stages],
@@ -15,12 +20,16 @@ export function buildPipelineDagSnapshotFromLoaded(loaded) {
         roots: loaded.dag.roots,
         childrenOf: loaded.dag.childrenOf,
         ...(Object.keys(gate_kinds).length > 0 ? { gate_kinds } : {}),
+        ...(Object.keys(clone_input_schema).length > 0
+            ? { clone_input_schema }
+            : {}),
     };
 }
 export function linearCompatDagSnapshot(stageIds) {
     const nodes = stageIds.map((id, index) => ({
         id,
         needs: index === 0 ? null : stageIds[index - 1],
+        needsEdges: index === 0 ? [] : [{ id: stageIds[index - 1], on: ["succeeded"] }],
         ancestors: index === 0 ? [] : stageIds.slice(0, index),
         stageIndex: index,
         definition_id: id,
@@ -44,7 +53,14 @@ export function parsePipelineDagSnapshot(raw) {
     const value = raw;
     if (!Array.isArray(value.stage_ids) || !Array.isArray(value.nodes))
         return null;
-    return raw;
+    const nodes = value.nodes.map((node) => {
+        if (!node || typeof node !== "object")
+            return node;
+        const record = node;
+        const hydrated = hydrateResolvedNeeds(record);
+        return { ...record, ...hydrated };
+    });
+    return { ...raw, nodes };
 }
 export function instancesOfDefinition(snapshot, catalogId) {
     const nodeById = new Map(snapshot.nodes.map((n) => [n.id, n]));
@@ -54,15 +70,24 @@ export function instancesOfDefinition(snapshot, catalogId) {
     });
 }
 export function appendCloneInstances(snapshot, input) {
-    const { catalogId, predecessorId, count } = input;
-    if (!snapshot.stage_ids.includes(catalogId)) {
+    const { catalogId, predecessorId, count, startAt } = input;
+    // A catalog id that's already been fanned out once is no longer present as
+    // its own stage_ids entry — it was replaced by its instances. Minting
+    // *more* instances for it (a retried fanout requesting a larger clone
+    // count) is still valid as long as those instances exist.
+    const existingInstanceIdxs = snapshot.stage_ids
+        .map((id, i) => [id, i])
+        .filter(([id]) => id !== catalogId && id.startsWith(`${catalogId}~`))
+        .map(([, i]) => i);
+    const catalogIdx = snapshot.stage_ids.indexOf(catalogId);
+    if (catalogIdx === -1 && existingInstanceIdxs.length === 0) {
         throw new Error(`catalog stage "${catalogId}" is not in the run DAG snapshot`);
     }
     const predNode = snapshot.nodes.find((n) => n.id === predecessorId);
     if (!predNode) {
         throw new Error(`predecessor "${predecessorId}" is not in the run DAG snapshot`);
     }
-    const instanceIds = mintCloneInstanceIds(catalogId, count);
+    const instanceIds = mintCloneInstanceIds(catalogId, count, startAt);
     for (const id of instanceIds) {
         if (snapshot.stage_ids.includes(id) ||
             snapshot.nodes.some((n) => n.id === id)) {
@@ -70,22 +95,37 @@ export function appendCloneInstances(snapshot, input) {
         }
     }
     const catalogNode = snapshot.nodes.find((n) => n.id === catalogId);
-    if (!catalogNode) {
+    const templateNode = catalogNode ?? snapshot.nodes.find((n) => n.definition_id === catalogId);
+    if (!templateNode) {
         throw new Error(`catalog stage "${catalogId}" is not in the run DAG snapshot`);
     }
-    const catalogIdx = snapshot.stage_ids.indexOf(catalogId);
+    const insertAt = catalogIdx !== -1 ? catalogIdx : Math.max(...existingInstanceIdxs) + 1;
+    const removeAt = catalogIdx !== -1 ? catalogIdx + 1 : insertAt;
     const stage_ids = [
-        ...snapshot.stage_ids.slice(0, catalogIdx),
+        ...snapshot.stage_ids.slice(0, insertAt),
         ...instanceIds,
-        ...snapshot.stage_ids.slice(catalogIdx + 1),
+        ...snapshot.stage_ids.slice(removeAt),
     ];
     const instanceNodes = instanceIds.map((id) => ({
         id,
         definition_id: catalogId,
         needs: predecessorId,
+        needsEdges: [{ id: predecessorId, on: ["succeeded"] }],
         ancestors: [...predNode.ancestors, predecessorId],
         stageIndex: 0,
-        ...(catalogNode.fork !== undefined ? { fork: catalogNode.fork } : {}),
+        ...(templateNode.fork !== undefined ? { fork: templateNode.fork } : {}),
+        ...(templateNode.completion !== undefined
+            ? { completion: templateNode.completion }
+            : {}),
+        ...(templateNode.recovery !== undefined
+            ? { recovery: templateNode.recovery }
+            : {}),
+        ...(templateNode.feedback_loop !== undefined
+            ? { feedback_loop: templateNode.feedback_loop }
+            : {}),
+        ...(templateNode.replay_safe !== undefined
+            ? { replay_safe: templateNode.replay_safe }
+            : {}),
     }));
     const remaining = new Map(snapshot.nodes
         .filter((n) => n.id !== catalogId)
@@ -112,7 +152,7 @@ export function appendCloneInstances(snapshot, input) {
                 ...instanceIds,
                 ...predChildren.slice(predIdx + 1),
             ];
-    const definitionParent = catalogNode.needs;
+    const definitionParent = catalogNode?.needs;
     if (definitionParent && definitionParent !== predecessorId) {
         const parentChildren = childrenOf[definitionParent] ?? [];
         childrenOf[definitionParent] = parentChildren.filter((id) => id !== catalogId);

package/dist/runstore/port.d.ts

@@ -1,12 +1,14 @@
 import type { StageLogLine } from "../agent/activity.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { ResolvedPipelineDag } from "../types/pipeline.js";
+import type { FeedbackLoopConfig, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { CompletionCheck } from "../types/completion.js";
 import type { StageGateKind } from "../types/stage.js";
 export type RunStatus = "created" | "running" | "succeeded" | "failed";
 export type RunPipelineDagSnapshot = ResolvedPipelineDag & {
     stage_ids: string[];
     gate_kinds?: Record<string, StageGateKind[]>;
+    clone_input_schema?: Record<string, unknown>;
 };
 export type StageReadiness = "blocked" | "ready" | "running" | "waiting" | "succeeded" | "failed" | "skipped";
 export type PipelineTrackNode = {
@@ -19,6 +21,9 @@ export type PipelineTrackNode = {
     gate_kinds?: StageGateKind[];
     attempt_count?: number;
     definition_id?: string;
+    feedback_loop?: {
+        target: string;
+    };
 };
 export type PipelineTrackEdge = {
     from: string;
@@ -70,16 +75,145 @@ export type StageExecution = {
     stage_id: string;
     attempt: number;
     status: StageSnapshot["status"];
+    verification_outcome: VerificationOutcome;
     started_at?: string;
     finished_at?: string;
     envelope: StageEnvelope | null;
 };
 export type StageExecutionPatch = {
     status?: StageSnapshot["status"];
+    verification_outcome?: VerificationOutcome;
     started_at?: string;
     finished_at?: string;
     envelope?: StageEnvelope | null;
 };
+/** The durable disposition of completion verification for one stage attempt. */
+export type VerificationOutcome = "not_run" | "passed" | "failed" | "error";
+/** The lifecycle state of one independently-run completion check. */
+export type VerificationCheckStatus = "pending" | "running" | "passed" | "failed" | "skipped";
+/**
+ * Durable evidence for one check in one stage execution attempt.
+ *
+ * `evidence` is intentionally JSON-shaped: each checker owns its evidence
+ * schema (for example, command output metadata or an artifact digest), while
+ * the run store preserves it without privileging a particular checker.
+ */
+export type VerificationCheckResult = {
+    run_id: string;
+    stage_id: string;
+    attempt: number;
+    check_id: string;
+    check_type: CompletionCheck["type"];
+    status: VerificationCheckStatus;
+    started_at?: string;
+    finished_at?: string;
+    evidence?: Record<string, unknown>;
+};
+/** Input for creating or updating a verification-check lifecycle record. */
+export type VerificationCheckResultPatch = {
+    check_id: string;
+    check_type: CompletionCheck["type"];
+    status: VerificationCheckStatus;
+    started_at?: string;
+    finished_at?: string;
+    evidence?: Record<string, unknown>;
+};
+/** Durable lifecycle for one source-owned feedback-loop policy in a run. */
+export type FeedbackLoopState = "active" | "waiting_for_human" | "continued" | "abandoned" | "completed";
+/** Durable lifecycle for one accepted send-back through a feedback loop. */
+export type FeedbackReplayStatus = "scheduled" | "active" | "waiting_for_human" | "completed" | "failed" | "superseded";
+/** Lifecycle for one persistent stage's pass within a feedback replay. */
+export type FeedbackReplayStagePassStatus = "pending" | "running" | "waiting" | "succeeded" | "failed" | "superseded";
+/** Active/history state for a dynamic clone cohort created by a fork parent. */
+export type ForkGenerationStatus = "active" | "completed" | "superseded";
+/** Deferred over-limit send_back awaiting a human feedback-loop decision. */
+export type DeferredFeedbackSendBack = {
+    target: string;
+    feedback_envelope: StageEnvelope;
+    source_attempt: number;
+};
+export type FeedbackLoopRecord = {
+    run_id: string;
+    loop_id: string;
+    source_stage_id: string;
+    source_attempt: number;
+    policy: FeedbackLoopConfig;
+    state: FeedbackLoopState;
+    current_replay_id?: string;
+    current_replay_number?: number;
+    deferred_send_back?: DeferredFeedbackSendBack;
+    created_at: string;
+    updated_at: string;
+};
+export type FeedbackReplayRecord = {
+    run_id: string;
+    replay_id: string;
+    loop_id: string;
+    source_stage_id: string;
+    source_attempt: number;
+    target_stage_id: string;
+    /** One-based accepted send-back count for this loop. */
+    replay_number: number;
+    max_replays: number;
+    replay_session: FeedbackLoopConfig["replay_session"];
+    route_stage_ids: string[];
+    feedback_envelope: StageEnvelope;
+    status: FeedbackReplayStatus;
+    created_at: string;
+    updated_at: string;
+};
+export type FeedbackReplayStagePassRecord = {
+    run_id: string;
+    replay_id: string;
+    stage_id: string;
+    /** Execution attempt whose session this pass resumes or newly creates. */
+    stage_attempt: number;
+    /** Immutable attempt whose Pi session resume targets; never rebound. */
+    session_origin_attempt?: number;
+    session_mode: FeedbackLoopConfig["replay_session"];
+    status: FeedbackReplayStagePassStatus;
+    started_at?: string;
+    finished_at?: string;
+    emitted_envelope?: StageEnvelope;
+};
+export type ForkGenerationRecord = {
+    run_id: string;
+    generation_id: string;
+    /** Undefined for an initial fan-out that is not part of a replay. */
+    replay_id?: string;
+    fork_parent_stage_id: string;
+    generation_number: number;
+    clone_stage_ids: string[];
+    status: ForkGenerationStatus;
+    created_at: string;
+    updated_at: string;
+};
+export type CreateFeedbackLoopInput = Omit<FeedbackLoopRecord, "run_id" | "state" | "current_replay_id" | "current_replay_number" | "created_at" | "updated_at"> & {
+    state?: FeedbackLoopState;
+};
+export type FeedbackLoopPatch = Partial<Pick<FeedbackLoopRecord, "state" | "current_replay_id" | "current_replay_number" | "policy">> & {
+    /** Set to clear a previously deferred send_back. */
+    deferred_send_back?: DeferredFeedbackSendBack | null;
+};
+export type CreateFeedbackReplayInput = Omit<FeedbackReplayRecord, "run_id" | "status" | "created_at" | "updated_at"> & {
+    status?: FeedbackReplayStatus;
+};
+export type FeedbackReplayPatch = Partial<Pick<FeedbackReplayRecord, "status">>;
+export type CreateFeedbackReplayStagePassInput = Omit<FeedbackReplayStagePassRecord, "run_id" | "status" | "started_at" | "finished_at" | "emitted_envelope"> & {
+    status?: FeedbackReplayStagePassStatus;
+    started_at?: string;
+    finished_at?: string;
+    emitted_envelope?: StageEnvelope;
+};
+export type FeedbackReplayStagePassPatch = Partial<Pick<FeedbackReplayStagePassRecord, "status" | "stage_attempt">> & {
+    started_at?: string | null;
+    finished_at?: string | null;
+    emitted_envelope?: StageEnvelope | null;
+};
+export type CreateForkGenerationInput = Omit<ForkGenerationRecord, "run_id" | "status" | "created_at" | "updated_at"> & {
+    status?: ForkGenerationStatus;
+};
+export type ForkGenerationPatch = Partial<Pick<ForkGenerationRecord, "status">>;
 export type CompactStage = {
     id: string;
     status: StageSnapshot["status"];
@@ -103,17 +237,31 @@ export type RunSummary = {
     waiting_stage_ids?: string[];
     /** Short prompt text for Today triage; omitted when not waiting. */
     waiting_summary?: string;
-    waiting_kind?: AskOperatorPrompt["kind"];
+    waiting_kind?: AskOperatorPrompt["kind"] | "feedback_loop_decision";
     waiting_prompt_id?: string;
     waiting_artifacts?: string[];
     waiting_questions?: string[];
     failed_stage_id?: string;
     failed_reason?: string;
+    /** The active loop, when a run is currently replaying or awaiting a decision. */
+    active_feedback_loop?: FeedbackLoopRecord;
 };
 export type RunDetail = Omit<RunSummary, "stages"> & {
     task_yaml: string;
     stages: StageSnapshot[];
     pipeline_track: PipelineTrackProjection;
+    /** Append-only feedback-loop and replay history, ordered by creation. */
+    feedback_loops: FeedbackLoopHistory[];
+};
+export type FeedbackLoopHistory = {
+    loop: FeedbackLoopRecord;
+    replays: Array<{
+        replay: FeedbackReplayRecord;
+        stage_passes: FeedbackReplayStagePassRecord[];
+        fork_generations: ForkGenerationRecord[];
+    }>;
+    /** Fork cohorts not associated with a replay, for example the first pass. */
+    fork_generations: ForkGenerationRecord[];
 };
 export type CreateRunInput = {
     pipelineId: string;
@@ -156,6 +304,15 @@ export interface RunStore {
     countStageAttempts(runId: string, stageId: string): Promise<number>;
     getStageExecution(runId: string, stageId: string, attempt: number): Promise<StageExecution>;
     updateStageExecution(runId: string, stageId: string, attempt: number, patch: StageExecutionPatch): Promise<void>;
+    /** Create or update evidence for one check in a stage execution attempt. */
+    upsertVerificationCheckResult(runId: string, stageId: string, result: VerificationCheckResultPatch, options?: {
+        attempt?: number;
+    }): Promise<void>;
+    /**
+     * List verification evidence in write order. Without an attempt, returns all
+     * attempts for the stage; callers may pass an attempt to inspect one retry.
+     */
+    listVerificationCheckResults(runId: string, stageId: string, attempt?: number): Promise<VerificationCheckResult[]>;
     writeEnvelope(runId: string, stageId: string, envelope: StageEnvelope, options?: {
         attempt?: number;
     }): Promise<void>;
@@ -167,6 +324,31 @@ export interface RunStore {
     listRuns(filter?: ListRunsFilter): Promise<RunSummary[]>;
     readRun(runId: string): Promise<RunDetail>;
     updatePipelineDag(runId: string, dag: RunPipelineDagSnapshot): Promise<void>;
+    createFeedbackLoop(runId: string, input: CreateFeedbackLoopInput): Promise<FeedbackLoopRecord>;
+    getFeedbackLoop(runId: string, loopId: string): Promise<FeedbackLoopRecord>;
+    listFeedbackLoops(runId: string): Promise<FeedbackLoopRecord[]>;
+    /**
+     * Patch a feedback loop. When `expectedState` is set, the update is conditional
+     * (CAS): returns false if the row exists but state does not match.
+     * Throws if the loop is missing.
+     */
+    updateFeedbackLoop(runId: string, loopId: string, patch: FeedbackLoopPatch, options?: {
+        expectedState?: FeedbackLoopState;
+    }): Promise<boolean>;
+    createFeedbackReplay(runId: string, input: CreateFeedbackReplayInput): Promise<FeedbackReplayRecord>;
+    getFeedbackReplay(runId: string, replayId: string): Promise<FeedbackReplayRecord>;
+    listFeedbackReplays(runId: string, loopId: string): Promise<FeedbackReplayRecord[]>;
+    updateFeedbackReplay(runId: string, replayId: string, patch: FeedbackReplayPatch): Promise<void>;
+    createFeedbackReplayStagePass(runId: string, input: CreateFeedbackReplayStagePassInput): Promise<FeedbackReplayStagePassRecord>;
+    listFeedbackReplayStagePasses(runId: string, replayId: string): Promise<FeedbackReplayStagePassRecord[]>;
+    updateFeedbackReplayStagePass(runId: string, replayId: string, stageId: string, patch: FeedbackReplayStagePassPatch): Promise<void>;
+    createForkGeneration(runId: string, input: CreateForkGenerationInput): Promise<ForkGenerationRecord>;
+    listForkGenerations(runId: string, options?: {
+        replayId?: string;
+        forkParentStageId?: string;
+    }): Promise<ForkGenerationRecord[]>;
+    updateForkGeneration(runId: string, generationId: string, patch: ForkGenerationPatch): Promise<void>;
 }
 export declare function stageStatusFromEvents(events: StageLogEvent[]): StageSnapshot["status"];
-export declare function deriveStatusFromStages(stages: StageSnapshot[]): RunStatus;
+export declare function findUnhandledFailedStage(stages: StageSnapshot[], dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null): StageSnapshot | undefined;
+export declare function deriveStatusFromStages(stages: StageSnapshot[], dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null): RunStatus;