stageflow 0.8.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # <img src="ui/public/stageflow-icon.svg" alt="" width="44" height="44" valign="middle"> Stageflow
 
-CLI pipeline runtime for **configurable stages** on [Pi](https://github.com/badlogic/pi-mono), with a local operator console.
+Open-source runtime for **configurable multi-stage agent workflows** with typed handoffs, DAG execution, human gates, MCP, CI, and a local operator console.
 
 [![npm version](https://img.shields.io/npm/v/stageflow)](https://www.npmjs.com/package/stageflow)
 [![npm downloads](https://img.shields.io/npm/dm/stageflow)](https://www.npmjs.com/package/stageflow)
@@ -9,7 +9,7 @@ CLI pipeline runtime for **configurable stages** on [Pi](https://github.com/badl
 [![GitHub issues](https://img.shields.io/github/issues/tejasghutukade/stageflow)](https://github.com/tejasghutukade/stageflow/issues)
 [![CI](https://img.shields.io/github/actions/workflow/status/tejasghutukade/stageflow/ci.yml?branch=main)](https://github.com/tejasghutukade/stageflow/actions/workflows/ci.yml)
 
-Author pipeline-owned YAML in your project. Stageflow runs each stage in a fresh Pi agent session, writes a structured handoff envelope, and keeps run state under `.stageflow/`. Bins: **`sf`** and **`stageflow`**.
+Author pipeline-owned YAML in your project. Stageflow schedules each stage in a fresh agent session, moves context through explicit envelopes and artifacts, and persists run state under `.stageflow/`. [Pi](https://github.com/badlogic/pi-mono) is the current agent execution backend. Bins: **`sf`** and **`stageflow`**.
 
 ## Why Stageflow?
 
@@ -21,7 +21,7 @@ The same pipeline runs three ways without rewriting anything:
 
 - **Locally** — `sf ui` for triage, provider setup, and gate replies
 - **Headless / CI** — `sf validate` and `sf run --json` with predictable exit codes
-- **Via MCP** — Streamable HTTP tools when the console is running
+- **Via MCP** — Streamable HTTP tools when `sf ui` or `sf mcp` is running
 
 **Stageflow is not an SDLC tool.** Software delivery is a popular pattern in fixtures and dogfood flows, but stages are user-authored and domain-agnostic. If you can express a multi-step workflow in YAML, Stageflow can run it on Pi.
 
@@ -31,14 +31,23 @@ 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` is running
+- **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
 - **Parallel stages** — pipeline DAG with fan-out and join (see [YAML catalog](docs/yaml-catalog.md))
 - **Clonable fan-out** — clone one successor N times at completion, then join (see [YAML catalog](docs/yaml-catalog.md#clonable-successors))
 - **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
 
+## Architecture at a glance
+
+![Stageflow architecture: pipeline definitions and operator interfaces drive the orchestration runtime, which coordinates agent execution and persisted state](docs/img/stageflow-architecture.svg)
+
+The scheduler owns orchestration semantics: DAG readiness, bounded parallelism, fan-out/join, conditional routing, retries, skipped branches, and resumable human gates. Agent execution sits behind `AgentPort`; Pi supplies the current coding-agent session, while Stageflow owns pipeline state, stage workspaces, handoff validation, and the interfaces used by the CLI, console, MCP, and CI.
+
+See [Architecture](docs/architecture.md) for component boundaries, execution flow, persistence, recovery behavior, and the tradeoffs behind fresh sessions and explicit handoffs.
+
 ## Installation
 
 Requires **Node.js ≥ 20**.
@@ -117,7 +126,7 @@ sf providers detect
 sf providers source set pi_home    # or sf_owned
 ```
 
-Stageflow is a thin Pi shell — you do not need Pi CLI `/login` as a hard prerequisite if you configure providers via the console or `sf providers`.
+Pi is Stageflow's current agent execution backend. Stageflow owns the workflow layer around it, and you do not need Pi CLI `/login` as a prerequisite when providers are configured through the console or `sf providers`.
 
 Full reference: [docs/providers.md](docs/providers.md)
 
@@ -126,12 +135,12 @@ Full reference: [docs/providers.md](docs/providers.md)
 Start the console with `sf ui` (default `http://127.0.0.1:3847`).
 
 - **Runs** — active and recent pipeline runs, capacity, and status at a glance
-- **Run detail** — stage timeline, transcripts, envelope payloads, and artifact paths
+- **Run detail** — spatial stage map; select a stage for the gated workspace (logs, files, envelopes, HITL). Created runs show **not started** with a **Start run** action until history exists
 - **HITL reply** — answer operator gates (`ask_operator`) without leaving the browser
 - **Pipelines** — browse manifest-declared pipeline definitions
 - **Settings → Providers** — connect model providers (`pi_home` or `sf_owned` credential storage)
 
-*Screenshot coming soon — capture after console polish lands (see `docs/img/`).*
+Brand assets live under `docs/img/` (`stageflow-og.svg`, `stageflow-icon.svg`).
 
 ## Headless / CI
 
@@ -141,7 +150,7 @@ The guest actor is the CLI (`sf` / `stageflow`). `sf ui` and MCP are not require
 sf validate --strict --json
 ```
 
-Validate exits `0` or `1` only (no waiting / `2`). It checks pipeline and stage YAML only; it does not prove provider auth, Task, or checkout.
+Validate exits `0` or `1` only (no waiting / `2`). With no flags, `sf validate` checks pipelines and tasks in the manifest (plus stages). `--pipeline` validates that pipeline and its stages only; `--task` validates that task file. It never proves provider auth or checkout paths.
 
 ```bash
 sf providers login <providerId> --api-key-env <VAR>
@@ -180,11 +189,9 @@ Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository
 
 ## MCP
 
-`sf ui` also serves a Streamable HTTP MCP endpoint at `http://127.0.0.1:3847/mcp` (URL printed on boot). Point a Cursor (or other) MCP client at that URL.
-
-Available tools: `list_pipelines`, `list_tasks`, `list_runs`, `get_health`, `start_run`, `get_run`, `read_artifact`.
+Host MCP via `sf ui` or `sf mcp` at `http://127.0.0.1:3847/mcp` (URL printed on boot). Sessions are the default. Point a Cursor (or other) MCP client at that URL. Do not run both hosts against the same store.
 
-Full reference: [docs/mcp.md](docs/mcp.md)
+HITL-aware tools include `wait_run`, `answer_gate`, and `list_waiting`. Full tool list: [docs/mcp.md](docs/mcp.md).
 
 ## Stageflow vs Conductor
 
@@ -196,7 +203,7 @@ Both projects address multi-step agent workflows. They differ in orchestration m
 | **Orchestration** | Pipeline DAG + stage worker | Jinja routing, no LLM in router |
 | **Unit of work** | Task → Pipeline → Stage attempts | Workflow → Agents |
 | **Handoff** | Typed **envelope** + artifacts | Agent output → context |
-| **Human gates** | Operator console + MCP | Dashboard + TUI fleet |
+| **Human gates** | Console + MCP + harness native question UI | Dashboard + TUI fleet |
 | **Runtime** | Node.js, Pi coding agent | Python, Copilot/Claude SDKs |
 | **Best for** | Personal/team **multi-stage Pi workflows** you define (releases, research, SDLC, …) | Enterprise multi-agent workflows |
 
@@ -210,6 +217,7 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 | [hello-world](examples/hello-world/) | Single stage, domain-neutral |
 | [plan-review](examples/plan-review/) | Multi-stage with operator gate — SDLC-style **example** |
 | [conditional-fork](examples/conditional-fork/) | Exclusive fork routing with operator branch choice |
+| [clonable-fanout](examples/clonable-fanout/) | Clone one successor N times, then join |
 | [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
 | [ci-validate](examples/ci-validate/) | Strict validate in CI |
 
@@ -222,15 +230,17 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | Doc | Description |
 |-----|-------------|
 | [docs/README.md](docs/README.md) | Documentation index |
+| [docs/architecture.md](docs/architecture.md) | Runtime components, execution flow, persistence, and design decisions |
 | [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
 | [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
-| [docs/cli-reference.md](docs/cli-reference.md) | `sf run`, `sf envelope`, `sf skills`, `sf validate`, `sf ui`, `sf providers` |
+| [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |
 | [docs/envelopes.md](docs/envelopes.md) | Handoff envelope contract |
 | [docs/hitl.md](docs/hitl.md) | Gate kinds, `--skip-gates`, exit code `2` |
 | [docs/ci.md](docs/ci.md) | `--json`, env vars, GitHub Actions |
 | [docs/mcp.md](docs/mcp.md) | MCP tool reference |
 | [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
 | [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
+| [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |
 | [docs/compare-conductor.md](docs/compare-conductor.md) | Positioning deep dive |
 
 ## Develop from source

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>;