stageflow 0.19.0 → 0.25.0

package/dist/runstore/submission.js

@@ -0,0 +1,7 @@
+export class RunSubmissionExistsError extends Error {
+    submission;
+    constructor(submission) {
+        super("Run submission already exists");
+        this.submission = submission;
+    }
+}

package/dist/runstore/workspaceLayout.d.ts

@@ -2,6 +2,7 @@ export { stageDir } from "./paths.js";
 export declare function guardStageId(stageId: string): void;
 export declare function attemptWorkspaceDir(workspaceDir: string, stageId: string, attempt: number): string;
 export declare function attemptLogPath(workspaceDir: string, stageId: string, attempt: number): string;
+export declare function attemptStreamLogPath(workspaceDir: string, stageId: string, attempt: number): string;
 export declare function attemptEnvelopePath(workspaceDir: string, stageId: string, attempt: number): string;
 export declare function attemptArtifactsDir(workspaceDir: string, stageId: string, attempt: number): string;
 export declare function attemptAgentDir(workspaceDir: string, stageId: string, attempt: number): string;

package/dist/runstore/workspaceLayout.js

@@ -21,6 +21,9 @@ export function attemptWorkspaceDir(workspaceDir, stageId, attempt) {
 export function attemptLogPath(workspaceDir, stageId, attempt) {
     return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), "log.jsonl");
 }
+export function attemptStreamLogPath(workspaceDir, stageId, attempt) {
+    return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), "stream.log");
+}
 export function attemptEnvelopePath(workspaceDir, stageId, attempt) {
     return path.join(attemptWorkspaceDir(workspaceDir, stageId, attempt), "envelope.json");
 }

package/dist/runtime/feedbackLoopCoordinator.d.ts

@@ -1,5 +1,5 @@
 import type { FeedbackLoopContext, StageSessionMode } from "../agent/port.js";
-import type { DeferredFeedbackSendBack, FeedbackLoopRecord, FeedbackReplayRecord, RunStore } from "../runstore/port.js";
+import type { DeferredFeedbackSendBack, FeedbackLoopRecord, FeedbackReplayRecord, FeedbackReplayStagePassStatus, RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { ResolvedPipelineDag, ResolvedPipelineStageNode } from "../types/pipeline.js";
 import type { FeedbackScheduleState } from "./feedbackLoopSchedule.js";
@@ -38,6 +38,14 @@ export type FeedbackSendBackRejected = {
 };
 export type FeedbackSendBackResult = FeedbackSendBackAccepted | FeedbackSendBackIdempotent | FeedbackSendBackWaitingForHuman | FeedbackSendBackRejected;
 export declare function terminalizeCurrentFeedbackReplay(store: RunStore, runId: string, loop: FeedbackLoopRecord, status: Extract<FeedbackReplayRecord["status"], "completed" | "failed" | "waiting_for_human">): Promise<void>;
+export declare function updateFeedbackReplaySourcePass(options: {
+    store: RunStore;
+    runId: string;
+    loop: FeedbackLoopRecord;
+    sourceStageId: string;
+    status: Extract<FeedbackReplayStagePassStatus, "waiting" | "succeeded" | "failed">;
+    envelope?: StageEnvelope;
+}): Promise<void>;
 export declare function acceptFeedbackSendBack(options: {
     store: RunStore;
     runId: string;

package/dist/runtime/feedbackLoopCoordinator.js

@@ -10,6 +10,33 @@ export async function terminalizeCurrentFeedbackReplay(store, runId, loop, statu
         return;
     await store.updateFeedbackReplay(runId, loop.current_replay_id, { status });
 }
+export async function updateFeedbackReplaySourcePass(options) {
+    const { store, runId, loop, sourceStageId, status, envelope } = options;
+    if (loop.current_replay_id === undefined)
+        return;
+    const passes = await store.listFeedbackReplayStagePasses(runId, loop.current_replay_id);
+    const sourcePass = passes.find((pass) => pass.stage_id === sourceStageId);
+    if (sourcePass === undefined)
+        return;
+    if (sourcePass.status === "succeeded")
+        return;
+    if (status === "waiting") {
+        await store.updateFeedbackReplayStagePass(runId, loop.current_replay_id, sourceStageId, { status: "waiting" });
+        return;
+    }
+    if (status === "succeeded") {
+        await store.updateFeedbackReplayStagePass(runId, loop.current_replay_id, sourceStageId, {
+            status: "succeeded",
+            finished_at: new Date().toISOString(),
+            ...(envelope !== undefined ? { emitted_envelope: envelope } : {}),
+        });
+        return;
+    }
+    await store.updateFeedbackReplayStagePass(runId, loop.current_replay_id, sourceStageId, {
+        status: "failed",
+        finished_at: new Date().toISOString(),
+    });
+}
 async function resolveResumeSessionAttempt(store, runId, loopId, stageId, fallbackAttempt) {
     const replays = await store.listFeedbackReplays(runId, loopId);
     for (const replay of replays) {
@@ -182,6 +209,13 @@ export async function acceptFeedbackSendBack(options) {
                 source_attempt: sourceAttempt,
             };
             await terminalizeCurrentFeedbackReplay(store, runId, loop, "waiting_for_human");
+            await updateFeedbackReplaySourcePass({
+                store,
+                runId,
+                loop,
+                sourceStageId: sourceNode.id,
+                status: "waiting",
+            });
             await store.updateFeedbackLoop(runId, loop.loop_id, {
                 state: "waiting_for_human",
                 deferred_send_back: deferred,
@@ -205,15 +239,14 @@ export async function acceptFeedbackSendBack(options) {
         };
     }
     if (loop.current_replay_id !== undefined) {
-        const currentPasses = await store.listFeedbackReplayStagePasses(runId, loop.current_replay_id);
-        const sourcePass = currentPasses.find((p) => p.stage_id === sourceNode.id);
-        if (sourcePass !== undefined && sourcePass.status !== "succeeded") {
-            await store.updateFeedbackReplayStagePass(runId, loop.current_replay_id, sourceNode.id, {
-                status: "succeeded",
-                finished_at: new Date().toISOString(),
-                emitted_envelope: envelope,
-            });
-        }
+        await updateFeedbackReplaySourcePass({
+            store,
+            runId,
+            loop,
+            sourceStageId: sourceNode.id,
+            status: "succeeded",
+            envelope,
+        });
         await store.updateFeedbackReplay(runId, loop.current_replay_id, {
             status: "completed",
         });
@@ -301,17 +334,14 @@ export async function markFeedbackLoopContinued(options) {
         (entry.state === "active" || entry.state === "waiting_for_human"));
     if (loop === undefined)
         return;
-    if (loop.current_replay_id !== undefined) {
-        const passes = await store.listFeedbackReplayStagePasses(runId, loop.current_replay_id);
-        const sourcePass = passes.find((p) => p.stage_id === sourceStageId);
-        if (sourcePass !== undefined && sourcePass.status !== "succeeded") {
-            await store.updateFeedbackReplayStagePass(runId, loop.current_replay_id, sourceStageId, {
-                status: "succeeded",
-                finished_at: new Date().toISOString(),
-                emitted_envelope: envelope,
-            });
-        }
-    }
+    await updateFeedbackReplaySourcePass({
+        store,
+        runId,
+        loop,
+        sourceStageId,
+        status: "succeeded",
+        envelope,
+    });
     await terminalizeCurrentFeedbackReplay(store, runId, loop, "completed");
     await store.updateFeedbackLoop(runId, loop.loop_id, {
         state: "continued",

package/dist/runtime/feedbackLoopDecision.js

@@ -1,7 +1,19 @@
-import { terminalizeCurrentFeedbackReplay } from "./feedbackLoopCoordinator.js";
+import { terminalizeCurrentFeedbackReplay, updateFeedbackReplaySourcePass, } from "./feedbackLoopCoordinator.js";
 import { createFeedbackScheduleState } from "./feedbackLoopSchedule.js";
 import { applySendBack, releaseHold, } from "./replayLifecycle.js";
 const DECISION_CONFLICT = "feedback loop decision conflict: no longer waiting_for_human";
+async function appendFeedbackLoopDecided(store, runId, loop, decision, reason) {
+    const latest = await store.getLatestStageExecution(runId, loop.source_stage_id);
+    const attempt = latest?.attempt;
+    const eventOptions = attempt !== undefined ? { attempt } : undefined;
+    const trimmed = reason?.trim();
+    await store.appendStageEvent(runId, loop.source_stage_id, {
+        event: "feedback_loop_decided",
+        decision,
+        loopId: loop.loop_id,
+        ...(trimmed ? { reason: trimmed } : {}),
+    }, eventOptions);
+}
 async function clearSourceWaiting(store, runId, sourceStageId, nextStatus, reason) {
     const latest = await store.getLatestStageExecution(runId, sourceStageId);
     const attempt = latest?.attempt;
@@ -96,6 +108,7 @@ export async function resolveFeedbackLoopDecision(options) {
                 reason: `${DECISION_CONFLICT} (loop=${loop.loop_id})`,
             };
         }
+        await appendFeedbackLoopDecided(store, runId, loop, "extend", options.reason);
         await clearSourceWaiting(store, runId, loop.source_stage_id, "succeeded");
         if (schedule === undefined) {
             const applied = await applySendBack({
@@ -168,8 +181,19 @@ export async function resolveFeedbackLoopDecision(options) {
                 reason: `${DECISION_CONFLICT} (loop=${loop.loop_id})`,
             };
         }
+        await appendFeedbackLoopDecided(store, runId, loop, "continue", options.reason);
         await terminalizeCurrentFeedbackReplay(store, runId, loop, "completed");
         await clearSourceWaiting(store, runId, loop.source_stage_id, "succeeded");
+        await updateFeedbackReplaySourcePass({
+            store,
+            runId,
+            loop,
+            sourceStageId: loop.source_stage_id,
+            status: "succeeded",
+            ...(deferred !== undefined
+                ? { envelope: deferred.feedback_envelope }
+                : {}),
+        });
         if (schedule !== undefined) {
             schedule.states.set(loop.source_stage_id, "succeeded");
             if (schedule.completedEnvelopes.get(loop.source_stage_id) === undefined &&
@@ -190,8 +214,16 @@ export async function resolveFeedbackLoopDecision(options) {
             reason: `${DECISION_CONFLICT} (loop=${loop.loop_id})`,
         };
     }
+    await appendFeedbackLoopDecided(store, runId, loop, "abandon", abandonReason);
     await terminalizeCurrentFeedbackReplay(store, runId, loop, "failed");
     await clearSourceWaiting(store, runId, loop.source_stage_id, "failed", abandonReason);
+    await updateFeedbackReplaySourcePass({
+        store,
+        runId,
+        loop,
+        sourceStageId: loop.source_stage_id,
+        status: "failed",
+    });
     if (schedule !== undefined) {
         schedule.states.set(loop.source_stage_id, "failed");
         releaseHold({ feedback: schedule.feedback });

package/dist/runtime/pipelineRunner.d.ts

@@ -1,9 +1,10 @@
+import type { RunSubmission } from "../runstore/submission.js";
 import type { AgentPort } from "../agent/port.js";
 import { type ValidationFinding } from "../config/validateCatalog.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { StageHitlController } from "./stageHitl.js";
-import type { LoadedPipeline } from "../types/pipeline.js";
+import type { InlinePipelineDefinition, LoadedPipeline } from "../types/pipeline.js";
 import type { TaskFile } from "../types/task.js";
 import { type StageExecutionMode } from "./stageConcurrency.js";
 import { StageProcessLauncher } from "./stageProcessLauncher.js";
@@ -57,7 +58,7 @@ export declare function runPipeline(options: {
     store: RunStore;
     taskPath?: string;
     taskYaml?: string;
-    pipeline: string;
+    pipeline: string | InlinePipelineDefinition;
     cwd?: string;
     projectRoot?: string;
     checkoutOverride?: string;
@@ -70,11 +71,12 @@ export declare function runPipeline(options: {
 }): Promise<PipelineRunResult>;
 /** Create the run immediately, then execute stages in the returned promise. */
 export declare function startPipeline(options: {
+    submission?: RunSubmission;
     agent: AgentPort;
     store: RunStore;
     taskPath?: string;
     taskYaml?: string;
-    pipeline: string;
+    pipeline: string | InlinePipelineDefinition;
     cwd?: string;
     projectRoot?: string;
     checkoutOverride?: string;

package/dist/runtime/pipelineRunner.js

@@ -57,12 +57,15 @@ async function preparePipeline(options) {
         console.error(`${finding.code}: ${finding.message}`);
     }
     const checkoutRoot = await resolveAndValidateCheckout(task, options.checkoutOverride, options.cwd);
-    const pipelinePath = normalizeCatalogPath(loaded.pipelinePath);
+    const pipelinePath = typeof options.pipeline === "string"
+        ? normalizeCatalogPath(loaded.pipelinePath)
+        : undefined;
     const taskPath = options.taskPath
         ? normalizeCatalogPath(path.resolve(options.cwd, options.taskPath))
         : undefined;
     const projectRoot = normalizeCatalogPath(options.projectRoot ?? options.cwd);
     const run = await options.store.createRun({
+        submission: options.submission,
         pipelineId: loaded.pipeline.id,
         taskYaml,
         taskId: task.id,
@@ -74,6 +77,7 @@ async function preparePipeline(options) {
         pipelinePath,
         taskPath,
         projectRoot,
+        inlinePipeline: typeof options.pipeline === "string" ? undefined : options.pipeline,
     });
     const executionMode = readStageExecutionMode(process.env, options.executionMode);
     const stageProcessLauncher = resolveStageProcessLauncher(executionMode, options.stageProcessLauncher);
@@ -143,6 +147,7 @@ export async function startPipeline(options) {
     const cwd = options.cwd ?? process.cwd();
     const projectRoot = options.projectRoot ?? cwd;
     const prepared = await preparePipeline({
+        submission: options.submission,
         agent: options.agent,
         store: options.store,
         taskPath: options.taskPath,

package/dist/runtime/pipelineScheduler.js

@@ -220,6 +220,25 @@ export function applyForkSkipsFromEnvelopes(dag, states, completedEnvelopes) {
         applyForkChoiceToSchedule(dag, node.id, chosen, states);
     }
 }
+async function applyEagerRouteIfSkipsFromEnvelopes(dag, states, completedEnvelopes, persistSkip) {
+    for (const [parentId, envelope] of completedEnvelopes) {
+        if (states.get(parentId) !== "succeeded")
+            continue;
+        for (const childId of dag.childrenOf[parentId] ?? []) {
+            const child = dag.nodes.find((n) => n.id === childId);
+            if (!child)
+                continue;
+            const result = classifyInboundAfterSuccess(child, parentId, envelope.payload);
+            if (result === "missing_field") {
+                return parentId;
+            }
+            if (isEagerSingleParentIfSkip(child, parentId, envelope.payload)) {
+                await persistSkip(childId);
+            }
+        }
+    }
+    return undefined;
+}
 export function applyRetryRootDelta(dag, states, completedEnvelopes, retryRoots, stageId, attempt, clearSchedulingHalt, alreadyLaunchedIds) {
     retryRoots.set(stageId, attempt);
     const downstream = cloneRetryDownstream(dag, [stageId]);
@@ -472,6 +491,13 @@ export async function runPipelineDag(options) {
             await persistSkipPending(id);
         }
     }
+    const missingRouteIfParent = await applyEagerRouteIfSkipsFromEnvelopes(dag, states, completedEnvelopes, persistSkipPending);
+    if (missingRouteIfParent !== undefined) {
+        schedulingHalted = true;
+        if (firstFailureReason === undefined) {
+            firstFailureReason = `stage "${missingRouteIfParent}": route if field missing from payload`;
+        }
+    }
     const markSkippedPending = () => {
         for (const node of dag.nodes) {
             if (states.get(node.id) === "pending") {
@@ -756,22 +782,13 @@ export async function runPipelineDag(options) {
                 await store.appendStageEvent(run.runId, id, { event: "skipped" });
             }
         }
-        const childIds = dag.childrenOf[stageId] ?? [];
-        for (const childId of childIds) {
-            const child = dag.nodes.find((node) => node.id === childId);
-            if (!child)
-                continue;
-            const result = classifyInboundAfterSuccess(child, stageId, envelope.payload);
-            if (result === "missing_field") {
-                schedulingHalted = true;
-                if (firstFailureReason === undefined) {
-                    firstFailureReason = `stage "${stageId}": route if field missing from payload`;
-                }
-                return;
-            }
-            if (isEagerSingleParentIfSkip(child, stageId, envelope.payload)) {
-                await persistSkipPending(childId);
+        const missingParent = await applyEagerRouteIfSkipsFromEnvelopes(dag, states, new Map([[stageId, envelope]]), persistSkipPending);
+        if (missingParent !== undefined) {
+            schedulingHalted = true;
+            if (firstFailureReason === undefined) {
+                firstFailureReason = `stage "${missingParent}": route if field missing from payload`;
             }
+            return;
         }
         await reopenRunnableSkippedStages(store, run.runId, dag, states, completedEnvelopes);
     };

package/dist/runtime/reloadRunCatalog.js

@@ -1,5 +1,5 @@
 import { access } from "node:fs/promises";
-import { loadPipeline } from "../config/loadPipeline.js";
+import { loadPipeline, loadPipelineFromObject } from "../config/loadPipeline.js";
 import { loadTask } from "../config/loadTask.js";
 import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
 function missingLocator(field, runId) {
@@ -33,6 +33,12 @@ async function assertCatalogFileExists(filePath, label) {
 }
 export async function reloadPipelineForRun(meta) {
     const projectRoot = requireProjectRoot(meta);
+    // An inline-pipeline run (no pipeline_path — nothing was ever written to a
+    // catalog file) carries its own pipeline body in meta.inline_pipeline
+    // instead, the same way a task without task_path reloads from task_yaml.
+    if (meta.inline_pipeline) {
+        return loadPipelineFromObject(meta.inline_pipeline, { projectRoot });
+    }
     const pipelinePath = requirePipelinePath(meta);
     await assertCatalogFileExists(pipelinePath, "Pipeline");
     return loadPipeline(pipelinePath, { cwd: projectRoot });

package/dist/runtime/resolveEnvelopeRef.d.ts

@@ -0,0 +1,30 @@
+import { type StoreLookupKind } from "../server/operatorResults.js";
+import type { RunStore } from "../runstore/port.js";
+import type { TaskFile } from "../types/task.js";
+export type EnvelopeRefInput = {
+    runId: string;
+    stageId: string;
+    attempt?: number;
+};
+type EnvelopeRefStore = Pick<RunStore, "readRunMeta" | "readRun" | "readEnvelope">;
+/** Carries enough to map onto either MCP's textResult shape or an A2aApplicationError. */
+export declare class EnvelopeRefError extends Error {
+    readonly status: number;
+    readonly kind: StoreLookupKind;
+    constructor(message: string, status: number, kind: StoreLookupKind);
+}
+/**
+ * Resolves one or more Envelope References (ADR-0002) into a TaskFile for
+ * the next standalone stage call — shared by the MCP run_stage tool and the
+ * A2A run_stage operation so this resolution logic exists in exactly one
+ * place (it was duplicated between them once already; see the reuse finding
+ * from this feature's code review).
+ *
+ * A single ref keeps today's exact shape: goal = its summary, input = its
+ * payload verbatim. Multiple refs namespace each resolved payload under its
+ * stageId (disambiguated by runId only if two refs share a stageId), so a
+ * stage author addresses each source by name in their own io.input.schema
+ * instead of one silently overwriting another on a key collision.
+ */
+export declare function resolveEnvelopeRefsToTask(store: EnvelopeRefStore, refs: EnvelopeRefInput | EnvelopeRefInput[], checkout?: string): Promise<TaskFile>;
+export {};

package/dist/runtime/resolveEnvelopeRef.js

@@ -0,0 +1,79 @@
+import { mapStoreLookupError } from "../server/operatorResults.js";
+/** Carries enough to map onto either MCP's textResult shape or an A2aApplicationError. */
+export class EnvelopeRefError extends Error {
+    status;
+    kind;
+    constructor(message, status, kind) {
+        super(message);
+        this.status = status;
+        this.kind = kind;
+    }
+}
+async function resolveOne(store, ref) {
+    try {
+        await store.readRunMeta(ref.runId);
+    }
+    catch (err) {
+        const mapped = mapStoreLookupError(err, { policy: "run" });
+        throw new EnvelopeRefError(mapped.error, mapped.status, mapped.kind);
+    }
+    try {
+        const detail = await store.readRun(ref.runId);
+        if (!detail.stages.some((s) => s.stage_id === ref.stageId)) {
+            throw new EnvelopeRefError(`Stage not found: ${ref.stageId}`, 404, "not_found");
+        }
+        return await store.readEnvelope(ref.runId, ref.stageId, ref.attempt);
+    }
+    catch (err) {
+        if (err instanceof EnvelopeRefError)
+            throw err;
+        const mapped = mapStoreLookupError(err, { policy: "envelope" });
+        throw new EnvelopeRefError(mapped.error, mapped.status, mapped.kind);
+    }
+}
+/**
+ * Resolves one or more Envelope References (ADR-0002) into a TaskFile for
+ * the next standalone stage call — shared by the MCP run_stage tool and the
+ * A2A run_stage operation so this resolution logic exists in exactly one
+ * place (it was duplicated between them once already; see the reuse finding
+ * from this feature's code review).
+ *
+ * A single ref keeps today's exact shape: goal = its summary, input = its
+ * payload verbatim. Multiple refs namespace each resolved payload under its
+ * stageId (disambiguated by runId only if two refs share a stageId), so a
+ * stage author addresses each source by name in their own io.input.schema
+ * instead of one silently overwriting another on a key collision.
+ */
+export async function resolveEnvelopeRefsToTask(store, refs, checkout) {
+    const list = Array.isArray(refs) ? refs : [refs];
+    const resolved = [];
+    for (const ref of list) {
+        resolved.push({ ref, envelope: await resolveOne(store, ref) });
+    }
+    if (resolved.length === 1) {
+        const { ref, envelope } = resolved[0];
+        return {
+            id: `ref-${ref.runId}-${ref.stageId}`,
+            goal: envelope.summary,
+            input: envelope.payload ?? {},
+            ...(checkout ? { checkout } : {}),
+        };
+    }
+    const usedKeys = new Set();
+    const input = {};
+    const summaryLines = [];
+    for (const { ref, envelope } of resolved) {
+        let key = ref.stageId;
+        if (usedKeys.has(key))
+            key = `${ref.stageId}:${ref.runId}`;
+        usedKeys.add(key);
+        input[key] = envelope.payload ?? {};
+        summaryLines.push(`${key}: ${envelope.summary}`);
+    }
+    return {
+        id: `ref-${list.map((r) => r.stageId).join("+")}`,
+        goal: summaryLines.join("\n"),
+        input,
+        ...(checkout ? { checkout } : {}),
+    };
+}

package/dist/runtime/resumeReconstruct.js

@@ -33,12 +33,12 @@ export async function loadRunContext(store, runId, cwd) {
 }
 export async function reconstructAndContinue(ctx) {
     const { runId, stageId, opaqueAnswer, agent, store, cwd } = ctx;
-    const factoryCwd = ctx.factoryCwd ?? cwd;
     try {
         const latestExecution = await store.getLatestStageExecution(runId, stageId);
         const attemptCtx = attemptContext(latestExecution?.attempt ?? 1);
         const attemptOpt = attemptCtx.eventOptions();
         const { meta, task, loaded } = await loadRunContext(store, runId, cwd);
+        const factoryCwd = meta.project_root ?? ctx.factoryCwd ?? cwd;
         const definitionId = definitionIdForInstance(meta.pipeline_dag, stageId);
         const stageIndex = loaded.stages.findIndex((s) => s.id === definitionId);
         if (stageIndex < 0) {
@@ -127,7 +127,7 @@ export async function reconstructAndContinue(ctx) {
                 run: { runId, workspaceDir },
                 agent,
                 store,
-                cwd,
+                cwd: factoryCwd,
                 projectRoot: factoryCwd,
                 checkoutRoot,
                 hitl: ctx.hitl,

package/dist/runtime/runManager.d.ts

@@ -1,4 +1,6 @@
+import { type RunSubmission } from "../runstore/submission.js";
 import type { AgentPort, OpaqueAnswer } from "../agent/port.js";
+import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type RunStore } from "../runstore/port.js";
 import type { TaskFile } from "../types/task.js";
 import { type PipelineRunResult } from "./pipelineRunner.js";
@@ -34,6 +36,23 @@ export type CapacityHealth = {
     activeStageProcesses: number;
     maxActiveStageProcesses: number | null;
 };
+export type StartRunOnceResult = {
+    ok: true;
+    runId: string;
+    /** False only for the caller whose submission durably created this run for the first time. */
+    reused: boolean;
+    /**
+     * Present when this call observed the run being launched in this process — either it launched
+     * the run itself, or it piggybacked on another in-flight call to the same submission key while
+     * that launch was still starting. Absent when the submission was already durably committed by
+     * an earlier, separate call: `reused: true` does not by itself imply `done` is absent, since a
+     * piggybacked call is also `reused: true`. Callers that need completion regardless of which case
+     * they hit must still fall back to polling run status by `runId`.
+     */
+    done?: Promise<PipelineRunResult>;
+} | Extract<StartRunResult, {
+    ok: false;
+}>;
 export type { DeliverAnswerResult };
 export type { RetryStageResult };
 export type AbandonStageResult = {
@@ -65,6 +84,7 @@ export type StopManualRecoveryResult = {
 };
 export declare class RunManager {
     private readonly options;
+    private readonly submissionsInFlight;
     private readonly active;
     private readonly checkoutLeases;
     private readonly provisionalIds;
@@ -124,15 +144,17 @@ export declare class RunManager {
         runId: string;
     }>>;
     abandonStage(runId: string, stageId: string): Promise<AbandonStageResult>;
+    startRunOnce(input: Parameters<RunManager["startRun"]>[0], submission: RunSubmission): Promise<StartRunOnceResult>;
+    private startSubmittedRun;
     startRun(input: StartTaskInput & {
-        pipeline: string;
+        pipeline: string | InlinePipelineDefinition;
         task?: string | TaskFile;
         checkoutOverride?: string;
         skipGates?: boolean;
         gitSha?: string;
         ciPrUrl?: string;
         ciJobUrl?: string;
-    }): Promise<StartRunResult>;
+    }, submission?: RunSubmission): Promise<StartRunResult>;
     rerun(runId: string): Promise<StartRunResult>;
     retryStage(runId: string, stageId: string): Promise<RetryStageResult>;
     resumeTimedOutStage(runId: string, stageId: string): Promise<RetryStageResult>;