stageflow 0.9.0 → 0.13.0

package/dist/runtime/runRetryCoordinator.js

@@ -1,3 +1,4 @@
+import { findUnhandledFailedStage, } from "../runstore/port.js";
 import { retryRun, } from "./pipelineScheduler.js";
 import { loadRunContext } from "./resumeReconstruct.js";
 import { syncRunStatusFromStages } from "./stageRecovery.js";
@@ -19,6 +20,20 @@ export class RetryRootWaitTimeoutError extends Error {
         this.name = "RetryRootWaitTimeoutError";
     }
 }
+export function succeededStageRetryBlocker(stageSnap) {
+    if (stageSnap.definition_id !== undefined &&
+        stageSnap.definition_id !== stageSnap.stage_id) {
+        return `Cannot re-run a succeeded clone instance stage (stage=${stageSnap.stage_id}, definition=${stageSnap.definition_id}): clone instances are created by upstream fan-out and cannot be rebuilt in place. Use rerun to start a new run.`;
+    }
+    const forks = stageSnap.envelope?.clone_forks;
+    if (Array.isArray(forks) && forks.length > 0) {
+        return `Cannot re-run a succeeded clonable-fanout stage (stage=${stageSnap.stage_id}): its envelope declared clone_forks and existing clone instances cannot be pruned. Use rerun to start a new run.`;
+    }
+    if (stageSnap.envelope?.fork_choice !== undefined) {
+        return `Cannot re-run a succeeded fork stage (stage=${stageSnap.stage_id}): its envelope recorded a fork_choice and skipped branches cannot be restored. Use rerun to start a new run.`;
+    }
+    return undefined;
+}
 export function assertStageRetryEligible(detail, stageId, opts) {
     const stageSnap = detail.stages.find((s) => s.stage_id === stageId);
     if (!stageSnap) {
@@ -35,23 +50,34 @@ export function assertStageRetryEligible(detail, stageId, opts) {
             status: 409,
         };
     }
+    const runStatus = opts?.persistedStatus ?? detail.status;
     const recoveryActive = opts?.recoveryActive === true;
-    if (detail.status !== "failed") {
-        if (!(detail.status === "running" && recoveryActive)) {
+    if (runStatus !== "failed" && runStatus !== "succeeded") {
+        const acceptedPendingRetry = runStatus === "running" &&
+            stageSnap.status === "failed" &&
+            findUnhandledFailedStage(detail.stages, opts?.dag) === undefined &&
+            detail.stages.some((stage) => stage.status === "pending");
+        if (!(runStatus === "running" && recoveryActive) && !acceptedPendingRetry) {
             return {
                 ok: false,
-                reason: `Run is not failed (status=${detail.status})`,
+                reason: `Run is not failed or succeeded (status=${runStatus})`,
                 status: 409,
             };
         }
     }
-    if (stageSnap.status !== "failed") {
+    if (stageSnap.status !== "failed" && stageSnap.status !== "succeeded") {
         return {
             ok: false,
-            reason: `Stage is not failed (status=${stageSnap.status})`,
+            reason: `Stage is not failed or succeeded (status=${stageSnap.status})`,
             status: 409,
         };
     }
+    if (stageSnap.status === "succeeded") {
+        const blocker = succeededStageRetryBlocker(stageSnap);
+        if (blocker !== undefined) {
+            return { ok: false, reason: blocker, status: 409 };
+        }
+    }
     return { ok: true };
 }
 function mutationKey(stageId, attempt) {
@@ -60,7 +86,7 @@ function mutationKey(stageId, attempt) {
 function rootWaitKey(runId, stageId, attempt) {
     return `${runId}\0${stageId}\0${attempt}`;
 }
-function readRetryRootWaitTimeoutMs() {
+export function readRetryRootWaitTimeoutMs() {
     const raw = process.env.STAGEFLOW_RETRY_ROOT_WAIT_TIMEOUT_MS;
     if (raw !== undefined && raw !== "") {
         const parsed = Number(raw);
@@ -225,8 +251,13 @@ export class RunRetryCoordinator {
     async retryStage(req) {
         const { runId, stageId, store, tracking } = req;
         let detail;
+        let metaStatus;
+        let dag;
         try {
             detail = await store.readRun(runId);
+            const meta = await store.readRunMeta(runId);
+            metaStatus = meta.status ?? detail.status;
+            dag = meta.pipeline_dag;
         }
         catch {
             return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
@@ -234,6 +265,8 @@ export class RunRetryCoordinator {
         const recoveryActive = this.isActive(runId);
         const eligibility = assertStageRetryEligible(detail, stageId, {
             recoveryActive,
+            persistedStatus: metaStatus,
+            ...(dag !== undefined ? { dag } : {}),
         });
         if (!eligibility.ok) {
             return {
@@ -258,7 +291,7 @@ export class RunRetryCoordinator {
                 status: 409,
             };
         }
-        const priorRunStatus = detail.status;
+        const priorRunStatus = metaStatus;
         let insertedForResume = false;
         let bumpedRunning = false;
         try {
@@ -272,7 +305,7 @@ export class RunRetryCoordinator {
                     };
                 }
                 insertedForResume = tracked.insertedForResume === true;
-                if (priorRunStatus === "failed") {
+                if (priorRunStatus === "failed" || priorRunStatus === "succeeded") {
                     await store.updateRunStatus(runId, "running");
                     bumpedRunning = true;
                 }
@@ -286,6 +319,7 @@ export class RunRetryCoordinator {
                 }
             }
             const execution = await store.createStageExecution(runId, stageId);
+            await req.beforeAttemptStart?.(execution.attempt);
             const { meta, task, loaded, workspaceDir } = await loadRunContext(store, runId, req.cwd);
             const prepared = {
                 task,
@@ -298,7 +332,7 @@ export class RunRetryCoordinator {
                 hitl: req.hitl,
                 operatorCatalog: req.operatorCatalog,
             };
-            if (recoveryActive) {
+            if (this.isActive(runId)) {
                 await this.addRoot(runId, stageId, execution.attempt);
             }
             else {

package/dist/runtime/stageAttemptBootstrap.d.ts

@@ -1,4 +1,4 @@
-import type { AgentPort, StageHandle, StageRunInput } from "../agent/port.js";
+import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunInput, StageSessionMode } from "../agent/port.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
@@ -25,9 +25,11 @@ export type StageAttemptOpenInput = {
     onActivity?: StageRunInput["onActivity"];
     roots?: StageRoots;
     resumeToken?: string;
+    sessionMode?: StageSessionMode;
     workerRoots?: boolean;
     completedEnvelopes?: Map<string, StageEnvelope>;
     stageId?: string;
+    feedbackLoopContext?: FeedbackLoopContext;
 };
 export type StageAttemptOpenResult = {
     ok: true;

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,5 +1,9 @@
 import { resolveSkillByName } from "../config/listSkills.js";
+import { mkdir } from "node:fs/promises";
+import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
+import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
+import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
 import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
 import { resumeSessionFilePath } from "./stageAttemptContext.js";
 import { buildStageRoots, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
@@ -19,16 +23,49 @@ async function resolveStageSkillForRun(stage, catalog) {
     }
     return { ok: true, skillFilePath: resolved.filePath };
 }
-async function openStageWithOperatorCatalog(agent, input, catalog) {
+async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir) {
+    const names = allowlist ?? [];
+    if (names.length === 0)
+        return undefined;
+    if (factoryCwd === undefined) {
+        throw new StageMcpError(`MCP catalog "${MCP_CATALOG_FILENAME}" is missing`, "missing_catalog");
+    }
+    await mkdir(artifactsDir, { recursive: true });
+    const resolved = await resolveStageMcpServers({
+        projectRoot: factoryCwd,
+        allowlist: names,
+        env: {
+            ...process.env,
+            [STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV]: artifactsDir,
+        },
+    });
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, artifactsDir) {
     const skill = await resolveStageSkillForRun(input.stage, catalog);
     if (!skill.ok)
         return skill;
+    let resolvedMcpServers;
+    try {
+        resolvedMcpServers = await resolveAttemptMcpServers(input.stage.mcp, factoryCwd, artifactsDir);
+    }
+    catch (err) {
+        if (err instanceof StageMcpError) {
+            return { ok: false, reason: err.message };
+        }
+        throw err;
+    }
     try {
         const handle = agent.openStage({
             ...input,
+            stage: {
+                ...input.stage,
+                system_prompt: stampStagePromptArtifactsDir(input.stage.system_prompt, artifactsDir),
+            },
             ...(skill.skillFilePath !== undefined
                 ? { skillFilePath: skill.skillFilePath }
                 : {}),
+            ...(resolvedMcpServers !== undefined ? { resolvedMcpServers } : {}),
         });
         return { ok: true, handle };
     }
@@ -48,6 +85,52 @@ function resolveAttemptRoots(input, stageId) {
         ? withResolvedAuthPath(baseRoots, input.factoryCwd)
         : baseRoots;
 }
+function evidencePreview(evidence) {
+    if (evidence === undefined)
+        return undefined;
+    try {
+        const text = JSON.stringify(evidence);
+        return text.length <= 4_000 ? text : `${text.slice(0, 4_000)}…`;
+    }
+    catch {
+        return "Verification evidence could not be serialized.";
+    }
+}
+async function repairContextForAttempt(input, stageId, attempt) {
+    if (attempt <= 1)
+        return undefined;
+    const recovery = input.dag.nodes.find((node) => node.id === stageId)?.recovery;
+    if (recovery?.mode !== "repair" && recovery?.mode !== "manual") {
+        return undefined;
+    }
+    const events = await input.store.listStageEvents(input.runId, stageId, attempt);
+    const guidance = events
+        .slice()
+        .reverse()
+        .find((event) => event.event === "manual_recovery_requested")?.guidance;
+    if (recovery.mode === "manual" && typeof guidance !== "string") {
+        return undefined;
+    }
+    const failed = (await input.store.listVerificationCheckResults(input.runId, stageId, attempt - 1)).filter((check) => check.status === "failed");
+    return {
+        prior_attempt: attempt - 1,
+        ...(typeof guidance === "string" && guidance.trim() !== ""
+            ? { operator_guidance: guidance.trim() }
+            : {}),
+        ...(recovery.include_failed_checks !== false
+            ? {
+                failed_checks: failed.map((check) => {
+                    const preview = evidencePreview(check.evidence);
+                    return {
+                        id: check.check_id,
+                        type: check.check_type,
+                        ...(preview !== undefined ? { evidence_preview: preview } : {}),
+                    };
+                }),
+            }
+            : {}),
+    };
+}
 export async function openStageAttempt(input) {
     const stageId = input.stageId ?? input.stage.id;
     const definitionId = input.stage.id;
@@ -67,7 +150,24 @@ export async function openStageAttempt(input) {
     const resumeToken = input.resumeToken ??
         resumeSessionFilePath(input.workspaceDir, stageId, attempt);
     const forkEmitContext = resolveForkEmitContext(input.dag, definitionId);
-    const cloneEmitContext = resolveCloneEmitContext(input.dag, definitionId);
+    const snapshot = input.dag;
+    const cloneEmitContext = resolveCloneEmitContext(input.dag, definitionId, {
+        ...(input.stage.clone_actions !== undefined
+            ? { allowedActions: input.stage.clone_actions }
+            : {}),
+        ...(snapshot.clone_input_schema !== undefined
+            ? { successorCloneInputSchemas: snapshot.clone_input_schema }
+            : {}),
+    });
+    const completionContract = input.dag.nodes.find((node) => node.id === stageId)?.completion;
+    const runtimeNode = input.dag.nodes.find((node) => node.id === stageId);
+    const isDynamicCloneInstance = runtimeNode?.definition_id !== undefined &&
+        runtimeNode.definition_id !== runtimeNode.id;
+    const feedbackLoopEmitContext = isDynamicCloneInstance || runtimeNode?.clonable === true
+        ? undefined
+        : runtimeNode?.feedback_loop;
+    const repairContext = await repairContextForAttempt(input, stageId, attempt);
+    const readQaTrail = createAttemptQaTrailReader(input.store, input.runId, stageId, attempt);
     const opened = await openStageWithOperatorCatalog(input.agent, {
         roots,
         stage: input.stage,
@@ -77,11 +177,25 @@ export async function openStageAttempt(input) {
         ...(priorResult.joinPriors !== undefined
             ? { priorEnvelopes: priorResult.joinPriors }
             : {}),
+        ...(priorResult.priorEnvelopesByStage !== undefined
+            ? { priorEnvelopesByStage: priorResult.priorEnvelopesByStage }
+            : {}),
         resumeToken,
+        ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
         onActivity: input.onActivity,
         forkEmitContext,
         cloneEmitContext,
-    }, input.operatorCatalog);
+        ...(feedbackLoopEmitContext !== undefined ? { feedbackLoopEmitContext } : {}),
+        ...(input.feedbackLoopContext !== undefined
+            ? { feedbackLoopContext: input.feedbackLoopContext }
+            : {}),
+        ...(completionContract !== undefined ? { completionContract } : {}),
+        ...(repairContext !== undefined ? { repairContext } : {}),
+        readQaTrail,
+        ...(input.stage.timeout_ms !== undefined
+            ? { timeoutMs: input.stage.timeout_ms }
+            : {}),
+    }, input.operatorCatalog, input.factoryCwd, attemptArtifactsDir(input.workspaceDir, stageId, attempt));
     if (!opened.ok)
         return opened;
     return {

package/dist/runtime/stageProcessLauncher.d.ts

@@ -3,7 +3,7 @@ export type StageLaunchInput = {
     runId: string;
     stageId: string;
     rootDir: string;
-    mode?: "run" | "resume";
+    mode?: "run" | "resume" | "feedback_resume" | "new_session";
     resumeAnswer?: unknown;
     attempt?: number;
     sessionFilePath?: string;

package/dist/runtime/stageRecovery.js

@@ -38,7 +38,7 @@ export async function syncRunStatusFromStages(store, runId) {
     if (meta.status === "succeeded")
         return;
     const run = await store.readRun(runId);
-    const derived = deriveStatusFromStages(run.stages);
+    const derived = deriveStatusFromStages(run.stages, meta.pipeline_dag);
     if ((meta.status ?? "created") !== derived) {
         await store.updateRunStatus(runId, derived);
     }

package/dist/runtime/stageRunner.d.ts

@@ -1,4 +1,4 @@
-import type { AgentPort, StageHandle, StageRunResult } from "../agent/port.js";
+import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunResult, StageSessionMode } from "../agent/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { StageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
@@ -45,6 +45,9 @@ export type RunStageOptions = {
     completedEnvelopes?: Map<string, StageEnvelope>;
     skipGates?: boolean;
     stageId?: string;
+    sessionMode?: StageSessionMode;
+    feedbackLoopContext?: FeedbackLoopContext;
+    resumeToken?: string;
 };
 /**
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).

package/dist/runtime/stageRunner.js

@@ -2,6 +2,7 @@ import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
 import { buildStageRoots, withResolvedAuthPath, } from "./stageRoots.js";
 import { createDefaultHitlQaHooks, recordWaitEnter, } from "./stageHitl.js";
 import { openStageAttempt, } from "./stageAttemptBootstrap.js";
+import { createVerifiedStageExecution } from "./verifiedStageExecution.js";
 export function isRunStageWaiting(outcome) {
     return "waiting" in outcome && outcome.waiting === true;
 }
@@ -113,7 +114,7 @@ export async function runStageYieldLoop(options) {
     }
 }
 export async function runStage(options) {
-    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, } = options;
+    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, } = options;
     const stageId = options.stageId ?? stage.id;
     const attemptOpt = attemptCtx?.eventOptions();
     const baseRoots = rootsOverride ??
@@ -133,6 +134,16 @@ export async function runStage(options) {
             attemptCtx,
         });
     }
+    const verifiedExecution = createVerifiedStageExecution({
+        store,
+        runId,
+        stageId,
+        attempt,
+        stage,
+        dag,
+        roots,
+    });
+    await verifiedExecution.prepare();
     console.error(`Running stage ${stageId} (${stage.model})...`);
     let activityChain = Promise.resolve();
     const enqueueActivity = (event) => {
@@ -152,7 +163,7 @@ export async function runStage(options) {
             task,
             dag: dag ?? {
                 nodes: [
-                    { id: stageId, needs: null, ancestors: [], stageIndex: 0 },
+                    { id: stageId, needs: null, needsEdges: [], ancestors: [], stageIndex: 0 },
                 ],
                 roots: [stageId],
                 childrenOf: {},
@@ -164,6 +175,9 @@ export async function runStage(options) {
             operatorCatalog,
             roots,
             completedEnvelopes,
+            ...(sessionMode !== undefined ? { sessionMode } : {}),
+            ...(feedbackLoopContext !== undefined ? { feedbackLoopContext } : {}),
+            ...(resumeToken !== undefined ? { resumeToken } : {}),
             onActivity: (event) => {
                 enqueueActivity(event);
             },
@@ -215,11 +229,23 @@ export async function runStage(options) {
         return { waiting: true };
     }
     try {
+        let result = outcome;
+        if (outcome.ok) {
+            try {
+                result = await verifiedExecution.verify(outcome);
+            }
+            catch (error) {
+                result = {
+                    ok: false,
+                    reason: `Completion verification errored: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
         return await finalizeStageResult({
             store,
             runId,
             stageId,
-            result: outcome,
+            result,
             activityChain,
             attemptCtx,
         });

package/dist/runtime/stageWorker.js

@@ -1,4 +1,6 @@
-import { PiAgentAdapter } from "../agent/piAdapter.js";
+import { resolveAgentPort } from "../agent/resolveAgentPort.js";
+import { asAgentBackendId } from "../agent/agentBackend.js";
+import { loadStageflowManifestOutcome } from "../config/loadStageflowManifest.js";
 import { definitionIdForInstance } from "../runstore/stageInstanceId.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { loadRunContext } from "./resumeReconstruct.js";
@@ -6,6 +8,7 @@ import { bindPiAgentDirEnv, rootsForStageWorker, withResolvedAuthPath, } from ".
 import { runStage, isRunStageWaiting, } from "./stageRunner.js";
 import { openStageAttempt } from "./stageAttemptBootstrap.js";
 import { attemptContext } from "./stageAttemptContext.js";
+import { loadActiveFeedbackLoopContext } from "./feedbackLoopCoordinator.js";
 import { outcomeToWorkerResult, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 export async function runStageWorker(input) {
     const store = createRunStore({ rootDir: input.rootDir });
@@ -19,7 +22,14 @@ export async function runStageWorker(input) {
         };
     }
     const dag = meta.pipeline_dag ?? loaded.dag;
-    const agent = new PiAgentAdapter();
+    const manifestOutcome = await loadStageflowManifestOutcome(input.rootDir);
+    const agent = resolveAgentPort({
+        global: manifestOutcome.ok
+            ? asAgentBackendId(manifestOutcome.value.manifest.agent)
+            : undefined,
+        pipeline: asAgentBackendId(loaded.pipeline.agent),
+        stage: asAgentBackendId(stage.agent),
+    });
     const workspaceDir = store.getWorkspaceDir(input.runId);
     const checkoutRoot = meta.checkout_root;
     const mode = input.mode ?? "run";
@@ -45,6 +55,7 @@ export async function runStageWorker(input) {
                 operatorCatalog: input.operatorCatalog,
                 roots,
                 resumeToken: input.sessionFilePath,
+                sessionMode: "waiting_resume",
                 onActivity: (event) => {
                     void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
                 },
@@ -74,6 +85,62 @@ export async function runStageWorker(input) {
             });
             return outcome;
         }
+        if (mode === "feedback_resume" || mode === "new_session") {
+            const feedbackLoopContext = await loadActiveFeedbackLoopContext(store, input.runId, input.stageId);
+            if (mode === "feedback_resume" && feedbackLoopContext === undefined) {
+                return {
+                    ok: false,
+                    reason: "feedback_resume requires an active feedback-loop context",
+                };
+            }
+            const priorAttempt = feedbackLoopContext?.prior_stage_attempt;
+            const resumeToken = input.sessionFilePath ??
+                (mode === "feedback_resume" && priorAttempt !== undefined
+                    ? attemptContext(priorAttempt).sessionPath(workspaceDir, input.stageId)
+                    : undefined);
+            const opened = await openStageAttempt({
+                agent,
+                store,
+                runId: input.runId,
+                stage,
+                stageId: input.stageId,
+                task,
+                dag,
+                checkoutRoot,
+                workspaceDir,
+                factoryCwd: input.rootDir,
+                attemptCtx,
+                operatorCatalog: input.operatorCatalog,
+                roots,
+                ...(resumeToken !== undefined ? { resumeToken } : {}),
+                sessionMode: mode,
+                ...(feedbackLoopContext !== undefined ? { feedbackLoopContext } : {}),
+                onActivity: (event) => {
+                    void store.appendStageEvent(input.runId, input.stageId, event, eventOptions);
+                },
+            });
+            if (!opened.ok) {
+                return { ok: false, reason: opened.reason };
+            }
+            return runStage({
+                agent,
+                store,
+                runId: input.runId,
+                stage,
+                stageId: input.stageId,
+                task,
+                dag,
+                checkoutRoot,
+                workspaceDir,
+                existingHandle: opened.handle,
+                workerMode: true,
+                roots,
+                attemptCtx,
+                factoryCwd: input.rootDir,
+                operatorCatalog: input.operatorCatalog,
+                skipGates: input.skipGates,
+            });
+        }
         return runStage({
             agent,
             store,

package/dist/runtime/stageWorkerProtocol.d.ts

@@ -10,7 +10,7 @@ export type StageWorkerInput = {
     runId: string;
     stageId: string;
     rootDir: string;
-    mode?: "run" | "resume";
+    mode?: "run" | "resume" | "feedback_resume" | "new_session";
     resumeAnswer?: unknown;
     attempt?: number;
     sessionFilePath?: string;

package/dist/runtime/verifiedStageExecution.d.ts

@@ -0,0 +1,31 @@
+import type { StageRunResult } from "../agent/port.js";
+import type { RunStore } from "../runstore/port.js";
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageConfig } from "../types/stage.js";
+import type { StageRoots } from "./stageRoots.js";
+/** Sidecar written before completion command checks so they can inspect fork_choice. */
+export declare const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
+export type VerifiedStageExecution = {
+    /** Establish durable observation before agent work begins. */
+    prepare(): Promise<void>;
+    /** Accept a successful agent result only when its contract passes. */
+    verify(candidate: Extract<StageRunResult, {
+        ok: true;
+    }>): Promise<StageRunResult>;
+};
+export declare function completionVerificationFailureReason(failedCheckIds: readonly string[]): string;
+/**
+ * Owns the verification lifecycle for one immutable stage attempt: establish
+ * observation before agent work, then persist evidence before accepting a
+ * candidate handoff. Agent lifecycle and final stage status stay outside this
+ * module in stageRunner.
+ */
+export declare function createVerifiedStageExecution(options: {
+    store: RunStore;
+    runId: string;
+    stageId: string;
+    attempt: number;
+    stage: StageConfig;
+    dag?: ResolvedPipelineDag;
+    roots: StageRoots;
+}): VerifiedStageExecution;