stageflow 0.23.0 → 0.25.0

package/dist/runstore/createStore.js

@@ -11,13 +11,22 @@ function resolveKind(kind) {
     return "sqlite";
 }
 /**
- * Factory at the application edge. Call sites should receive the returned `RunStore`
- * and must not branch on backend kind.
+ * Composition-root factory: hands back the concrete SQLite connection alongside the `RunStore`,
+ * for the one caller wiring a second, colocated store (A2A's tables) into the same `state.db`
+ * file. Ordinary call sites use `createRunStore` below and never see this.
  */
-export function createRunStore(config) {
+export function createRunStoreWithConnection(config) {
     resolveKind(config.kind);
     migrateLegacyStoreRoot(config.rootDir);
     const storeRoot = storeRootFor(config.rootDir);
     mkdirSync(storeRoot, { recursive: true });
-    return new SqliteRunStore(storeRoot);
+    const store = new SqliteRunStore(storeRoot);
+    return { store, connection: store.connection };
+}
+/**
+ * Factory at the application edge. Call sites should receive the returned `RunStore`
+ * and must not branch on backend kind.
+ */
+export function createRunStore(config) {
+    return createRunStoreWithConnection(config).store;
 }

package/dist/runstore/port.d.ts

@@ -1,7 +1,8 @@
 import type { StageLogLine } from "../agent/activity.js";
+import type { RunSubmission, RunSubmissionRecord } from "./submission.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { FeedbackLoopConfig, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { FeedbackLoopConfig, InlinePipelineDefinition, ResolvedPipelineDag } from "../types/pipeline.js";
 import type { CompletionCheck } from "../types/completion.js";
 import type { StageGateKind } from "../types/stage.js";
 import type { StageUsage } from "../types/usage.js";
@@ -51,6 +52,14 @@ export type RunMeta = {
     pipeline_path?: string;
     task_path?: string;
     project_root?: string;
+    /**
+     * The raw pipeline body for a run started from an inline pipeline
+     * (no pipeline_path). Lets a fresh stage-worker process — which has no
+     * memory of the original in-process call — reconstruct the pipeline
+     * without needing a catalog file, mirroring how task_yaml already lets
+     * task reconstruction work without a task_path.
+     */
+    inline_pipeline?: InlinePipelineDefinition;
 };
 export type CreatedRun = {
     runId: string;
@@ -275,6 +284,7 @@ export type FeedbackLoopHistory = {
     fork_generations: ForkGenerationRecord[];
 };
 export type CreateRunInput = {
+    submission?: RunSubmission;
     pipelineId: string;
     taskYaml: string;
     taskId?: string;
@@ -286,6 +296,8 @@ export type CreateRunInput = {
     pipelinePath?: string;
     taskPath?: string;
     projectRoot?: string;
+    /** Raw inline pipeline body, persisted only when pipelinePath is absent. */
+    inlinePipeline?: InlinePipelineDefinition;
 };
 export type ListRunsFilter = {
     status?: RunStatus;
@@ -301,6 +313,7 @@ export type ListRunsFilter = {
  * run id is all you have (catalog / rehydrate).
  */
 export interface RunStore {
+    getRunBySubmission(key: string): Promise<RunSubmissionRecord | null>;
     createRun(input: CreateRunInput): Promise<CreatedRun>;
     updateRunStatus(runId: string, status: RunStatus): Promise<void>;
     readRunMeta(runId: string): Promise<RunMeta>;

package/dist/runstore/sqlite/SqliteRunStore.d.ts

@@ -1,6 +1,8 @@
+import Database from "better-sqlite3";
 import type { StageEnvelope } from "../../types/envelope.js";
 import type { StageLogLine } from "../../agent/activity.js";
 import { type CreateFeedbackLoopInput, type CreateFeedbackReplayInput, type CreateFeedbackReplayStagePassInput, type CreateForkGenerationInput, type CreateRunInput, type CreatedRun, type FeedbackLoopPatch, type FeedbackLoopRecord, type FeedbackLoopState, type FeedbackReplayPatch, type FeedbackReplayRecord, type FeedbackReplayStagePassPatch, type FeedbackReplayStagePassRecord, type ForkGenerationPatch, type ForkGenerationRecord, type ListRunsFilter, type RunDetail, type RunMeta, type RunPipelineDagSnapshot, type RunStatus, type RunStore, type RunSummary, type StageExecution, type StageExecutionPatch, type StageLogEvent, type VerificationCheckResult, type VerificationCheckResultPatch } from "../port.js";
+import { type RunSubmissionRecord } from "../submission.js";
 export declare class SqliteRunStore implements RunStore {
     private readonly storeRoot;
     private readonly db;
@@ -8,8 +10,15 @@ export declare class SqliteRunStore implements RunStore {
     constructor(storeRoot: string);
     /** Await one-shot disk import before catalog reads (create paths also wait). */
     ready(): Promise<void>;
+    /**
+     * The connection this store owns, for the one caller allowed to share it: the composition root
+     * wiring the A2A tables into the same `state.db` file. Not part of the `RunStore` interface.
+     */
+    get connection(): Database.Database;
     getWorkspaceDir(runId: string): string;
     createRun(input: CreateRunInput): Promise<CreatedRun>;
+    private readSubmission;
+    getRunBySubmission(key: string): Promise<RunSubmissionRecord | null>;
     updateRunStatus(runId: string, status: RunStatus): Promise<void>;
     updatePipelineDag(runId: string, dag: RunPipelineDagSnapshot): Promise<void>;
     readRunMeta(runId: string): Promise<RunMeta>;

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -9,6 +9,7 @@ import { newRunId, runWorkspaceDir } from "../paths.js";
 import { attemptAgentDir, attemptArtifactsDir, stageDir, } from "../workspaceLayout.js";
 import { importDiskRunsIfEmpty } from "./migrateFromDisk.js";
 import { SCHEMA_SQL } from "./schema.js";
+import { RunSubmissionExistsError } from "../submission.js";
 const ensuredStageDirs = new Set();
 const DEFAULT_SQLITE_BUSY_TIMEOUT_MS = 5000;
 function readSqliteBusyTimeoutMs() {
@@ -52,6 +53,12 @@ function ensureRunLocatorColumns(db) {
         }
     }
 }
+function ensureInlinePipelineColumn(db) {
+    const cols = db.prepare(`PRAGMA table_info(runs)`).all();
+    if (!cols.some((c) => c.name === "inline_pipeline_json")) {
+        db.exec(`ALTER TABLE runs ADD COLUMN inline_pipeline_json TEXT`);
+    }
+}
 function ensureStageExecutionsTable(db) {
     db.exec(`
 CREATE TABLE IF NOT EXISTS stage_executions (
@@ -304,6 +311,7 @@ export class SqliteRunStore {
         ensureCiIdentityColumns(this.db);
         ensurePipelineDagColumn(this.db);
         ensureRunLocatorColumns(this.db);
+        ensureInlinePipelineColumn(this.db);
         ensureStageExecutionsTable(this.db);
         ensureStageExecutionVerificationOutcomeColumn(this.db);
         ensureStageExecutionCostColumns(this.db);
@@ -319,6 +327,13 @@ export class SqliteRunStore {
     async ready() {
         await this.migratePromise;
     }
+    /**
+     * The connection this store owns, for the one caller allowed to share it: the composition root
+     * wiring the A2A tables into the same `state.db` file. Not part of the `RunStore` interface.
+     */
+    get connection() {
+        return this.db;
+    }
     getWorkspaceDir(runId) {
         return runWorkspaceDir(this.storeRoot, runId);
     }
@@ -337,32 +352,55 @@ export class SqliteRunStore {
         const projectRoot = input.projectRoot
             ? normalizeCatalogPath(input.projectRoot)
             : null;
-        this.db
-            .prepare(`INSERT INTO runs
-          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root)
+        this.db.transaction(() => {
+            if (input.submission) {
+                const existing = this.readSubmission(input.submission.key);
+                if (existing)
+                    throw new RunSubmissionExistsError(existing);
+            }
+            this.db
+                .prepare(`INSERT INTO runs
+          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root, inline_pipeline_json)
          VALUES
-          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url, @pipeline_path, @task_path, @project_root)`)
-            .run({
-            run_id: runId,
-            pipeline_id: input.pipelineId,
-            task_id: input.taskId ?? null,
-            task_yaml: input.taskYaml,
-            status: "running",
-            created_at: now,
-            updated_at: now,
-            checkout_root: input.checkoutRoot ?? null,
-            pipeline_dag_json: input.pipelineDag
-                ? JSON.stringify(input.pipelineDag)
-                : null,
-            git_sha: input.gitSha ?? null,
-            ci_pr_url: input.ciPrUrl ?? null,
-            ci_job_url: input.ciJobUrl ?? null,
-            pipeline_path: pipelinePath,
-            task_path: taskPath,
-            project_root: projectRoot,
-        });
+          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url, @pipeline_path, @task_path, @project_root, @inline_pipeline_json)`)
+                .run({
+                run_id: runId,
+                pipeline_id: input.pipelineId,
+                task_id: input.taskId ?? null,
+                task_yaml: input.taskYaml,
+                status: "running",
+                created_at: now,
+                updated_at: now,
+                checkout_root: input.checkoutRoot ?? null,
+                pipeline_dag_json: input.pipelineDag
+                    ? JSON.stringify(input.pipelineDag)
+                    : null,
+                git_sha: input.gitSha ?? null,
+                ci_pr_url: input.ciPrUrl ?? null,
+                ci_job_url: input.ciJobUrl ?? null,
+                pipeline_path: pipelinePath,
+                task_path: taskPath,
+                project_root: projectRoot,
+                inline_pipeline_json: input.inlinePipeline
+                    ? JSON.stringify(input.inlinePipeline)
+                    : null,
+            });
+            if (input.submission) {
+                this.db.prepare("INSERT INTO run_submissions (submission_key, request_hash, run_id) VALUES (?, ?, ?)")
+                    .run(input.submission.key, input.submission.requestHash, runId);
+            }
+        })();
         return { runId, workspaceDir };
     }
+    readSubmission(key) {
+        const row = this.db.prepare("SELECT submission_key AS key, request_hash AS requestHash, run_id AS runId FROM run_submissions WHERE submission_key = ?")
+            .get(key);
+        return row ?? null;
+    }
+    async getRunBySubmission(key) {
+        await this.ready();
+        return this.readSubmission(key);
+    }
     async updateRunStatus(runId, status) {
         await this.ready();
         const result = this.db
@@ -710,7 +748,7 @@ export class SqliteRunStore {
         }
         const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
         const rows = this.db
-            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root
+            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root, inline_pipeline_json
          FROM runs ${where} ORDER BY created_at DESC`)
             .all(...params);
         const summaries = [];
@@ -1139,11 +1177,14 @@ export class SqliteRunStore {
             ...(row.task_path != null ? { task_path: row.task_path } : {}),
             ...(row.project_root != null ? { project_root: row.project_root } : {}),
             ...(pipeline_dag ? { pipeline_dag } : {}),
+            ...(row.inline_pipeline_json != null
+                ? { inline_pipeline: JSON.parse(row.inline_pipeline_json) }
+                : {}),
         };
     }
     getRunRow(runId) {
         const row = this.db
-            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root
+            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root, inline_pipeline_json
          FROM runs WHERE run_id = ?`)
             .get(runId);
         if (!row)

package/dist/runstore/sqlite/schema.d.ts

@@ -1 +1 @@
-export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  verification_outcome TEXT NOT NULL DEFAULT 'not_run',\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  cost_usd REAL,\n  usage_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n\nCREATE TABLE IF NOT EXISTS verification_check_results (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  check_id TEXT NOT NULL,\n  check_type TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  evidence_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt, check_id),\n  FOREIGN KEY (run_id, stage_id, attempt)\n    REFERENCES stage_executions(run_id, stage_id, attempt)\n);\n\nCREATE INDEX IF NOT EXISTS idx_verification_check_results_execution\n  ON verification_check_results (run_id, stage_id, attempt, check_id);\n\nCREATE TABLE IF NOT EXISTS feedback_loops (\n  run_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  policy_json TEXT NOT NULL,\n  state TEXT NOT NULL,\n  current_replay_id TEXT,\n  current_replay_number INTEGER,\n  deferred_send_back_json TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, loop_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state\n  ON feedback_loops (run_id, state, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replays (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  target_stage_id TEXT NOT NULL,\n  replay_number INTEGER NOT NULL,\n  max_replays INTEGER NOT NULL,\n  replay_session TEXT NOT NULL,\n  route_stage_ids_json TEXT NOT NULL,\n  feedback_envelope_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, replay_id),\n  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number\n  ON feedback_replays (run_id, loop_id, replay_number);\nCREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop\n  ON feedback_replays (run_id, loop_id, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  stage_attempt INTEGER NOT NULL,\n  session_origin_attempt INTEGER,\n  session_mode TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  emitted_envelope_json TEXT,\n  PRIMARY KEY (run_id, replay_id, stage_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay\n  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);\n\nCREATE TABLE IF NOT EXISTS fork_generations (\n  run_id TEXT NOT NULL,\n  generation_id TEXT NOT NULL,\n  replay_id TEXT,\n  fork_parent_stage_id TEXT NOT NULL,\n  generation_number INTEGER NOT NULL,\n  clone_stage_ids_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, generation_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number\n  ON fork_generations (run_id, fork_parent_stage_id, generation_number);\nCREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay\n  ON fork_generations (run_id, replay_id, created_at);\n";
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS run_submissions (\n  submission_key TEXT PRIMARY KEY,\n  request_hash TEXT NOT NULL,\n  run_id TEXT NOT NULL UNIQUE REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  verification_outcome TEXT NOT NULL DEFAULT 'not_run',\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  cost_usd REAL,\n  usage_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n\nCREATE TABLE IF NOT EXISTS verification_check_results (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  check_id TEXT NOT NULL,\n  check_type TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  evidence_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt, check_id),\n  FOREIGN KEY (run_id, stage_id, attempt)\n    REFERENCES stage_executions(run_id, stage_id, attempt)\n);\n\nCREATE INDEX IF NOT EXISTS idx_verification_check_results_execution\n  ON verification_check_results (run_id, stage_id, attempt, check_id);\n\nCREATE TABLE IF NOT EXISTS feedback_loops (\n  run_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  policy_json TEXT NOT NULL,\n  state TEXT NOT NULL,\n  current_replay_id TEXT,\n  current_replay_number INTEGER,\n  deferred_send_back_json TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, loop_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state\n  ON feedback_loops (run_id, state, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replays (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  target_stage_id TEXT NOT NULL,\n  replay_number INTEGER NOT NULL,\n  max_replays INTEGER NOT NULL,\n  replay_session TEXT NOT NULL,\n  route_stage_ids_json TEXT NOT NULL,\n  feedback_envelope_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, replay_id),\n  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number\n  ON feedback_replays (run_id, loop_id, replay_number);\nCREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop\n  ON feedback_replays (run_id, loop_id, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  stage_attempt INTEGER NOT NULL,\n  session_origin_attempt INTEGER,\n  session_mode TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  emitted_envelope_json TEXT,\n  PRIMARY KEY (run_id, replay_id, stage_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay\n  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);\n\nCREATE TABLE IF NOT EXISTS fork_generations (\n  run_id TEXT NOT NULL,\n  generation_id TEXT NOT NULL,\n  replay_id TEXT,\n  fork_parent_stage_id TEXT NOT NULL,\n  generation_number INTEGER NOT NULL,\n  clone_stage_ids_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, generation_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number\n  ON fork_generations (run_id, fork_parent_stage_id, generation_number);\nCREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay\n  ON fork_generations (run_id, replay_id, created_at);\n";

package/dist/runstore/sqlite/schema.js

@@ -17,6 +17,12 @@ CREATE TABLE IF NOT EXISTS runs (
   project_root TEXT
 );
 
+CREATE TABLE IF NOT EXISTS run_submissions (
+  submission_key TEXT PRIMARY KEY,
+  request_hash TEXT NOT NULL,
+  run_id TEXT NOT NULL UNIQUE REFERENCES runs(run_id)
+);
+
 CREATE TABLE IF NOT EXISTS stages (
   run_id TEXT NOT NULL,
   stage_id TEXT NOT NULL,

package/dist/runstore/submission.d.ts

@@ -0,0 +1,11 @@
+export type RunSubmission = {
+    key: string;
+    requestHash: string;
+};
+export type RunSubmissionRecord = RunSubmission & {
+    runId: string;
+};
+export declare class RunSubmissionExistsError extends Error {
+    readonly submission: RunSubmissionRecord;
+    constructor(submission: RunSubmissionRecord);
+}

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/runtime/pipelineRunner.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -70,6 +71,7 @@ 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;

package/dist/runtime/pipelineRunner.js

@@ -65,6 +65,7 @@ async function preparePipeline(options) {
         : 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,
@@ -76,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);
@@ -145,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/runManager.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -35,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 = {
@@ -66,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;
@@ -125,6 +144,8 @@ 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 | InlinePipelineDefinition;
         task?: string | TaskFile;
@@ -133,7 +154,7 @@ export declare class RunManager {
         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>;