spawnfile 0.1.13 → 0.1.17

package/dist/compiler/runProjectAuth.js

@@ -1,25 +1,60 @@
+import os from "node:os";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { parseEnvFile } from "../auth/index.js";
 import { fileExists, readUtf8File } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
 import { getRuntimeAdapter } from "../runtime/index.js";
+import { CLI_CREDENTIAL_SECRET_NAME, modelAuthMethodNeedsCliCredential } from "./modelEnv.js";
 const MODEL_AUTH_IMPORT_KINDS = {
     api_key: null,
     "claude-code": "claude-code",
     codex: "codex",
+    grok: null,
     none: null
 };
+export const resolveHostCliCredential = async (containerReport) => {
+    const needsCredential = containerReport.runtime_instances.some((instance) => Object.values(instance.model_auth_methods).some(modelAuthMethodNeedsCliCredential));
+    if (!needsCredential) {
+        return null;
+    }
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    const sourcePath = path.join(codexHome, "auth.json");
+    if (!await fileExists(sourcePath)) {
+        throw new SpawnfileError("validation_error", `Missing ${CLI_CREDENTIAL_SECRET_NAME}; host CLI credential source does not exist: ${sourcePath}`);
+    }
+    let value;
+    try {
+        value = await readUtf8File(sourcePath);
+    }
+    catch (error) {
+        throw new SpawnfileError("validation_error", `Unable to read ${CLI_CREDENTIAL_SECRET_NAME} from host CLI credential source ${sourcePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (value.trim().length === 0) {
+        throw new SpawnfileError("validation_error", `Missing ${CLI_CREDENTIAL_SECRET_NAME}; host CLI credential source is empty: ${sourcePath}`);
+    }
+    try {
+        return { name: CLI_CREDENTIAL_SECRET_NAME, sourcePath, value: JSON.stringify(JSON.parse(value)) };
+    }
+    catch (error) {
+        throw new SpawnfileError("validation_error", `Unable to read ${CLI_CREDENTIAL_SECRET_NAME} from host CLI credential source ${sourcePath}: invalid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+};
 const addCoveredModelSecrets = (coveredModelSecrets, instanceId, secretNames) => {
     for (const secretName of secretNames) {
         coveredModelSecrets.add(`${instanceId}:${secretName}`);
     }
 };
-export const prepareRuntimeAuthMounts = async (outputDirectory, containerReport, authProfile, env, tempRoot) => {
-    if (!authProfile) {
-        return { coveredModelSecrets: new Set(), mountArgs: [] };
-    }
+export const prepareRuntimeAuthMounts = async (outputDirectory, containerReport, authProfile, env, tempRoot, containerCredentialUid) => {
+    // No early return when `authProfile` is null: an adapter's
+    // `prepareRuntimeAuth` may still have host-credential staging to do that
+    // does not depend on an imported Spawnfile auth profile (e.g. the Pi
+    // adapter mounting the host's `~/.grok`/`~/.codex`/antigravity CLI homes
+    // for a real-engine org — see `src/runtime/pi/runAuth.ts`). Each adapter is
+    // responsible for treating a `null` `authProfile` as "no profile-derived
+    // imports available" rather than failing.
     const coveredModelSecrets = new Set();
+    let launchIdentity;
     const mountArgs = [];
     for (const instance of containerReport.runtime_instances) {
         const adapter = getRuntimeAdapter(instance.runtime);
@@ -28,17 +63,28 @@ export const prepareRuntimeAuthMounts = async (outputDirectory, containerReport,
         }
         const prepared = await adapter.prepareRuntimeAuth({
             authProfile,
+            ...(containerCredentialUid === undefined ? {} : { containerCredentialUid }),
             env,
             instance,
             outputDirectory,
             tempRoot
         });
         addCoveredModelSecrets(coveredModelSecrets, instance.id, prepared.coveredModelSecrets);
+        if (prepared.launchIdentity) {
+            if (launchIdentity && launchIdentity.uid !== prepared.launchIdentity.uid) {
+                throw new SpawnfileError("validation_error", "Opaque runtime credentials resolve conflicting launch UIDs");
+            }
+            launchIdentity = prepared.launchIdentity;
+        }
         mountArgs.push(...prepared.mountArgs);
     }
-    return { coveredModelSecrets, mountArgs };
+    return {
+        coveredModelSecrets,
+        ...(launchIdentity ? { launchIdentity } : {}),
+        mountArgs
+    };
 };
-export const assertDeclaredModelAuthSatisfied = (containerReport, authProfile) => {
+export const assertDeclaredModelAuthSatisfied = (containerReport, authProfile, cliCredentialProvided = false) => {
     const requiredImportKinds = new Set();
     for (const instance of containerReport.runtime_instances) {
         for (const method of Object.values(instance.model_auth_methods)) {
@@ -51,9 +97,15 @@ export const assertDeclaredModelAuthSatisfied = (containerReport, authProfile) =
     if (requiredImportKinds.size === 0) {
         return;
     }
-    if (!authProfile) {
+    if (!authProfile && !cliCredentialProvided) {
         throw new SpawnfileError("validation_error", `Auth profile is required for declared model auth methods: ${[...requiredImportKinds].sort().join(", ")}`);
     }
+    if (cliCredentialProvided) {
+        return;
+    }
+    if (!authProfile) {
+        return;
+    }
     const missingImportKinds = [...requiredImportKinds]
         .filter((kind) => !authProfile.imports[kind])
         .sort();
@@ -62,10 +114,16 @@ export const assertDeclaredModelAuthSatisfied = (containerReport, authProfile) =
     }
 };
 const getImportMountTargetName = (kind) => kind === "claude-code" ? ".claude" : ".codex";
-const createGeneratedRuntimeSecret = (secretName) => {
+const createGeneratedRuntimeSecret = (secretName, generatedMoltnetSecrets) => {
     if (secretName === "OPENCLAW_GATEWAY_TOKEN" || secretName === "OPENCLAW_HOOKS_TOKEN") {
         return randomBytes(24).toString("hex");
     }
+    if (generatedMoltnetSecrets.has(secretName)) {
+        return randomBytes(32).toString("base64url");
+    }
+    if (secretName === "SPAWNFILE_DAIMON_CONTROL_TOKEN") {
+        return randomBytes(32).toString("base64url");
+    }
     return null;
 };
 const hasEnvValue = (env, name) => typeof env[name] === "string" && env[name].length > 0;
@@ -93,17 +151,23 @@ export const resolveRunEnvironment = (containerReport, authProfile, envFileEnv =
         ...(authProfile?.env ?? {}),
         ...envFileEnv
     };
+    const generatedMoltnetSecrets = new Set((containerReport.moltnet?.server_plans ?? [])
+        .filter((server) => server.mode === "managed" && server.auth_mode === "bearer")
+        .flatMap((server) => (server.auth_tokens ?? []).map((token) => token.secret)));
     for (const name of new Set([...Object.keys(env), ...containerReport.secrets_required])) {
         const processValue = process.env[name];
         if (typeof processValue === "string" && processValue.length > 0) {
             env[name] = processValue;
         }
     }
-    for (const name of containerReport.runtime_secrets_required) {
+    for (const name of new Set([
+        ...containerReport.runtime_secrets_required,
+        ...generatedMoltnetSecrets
+    ])) {
         if (hasEnvValue(env, name)) {
             continue;
         }
-        const generatedValue = createGeneratedRuntimeSecret(name);
+        const generatedValue = createGeneratedRuntimeSecret(name, generatedMoltnetSecrets);
         if (generatedValue) {
             env[name] = generatedValue;
         }
@@ -121,6 +185,27 @@ export const assertRunEnvironmentSatisfied = (containerReport, env, coveredModel
         throw new SpawnfileError("validation_error", `Missing required runtime env: ${missing.sort().join(", ")}`);
     }
 };
+export const assertMoltnetCredentialValuesDistinct = (containerReport, env) => {
+    for (const server of containerReport.moltnet?.server_plans ?? []) {
+        if (server.mode !== "managed" || server.auth_mode !== "bearer") {
+            continue;
+        }
+        const secretNames = (server.auth_tokens ?? []).map((token) => token.secret);
+        const normalizedValues = secretNames.map((name) => {
+            const value = env[name];
+            if (typeof value !== "string" || value.trim().length === 0) {
+                return null;
+            }
+            if (value !== value.trim()) {
+                throw new SpawnfileError("validation_error", `Moltnet credential ${name} must not contain leading or trailing whitespace`);
+            }
+            return value;
+        }).filter((value) => value !== null);
+        if (new Set(normalizedValues).size !== normalizedValues.length) {
+            throw new SpawnfileError("validation_error", `Moltnet network ${server.network_id} requires distinct credential values`);
+        }
+    }
+};
 export const renderDockerEnvFile = (env) => `${Object.entries(env)
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, value]) => `${name}=${value}`)
@@ -142,6 +227,15 @@ export const resolveAuthMountArgs = async (containerReport, authProfile) => {
         return [];
     }
     const args = [];
+    // Pi owns its model and CLI-engine auth projection in preparePiRuntimeAuth.
+    // Mounting the generic imported home onto the same destination would create
+    // duplicate Docker mount points and bypass the adapter's minimal-file staging.
+    const piRuntimeHomes = new Set(containerReport.runtime_instances
+        .filter((instance) => instance.runtime === "pi")
+        .map((instance) => instance.home_path)
+        .filter((homePath) => homePath !== null));
+    const genericRuntimeHomes = containerReport.runtime_homes
+        .filter((runtimeHome) => !piRuntimeHomes.has(runtimeHome));
     for (const [kind, entry] of Object.entries(authProfile.imports)) {
         if (!entry) {
             continue;
@@ -149,7 +243,7 @@ export const resolveAuthMountArgs = async (containerReport, authProfile) => {
         if (!(await fileExists(entry.path))) {
             throw new SpawnfileError("validation_error", `Imported auth path for ${kind} does not exist: ${entry.path}`);
         }
-        for (const runtimeHome of containerReport.runtime_homes) {
+        for (const runtimeHome of genericRuntimeHomes) {
             args.push("-v", `${entry.path}:${path.posix.join(runtimeHome, getImportMountTargetName(kind))}`);
         }
     }

package/dist/compiler/runProjectDaimonCodexDocker.d.ts

@@ -0,0 +1,3 @@
+import type { CompileProjectResult } from "./compileProject.js";
+export { DAIMON_CODEX_NATIVE_SANDBOX_DOCKER_SECURITY_OPTS } from "../shared/index.js";
+export declare const resolveDaimonCodexNativeSandboxDockerSecurityOptions: (compileResult: CompileProjectResult) => Promise<string[]>;

package/dist/compiler/runProjectDaimonCodexDocker.js

@@ -0,0 +1,36 @@
+import path from "node:path";
+import { readUtf8File } from "../filesystem/index.js";
+import { daimonEngineDockerSecurityArgsForConfigs, materializeDaimonGrokSeccompProfile, SpawnfileError } from "../shared/index.js";
+export { DAIMON_CODEX_NATIVE_SANDBOX_DOCKER_SECURITY_OPTS } from "../shared/index.js";
+const assertContainedPath = (root, candidate) => {
+    const normalizedRoot = path.resolve(root);
+    const normalizedCandidate = path.resolve(candidate);
+    const relative = path.relative(normalizedRoot, normalizedCandidate);
+    if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new SpawnfileError("validation_error", "Daimon generated config path escapes the compiled container rootfs");
+    }
+    return normalizedCandidate;
+};
+const configPathInOutput = (outputDirectory, instance) => {
+    if (!instance.config_path.startsWith("/")) {
+        throw new SpawnfileError("validation_error", "Daimon runtime instance has a non-absolute generated config path");
+    }
+    const rootfs = path.join(outputDirectory, "container", "rootfs");
+    return assertContainedPath(rootfs, path.join(rootfs, `.${instance.config_path}`));
+};
+export const resolveDaimonCodexNativeSandboxDockerSecurityOptions = async (compileResult) => {
+    const instances = compileResult.report.container?.runtime_instances
+        .filter((instance) => instance.runtime === "daimon") ?? [];
+    const sources = [];
+    for (const instance of instances) {
+        try {
+            sources.push(await readUtf8File(configPathInOutput(compileResult.outputDirectory, instance)));
+        }
+        catch (error) {
+            if (error instanceof SpawnfileError)
+                throw error;
+            throw new SpawnfileError("validation_error", "Could not read Daimon's generated organization config before Docker launch");
+        }
+    }
+    return daimonEngineDockerSecurityArgsForConfigs(sources, () => materializeDaimonGrokSeccompProfile(path.join(compileResult.outputDirectory, "container", "security")));
+};

package/dist/compiler/runProjectDocker.d.ts

@@ -5,15 +5,26 @@ export interface DockerRunInvocation {
     cwd: string;
     detach: boolean;
     deploymentName?: string | null;
+    deploymentLabels?: Readonly<Record<string, string>>;
     dockerContext?: string | null;
     dockerHost?: string | null;
     envFilePath: string;
+    /** Host-stable credential realms that must have at most one live deployment. */
+    exclusiveReattachVolumes?: readonly string[];
     imageTag: string;
+    onDetachedStarted?: (result: DockerRunResult) => Promise<void>;
+    /** Ephemeral guard; never serialized into reports, records, or labels. */
+    opaqueDaimonCredentials?: boolean;
     supportDirectory: string;
 }
 export interface DockerRunResult {
     containerId?: string;
+    containerName?: string;
+    deploymentLabels?: Readonly<Record<string, string>>;
     imageId?: string;
 }
 export type DockerRunRunner = (invocation: DockerRunInvocation) => Promise<DockerRunResult | void>;
+export declare const createDetachedContainerInspectArgs: (invocation: DockerRunInvocation, containerId: string) => string[];
+export declare const parseDetachedContainerInspect: (stdout: string, expectedContainerId: string, expectedLabels?: Readonly<Record<string, string>>, expectedContainerName?: string | null) => DockerRunResult;
+export declare const inspectDetachedContainer: (invocation: DockerRunInvocation, containerId: string) => Promise<DockerRunResult>;
 export declare const runDockerContainer: DockerRunRunner;

package/dist/compiler/runProjectDocker.js

@@ -2,6 +2,8 @@ import { execFile as execFileCallback, spawn } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
 import { SpawnfileError } from "../shared/index.js";
+import { assertOpaqueDaimonCredentialsHaveNoUserNamespace, pinOpaqueDaimonDockerEndpoint } from "./runProjectDockerDaimonGuards.js";
+import { withExclusiveVolumeReservations } from "./runProjectDockerReservation.js";
 const execFile = promisify(execFileCallback);
 const parseDockerContextHost = (stdout) => {
     const trimmed = stdout.trim();
@@ -132,25 +134,49 @@ const prepareRemoteBindMounts = async (invocation) => {
         }
     };
 };
-const inspectImageArgs = (invocation, containerId) => {
+export const createDetachedContainerInspectArgs = (invocation, containerId) => {
     const base = invocation.dockerContext
         ? ["--context", invocation.dockerContext, "inspect"]
         : invocation.dockerHost
             ? ["--host", invocation.dockerHost, "inspect"]
             : ["inspect"];
-    return [...base, "--format", "{{.Image}}", containerId];
+    return [...base, "--format", "{{json .Id}}\n{{json .Name}}\n{{json .Image}}\n{{json .Config.Labels}}", containerId];
 };
-const inspectDetachedImageId = async (invocation, containerId) => {
+export const parseDetachedContainerInspect = (stdout, expectedContainerId, expectedLabels, expectedContainerName) => {
+    const [idRaw, nameRaw, imageRaw, labelsRaw, ...extra] = stdout.trim().split("\n");
+    if (!idRaw || !nameRaw || !imageRaw || !labelsRaw || extra.length > 0)
+        throw new Error("unexpected inspect response");
+    const actualId = JSON.parse(idRaw);
+    const actualName = JSON.parse(nameRaw);
+    const imageId = JSON.parse(imageRaw);
+    const labels = JSON.parse(labelsRaw);
+    if (typeof actualId !== "string" || actualId !== expectedContainerId || !/^[a-f0-9]{64}$/u.test(actualId)
+        || typeof actualName !== "string" || actualName !== `/${expectedContainerName ?? ""}`
+        || typeof imageId !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(imageId))
+        throw new Error("malformed detached container metadata");
+    if (!expectedLabels)
+        return { containerId: actualId, containerName: actualName.slice(1), imageId };
+    if (!labels || typeof labels !== "object" || Array.isArray(labels))
+        throw new Error("missing detached deployment labels");
+    const actual = Object.fromEntries(Object.keys(expectedLabels).sort().map((key) => {
+        const value = labels[key];
+        if (typeof value !== "string" || value !== expectedLabels[key])
+            throw new Error("detached deployment label drift");
+        return [key, value];
+    }));
+    return { containerId: actualId, containerName: actualName.slice(1), imageId, deploymentLabels: actual };
+};
+export const inspectDetachedContainer = async (invocation, containerId) => {
     try {
-        const { stdout } = await execFile(invocation.command, inspectImageArgs(invocation, containerId), {
+        const { stdout } = await execFile(invocation.command, createDetachedContainerInspectArgs(invocation, containerId), {
             cwd: invocation.cwd,
             timeout: 10_000
         });
-        return stdout.trim() || undefined;
+        return parseDetachedContainerInspect(stdout, containerId, invocation.deploymentLabels, invocation.containerName);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        throw new SpawnfileError("runtime_error", `Unable to inspect detached container ${containerId} image id: ${message}`);
+        throw new SpawnfileError("runtime_error", `Unable to inspect detached container ${containerId}: ${message}`);
     }
 };
 const runPreparedDockerContainer = (prepared) => new Promise((resolve, reject) => {
@@ -181,8 +207,12 @@ const runPreparedDockerContainer = (prepared) => new Promise((resolve, reject) =
                 settle(() => resolve(undefined));
                 return;
             }
-            inspectDetachedImageId(prepared.invocation, containerId)
-                .then((imageId) => resolve({ containerId, ...(imageId ? { imageId } : {}) }))
+            Promise.resolve(inspectDetachedContainer(prepared.invocation, containerId))
+                .then(async (result) => {
+                await prepared.invocation.onDetachedStarted?.(result);
+                return result;
+            })
+                .then(resolve)
                 .catch(reject);
             return;
         }
@@ -191,12 +221,30 @@ const runPreparedDockerContainer = (prepared) => new Promise((resolve, reject) =
             : `Docker run for ${prepared.invocation.imageTag} failed with exit code ${code ?? "unknown"}`));
     });
 });
-export const runDockerContainer = (invocation) => {
-    if (!invocation.dockerContext || collectBindMountSources(invocation.args).length === 0) {
-        return runPreparedDockerContainer({
-            cleanup: async () => undefined,
-            invocation
-        });
-    }
-    return prepareRemoteBindMounts(invocation).then(runPreparedDockerContainer);
+const runDockerContainerPrepared = async (invocation) => {
+    const run = async () => {
+        if (!invocation.dockerContext || collectBindMountSources(invocation.args).length === 0) {
+            if (invocation.opaqueDaimonCredentials && !invocation.dockerEndpointPinned) {
+                await assertOpaqueDaimonCredentialsHaveNoUserNamespace(invocation);
+                return await runPreparedDockerContainer({
+                    cleanup: async () => undefined,
+                    invocation
+                });
+            }
+            return await runPreparedDockerContainer({
+                cleanup: async () => undefined,
+                invocation
+            });
+        }
+        return await runPreparedDockerContainer(await prepareRemoteBindMounts(invocation));
+    };
+    return withExclusiveVolumeReservations(invocation, run);
 };
+export const runDockerContainer = (invocation) => invocation.opaqueDaimonCredentials
+    ? pinOpaqueDaimonDockerEndpoint(invocation)
+        .then(async (pinned) => {
+        await assertOpaqueDaimonCredentialsHaveNoUserNamespace(pinned);
+        return pinned;
+    })
+        .then((pinned) => runDockerContainerPrepared({ ...pinned, dockerEndpointPinned: true }))
+    : runDockerContainerPrepared(invocation);

package/dist/compiler/runProjectDockerDaimonGuards.d.ts

@@ -0,0 +1,15 @@
+export interface DaimonDockerGuardInvocation {
+    args: string[];
+    command: string;
+    cwd: string;
+    dockerContext?: string | null;
+    dockerHost?: string | null;
+    opaqueDaimonCredentials?: boolean;
+}
+/**
+ * Resolves a possibly mutable Docker context once, validates that endpoint,
+ * then makes every remaining Docker operation use the immutable endpoint.
+ */
+export declare const pinOpaqueDaimonDockerEndpoint: <T extends DaimonDockerGuardInvocation>(invocation: T) => Promise<T>;
+export declare const assertOpaqueDaimonCredentialsUseLocalDaemon: (invocation: DaimonDockerGuardInvocation) => Promise<void>;
+export declare const assertOpaqueDaimonCredentialsHaveNoUserNamespace: (invocation: DaimonDockerGuardInvocation) => Promise<void>;

package/dist/compiler/runProjectDockerDaimonGuards.js

@@ -0,0 +1,122 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const parseDockerContextHost = (stdout) => {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return typeof parsed === "string" ? parsed : null;
+    }
+    catch {
+        return trimmed;
+    }
+};
+const resolveDockerContextHost = async (invocation, context) => {
+    const { stdout } = await execFile(invocation.command, [
+        "context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}"
+    ], { cwd: invocation.cwd, timeout: 10_000 });
+    return parseDockerContextHost(stdout);
+};
+const resolveActiveDockerContext = async (invocation) => {
+    const { stdout } = await execFile(invocation.command, ["context", "show"], {
+        cwd: invocation.cwd,
+        timeout: 10_000
+    });
+    const context = stdout.trim();
+    if (!context || /\s/u.test(context)) {
+        throw new SpawnfileError("validation_error", "Unable to attest the active Docker context for opaque Daimon credentials");
+    }
+    return context;
+};
+const resolveDockerDaemonEndpoint = async (invocation) => {
+    if (invocation.dockerContext)
+        return resolveDockerContextHost(invocation, invocation.dockerContext);
+    if (invocation.dockerHost)
+        return invocation.dockerHost;
+    const ambientContext = process.env.DOCKER_CONTEXT?.trim();
+    if (ambientContext)
+        return resolveDockerContextHost(invocation, ambientContext);
+    const ambientHost = process.env.DOCKER_HOST?.trim();
+    if (ambientHost)
+        return ambientHost;
+    return resolveDockerContextHost(invocation, await resolveActiveDockerContext(invocation));
+};
+const isLocalDockerEndpoint = (host) => {
+    if (host.startsWith("/"))
+        return true;
+    if (host.startsWith("unix://")) {
+        try {
+            const endpoint = new URL(host);
+            return endpoint.host === "" && endpoint.pathname.startsWith("/");
+        }
+        catch {
+            return false;
+        }
+    }
+    return host.startsWith("npipe:////./pipe/") || host.startsWith("npipe://./pipe/");
+};
+const explicitLocalEndpoint = (endpoint) => endpoint.startsWith("/") ? `unix://${endpoint}` : endpoint;
+const withPinnedDockerEndpoint = (invocation, endpoint) => {
+    const run = invocation.args.indexOf("run");
+    if (run < 0) {
+        throw new SpawnfileError("validation_error", "Unable to pin Docker daemon endpoint for opaque Daimon credentials");
+    }
+    return {
+        ...invocation,
+        args: ["--host", endpoint, ...invocation.args.slice(run)],
+        dockerContext: null,
+        dockerHost: endpoint
+    };
+};
+/**
+ * Resolves a possibly mutable Docker context once, validates that endpoint,
+ * then makes every remaining Docker operation use the immutable endpoint.
+ */
+export const pinOpaqueDaimonDockerEndpoint = async (invocation) => {
+    if (!invocation.opaqueDaimonCredentials)
+        return invocation;
+    let resolved;
+    try {
+        resolved = await resolveDockerDaemonEndpoint(invocation);
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        throw new SpawnfileError("validation_error", "Unable to attest the Docker daemon locality for opaque Daimon credentials");
+    }
+    if (!resolved || !isLocalDockerEndpoint(resolved)) {
+        throw new SpawnfileError("validation_error", "Opaque Daimon credentials require a local Docker daemon; remote and SSH daemons are unsupported");
+    }
+    return withPinnedDockerEndpoint(invocation, explicitLocalEndpoint(resolved));
+};
+export const assertOpaqueDaimonCredentialsUseLocalDaemon = async (invocation) => {
+    await pinOpaqueDaimonDockerEndpoint(invocation);
+};
+export const assertOpaqueDaimonCredentialsHaveNoUserNamespace = async (invocation) => {
+    if (!invocation.opaqueDaimonCredentials)
+        return;
+    if (invocation.dockerContext || !invocation.dockerHost) {
+        throw new SpawnfileError("validation_error", "Opaque Daimon credentials require a pinned Docker daemon endpoint before Docker info");
+    }
+    const args = [
+        "--host", invocation.dockerHost,
+        "info", "--format", "{{json .SecurityOptions}}"
+    ];
+    let securityOptions;
+    try {
+        const { stdout } = await execFile(invocation.command, args, {
+            cwd: invocation.cwd,
+            timeout: 10_000
+        });
+        securityOptions = JSON.parse(stdout.trim());
+    }
+    catch {
+        throw new SpawnfileError("validation_error", "Unable to verify that the Docker daemon has no user namespace remapping for opaque Daimon credentials");
+    }
+    if (!Array.isArray(securityOptions) || securityOptions.some((value) => typeof value !== "string" || /userns|rootless/iu.test(value))) {
+        throw new SpawnfileError("validation_error", "Opaque Daimon credentials require a Docker daemon without user namespace remapping");
+    }
+};

package/dist/compiler/runProjectDockerReservation.d.ts

@@ -0,0 +1,3 @@
+import type { DockerRunInvocation, DockerRunResult } from "./runProjectDocker.js";
+/** Holds daemon-side atomic volume reservations through verified startup. */
+export declare const withExclusiveVolumeReservations: (invocation: DockerRunInvocation, operation: () => Promise<DockerRunResult | void>) => Promise<DockerRunResult | void>;

package/dist/compiler/runProjectDockerReservation.js

@@ -0,0 +1,118 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const dockerId = /^[a-f0-9]{64}$/u;
+const versionLabel = "com.spawnfile.exclusive-volume-reservation";
+const ownerLabel = "com.spawnfile.exclusive-volume-owner";
+const volumeLabel = "com.spawnfile.exclusive-volume-digest";
+const endpointArgs = (invocation) => invocation.dockerContext
+    ? ["--context", invocation.dockerContext]
+    : invocation.dockerHost ? ["--host", invocation.dockerHost] : [];
+const execute = async (invocation, args) => {
+    const { stdout } = await execFile(invocation.command, [...endpointArgs(invocation), ...args], {
+        cwd: invocation.cwd,
+        timeout: 10_000
+    });
+    return stdout;
+};
+const reservationName = (digest) => `spawnfile-volume-reservation-${digest.slice("sha256:".length, "sha256:".length + 24)}`;
+const verifyReservation = async (invocation, reservation) => {
+    try {
+        const [idRaw, labelsRaw, ...extra] = (await execute(invocation, [
+            "container", "inspect", "--format", "{{json .Id}}\n{{json .Config.Labels}}", reservation.id
+        ])).trim().split("\n");
+        if (!idRaw || !labelsRaw || extra.length > 0)
+            throw new Error("shape");
+        const id = JSON.parse(idRaw);
+        const labels = JSON.parse(labelsRaw);
+        if (id !== reservation.id || !labels || typeof labels !== "object" || Array.isArray(labels))
+            throw new Error("identity");
+        const values = labels;
+        if (values[versionLabel] !== "v1" || values[ownerLabel] !== reservation.owner
+            || values[volumeLabel] !== reservation.volumeDigest)
+            throw new Error("authority");
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation identity is unavailable");
+    }
+};
+const release = async (invocation, reservations) => {
+    let failed = false;
+    for (const reservation of [...reservations].reverse()) {
+        try {
+            await verifyReservation(invocation, reservation);
+            await execute(invocation, ["container", "rm", reservation.id]);
+        }
+        catch {
+            failed = true;
+        }
+    }
+    if (failed)
+        throw new SpawnfileError("runtime_error", "Unable to release exclusive persistent mount reservation");
+};
+const assertAvailable = async (invocation) => {
+    for (const volume of invocation.exclusiveReattachVolumes ?? []) {
+        let stdout;
+        try {
+            stdout = await execute(invocation, [
+                "ps", "--filter", `volume=${volume}`, "--format", "{{.Names}}"
+            ]);
+        }
+        catch {
+            throw new SpawnfileError("runtime_error", "Unable to verify exclusive persistent mount occupancy");
+        }
+        const occupants = stdout.split("\n").map((name) => name.trim()).filter(Boolean);
+        if (occupants.some((name) => name !== invocation.containerName)) {
+            throw new SpawnfileError("runtime_error", "Exclusive persistent mount is attached to another running deployment; stop it before reattaching this lineage");
+        }
+    }
+};
+const acquire = async (invocation) => {
+    const reservations = [];
+    const volumes = [...new Set(invocation.exclusiveReattachVolumes ?? [])].sort();
+    try {
+        for (const volume of volumes) {
+            const volumeDigest = `sha256:${createHash("sha256").update(volume).digest("hex")}`;
+            const owner = randomUUID();
+            let id;
+            try {
+                id = (await execute(invocation, [
+                    "container", "create", "--name", reservationName(volumeDigest),
+                    "--label", `${versionLabel}=v1`,
+                    "--label", `${ownerLabel}=${owner}`,
+                    "--label", `${volumeLabel}=${volumeDigest}`,
+                    invocation.imageTag
+                ])).trim();
+            }
+            catch {
+                throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation is already held");
+            }
+            if (!dockerId.test(id))
+                throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation returned invalid identity");
+            const reservation = { id, owner, volumeDigest };
+            reservations.push(reservation);
+            await verifyReservation(invocation, reservation);
+        }
+        await assertAvailable(invocation);
+        return reservations;
+    }
+    catch (error) {
+        if (reservations.length > 0)
+            await release(invocation, reservations);
+        throw error;
+    }
+};
+/** Holds daemon-side atomic volume reservations through verified startup. */
+export const withExclusiveVolumeReservations = async (invocation, operation) => {
+    if ((invocation.exclusiveReattachVolumes?.length ?? 0) === 0)
+        return operation();
+    const reservations = await acquire(invocation);
+    try {
+        return await operation();
+    }
+    finally {
+        await release(invocation, reservations);
+    }
+};