stageflow 0.9.0 → 0.12.0

package/dist/agent/claudeTools.js

@@ -0,0 +1,135 @@
+/**
+ * Claude Agent SDK tool wrappers for the stage tool set.
+ *
+ * The actual envelope/artifact business logic lives in
+ * `tools/emitStageEnvelope.ts` / `tools/writeStageArtifact.ts` and is fully
+ * SDK-agnostic (typed `params: unknown`, no Pi imports) — this file reuses
+ * those `execute` functions as-is and only translates the *declaration*
+ * layer (typebox → Zod) and the *result* layer (drops Pi-only `terminate`/
+ * `details` fields, keeping just the MCP `CallToolResult` shape).
+ *
+ * `ask_operator` is different: `tools/askOperator.ts`'s own `execute` blocks
+ * on an injected wait bridge (Pi's in-process mechanism), which is exactly
+ * what Phase 3's "never let it go dangling" design avoids. This file reuses
+ * only the pure parsing/validation helpers from that module
+ * (`parseAskOperatorParams`, `normalizePromptIds`) and writes its own
+ * non-blocking handler: record the prompt on `capture`, return an immediate
+ * placeholder result, and rely on the adapter's `interrupt()` backstop
+ * (called right after this result lands) to end the turn — see
+ * claudeAdapter.ts.
+ *
+ * Registered under one in-process MCP server named "stageflow", so the model
+ * sees these as `mcp__stageflow__emit_stage_envelope`,
+ * `mcp__stageflow__write_stage_artifact`, and `mcp__stageflow__ask_operator`
+ * — those exact strings are what `composeStageUserPrompt`'s hints and the
+ * adapter's resume prompts must reference.
+ */
+import { createSdkMcpServer, tool, } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
+import { createWriteStageArtifactTool, } from "../tools/writeStageArtifact.js";
+import { ASK_OPERATOR_KINDS, AskOperatorError, normalizePromptIds, parseAskOperatorParams, } from "../tools/askOperator.js";
+export const STAGEFLOW_MCP_SERVER_NAME = "stageflow";
+export const EMIT_STAGE_ENVELOPE_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__emit_stage_envelope`;
+export const WRITE_STAGE_ARTIFACT_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__write_stage_artifact`;
+export const ASK_OPERATOR_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__ask_operator`;
+/**
+ * Exported so a parity test can assert this stays field-for-field aligned
+ * with `tools/emitStageEnvelope.ts`'s typebox schema — the two are hand
+ * written against the same envelope shape with no shared source, so
+ * nothing else catches one drifting from the other.
+ *
+ * Field presence mirrors the typebox schema's own conditionality:
+ * `clone_forks` only exists when a stage can clone-fork at all, and
+ * `fork_choice` is required (not just present) when the stage has a fork
+ * to route. Building this statically would silently offer the model a
+ * `clone_forks` field on stages that have nowhere to route one.
+ */
+export function buildEmitStageEnvelopeShape(options) {
+    return {
+        status: z.enum(["success", "failure"]),
+        summary: z.string().min(1),
+        artifacts: z.array(z.string()),
+        payload: z.record(z.string(), z.unknown()).optional(),
+        fork_choice: options.forkEmitContext !== undefined
+            ? z.array(z.string())
+            : z.array(z.string()).optional(),
+        ...(options.cloneEmitContext !== undefined
+            ? { clone_forks: z.array(z.record(z.string(), z.unknown())) }
+            : {}),
+        checklist_attestations: z
+            .array(z.object({
+            check_id: z.string().min(1),
+            items: z.array(z.string()),
+        }))
+            .optional(),
+        stage_id: z.string().optional(),
+        notes: z.string().optional(),
+    };
+}
+/** Exported for the same parity-test reason as `emitStageEnvelopeShape` above. */
+export const writeStageArtifactShape = {
+    path: z.string().min(1),
+    content: z.string(),
+};
+const askOperatorShape = {
+    kind: z.string(),
+    message: z.string().optional(),
+    id: z.string().optional(),
+    questions: z.array(z.record(z.string(), z.unknown())).optional(),
+    artifacts: z.array(z.string()).optional(),
+};
+/** Adapts a `{content, details?, isError?, terminate?}` tool result to plain MCP CallToolResult. */
+function toCallToolResult(result) {
+    return {
+        content: result.content,
+        ...(result.isError ? { isError: true } : {}),
+    };
+}
+function buildAskOperatorTool(capture, allowedKinds) {
+    const allowed = allowedKinds && allowedKinds.length > 0
+        ? new Set(allowedKinds)
+        : null;
+    const kindList = allowed ? [...allowed].join(", ") : ASK_OPERATOR_KINDS.join(", ");
+    return tool("ask_operator", `Ask the operator a question and stop. Supports ${kindList} prompts. Calling this tool immediately ends your turn — after it returns, do not call any more tools and do not keep talking; you will be resumed in a new turn once the operator has answered. Does not complete the stage — call emit_stage_envelope when finished.`, askOperatorShape, async (args) => {
+        try {
+            const parsed = parseAskOperatorParams(args);
+            if (allowed && !allowed.has(parsed.kind)) {
+                throw new AskOperatorError(`unsupported prompt kind "${parsed.kind}" (allowed: ${kindList})`);
+            }
+            capture.prompt = normalizePromptIds(parsed);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Invalid ask_operator params: ${message}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Question recorded for the operator. Stop here — do not call any more tools or continue this turn; you will be resumed with the operator's answer in a new turn.",
+                },
+            ],
+        };
+    });
+}
+export function buildStageflowMcpServer(options) {
+    const emitDef = createEmitStageEnvelopeTool(options.capture, options.payloadSchema, options.forkEmitContext, options.cloneEmitContext, options.preEmitCheckOptions);
+    const artifactDef = createWriteStageArtifactTool(options.writeStageArtifact);
+    const emitTool = tool(emitDef.name, emitDef.description, buildEmitStageEnvelopeShape({
+        forkEmitContext: options.forkEmitContext,
+        cloneEmitContext: options.cloneEmitContext,
+    }), async (args) => toCallToolResult(await emitDef.execute("claude-tool-call", args)));
+    const artifactTool = tool(artifactDef.name, artifactDef.description, writeStageArtifactShape, async (args) => toCallToolResult(await artifactDef.execute("claude-tool-call", args)));
+    const tools = [emitTool, artifactTool];
+    if (options.askOperator) {
+        tools.push(buildAskOperatorTool(options.askOperator.capture, options.askOperator.allowedKinds));
+    }
+    return createSdkMcpServer({
+        name: STAGEFLOW_MCP_SERVER_NAME,
+        tools,
+    });
+}

package/dist/agent/fakeAgent.js

@@ -1,12 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
+import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
 import { assertCloneForks } from "../envelope/cloneForks.js";
 import { assertForkEnvelope } from "../envelope/forkChoice.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
 import { tryParsePendingPrompt } from "../runtime/stageHitl.js";
-import { runtimeStageId, runStageViaOpen } from "./port.js";
+import { runtimeStageId, runStageViaOpen, createCompletedOnlyStageHandle, } from "./port.js";
 function opaqueEqual(a, b) {
     if (Object.is(a, b))
         return true;
@@ -68,6 +69,17 @@ export class FakeAgent {
         let answerPromise;
         let started = false;
         let resumeCorrupt = false;
+        const sessionMode = input.sessionMode ?? "fresh";
+        const skipHitlPark = sessionMode === "feedback_resume" || sessionMode === "new_session";
+        if (sessionMode === "feedback_resume" && input.feedbackLoopContext === undefined) {
+            return createCompletedOnlyStageHandle({
+                stageId: runtimeStageId(input),
+                run: async () => ({
+                    ok: false,
+                    reason: "feedback_resume requires feedbackLoopContext",
+                }),
+            });
+        }
         const armWait = () => {
             waiting = true;
             answerPromise = new Promise((resolve) => {
@@ -83,7 +95,7 @@ export class FakeAgent {
             answerPromise = undefined;
             return answer;
         };
-        if (behavior.type === "wait_then_emit") {
+        if (behavior.type === "wait_then_emit" && !skipHitlPark) {
             const loaded = loadFakeHitlResume(input.roots, runtimeStageId(input));
             if (loaded === "corrupt") {
                 resumeCorrupt = true;
@@ -99,6 +111,12 @@ export class FakeAgent {
                 armWait();
             }
         }
+        if (sessionMode === "feedback_resume" && behavior.type === "wait_then_emit") {
+            behavior = {
+                type: "emit",
+                envelope: behavior.envelope,
+            };
+        }
         const emitStartActivity = () => {
             if (started)
                 return;
@@ -137,10 +155,12 @@ export class FakeAgent {
                 : undefined;
             try {
                 const envelope = assertRequiredEnvelope(envelopeValue);
-                if (input.forkEmitContext !== undefined) {
+                assertFeedbackLoopAction(envelope, input.feedbackLoopEmitContext);
+                const isFeedbackSendBack = envelope.feedback_loop?.action === "send_back";
+                if (!isFeedbackSendBack && input.forkEmitContext !== undefined) {
                     assertForkEnvelope(envelope, input.forkEmitContext);
                 }
-                if (input.cloneEmitContext !== undefined) {
+                if (!isFeedbackSendBack && input.cloneEmitContext !== undefined) {
                     assertCloneForks(envelope, input.cloneEmitContext);
                 }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);

package/dist/agent/piAdapter.d.ts

@@ -4,12 +4,14 @@ import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/ask
 import "./cursorProvider.js";
 import { type StageActivityObserver } from "./activityObserver.js";
 import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
+import type { StageGateKind } from "../types/stage.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
- * Always includes `ask_operator` (R7); `write_stage_artifact` when registered
- * (always, for bound and unbound — bound/unbound only gates cwd / env bind).
+ * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
+ * `write_stage_artifact` when registered (always, for bound and unbound —
+ * bound/unbound only gates cwd / env bind).
  */
-export declare function resolveStageToolNames(emitToolName: string, artifactToolName?: string, askOperatorToolName?: string): string[];
+export declare function resolveStageToolNames(emitToolName: string, artifactToolName?: string, askOperatorToolName?: string, gateKinds?: StageGateKind[]): string[];
 /**
  * In-process wait channel for `ask_operator` → StageHandle yield/deliver.
  * HITL `openStage` connects this via `setWaitHandler` + handle `deliverAnswer`.
@@ -62,6 +64,7 @@ export type RouteSessionEventToProgressOptions = {
  */
 export declare function routeSessionEventToProgress(event: Record<string, unknown>, options: RouteSessionEventToProgressOptions): void;
 export declare function composeStageUserPrompt(input: StageRunInput, emitToolName: string, emitHintOverride?: string, artifactToolName?: string): string;
+export declare function composeFeedbackResumePrompt(input: StageRunInput): string;
 /**
  * DefaultResourceLoader with host/global discovery turned off.
  *

package/dist/agent/piAdapter.js

@@ -26,14 +26,15 @@
  * fails closed with `StageSessionReconstructError` (KTD7). Epic proving
  * vehicle: pipeline `plan-review-proving` (Pi live wait + console answers).
  *
- * `ask_operator` is always registered on sealed stage sessions (allowlist +
- * customTools).
+ * `ask_operator` is registered on sealed stage sessions unless the stage
+ * declares `gate_kinds: []`.
  */
 import { existsSync } from "node:fs";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createAgentSession, DefaultResourceLoader, defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { isAdvancingEnvelope } from "../envelope/check.js";
+import { formatFeedbackLoopContext } from "../prompt/feedbackLoopContext.js";
 import { formatPriorEnvelope } from "../prompt/priorEnvelope.js";
 import { attemptContext, noAttemptContext, } from "../runtime/stageAttemptContext.js";
 import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
@@ -46,18 +47,21 @@ import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
- * Always includes `ask_operator` (R7); `write_stage_artifact` when registered
- * (always, for bound and unbound — bound/unbound only gates cwd / env bind).
+ * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
+ * `write_stage_artifact` when registered (always, for bound and unbound —
+ * bound/unbound only gates cwd / env bind).
  */
-export function resolveStageToolNames(emitToolName, artifactToolName, askOperatorToolName = "ask_operator") {
+export function resolveStageToolNames(emitToolName, artifactToolName, askOperatorToolName = "ask_operator", gateKinds) {
     const tools = [
         "read",
         "bash",
         "write",
         "edit",
         emitToolName,
-        askOperatorToolName,
     ];
+    if (gateKinds === undefined || gateKinds.length > 0) {
+        tools.push(askOperatorToolName);
+    }
     if (artifactToolName) {
         tools.push(artifactToolName);
     }
@@ -364,6 +368,37 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
     if (input.stage.payload_schema !== undefined) {
         emitHint += `\nOn status=success, payload is required and must match this JSON Schema:\n${JSON.stringify(input.stage.payload_schema, null, 2)}`;
     }
+    const checklistChecks = input.completionContract?.checks.filter((check) => check.type === "checklist") ?? [];
+    if (checklistChecks.length > 0) {
+        emitHint += `\nBefore emitting success, self-review every required checklist item. Include checklist_attestations in the envelope with each check_id and its complete item list exactly as declared:\n${JSON.stringify(checklistChecks, null, 2)}`;
+    }
+    if (input.repairContext !== undefined) {
+        emitHint += `\nThis is recovery attempt ${input.roots.attempt ?? input.repairContext.prior_attempt + 1}. The previous candidate did not pass Stageflow verification. Address the failed checks before emitting success.`;
+        if (input.repairContext.operator_guidance) {
+            emitHint += `\nThe operator approved this retry with these instructions:\n${input.repairContext.operator_guidance}`;
+        }
+        if (input.repairContext.failed_checks?.length) {
+            emitHint += `\nFailed-check evidence from attempt ${input.repairContext.prior_attempt}:\n${JSON.stringify(input.repairContext.failed_checks, null, 2)}`;
+        }
+    }
+    if (input.cloneEmitContext !== undefined) {
+        const allowedActions = input.cloneEmitContext.allowedActions ?? ["skip", "once", "fanout"];
+        const successorLines = input.cloneEmitContext.clonableSuccessors.map((successor) => {
+            const header = `- ${successor.successorId} (clone_cap: ${successor.cloneCap})`;
+            if (successor.cloneInputSchema === undefined) {
+                return header;
+            }
+            return `${header}\n  Assignment schema (clone_input_schema):\n${JSON.stringify(successor.cloneInputSchema, null, 2)}`;
+        });
+        emitHint += `\nClonable successors — emit clone_forks covering each of these ids exactly once:\n${successorLines.join("\n")}`;
+        emitHint += `\nEach once or fanout envelope is a full StageEnvelope — it requires status ("success" or "failure"), summary (non-empty string), and artifacts (array of strings). clone_input_schema fields belong in envelope.payload, not at the top level of the clone_forks item.`;
+        emitHint += `\nAllowed clone actions: ${allowedActions.join(", ")}`;
+    }
+    if (input.feedbackLoopEmitContext !== undefined) {
+        emitHint += `\nFeedback-loop decision: this stage is a feedback-loop source. On status=success, feedback_loop is required. Emit either {"action":"continue"} to proceed downstream or {"action":"send_back","target":"…"} to request another pass.`;
+        emitHint += `\nAllowed send_back target: ${input.feedbackLoopEmitContext.target}.`;
+        emitHint += `\nA send_back decision cannot be combined with fork_choice or clone_forks.`;
+    }
     const attempt = input.roots.attempt ?? 1;
     const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;
     const skillBaseDir = input.stage.skill !== undefined && input.skillFilePath !== undefined
@@ -394,7 +429,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
         `Goal: ${input.task.goal}`,
         input.task.context ? `Context: ${input.task.context}` : "",
         input.task.constraints ? `Constraints: ${input.task.constraints}` : "",
-        formatPriorEnvelope(input.priorEnvelope, input.priorEnvelopes),
+        formatPriorEnvelope(input.priorEnvelope, input.priorEnvelopes, input.priorEnvelopesByStage),
+        input.feedbackLoopContext !== undefined
+            ? formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode)
+            : "",
         "",
         artifactGuidance,
         emitHint,
@@ -409,6 +447,16 @@ export function composeStageUserPrompt(input, emitToolName, emitHintOverride, ar
     }
     return body;
 }
+export function composeFeedbackResumePrompt(input) {
+    if (input.feedbackLoopContext === undefined) {
+        throw new Error("feedback_resume requires feedbackLoopContext");
+    }
+    return [
+        "Continue this stage after feedback-loop send-back.",
+        "Incorporate the operator/source feedback below, then complete the stage (emit an envelope when done).",
+        formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode ?? "feedback_resume"),
+    ].join("\n\n");
+}
 /**
  * DefaultResourceLoader with host/global discovery turned off.
  *
@@ -686,12 +734,20 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     const provider = findProviderSupport(input.stage.model);
     const capture = {};
     const askWaitChannel = existingAskWaitChannel ?? new AskOperatorWaitChannel();
-    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext, input.cloneEmitContext);
+    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext, input.cloneEmitContext, {
+        checks: input.stage.pre_emit_checks,
+        readQaTrail: input.readQaTrail,
+    }, input.feedbackLoopEmitContext);
     const emitTool = defineTool(emitDef);
-    const askDef = createAskOperatorTool({
-        requestWait: (prompt) => askWaitChannel.requestWait(prompt),
-    });
-    const askTool = defineTool(askDef);
+    const gateKinds = input.stage.gate_kinds;
+    const includeAsk = gateKinds === undefined || gateKinds.length > 0;
+    const askDef = includeAsk
+        ? createAskOperatorTool({
+            requestWait: (prompt) => askWaitChannel.requestWait(prompt),
+            ...(gateKinds !== undefined ? { allowedKinds: gateKinds } : {}),
+        })
+        : undefined;
+    const askTool = askDef ? defineTool(askDef) : undefined;
     const artifactDef = createWriteStageArtifactTool({
         runWorkspaceDir: roots.runWorkspaceDir,
         stageId: runtimeStageId(input),
@@ -715,7 +771,17 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         restoreProvider = prepared.restore;
     }
     try {
-        const modelRuntime = await ModelRuntime.create(roots.authPath ? { authPath: roots.authPath } : undefined);
+        const modelRuntime = await ModelRuntime.create(roots.authPath
+            ? {
+                authPath: roots.authPath,
+                // ModelRuntime otherwise resolves models.json from getAgentDir(),
+                // which bindPiAgentDirEnv seals to an empty per-attempt sandbox
+                // dir. Point it at the same durable agent dir as authPath so
+                // custom providers (e.g. a self-hosted OpenAI-compatible
+                // gateway) defined there stay usable in sealed stage sessions.
+                modelsPath: path.join(path.dirname(roots.authPath), "models.json"),
+            }
+            : undefined);
         const settingsManager = SettingsManager.inMemory({
             compaction: { enabled: false },
         });
@@ -760,16 +826,18 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                 reason: `Skill "${input.stage.skill}" is not installed`,
             };
         }
-        const customTools = [emitTool, askTool, artifactTool];
+        const customTools = askTool
+            ? [emitTool, askTool, artifactTool]
+            : [emitTool, artifactTool];
         return {
             sessionManager,
             modelRuntime,
             settingsManager,
             loader,
-            tools: resolveStageToolNames(emitDef.name, artifactDef.name, askDef.name),
+            tools: resolveStageToolNames(emitDef.name, artifactDef.name, askDef?.name ?? "ask_operator", gateKinds),
             customTools,
             emitDefName: emitDef.name,
-            askOperatorDefName: askDef.name,
+            ...(askDef ? { askOperatorDefName: askDef.name } : {}),
             artifactDefName: artifactDef.name,
             providerEmitHint: provider?.emitToolHint?.(emitDef.name),
             restoreProvider,
@@ -901,30 +969,65 @@ export class PiAgentAdapter {
         const timeoutMs = input.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
         const askWaitChannel = new AskOperatorWaitChannel();
         const sessionFile = resolveStageSessionFile(input);
+        const sessionMode = input.sessionMode ?? "fresh";
         let sessionManager;
         let resumeWaiting = false;
-        if (existsSync(sessionFile)) {
+        let feedbackResume = false;
+        let forceNewSession = sessionMode === "new_session";
+        if (sessionMode === "feedback_resume") {
+            if (input.feedbackLoopContext === undefined) {
+                throw new StageSessionReconstructError(`feedback_resume requires feedbackLoopContext: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            }
+            if (!existsSync(sessionFile)) {
+                throw new StageSessionReconstructError(`stage session file missing for feedback_resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            }
             try {
                 sessionManager = SessionManager.open(sessionFile, path.dirname(sessionFile), input.roots.cwd);
             }
             catch (err) {
-                throw new StageSessionReconstructError(`stage session file corrupt or unreadable for resume: ${sessionFile}`, {
+                throw new StageSessionReconstructError(`stage session file corrupt or unreadable for feedback_resume: ${sessionFile}`, {
                     stageId: runtimeStageId(input),
                     sessionFile,
                     cause: err,
                 });
             }
             ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
-            if (!findOpenToolCall(sessionManager)) {
-                throw new StageSessionReconstructError(`stage session has no open tool call for resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            feedbackResume = true;
+        }
+        else if (sessionMode !== "new_session") {
+            if (sessionMode === "waiting_resume" || existsSync(sessionFile)) {
+                if (existsSync(sessionFile)) {
+                    try {
+                        sessionManager = SessionManager.open(sessionFile, path.dirname(sessionFile), input.roots.cwd);
+                    }
+                    catch (err) {
+                        throw new StageSessionReconstructError(`stage session file corrupt or unreadable for resume: ${sessionFile}`, {
+                            stageId: runtimeStageId(input),
+                            sessionFile,
+                            cause: err,
+                        });
+                    }
+                    ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
+                    if (!findOpenToolCall(sessionManager)) {
+                        throw new StageSessionReconstructError(`stage session has no open tool call for resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+                    }
+                    resumeWaiting = true;
+                }
+                else {
+                    throw new StageSessionReconstructError(`stage session file missing for resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+                }
             }
-            resumeWaiting = true;
         }
         let session;
         let wiring;
         let unsubscribeProgress;
         let prepareError;
         const preparePromise = (async () => {
+            if (forceNewSession) {
+                await mkdir(path.dirname(sessionFile), { recursive: true });
+                await writeFile(sessionFile, "");
+                sessionManager = undefined;
+            }
             if (!sessionManager) {
                 sessionManager = await createStageSessionManager(input.roots, runtimeStageId(input), sessionFile);
             }
@@ -987,6 +1090,11 @@ export class PiAgentAdapter {
             },
             run: async () => {
                 return runWithTimeout(async () => {
+                    if (feedbackResume) {
+                        syncAgentMessagesFromSession(session, sessionManager);
+                        await session.prompt(composeFeedbackResumePrompt(input));
+                        return;
+                    }
                     const userPrompt = composeStageUserPrompt(input, wiring.emitDefName, wiring.providerEmitHint, wiring.artifactDefName);
                     await session.prompt(userPrompt);
                 });

package/dist/agent/port.d.ts

@@ -1,11 +1,47 @@
-import type { StageEnvelope } from "../types/envelope.js";
+import type { StageEnvelope, TerminalEnvelope } from "../types/envelope.js";
+import type { CompletionContract } from "../types/completion.js";
 import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 import type { StageConfig } from "../types/stage.js";
+import type { FeedbackLoopConfig } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
 import type { StageActivityEvent } from "./activity.js";
 import type { StageRoots } from "../runtime/stageRoots.js";
+import type { QaExchange } from "../hitl/qaTrail.js";
 /** Opaque to runtime; adapters interpret. */
 export type StageResumeToken = string;
+export type StageSessionMode = "fresh" | "waiting_resume" | "feedback_resume" | "new_session";
+export type StageRepairContext = {
+    prior_attempt: number;
+    /** Operator-authored instructions for an explicitly approved manual retry. */
+    operator_guidance?: string;
+    failed_checks?: Array<{
+        id: string;
+        type: string;
+        evidence_preview?: string;
+    }>;
+};
+export type FeedbackLoopContext = {
+    loop_id: string;
+    replay_id: string;
+    source_stage_id: string;
+    target_stage_id: string;
+    /** Original send-back envelope from the source (feedback + artifacts). */
+    feedback_envelope: StageEnvelope;
+    /** One-based replay number for this send-back. */
+    replay_number: number;
+    max_replays: number;
+    remaining_replays: number;
+    is_final_replay: boolean;
+    replay_session: "resume" | "new_session";
+    /** Persistent stages on the active target→source route, forward order. */
+    route_stage_ids: string[];
+    /** Prior pass/session identity for THIS stage when resuming, if any. */
+    prior_stage_attempt?: number;
+    prior_pass_status?: string;
+    /** Active fork generation for this stage's parent fan-out, if any. */
+    active_fork_generation_id?: string;
+    active_fork_clone_stage_ids?: string[];
+};
 export type StageRunInput = {
     roots: StageRoots;
     stage: StageConfig;
@@ -14,13 +50,26 @@ export type StageRunInput = {
     task: TaskFile;
     priorEnvelope: StageEnvelope | null;
     priorEnvelopes?: StageEnvelope[];
+    priorEnvelopesByStage?: Record<string, TerminalEnvelope | TerminalEnvelope[]>;
     timeoutMs?: number;
     resumeToken?: StageResumeToken;
+    /** Launch/session mode; omitted is treated as `"fresh"`. */
+    sessionMode?: StageSessionMode;
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
     skillFilePath?: string;
     forkEmitContext?: ForkEmitContext;
     cloneEmitContext?: CloneEmitContext;
+    /** Declared source policy; successful emits must continue or send work back. */
+    feedbackLoopEmitContext?: FeedbackLoopConfig;
+    /** Replay context for stages being replayed (and typically the source on send-back). */
+    feedbackLoopContext?: FeedbackLoopContext;
+    /** Frozen pipeline-owned checks that must pass before Stageflow advances. */
+    completionContract?: CompletionContract;
+    /** Compact evidence from the failed verification that triggered this repair. */
+    repairContext?: StageRepairContext;
+    /** Live attempt-scoped QA trail; read at emit execute time, not bootstrap time. */
+    readQaTrail?: () => QaExchange[] | Promise<QaExchange[]>;
 };
 export declare function runtimeStageId(input: Pick<StageRunInput, "stage" | "stageId">): string;
 export type StageRunResult = {

package/dist/agent/resolveAgentPort.d.ts

@@ -0,0 +1,26 @@
+import { type AgentBackendId } from "./agentBackend.js";
+import type { AgentPort } from "./port.js";
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+export type AgentSelection = {
+    /** stageflow.yaml top-level `agent`. */
+    global?: AgentBackendId;
+    /** Pipeline yaml top-level `agent`; overrides global. */
+    pipeline?: AgentBackendId;
+    /** Stage yaml `agent`; would override pipeline/global once enabled. */
+    stage?: AgentBackendId;
+};
+/** stage > pipeline > global > "pi", with stage gated off for now. */
+export declare function resolveAgentBackend(selection?: AgentSelection): AgentBackendId;
+export declare function resolveAgentPort(selection?: AgentSelection): AgentPort;
+/** The global tier's backend id from an already-loaded manifest, or undefined for missing/invalid/unset. */
+export declare function globalAgentBackendFromManifest(manifest: LoadedManifest | null): AgentBackendId | undefined;
+/**
+ * Resolves an AgentPort using only the global (stageflow.yaml) tier — for
+ * the three call sites that construct an agent before any pipeline is
+ * known (`cli.ts`'s ui/mcp servers, `runCommand.ts`, `runsCommand.ts`).
+ * Named explicitly so it's clear these sites are scoped to the global tier
+ * on purpose, not by omission: production stage execution always goes
+ * through `stageWorker.ts`, which resolves the full stage > pipeline >
+ * global chain once it has loaded the specific pipeline and stage.
+ */
+export declare function resolveGlobalOnlyAgentPort(projectRoot: string): Promise<AgentPort>;

package/dist/agent/resolveAgentPort.js

@@ -0,0 +1,39 @@
+import { asAgentBackendId, STAGE_LEVEL_AGENT_OVERRIDE_ENABLED, } from "./agentBackend.js";
+import { PiAgentAdapter } from "./piAdapter.js";
+import { ClaudeAgentAdapter } from "./claudeAdapter.js";
+import { loadStageflowManifestOutcome } from "../config/loadStageflowManifest.js";
+/** stage > pipeline > global > "pi", with stage gated off for now. */
+export function resolveAgentBackend(selection = {}) {
+    if (STAGE_LEVEL_AGENT_OVERRIDE_ENABLED && selection.stage !== undefined) {
+        return selection.stage;
+    }
+    return selection.pipeline ?? selection.global ?? "pi";
+}
+export function resolveAgentPort(selection = {}) {
+    const backend = resolveAgentBackend(selection);
+    switch (backend) {
+        case "pi":
+            return new PiAgentAdapter();
+        case "claude":
+            return new ClaudeAgentAdapter();
+    }
+}
+/** The global tier's backend id from an already-loaded manifest, or undefined for missing/invalid/unset. */
+export function globalAgentBackendFromManifest(manifest) {
+    return manifest ? asAgentBackendId(manifest.manifest.agent) : undefined;
+}
+/**
+ * Resolves an AgentPort using only the global (stageflow.yaml) tier — for
+ * the three call sites that construct an agent before any pipeline is
+ * known (`cli.ts`'s ui/mcp servers, `runCommand.ts`, `runsCommand.ts`).
+ * Named explicitly so it's clear these sites are scoped to the global tier
+ * on purpose, not by omission: production stage execution always goes
+ * through `stageWorker.ts`, which resolves the full stage > pipeline >
+ * global chain once it has loaded the specific pipeline and stage.
+ */
+export async function resolveGlobalOnlyAgentPort(projectRoot) {
+    const outcome = await loadStageflowManifestOutcome(projectRoot);
+    return resolveAgentPort({
+        global: outcome.ok ? globalAgentBackendFromManifest(outcome.value) : undefined,
+    });
+}

package/dist/cli/runCommand.js

@@ -1,4 +1,4 @@
-import { PiAgentAdapter } from "../agent/piAdapter.js";
+import { resolveGlobalOnlyAgentPort } from "../agent/resolveAgentPort.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { PipelineValidationError } from "../runtime/pipelineRunner.js";
 import { RunManager } from "../runtime/runManager.js";
@@ -137,7 +137,7 @@ function defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog) {
     return async (input) => {
         const store = createRunStore({ rootDir: projectRoot });
         const manager = new RunManager({
-            agent: new PiAgentAdapter(),
+            agent: await resolveGlobalOnlyAgentPort(projectRoot),
             store,
             cwd,
             projectRoot,