stageflow 0.36.0 → 0.40.0

package/dist/runtime/sandboxFiles.js

@@ -0,0 +1,150 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { copyToSandboxContainer, execInSandboxContainer, SANDBOX_MOUNT_PATH, } from "./sandboxContainer.js";
+export class SandboxPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SandboxPathError";
+    }
+}
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/** Resolve a tool path onto the sandbox mount. Host absolutes and `..` escapes are rejected. */
+export function confineSandboxPath(inputPath) {
+    if (typeof inputPath !== "string" || inputPath.trim() === "") {
+        throw new SandboxPathError("path must be a non-empty string");
+    }
+    if (inputPath.includes("\0") || inputPath.startsWith("~")) {
+        throw new SandboxPathError("path escapes the sandbox");
+    }
+    const slashes = inputPath.replaceAll("\\", "/");
+    const joined = slashes.startsWith("/")
+        ? path.posix.normalize(slashes)
+        : path.posix.normalize(path.posix.join(SANDBOX_MOUNT_PATH, slashes));
+    if (joined !== SANDBOX_MOUNT_PATH && !joined.startsWith(`${SANDBOX_MOUNT_PATH}/`)) {
+        throw new SandboxPathError("path escapes the sandbox");
+    }
+    return joined;
+}
+function assertFilePath(containerPath) {
+    if (containerPath === SANDBOX_MOUNT_PATH) {
+        throw new SandboxPathError("path must name a file under /workspace");
+    }
+}
+async function requireExec(result, fallback) {
+    if (result.exitCode === 0)
+        return;
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new Error(detail || fallback);
+}
+export async function readSandboxFile(target, inputPath) {
+    const containerPath = confineSandboxPath(inputPath);
+    assertFilePath(containerPath);
+    const quoted = shellQuote(containerPath);
+    const result = await execInSandboxContainer({
+        containerName: target.containerName,
+        dockerBin: target.dockerBin,
+        command: `if [ ! -f ${quoted} ]; then echo "No such file: ${containerPath}" >&2; exit 1; fi; base64 < ${quoted}`,
+    });
+    await requireExec(result, `failed to read ${containerPath}`);
+    return Buffer.from(result.stdout, "base64").toString("utf8");
+}
+export async function writeSandboxFile(target, inputPath, content) {
+    const containerPath = confineSandboxPath(inputPath);
+    assertFilePath(containerPath);
+    const parent = path.posix.dirname(containerPath);
+    const made = await execInSandboxContainer({
+        containerName: target.containerName,
+        dockerBin: target.dockerBin,
+        command: `mkdir -p -- ${shellQuote(parent)}`,
+    });
+    await requireExec(made, `failed to write ${containerPath}`);
+    const scratch = await mkdtemp(path.join(tmpdir(), "sf-sandbox-write-"));
+    const payload = path.join(scratch, "payload");
+    try {
+        await writeFile(payload, content);
+        await copyToSandboxContainer({
+            containerName: target.containerName,
+            dockerBin: target.dockerBin,
+            hostPath: payload,
+            containerPath,
+        });
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+export async function editSandboxFile(target, inputPath, edits) {
+    if (edits.length === 0) {
+        throw new Error("edits must contain at least one replacement");
+    }
+    const original = await readSandboxFile(target, inputPath);
+    const ranges = [];
+    for (const edit of edits) {
+        if (edit.oldText.length === 0) {
+            throw new Error("oldText must not be empty");
+        }
+        const count = countOccurrences(original, edit.oldText);
+        if (count !== 1) {
+            throw new Error(`oldText matched ${count} times`);
+        }
+        const start = original.indexOf(edit.oldText);
+        ranges.push({ start, end: start + edit.oldText.length, newText: edit.newText });
+    }
+    ranges.sort((a, b) => b.start - a.start);
+    for (let i = 0; i < ranges.length; i += 1) {
+        const later = ranges[i];
+        for (let j = i + 1; j < ranges.length; j += 1) {
+            const earlier = ranges[j];
+            if (earlier.end > later.start) {
+                throw new Error("edits overlap");
+            }
+        }
+    }
+    let next = original;
+    for (const range of ranges) {
+        next = next.slice(0, range.start) + range.newText + next.slice(range.end);
+    }
+    await writeSandboxFile(target, inputPath, next);
+}
+export function sliceSandboxLines(text, offset, limit) {
+    if (offset === undefined && limit === undefined)
+        return text;
+    const lines = text.split("\n");
+    const start = offset !== undefined ? Math.max(0, Math.floor(offset) - 1) : 0;
+    if (start >= lines.length) {
+        throw new Error(`Offset ${offset} is beyond end of file (${lines.length} lines total)`);
+    }
+    const end = limit !== undefined ? start + Math.max(0, Math.floor(limit)) : lines.length;
+    return lines.slice(start, end).join("\n");
+}
+export function formatSandboxBashResult(result) {
+    const parts = [result.stdout];
+    if (result.stderr.trim().length > 0)
+        parts.push(result.stderr);
+    parts.push(`Exit code: ${result.exitCode}`);
+    return parts.join("\n");
+}
+export async function runSandboxBash(target, command, timeoutMs) {
+    const result = await execInSandboxContainer({
+        containerName: target.containerName,
+        dockerBin: target.dockerBin,
+        command,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+    return formatSandboxBashResult(result);
+}
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let from = 0;
+    while (from <= haystack.length) {
+        const at = haystack.indexOf(needle, from);
+        if (at < 0)
+            return count;
+        count += 1;
+        from = at + needle.length;
+    }
+    return count;
+}

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,6 +1,10 @@
 import { emailHostFor, stageEmail, workerStageEmail, validateStageEmailAccounts } from "../email/host.js";
 import { ChannelError } from "../channels/errors.js";
 import { channelHostFor, stageChannels, validateStageChannelConnections, workerStageChannels } from "../channels/host.js";
+import { bindStageMemory } from "../memory/access.js";
+import { memoryHostFor } from "../memory/host.js";
+import { workerMemoryForStage } from "../memory/worker.js";
+import { memoryPrompt } from "../tools/memoryTools.js";
 import { EmailError } from "../email/port.js";
 import { bindingKindForOrigin, catalogOrSeededOrigin, decideWorkspaceConfigTrust, } from "../config/configOrigin.js";
 import { loginCheckPromptBlock, readStageLoginCheck, } from "../browser/loginCheck.js";
@@ -98,12 +102,13 @@ async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir, opt
     };
     const stageIdOpt = options.stageId !== undefined ? { stageId: options.stageId } : {};
     const bindingKind = bindingKindForOrigin(options.bindingKind);
-    if (factoryCwd !== undefined && (await mcpCatalogExists(factoryCwd))) {
+    if (factoryCwd !== undefined && (await mcpCatalogExists(factoryCwd, { scope: { kind: "validate" } }))) {
         await mkdir(artifactsDir, { recursive: true });
         const resolved = await resolveStageMcpServers({
             projectRoot: factoryCwd,
             allowlist: names,
             env,
+            scope: { kind: "stage", secrets: options.declaredSecrets ?? [] },
             bindingKind,
             trustWorkspaceConfig: options.trustWorkspaceConfig,
             ...stageIdOpt,
@@ -187,6 +192,7 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
             trustWorkspaceConfig: resolveOptions.trustWorkspaceConfig,
             stageEnv: resolveOptions.stageEnv,
             stageId: input.stageId,
+            declaredSecrets: (input.stage.secrets ?? []).map((d) => d.name),
         });
         resolvedMcpServers = mcp.servers;
         origins.push(...mcp.origins);
@@ -462,6 +468,11 @@ export async function openStageAttempt(input) {
             throw error;
         }
     }
+    const stageMemory = input.stage.memories?.length
+        ? process.env.SF_STAGE_WORKER === "1"
+            ? await workerMemoryForStage(input.stage.memories)
+            : await bindStageMemory(memoryHostFor(), input.stage.memories)
+        : undefined;
     const opened = await openStageWithOperatorCatalog(input.agent, {
         roots,
         stage: input.stage,
@@ -481,6 +492,9 @@ export async function openStageAttempt(input) {
             channels: process.env.SF_STAGE_WORKER === "1" ? workerStageChannels()
                 : stageChannels(channelHostFor(input.factoryCwd ?? process.cwd()), input.stage, input.runId),
         } : {}),
+        ...(stageMemory
+            ? { memory: stageMemory, memoryPrompt: await memoryPrompt(stageMemory) }
+            : {}),
         ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
         onActivity: (event) => {
             input.onActivity?.(input.stage.browser !== undefined

package/dist/runtime/stageEnvironment.d.ts

@@ -2,6 +2,7 @@ export declare const STAGE_ENV_PASSTHROUGH = "STAGEFLOW_STAGE_ENV_PASSTHROUGH";
 export declare const STAGE_ENV_ALLOW = "STAGEFLOW_STAGE_ENV_ALLOW";
 /** Names copied from Host when present (exact-name allowlist; no prefix wildcards). */
 export declare const STAGE_ENV_ALLOWLIST: readonly string[];
+export declare const PROVIDER_AND_CLOUD_NAMES: readonly ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENAI_API_KEY_FILE", "GOOGLE_API_KEY", "GEMINI_API_KEY", "GROQ_API_KEY", "MISTRAL_API_KEY", "DEEPSEEK_API_KEY", "TOGETHER_API_KEY", "FIREWORKS_API_KEY", "PERPLEXITY_API_KEY", "XAI_API_KEY", "COHERE_API_KEY", "OPENROUTER_API_KEY", "AZURE_OPENAI_API_KEY", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_SECURITY_TOKEN", "AWS_PROFILE", "AWS_DEFAULT_REGION", "AWS_REGION", "GOOGLE_APPLICATION_CREDENTIALS", "GCLOUD_PROJECT", "AZURE_CLIENT_SECRET", "AZURE_TENANT_ID", "AZURE_CLIENT_ID", "NPM_TOKEN", "NODE_AUTH_TOKEN", "SSH_AUTH_SOCK", "SSH_AGENT_PID", "GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN_FILE", "GH_TOKEN_FILE"];
 /** Never grantable — even via secrets `as: env`. */
 export declare const FOREVER_DENIED_SECRET_NAMES: ReadonlySet<string>;
 /** Blocked from ambient / ALLOW / PASSTHROUGH; `as: env` grants may still inject. */
@@ -29,6 +30,7 @@ export type BuildStageEnvironmentResult = {
     passthroughActive: boolean;
 };
 export declare function isForeverDeniedSecret(name: string): boolean;
+export declare function isProviderOrCloudName(name: string): boolean;
 export declare function isAmbientBlockedEnv(name: string): boolean;
 /**
  * Construct the stage child environment. Exact-name allowlist only — never a

package/dist/runtime/stageEnvironment.js

@@ -26,8 +26,10 @@ export const STAGE_ENV_ALLOWLIST = [
     "no_proxy",
     "STAGEFLOW_HOME",
     "STAGEFLOW_CURSOR_EXTENSION",
+    "STAGEFLOW_STAGE_CONTAINER_IMAGE",
+    "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN",
 ];
-const PROVIDER_AND_CLOUD_NAMES = [
+export const PROVIDER_AND_CLOUD_NAMES = [
     "ANTHROPIC_API_KEY",
     "OPENAI_API_KEY",
     "OPENAI_API_KEY_FILE",
@@ -70,6 +72,8 @@ export const FOREVER_DENIED_SECRET_NAMES = new Set([
     "STAGEFLOW_CONTROL_TOKEN_FILE",
     "STAGEFLOW_READ_TOKEN",
     "STAGEFLOW_READ_TOKEN_FILE",
+    // Host-generated key for the MCP OAuth token store; never hand it to a stage or an MCP server.
+    "PI_MCP_ADAPTER_OAUTH_FILE_KEY",
 ]);
 /** Blocked from ambient / ALLOW / PASSTHROUGH; `as: env` grants may still inject. */
 export const AMBIENT_BLOCKED_ENV_NAMES = new Set([
@@ -94,6 +98,9 @@ export function isForeverDeniedSecret(name) {
         return true;
     return name.startsWith("STAGEFLOW_CONTROL_TOKEN_");
 }
+export function isProviderOrCloudName(name) {
+    return PROVIDER_AND_CLOUD_NAMES.includes(name);
+}
 export function isAmbientBlockedEnv(name) {
     return isForeverDeniedSecret(name) || AMBIENT_BLOCKED_ENV_NAMES.has(name);
 }

package/dist/runtime/stageProcessLauncher.js

@@ -15,6 +15,8 @@ import { SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 import { emailHostFor, emailWorkerEnvironment, stageEmail, validateStageEmailAccounts } from "../email/host.js";
 import { ChannelError } from "../channels/errors.js";
 import { channelFault, channelHostFor, channelsWorkerEnvironment, stageChannels, validateStageChannelConnections } from "../channels/host.js";
+import { MemoryError, memoryHostFor } from "../memory/host.js";
+import { isMemoryVerb, runMemoryRequest } from "../memory/access.js";
 import { EmailError } from "../email/port.js";
 import { overlayStageBindingEnv, } from "./stageRoots.js";
 function defaultStageCliEntry() {
@@ -443,6 +445,27 @@ export class StageProcessLauncher {
                     })();
                     return;
                 }
+                const memoryVerb = request?.type;
+                if (!settled && isMemoryVerb(memoryVerb)) {
+                    void (async () => {
+                        if (typeof request.requestId !== "string" || request.requestId.length > 100)
+                            return;
+                        let response;
+                        try {
+                            const stage = input.stage;
+                            if (!stage || settled)
+                                throw new MemoryError("MEMORY_NOT_ATTACHED");
+                            response = await runMemoryRequest(memoryHostFor(), stage.memories ?? [], memoryVerb, request.input);
+                        }
+                        catch (error) {
+                            const code = error instanceof MemoryError ? error.code : "MEMORY_UNREADABLE";
+                            response = { error: { code } };
+                        }
+                        if (child.connected && !settled)
+                            child.send({ type: "memory.response", requestId: request.requestId, ...response });
+                    })();
+                    return;
+                }
                 if (!settled && request?.type === "channel.send") {
                     void (async () => {
                         if (typeof request.requestId !== "string" || request.requestId.length > 100)

package/dist/runtime/stageRoots.d.ts

@@ -11,6 +11,14 @@ export type StageRoots = {
     attempt?: number;
     /** Durable Pi auth.json path for ModelRuntime.create({ authPath }). */
     authPath?: string;
+    /**
+     * Sandbox container `stageWorker.ts` started for this attempt, if any.
+     * When set, read/write/edit/bash run inside that container's /workspace
+     * desk. Undefined leaves those tools on the host.
+     */
+    containerName?: string;
+    /** The docker binary the container above was started with (see STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN). */
+    containerDockerBin?: string;
 };
 export declare const STAGEFLOW_CHECKOUT = "STAGEFLOW_CHECKOUT";
 export declare const STAGEFLOW_RUN_WORKSPACE = "STAGEFLOW_RUN_WORKSPACE";
@@ -51,6 +59,7 @@ export declare function stageBindingEnvFromRun(options: {
 };
 export declare function withResolvedAuthPath(roots: StageRoots, factoryCwd: string): StageRoots;
 export declare function rootsForStageWorker(runWorkspaceDir: string, stageId: string, model: string, checkoutRoot?: string, attemptCtx?: StageAttemptContext): StageRoots;
+export declare function withContainerName(roots: StageRoots, containerName: string | undefined, containerDockerBin?: string): StageRoots;
 export declare function bindPiAgentDirEnv(agentDirPath: string): () => void;
 export declare function resolveCheckoutPath(declared: string, cwd: string): string;
 export declare function resolveAndValidateCheckout(task: TaskFile, override: string | undefined, factoryCwd: string): Promise<string | undefined>;

package/dist/runtime/stageRoots.js

@@ -4,6 +4,7 @@ import { isCursorModelRef } from "../agent/cursorProvider.js";
 import { stageDir } from "../runstore/paths.js";
 import { noAttemptContext } from "./stageAttemptContext.js";
 import { resolveCredentialBinding, STAGEFLOW_AGENT_AUTH_PATH_ENV, currentExplicitAuthPath, } from "./credentialBinding.js";
+import { ensureWorktreeCheckout } from "./gitWorktreeCheckout.js";
 import { SF_STAGE_WORKER } from "./stageWorkerProtocol.js";
 export const STAGEFLOW_CHECKOUT = "STAGEFLOW_CHECKOUT";
 export const STAGEFLOW_RUN_WORKSPACE = "STAGEFLOW_RUN_WORKSPACE";
@@ -151,6 +152,11 @@ export function rootsForStageWorker(runWorkspaceDir, stageId, model, checkoutRoo
         cwd: stageDir(runWorkspaceDir, stageId),
     };
 }
+export function withContainerName(roots, containerName, containerDockerBin) {
+    return containerName === undefined
+        ? roots
+        : { ...roots, containerName, containerDockerBin };
+}
 export function bindPiAgentDirEnv(agentDirPath) {
     const prev = process.env[PI_CODING_AGENT_DIR_ENV];
     process.env[PI_CODING_AGENT_DIR_ENV] = agentDirPath;
@@ -170,6 +176,14 @@ export async function resolveAndValidateCheckout(task, override, factoryCwd) {
     const raw = override ?? task.checkout;
     if (raw === undefined)
         return undefined;
+    if (typeof raw !== "string") {
+        return ensureWorktreeCheckout({
+            projectRoot: factoryCwd,
+            branch: raw.branch,
+            base: raw.base,
+            taskId: task.id,
+        });
+    }
     if (raw.trim() === "") {
         throw new Error("Invalid checkout: path is empty or whitespace-only");
     }

package/dist/runtime/stageRunner.d.ts

@@ -53,6 +53,11 @@ export type RunStageOptions = {
     stageEnv?: Record<string, string>;
     /** Test seam for the Host login check run by a `browser_login` verify item. */
     browser?: Pick<StageBrowserSupport, "runner" | "loginCheck">;
+    /**
+     * Runs after the agent turn and before completion verification records a
+     * verdict. Used to copy a sandbox desk back onto the host tree.
+     */
+    beforeVerify?: () => Promise<void>;
 };
 /**
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).

package/dist/runtime/stageRunner.js

@@ -47,6 +47,17 @@ async function appendLifecycleEventAndPatchExecution(options) {
         // no execution row yet
     }
 }
+async function runBeforeVerify(beforeVerify) {
+    if (beforeVerify === undefined)
+        return undefined;
+    try {
+        await beforeVerify();
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 async function finalizeStageResult(options) {
     const { store, runId, stageId, result, activityChain, attemptCtx, browser } = options;
     const attemptOpt = attemptCtx?.eventOptions();
@@ -125,7 +136,7 @@ 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, sessionMode, feedbackLoopContext, resumeToken, stageEnv, browser: browserSeams, } = options;
+    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, stageEnv, browser: browserSeams, beforeVerify, } = options;
     const stageId = options.stageId ?? stage.id;
     const attemptOpt = attemptCtx?.eventOptions();
     const baseRoots = rootsOverride ??
@@ -242,20 +253,43 @@ export async function runStage(options) {
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
+        const synced = await runBeforeVerify(beforeVerify);
+        const fullReason = synced === undefined ? reason : `${reason}; ${synced}`;
         await activityChain;
         hitl?.clearLiveWait(runId, stageId);
         await appendLifecycleEventAndPatchExecution({
             store,
             runId,
             stageId,
-            event: { event: "failed", reason },
+            event: { event: "failed", reason: fullReason },
             attemptCtx,
         });
-        console.error(`Stage ${stageId} failed: ${reason}`);
+        console.error(`Stage ${stageId} failed: ${fullReason}`);
         await handle
             .close(isStageTimeoutReason(reason) ? { park: true } : undefined)
             .catch(() => undefined);
-        return { ok: false, reason };
+        return { ok: false, reason: fullReason };
+    }
+    const syncError = await runBeforeVerify(beforeVerify);
+    if (syncError !== undefined) {
+        const reason = syncError;
+        if (isRunStageWaiting(outcome)) {
+            await activityChain;
+            hitl?.clearLiveWait(runId, stageId);
+            await appendLifecycleEventAndPatchExecution({
+                store,
+                runId,
+                stageId,
+                event: { event: "failed", reason },
+                attemptCtx,
+            });
+            console.error(`Stage ${stageId} failed: ${reason}`);
+            await handle.close().catch(() => undefined);
+            return { ok: false, reason };
+        }
+        outcome = outcome.ok
+            ? { ok: false, reason }
+            : { ok: false, reason: `${outcome.reason}; ${reason}` };
     }
     if (isRunStageWaiting(outcome)) {
         await activityChain;

package/dist/runtime/stageSandbox.d.ts

@@ -0,0 +1,16 @@
+import { type StageRoots } from "./stageRoots.js";
+export type StageSandbox = {
+    roots: StageRoots;
+    beforeVerify?: () => Promise<void>;
+    close: () => Promise<void>;
+    failure?: string;
+};
+export declare function openStageSandbox(input: {
+    env: NodeJS.ProcessEnv;
+    roots: StageRoots;
+    runId: string;
+    stageId: string;
+    attempt: number;
+    attemptDir: string;
+    checkoutRoot?: string;
+}): Promise<StageSandbox>;

package/dist/runtime/stageSandbox.js

@@ -0,0 +1,54 @@
+import { resolveSandboxContainerOptions, startSandboxContainer, stopSandboxContainer, } from "./sandboxContainer.js";
+import { buildSandboxDesk, populateSandboxDesk, syncSandboxDesk, } from "./sandboxDesk.js";
+import { withContainerName } from "./stageRoots.js";
+export async function openStageSandbox(input) {
+    const options = resolveSandboxContainerOptions(input.env);
+    if (!options) {
+        return { roots: input.roots, close: async () => { } };
+    }
+    const started = await startSandboxContainer({
+        image: options.image,
+        dockerBin: options.dockerBin,
+        runId: input.runId,
+        stageId: input.stageId,
+        attempt: input.attempt,
+    });
+    const roots = withContainerName(input.roots, started.containerName, options.dockerBin);
+    const checkout = input.checkoutRoot?.trim();
+    const desk = buildSandboxDesk({
+        attemptDir: input.attemptDir,
+        ...(checkout ? { checkoutRoot: checkout } : {}),
+    });
+    const session = {
+        roots,
+        close: () => stopSandboxContainer({
+            containerName: started.containerName,
+            dockerBin: options.dockerBin,
+        }).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[stageWorker] failed to stop sandbox container ${started.containerName}: ${message}\n`);
+        }),
+    };
+    try {
+        await populateSandboxDesk({
+            containerName: started.containerName,
+            dockerBin: options.dockerBin,
+            desk,
+        });
+    }
+    catch (err) {
+        session.failure = err instanceof Error ? err.message : String(err);
+        return session;
+    }
+    session.beforeVerify = syncOnce(started.containerName, options.dockerBin, desk);
+    return session;
+}
+function syncOnce(containerName, dockerBin, desk) {
+    let synced = false;
+    return async () => {
+        if (synced)
+            return;
+        synced = true;
+        await syncSandboxDesk({ containerName, dockerBin, desk });
+    };
+}

package/dist/runtime/stageSecrets.d.ts

@@ -9,6 +9,11 @@ export type SecretRegistryEntry = {
     name: string;
     source: string;
     pointerVar: string;
+}
+/** A secret saved from the console (Settings → Project MCP). It only fills `${NAME}` in MCP servers; never the stage environment. */
+ | {
+    kind: "console";
+    name: string;
 };
 export type SecretRegistry = Map<string, SecretRegistryEntry>;
 export declare class SecretUnavailableError extends Error {
@@ -35,6 +40,6 @@ export type ResolveStageSecretsResult = {
     credentialDirs: string[];
 };
 /** Presence-only check (no materialisation) for preflight / start gates. */
-export declare function assertSecretPresent(name: string, registry: SecretRegistry, hostEnv: NodeJS.ProcessEnv): void;
+export declare function assertSecretPresent(name: string, registry: SecretRegistry, hostEnv: NodeJS.ProcessEnv, home?: string): void;
 export declare function resolveStageSecrets(input: ResolveStageSecretsInput): ResolveStageSecretsResult;
 export { cleanupCredentialsDir };

package/dist/runtime/stageSecrets.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { shouldRegisterValue } from "../logging/redact.js";
+import { readMcpSecrets } from "../config/mcpHostCatalog.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { attemptCredentialsDir, cleanupCredentialsDir, ensureStageAskpassHelper, materialiseCredentialFile, materialiseSecretBytes, readFileCredentialRegistry, } from "./credentialMaterialisation.js";
 import { defaultSecretDelivery, } from "./stageSecretDecl.js";
@@ -66,10 +67,20 @@ export function loadSecretRegistry(env = process.env, home = globalStageflowHome
             continue;
         registry.set(name, { kind: "env", name });
     }
+    // Console-stored MCP secrets: a stage may declare them so its `mcp:` servers can be filled.
+    try {
+        for (const name of Object.keys(readMcpSecrets(home))) {
+            if (!isForeverDeniedSecret(name) && !registry.has(name))
+                registry.set(name, { kind: "console", name });
+        }
+    }
+    catch {
+        // A corrupt host-state file is reported by the MCP routes; it must not stop other stages.
+    }
     return registry;
 }
 /** Presence-only check (no materialisation) for preflight / start gates. */
-export function assertSecretPresent(name, registry, hostEnv) {
+export function assertSecretPresent(name, registry, hostEnv, home) {
     if (isForeverDeniedSecret(name)) {
         throw new Error(`secret "${name}" is permanently denied`);
     }
@@ -86,11 +97,24 @@ export function assertSecretPresent(name, registry, hostEnv) {
         }
         return;
     }
+    if (entry.kind === "console") {
+        if (!readMcpSecretValue(name, home))
+            throw new SecretUnavailableError(name);
+        return;
+    }
     const value = readEnvSecretValue(name, hostEnv);
     if (value === undefined || value === "") {
         throw new SecretUnavailableError(name);
     }
 }
+function readMcpSecretValue(name, home) {
+    try {
+        return readMcpSecrets(home)[name];
+    }
+    catch {
+        return undefined;
+    }
+}
 function materialiseGitAskpassGrant(grantEnv, credentialDirs, opts) {
     const destDir = attemptCredentialsDir(opts.attemptDir, opts.secretName);
     const tokenFile = materialiseSecretBytes({
@@ -119,6 +143,15 @@ export function resolveStageSecrets(input) {
         if (entry === undefined) {
             throw new Error(`stage.unknown_secret: "${decl.name}"`);
         }
+        if (entry.kind === "console") {
+            const stored = readMcpSecretValue(decl.name, input.home);
+            if (!stored)
+                throw new SecretUnavailableError(decl.name);
+            if (shouldRegisterValue(stored))
+                knownValues.push({ name: decl.name, value: stored });
+            warnings.push(`secrets: ${decl.name} is a console secret; it fills MCP servers only and is not set in the stage environment`);
+            continue;
+        }
         if (entry.kind === "file") {
             const destDir = attemptCredentialsDir(input.attemptDir, decl.name);
             const homeRoot = input.home ?? globalStageflowHome();