stageflow 0.2.0 → 0.8.0

package/dist/runtime/runChangeBus.js

@@ -0,0 +1,83 @@
+export class RunChangeBus {
+    listeners = new Set();
+    on(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    off(listener) {
+        this.listeners.delete(listener);
+    }
+    emit(event) {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listener isolation: one throw must not block others.
+            }
+        }
+    }
+}
+export function createRunChangeBus() {
+    return new RunChangeBus();
+}
+const WRAPPED_MARKER = Symbol.for("stageflow.wrapRunStoreWithChangeBus");
+const BUS_MARKER = Symbol.for("stageflow.runChangeBus");
+export function isRunStoreWrapped(store) {
+    return store[WRAPPED_MARKER] === true;
+}
+export function getRunChangeBusFromWrappedStore(store) {
+    const bus = store[BUS_MARKER];
+    return bus instanceof RunChangeBus ? bus : undefined;
+}
+export function wrapRunStoreWithChangeBus(store, bus) {
+    if (isRunStoreWrapped(store)) {
+        const bound = getRunChangeBusFromWrappedStore(store);
+        if (bound !== bus) {
+            throw new Error("runChangeBus does not match the bus already bound to the provided store");
+        }
+        return store;
+    }
+    const createRun = async (input) => {
+        const created = await store.createRun(input);
+        bus.emit({ runId: created.runId, kind: "created" });
+        return created;
+    };
+    const updateRunStatus = async (runId, status) => {
+        await store.updateRunStatus(runId, status);
+        bus.emit({ runId, kind: "status" });
+    };
+    const appendStageEvent = async (runId, stageId, event, options) => {
+        await store.appendStageEvent(runId, stageId, event, options);
+        if (event.event === "waiting_for_input" || event.event === "resumed") {
+            bus.emit({ runId, kind: "waiting" });
+        }
+    };
+    const boundCache = new Map();
+    return new Proxy(store, {
+        get(target, prop, receiver) {
+            if (prop === WRAPPED_MARKER)
+                return true;
+            if (prop === BUS_MARKER)
+                return bus;
+            if (prop === "createRun")
+                return createRun;
+            if (prop === "updateRunStatus")
+                return updateRunStatus;
+            if (prop === "appendStageEvent")
+                return appendStageEvent;
+            const cached = boundCache.get(prop);
+            if (cached !== undefined)
+                return cached;
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value === "function") {
+                const bound = value.bind(target);
+                boundCache.set(prop, bound);
+                return bound;
+            }
+            return value;
+        },
+    });
+}

package/dist/runtime/runManager.d.ts

@@ -61,10 +61,14 @@ export declare class RunManager {
     private readonly retryCoordinator;
     private readonly retryTracking;
     private readonly cwd;
+    private readonly projectRoot;
+    private readonly isGitProject;
     constructor(options: {
         agent: AgentPort;
         store: RunStore;
         cwd?: string;
+        projectRoot?: string;
+        isGitProject?: boolean;
         operatorCatalog?: OperatorCatalog;
         seams?: HitlSeams;
         maxConcurrent?: number;

package/dist/runtime/runManager.js

@@ -1,14 +1,15 @@
 import { randomUUID } from "node:crypto";
 import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
-import { loadPipeline } from "../config/loadPipeline.js";
+import { normalizeCatalogPath } from "../runstore/normalizeCatalogPath.js";
+import { loadRunContext } from "./resumeReconstruct.js";
 import { loadTaskFromYaml } from "../config/loadTask.js";
 import { PipelineValidationError, startPipeline, } from "./pipelineRunner.js";
 import { resumeRun } from "./pipelineScheduler.js";
 import { RunRetryCoordinator, } from "./runRetryCoordinator.js";
 import { readMaxActiveStageProcesses, readMaxActiveStagesPerRun, readStageExecutionMode, } from "./stageConcurrency.js";
 import { StageProcessLauncher } from "./stageProcessLauncher.js";
-import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, readMaxConcurrentFromFile, writeMaxConcurrentToFile, } from "./settingsFile.js";
+import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, projectSettingsContext, readMaxConcurrentFromContext, writeMaxConcurrentToContext, } from "./settingsFile.js";
 import { StageHitlController, waitKey, } from "./stageHitl.js";
 import { resolveAndValidateCheckout, } from "./stageRoots.js";
 import { orchestrateAnswerResume } from "./answerResume.js";
@@ -79,12 +80,17 @@ export class RunManager {
         },
     };
     cwd;
+    projectRoot;
+    isGitProject;
     constructor(options) {
         this.options = options;
         this.cwd = options.cwd ?? process.cwd();
+        this.projectRoot = options.projectRoot ?? this.cwd;
+        this.isGitProject = options.isGitProject ?? false;
+        const settingsCtx = projectSettingsContext(this.cwd, this.projectRoot, this.isGitProject);
         this.maxConcurrent =
             options.maxConcurrent ??
-                readMaxConcurrentFromFile(this.cwd) ??
+                readMaxConcurrentFromContext(settingsCtx) ??
                 parseMaxConcurrent(process.env.STAGEFLOW_MAX_CONCURRENT_RUNS);
         this.maxActiveStagesPerRun = readMaxActiveStagesPerRun(process.env, options.maxActiveStagesPerRun);
         this.executionMode = readStageExecutionMode(process.env, options.executionMode);
@@ -106,7 +112,7 @@ export class RunManager {
             throw new Error(INVALID_SLOT_COUNT_MESSAGE);
         }
         this.maxConcurrent = parsed;
-        writeMaxConcurrentToFile(this.cwd, parsed);
+        writeMaxConcurrentToContext(projectSettingsContext(this.cwd, this.projectRoot, this.isGitProject), parsed);
         return this.getHealth();
     }
     getActiveCount() {
@@ -355,17 +361,32 @@ export class RunManager {
     }
     async rerun(runId) {
         const cwd = this.options.cwd ?? process.cwd();
-        let pipelineId;
+        let pipeline;
         let taskYaml;
+        let rerunCwd = cwd;
+        let rerunProjectRoot;
         try {
             const meta = await this.options.store.readRunMeta(runId);
-            pipelineId = meta.pipeline_id;
+            if (!meta.pipeline_path) {
+                return {
+                    ok: false,
+                    reason: `Run ${runId} is missing pipeline_path; re-run requires stored catalog locators.`,
+                    status: 400,
+                };
+            }
+            pipeline = normalizeCatalogPath(meta.pipeline_path);
+            rerunCwd = meta.project_root
+                ? normalizeCatalogPath(meta.project_root)
+                : cwd;
+            rerunProjectRoot = meta.project_root
+                ? normalizeCatalogPath(meta.project_root)
+                : undefined;
             taskYaml = await this.options.store.readTaskYaml(runId);
         }
         catch {
             return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
         }
-        return this.reserveAndStartPipeline(taskYaml, pipelineId, `run ${runId} task`, cwd);
+        return this.reserveAndStartPipeline(taskYaml, pipeline, `run ${runId} task`, rerunCwd, undefined, undefined, undefined, rerunProjectRoot);
     }
     async retryStage(runId, stageId) {
         const retryKey = waitKey(runId, stageId);
@@ -489,7 +510,6 @@ export class RunManager {
         }
     }
     async resumeViaSubprocess(runId, stageId, opaqueAnswer) {
-        const cwd = this.options.cwd ?? process.cwd();
         const store = this.options.store;
         const launcher = this.stageProcessLauncher;
         if (!launcher) {
@@ -504,7 +524,7 @@ export class RunManager {
             const launchResult = await launcher.launch({
                 runId,
                 stageId,
-                rootDir: cwd,
+                rootDir: this.projectRoot,
                 mode: "resume",
                 resumeAnswer: opaqueAnswer,
                 attempt,
@@ -531,10 +551,7 @@ export class RunManager {
             catch {
                 // downstream resume may read envelope from store
             }
-            const meta = await store.readRunMeta(runId);
-            const taskYaml = await store.readTaskYaml(runId);
-            const task = loadTaskFromYaml(taskYaml, `run ${runId} task`);
-            const loaded = await loadPipeline(meta.pipeline_id, { cwd });
+            const { meta, task, loaded } = await loadRunContext(store, runId, this.cwd);
             const rest = await resumeRun({
                 prepared: {
                     task,
@@ -542,7 +559,8 @@ export class RunManager {
                     run: { runId, workspaceDir: store.getWorkspaceDir(runId) },
                     agent: this.options.agent,
                     store,
-                    cwd,
+                    cwd: this.cwd,
+                    projectRoot: this.projectRoot,
                     checkoutRoot: meta.checkout_root,
                     hitl: this.hitl,
                     operatorCatalog: this.options.operatorCatalog,
@@ -590,6 +608,7 @@ export class RunManager {
                 executionMode: this.executionMode,
                 stageProcessLauncher: this.stageProcessLauncher,
                 cwd: this.cwd,
+                factoryCwd: this.projectRoot,
                 maxActiveStagesPerRun: this.maxActiveStagesPerRun,
                 operatorCatalog: this.options.operatorCatalog,
             });
@@ -598,7 +617,7 @@ export class RunManager {
             this.attachedWaiting.delete(`${runId}\0${stageId}`);
         }
     }
-    async reserveAndStartPipeline(taskYaml, pipelineId, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity) {
+    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot) {
         let checkoutKey;
         try {
             const task = loadTaskFromYaml(taskYaml, taskLabel);
@@ -623,8 +642,9 @@ export class RunManager {
                 agent: this.options.agent,
                 store: this.options.store,
                 taskYaml,
-                pipeline: pipelineId,
+                pipeline,
                 cwd,
+                projectRoot: projectRoot ?? this.projectRoot,
                 checkoutOverride,
                 gitSha: ciIdentity?.gitSha,
                 ciPrUrl: ciIdentity?.ciPrUrl,

package/dist/runtime/settingsFile.d.ts

@@ -1,3 +1,5 @@
+import type { ProjectContext } from "../project/resolveProjectContext.js";
+import type { StageflowContext } from "../project/resolveStageflowContext.js";
 export declare const SETTINGS_FILE_NAME = "settings.json";
 export declare const INVALID_SLOT_COUNT_MESSAGE = "maxConcurrent must be an integer >= 1";
 export declare const INVALID_CREDENTIAL_SOURCE_MESSAGE = "credentialSource must be \"pi_home\" or \"sf_owned\"";
@@ -6,12 +8,22 @@ export type FactorySettings = {
     maxConcurrent?: number;
     credentialSource?: CredentialSource;
 };
+export declare function globalSettingsFilePath(): string;
+export declare function settingsFilePathForContext(ctx: ProjectContext | StageflowContext): string;
 export declare function settingsFilePath(cwd: string): string;
 export declare function parseSlotCount(value: unknown): number | undefined;
 export declare function parseCredentialSource(value: unknown): CredentialSource | undefined;
+export declare function readCredentialSourceFromContext(ctx: ProjectContext): CredentialSource | undefined;
+export declare function readPersistedCredentialSourceFromContext(ctx: ProjectContext): CredentialSource | undefined;
+export declare function readFactorySettingsForContext(ctx: ProjectContext): FactorySettings;
 export declare function readFactorySettings(cwd: string): FactorySettings;
+export declare function writeFactorySettingsForContext(ctx: ProjectContext, patch: FactorySettings): void;
 export declare function writeFactorySettings(cwd: string, patch: FactorySettings): void;
+export declare function readMaxConcurrentFromContext(ctx: ProjectContext): number | undefined;
 export declare function readMaxConcurrentFromFile(cwd: string): number | undefined;
+export declare function writeMaxConcurrentToContext(ctx: ProjectContext, maxConcurrent: number): void;
 export declare function writeMaxConcurrentToFile(cwd: string, maxConcurrent: number): void;
 export declare function readCredentialSourceFromFile(cwd: string): CredentialSource | undefined;
+export declare function writeCredentialSourceToContext(ctx: ProjectContext, credentialSource: CredentialSource): void;
 export declare function writeCredentialSourceToFile(cwd: string, credentialSource: CredentialSource): void;
+export declare function projectSettingsContext(cwd: string, projectRoot: string, isGitProject: boolean): ProjectContext;

package/dist/runtime/settingsFile.js

@@ -1,11 +1,25 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { storeRootFor } from "../runstore/paths.js";
 export const SETTINGS_FILE_NAME = "settings.json";
 export const INVALID_SLOT_COUNT_MESSAGE = "maxConcurrent must be an integer >= 1";
 export const INVALID_CREDENTIAL_SOURCE_MESSAGE = 'credentialSource must be "pi_home" or "sf_owned"';
+export function globalSettingsFilePath() {
+    return path.join(globalStageflowHome(), SETTINGS_FILE_NAME);
+}
+export function settingsFilePathForContext(ctx) {
+    if (ctx.isGitProject) {
+        return path.join(storeRootFor(ctx.projectRoot), SETTINGS_FILE_NAME);
+    }
+    if (path.resolve(ctx.projectRoot) === path.resolve(os.homedir())) {
+        return path.join(ctx.globalHome, SETTINGS_FILE_NAME);
+    }
+    return path.join(storeRootFor(ctx.projectRoot), SETTINGS_FILE_NAME);
+}
 export function settingsFilePath(cwd) {
-    return path.join(storeRootFor(cwd), SETTINGS_FILE_NAME);
+    return path.join(storeRootFor(path.resolve(cwd)), SETTINGS_FILE_NAME);
 }
 export function parseSlotCount(value) {
     if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
@@ -19,8 +33,7 @@ export function parseCredentialSource(value) {
     }
     return undefined;
 }
-function readRawSettings(cwd) {
-    const filePath = settingsFilePath(cwd);
+function readRawSettingsFromFile(filePath) {
     if (!existsSync(filePath))
         return {};
     try {
@@ -34,8 +47,10 @@ function readRawSettings(cwd) {
         return {};
     }
 }
-export function readFactorySettings(cwd) {
-    const raw = readRawSettings(cwd);
+function readRawSettings(ctx) {
+    return readRawSettingsFromFile(settingsFilePathForContext(ctx));
+}
+function parseFactorySettingsFromRaw(raw) {
     const settings = {};
     const maxConcurrent = parseSlotCount(raw.maxConcurrent);
     if (maxConcurrent !== undefined) {
@@ -47,6 +62,54 @@ export function readFactorySettings(cwd) {
     }
     return settings;
 }
+export function readCredentialSourceFromContext(ctx) {
+    if (ctx.isGitProject) {
+        const fromProject = parseCredentialSource(readRawSettingsFromFile(settingsFilePathForContext(ctx)).credentialSource);
+        if (fromProject !== undefined) {
+            return fromProject;
+        }
+    }
+    return parseCredentialSource(readRawSettingsFromFile(globalSettingsFilePath()).credentialSource);
+}
+export function readPersistedCredentialSourceFromContext(ctx) {
+    return parseCredentialSource(readRawSettingsFromFile(settingsFilePathForContext(ctx)).credentialSource);
+}
+export function readFactorySettingsForContext(ctx) {
+    return parseFactorySettingsFromRaw(readRawSettings(ctx));
+}
+export function readFactorySettings(cwd) {
+    return parseFactorySettingsFromRaw(readRawSettingsFromFile(settingsFilePath(cwd)));
+}
+function ensureSettingsDirForContext(ctx) {
+    mkdirSync(path.dirname(settingsFilePathForContext(ctx)), { recursive: true });
+}
+export function writeFactorySettingsForContext(ctx, patch) {
+    if (patch.credentialSource !== undefined &&
+        parseCredentialSource(patch.credentialSource) === undefined) {
+        throw new Error(INVALID_CREDENTIAL_SOURCE_MESSAGE);
+    }
+    if (patch.maxConcurrent !== undefined &&
+        parseSlotCount(patch.maxConcurrent) === undefined) {
+        throw new Error(INVALID_SLOT_COUNT_MESSAGE);
+    }
+    const current = readFactorySettingsForContext(ctx);
+    const next = { ...current };
+    if (patch.maxConcurrent !== undefined) {
+        next.maxConcurrent = patch.maxConcurrent;
+    }
+    if (patch.credentialSource !== undefined) {
+        next.credentialSource = patch.credentialSource;
+    }
+    const out = {};
+    if (next.maxConcurrent !== undefined) {
+        out.maxConcurrent = next.maxConcurrent;
+    }
+    if (next.credentialSource !== undefined) {
+        out.credentialSource = next.credentialSource;
+    }
+    ensureSettingsDirForContext(ctx);
+    writeFileSync(settingsFilePathForContext(ctx), `${JSON.stringify(out, null, 2)}\n`, "utf8");
+}
 export function writeFactorySettings(cwd, patch) {
     if (patch.credentialSource !== undefined &&
         parseCredentialSource(patch.credentialSource) === undefined) {
@@ -71,18 +134,36 @@ export function writeFactorySettings(cwd, patch) {
     if (next.credentialSource !== undefined) {
         out.credentialSource = next.credentialSource;
     }
-    mkdirSync(storeRootFor(cwd), { recursive: true });
+    const root = path.resolve(cwd);
+    mkdirSync(storeRootFor(root), { recursive: true });
     writeFileSync(settingsFilePath(cwd), `${JSON.stringify(out, null, 2)}\n`, "utf8");
 }
+export function readMaxConcurrentFromContext(ctx) {
+    return readFactorySettingsForContext(ctx).maxConcurrent;
+}
 export function readMaxConcurrentFromFile(cwd) {
     return readFactorySettings(cwd).maxConcurrent;
 }
+export function writeMaxConcurrentToContext(ctx, maxConcurrent) {
+    writeFactorySettingsForContext(ctx, { maxConcurrent });
+}
 export function writeMaxConcurrentToFile(cwd, maxConcurrent) {
     writeFactorySettings(cwd, { maxConcurrent });
 }
 export function readCredentialSourceFromFile(cwd) {
     return readFactorySettings(cwd).credentialSource;
 }
+export function writeCredentialSourceToContext(ctx, credentialSource) {
+    writeFactorySettingsForContext(ctx, { credentialSource });
+}
 export function writeCredentialSourceToFile(cwd, credentialSource) {
     writeFactorySettings(cwd, { credentialSource });
 }
+export function projectSettingsContext(cwd, projectRoot, isGitProject) {
+    return {
+        invocationCwd: path.resolve(cwd),
+        projectRoot: path.resolve(projectRoot),
+        globalHome: globalStageflowHome(),
+        isGitProject,
+    };
+}

package/dist/runtime/stageAttemptBootstrap.d.ts

@@ -27,6 +27,7 @@ export type StageAttemptOpenInput = {
     resumeToken?: string;
     workerRoots?: boolean;
     completedEnvelopes?: Map<string, StageEnvelope>;
+    stageId?: string;
 };
 export type StageAttemptOpenResult = {
     ok: true;

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,4 +1,5 @@
 import { resolveSkillByName } from "../config/listSkills.js";
+import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
 import { resumeSessionFilePath } from "./stageAttemptContext.js";
 import { buildStageRoots, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
@@ -38,38 +39,48 @@ async function openStageWithOperatorCatalog(agent, input, catalog) {
         };
     }
 }
-function resolveAttemptRoots(input) {
+function resolveAttemptRoots(input, stageId) {
     const baseRoots = input.roots ??
         (input.workerRoots
-            ? rootsForStageWorker(input.workspaceDir, input.stage.id, input.stage.model, input.checkoutRoot, input.attemptCtx)
-            : buildStageRoots(input.workspaceDir, input.stage.id, input.checkoutRoot, input.attemptCtx));
+            ? rootsForStageWorker(input.workspaceDir, stageId, input.stage.model, input.checkoutRoot, input.attemptCtx)
+            : buildStageRoots(input.workspaceDir, stageId, input.checkoutRoot, input.attemptCtx));
     return input.factoryCwd !== undefined
         ? withResolvedAuthPath(baseRoots, input.factoryCwd)
         : baseRoots;
 }
 export async function openStageAttempt(input) {
+    const stageId = input.stageId ?? input.stage.id;
+    const definitionId = input.stage.id;
     const completedEnvelopes = input.completedEnvelopes ??
-        (await buildCompletedEnvelopesFromRun(input.store, input.runId));
+        (await buildCompletedEnvelopesFromRun(input.store, input.runId, undefined, input.dag));
     const priorResult = await resolvePriorEnvelope({
         dag: input.dag,
-        stageId: input.stage.id,
+        stageId,
         completedEnvelopes,
         store: input.store,
         runId: input.runId,
     });
     if (!priorResult.ok)
         return priorResult;
-    const roots = resolveAttemptRoots(input);
+    const roots = resolveAttemptRoots(input, stageId);
     const attempt = input.attemptCtx?.attempt ?? 1;
     const resumeToken = input.resumeToken ??
-        resumeSessionFilePath(input.workspaceDir, input.stage.id, attempt);
+        resumeSessionFilePath(input.workspaceDir, stageId, attempt);
+    const forkEmitContext = resolveForkEmitContext(input.dag, definitionId);
+    const cloneEmitContext = resolveCloneEmitContext(input.dag, definitionId);
     const opened = await openStageWithOperatorCatalog(input.agent, {
         roots,
         stage: input.stage,
+        stageId,
         task: input.task,
         priorEnvelope: priorResult.prior,
+        ...(priorResult.joinPriors !== undefined
+            ? { priorEnvelopes: priorResult.joinPriors }
+            : {}),
         resumeToken,
         onActivity: input.onActivity,
+        forkEmitContext,
+        cloneEmitContext,
     }, input.operatorCatalog);
     if (!opened.ok)
         return opened;

package/dist/runtime/stageProcessLauncher.js

@@ -132,6 +132,9 @@ export class StageProcessLauncher {
         if (input.sessionFilePath !== undefined) {
             args.push("--session-file", input.sessionFilePath);
         }
+        if (input.operatorCatalog?.cwd !== undefined) {
+            args.push("--operator-cwd", input.operatorCatalog.cwd);
+        }
         if (input.operatorCatalog?.agentDir !== undefined) {
             args.push("--operator-agent-dir", input.operatorCatalog.agentDir);
         }

package/dist/runtime/stageRecovery.js

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

package/dist/runtime/stageRunner.d.ts

@@ -44,6 +44,7 @@ export type RunStageOptions = {
     operatorCatalog?: OperatorCatalog;
     completedEnvelopes?: Map<string, StageEnvelope>;
     skipGates?: boolean;
+    stageId?: string;
 };
 /**
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).

package/dist/runtime/stageRunner.js

@@ -114,28 +114,29 @@ export async function runStageYieldLoop(options) {
 }
 export async function runStage(options) {
     const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, } = options;
+    const stageId = options.stageId ?? stage.id;
     const attemptOpt = attemptCtx?.eventOptions();
     const baseRoots = rootsOverride ??
-        buildStageRoots(workspaceDir ?? store.getWorkspaceDir(runId), stage.id, checkoutRoot, attemptCtx);
+        buildStageRoots(workspaceDir ?? store.getWorkspaceDir(runId), stageId, checkoutRoot, attemptCtx);
     const roots = factoryCwd !== undefined
         ? withResolvedAuthPath(baseRoots, factoryCwd)
         : baseRoots;
     const attempt = attemptCtx?.attempt ?? 1;
-    await ensureStageExecutionForAttempt(store, runId, stage.id, attempt);
-    await store.ensureAttemptWorkspace(runId, stage.id, attempt);
+    await ensureStageExecutionForAttempt(store, runId, stageId, attempt);
+    await store.ensureAttemptWorkspace(runId, stageId, attempt);
     if (!skipStarted) {
         await appendLifecycleEventAndPatchExecution({
             store,
             runId,
-            stageId: stage.id,
+            stageId,
             event: { event: "started" },
             attemptCtx,
         });
     }
-    console.error(`Running stage ${stage.id} (${stage.model})...`);
+    console.error(`Running stage ${stageId} (${stage.model})...`);
     let activityChain = Promise.resolve();
     const enqueueActivity = (event) => {
-        activityChain = activityChain.then(() => store.appendStageEvent(runId, stage.id, event, attemptOpt));
+        activityChain = activityChain.then(() => store.appendStageEvent(runId, stageId, event, attemptOpt));
     };
     let handle;
     if (existingHandle) {
@@ -147,12 +148,13 @@ export async function runStage(options) {
             store,
             runId,
             stage,
+            stageId,
             task,
             dag: dag ?? {
                 nodes: [
-                    { id: stage.id, needs: null, ancestors: [], stageIndex: 0 },
+                    { id: stageId, needs: null, ancestors: [], stageIndex: 0 },
                 ],
-                roots: [stage.id],
+                roots: [stageId],
                 childrenOf: {},
             },
             checkoutRoot,
@@ -170,11 +172,11 @@ export async function runStage(options) {
             await appendLifecycleEventAndPatchExecution({
                 store,
                 runId,
-                stageId: stage.id,
+                stageId,
                 event: { event: "failed", reason: opened.reason },
                 attemptCtx,
             });
-            console.error(`Stage ${stage.id} failed: ${opened.reason}`);
+            console.error(`Stage ${stageId} failed: ${opened.reason}`);
             return { ok: false, reason: opened.reason };
         }
         handle = opened.handle;
@@ -184,7 +186,7 @@ export async function runStage(options) {
         outcome = await runStageYieldLoop({
             handle,
             runId,
-            stageId: stage.id,
+            stageId,
             hitl,
             workerMode,
             store: workerMode ? store : undefined,
@@ -195,15 +197,15 @@ export async function runStage(options) {
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
         await activityChain;
-        hitl?.clearLiveWait(runId, stage.id);
+        hitl?.clearLiveWait(runId, stageId);
         await appendLifecycleEventAndPatchExecution({
             store,
             runId,
-            stageId: stage.id,
+            stageId,
             event: { event: "failed", reason },
             attemptCtx,
         });
-        console.error(`Stage ${stage.id} failed: ${reason}`);
+        console.error(`Stage ${stageId} failed: ${reason}`);
         await handle.close().catch(() => undefined);
         return { ok: false, reason };
     }
@@ -216,7 +218,7 @@ export async function runStage(options) {
         return await finalizeStageResult({
             store,
             runId,
-            stageId: stage.id,
+            stageId,
             result: outcome,
             activityChain,
             attemptCtx,