stageflow 0.9.0 → 0.12.0

package/README.md

@@ -31,6 +31,7 @@ The same pipeline runs three ways without rewriting anything:
 - **Path-based CLI** — `--pipeline` and `--task` take filesystem paths (no bare-id lookup)
 - **Pi-native** — runs on `@earendil-works/pi-coding-agent`; reuse an existing Pi login (`pi_home`) or store credentials in `~/.stageflow/agent/auth.json` (`sf_owned`)
 - **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
+- **Verified stage execution** — pipeline-owned completion checks with durable evidence, automatic repair, and manual recovery ([guide](docs/verified-stage-execution.md))
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
 - **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running

package/dist/agent/activity.d.ts

@@ -70,6 +70,15 @@ export type StageLifecycleEvent = {
     reason: string;
 } | {
     event: "skipped";
+}
+/** Operator explicitly authorized a new attempt after verified failure. */
+ | {
+    event: "manual_recovery_requested";
+    guidance?: string;
+}
+/** Operator chose to leave the verified failure terminal. */
+ | {
+    event: "manual_recovery_stopped";
 };
 export type StageLogLine = StageActivityEvent | StageLifecycleEvent;
 export declare function truncateActivityText(value: unknown, limit?: number): string | undefined;

package/dist/agent/agentBackend.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Known AgentPort backend ids, and the config-hierarchy gate.
+ *
+ * Kept dependency-free (no adapter imports) so config loaders can validate
+ * `agent:` fields without pulling in the actual SDKs.
+ */
+export declare const AGENT_BACKENDS: readonly ["pi", "claude"];
+export type AgentBackendId = (typeof AGENT_BACKENDS)[number];
+export declare function isAgentBackendId(value: string): value is AgentBackendId;
+/** Narrows an already-validated config field; returns undefined for anything else. */
+export declare function asAgentBackendId(value: string | undefined): AgentBackendId | undefined;
+export type ParsedAgentField = {
+    ok: true;
+    value: AgentBackendId | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Validates a raw `agent:` config value (stage, pipeline, or manifest YAML).
+ * Callers own their own error shape (code/category/label differ per site) —
+ * this only owns the one rule that must stay identical everywhere: absent is
+ * fine, present must be a known backend id.
+ */
+export declare function parseAgentField(raw: unknown): ParsedAgentField;
+/**
+ * Stage-level `agent` overrides are parsed and stored on StageConfig, but
+ * intentionally not consulted by resolveAgentBackend while this is false.
+ * Flip to true once per-stage selection is ready to ship; no other change
+ * needed to light it up.
+ */
+export declare const STAGE_LEVEL_AGENT_OVERRIDE_ENABLED = false;

package/dist/agent/agentBackend.js

@@ -0,0 +1,38 @@
+/**
+ * Known AgentPort backend ids, and the config-hierarchy gate.
+ *
+ * Kept dependency-free (no adapter imports) so config loaders can validate
+ * `agent:` fields without pulling in the actual SDKs.
+ */
+export const AGENT_BACKENDS = ["pi", "claude"];
+export function isAgentBackendId(value) {
+    return AGENT_BACKENDS.includes(value);
+}
+/** Narrows an already-validated config field; returns undefined for anything else. */
+export function asAgentBackendId(value) {
+    return value !== undefined && isAgentBackendId(value) ? value : undefined;
+}
+/**
+ * Validates a raw `agent:` config value (stage, pipeline, or manifest YAML).
+ * Callers own their own error shape (code/category/label differ per site) —
+ * this only owns the one rule that must stay identical everywhere: absent is
+ * fine, present must be a known backend id.
+ */
+export function parseAgentField(raw) {
+    if (raw === undefined)
+        return { ok: true, value: undefined };
+    if (typeof raw !== "string" || !isAgentBackendId(raw)) {
+        return {
+            ok: false,
+            message: `agent must be one of ${AGENT_BACKENDS.join(", ")}`,
+        };
+    }
+    return { ok: true, value: raw };
+}
+/**
+ * Stage-level `agent` overrides are parsed and stored on StageConfig, but
+ * intentionally not consulted by resolveAgentBackend while this is false.
+ * Flip to true once per-stage selection is ready to ship; no other change
+ * needed to light it up.
+ */
+export const STAGE_LEVEL_AGENT_OVERRIDE_ENABLED = false;

package/dist/agent/claudeActivity.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Claude Agent SDK message → Pi-agnostic StageActivityEvent mapping.
+ *
+ * `tool_result` blocks in the Anthropic Messages API carry only a
+ * `tool_use_id`, not the tool name, so this mapper is stateful: it remembers
+ * the name for each in-flight tool_use id (set on `tool_start`, consumed on
+ * `tool_end`) the same way Pi's own session already tracks call/response
+ * pairing internally.
+ */
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { type StageActivityEvent } from "./activity.js";
+export type ClaudeActivityMapper = {
+    map(message: SDKMessage): StageActivityEvent[];
+};
+export declare function createClaudeActivityMapper(): ClaudeActivityMapper;

package/dist/agent/claudeActivity.js

@@ -0,0 +1,58 @@
+import { truncateActivityText } from "./activity.js";
+function contentBlocks(content) {
+    if (!Array.isArray(content))
+        return [];
+    return content.filter((block) => block !== null && typeof block === "object");
+}
+export function createClaudeActivityMapper() {
+    const toolNameById = new Map();
+    function map(message) {
+        if (message.type === "assistant") {
+            const events = [];
+            for (const block of contentBlocks(message.message.content)) {
+                if (block.type === "text" && typeof block.text === "string") {
+                    events.push({
+                        event: "message",
+                        role: "assistant",
+                        text: truncateActivityText(block.text),
+                    });
+                }
+                else if (block.type === "tool_use" && typeof block.name === "string") {
+                    const toolCallId = typeof block.id === "string" ? block.id : undefined;
+                    if (toolCallId) {
+                        toolNameById.set(toolCallId, block.name);
+                    }
+                    events.push({
+                        event: "tool_start",
+                        toolName: block.name,
+                        toolCallId,
+                        argsPreview: truncateActivityText(block.input),
+                    });
+                }
+            }
+            return events;
+        }
+        if (message.type === "user") {
+            const events = [];
+            for (const block of contentBlocks(message.message.content)) {
+                if (block.type !== "tool_result")
+                    continue;
+                const toolCallId = typeof block.tool_use_id === "string" ? block.tool_use_id : undefined;
+                const toolName = (toolCallId ? toolNameById.get(toolCallId) : undefined) ?? "unknown";
+                if (toolCallId) {
+                    toolNameById.delete(toolCallId);
+                }
+                events.push({
+                    event: "tool_end",
+                    toolName,
+                    toolCallId,
+                    isError: Boolean(block.is_error),
+                    resultPreview: truncateActivityText(block.content),
+                });
+            }
+            return events;
+        }
+        return [];
+    }
+    return { map };
+}

package/dist/agent/claudeAdapter.d.ts

@@ -0,0 +1,5 @@
+import { type AgentPort, type StageHandle, type StageRunInput, type StageRunResult } from "./port.js";
+export declare class ClaudeAgentAdapter implements AgentPort {
+    openStage(input: StageRunInput): StageHandle;
+    runStage(input: StageRunInput): Promise<StageRunResult>;
+}

package/dist/agent/claudeAdapter.js

@@ -0,0 +1,301 @@
+/**
+ * Claude Agent SDK implementation of AgentPort.
+ *
+ * One turn = one streaming-input `query()` call, spawned as a subprocess by
+ * the SDK. The session is sealed the same way Pi's sealed stage session is:
+ * a custom (not preset) system prompt with nothing appended, no filesystem
+ * settings sources, and a fixed built-in tool allowlist — plus one
+ * in-process MCP server (`buildStageflowMcpServer`) carrying
+ * `emit_stage_envelope`, `write_stage_artifact`, and (when the stage's
+ * `gate_kinds` allow it) `ask_operator`. Permission prompts are bypassed
+ * outright: there is no human attached to a stage session to answer them,
+ * exactly like Pi's sealed session never surfaces an interactive approval
+ * loop either.
+ *
+ * HITL — "never let it go dangling" (confirmed by spike, see the adapter's
+ * plan doc): `ask_operator`'s handler never blocks. It records the prompt
+ * and returns an immediate placeholder result; the tool description tells
+ * the model to stop, and this adapter calls `query.interrupt()` right after
+ * observing that result as a backstop that doesn't depend on the model
+ * cooperating. By the time a stage reports `waiting_for_input`, the Claude
+ * CLI subprocess has already exited on its own — `close({park: true})` has
+ * nothing to flush or kill. The only state that needs to survive a process
+ * restart is the small JSON marker in `claudeSession.ts` (session id + the
+ * exact prompt), not a session file to repair.
+ *
+ * Answering resumes the *same* session (`resume: sessionId`, no
+ * `forkSession`) with a new user turn stating the operator's answer — the
+ * real prior conversation reloads (confirmed by spike), but this is a new
+ * turn on that history, not Pi's mid-thought `continue()`. That gap is
+ * permanent and documented, not a bug to chase.
+ *
+ * Explicitly NOT supported yet, rejected up front with a clear reason
+ * rather than silently misbehaving: `stage.skill` (Pi's `/skill:`
+ * convention has no Claude equivalent wired up yet) and any `stage.model`
+ * outside `anthropic/*` (this backend only runs Claude models).
+ *
+ * Credentials: delegated entirely to the spawned `claude` CLI's own
+ * environment/auth (ANTHROPIC_API_KEY or a logged-in session) — the same
+ * story as running `claude` by hand.
+ */
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { isAdvancingEnvelope } from "../envelope/check.js";
+import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, summarizeAnswer, } from "../tools/askOperator.js";
+import { buildStageflowMcpServer, EMIT_STAGE_ENVELOPE_TOOL_NAME, STAGEFLOW_MCP_SERVER_NAME, WRITE_STAGE_ARTIFACT_TOOL_NAME, ASK_OPERATOR_TOOL_NAME, } from "./claudeTools.js";
+import { createClaudeActivityMapper } from "./claudeActivity.js";
+import { composeStageUserPrompt } from "./piAdapter.js";
+import { claudeSessionMarkerPath, clearClaudeSessionMarker, readClaudeSessionMarker, writeClaudeSessionMarker, } from "./claudeSession.js";
+import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen, runtimeStageId, } from "./port.js";
+/** Built-in tool allowlist, mirroring Pi's sealed-session base set (read/bash/write/edit). */
+const CLAUDE_BUILTIN_TOOLS = ["Read", "Write", "Edit", "Bash"];
+function resolveClaudeModel(stageModel) {
+    const slash = stageModel.indexOf("/");
+    if (slash < 0) {
+        return {
+            ok: false,
+            reason: `stage.model "${stageModel}" must be "anthropic/<model>" to run on the claude agent backend`,
+        };
+    }
+    const provider = stageModel.slice(0, slash);
+    const model = stageModel.slice(slash + 1);
+    if (provider !== "anthropic" || model.length === 0) {
+        return {
+            ok: false,
+            reason: `stage.model "${stageModel}" is not an anthropic model; the claude agent backend only runs anthropic/* models`,
+        };
+    }
+    return { ok: true, model };
+}
+function preflight(input) {
+    if (input.stage.skill !== undefined) {
+        return {
+            ok: false,
+            reason: `stage declares skill "${input.stage.skill}"; the claude agent backend does not support skills yet`,
+        };
+    }
+    return resolveClaudeModel(input.stage.model);
+}
+function resultFromCapture(capture) {
+    if (capture.error && !capture.envelope) {
+        return { ok: false, reason: capture.error };
+    }
+    if (!capture.envelope) {
+        return { ok: false, reason: "missing emit_stage_envelope" };
+    }
+    if (!isAdvancingEnvelope(capture.envelope)) {
+        return { ok: false, reason: "status: failure", envelope: capture.envelope };
+    }
+    return { ok: true, envelope: capture.envelope };
+}
+async function* singleUserMessage(text) {
+    yield {
+        type: "user",
+        message: { role: "user", content: text },
+        parent_tool_use_id: null,
+    };
+}
+/** One `query()` call — either the stage's initial turn or a resume turn. */
+async function runTurn(input, model, markerPath, promptText, resumeSessionId) {
+    const timeoutMs = input.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const activityMapper = createClaudeActivityMapper();
+    const emitCapture = {};
+    const askCapture = {};
+    const gateKinds = input.stage.gate_kinds;
+    const hitlAllowed = gateKinds === undefined || gateKinds.length > 0;
+    input.onActivity?.({ event: "agent_start" });
+    input.onActivity?.({ event: "turn_start" });
+    let sessionId = resumeSessionId;
+    try {
+        const mcpServer = buildStageflowMcpServer({
+            capture: emitCapture,
+            payloadSchema: input.stage.payload_schema,
+            forkEmitContext: input.forkEmitContext,
+            cloneEmitContext: input.cloneEmitContext,
+            preEmitCheckOptions: {
+                checks: input.stage.pre_emit_checks,
+                readQaTrail: input.readQaTrail,
+            },
+            writeStageArtifact: {
+                runWorkspaceDir: input.roots.runWorkspaceDir,
+                stageId: runtimeStageId(input),
+                attempt: input.roots.attempt ?? 1,
+            },
+            ...(hitlAllowed
+                ? {
+                    askOperator: {
+                        capture: askCapture,
+                        ...(gateKinds !== undefined ? { allowedKinds: gateKinds } : {}),
+                    },
+                }
+                : {}),
+        });
+        const stream = query({
+            prompt: singleUserMessage(promptText),
+            options: {
+                abortController: controller,
+                cwd: input.roots.cwd,
+                model,
+                systemPrompt: { type: "custom", prompt: input.stage.system_prompt },
+                settingSources: [],
+                tools: CLAUDE_BUILTIN_TOOLS,
+                mcpServers: { [STAGEFLOW_MCP_SERVER_NAME]: mcpServer },
+                permissionMode: "bypassPermissions",
+                allowDangerouslySkipPermissions: true,
+                persistSession: true,
+                ...(resumeSessionId !== undefined ? { resume: resumeSessionId } : {}),
+            },
+        });
+        for await (const message of stream) {
+            for (const event of activityMapper.map(message)) {
+                input.onActivity?.(event);
+            }
+            if (message.type === "system" && message.subtype === "init") {
+                sessionId = message.session_id;
+                await writeClaudeSessionMarker(markerPath, { sessionId: message.session_id });
+            }
+            if (message.type === "user" &&
+                (emitCapture.envelope !== undefined || askCapture.prompt !== undefined)) {
+                try {
+                    await stream.interrupt();
+                }
+                catch {
+                    // best-effort backstop; a natural stop may have already ended the turn
+                }
+                break;
+            }
+            if (message.type === "result") {
+                break;
+            }
+        }
+        if (askCapture.prompt !== undefined) {
+            const resolvedSessionId = sessionId;
+            if (resolvedSessionId === undefined) {
+                return {
+                    kind: "completed",
+                    result: { ok: false, reason: "ask_operator called but no session_id was observed" },
+                };
+            }
+            await writeClaudeSessionMarker(markerPath, {
+                sessionId: resolvedSessionId,
+                prompt: askCapture.prompt,
+            });
+            return { kind: "waiting", sessionId: resolvedSessionId, request: askCapture.prompt };
+        }
+        await clearClaudeSessionMarker(markerPath);
+        return { kind: "completed", result: resultFromCapture(emitCapture) };
+    }
+    catch (err) {
+        if (askCapture.prompt !== undefined && sessionId !== undefined) {
+            await writeClaudeSessionMarker(markerPath, { sessionId, prompt: askCapture.prompt });
+            return { kind: "waiting", sessionId, request: askCapture.prompt };
+        }
+        if (emitCapture.envelope && isAdvancingEnvelope(emitCapture.envelope)) {
+            await clearClaudeSessionMarker(markerPath);
+            return { kind: "completed", result: { ok: true, envelope: emitCapture.envelope } };
+        }
+        return {
+            kind: "completed",
+            result: {
+                ok: false,
+                reason: err instanceof Error ? err.message : String(err),
+                envelope: emitCapture.envelope,
+            },
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        input.onActivity?.({ event: "agent_end" });
+    }
+}
+function resumePromptText(answer) {
+    return [
+        summarizeAnswer(answer),
+        "",
+        `Continue the stage. Call ${EMIT_STAGE_ENVELOPE_TOOL_NAME} when finished, or ${ASK_OPERATOR_TOOL_NAME} again if you need to ask something else.`,
+    ].join("\n");
+}
+export class ClaudeAgentAdapter {
+    openStage(input) {
+        const stageId = runtimeStageId(input);
+        const markerPath = claudeSessionMarkerPath(input);
+        let closed = false;
+        let bootstrapped = false;
+        let waiting;
+        let pendingAnswer;
+        const applyOutcome = (outcome) => {
+            if (outcome.kind === "waiting") {
+                waiting = { sessionId: outcome.sessionId, prompt: outcome.request };
+                pendingAnswer = undefined;
+                return { status: "waiting_for_input", request: outcome.request };
+            }
+            waiting = undefined;
+            return { status: "completed", result: outcome.result };
+        };
+        return {
+            stageId,
+            async next() {
+                if (closed) {
+                    return { status: "completed", result: { ok: false, reason: "stage handle closed" } };
+                }
+                if (!bootstrapped) {
+                    bootstrapped = true;
+                    const marker = await readClaudeSessionMarker(markerPath);
+                    if (marker?.prompt !== undefined) {
+                        waiting = { sessionId: marker.sessionId, prompt: marker.prompt };
+                    }
+                }
+                if (waiting) {
+                    if (pendingAnswer === undefined) {
+                        return { status: "waiting_for_input", request: waiting.prompt };
+                    }
+                    const rawAnswer = pendingAnswer;
+                    pendingAnswer = undefined;
+                    const prompt = waiting.prompt;
+                    const sessionId = waiting.sessionId;
+                    let parsedAnswer;
+                    try {
+                        parsedAnswer = parseAskOperatorAnswer(rawAnswer);
+                        assertAnswerMatchesPrompt(prompt, parsedAnswer);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        waiting = undefined;
+                        await clearClaudeSessionMarker(markerPath);
+                        return { status: "completed", result: { ok: false, reason: `invalid operator answer: ${message}` } };
+                    }
+                    const pre = preflight(input);
+                    if (!pre.ok) {
+                        waiting = undefined;
+                        await clearClaudeSessionMarker(markerPath);
+                        return { status: "completed", result: { ok: false, reason: pre.reason } };
+                    }
+                    const outcome = await runTurn(input, pre.model, markerPath, resumePromptText(parsedAnswer), sessionId);
+                    return applyOutcome(outcome);
+                }
+                const pre = preflight(input);
+                if (!pre.ok) {
+                    return { status: "completed", result: { ok: false, reason: pre.reason } };
+                }
+                const outcome = await runTurn(input, pre.model, markerPath, composeStageUserPrompt(input, EMIT_STAGE_ENVELOPE_TOOL_NAME, undefined, WRITE_STAGE_ARTIFACT_TOOL_NAME), undefined);
+                return applyOutcome(outcome);
+            },
+            deliverAnswer(answer) {
+                pendingAnswer = answer;
+            },
+            async close(closeOptions) {
+                closed = true;
+                if (closeOptions?.park) {
+                    // Nothing to flush or kill — by the time a turn reports "waiting",
+                    // its Claude CLI subprocess has already exited on its own and the
+                    // marker file is already durably written.
+                    return;
+                }
+            },
+        };
+    }
+    async runStage(input) {
+        return runStageViaOpen(this, input);
+    }
+}

package/dist/agent/claudeSession.d.ts

@@ -0,0 +1,18 @@
+import type { AskOperatorPrompt } from "../tools/askOperator.js";
+import type { StageRunInput } from "./port.js";
+export type ClaudeSessionMarker = {
+    sessionId: string;
+    prompt?: AskOperatorPrompt;
+};
+/**
+ * Derives a stable, per-attempt path from `input.resumeToken` — the same
+ * value the runtime always recomputes identically for a given
+ * (workspace, stage, attempt), so a later process asking for this stage's
+ * marker lands on the same file. `resumeToken` defaults to Pi's own session
+ * path (`.../pi-session.jsonl`); this adapter writes a sibling file instead
+ * of reusing that path directly, so the two backends never share a file.
+ */
+export declare function claudeSessionMarkerPath(input: StageRunInput): string;
+export declare function readClaudeSessionMarker(markerPath: string): Promise<ClaudeSessionMarker | undefined>;
+export declare function writeClaudeSessionMarker(markerPath: string, marker: ClaudeSessionMarker): Promise<void>;
+export declare function clearClaudeSessionMarker(markerPath: string): Promise<void>;

package/dist/agent/claudeSession.js

@@ -0,0 +1,54 @@
+/**
+ * Claude session continuity marker — the adapter's equivalent of Pi's
+ * session JSONL file, minus the "reconstruct a dangling tool call" problem.
+ *
+ * Under "never let it go dangling" (see claudeAdapter.ts), by the time a
+ * stage is waiting on an operator answer, the Claude CLI subprocess has
+ * already exited cleanly on its own — there is nothing left to reopen or
+ * repair. The only state that needs to survive a process restart is small
+ * enough to write as one JSON file: the Claude `session_id` to resume, and
+ * the exact operator prompt so a later `deliverAnswer()` can be validated
+ * against it (and re-reported unchanged if `next()` is called again before
+ * an answer arrives).
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { runtimeStageId } from "./port.js";
+/**
+ * Derives a stable, per-attempt path from `input.resumeToken` — the same
+ * value the runtime always recomputes identically for a given
+ * (workspace, stage, attempt), so a later process asking for this stage's
+ * marker lands on the same file. `resumeToken` defaults to Pi's own session
+ * path (`.../pi-session.jsonl`); this adapter writes a sibling file instead
+ * of reusing that path directly, so the two backends never share a file.
+ */
+export function claudeSessionMarkerPath(input) {
+    if (input.resumeToken !== undefined && input.resumeToken.trim() !== "") {
+        return path.join(path.dirname(input.resumeToken), "claude-session.json");
+    }
+    return path.join(input.roots.runWorkspaceDir, "stages", runtimeStageId(input), "claude-session.json");
+}
+export async function readClaudeSessionMarker(markerPath) {
+    try {
+        const raw = await readFile(markerPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            typeof parsed.sessionId === "string") {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+export async function writeClaudeSessionMarker(markerPath, marker) {
+    await mkdir(path.dirname(markerPath), { recursive: true });
+    await writeFile(markerPath, JSON.stringify(marker), "utf8");
+}
+export async function clearClaudeSessionMarker(markerPath) {
+    await rm(markerPath, { force: true });
+}

package/dist/agent/claudeTools.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 { type McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { type EmitCapture } from "../tools/emitStageEnvelope.js";
+import { type WriteStageArtifactOptions } from "../tools/writeStageArtifact.js";
+import { type AskOperatorKind, type AskOperatorPrompt } from "../tools/askOperator.js";
+import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
+import type { PreEmitCheckOptions } from "../envelope/preEmitChecks.js";
+export declare const STAGEFLOW_MCP_SERVER_NAME = "stageflow";
+export declare const EMIT_STAGE_ENVELOPE_TOOL_NAME = "mcp__stageflow__emit_stage_envelope";
+export declare const WRITE_STAGE_ARTIFACT_TOOL_NAME = "mcp__stageflow__write_stage_artifact";
+export declare const ASK_OPERATOR_TOOL_NAME = "mcp__stageflow__ask_operator";
+export type AskOperatorCapture = {
+    prompt?: AskOperatorPrompt;
+};
+/**
+ * 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 declare function buildEmitStageEnvelopeShape(options: {
+    forkEmitContext?: ForkEmitContext;
+    cloneEmitContext?: CloneEmitContext;
+}): {
+    status: z.ZodEnum<{
+        failure: "failure";
+        success: "success";
+    }>;
+    summary: z.ZodString;
+    artifacts: z.ZodArray<z.ZodString>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    fork_choice: z.ZodArray<z.ZodString> | z.ZodOptional<z.ZodArray<z.ZodString>>;
+    clone_forks?: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>> | undefined;
+    checklist_attestations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        check_id: z.ZodString;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    stage_id: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodString>;
+};
+/** Exported for the same parity-test reason as `emitStageEnvelopeShape` above. */
+export declare const writeStageArtifactShape: {
+    path: z.ZodString;
+    content: z.ZodString;
+};
+export declare function buildStageflowMcpServer(options: {
+    capture: EmitCapture;
+    payloadSchema?: unknown;
+    forkEmitContext?: ForkEmitContext;
+    cloneEmitContext?: CloneEmitContext;
+    preEmitCheckOptions?: PreEmitCheckOptions;
+    writeStageArtifact: WriteStageArtifactOptions;
+    askOperator?: {
+        capture: AskOperatorCapture;
+        allowedKinds?: readonly AskOperatorKind[];
+    };
+}): McpServerConfig;