spawnfile 0.1.14 → 0.1.17

package/dist/distribution/consumeImageLifecycle.d.ts

@@ -0,0 +1,17 @@
+import type { DockerCommandRunner } from "./dockerRunner.js";
+import type { DistributionReport } from "./types.js";
+export interface ContainerSnapshot {
+    readonly id: string;
+    readonly name: string;
+    readonly running: boolean;
+}
+export interface ExclusiveVolumeReservation {
+    release(): Promise<void>;
+}
+export declare const inspectContainerSnapshot: (runDocker: DockerCommandRunner, reference: string) => Promise<ContainerSnapshot | null>;
+export declare const assertExclusiveVolumesAvailable: (report: DistributionReport, deploymentLineage: string, deploymentContainerName: string, runDocker: DockerCommandRunner) => Promise<void>;
+export declare const acquireExclusiveVolumeReservations: (report: DistributionReport, deploymentLineage: string, deploymentContainerName: string, imageReference: string, runDocker: DockerCommandRunner) => Promise<ExclusiveVolumeReservation>;
+export declare const assertCandidateContainerReady: (runDocker: DockerCommandRunner, candidateId: string, expectedName: string) => Promise<void>;
+export declare const assertContainerStopped: (runDocker: DockerCommandRunner, reference: string, expectedId: string) => Promise<void>;
+export declare const restorePreviousContainer: (runDocker: DockerCommandRunner, previous: ContainerSnapshot, backupName: string, deploymentName: string) => Promise<void>;
+export declare const rollbackCandidateContainer: (runDocker: DockerCommandRunner, candidateId: string | undefined, candidateName: string, previous: ContainerSnapshot | null, backupName: string) => Promise<void>;

package/dist/distribution/consumeImageLifecycle.js

@@ -0,0 +1,231 @@
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { SpawnfileError } from "../shared/index.js";
+import { derivePersistentMountVolumeName } from "./consumeImageSupport.js";
+const dockerId = /^[a-f0-9]{64}$/u;
+const missingContainer = /(?:No such (?:container|object)|container .* not found)/iu;
+const snapshotFormat = "{{json .Id}}\n{{json .Name}}\n{{json .State.Running}}";
+const reservationFormat = "{{json .Id}}\n{{json .Config.Labels}}";
+const reservationVersionLabel = "com.spawnfile.exclusive-volume-reservation";
+const reservationOwnerLabel = "com.spawnfile.exclusive-volume-owner";
+const reservationVolumeLabel = "com.spawnfile.exclusive-volume-digest";
+const parseSnapshot = (raw) => {
+    try {
+        const [idRaw, nameRaw, runningRaw, ...extra] = raw.toString("utf8").trim().split("\n");
+        if (!idRaw || !nameRaw || !runningRaw || extra.length > 0)
+            throw new Error("shape");
+        const id = JSON.parse(idRaw);
+        const name = JSON.parse(nameRaw);
+        const running = JSON.parse(runningRaw);
+        if (typeof id !== "string" || !dockerId.test(id)
+            || typeof name !== "string" || !name.startsWith("/") || name.length < 2
+            || typeof running !== "boolean")
+            throw new Error("values");
+        return { id, name: name.slice(1), running };
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Container returned invalid identity state");
+    }
+};
+export const inspectContainerSnapshot = async (runDocker, reference) => {
+    try {
+        return parseSnapshot(await runDocker([
+            "container", "inspect", "--format", snapshotFormat, reference
+        ]));
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError && error.message === "Container returned invalid identity state")
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        if (missingContainer.test(message))
+            return null;
+        throw new SpawnfileError("runtime_error", "Unable to determine container identity state");
+    }
+};
+export const assertExclusiveVolumesAvailable = async (report, deploymentLineage, deploymentContainerName, runDocker) => {
+    for (const mount of report.persistent_mounts.filter((candidate) => candidate.lifecycle === "exclusive-reattach")) {
+        const volume = derivePersistentMountVolumeName(deploymentLineage, mount);
+        const occupants = (await runDocker([
+            "ps", "--filter", `volume=${volume}`, "--format", "{{.Names}}"
+        ])).toString("utf8").split("\n").map((name) => name.trim()).filter(Boolean);
+        if (occupants.some((name) => name !== deploymentContainerName)) {
+            throw new SpawnfileError("runtime_error", `Exclusive persistent mount ${mount.id} is attached to another running deployment; stop that deployment before reattaching the realm`);
+        }
+    }
+};
+const reservationName = (volumeDigest) => `spawnfile-volume-reservation-${volumeDigest.slice("sha256:".length, 24 + "sha256:".length)}`;
+const inspectReservation = async (runDocker, record) => {
+    try {
+        const output = (await runDocker([
+            "container", "inspect", "--format", reservationFormat, record.id
+        ])).toString("utf8").trim().split("\n");
+        if (output.length !== 2)
+            throw new Error("shape");
+        const id = JSON.parse(output[0]);
+        const labels = JSON.parse(output[1]);
+        if (id !== record.id || !labels || typeof labels !== "object" || Array.isArray(labels))
+            throw new Error("identity");
+        const values = labels;
+        if (values[reservationVersionLabel] !== "v1"
+            || values[reservationOwnerLabel] !== record.owner
+            || values[reservationVolumeLabel] !== record.volumeDigest)
+            throw new Error("authority");
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Exclusive persistent mount reservation identity is unavailable");
+    }
+};
+const releaseReservations = async (runDocker, records) => {
+    let failed = false;
+    for (const record of [...records].reverse()) {
+        try {
+            await inspectReservation(runDocker, record);
+            await runDocker(["container", "rm", record.id]);
+        }
+        catch {
+            failed = true;
+        }
+    }
+    if (failed)
+        throw new SpawnfileError("runtime_error", "Unable to release exclusive persistent mount reservation");
+};
+export const acquireExclusiveVolumeReservations = async (report, deploymentLineage, deploymentContainerName, imageReference, runDocker) => {
+    const volumes = report.persistent_mounts
+        .filter((mount) => mount.lifecycle === "exclusive-reattach")
+        .map((mount) => derivePersistentMountVolumeName(deploymentLineage, mount))
+        .sort();
+    const records = [];
+    try {
+        for (const volume of volumes) {
+            const volumeDigest = `sha256:${createHash("sha256").update(volume).digest("hex")}`;
+            const owner = randomUUID();
+            const name = reservationName(volumeDigest);
+            let id;
+            try {
+                id = (await runDocker([
+                    "container", "create", "--name", name,
+                    "--label", `${reservationVersionLabel}=v1`,
+                    "--label", `${reservationOwnerLabel}=${owner}`,
+                    "--label", `${reservationVolumeLabel}=${volumeDigest}`,
+                    imageReference
+                ])).toString("utf8").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 record = { id, name, owner, volumeDigest };
+            records.push(record);
+            await inspectReservation(runDocker, record);
+        }
+        await assertExclusiveVolumesAvailable(report, deploymentLineage, deploymentContainerName, runDocker);
+    }
+    catch (error) {
+        if (records.length > 0)
+            await releaseReservations(runDocker, records);
+        throw error;
+    }
+    let released = false;
+    return {
+        release: async () => {
+            if (released)
+                return;
+            await releaseReservations(runDocker, records);
+            released = true;
+        }
+    };
+};
+const parseCandidateState = (raw) => {
+    try {
+        const [idRaw, nameRaw, stateRaw, ...extra] = raw.toString("utf8").trim().split("\n");
+        if (!idRaw || !nameRaw || !stateRaw || extra.length > 0)
+            throw new Error("shape");
+        const id = JSON.parse(idRaw);
+        const name = JSON.parse(nameRaw);
+        const state = JSON.parse(stateRaw);
+        if (typeof id !== "string" || !dockerId.test(id)
+            || typeof name !== "string" || !name.startsWith("/") || name.length < 2
+            || !state || typeof state !== "object" || typeof state.Running !== "boolean")
+            throw new Error("values");
+        return { snapshot: { id, name: name.slice(1), running: state.Running }, state };
+    }
+    catch {
+        throw new SpawnfileError("runtime_error", "Candidate container returned invalid readiness state");
+    }
+};
+const candidateReadinessTimeoutMs = 120_000;
+const candidateReadinessPollMs = 1_000;
+export const assertCandidateContainerReady = async (runDocker, candidateId, expectedName) => {
+    if (!dockerId.test(candidateId))
+        throw new SpawnfileError("runtime_error", "Candidate container returned invalid identity");
+    const deadline = Date.now() + candidateReadinessTimeoutMs;
+    for (;;) {
+        const { snapshot, state } = parseCandidateState(await runDocker([
+            "container", "inspect", "--format", "{{json .Id}}\n{{json .Name}}\n{{json .State}}", candidateId
+        ]));
+        if (snapshot.id !== candidateId || snapshot.name !== expectedName) {
+            throw new SpawnfileError("runtime_error", "Candidate container identity did not match detached run");
+        }
+        const health = state.Health?.Status;
+        if (state.Running === true && (health === undefined || health === "healthy"))
+            return;
+        // Docker may exhaust its health retries while a live process is still
+        // initializing. Honor our full readiness budget; only healthy can pass.
+        if (state.Running !== true || (health !== "starting" && health !== "unhealthy"))
+            break;
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            break;
+        await delay(Math.min(candidateReadinessPollMs, remainingMs));
+    }
+    throw new SpawnfileError("runtime_error", "Candidate container did not become ready");
+};
+export const assertContainerStopped = async (runDocker, reference, expectedId) => {
+    const observed = await inspectContainerSnapshot(runDocker, reference);
+    if (observed === null || observed.id !== expectedId || observed.running) {
+        throw new SpawnfileError("runtime_error", "Prior container did not reach a verified stopped state");
+    }
+};
+export const restorePreviousContainer = async (runDocker, previous, backupName, deploymentName) => {
+    const backup = await inspectContainerSnapshot(runDocker, backupName);
+    if (backup === null || backup.id !== previous.id) {
+        throw new SpawnfileError("runtime_error", "Prior container rollback identity is unavailable");
+    }
+    await runDocker(["rename", backupName, deploymentName]);
+    if (previous.running !== backup.running) {
+        await runDocker([previous.running ? "start" : "stop", previous.id]);
+    }
+    const restored = await inspectContainerSnapshot(runDocker, previous.id);
+    if (restored === null || restored.id !== previous.id || restored.name !== deploymentName
+        || restored.running !== previous.running) {
+        throw new SpawnfileError("runtime_error", "Prior container rollback state could not be verified");
+    }
+};
+export const rollbackCandidateContainer = async (runDocker, candidateId, candidateName, previous, backupName) => {
+    const failed = [];
+    if (candidateId !== undefined) {
+        try {
+            const candidate = await inspectContainerSnapshot(runDocker, candidateId);
+            if (candidate !== null) {
+                if (candidate.id !== candidateId || candidate.name !== candidateName)
+                    throw new Error("identity");
+                await runDocker(["rm", "-f", candidateId]);
+            }
+        }
+        catch {
+            failed.push("candidate cleanup");
+        }
+    }
+    if (previous !== null) {
+        try {
+            await restorePreviousContainer(runDocker, previous, backupName, candidateName);
+        }
+        catch {
+            failed.push("prior restore");
+        }
+    }
+    if (failed.length > 0) {
+        throw new SpawnfileError("runtime_error", `Candidate deployment failed and rollback was incomplete (${failed.join(", ")})`);
+    }
+};

package/dist/distribution/consumeImageSupport.d.ts

@@ -1,9 +1,21 @@
 import type { ParsedImageReference } from "./imageRef.js";
 import type { DistributionReport } from "./types.js";
+import type { DistributionPersistentMount } from "./types.js";
 /** Derives a kebab-case deployment name from the image repository component. */
 export declare const deriveDeploymentName: (ref: ParsedImageReference) => string;
 /** Per-deployment volume name so two deployments never share a store. */
 export declare const deriveVolumeName: (deploymentName: string, mountId: string) => string;
+/**
+ * An author-declared name wins over any derivation, in image mode exactly as
+ * in project mode. Without this, an operator who pre-created
+ * `clank-newsroom-store` and deployed the published image silently got
+ * `spawnfile-exclusive-<id>-<hash>` — a brand-new empty volume — while the
+ * spec promised the declared name verbatim.
+ *
+ * Only a DECLARED name travels in the report; an undeclared mount is still
+ * named per deployment so two deployments of one image never share state.
+ */
+export declare const derivePersistentMountVolumeName: (deploymentName: string, mount: DistributionPersistentMount) => string;
 export interface ResolveImageEnvironmentInput {
     authValues: Record<string, string>;
     envFileEnv?: Record<string, string>;

package/dist/distribution/consumeImageSupport.js

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { createExclusiveReattachVolumeName } from "../shared/index.js";
 const GENERATED_RUNTIME_SECRET_NAMES = new Set([
     "OPENCLAW_GATEWAY_TOKEN",
     "OPENCLAW_HOOKS_TOKEN"
@@ -17,6 +18,20 @@ export const deriveVolumeName = (deploymentName, mountId) => {
     const safeMount = mountId.replace(/[^A-Za-z0-9_.-]+/g, "-");
     return `spawnfile_${deploymentName}_${safeMount}`;
 };
+/**
+ * An author-declared name wins over any derivation, in image mode exactly as
+ * in project mode. Without this, an operator who pre-created
+ * `clank-newsroom-store` and deployed the published image silently got
+ * `spawnfile-exclusive-<id>-<hash>` — a brand-new empty volume — while the
+ * spec promised the declared name verbatim.
+ *
+ * Only a DECLARED name travels in the report; an undeclared mount is still
+ * named per deployment so two deployments of one image never share state.
+ */
+export const derivePersistentMountVolumeName = (deploymentName, mount) => mount.declared_volume_name?.trim()
+    || (mount.lifecycle === "exclusive-reattach"
+        ? createExclusiveReattachVolumeName(deploymentName, mount.id)
+        : deriveVolumeName(deploymentName, mount.id));
 /**
  * Builds the container environment for a sourceless deployment: auth-profile
  * and env-file values, process-env overrides for declared secrets, and

package/dist/distribution/distributionReportSchema.d.ts

@@ -27,9 +27,11 @@ export declare const distributionReportSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     persistent_mounts: z.ZodArray<z.ZodObject<{
+        declared_volume_name: z.ZodOptional<z.ZodString>;
         durability: z.ZodLiteral<"persistent">;
         id: z.ZodString;
         kind: z.ZodLiteral<"volume">;
+        lifecycle: z.ZodOptional<z.ZodLiteral<"exclusive-reattach">>;
         target: z.ZodString;
     }, z.core.$strict>>;
     port_mappings: z.ZodArray<z.ZodObject<{
@@ -39,7 +41,7 @@ export declare const distributionReportSchema: z.ZodObject<{
     ports: z.ZodArray<z.ZodNumber>;
     resources: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        kind: z.ZodUnion<readonly [z.ZodLiteral<"git">, z.ZodLiteral<"volume">]>;
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"bundle">, z.ZodLiteral<"git">, z.ZodLiteral<"volume">]>;
         link_path: z.ZodString;
         mode: z.ZodUnion<readonly [z.ZodLiteral<"mutable">, z.ZodLiteral<"readonly">]>;
         mount: z.ZodString;
@@ -47,6 +49,14 @@ export declare const distributionReportSchema: z.ZodObject<{
     }, z.core.$strict>>;
     runtime_instances: z.ZodArray<z.ZodObject<{
         config_path: z.ZodString;
+        engine_by_node_id: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            codex: "codex";
+            grok: "grok";
+            agy: "agy";
+            claude: "claude";
+            pi: "pi";
+            scripted: "scripted";
+        }>>>;
         home_path: z.ZodNullable<z.ZodString>;
         id: z.ZodString;
         internal_port: z.ZodNullable<z.ZodNumber>;

package/dist/distribution/distributionReportSchema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { SpawnfileError } from "../shared/index.js";
-import { DISTRIBUTION_REPORT_VERSION, WORLD_BINDINGS_IMAGE_PATH } from "./types.js";
+import { DISTRIBUTION_ENGINE_KINDS, DISTRIBUTION_REPORT_VERSION, WORLD_BINDINGS_IMAGE_PATH } from "./types.js";
 const secretEntrySchema = z.object({
     generated: z.boolean(),
     name: z.string().min(1),
@@ -32,6 +32,7 @@ const instanceIdSchema = z
 });
 const runtimeInstanceSchema = z.object({
     config_path: containerPathSchema,
+    engine_by_node_id: z.record(z.string().min(1), z.enum(DISTRIBUTION_ENGINE_KINDS)).optional(),
     home_path: containerPathSchema.nullable(),
     id: instanceIdSchema,
     internal_port: portSchema.nullable(),
@@ -69,11 +70,23 @@ export const distributionReportSchema = z.object({
         }).strict())
     }).strict(),
     persistent_mounts: z.array(z.object({
+        // Used verbatim as a docker volume name by `consumeImage`, so it is
+        // constrained to docker's own volume-name charset here (defence in depth,
+        // exactly as `id` is).
+        declared_volume_name: z
+            .string()
+            .min(1)
+            .max(255)
+            .refine((value) => /^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(value) && !value.includes(".."), {
+            message: "must be a docker volume name (letters, digits, '_', '.', '-'; no '/', ':', whitespace, or '..')"
+        })
+            .optional(),
         durability: z.literal("persistent"),
         // Sanitized by deriveVolumeName before use, but constrained here too so the
         // schema alone keeps the volume-name source clean (defense in depth).
         id: instanceIdSchema,
         kind: z.literal("volume"),
+        lifecycle: z.literal("exclusive-reattach").optional(),
         target: containerPathSchema
     }).strict()),
     port_mappings: z.array(z.object({
@@ -83,7 +96,7 @@ export const distributionReportSchema = z.object({
     ports: z.array(portSchema),
     resources: z.array(z.object({
         id: z.string().min(1),
-        kind: z.union([z.literal("git"), z.literal("volume")]),
+        kind: z.union([z.literal("bundle"), z.literal("git"), z.literal("volume")]),
         link_path: z.string(),
         mode: z.union([z.literal("mutable"), z.literal("readonly")]),
         mount: z.string(),

package/dist/distribution/dockerRunner.d.ts

@@ -1,5 +1,10 @@
 export interface DockerCommandRunner {
     /** Runs docker with args; resolves stdout as a Buffer. Rejects on non-zero exit. */
-    (args: string[]): Promise<Buffer>;
+    (args: string[], options?: DockerCommandOptions): Promise<Buffer>;
+}
+export interface DockerCommandOptions {
+    captureStderr?: boolean;
+    maxOutputBytes?: number;
+    timeoutMs?: number;
 }
 export declare const createConsumerDockerRunner: (dockerCommand: string, baseArgs: string[]) => DockerCommandRunner;

package/dist/distribution/dockerRunner.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { SpawnfileError } from "../shared/index.js";
-export const createConsumerDockerRunner = (dockerCommand, baseArgs) => async (args) => new Promise((resolve, reject) => {
+export const createConsumerDockerRunner = (dockerCommand, baseArgs) => async (args, options = {}) => new Promise((resolve, reject) => {
     const finalArgs = [...baseArgs, ...args];
     const child = spawn(dockerCommand, finalArgs, {
         env: { ...process.env },
@@ -8,10 +8,37 @@ export const createConsumerDockerRunner = (dockerCommand, baseArgs) => async (ar
     });
     const stdout = [];
     const stderr = [];
-    child.stdout.on("data", (chunk) => stdout.push(chunk));
-    child.stderr.on("data", (chunk) => stderr.push(String(chunk)));
-    child.on("error", reject);
+    let bytes = 0;
+    let stopped = false;
+    const stop = (reason) => {
+        stopped = true;
+        child.kill("SIGKILL");
+        reject(new SpawnfileError("runtime_error", reason));
+    };
+    const timer = options.timeoutMs === undefined ? undefined
+        : setTimeout(() => stop("Docker diagnostic command timed out"), options.timeoutMs);
+    const clearTimer = () => { if (timer)
+        clearTimeout(timer); };
+    const collect = (chunk, isStderr) => {
+        if (stopped)
+            return;
+        bytes += chunk.length;
+        if (options.maxOutputBytes !== undefined && bytes > options.maxOutputBytes) {
+            stop("Docker diagnostic output exceeded its byte limit");
+            return;
+        }
+        if (isStderr)
+            stderr.push(chunk.toString("utf8"));
+        if (!isStderr || options.captureStderr)
+            stdout.push(chunk);
+    };
+    child.stdout.on("data", (chunk) => collect(chunk, false));
+    child.stderr.on("data", (chunk) => collect(chunk, true));
+    child.on("error", (error) => { clearTimer(); reject(error); });
     child.on("close", (code) => {
+        clearTimer();
+        if (stopped)
+            return;
         if (code === 0) {
             resolve(Buffer.concat(stdout));
             return;

package/dist/distribution/imageRuntimeAuth.d.ts

@@ -1,14 +1,22 @@
 import type { ResolvedAuthProfile } from "../auth/index.js";
 import type { DistributionReport } from "./types.js";
 export interface ImageRuntimeAuthInput {
-    authProfile: ResolvedAuthProfile;
+    authProfile: ResolvedAuthProfile | null;
+    /**
+     * The uid the deployed Daimon image reads its credential leaves as. Defaults
+     * to the compiled image's organization uid; only override it against an image
+     * known to run under a different identity.
+     */
+    daimonContainerCredentialUid?: number;
     report: DistributionReport;
+    sourceEnvironment?: Record<string, string | undefined>;
     tempRoot: string;
 }
 export interface ImageRuntimeAuthResult {
     coveredModelSecrets: Set<string>;
     mountArgs: string[];
 }
+export declare const prepareDaimonImageAuthMounts: (instance: DistributionReport["runtime_instances"][number], environment: Record<string, string | undefined>, authProfile: ResolvedAuthProfile | null, containerCredentialUid?: number) => Promise<string[]>;
 /**
  * Builds the credential mounts for a sourceless image deployment that uses
  * import-based model auth. The OAuth-mode config is already baked into the

package/dist/distribution/imageRuntimeAuth.js

@@ -2,8 +2,71 @@ import path from "node:path";
 import { loadImportedClaudeCodeCredential, loadImportedCodexCredential } from "../auth/index.js";
 import { fileExists } from "../filesystem/index.js";
 import { getRuntimeAdapter } from "../runtime/index.js";
+import { DAIMON_AGY_SUBSCRIPTION_REALM, DAIMON_ENGINE_CREDENTIALS, DAIMON_GROK_SUBSCRIPTION_REALM } from "../runtime/daimon/contractManifest.js";
+import { assertDaimonCredentialContainerOwner, assertSafeDaimonSourceFile, DAIMON_AGY_UNLOCK_SOURCE_ENV, DAIMON_CREDENTIAL_CONTAINER_UID, daimonSourcePathForEngine } from "../runtime/daimon/runAuth.js";
 import { SpawnfileError } from "../shared/index.js";
 const importMountTargetName = (kind) => kind === "claude-code" ? ".claude" : ".codex";
+const daimonNodeSlug = (nodeId) => nodeId.replace(/^agent:/u, "").toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "");
+const daimonInstanceRoot = (instance) => {
+    const root = path.posix.join("/var/lib/spawnfile/instances/daimon", instance.id);
+    if (instance.config_path !== path.posix.join(root, "daimon/daimon-organization-runtime.json")
+        || instance.workspace_path !== path.posix.join(root, "workspace")) {
+        throw new SpawnfileError("validation_error", "Daimon image runtime paths are not canonical");
+    }
+    return root;
+};
+export const prepareDaimonImageAuthMounts = async (instance, environment, authProfile, containerCredentialUid = DAIMON_CREDENTIAL_CONTAINER_UID) => {
+    const engines = Object.entries(instance.engine_by_node_id ?? {}).sort(([left], [right]) => left.localeCompare(right));
+    if (engines.length === 0) {
+        throw new SpawnfileError("validation_error", "Daimon image report is missing its engine map");
+    }
+    const engineNodeIds = engines.map(([nodeId]) => nodeId);
+    if (JSON.stringify(engineNodeIds) !== JSON.stringify([...instance.node_ids].sort())) {
+        throw new SpawnfileError("validation_error", "Daimon image engine map does not match its declared agents");
+    }
+    if (engines.some(([, engine]) => engine !== "agy" && engine !== "codex" && engine !== "grok")) {
+        throw new SpawnfileError("validation_error", "Daimon image report declares an unsupported engine");
+    }
+    const root = daimonInstanceRoot(instance);
+    const mounts = [];
+    const slugs = new Map();
+    for (const [nodeId] of engines) {
+        const slug = daimonNodeSlug(nodeId);
+        if (!slug || slugs.has(slug))
+            throw new SpawnfileError("validation_error", "Daimon image report has an unsafe agent id");
+        slugs.set(slug, nodeId);
+    }
+    const codexSource = engines.some(([, engine]) => engine === "codex")
+        ? daimonSourcePathForEngine("codex", environment, authProfile) : null;
+    if (codexSource) {
+        const ownerUid = await assertSafeDaimonSourceFile(codexSource, "codex", 64 * 1024, "codex");
+        assertDaimonCredentialContainerOwner(ownerUid, "codex", containerCredentialUid);
+    }
+    for (const [nodeId, engine] of engines) {
+        if (engine !== "codex")
+            continue;
+        const slug = daimonNodeSlug(nodeId);
+        const target = path.posix.join(root, "runtime-homes", slug, DAIMON_ENGINE_CREDENTIALS.codex.sourceRelativePath);
+        mounts.push("-v", `${codexSource}:${target}:ro`);
+    }
+    // The Grok bootstrap leaf is deliberately exempt from the container-owner
+    // assertion; see the matching note in runAuth.ts.
+    if (engines.some(([, engine]) => engine === "grok")) {
+        const source = daimonSourcePathForEngine("grok", environment);
+        await assertSafeDaimonSourceFile(source, "grok", DAIMON_GROK_SUBSCRIPTION_REALM.maxCredentialBytes, "grok");
+        mounts.push("-v", `${source}:${DAIMON_GROK_SUBSCRIPTION_REALM.bootstrapMountPath}:ro`);
+    }
+    if (engines.some(([, engine]) => engine === "agy")) {
+        const source = environment[DAIMON_AGY_UNLOCK_SOURCE_ENV]?.trim();
+        if (!source)
+            throw new SpawnfileError("validation_error", "Daimon runtime auth is missing the operator-authorized AGY realm unlock artifact");
+        const ownerUid = await assertSafeDaimonSourceFile(source, "AGY realm unlock", DAIMON_AGY_SUBSCRIPTION_REALM.maxUnlockBytes);
+        assertDaimonCredentialContainerOwner(ownerUid, "AGY realm unlock", containerCredentialUid);
+        mounts.push("-v", `${source}:${DAIMON_AGY_SUBSCRIPTION_REALM.unlockMountPath}:ro`);
+    }
+    return mounts;
+};
 /**
  * Builds the credential mounts for a sourceless image deployment that uses
  * import-based model auth. The OAuth-mode config is already baked into the
@@ -19,6 +82,12 @@ export const prepareImageRuntimeAuthMounts = async (input) => {
         if (instance.home_path) {
             runtimeHomes.add(instance.home_path);
         }
+        if (instance.runtime === "daimon") {
+            mountArgs.push(...await prepareDaimonImageAuthMounts(instance, input.sourceEnvironment ?? process.env, input.authProfile, input.daimonContainerCredentialUid ?? DAIMON_CREDENTIAL_CONTAINER_UID));
+            continue;
+        }
+        if (!input.authProfile)
+            continue;
         const adapter = getRuntimeAdapter(instance.runtime);
         if (!adapter.prepareRuntimeAuth) {
             continue;
@@ -45,7 +114,7 @@ export const prepareImageRuntimeAuthMounts = async (input) => {
     // Mount the raw credential import directories into each runtime home so the
     // runtime's OAuth client can read them (e.g. ~/.claude, ~/.codex).
     for (const kind of ["claude-code", "codex"]) {
-        const entry = input.authProfile.imports[kind];
+        const entry = input.authProfile?.imports[kind];
         if (!entry) {
             continue;
         }

package/dist/distribution/index.d.ts

@@ -6,7 +6,7 @@ export type { DockerCommandRunner, ExtractImageOptions, ImageInspection } from "
 export { parseDistributionReport } from "./distributionReportSchema.js";
 export { consumeImageUp } from "./consumeImage.js";
 export type { ConsumeImageUpOptions, ConsumeImageUpResult } from "./consumeImage.js";
-export { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+export { deriveDeploymentName, derivePersistentMountVolumeName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
 export { createConsumerDockerRunner } from "./dockerRunner.js";
 export { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
 export { runImagePreflight } from "./preflight.js";

package/dist/distribution/index.js

@@ -3,7 +3,7 @@ export { createDistributionFingerprint } from "./fingerprint.js";
 export { extractImageReport, resolveDockerBaseArgs } from "./extractImage.js";
 export { parseDistributionReport } from "./distributionReportSchema.js";
 export { consumeImageUp } from "./consumeImage.js";
-export { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+export { deriveDeploymentName, derivePersistentMountVolumeName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
 export { createConsumerDockerRunner } from "./dockerRunner.js";
 export { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
 export { runImagePreflight } from "./preflight.js";

package/dist/distribution/preflight.js

@@ -1,5 +1,9 @@
 import { SpawnfileError } from "../shared/index.js";
 const ENV_BASED_AUTH_METHODS = new Set(["api_key", "none"]);
+// Satisfied by the runtime's own credential slot (the Daimon Grok broker's
+// bootstrap realm, checked by `imageRuntimeAuth.ts`), never by an env value
+// or a host CLI import.
+const RUNTIME_OWNED_AUTH_METHODS = new Set(["grok"]);
 // Import-based auth methods are satisfiable sourceless when the consumer has the
 // matching local credential import (their logged-in Claude Code / Codex session).
 const IMPORT_AUTH_METHOD_KINDS = {
@@ -10,7 +14,7 @@ const collectUnsupportedAuth = (report, availableImports) => {
     const unsupported = [];
     for (const instance of report.runtime_instances) {
         for (const [provider, method] of Object.entries(instance.model_auth_methods)) {
-            if (ENV_BASED_AUTH_METHODS.has(method)) {
+            if (ENV_BASED_AUTH_METHODS.has(method) || RUNTIME_OWNED_AUTH_METHODS.has(method)) {
                 continue;
             }
             const importKind = IMPORT_AUTH_METHOD_KINDS[method];

package/dist/distribution/types.d.ts

@@ -22,14 +22,24 @@ export interface DistributionOrganizationSummary {
     teams: DistributionTeamSummary[];
 }
 export interface DistributionPersistentMount {
+    /**
+     * The author's own volume name for this mount, when the manifest declared
+     * one. The report never carries a compiler-DERIVED name — that encodes the
+     * creator's plan root and deployment lineage and stays private to that host
+     * — but a declared name belongs to the published declaration and a consumer
+     * honours it verbatim, so an operator who pre-created that volume attaches
+     * it instead of silently getting an empty one.
+     */
+    declared_volume_name?: string;
     durability: "persistent";
     id: string;
     kind: "volume";
+    lifecycle?: "exclusive-reattach";
     target: string;
 }
 export interface DistributionWorkspaceResource {
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     link_path: string;
     mode: "mutable" | "readonly";
     mount: string;
@@ -37,6 +47,7 @@ export interface DistributionWorkspaceResource {
 }
 export interface DistributionRuntimeInstance {
     config_path: string;
+    engine_by_node_id?: Record<string, string>;
     home_path: string | null;
     id: string;
     internal_port: number | null;
@@ -47,6 +58,8 @@ export interface DistributionRuntimeInstance {
     runtime: string;
     workspace_path: string;
 }
+export declare const DISTRIBUTION_ENGINE_KINDS: readonly ["agy", "claude", "codex", "grok", "pi", "scripted"];
+export type DistributionEngineKind = typeof DISTRIBUTION_ENGINE_KINDS[number];
 export interface DistributionMoltnetNetwork {
     binding: "env";
     id: string;

package/dist/distribution/types.js

@@ -1,3 +1,6 @@
+export const DISTRIBUTION_ENGINE_KINDS = [
+    "agy", "claude", "codex", "grok", "pi", "scripted"
+];
 export const DISTRIBUTION_REPORT_VERSION = "spawnfile.distribution-report.v1";
 export const DISTRIBUTION_REPORT_IMAGE_PATH = "/spawnfile/spawnfile-report.json";
 export const DISTRIBUTION_REPORT_OUTPUT_FILE = "distribution-report.json";