stageflow 0.3.0 → 0.9.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.
 
@@ -33,11 +33,20 @@ The same pipeline runs three ways without rewriting anything:
 - **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
 - **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**.
@@ -60,6 +69,14 @@ npm i -g ./stageflow-*.tgz
 
 `better-sqlite3` ships prebuilds for common platforms. `--ignore-scripts` is fine when a prebuild exists. Benign `node-gyp` warnings during install can be ignored if `require("better-sqlite3")` works.
 
+**Harness skills** (Cursor, Claude Code, Codex, Pi, OpenCode) — from a consumer project:
+
+```bash
+npx skills add tejasghutukade/stageflow
+```
+
+Then ask the agent to set up Stageflow. Details: [docs/skills-suite.md](docs/skills-suite.md).
+
 ## Quick start
 
 In a project directory (preferably a git repo):
@@ -108,7 +125,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)
 
@@ -117,12 +134,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
 
@@ -132,7 +149,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>
@@ -155,17 +172,25 @@ The process exits `0` when the Run succeeded, `1` when it failed (including a bu
 
 On a mixed Pipeline, default wait parks the Run (exit `2`). `--skip-gates` fails the Stage (exit `1`). A Pipeline with no HITL does not need the flag.
 
+Post-run extraction (dogfooded in [Archify PR diagrams](examples/archify-on-pr/)):
+
+```bash
+sf run ... --json --include stages > sf-run.json
+sf envelope get --from sf-run.json --stage author-diagrams --format handoff --json
+sf skills install --from-zip <url> --skill-name archify
+```
+
+See [docs/ci.md](docs/ci.md) for the full CI recipe and [`.github/actions/sf-run`](.github/actions/sf-run) composite action.
+
 ## State
 
 Runtime state lives in **`<git-root>/.stageflow/`** when inside a git repository (SQLite + per-run workspaces under `.stageflow/runs/`). Global config and `sf_owned` auth live under **`~/.stageflow/`**. If `.stageflow` is missing and `.software-factory` exists from an older install, the next store open renames it to `.stageflow` once.
 
 ## 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
 
@@ -177,7 +202,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 |
 
@@ -187,8 +212,11 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 
 | Example | Description |
 |---------|-------------|
+| **[archify-on-pr](examples/archify-on-pr/)** | **Featured** — PR diagram automation: conditional fork, skill binding, envelope handoff, GHA deliver |
 | [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 |
 
@@ -201,15 +229,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 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

@@ -68,6 +68,8 @@ export type StageLifecycleEvent = {
 } | {
     event: "failed";
     reason: string;
+} | {
+    event: "skipped";
 };
 export type StageLogLine = StageActivityEvent | StageLifecycleEvent;
 export declare function truncateActivityText(value: unknown, limit?: number): string | undefined;

package/dist/agent/cursorProvider.d.ts

@@ -1,14 +1,5 @@
 import { type StageProviderSupport } from "./providerSupport.js";
-/**
- * Locate the pi-cursor-sdk extension entry without opening full global package
- * discovery. Stages stay sealed; only this allowlisted path is loaded.
- *
- * Resolution order:
- * 1. STAGEFLOW_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
- * 2. Path package from ~/.pi/agent/settings.json (same source interactive pi uses)
- * 3. npm install under ~/.pi/agent/npm/node_modules/pi-cursor-sdk
- * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
- */
+export declare function cursorExtensionEntryInPackage(packageRoot: string): string | undefined;
 export declare function resolveCursorExtensionPath(): string | undefined;
 export declare function isCursorModelRef(modelRef: string): boolean;
 export declare const cursorProviderSupport: StageProviderSupport;

package/dist/agent/cursorProvider.js

@@ -18,8 +18,19 @@ const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
  * 1. STAGEFLOW_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
  * 2. Path package from ~/.pi/agent/settings.json (same source interactive pi uses)
  * 3. npm install under ~/.pi/agent/npm/node_modules/pi-cursor-sdk
+ *    (`dist/index.js` for 0.3+, `src/index.ts` for older publishes)
  * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
  */
+const CURSOR_PACKAGE_ENTRIES = ["dist/index.js", "src/index.ts"];
+export function cursorExtensionEntryInPackage(packageRoot) {
+    for (const rel of CURSOR_PACKAGE_ENTRIES) {
+        const full = path.join(packageRoot, rel);
+        if (existsSync(full)) {
+            return full;
+        }
+    }
+    return undefined;
+}
 export function resolveCursorExtensionPath() {
     const fromEnv = process.env.STAGEFLOW_CURSOR_EXTENSION?.trim();
     if (fromEnv && existsSync(fromEnv)) {
@@ -29,16 +40,13 @@ export function resolveCursorExtensionPath() {
     if (fromSettings) {
         return fromSettings;
     }
-    const npmEntry = path.join(os.homedir(), ".pi", "agent", "npm", "node_modules", "pi-cursor-sdk", "src", "index.ts");
-    if (existsSync(npmEntry)) {
+    const npmEntry = cursorExtensionEntryInPackage(path.join(os.homedir(), ".pi", "agent", "npm", "node_modules", "pi-cursor-sdk"));
+    if (npmEntry) {
         return npmEntry;
     }
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const sibling = path.resolve(here, "../../../pi-cursor-sdk/src/index.ts");
-    if (existsSync(sibling)) {
-        return sibling;
-    }
-    return undefined;
+    const siblingRoot = path.resolve(here, "../../../pi-cursor-sdk");
+    return cursorExtensionEntryInPackage(siblingRoot);
 }
 export function isCursorModelRef(modelRef) {
     const slash = modelRef.indexOf("/");
@@ -60,7 +68,7 @@ function missingExtensionReason(modelRef) {
     return [
         `Model "${modelRef}" requires pi-cursor-sdk, but no extension entry was found.`,
         "Install with `pi install npm:pi-cursor-sdk`, or set STAGEFLOW_CURSOR_EXTENSION",
-        "to the absolute path of pi-cursor-sdk/src/index.ts.",
+        "to the absolute path of pi-cursor-sdk/dist/index.js (or src/index.ts).",
         "Also ensure a Cursor SDK API key is available via Pi /login or CURSOR_API_KEY.",
     ].join(" ");
 }
@@ -130,8 +138,8 @@ function resolveFromPiSettings() {
                 }
             }
         }
-        const declared = path.join(packageRoot, "src", "index.ts");
-        if (existsSync(declared)) {
+        const declared = cursorExtensionEntryInPackage(packageRoot);
+        if (declared) {
             return declared;
         }
     }

package/dist/agent/fakeAgent.js

@@ -2,10 +2,11 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "
 import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.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 { runStageViaOpen } from "./port.js";
+import { runtimeStageId, runStageViaOpen } from "./port.js";
 function opaqueEqual(a, b) {
     if (Object.is(a, b))
         return true;
@@ -83,7 +84,7 @@ export class FakeAgent {
             return answer;
         };
         if (behavior.type === "wait_then_emit") {
-            const loaded = loadFakeHitlResume(input.roots, input.stage.id);
+            const loaded = loadFakeHitlResume(input.roots, runtimeStageId(input));
             if (loaded === "corrupt") {
                 resumeCorrupt = true;
             }
@@ -116,7 +117,7 @@ export class FakeAgent {
             });
         };
         const finishEmit = () => {
-            clearFakeHitlResume(input.roots, input.stage.id);
+            clearFakeHitlResume(input.roots, runtimeStageId(input));
             if (behavior.type === "throw") {
                 input.onActivity?.({ event: "agent_end" });
                 return {
@@ -139,6 +140,9 @@ export class FakeAgent {
                 if (input.forkEmitContext !== undefined) {
                     assertForkEnvelope(envelope, input.forkEmitContext);
                 }
+                if (input.cloneEmitContext !== undefined) {
+                    assertCloneForks(envelope, input.cloneEmitContext);
+                }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);
                 if (!isAdvancingEnvelope(envelope)) {
                     input.onActivity?.({ event: "agent_end" });
@@ -171,7 +175,7 @@ export class FakeAgent {
             }
         };
         return {
-            stageId: input.stage.id,
+            stageId: runtimeStageId(input),
             async next() {
                 if (closed) {
                     return {
@@ -210,7 +214,7 @@ export class FakeAgent {
                         }
                         catch (err) {
                             input.onActivity?.({ event: "agent_end" });
-                            clearFakeHitlResume(input.roots, input.stage.id);
+                            clearFakeHitlResume(input.roots, runtimeStageId(input));
                             return {
                                 status: "completed",
                                 result: {
@@ -227,7 +231,7 @@ export class FakeAgent {
                         answer !== undefined &&
                         !opaqueEqual(answer, expected)) {
                         input.onActivity?.({ event: "agent_end" });
-                        clearFakeHitlResume(input.roots, input.stage.id);
+                        clearFakeHitlResume(input.roots, runtimeStageId(input));
                         return {
                             status: "completed",
                             result: {
@@ -241,7 +245,7 @@ export class FakeAgent {
                     const request = behavior.waitRequests[waitIndex];
                     waitIndex += 1;
                     armWait();
-                    writeFakeHitlResume(input.roots, input.stage.id, {
+                    writeFakeHitlResume(input.roots, runtimeStageId(input), {
                         waitRequests: behavior.waitRequests,
                         expectedAnswers: behavior.expectedAnswers,
                         envelope: behavior.envelope,

package/dist/agent/piAdapter.d.ts

@@ -84,6 +84,7 @@ export declare function createSealedResourceLoader(options: {
 }): DefaultResourceLoader;
 /** Stable Pi session JSONL path under the run workspace stage dir. */
 export declare function stageSessionFilePath(roots: Pick<StageRoots, "runWorkspaceDir" | "attempt">, stageId: string): string;
+export declare function resolveStageSessionFile(input: StageRunInput): string;
 export declare class StageSessionReconstructError extends Error {
     readonly stageId: string;
     readonly sessionFile: string;
@@ -97,7 +98,7 @@ export declare class StageSessionReconstructError extends Error {
  * Create or reopen the durable stage session file under the run workspace.
  * Touches an empty file first so Pi flushes the session header immediately.
  */
-export declare function createStageSessionManager(roots: StageRoots, stageId: string): Promise<SessionManager>;
+export declare function createStageSessionManager(roots: StageRoots, stageId: string, sessionFile?: string): Promise<SessionManager>;
 /**
  * Open an existing stage session for post-restart reconstruct.
  * Missing or corrupt files fail closed (KTD7) — never create a fresh session.

package/dist/agent/piAdapter.js

@@ -43,7 +43,7 @@ import "./cursorProvider.js";
 import { findProviderSupport } from "./providerSupport.js";
 import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
 import { createStageActivityObserver, } from "./activityObserver.js";
-import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen } from "./port.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
@@ -365,7 +365,7 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
         emitHint += `\nOn status=success, payload is required and must match this JSON Schema:\n${JSON.stringify(input.stage.payload_schema, null, 2)}`;
     }
     const attempt = input.roots.attempt ?? 1;
-    const attemptArtifactsPath = `stages/${input.stage.id}/attempts/${attempt}/artifacts/`;
+    const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;
     const skillBaseDir = input.stage.skill !== undefined && input.skillFilePath !== undefined
         ? path.dirname(input.skillFilePath)
         : undefined;
@@ -390,11 +390,11 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`;
     return [
         `Task id: ${input.task.id}`,
-        `Stage id: ${input.stage.id}`,
+        `Stage id: ${runtimeStageId(input)}`,
         `Goal: ${input.task.goal}`,
         input.task.context ? `Context: ${input.task.context}` : "",
         input.task.constraints ? `Constraints: ${input.task.constraints}` : "",
-        formatPriorEnvelope(input.priorEnvelope),
+        formatPriorEnvelope(input.priorEnvelope, input.priorEnvelopes),
         "",
         artifactGuidance,
         emitHint,
@@ -490,6 +490,10 @@ export function stageSessionFilePath(roots, stageId) {
         : noAttemptContext();
     return ctx.sessionPath(roots.runWorkspaceDir, stageId);
 }
+export function resolveStageSessionFile(input) {
+    return (input.resumeToken ??
+        stageSessionFilePath(input.roots, runtimeStageId(input)));
+}
 export class StageSessionReconstructError extends Error {
     stageId;
     sessionFile;
@@ -504,8 +508,7 @@ export class StageSessionReconstructError extends Error {
  * Create or reopen the durable stage session file under the run workspace.
  * Touches an empty file first so Pi flushes the session header immediately.
  */
-export async function createStageSessionManager(roots, stageId) {
-    const sessionFile = stageSessionFilePath(roots, stageId);
+export async function createStageSessionManager(roots, stageId, sessionFile = stageSessionFilePath(roots, stageId)) {
     await mkdir(path.dirname(sessionFile), { recursive: true });
     if (!(await fileExists(sessionFile))) {
         await writeFile(sessionFile, "");
@@ -683,7 +686,7 @@ 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);
+    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext, input.cloneEmitContext);
     const emitTool = defineTool(emitDef);
     const askDef = createAskOperatorTool({
         requestWait: (prompt) => askWaitChannel.requestWait(prompt),
@@ -691,7 +694,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     const askTool = defineTool(askDef);
     const artifactDef = createWriteStageArtifactTool({
         runWorkspaceDir: roots.runWorkspaceDir,
-        stageId: input.stage.id,
+        stageId: runtimeStageId(input),
         attempt: roots.attempt ?? 1,
     });
     const artifactTool = defineTool(artifactDef);
@@ -788,18 +791,18 @@ function isStageRunResult(value) {
  * Does not auto-continue the model turn — U4 owns the yield loop.
  */
 export async function reconstructStageSessionForAnswer(input, answer) {
-    const sessionManager = await openStageSessionManager(input.roots, input.stage.id);
-    const sessionFile = ensureStageSessionFlushed(sessionManager, input.stage.id);
+    const sessionManager = await openStageSessionManager(input.roots, runtimeStageId(input));
+    const sessionFile = ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
     let injection;
     try {
         injection = injectOpaqueAnswerIntoSession(sessionManager, answer);
     }
     catch (err) {
-        throw new StageSessionReconstructError(`failed to inject answer into stage session: ${sessionFile}`, { stageId: input.stage.id, sessionFile, cause: err });
+        throw new StageSessionReconstructError(`failed to inject answer into stage session: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile, cause: err });
     }
     const wiring = await prepareStageSessionWiring(input, sessionManager);
     if (isStageRunResult(wiring)) {
-        throw new StageSessionReconstructError(wiring.ok === false ? wiring.reason : "stage session reconstruct failed", { stageId: input.stage.id, sessionFile });
+        throw new StageSessionReconstructError(wiring.ok === false ? wiring.reason : "stage session reconstruct failed", { stageId: runtimeStageId(input), sessionFile });
     }
     let session;
     try {
@@ -820,7 +823,7 @@ export async function reconstructStageSessionForAnswer(input, answer) {
             modelRuntime: wiring.modelRuntime,
         });
         if (resolved.error || !resolved.model) {
-            throw new StageSessionReconstructError(resolved.error ?? `Model not found: ${input.stage.model}`, { stageId: input.stage.id, sessionFile });
+            throw new StageSessionReconstructError(resolved.error ?? `Model not found: ${input.stage.model}`, { stageId: runtimeStageId(input), sessionFile });
         }
         await session.setModel(resolved.model);
         if (resolved.thinkingLevel) {
@@ -846,7 +849,7 @@ export async function reconstructStageSessionForAnswer(input, answer) {
         wiring.restoreProvider?.();
         if (err instanceof StageSessionReconstructError)
             throw err;
-        throw new StageSessionReconstructError(`failed to reconstruct stage session: ${err instanceof Error ? err.message : String(err)}`, { stageId: input.stage.id, sessionFile, cause: err });
+        throw new StageSessionReconstructError(`failed to reconstruct stage session: ${err instanceof Error ? err.message : String(err)}`, { stageId: runtimeStageId(input), sessionFile, cause: err });
     }
 }
 async function bindStageSession(input, sessionManager, wiring) {
@@ -862,7 +865,7 @@ async function bindStageSession(input, sessionManager, wiring) {
         settingsManager: wiring.settingsManager,
     });
     const session = created.session;
-    ensureStageSessionFlushed(sessionManager, input.stage.id);
+    ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
     await session.bindExtensions({});
     const resolved = resolveCliModel({
         cliModel: input.stage.model,
@@ -897,7 +900,7 @@ export class PiAgentAdapter {
     openStage(input) {
         const timeoutMs = input.timeoutMs ?? DEFAULT_STAGE_TIMEOUT_MS;
         const askWaitChannel = new AskOperatorWaitChannel();
-        const sessionFile = input.resumeToken ?? stageSessionFilePath(input.roots, input.stage.id);
+        const sessionFile = resolveStageSessionFile(input);
         let sessionManager;
         let resumeWaiting = false;
         if (existsSync(sessionFile)) {
@@ -906,14 +909,14 @@ export class PiAgentAdapter {
             }
             catch (err) {
                 throw new StageSessionReconstructError(`stage session file corrupt or unreadable for resume: ${sessionFile}`, {
-                    stageId: input.stage.id,
+                    stageId: runtimeStageId(input),
                     sessionFile,
                     cause: err,
                 });
             }
-            ensureStageSessionFlushed(sessionManager, input.stage.id);
+            ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
             if (!findOpenToolCall(sessionManager)) {
-                throw new StageSessionReconstructError(`stage session has no open tool call for resume: ${sessionFile}`, { stageId: input.stage.id, sessionFile });
+                throw new StageSessionReconstructError(`stage session has no open tool call for resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
             }
             resumeWaiting = true;
         }
@@ -923,7 +926,7 @@ export class PiAgentAdapter {
         let prepareError;
         const preparePromise = (async () => {
             if (!sessionManager) {
-                sessionManager = await createStageSessionManager(input.roots, input.stage.id);
+                sessionManager = await createStageSessionManager(input.roots, runtimeStageId(input), sessionFile);
             }
             const prepared = await prepareStageSessionWiring(input, sessionManager, askWaitChannel);
             if (isStageRunResult(prepared)) {
@@ -975,11 +978,11 @@ export class PiAgentAdapter {
             }
         };
         return createConnectedAskWaitStageHandle({
-            stageId: input.stage.id,
+            stageId: runtimeStageId(input),
             askWaitChannel,
             onBeforeWaitYield: () => {
                 if (sessionManager) {
-                    ensureStageSessionFlushed(sessionManager, input.stage.id);
+                    ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
                 }
             },
             run: async () => {
@@ -992,7 +995,7 @@ export class PiAgentAdapter {
                 ? {
                     onDeliver: (answer) => {
                         if (!sessionManager) {
-                            throw new StageSessionReconstructError("stage session missing during resume deliver", { stageId: input.stage.id, sessionFile });
+                            throw new StageSessionReconstructError("stage session missing during resume deliver", { stageId: runtimeStageId(input), sessionFile });
                         }
                         injectOpaqueAnswerIntoSession(sessionManager, answer);
                         if (session) {
@@ -1002,7 +1005,7 @@ export class PiAgentAdapter {
                     continueRun: async () => {
                         return runWithTimeout(async () => {
                             if (!session || !sessionManager) {
-                                throw new StageSessionReconstructError("stage session missing during resume continue", { stageId: input.stage.id, sessionFile });
+                                throw new StageSessionReconstructError("stage session missing during resume continue", { stageId: runtimeStageId(input), sessionFile });
                             }
                             syncAgentMessagesFromSession(session, sessionManager);
                             await session.agent.continue();
@@ -1014,7 +1017,7 @@ export class PiAgentAdapter {
                 await preparePromise.catch(() => undefined);
                 if (closeOptions?.park) {
                     if (sessionManager) {
-                        ensureStageSessionFlushed(sessionManager, input.stage.id);
+                        ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
                         if (askWaitChannel.hasPending) {
                             await repairPrematureAskOperatorClosure(sessionFile);
                         }

package/dist/agent/port.d.ts

@@ -1,5 +1,5 @@
 import type { StageEnvelope } from "../types/envelope.js";
-import type { ForkEmitContext } from "../types/forkChoice.js";
+import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 import type { StageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
 import type { StageActivityEvent } from "./activity.js";
@@ -9,15 +9,20 @@ export type StageResumeToken = string;
 export type StageRunInput = {
     roots: StageRoots;
     stage: StageConfig;
+    /** Runtime instance id (`work~2`). Defaults to `stage.id` when omitted. */
+    stageId?: string;
     task: TaskFile;
     priorEnvelope: StageEnvelope | null;
+    priorEnvelopes?: StageEnvelope[];
     timeoutMs?: number;
     resumeToken?: StageResumeToken;
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
     skillFilePath?: string;
     forkEmitContext?: ForkEmitContext;
+    cloneEmitContext?: CloneEmitContext;
 };
+export declare function runtimeStageId(input: Pick<StageRunInput, "stage" | "stageId">): string;
 export type StageRunResult = {
     ok: true;
     envelope: StageEnvelope;

package/dist/agent/port.js

@@ -1,3 +1,6 @@
+export function runtimeStageId(input) {
+    return input.stageId ?? input.stage.id;
+}
 /** Thin non-HITL wrapper: open → next; unexpected wait fails closed. */
 export async function runStageViaOpen(port, input) {
     const handle = port.openStage(input);

package/dist/cli/artifactCommand.d.ts

@@ -0,0 +1,10 @@
+export declare const ARTIFACT_USAGE = "Usage:\n  sf artifact read --run <runId> --path <relPath> [--out <file>]";
+export type ArtifactCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runArtifactCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<ArtifactCommandIo>;
+}): Promise<number>;