stageflow 0.2.0 → 0.3.0

package/dist/project/resolveProjectContext.js

@@ -0,0 +1,38 @@
+import os from "node:os";
+import path from "node:path";
+import { findProjectRoot } from "./findProjectRoot.js";
+import { ensureGlobalHome, globalStageflowHome } from "./globalHome.js";
+export function resolveProjectContext(invocationCwd) {
+    const resolvedInvocation = path.resolve(invocationCwd);
+    const gitRoot = findProjectRoot(resolvedInvocation);
+    const globalHome = ensureGlobalHome();
+    if (gitRoot !== null) {
+        return {
+            invocationCwd: resolvedInvocation,
+            projectRoot: gitRoot,
+            globalHome,
+            isGitProject: true,
+        };
+    }
+    return {
+        invocationCwd: resolvedInvocation,
+        projectRoot: os.homedir(),
+        globalHome,
+        isGitProject: false,
+    };
+}
+export function legacyProjectContext(cwd) {
+    const invocationCwd = path.resolve(cwd);
+    return {
+        invocationCwd,
+        projectRoot: invocationCwd,
+        globalHome: globalStageflowHome(),
+        isGitProject: false,
+    };
+}
+export function asProjectContext(input) {
+    if (typeof input !== "string") {
+        return input;
+    }
+    return resolveProjectContext(input);
+}

package/dist/project/resolveStageflowContext.d.ts

@@ -0,0 +1,11 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import type { LoadIssue } from "../config/loadOutcome.js";
+import type { ProjectContext } from "./resolveProjectContext.js";
+export type CatalogManifestStatus = "ok" | "missing" | "invalid" | "not_git";
+export type StageflowContext = ProjectContext & {
+    manifest: LoadedManifest | null;
+    manifestStatus: CatalogManifestStatus;
+    manifestIssues: LoadIssue[];
+};
+export declare function projectContextFromStageflow(ctx: StageflowContext): ProjectContext;
+export declare function resolveStageflowContext(invocationCwd: string): Promise<StageflowContext>;

package/dist/project/resolveStageflowContext.js

@@ -0,0 +1,66 @@
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { loadStageflowManifestOutcome, manifestPathForProject, } from "../config/loadStageflowManifest.js";
+import { findProjectRoot } from "./findProjectRoot.js";
+import { ensureGlobalHome } from "./globalHome.js";
+export function projectContextFromStageflow(ctx) {
+    return {
+        invocationCwd: ctx.invocationCwd,
+        projectRoot: ctx.projectRoot,
+        globalHome: ctx.globalHome,
+        isGitProject: ctx.isGitProject,
+    };
+}
+export async function resolveStageflowContext(invocationCwd) {
+    const resolvedInvocation = path.resolve(invocationCwd);
+    const gitRoot = findProjectRoot(resolvedInvocation);
+    const globalHome = ensureGlobalHome();
+    if (gitRoot === null) {
+        return {
+            invocationCwd: resolvedInvocation,
+            projectRoot: os.homedir(),
+            globalHome,
+            isGitProject: false,
+            manifest: null,
+            manifestStatus: "not_git",
+            manifestIssues: [],
+        };
+    }
+    const manifestPath = manifestPathForProject(gitRoot);
+    try {
+        await access(manifestPath);
+    }
+    catch {
+        return {
+            invocationCwd: resolvedInvocation,
+            projectRoot: gitRoot,
+            globalHome,
+            isGitProject: true,
+            manifest: null,
+            manifestStatus: "missing",
+            manifestIssues: [],
+        };
+    }
+    const outcome = await loadStageflowManifestOutcome(gitRoot);
+    if (!outcome.ok) {
+        return {
+            invocationCwd: resolvedInvocation,
+            projectRoot: gitRoot,
+            globalHome,
+            isGitProject: true,
+            manifest: null,
+            manifestStatus: "invalid",
+            manifestIssues: outcome.issues,
+        };
+    }
+    return {
+        invocationCwd: resolvedInvocation,
+        projectRoot: gitRoot,
+        globalHome,
+        isGitProject: true,
+        manifest: outcome.value,
+        manifestStatus: "ok",
+        manifestIssues: [],
+    };
+}

package/dist/runstore/normalizeCatalogPath.d.ts

@@ -0,0 +1 @@
+export declare function normalizeCatalogPath(raw: string): string;

package/dist/runstore/normalizeCatalogPath.js

@@ -0,0 +1,4 @@
+import path from "node:path";
+export function normalizeCatalogPath(raw) {
+    return path.resolve(raw);
+}

package/dist/runstore/port.d.ts

@@ -40,6 +40,9 @@ export type RunMeta = {
     ci_pr_url?: string;
     ci_job_url?: string;
     pipeline_dag?: RunPipelineDagSnapshot;
+    pipeline_path?: string;
+    task_path?: string;
+    project_root?: string;
 };
 export type CreatedRun = {
     runId: string;
@@ -84,6 +87,9 @@ export type RunSummary = {
     run_id: string;
     pipeline_id: string;
     task_id?: string;
+    pipeline_path?: string;
+    task_path?: string;
+    project_root?: string;
     status: RunStatus;
     created_at: string;
     updated_at?: string;
@@ -115,6 +121,9 @@ export type CreateRunInput = {
     ciPrUrl?: string;
     ciJobUrl?: string;
     pipelineDag?: RunPipelineDagSnapshot;
+    pipelinePath?: string;
+    taskPath?: string;
+    projectRoot?: string;
 };
 /**
  * Persistence port for pipeline run state.

package/dist/runstore/runProjection.js

@@ -65,14 +65,24 @@ function failedFieldsFromStages(stages) {
     };
 }
 function resolveListedStatus(stages, meta) {
+    if (stages.length === 0)
+        return meta.status ?? "created";
     const derived = deriveStatusFromStages(stages);
-    return stages.length > 0 ? derived : (meta.status ?? derived);
+    if (meta.status === "succeeded" && derived === "running") {
+        const hasActiveStage = stages.some((s) => s.status === "running" || s.status === "waiting_for_input");
+        if (!hasActiveStage)
+            return "succeeded";
+    }
+    return derived;
 }
 export function projectRunSummary(meta, stages) {
     return {
         run_id: meta.run_id,
         pipeline_id: meta.pipeline_id,
         task_id: meta.task_id,
+        ...(meta.pipeline_path !== undefined ? { pipeline_path: meta.pipeline_path } : {}),
+        ...(meta.task_path !== undefined ? { task_path: meta.task_path } : {}),
+        ...(meta.project_root !== undefined ? { project_root: meta.project_root } : {}),
         status: resolveListedStatus(stages, meta),
         created_at: meta.created_at,
         updated_at: meta.updated_at,

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -2,6 +2,7 @@ import Database from "better-sqlite3";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { projectRunDetail, projectRunSummary, orderStageSnapshots } from "../runProjection.js";
+import { normalizeCatalogPath } from "../normalizeCatalogPath.js";
 import { buildStageSnapshotFromStore } from "../stageSnapshot.js";
 import { parsePipelineDagSnapshot } from "../pipelineDagSnapshot.js";
 import { newRunId, runWorkspaceDir } from "../paths.js";
@@ -42,6 +43,15 @@ function ensurePipelineDagColumn(db) {
         db.exec(`ALTER TABLE runs ADD COLUMN pipeline_dag_json TEXT`);
     }
 }
+function ensureRunLocatorColumns(db) {
+    const cols = db.prepare(`PRAGMA table_info(runs)`).all();
+    const names = new Set(cols.map((c) => c.name));
+    for (const name of ["pipeline_path", "task_path", "project_root"]) {
+        if (!names.has(name)) {
+            db.exec(`ALTER TABLE runs ADD COLUMN ${name} TEXT`);
+        }
+    }
+}
 function ensureStageExecutionsTable(db) {
     db.exec(`
 CREATE TABLE IF NOT EXISTS stage_executions (
@@ -98,6 +108,7 @@ export class SqliteRunStore {
         ensureCheckoutRootColumn(this.db);
         ensureCiIdentityColumns(this.db);
         ensurePipelineDagColumn(this.db);
+        ensureRunLocatorColumns(this.db);
         ensureStageExecutionsTable(this.db);
         ensureStageEventsAttemptColumn(this.db);
         this.migratePromise = importDiskRunsIfEmpty(this.db, storeRoot).then(() => undefined);
@@ -115,11 +126,20 @@ export class SqliteRunStore {
         const workspaceDir = this.getWorkspaceDir(runId);
         await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
         const now = new Date().toISOString();
+        const pipelinePath = input.pipelinePath
+            ? normalizeCatalogPath(input.pipelinePath)
+            : null;
+        const taskPath = input.taskPath
+            ? normalizeCatalogPath(input.taskPath)
+            : null;
+        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)
+          (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)
          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)`)
+          (@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,
@@ -135,6 +155,9 @@ export class SqliteRunStore {
             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,
         });
         return { runId, workspaceDir };
     }
@@ -391,7 +414,7 @@ export class SqliteRunStore {
     async listRuns() {
         await this.ready();
         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
+            .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
          FROM runs ORDER BY created_at DESC`)
             .all();
         const summaries = [];
@@ -426,11 +449,14 @@ export class SqliteRunStore {
             ...(row.git_sha != null ? { git_sha: row.git_sha } : {}),
             ...(row.ci_pr_url != null ? { ci_pr_url: row.ci_pr_url } : {}),
             ...(row.ci_job_url != null ? { ci_job_url: row.ci_job_url } : {}),
+            ...(row.pipeline_path != null ? { pipeline_path: row.pipeline_path } : {}),
+            ...(row.task_path != null ? { task_path: row.task_path } : {}),
+            ...(row.project_root != null ? { project_root: row.project_root } : {}),
         };
     }
     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
+            .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
          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);\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  started_at TEXT,\n  finished_at TEXT,\n  envelope_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";
+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  started_at TEXT,\n  finished_at TEXT,\n  envelope_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";

package/dist/runstore/sqlite/schema.js

@@ -11,7 +11,10 @@ CREATE TABLE IF NOT EXISTS runs (
   pipeline_dag_json TEXT,
   git_sha TEXT,
   ci_pr_url TEXT,
-  ci_job_url TEXT
+  ci_job_url TEXT,
+  pipeline_path TEXT,
+  task_path TEXT,
+  project_root TEXT
 );
 
 CREATE TABLE IF NOT EXISTS stages (

package/dist/runtime/credentialBinding.d.ts

@@ -1,5 +1,6 @@
-import { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, type CredentialSource } from "./settingsFile.js";
-export { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, };
+import { type ProjectContext } from "../project/resolveProjectContext.js";
+import { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, type CredentialSource } from "./settingsFile.js";
+export { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, };
 export type CredentialBinding = {
     source: CredentialSource;
     authPath: string;
@@ -8,9 +9,10 @@ export type CredentialBinding = {
 export type ResolveCredentialBindingOptions = {
     piHomeAuthPath?: string;
 };
-export declare function sfOwnedAgentDir(cwd: string): string;
-export declare function sfOwnedAuthPath(cwd: string): string;
+export declare function sfOwnedAgentDir(): string;
+export declare function sfOwnedAuthPath(): string;
 export declare function piHomeAuthPath(override?: string): string;
 export declare function isUsableAuthFile(authPath: string): boolean;
-export declare function ensureSfOwnedAuthStore(cwd: string): string;
-export declare function resolveCredentialBinding(cwd: string, options?: ResolveCredentialBindingOptions): CredentialBinding;
+export declare function ensureSfOwnedAuthStore(): string;
+export declare function resolveCredentialBinding(ctx: ProjectContext | string, options?: ResolveCredentialBindingOptions): CredentialBinding;
+export { readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";

package/dist/runtime/credentialBinding.js

@@ -1,14 +1,15 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { storeRootFor } from "../runstore/paths.js";
-import { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";
-export { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, };
-export function sfOwnedAgentDir(cwd) {
-    return path.join(storeRootFor(cwd), "agent");
+import { ensureGlobalHome } from "../project/globalHome.js";
+import { resolveProjectContext, } from "../project/resolveProjectContext.js";
+import { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, } from "./settingsFile.js";
+export { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, };
+export function sfOwnedAgentDir() {
+    return path.join(ensureGlobalHome(), "agent");
 }
-export function sfOwnedAuthPath(cwd) {
-    return path.join(sfOwnedAgentDir(cwd), "auth.json");
+export function sfOwnedAuthPath() {
+    return path.join(sfOwnedAgentDir(), "auth.json");
 }
 export function piHomeAuthPath(override) {
     return (override ??
@@ -25,18 +26,9 @@ export function isUsableAuthFile(authPath) {
         return false;
     }
 }
-export function ensureSfOwnedAuthStore(cwd) {
-    const storeRoot = storeRootFor(cwd);
-    mkdirSync(storeRoot, { recursive: true });
-    const agentDir = sfOwnedAgentDir(cwd);
-    mkdirSync(agentDir, { recursive: true });
-    try {
-        chmodSync(agentDir, 0o700);
-    }
-    catch {
-        // best-effort on non-POSIX
-    }
-    const authPath = sfOwnedAuthPath(cwd);
+export function ensureSfOwnedAuthStore() {
+    ensureGlobalHome();
+    const authPath = sfOwnedAuthPath();
     if (!existsSync(authPath)) {
         writeFileSync(authPath, "{}\n", { encoding: "utf8", mode: 0o600 });
     }
@@ -48,14 +40,15 @@ export function ensureSfOwnedAuthStore(cwd) {
     }
     return authPath;
 }
-export function resolveCredentialBinding(cwd, options = {}) {
+export function resolveCredentialBinding(ctx, options = {}) {
+    const projectCtx = typeof ctx === "string" ? resolveProjectContext(ctx) : ctx;
     const piHome = piHomeAuthPath(options.piHomeAuthPath);
-    const persisted = readCredentialSourceFromFile(cwd);
+    const persisted = readCredentialSourceFromContext(projectCtx);
     if (persisted !== undefined) {
         if (persisted === "sf_owned") {
             return {
                 source: "sf_owned",
-                authPath: ensureSfOwnedAuthStore(cwd),
+                authPath: ensureSfOwnedAuthStore(),
                 provisional: false,
             };
         }
@@ -74,7 +67,8 @@ export function resolveCredentialBinding(cwd, options = {}) {
     }
     return {
         source: "sf_owned",
-        authPath: ensureSfOwnedAuthStore(cwd),
+        authPath: ensureSfOwnedAuthStore(),
         provisional: true,
     };
 }
+export { readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";

package/dist/runtime/pipelineRunner.d.ts

@@ -31,6 +31,7 @@ export type PreparedPipeline = {
     agent: AgentPort;
     store: RunStore;
     cwd: string;
+    projectRoot: string;
     checkoutRoot?: string;
     hitl?: StageHitlController;
     executionMode?: StageExecutionMode;
@@ -55,6 +56,7 @@ export declare function runPipeline(options: {
     taskYaml?: string;
     pipeline: string;
     cwd?: string;
+    projectRoot?: string;
     checkoutOverride?: string;
     hitl?: StageHitlController;
     maxActiveStagesPerRun?: number;
@@ -71,6 +73,7 @@ export declare function startPipeline(options: {
     taskYaml?: string;
     pipeline: string;
     cwd?: string;
+    projectRoot?: string;
     checkoutOverride?: string;
     gitSha?: string;
     ciPrUrl?: string;

package/dist/runtime/pipelineRunner.js

@@ -1,10 +1,11 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { loadPipelineValidated } from "../config/loadPipeline.js";
+import { loadPipelineValidated } from "../config/validateCatalog.js";
 import { loadTaskFromYaml } from "../config/loadTask.js";
 import { buildValidationResult } from "../config/validateCatalog.js";
 import { resolveAndValidateCheckout } from "./stageRoots.js";
 import { buildPipelineDagSnapshotFromLoaded } from "../runstore/pipelineDagSnapshot.js";
+import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
 import { runPipelineDag } from "./pipelineScheduler.js";
 import { readMaxActiveStagesPerRun, readStageExecutionMode, } from "./stageConcurrency.js";
 import { StageProcessLauncher } from "./stageProcessLauncher.js";
@@ -41,6 +42,11 @@ async function preparePipeline(options) {
     const label = options.taskPath ?? "task.yaml";
     const task = loadTaskFromYaml(taskYaml, `task file ${label}`);
     const checkoutRoot = await resolveAndValidateCheckout(task, options.checkoutOverride, options.cwd);
+    const pipelinePath = normalizeCatalogPath(loaded.pipelinePath);
+    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({
         pipelineId: loaded.pipeline.id,
         taskYaml,
@@ -50,6 +56,9 @@ async function preparePipeline(options) {
         ciPrUrl: options.ciPrUrl,
         ciJobUrl: options.ciJobUrl,
         pipelineDag: buildPipelineDagSnapshotFromLoaded(loaded),
+        pipelinePath,
+        taskPath,
+        projectRoot,
     });
     const executionMode = readStageExecutionMode(process.env, options.executionMode);
     const stageProcessLauncher = resolveStageProcessLauncher(executionMode, options.stageProcessLauncher);
@@ -60,6 +69,7 @@ async function preparePipeline(options) {
         agent: options.agent,
         store: options.store,
         cwd: options.cwd,
+        projectRoot: options.projectRoot ?? options.cwd,
         checkoutRoot,
         hitl: options.hitl,
         executionMode,
@@ -86,6 +96,7 @@ export async function executeStages(prepared, options) {
 }
 export async function runPipeline(options) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
     const prepared = await preparePipeline({
         agent: options.agent,
         store: options.store,
@@ -93,6 +104,7 @@ export async function runPipeline(options) {
         taskYaml: options.taskYaml,
         pipeline: options.pipeline,
         cwd,
+        projectRoot,
         checkoutOverride: options.checkoutOverride,
         hitl: options.hitl,
         executionMode: options.executionMode,
@@ -109,6 +121,7 @@ export async function runPipeline(options) {
 /** Create the run immediately, then execute stages in the returned promise. */
 export async function startPipeline(options) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
     const prepared = await preparePipeline({
         agent: options.agent,
         store: options.store,
@@ -116,6 +129,7 @@ export async function startPipeline(options) {
         taskYaml: options.taskYaml,
         pipeline: options.pipeline,
         cwd,
+        projectRoot,
         checkoutOverride: options.checkoutOverride,
         gitSha: options.gitSha,
         ciPrUrl: options.ciPrUrl,

package/dist/runtime/pipelineScheduler.d.ts

@@ -18,6 +18,7 @@ type SchedulerPreparedPipeline = {
     agent: AgentPort;
     store: RunStore;
     cwd: string;
+    projectRoot?: string;
     checkoutRoot?: string;
     hitl?: StageHitlController;
     operatorCatalog?: OperatorCatalog;
@@ -86,6 +87,7 @@ export type RetryRunOptions = {
     onRetryRootTerminal?: OnRetryRootTerminal;
 };
 export declare function retryRun(options: RetryRunOptions): Promise<PipelineRunResult>;
+export declare function applyForkSkipsFromEnvelopes(dag: ResolvedPipelineDag, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>): void;
 export declare function applyRetryRootDelta(dag: ResolvedPipelineDag, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>, retryRoots: Map<string, number>, stageId: string, attempt: number, clearSchedulingHalt?: () => void): void;
 export declare function hasWorkOutsideBranch(dag: ResolvedPipelineDag, branchRootId: string, states: Map<string, StageScheduleState>, ctx?: HasWorkOutsideBranchContext): boolean;
 export declare function runPipelineDag(options: RunPipelineDagOptions): Promise<PipelineRunResult>;

package/dist/runtime/pipelineScheduler.js

@@ -1,3 +1,4 @@
+import { normalizeForkChoice } from "../envelope/forkChoice.js";
 import { collectDownstreamClosure, collectDownstreamStageIds, } from "./dagTraversal.js";
 import { buildCompletedEnvelopesFromRun, buildStageConfigById, } from "./envelopeRouting.js";
 import { WAIT_WITHOUT_WORKER_DISPATCH } from "./answerResume.js";
@@ -104,7 +105,10 @@ export async function resumeRun(options) {
         return state !== undefined && terminalState(state);
     });
     if (allTerminal) {
-        const allSucceeded = dag.nodes.every((node) => hydrated.states.get(node.id) === "succeeded");
+        const allSucceeded = dag.nodes.every((node) => {
+            const s = hydrated.states.get(node.id);
+            return s === "succeeded" || s === "skipped";
+        });
         await prepared.store.updateRunStatus(prepared.run.runId, allSucceeded ? "succeeded" : "failed");
         return {
             ok: allSucceeded,
@@ -133,6 +137,33 @@ export async function retryRun(options) {
         onRetryRootTerminal: options.onRetryRootTerminal,
     });
 }
+function applyForkChoiceToSchedule(dag, forkStageId, chosen, states, options) {
+    const skipPending = (stageId) => {
+        if (states.get(stageId) === "pending") {
+            states.set(stageId, "skipped");
+            options?.onSkip?.(stageId);
+        }
+    };
+    for (const childId of dag.childrenOf[forkStageId] ?? []) {
+        if (!chosen.has(childId)) {
+            skipPending(childId);
+            for (const desc of collectDownstreamStageIds(dag, childId)) {
+                skipPending(desc);
+            }
+        }
+    }
+}
+export function applyForkSkipsFromEnvelopes(dag, states, completedEnvelopes) {
+    for (const node of dag.nodes) {
+        if (!node.fork)
+            continue;
+        const envelope = completedEnvelopes.get(node.id);
+        if (!envelope)
+            continue;
+        const chosen = normalizeForkChoice(envelope.fork_choice, "stored");
+        applyForkChoiceToSchedule(dag, node.id, chosen, states);
+    }
+}
 export function applyRetryRootDelta(dag, states, completedEnvelopes, retryRoots, stageId, attempt, clearSchedulingHalt) {
     retryRoots.set(stageId, attempt);
     const downstream = collectDownstreamClosure(dag, [stageId]);
@@ -206,7 +237,8 @@ function isRunnable(dag, stageId, states, schedulingHalted) {
 export async function runPipelineDag(options) {
     const { prepared, maxActiveStagesPerRun } = options;
     const executionMode = options.executionMode ?? "process";
-    const { agent, task, loaded, run, store, checkoutRoot, hitl, cwd, } = prepared;
+    const { agent, task, loaded, run, store, checkoutRoot, hitl, cwd, projectRoot, } = prepared;
+    const factoryCwd = projectRoot ?? cwd ?? process.cwd();
     const dag = loaded.dag;
     const stageById = buildStageConfigById(loaded);
     let { states, completedEnvelopes, schedulingHalted, firstFailureReason } = options.initialSchedule ??
@@ -260,6 +292,7 @@ export async function runPipelineDag(options) {
             }
         }
     }
+    applyForkSkipsFromEnvelopes(dag, states, completedEnvelopes);
     let activeCount = 0;
     const inFlight = new Set();
     const notifyRetryRootTerminal = (stageId, outcome) => {
@@ -323,6 +356,13 @@ export async function runPipelineDag(options) {
         states.set(stageId, "succeeded");
         completedEnvelopes.set(stageId, envelope);
         notifyRetryRootTerminal(stageId, "succeeded");
+        const node = dag.nodes.find((n) => n.id === stageId);
+        if (node?.fork) {
+            const chosen = normalizeForkChoice(envelope.fork_choice, "stored");
+            applyForkChoiceToSchedule(dag, stageId, chosen, states, {
+                onSkip: (id) => notifyRetryRootTerminal(id, "skipped"),
+            });
+        }
     };
     const launchStage = async (stageId) => {
         const stage = stageById.get(stageId);
@@ -341,7 +381,7 @@ export async function runPipelineDag(options) {
             const launchResult = await launcher.launch({
                 runId: run.runId,
                 stageId,
-                rootDir: cwd,
+                rootDir: factoryCwd,
                 attempt,
                 ...(prepared.operatorCatalog !== undefined
                     ? { operatorCatalog: prepared.operatorCatalog }
@@ -353,9 +393,8 @@ export async function runPipelineDag(options) {
                     const envelope = await store.readEnvelope(run.runId, stageId);
                     onStageSuccess(stageId, envelope);
                 }
-                catch {
-                    states.set(stageId, "succeeded");
-                    notifyRetryRootTerminal(stageId, "succeeded");
+                catch (err) {
+                    await onStageFailure(stageId, err instanceof Error ? err.message : String(err));
                 }
                 return;
             }
@@ -377,7 +416,7 @@ export async function runPipelineDag(options) {
             workspaceDir: run.workspaceDir,
             hitl,
             attemptCtx,
-            factoryCwd: cwd,
+            factoryCwd,
             operatorCatalog: prepared.operatorCatalog,
             completedEnvelopes,
             skipGates: prepared.skipGates,
@@ -485,7 +524,10 @@ export async function runPipelineDag(options) {
             reason: firstFailureReason,
         };
     }
-    const allSucceeded = dag.nodes.every((node) => states.get(node.id) === "succeeded");
+    const allSucceeded = dag.nodes.every((node) => {
+        const s = states.get(node.id);
+        return s === "succeeded" || s === "skipped";
+    });
     if (!allSucceeded) {
         if (retryContext === undefined) {
             await store.updateRunStatus(run.runId, "failed");
@@ -498,9 +540,7 @@ export async function runPipelineDag(options) {
             reason: firstFailureReason ?? "pipeline incomplete",
         };
     }
-    if (retryContext === undefined) {
-        await store.updateRunStatus(run.runId, "succeeded");
-    }
+    await store.updateRunStatus(run.runId, "succeeded");
     return {
         ok: true,
         outcome: "succeeded",

package/dist/runtime/reloadRunCatalog.d.ts

@@ -0,0 +1,5 @@
+import type { RunMeta } from "../runstore/port.js";
+import type { LoadedPipeline } from "../types/pipeline.js";
+import type { TaskFile } from "../types/task.js";
+export declare function reloadPipelineForRun(meta: RunMeta): Promise<LoadedPipeline>;
+export declare function reloadTaskForRun(meta: RunMeta): Promise<TaskFile>;