stageflow 0.18.0 → 0.19.0

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/fakeAgent.js

@@ -69,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),

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).
@@ -1028,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) {
@@ -1049,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)) {
@@ -1115,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 };
                 }
@@ -1151,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/mcp/controlTools.js

@@ -183,6 +183,23 @@ export function registerControlTools(server, deps) {
             attemptIndex: result.attemptIndex,
         });
     });
+    server.registerTool("resume_stage", {
+        description: "Resume a stage that failed because it timed out, continuing the same attempt/session (same as POST .../resume). Does not start a new attempt — use retry_stage to start over.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        const result = await manager.resumeTimedOutStage(runId, stageId);
+        if (!result.ok) {
+            return textResult({ ...mapRetryStageFailure(result), status: result.status }, true);
+        }
+        return textResult({
+            runId: result.runId,
+            stageId: result.stageId,
+            attemptIndex: result.attemptIndex,
+        });
+    });
     server.registerTool("abandon_stage", {
         description: "Abandon a running stage (marks it failed/interrupted). Does not dismiss HITL — waiting stages return 409; answer them with answer_gate. There is no run-level cancel tool.",
         inputSchema: z.object({

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.18.0";
+export declare const PACKAGE_VERSION = "0.19.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.18.0";
+export const PACKAGE_VERSION = "0.19.0";

package/dist/runstore/port.js

@@ -12,6 +12,8 @@ export function stageStatusFromEvents(events) {
             status = "failed";
         if (ev.event === "skipped")
             status = "skipped";
+        if (ev.event === "reopened")
+            status = "pending";
     }
     return status;
 }

package/dist/runtime/forkGeneration.d.ts

@@ -63,6 +63,10 @@ export declare function selectActiveInput(options: {
     needsStageId: string;
     scheduleOverride?: ReadonlyMap<string, ReadonlySet<string>>;
 }): Promise<ActiveCohort>;
+export declare function forkCohortMapsFromStore(store: Pick<RunStore, "listForkGenerations">, runId: string): Promise<{
+    supersededCloneIds: Set<string>;
+    cohortByForkParent: Map<string, Set<string>>;
+}>;
 export declare function filterJoinInputs(allInstanceIds: readonly string[], cohort: ActiveCohort): string[];
 export declare function filterJoinInstanceIds(allInstanceIds: readonly string[], activeCloneIds: Set<string> | null): string[];
 /**

package/dist/runtime/forkGeneration.js

@@ -251,6 +251,22 @@ export async function selectActiveInput(options) {
     }
     return activeCohortForParent(options.store, options.runId, forkParentId);
 }
+export async function forkCohortMapsFromStore(store, runId) {
+    const gens = await store.listForkGenerations(runId);
+    const supersededCloneIds = new Set();
+    const cohortByForkParent = new Map();
+    for (const gen of gens) {
+        if (gen.status === "superseded") {
+            for (const id of gen.clone_stage_ids) {
+                supersededCloneIds.add(id);
+            }
+        }
+        else if (gen.status === "active") {
+            cohortByForkParent.set(gen.fork_parent_stage_id, new Set(gen.clone_stage_ids));
+        }
+    }
+    return { supersededCloneIds, cohortByForkParent };
+}
 export function filterJoinInputs(allInstanceIds, cohort) {
     if (cohort.kind === "untracked")
         return [...allInstanceIds];

package/dist/runtime/pipelineScheduler.js

@@ -4,7 +4,8 @@ import { definitionIdForInstance } from "../runstore/stageInstanceId.js";
 import { cloneFailureContinuesSchedule, cloneRetryDownstream, cloneFailFastSkipIds, cloneScheduleAllowsRun, failureIsAccepted, isCloneInstance, mint, protectedClonableChildIds, sequentialLaterCloneIds, skipRejectedNeedDependents, } from "./cloneSchedule.js";
 import { buildCompletedEnvelopesFromRun, buildStageConfigById, } from "./envelopeRouting.js";
 import { classifyInboundAfterSuccess, isEagerSingleParentIfSkip, joinAllowsRun, pickStalledJoinSkips, } from "./joinReadiness.js";
-import { forkChoicePreservesReplaySource, mintCohortForFanout, } from "./forkGeneration.js";
+import { reopenRunnableSkippedStages, persistReopenedStages } from "./reopenSkipped.js";
+import { forkChoicePreservesReplaySource, forkCohortMapsFromStore, mintCohortForFanout, } from "./forkGeneration.js";
 import { activeReplayId, activeSourceStageId, applySendBack, createReplaySchedule, hydrateFromStore, isHeld, launchAttemptFor, launchFor, noteActiveCohort, onContinued, onRouteStageFailed, onRouteStageRunning, onRouteStageSucceeded, rebindRouteAttempts, resolveDecision, } from "./replayLifecycle.js";
 import { WAIT_WITHOUT_WORKER_DISPATCH } from "./answerResume.js";
 import { runStage, isRunStageWaiting } from "./stageRunner.js";
@@ -65,6 +66,7 @@ export async function hydrateScheduleFromStore(store, runId, dag, executionMode
             continue;
         schedulingHalted = true;
     }
+    await reopenRunnableSkippedStages(store, runId, resolvedDag, states, completedEnvelopes);
     return {
         states,
         completedEnvelopes,
@@ -85,15 +87,20 @@ export async function hydrateScheduleForRetryRoots(store, runId, dag, retryStage
         }
     }
     const retryRootSet = new Set(retryStageIds);
+    const { supersededCloneIds } = await forkCohortMapsFromStore(store, runId);
     const states = new Map();
     for (const node of resolvedDag.nodes) {
         states.set(node.id, "pending");
     }
     const overrides = new Map();
     for (const rootId of retryStageIds) {
+        if (supersededCloneIds.has(rootId))
+            continue;
         overrides.set(rootId, "pending");
     }
     for (const id of downstream) {
+        if (supersededCloneIds.has(id))
+            continue;
         overrides.set(id, "pending");
     }
     for (const snap of runDetail.stages) {
@@ -104,6 +111,20 @@ export async function hydrateScheduleForRetryRoots(store, runId, dag, retryStage
             completedEnvelopes.delete(id);
         }
     }
+    const skippedToReopen = [];
+    const skipStates = new Map();
+    for (const snap of runDetail.stages) {
+        const id = snap.stage_id;
+        if (supersededCloneIds.has(id))
+            continue;
+        if (snap.status !== "skipped")
+            continue;
+        if (!retryRootSet.has(id) && !downstream.has(id))
+            continue;
+        skippedToReopen.push(id);
+        skipStates.set(id, "skipped");
+    }
+    await persistReopenedStages(store, runId, skippedToReopen, skipStates);
     return {
         states,
         completedEnvelopes,
@@ -752,6 +773,7 @@ export async function runPipelineDag(options) {
                 await persistSkipPending(childId);
             }
         }
+        await reopenRunnableSkippedStages(store, run.runId, dag, states, completedEnvelopes);
     };
     const handlePostSuccessError = async (stageId, reason) => {
         if (states.get(stageId) === "succeeded") {