stageflow 0.40.0 → 0.44.0

package/dist/runtime/runManager.js

@@ -530,7 +530,7 @@ export class RunManager {
      */
     async attachWaitingStages() {
         const found = [];
-        const runs = await this.options.store.listRuns();
+        const runs = await this.options.store.listRuns({ origin: "any" });
         for (const summary of runs) {
             if (summary.status !== "running")
                 continue;
@@ -627,7 +627,7 @@ export class RunManager {
     }
     async reconcileOrphanedStages() {
         const reconciled = [];
-        const runs = await this.options.store.listRuns();
+        const runs = await this.options.store.listRuns({ origin: "any" });
         for (const summary of runs) {
             let meta;
             try {
@@ -806,7 +806,7 @@ export class RunManager {
     }
     async resumeStalledSchedules() {
         const resumed = [];
-        const runs = await this.options.store.listRuns();
+        const runs = await this.options.store.listRuns({ origin: "any" });
         for (const summary of runs) {
             if (summary.status !== "running")
                 continue;
@@ -828,7 +828,7 @@ export class RunManager {
     }
     /** Rebuild in-memory admission queue from persisted `queued` rows (R27). */
     async reenqueuePersistedQueuedRuns() {
-        const queued = await this.options.store.listRuns({ status: "queued" });
+        const queued = await this.options.store.listRuns({ status: "queued", origin: "any" });
         const ordered = [...queued].sort((a, b) => a.created_at.localeCompare(b.created_at));
         this.admissionQueue.clear();
         for (const row of ordered) {
@@ -988,7 +988,16 @@ export class RunManager {
         catch {
             return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
         }
+        const trimmedReason = reason.trim();
+        if (trimmedReason.length === 0) {
+            return {
+                ok: false,
+                reason: "Cancel reason is required",
+                status: 400,
+            };
+        }
         if (meta.status === "cancelled") {
+            await this.interruptLiveStages(runId);
             return { ok: true, runId };
         }
         if (meta.status === "succeeded" || meta.status === "failed") {
@@ -998,14 +1007,6 @@ export class RunManager {
                 status: 409,
             };
         }
-        const trimmedReason = reason.trim();
-        if (trimmedReason.length === 0) {
-            return {
-                ok: false,
-                reason: "Cancel reason is required",
-                status: 400,
-            };
-        }
         await this.options.store.updateRunStatus(runId, "cancelled");
         this.notifyGateClosed(runId);
         await this.options.store.setCancelReason(runId, trimmedReason);
@@ -1056,6 +1057,39 @@ export class RunManager {
         }
         return { ok: true, runId };
     }
+    async interruptLiveStages(runId) {
+        const halt = this.schedulingHalts.get(runId);
+        if (halt !== undefined) {
+            halt.halted = true;
+        }
+        if (this.stageProcessLauncher !== undefined) {
+            await this.stageProcessLauncher.cancelRun(runId);
+        }
+        const detail = await this.options.store.readRun(runId);
+        for (const stage of detail.stages) {
+            if (stage.status !== "running" && stage.status !== "waiting_for_input") {
+                continue;
+            }
+            const wasWaiting = stage.status === "waiting_for_input";
+            await markStageInterrupted({
+                store: this.options.store,
+                runId,
+                stageId: stage.stage_id,
+                reason: OPERATOR_CANCEL_REASON,
+                status: "failed",
+            });
+            if (this.retryCoordinator.isActive(runId) &&
+                this.retryCoordinator.getActiveRoots(runId)?.has(stage.stage_id)) {
+                this.retryCoordinator.signalExternalRetryRootTerminal(runId, stage.stage_id);
+            }
+            if (wasWaiting) {
+                this.hitl.clearLiveWait(runId, stage.stage_id);
+            }
+        }
+        if (this.active.has(runId)) {
+            this.removeActiveEntry(runId, false);
+        }
+    }
     setA2aStore(store) {
         this.a2aStore = store;
     }
@@ -1273,7 +1307,7 @@ export class RunManager {
             gitSha: input.gitSha,
             ciPrUrl: input.ciPrUrl,
             ciJobUrl: input.ciJobUrl,
-        }, derivedProjectRoot, resolved.kind === "path" ? resolved.taskPath : undefined, submission, undefined, input.callerId, input.skills, input.dispatchKey);
+        }, derivedProjectRoot, resolved.kind === "path" ? resolved.taskPath : undefined, submission, undefined, input.callerId, input.skills, input.dispatchKey, input.origin);
     }
     async rerun(runId, options) {
         if (!this.acceptingWork) {
@@ -1357,8 +1391,8 @@ export class RunManager {
         }
         return this.reserveAndStartPipeline(taskYaml, pipeline, `run ${runId} task`, rerunCwd, undefined, skipGates, ciIdentity, rerunProjectRoot, undefined, undefined, pinned, options?.callerId);
     }
-    async retryStage(runId, stageId) {
-        return this.retryStageInternal(runId, stageId, true);
+    async retryStage(runId, stageId, options) {
+        return this.retryStageInternal(runId, stageId, options?.awaitRoot !== false);
     }
     async resumeTimedOutStage(runId, stageId, options) {
         if (!this.acceptingWork) {
@@ -1622,6 +1656,14 @@ export class RunManager {
             if (!result.ok || awaitRoot !== false) {
                 this.retryInFlight.delete(retryKey);
             }
+            else if (result.done !== undefined) {
+                void result.done.finally(() => {
+                    this.retryInFlight.delete(retryKey);
+                });
+            }
+            else {
+                this.retryInFlight.delete(retryKey);
+            }
             return result;
         }
         catch (err) {
@@ -2219,7 +2261,7 @@ export class RunManager {
             this.attachedWaiting.delete(`${runId}\0${stageId}`);
         }
     }
-    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath, submission, pinned, callerId, skills, dispatchKey) {
+    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath, submission, pinned, callerId, skills, dispatchKey, origin) {
         const persistence = pipelinePersistenceForStart(pipeline);
         if (!persistence.ok) {
             return {
@@ -2419,6 +2461,7 @@ export class RunManager {
                 ...(callerId !== undefined && callerId !== null
                     ? { callerId }
                     : {}),
+                ...(origin !== undefined ? { origin } : {}),
                 runManifest,
                 skipGates,
             });
@@ -2506,6 +2549,7 @@ export class RunManager {
                 skipGates,
                 schedulingHalt,
                 callerId,
+                ...(origin !== undefined ? { origin } : {}),
                 ...(hasSkills ? { skills: validatedSkills } : {}),
             });
             if (started.created === false)

package/dist/runtime/runRetentionSweep.js

@@ -252,7 +252,7 @@ export async function runRetentionSweep(store, a2aStore, options = {}) {
     const windows = options.windows ?? retentionWindowsFromEnv(env);
     const artifactMaxBytes = options.artifactMaxBytes ?? slimArtifactMaxBytesFromEnv(env);
     const bareCacheTtlMs = options.bareCacheTtlMs ?? bareCacheTtlFromEnv(env);
-    const runs = await store.listRuns();
+    const runs = await store.listRuns({ origin: "any" });
     const slimmed = [];
     const purged = [];
     const metas = new Map();
@@ -305,7 +305,7 @@ export async function runRetentionSweep(store, a2aStore, options = {}) {
         }
     }
     // Re-list for bare-cache decisions after PURGE removed rows when execute.
-    const runsForBare = execute ? await store.listRuns() : runs;
+    const runsForBare = execute ? await store.listRuns({ origin: "any" }) : runs;
     const bareCachesEvicted = await evictBareCaches({
         runs: runsForBare,
         now,

package/dist/runtime/runRetryCoordinator.d.ts

@@ -1,5 +1,5 @@
 import type { StagePort } from "../agent/port.js";
-import { type RunDetail, type RunPipelineDagSnapshot, type RunStatus, type RunStore, type StageSnapshot } from "../runstore/port.js";
+import type { RunStatus, RunStore } from "../runstore/port.js";
 import type { PipelineRunResult } from "./pipelineRunner.js";
 import { type SchedulerPreparedPipeline } from "./pipelineScheduler.js";
 import type { StageExecutionMode } from "./stageConcurrency.js";
@@ -7,6 +7,7 @@ import type { StageBrowserSupport } from "../browser/browserHost.js";
 import type { StageProcessLauncher } from "./stageProcessLauncher.js";
 import type { StageHitlController } from "./stageHitl.js";
 import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
+export { assertStageRetryEligible, resumesRunOnStageRetry, succeededStageRetryBlocker, } from "./runActionEligibility.js";
 export declare class DuplicateRetryRootError extends Error {
     constructor(runId: string, stageId: string);
 }
@@ -69,19 +70,6 @@ export type RetryStageRequest = {
     awaitRoot?: boolean;
     beforeAttemptStart?: (attempt: number) => Promise<void>;
 };
-export declare function succeededStageRetryBlocker(stageSnap: StageSnapshot): string | undefined;
-export declare function assertStageRetryEligible(detail: RunDetail, stageId: string, opts?: {
-    recoveryActive?: boolean;
-    persistedStatus?: RunStatus;
-    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
-}): {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-    status: number;
-    code: string;
-};
 export declare function readRetryRootWaitTimeoutMs(): number;
 export declare class RunRetryCoordinator {
     private readonly sessions;

package/dist/runtime/runRetryCoordinator.js

@@ -1,7 +1,8 @@
-import { findUnhandledFailedStage, } from "../runstore/port.js";
 import { retryRun, } from "./pipelineScheduler.js";
 import { loadRunContext } from "./resumeReconstruct.js";
 import { syncRunStatusFromStages } from "./stageRecovery.js";
+import { assertStageRetryEligible, resumesRunOnStageRetry, } from "./runActionEligibility.js";
+export { assertStageRetryEligible, resumesRunOnStageRetry, succeededStageRetryBlocker, } from "./runActionEligibility.js";
 export class DuplicateRetryRootError extends Error {
     constructor(runId, stageId) {
         super(`Retry already in progress for run ${runId} stage ${stageId}`);
@@ -20,71 +21,6 @@ export class RetryRootWaitTimeoutError extends Error {
         this.name = "RetryRootWaitTimeoutError";
     }
 }
-export function succeededStageRetryBlocker(stageSnap) {
-    if (stageSnap.definition_id !== undefined &&
-        stageSnap.definition_id !== stageSnap.stage_id) {
-        return `Cannot re-run a succeeded clone instance stage (stage=${stageSnap.stage_id}, definition=${stageSnap.definition_id}): clone instances are created by upstream fan-out and cannot be rebuilt in place. Use rerun to start a new run.`;
-    }
-    if (stageSnap.envelope?.fork_choice !== undefined) {
-        return `Cannot re-run a succeeded fork stage (stage=${stageSnap.stage_id}): its envelope recorded a fork_choice and skipped branches cannot be restored. Use rerun to start a new run.`;
-    }
-    return undefined;
-}
-export function assertStageRetryEligible(detail, stageId, opts) {
-    const stageSnap = detail.stages.find((s) => s.stage_id === stageId);
-    if (!stageSnap) {
-        return {
-            ok: false,
-            reason: `Stage not found: ${stageId}`,
-            status: 404,
-            code: "stage_not_found",
-        };
-    }
-    if (stageSnap.status === "waiting_for_input") {
-        return {
-            ok: false,
-            reason: `Stage is waiting for input and cannot be retried`,
-            status: 409,
-            code: "hitl_not_retriable",
-        };
-    }
-    const runStatus = opts?.persistedStatus ?? detail.status;
-    const recoveryActive = opts?.recoveryActive === true;
-    if (runStatus !== "failed" && runStatus !== "succeeded") {
-        const acceptedPendingRetry = runStatus === "running" &&
-            stageSnap.status === "failed" &&
-            findUnhandledFailedStage(detail.stages, opts?.dag) === undefined &&
-            detail.stages.some((stage) => stage.status === "pending");
-        if (!(runStatus === "running" && recoveryActive) && !acceptedPendingRetry) {
-            return {
-                ok: false,
-                reason: `Run is not failed or succeeded (status=${runStatus})`,
-                status: 409,
-                code: "run_not_retryable",
-            };
-        }
-    }
-    if (stageSnap.status !== "failed" && stageSnap.status !== "succeeded") {
-        return {
-            ok: false,
-            reason: `Stage is not failed or succeeded (status=${stageSnap.status})`,
-            status: 409,
-            code: "stage_not_failed",
-        };
-    }
-    if (stageSnap.status === "succeeded") {
-        const blocker = succeededStageRetryBlocker(stageSnap);
-        if (blocker !== undefined) {
-            return {
-                ok: false,
-                reason: blocker,
-                status: 409,
-                code: "run_not_retryable",
-            };
-        }
-    }
-    return { ok: true };
-}
 function mutationKey(stageId, attempt) {
     return `${stageId}\0${attempt}`;
 }
@@ -318,7 +254,7 @@ export class RunRetryCoordinator {
                     };
                 }
                 insertedForResume = tracked.insertedForResume === true;
-                if (priorRunStatus === "failed" || priorRunStatus === "succeeded") {
+                if (resumesRunOnStageRetry(priorRunStatus)) {
                     await store.updateRunStatus(runId, "running");
                     bumpedRunning = true;
                 }

package/dist/runtime/sandboxContainer.d.ts

@@ -1,5 +1,7 @@
 export declare const SANDBOX_CONTAINER_IMAGE_ENV = "STAGEFLOW_STAGE_CONTAINER_IMAGE";
 export declare const SANDBOX_CONTAINER_DOCKER_BIN_ENV = "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN";
+/** One host directory bind-mounted read-only into every stage sandbox, at the same path. */
+export declare const STAGE_READONLY_DIR_ENV = "STAGEFLOW_STAGE_READONLY_DIR";
 /** Docker container names allow only `[a-zA-Z0-9_.-]`. */
 export declare function sanitizeContainerNameSegment(value: string): string;
 export declare function buildContainerName(input: {
@@ -18,9 +20,13 @@ export declare function resolveSandboxContainerOptions(env: Record<string, strin
 /** Fixed path inside the sandbox. The daemon owns the volume; we never pass it a path from this process. */
 export declare const SANDBOX_MOUNT_PATH = "/workspace";
 export declare function sandboxVolumeName(containerName: string): string;
+export declare function stageReadOnlyDir(env: Record<string, string | undefined>): string | undefined;
+export declare function assertStageReadOnlyDir(raw: string): string;
+export declare function assertStageReadOnlyDirExists(dir: string): Promise<void>;
 export declare function buildStartContainerArgs(params: {
     image: string;
     containerName: string;
+    readOnlyDir?: string;
 }): string[];
 export declare function startSandboxContainer(params: {
     image: string;
@@ -28,6 +34,7 @@ export declare function startSandboxContainer(params: {
     stageId: string;
     attempt?: number;
     dockerBin?: string;
+    readOnlyDir?: string;
 }): Promise<{
     containerName: string;
 }>;

package/dist/runtime/sandboxContainer.js

@@ -1,8 +1,12 @@
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { stat } from "node:fs/promises";
+import path from "node:path";
 import { promisify } from "node:util";
 export const SANDBOX_CONTAINER_IMAGE_ENV = "STAGEFLOW_STAGE_CONTAINER_IMAGE";
 export const SANDBOX_CONTAINER_DOCKER_BIN_ENV = "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN";
+/** One host directory bind-mounted read-only into every stage sandbox, at the same path. */
+export const STAGE_READONLY_DIR_ENV = "STAGEFLOW_STAGE_READONLY_DIR";
 const execFileAsync = promisify(execFile);
 /** Docker container names allow only `[a-zA-Z0-9_.-]`. */
 export function sanitizeContainerNameSegment(value) {
@@ -35,21 +39,55 @@ export function sandboxVolumeName(containerName) {
     const safe = containerName.replace(/[^A-Za-z0-9_.-]/g, "_");
     return `sf-bash-${safe}`;
 }
+export function stageReadOnlyDir(env) {
+    const raw = env[STAGE_READONLY_DIR_ENV];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    return assertStageReadOnlyDir(raw);
+}
+export function assertStageReadOnlyDir(raw) {
+    const trimmed = raw.trim();
+    if (!path.isAbsolute(trimmed)) {
+        throw new Error(`${STAGE_READONLY_DIR_ENV} must be an absolute path`);
+    }
+    if (trimmed.includes("\0") || trimmed.includes(":")) {
+        throw new Error(`${STAGE_READONLY_DIR_ENV} contains a character docker cannot mount`);
+    }
+    const resolved = path.resolve(trimmed);
+    const parts = resolved.split(path.sep).filter((part) => part.length > 0);
+    if (parts.length < 3) {
+        throw new Error(`${STAGE_READONLY_DIR_ENV} is too broad`);
+    }
+    return resolved;
+}
+export async function assertStageReadOnlyDirExists(dir) {
+    let info;
+    try {
+        info = await stat(dir);
+    }
+    catch {
+        throw new Error(`read-only folder is not available: ${dir}`);
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`read-only folder is not a directory: ${dir}`);
+    }
+}
 export function buildStartContainerArgs(params) {
     const { image, containerName } = params;
-    return [
+    const args = [
         "run",
         "-d",
         "--name",
         containerName,
         "-v",
         `${sandboxVolumeName(containerName)}:${SANDBOX_MOUNT_PATH}`,
-        "-w",
-        SANDBOX_MOUNT_PATH,
-        image,
-        "sleep",
-        "infinity",
     ];
+    if (params.readOnlyDir !== undefined) {
+        const dir = assertStageReadOnlyDir(params.readOnlyDir);
+        args.push("-v", `${dir}:${dir}:ro`);
+    }
+    args.push("-w", SANDBOX_MOUNT_PATH, image, "sleep", "infinity");
+    return args;
 }
 function errorMessage(err) {
     if (err && typeof err === "object" && "stderr" in err) {
@@ -61,9 +99,13 @@ function errorMessage(err) {
 }
 export async function startSandboxContainer(params) {
     const containerName = buildContainerName({ runId: params.runId, stageId: params.stageId, attempt: params.attempt }, randomUUID().slice(0, 8));
+    if (params.readOnlyDir !== undefined) {
+        await assertStageReadOnlyDirExists(params.readOnlyDir);
+    }
     const args = buildStartContainerArgs({
         image: params.image,
         containerName,
+        ...(params.readOnlyDir !== undefined ? { readOnlyDir: params.readOnlyDir } : {}),
     });
     try {
         await execFileAsync(params.dockerBin ?? "docker", args);

package/dist/runtime/sandboxDesk.d.ts

@@ -1,3 +1,4 @@
+import type { StageArtifactGrant } from "./stageRoots.js";
 export type SandboxDeskRole = "artifacts" | "envelope" | "checkout" | "grant" | "work";
 export type SandboxDeskBinding = {
     role: SandboxDeskRole;
@@ -14,7 +15,7 @@ export type SandboxDesk = {
 export declare function buildSandboxDesk(input: {
     attemptDir: string;
     checkoutRoot?: string;
-    grantedPaths?: readonly string[];
+    grants?: readonly StageArtifactGrant[];
 }): SandboxDesk;
 export declare function populateSandboxDesk(params: {
     containerName: string;

package/dist/runtime/sandboxDesk.js

@@ -37,16 +37,14 @@ export function buildSandboxDesk(input) {
             optional: false,
         });
     }
-    const grants = input.grantedPaths ?? [];
-    for (let index = 0; index < grants.length; index += 1) {
-        const hostPath = grants[index];
+    for (const grant of input.grants ?? []) {
         bindings.push({
             role: "grant",
-            hostPath,
-            containerPath: `${SANDBOX_MOUNT_PATH}/grants/${grantSegment(index, hostPath)}`,
-            shape: "mirror",
+            hostPath: grant.hostPath,
+            containerPath: grant.containerPath,
+            shape: grant.kind === "directory" ? "directory" : "file",
             copyIn: true,
-            copyOut: true,
+            copyOut: false,
             optional: false,
         });
     }
@@ -61,11 +59,6 @@ export function buildSandboxDesk(input) {
     });
     return { bindings };
 }
-function grantSegment(index, hostPath) {
-    const base = path.basename(hostPath).replace(/[^A-Za-z0-9_.-]/g, "_");
-    const safe = base.length > 0 && base !== "." && base !== ".." ? base : "path";
-    return `${index}-${safe}`;
-}
 async function pathExists(target) {
     try {
         await access(target);
@@ -85,6 +78,12 @@ export async function populateSandboxDesk(params) {
         if (binding.role === "checkout" || binding.shape === "mirror") {
             dirs.add(binding.containerPath);
         }
+        if (binding.role === "grant" && binding.shape === "file") {
+            dirs.add(path.posix.dirname(binding.containerPath));
+        }
+        if (binding.role === "grant" && binding.shape === "directory") {
+            dirs.add(binding.containerPath);
+        }
     }
     const made = await execInSandboxContainer({
         containerName: params.containerName,

package/dist/runtime/stageEnvironment.js

@@ -28,6 +28,7 @@ export const STAGE_ENV_ALLOWLIST = [
     "STAGEFLOW_CURSOR_EXTENSION",
     "STAGEFLOW_STAGE_CONTAINER_IMAGE",
     "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN",
+    "STAGEFLOW_STAGE_READONLY_DIR",
 ];
 export const PROVIDER_AND_CLOUD_NAMES = [
     "ANTHROPIC_API_KEY",

package/dist/runtime/stageRoots.d.ts

@@ -2,6 +2,14 @@ import type { RunMeta } from "../runstore/port.js";
 import type { StageAttemptContext } from "./stageAttemptContext.js";
 import type { TaskFile, TaskGitIdentity } from "../types/task.js";
 export type DerivedBindingKind = "repository" | "checkout" | "unbound";
+export type StageArtifactGrant = {
+    /** Run-relative path from the prior envelope. */
+    listedPath: string;
+    hostPath: string;
+    /** File or directory inside the sandbox, under /workspace/grants. */
+    containerPath: string;
+    kind: "file" | "directory";
+};
 export type StageRoots = {
     mode: "bound" | "unbound";
     cwd: string;
@@ -19,6 +27,10 @@ export type StageRoots = {
     containerName?: string;
     /** The docker binary the container above was started with (see STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN). */
     containerDockerBin?: string;
+    /** Host folder bind-mounted read-only into the sandbox at this same path. */
+    readonlyDir?: string;
+    /** Prior artifacts mounted into the sandbox. Empty or omitted when none are granted. */
+    artifactGrants?: readonly StageArtifactGrant[];
 };
 export declare const STAGEFLOW_CHECKOUT = "STAGEFLOW_CHECKOUT";
 export declare const STAGEFLOW_RUN_WORKSPACE = "STAGEFLOW_RUN_WORKSPACE";

package/dist/runtime/stageSandbox.d.ts

@@ -1,4 +1,4 @@
-import { type StageRoots } from "./stageRoots.js";
+import { type StageArtifactGrant, type StageRoots } from "./stageRoots.js";
 export type StageSandbox = {
     roots: StageRoots;
     beforeVerify?: () => Promise<void>;
@@ -13,4 +13,5 @@ export declare function openStageSandbox(input: {
     attempt: number;
     attemptDir: string;
     checkoutRoot?: string;
+    grants?: readonly StageArtifactGrant[];
 }): Promise<StageSandbox>;

package/dist/runtime/stageSandbox.js

@@ -1,4 +1,4 @@
-import { resolveSandboxContainerOptions, startSandboxContainer, stopSandboxContainer, } from "./sandboxContainer.js";
+import { assertStageReadOnlyDirExists, resolveSandboxContainerOptions, stageReadOnlyDir, startSandboxContainer, stopSandboxContainer, } from "./sandboxContainer.js";
 import { buildSandboxDesk, populateSandboxDesk, syncSandboxDesk, } from "./sandboxDesk.js";
 import { withContainerName } from "./stageRoots.js";
 export async function openStageSandbox(input) {
@@ -6,18 +6,34 @@ export async function openStageSandbox(input) {
     if (!options) {
         return { roots: input.roots, close: async () => { } };
     }
+    let readOnlyDir;
+    try {
+        readOnlyDir = stageReadOnlyDir(input.env);
+        if (readOnlyDir !== undefined)
+            await assertStageReadOnlyDirExists(readOnlyDir);
+    }
+    catch (err) {
+        return {
+            roots: input.roots,
+            close: async () => { },
+            failure: err instanceof Error ? err.message : String(err),
+        };
+    }
     const started = await startSandboxContainer({
         image: options.image,
         dockerBin: options.dockerBin,
         runId: input.runId,
         stageId: input.stageId,
         attempt: input.attempt,
+        ...(readOnlyDir !== undefined ? { readOnlyDir } : {}),
     });
-    const roots = withContainerName(input.roots, started.containerName, options.dockerBin);
+    const roots = withContainerName(readOnlyDir !== undefined ? { ...input.roots, readonlyDir: readOnlyDir } : input.roots, started.containerName, options.dockerBin);
     const checkout = input.checkoutRoot?.trim();
+    const grants = input.grants ?? [];
     const desk = buildSandboxDesk({
         attemptDir: input.attemptDir,
         ...(checkout ? { checkoutRoot: checkout } : {}),
+        ...(grants.length > 0 ? { grants } : {}),
     });
     const session = {
         roots,

package/dist/runtime/stageWorker.js

@@ -16,6 +16,9 @@ import { runStage, isRunStageWaiting, } from "./stageRunner.js";
 import { openStageAttempt } from "./stageAttemptBootstrap.js";
 import { attemptContext } from "./stageAttemptContext.js";
 import { loadActiveFeedbackLoopContext } from "./feedbackLoopCoordinator.js";
+import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
+import { assignment } from "./cloneSchedule.js";
+import { artifactGrantsFromPriors } from "./priorArtifactGrants.js";
 import { outcomeToWorkerResult, SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 export async function runStageWorker(input) {
     const store = createRunStore({ rootDir: globalStageflowHome() });
@@ -67,6 +70,19 @@ export async function runStageWorker(input) {
     const eventOptions = { attempt };
     let roots = withResolvedAuthPath(rootsForStageWorker(workspaceDir, input.stageId, stage.model, checkoutRoot, attemptCtx), input.rootDir);
     const unbindAgentDir = bindPiAgentDirEnv(roots.agentDir);
+    const completedEnvelopes = await buildCompletedEnvelopesFromRun(store, input.runId, undefined, dag);
+    const assigned = assignment(dag, input.stageId, definitionId, completedEnvelopes);
+    const priorResult = assigned ??
+        (await resolvePriorEnvelope({
+            dag,
+            stageId: input.stageId,
+            completedEnvelopes,
+            store,
+            runId: input.runId,
+        }));
+    const artifactGrants = priorResult.ok
+        ? await artifactGrantsFromPriors(workspaceDir, priorResult)
+        : [];
     const sandbox = await openStageSandbox({
         env: process.env,
         roots,
@@ -75,8 +91,12 @@ export async function runStageWorker(input) {
         attempt,
         attemptDir,
         ...(checkoutRoot !== undefined ? { checkoutRoot } : {}),
+        ...(artifactGrants.length > 0 ? { grants: artifactGrants } : {}),
     });
     roots = sandbox.roots;
+    if (artifactGrants.length > 0) {
+        roots = { ...roots, artifactGrants };
+    }
     const beforeVerify = sandbox.beforeVerify;
     let outcome;
     let thrown;