spawnfile 0.1.13 → 0.1.17

package/dist/distribution/consumeImage.js

@@ -1,10 +1,12 @@
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { acquireHomeDeploymentLock, createDockerDeploymentLabels, homeDeploymentExists, normalizeDeploymentName, readHomeDeploymentRecord, resolveDockerDeploymentTarget, verifyDockerDeploymentTarget, writeHomeDeployment } from "../deployment/index.js";
+import { acquireHomeDeploymentLock, captureCandidateDiagnostics, createDockerDeploymentLabels, homeDeploymentExists, normalizeDeploymentName, readHomeDeploymentRecord, resolveDockerDeploymentTarget, sanitizeCandidateDiagnostic, verifyDockerDeploymentTarget, writeHomeDeployment } from "../deployment/index.js";
 import { SpawnfileError } from "../shared/index.js";
-import { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+import { deriveDeploymentName, derivePersistentMountVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+import { acquireExclusiveVolumeReservations, assertCandidateContainerReady, assertContainerStopped, inspectContainerSnapshot, restorePreviousContainer, rollbackCandidateContainer } from "./consumeImageLifecycle.js";
 import { createConsumerDockerRunner } from "./dockerRunner.js";
+import { resolveDaimonDockerSecurityArgsForImage } from "./consumeImageDaimonDocker.js";
 import { extractImageReport, resolveDockerBaseArgs } from "./extractImage.js";
 import { parseImageReference } from "./imageRef.js";
 import { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
@@ -35,15 +37,6 @@ const resolveRegistryDigest = async (imageRef, runDocker) => {
         return null;
     }
 };
-const containerExists = async (runDocker, containerName) => {
-    try {
-        await runDocker(["container", "inspect", containerName]);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
 const resolveLocalImageId = async (imageRef, runDocker) => {
     try {
         const raw = (await runDocker([
@@ -131,6 +124,7 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
     // port for two containers at once. There is a brief restart gap, unavoidable
     // when reusing host ports without a proxy.
     const backupName = `${containerName}-previous-${Date.now().toString(36)}`;
+    let volumeReservation;
     try {
         await writeFile(envFilePath, renderEnvFileContent(env), "utf8");
         // Prepare import-based model auth (the consumer's Claude/Codex login) and
@@ -138,24 +132,41 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
         // config is already baked into the image; this only resolves the credential
         // mounts. Doing it first guarantees an unusable import fails while the live
         // container is still untouched, never mid-swap.
-        const authMountArgs = options.authProfile && availableImports.length > 0
-            ? (await prepareImageRuntimeAuthMounts({
-                authProfile: options.authProfile,
-                report,
-                tempRoot: workDir
-            })).mountArgs
-            : [];
-        const liveExists = await containerExists(runDocker, containerName);
-        if (liveExists) {
+        const authMountArgs = (await prepareImageRuntimeAuthMounts({
+            authProfile: options.authProfile ?? null,
+            ...(options.daimonContainerCredentialUid === undefined
+                ? {}
+                : { daimonContainerCredentialUid: options.daimonContainerCredentialUid }),
+            report,
+            tempRoot: workDir
+        })).mountArgs;
+        const daimonDockerSecurityArgs = await resolveDaimonDockerSecurityArgsForImage(imageRef, report, runDocker, workDir);
+        volumeReservation = await acquireExclusiveVolumeReservations(report, deploymentName, containerName, imageRef, runDocker);
+        const previousContainer = await inspectContainerSnapshot(runDocker, containerName);
+        if (previousContainer !== null) {
             await runDocker(["rename", containerName, backupName]);
-            await runDocker(["stop", backupName]).catch(() => undefined);
+            try {
+                await runDocker(["stop", backupName]);
+                await assertContainerStopped(runDocker, backupName, previousContainer.id);
+            }
+            catch (error) {
+                try {
+                    await restorePreviousContainer(runDocker, previousContainer, backupName, containerName);
+                }
+                catch {
+                    throw new SpawnfileError("runtime_error", "Prior deployment stop failed and its original state could not be restored");
+                }
+                throw error;
+            }
         }
-        const runArgs = ["run", "-d", "--name", containerName, "--env-file", envFilePath];
+        const runArgs = [
+            "run", "-d", "--name", containerName, ...daimonDockerSecurityArgs, "--env-file", envFilePath
+        ];
         for (const port of report.ports) {
             runArgs.push("-p", `${port}:${port}`);
         }
         for (const mount of report.persistent_mounts) {
-            runArgs.push("-v", `${deriveVolumeName(deploymentName, mount.id)}:${mount.target}`);
+            runArgs.push("-v", `${derivePersistentMountVolumeName(deploymentName, mount)}:${mount.target}`);
         }
         runArgs.push(...authMountArgs);
         const labels = createDockerDeploymentLabels({
@@ -169,63 +180,77 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
             runArgs.push("--label", `${name}=${value}`);
         }
         runArgs.push(imageRef);
-        let runOutput;
+        let candidateId;
         try {
-            runOutput = (await runDocker(runArgs)).toString("utf8").trim();
+            const runOutput = (await runDocker(runArgs)).toString("utf8").trim();
+            const observedId = runOutput.split("\n").pop()?.trim();
+            if (!observedId || !/^[a-f0-9]{64}$/u.test(observedId)) {
+                throw new SpawnfileError("runtime_error", "Candidate container returned invalid identity");
+            }
+            candidateId = observedId;
+            await assertCandidateContainerReady(runDocker, candidateId, containerName);
+            const imageId = await resolveLocalImageId(imageRef, runDocker);
+            const digest = await resolveRegistryDigest(imageRef, runDocker);
+            const record = {
+                auth_profile: options.authProfileName ?? null,
+                compile_fingerprint: inspection.compileFingerprint,
+                created_at: new Date().toISOString(),
+                ...(options.envFilePath ? { env_file: path.resolve(options.envFilePath) } : {}),
+                manager: "docker",
+                name: deploymentName,
+                output_directory: null,
+                source: { digest, kind: "image", ref: imageRef },
+                target,
+                units: [
+                    {
+                        container_id: candidateId,
+                        container_name: containerName,
+                        contains: buildContainsEntries(report),
+                        id: unitIdFor(deploymentName),
+                        image_id: imageId,
+                        image_tag: imageRef,
+                        kind: "container",
+                        runtime_instances: report.runtime_instances.map((instance) => instance.id).sort()
+                    }
+                ],
+                version: "spawnfile.deployment.v2"
+            };
+            const written = await writeHomeDeployment(record, report);
+            if (previousContainer !== null) {
+                await runDocker(["rm", "-f", previousContainer.id]).catch(() => undefined);
+            }
+            return {
+                containerName,
+                deploymentName,
+                imageRef,
+                previous,
+                record,
+                recordPath: written.recordPath
+            };
         }
         catch (error) {
-            // The new container failed to start; remove the failed attempt and restore
-            // the previous deployment so a failed redeploy never loses the live one.
-            await runDocker(["rm", "-f", containerName]).catch(() => undefined);
-            if (liveExists) {
-                await runDocker(["rename", backupName, containerName]).catch(() => undefined);
-                await runDocker(["start", containerName]).catch(() => undefined);
+            const diagnostics = candidateId ? await captureCandidateDiagnostics({
+                candidateId, deploymentName, runDocker, secretValues: Object.values(env)
+            }) : null;
+            const detail = diagnostics ? ` (${diagnostics.summary}); ${diagnostics.path
+                ? `private diagnostics: ${diagnostics.path}` : "private diagnostics unavailable"}` : "";
+            const failure = (cause) => new SpawnfileError("runtime_error", sanitizeCandidateDiagnostic(cause instanceof Error ? cause.message : String(cause), Object.values(env)) + detail);
+            try {
+                await rollbackCandidateContainer(runDocker, candidateId, containerName, previousContainer, backupName);
             }
-            throw error;
-        }
-        // The new container is up — discard the previous one.
-        if (liveExists) {
-            await runDocker(["rm", "-f", backupName]).catch(() => undefined);
+            catch (rollbackError) {
+                throw failure(rollbackError);
+            }
+            throw failure(error);
         }
-        const containerId = runOutput.split("\n").pop()?.trim() || null;
-        const imageId = await resolveLocalImageId(imageRef, runDocker);
-        const digest = await resolveRegistryDigest(imageRef, runDocker);
-        const record = {
-            auth_profile: options.authProfileName ?? null,
-            compile_fingerprint: inspection.compileFingerprint,
-            created_at: new Date().toISOString(),
-            ...(options.envFilePath ? { env_file: path.resolve(options.envFilePath) } : {}),
-            manager: "docker",
-            name: deploymentName,
-            output_directory: null,
-            source: { digest, kind: "image", ref: imageRef },
-            target,
-            units: [
-                {
-                    container_id: containerId,
-                    container_name: containerName,
-                    contains: buildContainsEntries(report),
-                    id: unitIdFor(deploymentName),
-                    image_id: imageId,
-                    image_tag: imageRef,
-                    kind: "container",
-                    runtime_instances: report.runtime_instances.map((instance) => instance.id).sort()
-                }
-            ],
-            version: "spawnfile.deployment.v2"
-        };
-        const written = await writeHomeDeployment(record, report);
-        return {
-            containerName,
-            deploymentName,
-            imageRef,
-            previous,
-            record,
-            recordPath: written.recordPath
-        };
     }
     finally {
-        await rm(workDir, { force: true, recursive: true }).catch(() => undefined);
+        try {
+            await volumeReservation?.release();
+        }
+        finally {
+            await rm(workDir, { force: true, recursive: true }).catch(() => undefined);
+        }
     }
 };
 const readPreviousSource = async (deploymentName) => {

package/dist/distribution/consumeImageDaimonDocker.d.ts

@@ -0,0 +1,3 @@
+import type { DockerCommandRunner } from "./dockerRunner.js";
+import type { DistributionReport } from "./types.js";
+export declare const resolveDaimonDockerSecurityArgsForImage: (imageRef: string, report: DistributionReport, runDocker: DockerCommandRunner, securityDirectory: string) => Promise<string[]>;

package/dist/distribution/consumeImageDaimonDocker.js

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+import { SpawnfileError } from "../shared/errors.js";
+import { DAIMON_DOCKER_RUNTIME_SECURITY_ARGS, daimonEngineDockerSecurityArgsForConfigs, materializeDaimonGrokSeccompProfile } from "../shared/daimonCodexDocker.js";
+import { extractSingleFileFromTar } from "./tarReader.js";
+const DAIMON_CONFIG_SIZE_CAP_BYTES = 4 * 1024 * 1024;
+const daimonInstancesFrom = (report) => report.runtime_instances.filter((instance) => instance.runtime === "daimon");
+const assertAbsoluteConfigPath = (instance) => {
+    if (!instance.config_path.startsWith("/")) {
+        throw new SpawnfileError("validation_error", "Daimon runtime instance has a non-absolute generated config path");
+    }
+    return instance.config_path;
+};
+const readDaimonConfigSourcesFromImage = async (imageRef, instances, runDocker) => {
+    const helperName = `spawnfile-daimon-config-${randomUUID()}`;
+    await runDocker(["create", "--name", helperName, imageRef]);
+    try {
+        const sources = [];
+        for (const instance of instances) {
+            let tar;
+            try {
+                tar = await runDocker(["cp", `${helperName}:${assertAbsoluteConfigPath(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");
+            }
+            sources.push(extractSingleFileFromTar(tar, { maxBytes: DAIMON_CONFIG_SIZE_CAP_BYTES }).toString("utf8"));
+        }
+        return sources;
+    }
+    finally {
+        await runDocker(["rm", "-f", helperName]).catch(() => undefined);
+    }
+};
+export const resolveDaimonDockerSecurityArgsForImage = async (imageRef, report, runDocker, securityDirectory) => {
+    const daimonInstances = daimonInstancesFrom(report);
+    if (daimonInstances.length === 0)
+        return [];
+    const sources = await readDaimonConfigSourcesFromImage(imageRef, daimonInstances, runDocker);
+    return [
+        ...DAIMON_DOCKER_RUNTIME_SECURITY_ARGS,
+        ...(await daimonEngineDockerSecurityArgsForConfigs(sources, () => materializeDaimonGrokSeccompProfile(securityDirectory)))
+    ];
+};

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>;
@@ -80,5 +90,10 @@ export declare const distributionReportSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     version: z.ZodLiteral<"spawnfile.distribution-report.v1">;
+    world_bindings: z.ZodOptional<z.ZodObject<{
+        artifact_path: z.ZodLiteral<"/spawnfile/world-bindings.json">;
+        digest: z.ZodString;
+        schema: z.ZodLiteral<"simfile.world-bindings.v1">;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const parseDistributionReport: (source: unknown, sourceLabel?: string) => DistributionReport;