stageflow 0.16.0 → 0.19.0

package/dist/runtime/resumeTimedOut.js

@@ -0,0 +1,165 @@
+import { existsSync } from "node:fs";
+import { fakeHitlResumePath } from "../agent/fakeAgent.js";
+import { definitionIdForInstance } from "../runstore/stageInstanceId.js";
+import { attemptSessionPath } from "../runstore/workspaceLayout.js";
+import { WAIT_WITHOUT_WORKER_DISPATCH } from "./answerResume.js";
+import { resumeRun } from "./pipelineScheduler.js";
+import { loadRunContext } from "./resumeReconstruct.js";
+import { isRunStageWaiting, runStage } from "./stageRunner.js";
+import { attemptContext } from "./stageAttemptContext.js";
+import { openStageAttempt, } from "./stageAttemptBootstrap.js";
+import { buildStageRoots, withResolvedAuthPath } from "./stageRoots.js";
+import { isStageTimeoutReason, lastFailedReason, } from "../agent/stageTimeout.js";
+import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
+export function assertTimedOutStageEligible(status, events) {
+    if (status !== "failed") {
+        return {
+            ok: false,
+            reason: `Stage is not timed out (status=${status})`,
+            status: 409,
+        };
+    }
+    if (!isStageTimeoutReason(lastFailedReason(events))) {
+        return {
+            ok: false,
+            reason: "Stage did not fail due to timeout; use retry to start a new attempt",
+            status: 409,
+        };
+    }
+    return { ok: true };
+}
+export async function reconstructTimedOutAndContinue(ctx) {
+    const { runId, stageId, agent, store, cwd } = ctx;
+    const factoryCwd = ctx.factoryCwd ?? cwd;
+    try {
+        const latestExecution = await store.getLatestStageExecution(runId, stageId);
+        const attempt = latestExecution?.attempt ?? 1;
+        const attemptCtx = attemptContext(attempt);
+        const attemptOpt = attemptCtx.eventOptions();
+        const { meta, task, loaded } = await loadRunContext(store, runId, cwd);
+        const definitionId = definitionIdForInstance(meta.pipeline_dag, stageId);
+        const stageIndex = loaded.stages.findIndex((s) => s.id === definitionId);
+        if (stageIndex < 0) {
+            const reason = `Stage ${stageId} not in pipeline ${meta.pipeline_id}`;
+            await store.appendStageEvent(runId, stageId, { event: "failed", reason }, attemptOpt);
+            await store.updateRunStatus(runId, "failed");
+            return { ok: false, reason };
+        }
+        const stage = loaded.stages[stageIndex];
+        const dag = meta.pipeline_dag ?? loaded.dag;
+        const workspaceDir = store.getWorkspaceDir(runId);
+        const checkoutRoot = meta.checkout_root;
+        const roots = withResolvedAuthPath(buildStageRoots(workspaceDir, stageId, checkoutRoot, attemptCtx), factoryCwd);
+        const sessionFile = attemptSessionPath(workspaceDir, stageId, attempt);
+        const fakeResume = fakeHitlResumePath(roots, stageId);
+        if (!existsSync(sessionFile) && !existsSync(fakeResume)) {
+            return {
+                ok: false,
+                reason: "missing session to resume; use retry to start a new attempt",
+            };
+        }
+        const resumed = { event: "resumed" };
+        await store.appendStageEvent(runId, stageId, resumed, attemptOpt);
+        try {
+            const execution = await store.getStageExecution(runId, stageId, attempt);
+            const patch = deriveExecutionPatchFromEvent(resumed, execution);
+            if (Object.keys(patch).length > 0) {
+                await store.updateStageExecution(runId, stageId, attempt, patch);
+            }
+        }
+        catch {
+            // no execution row yet
+        }
+        await store.updateRunStatus(runId, "running");
+        const opened = await openStageAttempt({
+            agent,
+            store,
+            runId,
+            stage,
+            stageId,
+            task,
+            dag,
+            checkoutRoot,
+            workspaceDir,
+            factoryCwd,
+            attemptCtx,
+            operatorCatalog: ctx.operatorCatalog,
+            sessionMode: "timeout_resume",
+            resumeToken: sessionFile,
+            onActivity: (event) => {
+                void store.appendStageEvent(runId, stageId, event, attemptOpt);
+            },
+        });
+        if (!opened.ok) {
+            await store.appendStageEvent(runId, stageId, { event: "failed", reason: opened.reason }, attemptOpt);
+            await store.updateRunStatus(runId, "failed");
+            return { ok: false, reason: opened.reason };
+        }
+        const result = await runStage({
+            agent,
+            store,
+            runId,
+            stage,
+            stageId,
+            task,
+            dag,
+            checkoutRoot,
+            workspaceDir,
+            hitl: ctx.hitl,
+            skipStarted: true,
+            existingHandle: opened.handle,
+            attemptCtx,
+            factoryCwd,
+            operatorCatalog: ctx.operatorCatalog,
+            sessionMode: "timeout_resume",
+            resumeToken: sessionFile,
+        });
+        if (isRunStageWaiting(result)) {
+            await store.updateRunStatus(runId, "failed");
+            return {
+                ok: false,
+                reason: WAIT_WITHOUT_WORKER_DISPATCH,
+            };
+        }
+        if (!result.ok) {
+            await store.updateRunStatus(runId, "failed");
+            return { ok: false, reason: result.reason };
+        }
+        const rest = await resumeRun({
+            prepared: {
+                task,
+                loaded,
+                run: { runId, workspaceDir },
+                agent,
+                store,
+                cwd,
+                projectRoot: factoryCwd,
+                checkoutRoot,
+                hitl: ctx.hitl,
+                operatorCatalog: ctx.operatorCatalog,
+            },
+            maxActiveStagesPerRun: ctx.maxActiveStagesPerRun,
+            resumeFromStageId: stageId,
+            initialPrior: result.envelope ?? null,
+            executionMode: ctx.executionMode,
+            stageProcessLauncher: ctx.stageProcessLauncher,
+        });
+        if (rest.outcome === "failed") {
+            return { ok: false, reason: rest.reason };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : `timeout resume failed: ${String(err)}`;
+        try {
+            const latestExecution = await store.getLatestStageExecution(runId, stageId);
+            const attemptCtx = attemptContext(latestExecution?.attempt ?? 1);
+            await store.appendStageEvent(runId, stageId, { event: "failed", reason }, attemptCtx.eventOptions());
+            await store.updateRunStatus(runId, "failed");
+        }
+        catch {
+            // ignore secondary failures
+        }
+        return { ok: false, reason };
+    }
+}

package/dist/runtime/routeIfEval.d.ts

@@ -0,0 +1,3 @@
+import type { RouteIfPredicate } from "../types/pipeline.js";
+export type RouteIfEval = "fire" | "miss" | "missing_field";
+export declare function evaluateRouteIf(predicate: RouteIfPredicate, payload: Record<string, unknown> | undefined): RouteIfEval;

package/dist/runtime/routeIfEval.js

@@ -0,0 +1,94 @@
+const NUMERIC_OPS = new Set(["gt", "gte", "lt", "lte"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+function isRouteIfLeaf(predicate) {
+    return "op" in predicate && predicate.op !== undefined && typeof predicate.field === "string";
+}
+function readPayloadPath(payload, field) {
+    if (payload === undefined)
+        return { ok: false };
+    const segments = field.split(".");
+    let current = payload;
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (!isPlainObject(current) || !hasOwn(current, segment)) {
+            return { ok: false };
+        }
+        current = current[segment];
+        if (i < segments.length - 1 && !isPlainObject(current)) {
+            return { ok: false };
+        }
+    }
+    return { ok: true, value: current };
+}
+function compareLeaf(op, actual, expected) {
+    if (op === "eq")
+        return actual === expected ? "fire" : "miss";
+    if (op === "ne")
+        return actual !== expected ? "fire" : "miss";
+    if (NUMERIC_OPS.has(op)) {
+        if (typeof actual !== "number" || !Number.isFinite(actual))
+            return "miss";
+        if (typeof expected !== "number" || !Number.isFinite(expected))
+            return "miss";
+        if (op === "gt")
+            return actual > expected ? "fire" : "miss";
+        if (op === "gte")
+            return actual >= expected ? "fire" : "miss";
+        if (op === "lt")
+            return actual < expected ? "fire" : "miss";
+        if (op === "lte")
+            return actual <= expected ? "fire" : "miss";
+    }
+    if (op === "in") {
+        if (!Array.isArray(expected))
+            return "miss";
+        return expected.includes(actual) ? "fire" : "miss";
+    }
+    if (op === "not_in") {
+        if (!Array.isArray(expected))
+            return "miss";
+        return expected.includes(actual) ? "miss" : "fire";
+    }
+    return "miss";
+}
+export function evaluateRouteIf(predicate, payload) {
+    if ("all" in predicate && predicate.all !== undefined) {
+        let anyMiss = false;
+        for (const child of predicate.all) {
+            const result = evaluateRouteIf(child, payload);
+            if (result === "missing_field")
+                return "missing_field";
+            if (result === "miss")
+                anyMiss = true;
+        }
+        return anyMiss ? "miss" : "fire";
+    }
+    if ("any" in predicate && predicate.any !== undefined) {
+        let anyFire = false;
+        for (const child of predicate.any) {
+            const result = evaluateRouteIf(child, payload);
+            if (result === "missing_field")
+                return "missing_field";
+            if (result === "fire")
+                anyFire = true;
+        }
+        return anyFire ? "fire" : "miss";
+    }
+    if ("not" in predicate && predicate.not !== undefined) {
+        const result = evaluateRouteIf(predicate.not, payload);
+        if (result === "missing_field")
+            return "missing_field";
+        return result === "fire" ? "miss" : "fire";
+    }
+    if (!isRouteIfLeaf(predicate))
+        return "missing_field";
+    const read = readPayloadPath(payload, predicate.field);
+    if (!read.ok)
+        return "missing_field";
+    return compareLeaf(predicate.op, read.value, predicate.value);
+}

package/dist/runtime/runManager.d.ts

@@ -135,6 +135,7 @@ export declare class RunManager {
     }): Promise<StartRunResult>;
     rerun(runId: string): Promise<StartRunResult>;
     retryStage(runId: string, stageId: string): Promise<RetryStageResult>;
+    resumeTimedOutStage(runId: string, stageId: string): Promise<RetryStageResult>;
     recoverManualStage(runId: string, stageId: string, guidance?: string): Promise<RetryStageResult>;
     recoverManualStageUntilStop(runId: string, stageId: string, guidance?: string): Promise<{
         ok: true;

package/dist/runtime/runManager.js

@@ -3,6 +3,7 @@ import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
 import { loadRunContext } from "./resumeReconstruct.js";
+import { assertTimedOutStageEligible, reconstructTimedOutAndContinue, } from "./resumeTimedOut.js";
 import { loadTaskFromYaml } from "../config/loadTask.js";
 import { deriveStatusFromStages, findUnhandledFailedStage, } from "../runstore/port.js";
 import { PipelineValidationError, startPipeline, } from "./pipelineRunner.js";
@@ -417,6 +418,81 @@ export class RunManager {
     async retryStage(runId, stageId) {
         return this.retryStageInternal(runId, stageId, true);
     }
+    async resumeTimedOutStage(runId, stageId) {
+        const resumeKey = waitKey(runId, stageId);
+        if (this.resumeInFlight.has(resumeKey) || this.retryInFlight.has(resumeKey)) {
+            return {
+                ok: false,
+                reason: `Resume already in progress for run ${runId} stage ${stageId}`,
+                status: 409,
+            };
+        }
+        this.resumeInFlight.add(resumeKey);
+        let detail;
+        try {
+            detail = await this.options.store.readRun(runId);
+        }
+        catch {
+            this.resumeInFlight.delete(resumeKey);
+            return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
+        }
+        const stageSnap = detail.stages.find((s) => s.stage_id === stageId);
+        if (!stageSnap) {
+            this.resumeInFlight.delete(resumeKey);
+            return { ok: false, reason: `Stage not found: ${stageId}`, status: 404 };
+        }
+        const eligibility = assertTimedOutStageEligible(stageSnap.status, stageSnap.events);
+        if (!eligibility.ok) {
+            this.resumeInFlight.delete(resumeKey);
+            return eligibility;
+        }
+        const latest = await this.options.store.getLatestStageExecution(runId, stageId);
+        const attemptIndex = latest?.attempt ?? 1;
+        const wasActive = this.active.has(runId);
+        const tracked = await this.ensureResumeTracked(runId);
+        if (!tracked.ok) {
+            this.resumeInFlight.delete(resumeKey);
+            return { ok: false, reason: tracked.reason, status: 409 };
+        }
+        const insertedForResume = !wasActive;
+        try {
+            const done = reconstructTimedOutAndContinue({
+                runId,
+                stageId,
+                agent: this.options.agent,
+                store: this.options.store,
+                hitl: this.hitl,
+                executionMode: this.executionMode,
+                cwd: this.cwd,
+                maxActiveStagesPerRun: this.maxActiveStagesPerRun,
+                factoryCwd: this.projectRoot,
+                ...(this.stageProcessLauncher !== undefined
+                    ? { stageProcessLauncher: this.stageProcessLauncher }
+                    : {}),
+                ...(this.options.operatorCatalog !== undefined
+                    ? { operatorCatalog: this.options.operatorCatalog }
+                    : {}),
+            });
+            this.registerResumeUntrack(runId, done);
+            const outcome = await done;
+            if (!outcome.ok) {
+                if (insertedForResume) {
+                    this.removeActiveEntry(runId, false);
+                }
+                const missingSession = outcome.reason !== undefined &&
+                    outcome.reason.startsWith("missing session to resume");
+                return {
+                    ok: false,
+                    reason: outcome.reason ?? "timeout resume failed",
+                    status: missingSession ? 409 : 500,
+                };
+            }
+            return { ok: true, runId, stageId, attemptIndex };
+        }
+        finally {
+            this.resumeInFlight.delete(resumeKey);
+        }
+    }
     async recoverManualStage(runId, stageId, guidance) {
         return this.recoverManualStageInternal(runId, stageId, guidance, true);
     }

package/dist/runtime/runRetryCoordinator.js

@@ -25,10 +25,6 @@ export function succeededStageRetryBlocker(stageSnap) {
         stageSnap.definition_id !== stageSnap.stage_id) {
         return `Cannot re-run a succeeded clone instance stage (stage=${stageSnap.stage_id}, definition=${stageSnap.definition_id}): clone instances are created by upstream fan-out and cannot be rebuilt in place. Use rerun to start a new run.`;
     }
-    const forks = stageSnap.envelope?.clone_forks;
-    if (Array.isArray(forks) && forks.length > 0) {
-        return `Cannot re-run a succeeded clonable-fanout stage (stage=${stageSnap.stage_id}): its envelope declared clone_forks and existing clone instances cannot be pruned. Use rerun to start a new run.`;
-    }
     if (stageSnap.envelope?.fork_choice !== undefined) {
         return `Cannot re-run a succeeded fork stage (stage=${stageSnap.stage_id}): its envelope recorded a fork_choice and skipped branches cannot be restored. Use rerun to start a new run.`;
     }

package/dist/runtime/stageAttemptBootstrap.js

@@ -4,7 +4,9 @@ import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError,
 import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
+import { assertPriorInputPayload, payloadInstanceMismatch, } from "../envelope/payloadSchema.js";
 import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
+import { assignment } from "./cloneSchedule.js";
 import { resumeSessionFilePath } from "./stageAttemptContext.js";
 import { buildStageRoots, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
 async function resolveStageSkillForRun(stage, catalog) {
@@ -76,6 +78,51 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
         };
     }
 }
+function assertPriorsMatchCloneInput(cloneInputSchema, childId, priorResult, task, skipCloneAssignment) {
+    if (cloneInputSchema === undefined)
+        return { ok: true };
+    if (skipCloneAssignment)
+        return { ok: true };
+    try {
+        if (priorResult.priorEnvelopesByStage !== undefined) {
+            for (const value of Object.values(priorResult.priorEnvelopesByStage)) {
+                const envelopes = Array.isArray(value) ? value : [value];
+                for (const envelope of envelopes) {
+                    if (envelope.status !== "success")
+                        continue;
+                    assertPriorInputPayload(envelope, cloneInputSchema, childId);
+                }
+            }
+            return { ok: true };
+        }
+        if (priorResult.joinPriors !== undefined) {
+            for (const envelope of priorResult.joinPriors) {
+                if (envelope.status !== "success")
+                    continue;
+                assertPriorInputPayload(envelope, cloneInputSchema, childId);
+            }
+            return { ok: true };
+        }
+        if (priorResult.prior !== null) {
+            assertPriorInputPayload(priorResult.prior, cloneInputSchema, childId);
+            return { ok: true };
+        }
+        const details = payloadInstanceMismatch(task.input ?? {}, cloneInputSchema);
+        if (details !== undefined) {
+            return {
+                ok: false,
+                reason: `task input does not match io.input.schema for ${childId}: ${details}`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 function resolveAttemptRoots(input, stageId) {
     const baseRoots = input.roots ??
         (input.workerRoots
@@ -136,15 +183,20 @@ export async function openStageAttempt(input) {
     const definitionId = input.stage.id;
     const completedEnvelopes = input.completedEnvelopes ??
         (await buildCompletedEnvelopesFromRun(input.store, input.runId, undefined, input.dag));
-    const priorResult = await resolvePriorEnvelope({
-        dag: input.dag,
-        stageId,
-        completedEnvelopes,
-        store: input.store,
-        runId: input.runId,
-    });
+    const assigned = assignment(input.dag, stageId, definitionId, completedEnvelopes);
+    const priorResult = assigned ??
+        (await resolvePriorEnvelope({
+            dag: input.dag,
+            stageId,
+            completedEnvelopes,
+            store: input.store,
+            runId: input.runId,
+        }));
     if (!priorResult.ok)
         return priorResult;
+    const priorInput = assertPriorsMatchCloneInput(input.stage.clone_input_schema, stageId, priorResult, input.task, false);
+    if (!priorInput.ok)
+        return priorInput;
     const roots = resolveAttemptRoots(input, stageId);
     const attempt = input.attemptCtx?.attempt ?? 1;
     const resumeToken = input.resumeToken ??
@@ -152,9 +204,6 @@ export async function openStageAttempt(input) {
     const forkEmitContext = resolveForkEmitContext(input.dag, definitionId);
     const snapshot = input.dag;
     const cloneEmitContext = resolveCloneEmitContext(input.dag, definitionId, {
-        ...(input.stage.clone_actions !== undefined
-            ? { allowedActions: input.stage.clone_actions }
-            : {}),
         ...(snapshot.clone_input_schema !== undefined
             ? { successorCloneInputSchemas: snapshot.clone_input_schema }
             : {}),
@@ -163,7 +212,7 @@ export async function openStageAttempt(input) {
     const runtimeNode = input.dag.nodes.find((node) => node.id === stageId);
     const isDynamicCloneInstance = runtimeNode?.definition_id !== undefined &&
         runtimeNode.definition_id !== runtimeNode.id;
-    const feedbackLoopEmitContext = isDynamicCloneInstance || runtimeNode?.clonable === true
+    const feedbackLoopEmitContext = isDynamicCloneInstance
         ? undefined
         : runtimeNode?.feedback_loop;
     const repairContext = await repairContextForAttempt(input, stageId, attempt);

package/dist/runtime/stageRecovery.js

@@ -35,10 +35,10 @@ export async function failStageAsInterrupted(options) {
 }
 export async function syncRunStatusFromStages(store, runId) {
     const meta = await store.readRunMeta(runId);
-    if (meta.status === "succeeded")
-        return;
     const run = await store.readRun(runId);
     const derived = deriveStatusFromStages(run.stages, meta.pipeline_dag);
+    if (meta.status === "succeeded" && derived !== "running")
+        return;
     if ((meta.status ?? "created") !== derived) {
         await store.updateRunStatus(runId, derived);
     }

package/dist/runtime/stageRunner.js

@@ -3,6 +3,7 @@ import { buildStageRoots, withResolvedAuthPath, } from "./stageRoots.js";
 import { createDefaultHitlQaHooks, recordWaitEnter, } from "./stageHitl.js";
 import { openStageAttempt, } from "./stageAttemptBootstrap.js";
 import { createVerifiedStageExecution } from "./verifiedStageExecution.js";
+import { isStageTimeoutReason } from "../agent/stageTimeout.js";
 export function isRunStageWaiting(outcome) {
     return "waiting" in outcome && outcome.waiting === true;
 }
@@ -220,7 +221,9 @@ export async function runStage(options) {
             attemptCtx,
         });
         console.error(`Stage ${stageId} failed: ${reason}`);
-        await handle.close().catch(() => undefined);
+        await handle
+            .close(isStageTimeoutReason(reason) ? { park: true } : undefined)
+            .catch(() => undefined);
         return { ok: false, reason };
     }
     if (isRunStageWaiting(outcome)) {
@@ -251,6 +254,7 @@ export async function runStage(options) {
         });
     }
     finally {
-        await handle.close().catch(() => undefined);
+        const timedOut = isStageTimeoutReason(outcome.ok ? undefined : outcome.reason);
+        await handle.close(timedOut ? { park: true } : undefined).catch(() => undefined);
     }
 }

package/dist/runtime/taskInput.js

@@ -34,21 +34,9 @@ export function checkTaskEntryInput(task, loaded, options) {
         const stage = stageById.get(rootId);
         if (stage?.clone_input_schema === undefined)
             continue;
-        if (task.input === undefined) {
-            findings.push({
-                severity: "warning",
-                code: "task.entry_input_unmet",
-                path: findingPath,
-                message: `Task has no input; entry stage "${rootId}" requires io.input`,
-                category: "task",
-                pipelineId: loaded.pipeline.id,
-                stageId: rootId,
-            });
-            continue;
-        }
         let details;
         try {
-            details = payloadInstanceMismatch(task.input, stage.clone_input_schema);
+            details = payloadInstanceMismatch(task.input ?? {}, stage.clone_input_schema);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/server/http.js

@@ -91,6 +91,7 @@ function isMutatingApi(method, pathname) {
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/answer$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/feedback-decision$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/retry$/.test(pathname) ||
+        /^\/api\/runs\/[^/]+\/stages\/[^/]+\/resume$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/recovery$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/recovery\/stop$/.test(pathname) ||
         /^\/api\/runs\/[^/]+\/stages\/[^/]+\/abandon$/.test(pathname) ||
@@ -390,6 +391,23 @@ export async function startUiServer(options) {
                     });
                     return true;
                 }
+                const resumeMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/resume$/);
+                if (method === "POST" && resumeMatch) {
+                    await readJsonBody(req);
+                    const runId = decodeURIComponent(resumeMatch[1] ?? "");
+                    const stageId = decodeURIComponent(resumeMatch[2] ?? "");
+                    const result = await manager.resumeTimedOutStage(runId, stageId);
+                    if (!result.ok) {
+                        json(res, result.status ?? 500, mapRetryStageFailure(result));
+                        return true;
+                    }
+                    json(res, 202, {
+                        runId: result.runId,
+                        stageId: result.stageId,
+                        attemptIndex: result.attemptIndex,
+                    });
+                    return true;
+                }
                 const recoverMatch = pathname.match(/^\/api\/runs\/([^/]+)\/stages\/([^/]+)\/recovery$/);
                 if (method === "POST" && recoverMatch) {
                     let body;

package/dist/tools/askOperator.d.ts

@@ -330,6 +330,7 @@ export declare function createAskOperatorTool(options: AskOperatorToolOptions):
         artifacts: Type.TArray<Type.TString>;
         id: Type.TOptional<Type.TString>;
     }>)[]]>;
+    prepareArguments: (args: unknown) => never;
     execute: (_toolCallId: string, params: unknown) => Promise<{
         content: {
             type: "text";

package/dist/tools/askOperator.js

@@ -9,6 +9,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
+import { prepareAskOperatorArguments } from "./prepareToolArguments.js";
 export class AskOperatorError extends Error {
     constructor(message) {
         super(message);
@@ -168,10 +169,11 @@ function parseSubQuestion(value, path) {
     };
 }
 export function parseAskOperatorParams(value) {
-    if (!isRecord(value)) {
+    const prepared = prepareAskOperatorArguments(value);
+    if (!isRecord(prepared)) {
         throw new AskOperatorError("ask_operator params must be an object");
     }
-    const kind = value.kind;
+    const kind = prepared.kind;
     if (typeof kind !== "string") {
         throw new AskOperatorError("kind is required");
     }
@@ -181,36 +183,36 @@ export function parseAskOperatorParams(value) {
         kind !== "artifact_backed") {
         throw new AskOperatorError(`unsupported prompt kind "${kind}" (allowed: free_text, confirm, multi_question, artifact_backed)`);
     }
-    const id = optionalId(value.id, "id");
+    const id = optionalId(prepared.id, "id");
     if (kind === "free_text" || kind === "confirm") {
         return {
             kind,
-            message: requireNonEmptyString(value.message, "message"),
+            message: requireNonEmptyString(prepared.message, "message"),
             ...(id !== undefined ? { id } : {}),
         };
     }
     if (kind === "artifact_backed") {
-        if (!Array.isArray(value.artifacts)) {
+        if (!Array.isArray(prepared.artifacts)) {
             throw new AskOperatorError("artifacts must be an array");
         }
-        if (value.artifacts.length < 1) {
+        if (prepared.artifacts.length < 1) {
             throw new AskOperatorError("artifacts must contain at least one path");
         }
-        const artifacts = value.artifacts.map((item, index) => requireNonEmptyString(item, `artifacts[${index}]`));
+        const artifacts = prepared.artifacts.map((item, index) => requireNonEmptyString(item, `artifacts[${index}]`));
         return {
             kind,
-            message: requireNonEmptyString(value.message, "message"),
+            message: requireNonEmptyString(prepared.message, "message"),
             artifacts,
             ...(id !== undefined ? { id } : {}),
         };
     }
-    if (!Array.isArray(value.questions)) {
+    if (!Array.isArray(prepared.questions)) {
         throw new AskOperatorError("questions must be an array");
     }
-    if (value.questions.length < 1) {
+    if (prepared.questions.length < 1) {
         throw new AskOperatorError("questions must contain at least one item");
     }
-    const questions = value.questions.map((item, index) => parseSubQuestion(item, `questions[${index}]`));
+    const questions = prepared.questions.map((item, index) => parseSubQuestion(item, `questions[${index}]`));
     return {
         kind,
         questions,
@@ -401,6 +403,7 @@ export function createAskOperatorTool(options) {
         label: "Ask operator",
         description: `Ask the operator a question and wait for their answer. Supports ${kindList} prompts. Does not complete the stage — call emit_stage_envelope when finished.`,
         parameters: askOperatorParamsSchemaFor(allowedKinds),
+        prepareArguments: prepareAskOperatorArguments,
         execute: async (_toolCallId, params) => {
             let prompt;
             try {