stageflow 0.16.0 → 0.19.0

package/README.md

@@ -31,13 +31,12 @@ 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))
+- **Verified stage execution** — after-phase `verify` checks with durable evidence, plus `on_verify_fail` repair or manual operator recovery ([guide](docs/verified-stage-execution.md))
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
 - **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
 - **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))
+- **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
 - **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
 
 ## Architecture at a glance
@@ -219,7 +218,6 @@ 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 |
 | [stage-mcp](examples/stage-mcp/) | Stage MCP via project `.mcp.json` and a local echo fixture |
 | [playwright-mcp](examples/playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) |
 | [context7-mcp](examples/context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) |

package/dist/agent/activity.d.ts

@@ -74,6 +74,10 @@ export type StageLifecycleEvent = {
 } | {
     event: "skipped";
 }
+/** A previously skipped stage is runnable again (parent succeeded). */
+ | {
+    event: "reopened";
+}
 /** Operator explicitly authorized a new attempt after verified failure. */
  | {
     event: "manual_recovery_requested";

package/dist/agent/claudeAdapter.js

@@ -47,6 +47,7 @@ import { readActivityVerbose } from "./activity.js";
 import { composeStageUserPrompt } from "./piAdapter.js";
 import { claudeSessionMarkerPath, clearClaudeSessionMarker, readClaudeSessionMarker, writeClaudeSessionMarker, } from "./claudeSession.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen, runtimeStageId, } from "./port.js";
+import { composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
 import { StageMcpError } from "../config/resolveStageMcpServers.js";
 import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 /** Built-in tool allowlist, mirroring Pi's sealed-session base set (read/bash/write/edit). */
@@ -295,6 +296,29 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
             await clearClaudeSessionMarker(markerPath);
             return { kind: "completed", result: { ok: true, envelope: emitCapture.envelope, usage } };
         }
+        if (controller.signal.aborted && sessionId !== undefined) {
+            await writeClaudeSessionMarker(markerPath, { sessionId, usage });
+            return {
+                kind: "completed",
+                result: {
+                    ok: false,
+                    reason: stageTimeoutReason(timeoutMs),
+                    envelope: emitCapture.envelope,
+                    usage,
+                },
+            };
+        }
+        if (controller.signal.aborted) {
+            return {
+                kind: "completed",
+                result: {
+                    ok: false,
+                    reason: stageTimeoutReason(timeoutMs),
+                    envelope: emitCapture.envelope,
+                    usage,
+                },
+            };
+        }
         return {
             kind: "completed",
             result: {
@@ -385,6 +409,20 @@ export class ClaudeAgentAdapter {
                 if (!pre.ok) {
                     return { status: "completed", result: { ok: false, reason: pre.reason } };
                 }
+                if (input.sessionMode === "timeout_resume") {
+                    const marker = await readClaudeSessionMarker(markerPath);
+                    if (marker?.sessionId === undefined) {
+                        return {
+                            status: "completed",
+                            result: {
+                                ok: false,
+                                reason: "missing Claude session to resume; use retry to start a new attempt",
+                            },
+                        };
+                    }
+                    const outcome = await runTurn(input, pre.model, markerPath, composeTimeoutResumePrompt(), marker.sessionId, usage);
+                    return applyOutcome(outcome);
+                }
                 const outcome = await runTurn(input, pre.model, markerPath, composeStageUserPrompt(input, EMIT_STAGE_ENVELOPE_TOOL_NAME, undefined, WRITE_STAGE_ARTIFACT_TOOL_NAME), undefined, usage);
                 return applyOutcome(outcome);
             },

package/dist/agent/claudeTools.d.ts

@@ -45,10 +45,8 @@ export type AskOperatorCapture = {
  * nothing else catches one drifting from the other.
  *
  * Field presence mirrors the typebox schema's own conditionality:
- * `clone_forks` only exists when a stage can clone-fork at all, and
  * `fork_choice` is required (not just present) when the stage has a fork
- * to route. Building this statically would silently offer the model a
- * `clone_forks` field on stages that have nowhere to route one.
+ * to route.
  */
 export declare function buildEmitStageEnvelopeShape(options: {
     forkEmitContext?: ForkEmitContext;
@@ -62,7 +60,6 @@ export declare function buildEmitStageEnvelopeShape(options: {
     artifacts: z.ZodArray<z.ZodString>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     fork_choice: z.ZodArray<z.ZodString> | z.ZodOptional<z.ZodArray<z.ZodString>>;
-    clone_forks?: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>> | undefined;
     checklist_attestations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         check_id: z.ZodString;
         items: z.ZodArray<z.ZodString>;

package/dist/agent/claudeTools.js

@@ -40,10 +40,8 @@ export const ASK_OPERATOR_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__ask_op
  * nothing else catches one drifting from the other.
  *
  * Field presence mirrors the typebox schema's own conditionality:
- * `clone_forks` only exists when a stage can clone-fork at all, and
  * `fork_choice` is required (not just present) when the stage has a fork
- * to route. Building this statically would silently offer the model a
- * `clone_forks` field on stages that have nowhere to route one.
+ * to route.
  */
 export function buildEmitStageEnvelopeShape(options) {
     return {
@@ -54,9 +52,6 @@ export function buildEmitStageEnvelopeShape(options) {
         fork_choice: options.forkEmitContext !== undefined
             ? z.array(z.string())
             : z.array(z.string()).optional(),
-        ...(options.cloneEmitContext !== undefined
-            ? { clone_forks: z.array(z.record(z.string(), z.unknown())) }
-            : {}),
         checklist_attestations: z
             .array(z.object({
             check_id: z.string().min(1),

package/dist/agent/fakeAgent.js

@@ -3,7 +3,6 @@ import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
 import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
-import { assertCloneForks } from "../envelope/cloneForks.js";
 import { assertForkEnvelope } from "../envelope/forkChoice.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
 import { tryParsePendingPrompt } from "../runtime/stageHitl.js";
@@ -70,7 +69,9 @@ export class FakeAgent {
         let started = false;
         let resumeCorrupt = false;
         const sessionMode = input.sessionMode ?? "fresh";
-        const skipHitlPark = sessionMode === "feedback_resume" || sessionMode === "new_session";
+        const skipHitlPark = sessionMode === "feedback_resume" ||
+            sessionMode === "timeout_resume" ||
+            sessionMode === "new_session";
         if (sessionMode === "feedback_resume" && input.feedbackLoopContext === undefined) {
             return createCompletedOnlyStageHandle({
                 stageId: runtimeStageId(input),
@@ -154,15 +155,15 @@ export class FakeAgent {
                 ? behavior.envelope
                 : undefined;
             try {
-                const envelope = assertRequiredEnvelope(envelopeValue);
+                let envelope = assertRequiredEnvelope(envelopeValue);
+                if (envelope.status === "success" && envelope.payload === undefined) {
+                    envelope = { ...envelope, payload: {} };
+                }
                 assertFeedbackLoopAction(envelope, input.feedbackLoopEmitContext);
                 const isFeedbackSendBack = envelope.feedback_loop?.action === "send_back";
                 if (!isFeedbackSendBack && input.forkEmitContext !== undefined) {
                     assertForkEnvelope(envelope, input.forkEmitContext);
                 }
-                if (!isFeedbackSendBack && input.cloneEmitContext !== undefined) {
-                    assertCloneForks(envelope, input.cloneEmitContext);
-                }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);
                 if (!isAdvancingEnvelope(envelope)) {
                     input.onActivity?.({ event: "agent_end" });

package/dist/agent/piAdapter.js

@@ -48,6 +48,7 @@ import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
 import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
 import { addModelUsage, emptyStageUsage } from "../types/usage.js";
+import { TIMEOUT_ABORT_TOOL_RESULT, composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
  * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
@@ -404,23 +405,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             emitHint += `\nFailed-check evidence from attempt ${input.repairContext.prior_attempt}:\n${JSON.stringify(input.repairContext.failed_checks, null, 2)}`;
         }
     }
-    if (input.cloneEmitContext !== undefined) {
-        const allowedActions = input.cloneEmitContext.allowedActions ?? ["skip", "once", "fanout"];
-        const successorLines = input.cloneEmitContext.clonableSuccessors.map((successor) => {
-            const header = `- ${successor.successorId} (clone_cap: ${successor.cloneCap})`;
-            if (successor.cloneInputSchema === undefined) {
-                return header;
-            }
-            return `${header}\n  Assignment schema (io.input.schema):\n${JSON.stringify(successor.cloneInputSchema, null, 2)}`;
-        });
-        emitHint += `\nClonable successors — emit clone_forks covering each of these ids exactly once:\n${successorLines.join("\n")}`;
-        emitHint += `\nEach once or fanout envelope is a full StageEnvelope — it requires status ("success" or "failure"), summary (non-empty string), and artifacts (array of strings). io.input.schema fields belong in envelope.payload, not at the top level of the clone_forks item.`;
-        emitHint += `\nAllowed clone actions: ${allowedActions.join(", ")}`;
-    }
     if (input.feedbackLoopEmitContext !== undefined) {
         emitHint += `\nFeedback-loop decision: this stage is a feedback-loop source. On status=success, feedback_loop is required. Emit either {"action":"continue"} to proceed downstream or {"action":"send_back","target":"…"} to request another pass.`;
         emitHint += `\nAllowed send_back target: ${input.feedbackLoopEmitContext.target}.`;
-        emitHint += `\nA send_back decision cannot be combined with fork_choice or clone_forks.`;
+        emitHint += `\nA send_back decision cannot be combined with fork_choice.`;
     }
     const attempt = input.roots.attempt ?? 1;
     const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;
@@ -1041,6 +1029,7 @@ export class PiAgentAdapter {
         let sessionManager;
         let resumeWaiting = false;
         let feedbackResume = false;
+        let timeoutResume = false;
         let forceNewSession = sessionMode === "new_session";
         if (sessionMode === "feedback_resume") {
             if (input.feedbackLoopContext === undefined) {
@@ -1062,6 +1051,23 @@ export class PiAgentAdapter {
             ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
             feedbackResume = true;
         }
+        else if (sessionMode === "timeout_resume") {
+            if (!existsSync(sessionFile)) {
+                throw new StageSessionReconstructError(`stage session file missing for timeout_resume: ${sessionFile}`, { stageId: runtimeStageId(input), sessionFile });
+            }
+            try {
+                sessionManager = SessionManager.open(sessionFile, path.dirname(sessionFile), input.roots.cwd);
+            }
+            catch (err) {
+                throw new StageSessionReconstructError(`stage session file corrupt or unreadable for timeout_resume: ${sessionFile}`, {
+                    stageId: runtimeStageId(input),
+                    sessionFile,
+                    cause: err,
+                });
+            }
+            ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
+            timeoutResume = true;
+        }
         else if (sessionMode !== "new_session") {
             if (sessionMode === "waiting_resume" || existsSync(sessionFile)) {
                 if (existsSync(sessionFile)) {
@@ -1128,13 +1134,17 @@ export class PiAgentAdapter {
                 const workPromise = work();
                 const abortPromise = new Promise((_, reject) => {
                     controller.signal.addEventListener("abort", () => {
-                        reject(new Error(`stage timed out after ${timeoutMs}ms`));
+                        void session?.abort();
+                        reject(new Error(stageTimeoutReason(timeoutMs)));
                     });
                 });
                 await Promise.race([workPromise, abortPromise]);
                 return { ...resultFromCapture(wiring.capture), usage: wiring.usage };
             }
             catch (err) {
+                if (sessionManager) {
+                    ensureStageSessionFlushed(sessionManager, runtimeStageId(input));
+                }
                 if (wiring.capture.envelope && isAdvancingEnvelope(wiring.capture.envelope)) {
                     return { ok: true, envelope: wiring.capture.envelope, usage: wiring.usage };
                 }
@@ -1164,6 +1174,15 @@ export class PiAgentAdapter {
                         await session.prompt(composeFeedbackResumePrompt(input));
                         return;
                     }
+                    if (timeoutResume) {
+                        syncAgentMessagesFromSession(session, sessionManager);
+                        if (findOpenToolCall(sessionManager)) {
+                            injectOpaqueAnswerIntoSession(sessionManager, TIMEOUT_ABORT_TOOL_RESULT);
+                            syncAgentMessagesFromSession(session, sessionManager);
+                        }
+                        await session.prompt(composeTimeoutResumePrompt());
+                        return;
+                    }
                     const userPrompt = composeStageUserPrompt(input, wiring.emitDefName, wiring.providerEmitHint, wiring.artifactDefName);
                     await session.prompt(userPrompt);
                 });

package/dist/agent/port.d.ts

@@ -11,7 +11,7 @@ import type { QaExchange } from "../hitl/qaTrail.js";
 import type { StageUsage } from "../types/usage.js";
 /** Opaque to runtime; adapters interpret. */
 export type StageResumeToken = string;
-export type StageSessionMode = "fresh" | "waiting_resume" | "feedback_resume" | "new_session";
+export type StageSessionMode = "fresh" | "waiting_resume" | "feedback_resume" | "timeout_resume" | "new_session";
 export type StageRepairContext = {
     prior_attempt: number;
     /** Operator-authored instructions for an explicitly approved manual retry. */

package/dist/agent/stageTimeout.d.ts

@@ -0,0 +1,9 @@
+export declare const STAGE_TIMEOUT_REASON_PREFIX = "stage timed out after ";
+export declare function stageTimeoutReason(timeoutMs: number): string;
+export declare function isStageTimeoutReason(reason: string | undefined): boolean;
+export declare function lastFailedReason(events: ReadonlyArray<{
+    event: string;
+    reason?: string;
+}>): string | undefined;
+export declare const TIMEOUT_ABORT_TOOL_RESULT = "Command aborted: the stage timed out. Continue without a debugger. Do not use --inspect or --inspect-brk.";
+export declare function composeTimeoutResumePrompt(): string;

package/dist/agent/stageTimeout.js

@@ -0,0 +1,24 @@
+export const STAGE_TIMEOUT_REASON_PREFIX = "stage timed out after ";
+export function stageTimeoutReason(timeoutMs) {
+    return `${STAGE_TIMEOUT_REASON_PREFIX}${timeoutMs}ms`;
+}
+export function isStageTimeoutReason(reason) {
+    return (typeof reason === "string" && reason.startsWith(STAGE_TIMEOUT_REASON_PREFIX));
+}
+export function lastFailedReason(events) {
+    let reason;
+    for (const event of events) {
+        if (event.event === "failed")
+            reason = event.reason;
+    }
+    return reason;
+}
+export const TIMEOUT_ABORT_TOOL_RESULT = "Command aborted: the stage timed out. Continue without a debugger. Do not use --inspect or --inspect-brk.";
+export function composeTimeoutResumePrompt() {
+    return [
+        "The previous turn was interrupted because the stage timed out.",
+        "Continue the same work from the conversation above. Do not start over.",
+        "Do not attach a debugger (no --inspect or --inspect-brk).",
+        "Finish the stage and emit the envelope when done.",
+    ].join(" ");
+}

package/dist/cli/graphCommand.d.ts

@@ -0,0 +1,15 @@
+import type { LoadedPipeline } from "../types/pipeline.js";
+export declare const GRAPH_USAGE = "Usage:\n  sf graph --pipeline <path> [--json]\n\n  Prints a definition-time view of how a pipeline graph is wired, before any run.\n  --pipeline loads and resolves the pipeline (same resolution as sf validate / sf run).\n  --json dumps the resolved DAG as JSON instead of the terminal diagram.";
+export type GraphCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runGraphCommand(args: string[], options?: {
+    cwd?: string;
+    projectRoot?: string;
+    io?: Partial<GraphCommandIo>;
+    loadPipeline?: (nameOrPath: string, opts: {
+        cwd?: string;
+        projectRoot?: string;
+    }) => Promise<LoadedPipeline>;
+}): Promise<number>;

package/dist/cli/graphCommand.js

@@ -0,0 +1,79 @@
+import { loadPipeline } from "../config/loadPipeline.js";
+import { renderGraph } from "./graphRender.js";
+export const GRAPH_USAGE = `Usage:
+  sf graph --pipeline <path> [--json]
+
+  Prints a definition-time view of how a pipeline graph is wired, before any run.
+  --pipeline loads and resolves the pipeline (same resolution as sf validate / sf run).
+  --json dumps the resolved DAG as JSON instead of the terminal diagram.`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+function parseGraphArgs(args) {
+    if (args.length === 0) {
+        return { help: false, json: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true, json: false };
+    }
+    let pipeline;
+    let json = false;
+    let help = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else if (arg === "--pipeline") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --pipeline");
+            }
+            pipeline = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg.startsWith("-")) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+    }
+    return { help, pipeline, json };
+}
+export async function runGraphCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const out = { ...defaultIo, ...options.io };
+    const loadPipelineFn = options.loadPipeline ?? loadPipeline;
+    try {
+        const parsed = parseGraphArgs(args);
+        if (parsed.help) {
+            out.error(GRAPH_USAGE);
+            return 0;
+        }
+        if (parsed.pipeline === undefined) {
+            throw new Error("Missing value for --pipeline");
+        }
+        const loaded = await loadPipelineFn(parsed.pipeline, { cwd, projectRoot });
+        if (parsed.json) {
+            out.log(JSON.stringify(loaded.dag, null, 2));
+            return 0;
+        }
+        out.log(renderGraph(loaded.dag));
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Graph command failed";
+        out.error(message);
+        out.error(GRAPH_USAGE);
+        return 1;
+    }
+}

package/dist/cli/graphRender.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedPipelineDag } from "../types/pipeline.js";
+export declare function renderGraph(dag: ResolvedPipelineDag): string;

package/dist/cli/graphRender.js

@@ -0,0 +1,85 @@
+const MAX_WIDTH = 80;
+// Clip to MAX_WIDTH code points so the picture fits an 80-column terminal.
+function clampWidth(text, max = MAX_WIDTH) {
+    const chars = [...text];
+    if (chars.length <= max)
+        return text;
+    return chars.slice(0, max - 1).join("") + "…";
+}
+function cloneModeSuffix(node) {
+    return node.clone_mode ? ` (${node.clone_mode})` : "";
+}
+function buildAnnotations(node) {
+    const parts = [];
+    if (node.entry)
+        parts.push("entry");
+    if (node.clone_cap !== undefined) {
+        parts.push(`clone ${node.clone_cap}${cloneModeSuffix(node)}`);
+    }
+    if (node.replay_safe === false) {
+        parts.push("replay_safe: false");
+    }
+    return parts.join(" · ");
+}
+// loadPipeline returns a topologically ordered DAG, so a DF walk over childrenOf yields a stable, dependency-ordered list.
+function orderedNodeIds(dag) {
+    const visited = new Set();
+    const order = [];
+    const walk = (id) => {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        order.push(id);
+        for (const child of dag.childrenOf[id] ?? [])
+            walk(child);
+    };
+    for (const root of dag.roots)
+        walk(root);
+    for (const node of dag.nodes) {
+        if (!visited.has(node.id))
+            walk(node.id);
+    }
+    return order;
+}
+function cloneBandLabel(node) {
+    if (node.clone_cap === undefined)
+        return "";
+    return ` child~${node.clone_cap}${cloneModeSuffix(node)}`;
+}
+function loopCueLine(node) {
+    if (!node.feedback_loop)
+        return "";
+    const fl = node.feedback_loop;
+    const note = fl.on_max_replays ? `   (${fl.on_max_replays})` : "";
+    return `   ↩ loop ×${fl.max_replays} → ${fl.target}${note}`;
+}
+export function renderGraph(dag) {
+    const byId = new Map(dag.nodes.map((node) => [node.id, node]));
+    const order = orderedNodeIds(dag);
+    const lines = [];
+    const push = (line) => lines.push(clampWidth(line));
+    order.forEach((id, idx) => {
+        const node = byId.get(id);
+        const marker = node.entry ? "▶ " : "  ";
+        const annotations = buildAnnotations(node);
+        push(`${marker}${id}` + (annotations ? `   ${annotations}` : ""));
+        const loopCue = loopCueLine(node);
+        if (loopCue)
+            push(loopCue);
+        if (idx < order.length - 1) {
+            const children = dag.childrenOf[id] ?? [];
+            if (children.length === 1) {
+                push("   │");
+                push(`   ▼${cloneBandLabel(node)}`);
+            }
+            else if (children.length > 1) {
+                children.forEach((childId, ci) => {
+                    const isLast = ci === children.length - 1;
+                    const branch = isLast ? "└─" : "├─";
+                    push(`   ${branch}▶ ${childId}${cloneBandLabel(node)}`);
+                });
+            }
+        }
+    });
+    return lines.join("\n") + "\n";
+}

package/dist/cli/runsCommand.d.ts

@@ -1,6 +1,6 @@
 import type { RunStore } from "../runstore/port.js";
 import { RunManager } from "../runtime/runManager.js";
-export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs rerun --run <runId> [--json]";
+export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs resume --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs rerun --run <runId> [--json]";
 export type RunsCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/runsCommand.js

@@ -24,6 +24,7 @@ export const RUNS_USAGE = `Usage:
   sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
   sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]
   sf runs retry --run <runId> --stage <stageId> [--json]
+  sf runs resume --run <runId> --stage <stageId> [--json]
   sf runs abandon --run <runId> --stage <stageId> [--json]
   sf runs rerun --run <runId> [--json]`;
 const defaultIo = {
@@ -122,6 +123,8 @@ function flagsFor(subcommand) {
             return FEEDBACK_DECIDE_FLAGS;
         case "retry":
             return RETRY_FLAGS;
+        case "resume":
+            return RETRY_FLAGS;
         case "abandon":
             return ABANDON_FLAGS;
         case "rerun":
@@ -675,6 +678,40 @@ export async function runRunsCommand(args, options = {}) {
             }
             return reportCliRun({ kind: "completion", result: result.pipeline }, { json: parsed.json, io: mutatingIo });
         }
+        case "resume": {
+            const blocked = await guardHost();
+            if (blocked !== undefined)
+                return blocked;
+            if (!parsed.runId || !parsed.stageId) {
+                return usageError(out, "Missing --run and/or --stage");
+            }
+            const manager = buildManager();
+            const result = await manager.resumeTimedOutStage(parsed.runId, parsed.stageId);
+            if (!result.ok) {
+                if (parsed.json) {
+                    printJson(out, {
+                        ...mapRetryStageFailure(result),
+                        status: result.status,
+                    });
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            if (parsed.json) {
+                printJson(out, {
+                    ok: true,
+                    runId: result.runId,
+                    stageId: result.stageId,
+                    attemptIndex: result.attemptIndex,
+                });
+            }
+            else {
+                out.log(`ok\t${result.runId}\t${result.stageId}\t${result.attemptIndex}`);
+            }
+            return 0;
+        }
         case "recover": {
             const blocked = await guardHost();
             if (blocked !== undefined)

package/dist/cli.js

@@ -14,6 +14,7 @@ import { RUNS_USAGE, runRunsCommand } from "./cli/runsCommand.js";
 import { resolveOperatorCatalog } from "./cli/operatorCatalog.js";
 import { SKILLS_USAGE, runSkillsCommand } from "./cli/skillsCommand.js";
 import { VALIDATE_USAGE, runValidateCommand } from "./cli/validateCommand.js";
+import { GRAPH_USAGE, runGraphCommand } from "./cli/graphCommand.js";
 import { MIGRATE_YAML_USAGE, runMigrateYamlCommand } from "./cli/migrateYamlCommand.js";
 import { createRunStore } from "./runstore/createStore.js";
 import { resolveStageflowContext } from "./project/resolveStageflowContext.js";
@@ -27,6 +28,7 @@ const USAGE = `Usage:
   sf init
   sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--include stages] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]
   sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]
+  sf graph --pipeline <path> [--json]
   sf migrate-yaml [path] [--root <path>] [--write] [--json] [--force]
   sf artifact read --run <runId> --path <relPath> [--out <file>]
   sf envelope get --run <runId> --stage <stageId> [--json] [--from <sf-run.json>] [--detect-stage <id>] [--format envelope|handoff]
@@ -39,6 +41,7 @@ const USAGE = `Usage:
   sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]
   sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
   sf runs retry --run <runId> --stage <stageId> [--json]
+  sf runs resume --run <runId> --stage <stageId> [--json]
   sf runs abandon --run <runId> --stage <stageId> [--json]
   sf runs rerun --run <runId> [--json]
   sf ui [--port ${DEFAULT_PORT}] [--mcp-stateless]
@@ -66,6 +69,8 @@ ${RUN_USAGE}
 
 ${VALIDATE_USAGE}
 
+${GRAPH_USAGE}
+
 ${MIGRATE_YAML_USAGE}
 
 ${ARTIFACT_USAGE}
@@ -97,6 +102,7 @@ function parseArgs(argv) {
     const command = args[0];
     if (command === "providers" ||
         command === "validate" ||
+        command === "graph" ||
         command === "migrate-yaml" ||
         command === "run" ||
         command === "init" ||
@@ -285,6 +291,12 @@ async function main(argv) {
                 projectRoot: ctx.projectRoot,
             });
         }
+        if (parsed.command === "graph") {
+            return runGraphCommand(argv.slice(3), {
+                cwd: ctx.invocationCwd,
+                projectRoot: ctx.projectRoot,
+            });
+        }
         if (parsed.command === "migrate-yaml") {
             return runMigrateYamlCommand(argv.slice(3), {
                 cwd: ctx.invocationCwd,

package/dist/config/cloneChain.d.ts

@@ -0,0 +1,12 @@
+import type { PipelineStageRef, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export type DetectedCloneChain = {
+    emitterId: string;
+    cloneChildId: string;
+    joinId: string;
+    arrayField: string;
+    ref: string;
+};
+export declare function detectCloneChains(stages: StageConfig[], refs: PipelineStageRef[], pipelineId: string): LoadOutcome<DetectedCloneChain[]>;
+export declare function applyCloneChains(stages: StageConfig[], refs: PipelineStageRef[], dag: ResolvedPipelineDag, pipelineId: string): LoadOutcome<void>;