stageflow 0.3.0 → 0.8.0

package/README.md

@@ -36,6 +36,7 @@ The same pipeline runs three ways without rewriting anything:
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` 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/`
 
 ## Installation
@@ -60,6 +61,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):
@@ -155,6 +164,16 @@ 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.
@@ -187,8 +206,10 @@ 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 |
 | [github-release](examples/github-release/) | Dogfood: draft + publish GitHub Release |
 | [ci-validate](examples/ci-validate/) | Strict validate in CI |
 
@@ -203,7 +224,7 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | [docs/README.md](docs/README.md) | Documentation index |
 | [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 run`, `sf envelope`, `sf skills`, `sf validate`, `sf ui`, `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 |

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

package/dist/cli/artifactCommand.js

@@ -0,0 +1,120 @@
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { readRunArtifact } from "../mcp/readArtifact.js";
+import { createRunStore } from "../runstore/createStore.js";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+export const ARTIFACT_USAGE = `Usage:
+  sf artifact read --run <runId> --path <relPath> [--out <file>]`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseArtifactArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    const subcommand = args[0];
+    if (subcommand !== "read") {
+        throw new Error(`Unknown artifact subcommand: ${subcommand}`);
+    }
+    let runId;
+    let artifactPath;
+    let outPath;
+    let help = false;
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--run") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --run");
+            }
+            runId = value;
+        }
+        else if (arg === "--path") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --path");
+            }
+            artifactPath = value;
+        }
+        else if (arg === "--out") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --out");
+            }
+            outPath = value;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, subcommand, runId, artifactPath, outPath };
+}
+function resolveSafeOutPath(outPath, cwd) {
+    const segments = outPath.split(/[/\\]/);
+    if (segments.some((segment) => segment === "..")) {
+        throw new Error("path must not contain .. segments");
+    }
+    const resolved = path.resolve(cwd, outPath);
+    const cwdResolved = path.resolve(cwd);
+    if (!isInsideDir(resolved, cwdResolved)) {
+        throw new Error("output path must resolve under the current working directory");
+    }
+    return resolved;
+}
+export async function runArtifactCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const out = { ...defaultIo, ...options.io };
+    let parsed;
+    try {
+        parsed = parseArtifactArgs(args);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        out.error(ARTIFACT_USAGE);
+        return 1;
+    }
+    if (parsed.help) {
+        out.error(ARTIFACT_USAGE);
+        return 0;
+    }
+    if (parsed.subcommand !== "read") {
+        out.error("Missing artifact subcommand");
+        out.error(ARTIFACT_USAGE);
+        return 1;
+    }
+    if (!parsed.runId || !parsed.artifactPath) {
+        out.error("Missing --run and/or --path");
+        out.error(ARTIFACT_USAGE);
+        return 1;
+    }
+    const store = createRunStore({ rootDir: projectRoot });
+    try {
+        const contents = await readRunArtifact(store, parsed.runId, parsed.artifactPath);
+        if (parsed.outPath !== undefined) {
+            const target = resolveSafeOutPath(parsed.outPath, cwd);
+            writeFileSync(target, contents, "utf8");
+            out.error(`Wrote ${target}`);
+        }
+        else {
+            out.log(contents);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        out.error(message);
+        return 1;
+    }
+}

package/dist/cli/envelopeCommand.d.ts

@@ -0,0 +1,32 @@
+import type { StageEnvelope } from "../types/envelope.js";
+export declare const ENVELOPE_USAGE = "Usage:\n  sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]";
+export type EnvelopeCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export type EnvelopeOutput = StageEnvelope | SyntheticSkippedEnvelope;
+export type SyntheticSkippedEnvelope = {
+    status: "skipped";
+    summary: "stage was fork-skipped";
+    artifacts: [];
+    fork_choice: null;
+};
+type EnvelopeFormat = "envelope" | "handoff";
+type ParsedEnvelopeArgs = {
+    help: boolean;
+    subcommand?: string;
+    runId?: string;
+    stageId?: string;
+    json: boolean;
+    fromPath?: string;
+    detectStageId?: string;
+    format: EnvelopeFormat;
+};
+export declare function parseEnvelopeArgs(args: string[]): ParsedEnvelopeArgs;
+export declare const SYNTHETIC_SKIPPED_ENVELOPE: SyntheticSkippedEnvelope;
+export declare function runEnvelopeCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<EnvelopeCommandIo>;
+}): Promise<number>;
+export {};