stageflow 0.42.0 → 0.44.0

package/dist/runtime/priorArtifactGrants.js

@@ -0,0 +1,105 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+import { acceptArtifactListedPath, isGrantableArtifactPath, } from "./artifactPath.js";
+import { inspectArtifactUnderRoot } from "./artifactDiskInspect.js";
+import { SANDBOX_MOUNT_PATH } from "./sandboxContainer.js";
+export { isGrantableArtifactPath } from "./artifactPath.js";
+function successArtifactsFromPrior(prior) {
+    const envelopes = [];
+    if (prior.prior !== null && prior.prior !== undefined) {
+        envelopes.push(prior.prior);
+    }
+    if (prior.joinPriors !== undefined) {
+        envelopes.push(...prior.joinPriors);
+    }
+    if (prior.priorEnvelopesByStage !== undefined) {
+        for (const value of Object.values(prior.priorEnvelopesByStage)) {
+            if (Array.isArray(value))
+                envelopes.push(...value);
+            else
+                envelopes.push(value);
+        }
+    }
+    const listed = [];
+    for (const envelope of envelopes) {
+        if (envelope.status !== "success")
+            continue;
+        listed.push(...envelope.artifacts);
+    }
+    return listed;
+}
+/**
+ * Soft-skip grant host resolution: missing / symlink / non-file → null.
+ * Closed-posture walk via inspect; realpath must stay inside the workspace.
+ */
+async function resolveGrantableHostFile(workspaceRoot, listedPath) {
+    try {
+        const presence = await inspectArtifactUnderRoot(workspaceRoot, listedPath);
+        if (presence.file_type !== "file" || presence.absolutePath === undefined) {
+            return null;
+        }
+        const current = presence.absolutePath;
+        if (!isInsideDir(current, workspaceRoot) || current === workspaceRoot) {
+            return null;
+        }
+        const workspaceReal = await realpath(workspaceRoot);
+        const fileReal = await realpath(current);
+        if (!isInsideDir(fileReal, workspaceReal) || fileReal === workspaceReal) {
+            return null;
+        }
+        return current;
+    }
+    catch {
+        return null;
+    }
+}
+/** Sandbox path for one artifact. Colliding names from different attempts include the attempt. */
+export function assignGrantContainerPaths(listedPaths) {
+    const parsed = listedPaths.map((listedPath) => {
+        const parts = acceptArtifactListedPath(listedPath, { kind: "grantable" });
+        const base = parts === undefined
+            ? null
+            : `${SANDBOX_MOUNT_PATH}/grants/${parts.stageId}/${parts.relative}`;
+        return { listedPath, parts, base };
+    });
+    const counts = new Map();
+    for (const item of parsed) {
+        if (item.base === null)
+            continue;
+        counts.set(item.base, (counts.get(item.base) ?? 0) + 1);
+    }
+    const assigned = new Map();
+    for (const item of parsed) {
+        if (item.parts === undefined || item.base === null)
+            continue;
+        const containerPath = (counts.get(item.base) ?? 0) > 1
+            ? `${SANDBOX_MOUNT_PATH}/grants/${item.parts.stageId}/attempt-${item.parts.attempt}/${item.parts.relative}`
+            : item.base;
+        assigned.set(item.listedPath, containerPath);
+    }
+    return assigned;
+}
+export async function artifactGrantsFromPriors(workspaceDir, prior) {
+    const workspaceRoot = path.resolve(workspaceDir);
+    const listed = successArtifactsFromPrior(prior).filter(isGrantableArtifactPath);
+    const containerPaths = assignGrantContainerPaths(listed);
+    const grants = [];
+    const seen = new Set();
+    for (const listedPath of listed) {
+        const containerPath = containerPaths.get(listedPath);
+        if (containerPath === undefined)
+            continue;
+        const hostPath = await resolveGrantableHostFile(workspaceRoot, listedPath);
+        if (hostPath === null || seen.has(hostPath))
+            continue;
+        seen.add(hostPath);
+        grants.push({
+            listedPath,
+            hostPath,
+            containerPath,
+            kind: "file",
+        });
+    }
+    return grants;
+}

package/dist/runtime/runActionEligibility.d.ts

@@ -0,0 +1,46 @@
+import { type RunDetail, type RunPipelineDagSnapshot, type RunStatus, type StageSnapshot } from "../runstore/port.js";
+export type StageRetrySubject = Pick<StageSnapshot, "stage_id" | "status" | "definition_id" | "envelope">;
+export type RunActionEligibilityInput = {
+    runStatus: RunStatus;
+    stage?: StageRetrySubject;
+    stages?: ReadonlyArray<Pick<StageSnapshot, "status" | "stage_id">>;
+    recoveryActive?: boolean;
+    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
+};
+export type RunActionEligibility = {
+    canRetry: boolean;
+    canCancel: boolean;
+    canAbandon: boolean;
+    blockers: string[];
+};
+export declare function resumesRunOnStageRetry(status: RunStatus): boolean;
+export declare function canCancelRun(status: RunStatus): boolean;
+export declare function canAbandonStage(stageStatus: string): boolean;
+export declare function succeededStageRetryBlocker(stageSnap: StageRetrySubject): string | undefined;
+export declare function stageRetryBlocker(input: {
+    runStatus: RunStatus;
+    stage: StageRetrySubject;
+    stages?: ReadonlyArray<Pick<StageSnapshot, "status" | "stage_id">>;
+    recoveryActive?: boolean;
+    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
+}): string | undefined;
+export declare function canRetryStage(input: {
+    runStatus: RunStatus;
+    stage: StageRetrySubject;
+    stages?: ReadonlyArray<Pick<StageSnapshot, "status" | "stage_id">>;
+    recoveryActive?: boolean;
+    dag?: Pick<RunPipelineDagSnapshot, "nodes"> | null;
+}): boolean;
+export declare function runActionEligibility(input: RunActionEligibilityInput): RunActionEligibility;
+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;
+};

package/dist/runtime/runActionEligibility.js

@@ -0,0 +1,123 @@
+import { findUnhandledFailedStage, } from "../runstore/port.js";
+import { isRunClockTerminal } from "../runstore/runStatusClock.js";
+export function resumesRunOnStageRetry(status) {
+    return isRunClockTerminal(status);
+}
+export function canCancelRun(status) {
+    return status !== "succeeded" && status !== "failed";
+}
+export function canAbandonStage(stageStatus) {
+    return stageStatus === "running";
+}
+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 stageRetryBlocker(input) {
+    const { stage, runStatus } = input;
+    if (stage.status === "waiting_for_input") {
+        return `Stage is waiting for input and cannot be retried`;
+    }
+    const recoveryActive = input.recoveryActive === true;
+    if (!resumesRunOnStageRetry(runStatus)) {
+        const stages = input.stages ?? [];
+        const acceptedPendingRetry = runStatus === "running" &&
+            stage.status === "failed" &&
+            findUnhandledFailedStage(stages, input.dag) === undefined &&
+            stages.some((s) => s.status === "pending");
+        if (!(runStatus === "running" && recoveryActive) && !acceptedPendingRetry) {
+            return `Run is not failed or succeeded (status=${runStatus})`;
+        }
+    }
+    if (stage.status !== "failed" && stage.status !== "succeeded") {
+        return `Stage is not failed or succeeded (status=${stage.status})`;
+    }
+    if (stage.status === "succeeded") {
+        return succeededStageRetryBlocker(stage);
+    }
+    return undefined;
+}
+export function canRetryStage(input) {
+    return stageRetryBlocker(input) === undefined;
+}
+export function runActionEligibility(input) {
+    const blockers = [];
+    const canCancel = canCancelRun(input.runStatus);
+    if (!canCancel) {
+        blockers.push(`Run is ${input.runStatus} and cannot be cancelled`);
+    }
+    const canAbandon = input.stage !== undefined && canAbandonStage(input.stage.status);
+    if (input.stage !== undefined && !canAbandon) {
+        blockers.push(`Stage is not running (status=${input.stage.status})`);
+    }
+    let canRetry = false;
+    if (input.stage === undefined) {
+        blockers.push("Stage is required to retry");
+    }
+    else {
+        const retryBlocker = stageRetryBlocker({
+            runStatus: input.runStatus,
+            stage: input.stage,
+            stages: input.stages,
+            recoveryActive: input.recoveryActive,
+            dag: input.dag,
+        });
+        if (retryBlocker === undefined) {
+            canRetry = true;
+        }
+        else {
+            blockers.push(retryBlocker);
+        }
+    }
+    return { canRetry, canCancel, canAbandon, blockers };
+}
+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",
+        };
+    }
+    const runStatus = opts?.persistedStatus ?? detail.status;
+    const blocker = stageRetryBlocker({
+        runStatus,
+        stage: stageSnap,
+        stages: detail.stages,
+        recoveryActive: opts?.recoveryActive,
+        dag: opts?.dag,
+    });
+    if (blocker === undefined) {
+        return { ok: true };
+    }
+    if (blocker.includes("waiting for input")) {
+        return {
+            ok: false,
+            reason: blocker,
+            status: 409,
+            code: "hitl_not_retriable",
+        };
+    }
+    if (blocker.startsWith("Stage is not failed or succeeded")) {
+        return {
+            ok: false,
+            reason: blocker,
+            status: 409,
+            code: "stage_not_failed",
+        };
+    }
+    return {
+        ok: false,
+        reason: blocker,
+        status: 409,
+        code: "run_not_retryable",
+    };
+}

package/dist/runtime/runManager.d.ts

@@ -285,6 +285,7 @@ export declare class RunManager {
     private notifyGateClosed;
     abandonStage(runId: string, stageId: string): Promise<AbandonStageResult>;
     cancelRun(runId: string, reason: string): Promise<CancelRunResult>;
+    private interruptLiveStages;
     setA2aStore(store: A2aStore): void;
     deleteRun(runId: string, options?: {
         force?: boolean;
@@ -321,7 +322,9 @@ export declare class RunManager {
         pinned?: boolean;
         callerId?: string | null;
     }): Promise<StartRunResult>;
-    retryStage(runId: string, stageId: string): Promise<RetryStageResult>;
+    retryStage(runId: string, stageId: string, options?: {
+        awaitRoot?: boolean;
+    }): Promise<RetryStageResult>;
     resumeTimedOutStage(runId: string, stageId: string, options?: {
         source?: "explicit" | "auto";
     }): Promise<RetryStageResult>;

package/dist/runtime/runManager.js

@@ -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;
     }
@@ -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) {

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;