spawnfile 0.1.17 → 0.1.19

package/dist/deployment/resourceLog.d.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { type RecordingReport } from "../report/index.js";
+export declare const DEPLOY_RESOURCES_VERSION = "spawnfile.deploy-resources.v1";
+export declare const DEPLOY_RESOURCE_LOG_FILE = "resource-log.jsonl";
+export declare const deployResourcesSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.deploy-resources.v1">;
+    deployment: z.ZodString;
+    deployment_id: z.ZodString;
+    activated_at: z.ZodISODateTime;
+    activation_exact: z.ZodBoolean;
+    activation_note: z.ZodOptional<z.ZodString>;
+    rolled_back_at: z.ZodOptional<z.ZodISODateTime>;
+    exact: z.ZodOptional<z.ZodLiteral<false>>;
+    deployed_at: z.ZodISODateTime;
+    report_sha256: z.ZodString;
+    resources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"git">;
+        commit: z.ZodString;
+        sha256: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+        agent_node_ids: z.ZodArray<z.ZodString>;
+        declared_by: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"bundle">;
+        sha256: z.ZodString;
+        origin: z.ZodOptional<z.ZodString>;
+        agent_node_ids: z.ZodArray<z.ZodString>;
+        declared_by: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "kind">>;
+    recording_agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        node_id: z.ZodString;
+        slug: z.ZodString;
+        directory: z.ZodString;
+        keep_ms: z.ZodNumber;
+        networks: z.ZodArray<z.ZodString>;
+        memory: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            declared_by: z.ZodString;
+            ledger_path: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+        feeds: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            volume_name: z.ZodString;
+        }, z.core.$strict>>;
+        resources: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                git: "git";
+                bundle: "bundle";
+            }>;
+        }, z.core.$strict>>;
+        snapshots: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type DeployResources = z.infer<typeof deployResourcesSchema>;
+export interface ResourceOwnership {
+    agent_node_ids: string[];
+    declared_by?: string;
+}
+/** Both reports carry the already-resolved pins; distribution omits private URLs. */
+export interface DeployResourceReport {
+    recording?: RecordingReport;
+    workspace_git_resources?: Array<Partial<ResourceOwnership> & {
+        id: string;
+        commit: string;
+        sha256: string;
+        url?: string;
+    }>;
+    workspace_bundles?: Array<Partial<ResourceOwnership> & {
+        id: string;
+        sha256: string;
+        origin?: string;
+    }>;
+}
+export interface DeploymentActivation {
+    activated_at?: string;
+    activation_exact?: boolean;
+    activation_note?: string;
+}
+/** Record path is the deployment identity: project output scoped, or home scoped. */
+export declare const deployResourceLogPath: (recordPath: string) => string;
+export declare const createDeployResources: (recordPath: string, record: DeploymentActivation & {
+    name: string;
+    created_at: string;
+}, report: DeployResourceReport, reportBytes: string) => DeployResources;
+/** Invalid/legacy unowned lines are reported; never guess an agent's pin. */
+export declare const readDeployResources: (recordPath: string) => import("../filesystem/retainedJsonl.js").JsonlReadResult<{
+    version: "spawnfile.deploy-resources.v1";
+    deployment: string;
+    deployment_id: string;
+    activated_at: string;
+    activation_exact: boolean;
+    deployed_at: string;
+    report_sha256: string;
+    resources: ({
+        id: string;
+        kind: "git";
+        commit: string;
+        sha256: string;
+        agent_node_ids: string[];
+        url?: string | undefined;
+        declared_by?: string | undefined;
+    } | {
+        id: string;
+        kind: "bundle";
+        sha256: string;
+        agent_node_ids: string[];
+        origin?: string | undefined;
+        declared_by?: string | undefined;
+    })[];
+    activation_note?: string | undefined;
+    rolled_back_at?: string | undefined;
+    exact?: false | undefined;
+    recording_agents?: {
+        node_id: string;
+        slug: string;
+        directory: string;
+        keep_ms: number;
+        networks: string[];
+        memory: {
+            id: string;
+            declared_by: string;
+            ledger_path: string | null;
+        }[];
+        feeds: {
+            id: string;
+            volume_name: string;
+        }[];
+        resources: {
+            id: string;
+            kind: "git" | "bundle";
+        }[];
+        snapshots: string[];
+    }[] | undefined;
+}>;
+export declare const deployResourcesAt: (entries: readonly DeployResources[], recordPath: string, instant: string | Date, agentNodeId?: string) => DeployResources | null;
+/** Caller holds the publication lock. Reconcile only against the LAST entry. */
+export declare const ensureDeployResources: (recordPath: string, entry: DeployResources, keepMs: number) => void;

package/dist/deployment/resourceLog.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { z } from "zod";
+import { appendRetainedJsonl, entryAt, readRetainedJsonl, syncFileSync } from "../filesystem/index.js";
+import { recordingAgentSchema } from "../report/index.js";
+export const DEPLOY_RESOURCES_VERSION = "spawnfile.deploy-resources.v1";
+export const DEPLOY_RESOURCE_LOG_FILE = "resource-log.jsonl";
+const text = z.string().min(1);
+const digest = text.regex(/^sha256:[a-f0-9]{64}$/u);
+const ownership = { agent_node_ids: z.array(text).min(1), declared_by: text.optional() };
+const resourceSchema = z.discriminatedUnion("kind", [
+    z.object({ ...ownership, id: text, kind: z.literal("git"), commit: text.regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u), sha256: digest, url: text.optional() }).strict(),
+    z.object({ ...ownership, id: text, kind: z.literal("bundle"), sha256: digest, origin: text.optional() }).strict()
+]);
+export const deployResourcesSchema = z.object({
+    version: z.literal(DEPLOY_RESOURCES_VERSION), deployment: text,
+    deployment_id: text,
+    activated_at: z.iso.datetime({ offset: true }), activation_exact: z.boolean(), activation_note: text.optional(),
+    rolled_back_at: z.iso.datetime({ offset: true }).optional(), exact: z.literal(false).optional(),
+    deployed_at: z.iso.datetime({ offset: true }), report_sha256: digest,
+    resources: z.array(resourceSchema),
+    recording_agents: z.array(recordingAgentSchema).optional()
+}).strict().refine((value) => !value.rolled_back_at || (value.exact === false && !value.activation_exact
+    && Date.parse(value.rolled_back_at) >= Date.parse(value.activated_at)), "Invalid candidate interval");
+const isDeployResources = (value) => deployResourcesSchema.safeParse(value).success;
+/** Record path is the deployment identity: project output scoped, or home scoped. */
+export const deployResourceLogPath = (recordPath) => path.join(path.dirname(recordPath), path.basename(recordPath) === "record.json" ? DEPLOY_RESOURCE_LOG_FILE : `${path.basename(recordPath, ".json")}.${DEPLOY_RESOURCE_LOG_FILE}`);
+export const createDeployResources = (recordPath, record, report, reportBytes) => deployResourcesSchema.parse({
+    version: DEPLOY_RESOURCES_VERSION, deployment: record.name, deployment_id: path.resolve(recordPath),
+    deployed_at: record.created_at, activated_at: record.activated_at ?? record.created_at,
+    activation_exact: record.activation_exact ?? false,
+    ...((record.activation_note || !record.activated_at) ? { activation_note: record.activation_note ?? "Activation boundary was not recorded" } : {}),
+    report_sha256: `sha256:${createHash("sha256").update(reportBytes).digest("hex")}`,
+    ...(report.recording?.agents ? { recording_agents: report.recording.agents } : {}),
+    resources: [
+        ...(report.workspace_git_resources ?? []).map(({ id, commit, sha256, url, agent_node_ids, declared_by }) => ({ id, kind: "git", commit, sha256, agent_node_ids, ...(declared_by ? { declared_by } : {}), ...(url === undefined ? {} : { url }) })),
+        ...(report.workspace_bundles ?? []).map(({ id, sha256, origin, agent_node_ids, declared_by }) => ({ id, kind: "bundle", sha256, agent_node_ids, ...(declared_by ? { declared_by } : {}), ...(origin === undefined ? {} : { origin }) }))
+    ]
+});
+/** Invalid/legacy unowned lines are reported; never guess an agent's pin. */
+export const readDeployResources = (recordPath) => readRetainedJsonl(deployResourceLogPath(recordPath), isDeployResources);
+export const deployResourcesAt = (entries, recordPath, instant, agentNodeId) => {
+    const scoped = entries.filter((value) => value.deployment_id === path.resolve(recordPath));
+    const at = instant instanceof Date ? instant.getTime() : Date.parse(instant);
+    const candidate = entryAt(scoped.filter((value) => value.rolled_back_at && at <= Date.parse(value.rolled_back_at)), instant, (value) => value.activated_at);
+    const entry = candidate ?? entryAt(activeDeployments(scoped), instant, (value) => value.activated_at);
+    return entry && agentNodeId !== undefined
+        ? { ...entry, resources: entry.resources.filter((resource) => resource.agent_node_ids.includes(agentNodeId)) }
+        : entry;
+};
+/** A published project candidate can subsequently fail readiness. Its successful-looking
+ * snapshot must not outlive its rollback interval, nor replace the restored predecessor. */
+const activeDeployments = (entries) => {
+    const rolledBack = new Set(entries.filter((entry) => entry.rolled_back_at)
+        .map((entry) => `${entry.activated_at}:${entry.report_sha256}`));
+    return entries.filter((entry) => !entry.rolled_back_at && !rolledBack.has(`${entry.activated_at}:${entry.report_sha256}`));
+};
+const retainDeployResources = (entries, cutoff) => {
+    const predecessor = entryAt(activeDeployments(entries), new Date(cutoff), (entry) => entry.activated_at);
+    return entries.filter((entry) => entry === predecessor || Date.parse(entry.activated_at) > cutoff
+        || (entry.rolled_back_at !== undefined && Date.parse(entry.rolled_back_at) >= cutoff));
+};
+/** Caller holds the publication lock. Reconcile only against the LAST entry. */
+export const ensureDeployResources = (recordPath, entry, keepMs) => {
+    if (entry.deployment_id !== path.resolve(recordPath))
+        throw new Error("Deployment history identity does not match its record path");
+    const history = readDeployResources(recordPath);
+    if (history.errors.length)
+        throw new Error(`Cannot reconcile deployment history: ${history.errors.join("; ")}`);
+    if (JSON.stringify(history.entries.at(-1)) === JSON.stringify(entry)) {
+        syncFileSync(deployResourceLogPath(recordPath));
+        return;
+    }
+    appendRetainedJsonl(deployResourceLogPath(recordPath), entry, {
+        keepMs, now: new Date(), timeOf: (value) => value.activated_at, isEntry: isDeployResources,
+        retain: retainDeployResources
+    });
+};

package/dist/distribution/buildDistributionReport.d.ts

@@ -15,9 +15,12 @@ export interface BuildDistributionReportInput {
     persistentMounts: DistributionPersistentMount[];
     portMappings: DistributionPortMapping[];
     publishedPorts: number[];
+    recording?: DistributionReport["recording"];
     resources: DistributionWorkspaceResource[];
     runtimeInstances: DistributionRuntimeInstance[];
     worldBindings?: DistributionWorldBindingsEvidence;
+    workspaceGitResources?: DistributionReport["workspace_git_resources"];
+    workspaceBundles?: DistributionReport["workspace_bundles"];
 }
 export declare const buildDistributionReport: (input: BuildDistributionReportInput) => DistributionReport;
 export declare const createDistributionImageLabels: (projectSlug: string, compileFingerprint: string) => DistributionImageLabels;

package/dist/distribution/buildDistributionReport.js

@@ -36,6 +36,11 @@ export const buildDistributionReport = (input) => {
         runtime_instances: [...input.runtimeInstances].sort((left, right) => left.id.localeCompare(right.id)),
         secrets: createSecretCategoryMap(input.envVariables),
         version: DISTRIBUTION_REPORT_VERSION,
+        ...(input.recording ? {
+            recording: input.recording,
+            workspace_git_resources: input.workspaceGitResources ?? [],
+            workspace_bundles: input.workspaceBundles ?? []
+        } : {}),
         ...(input.worldBindings ? { world_bindings: input.worldBindings } : {})
     };
     return {

package/dist/distribution/consumeImage.d.ts

@@ -8,6 +8,8 @@ export interface ConsumeImageUpOptions {
     daimonContainerCredentialUid?: number;
     authProfileName?: string | null;
     deploymentName?: string;
+    /** Caller owns the home lock across drain and swap; never set this without holding it. */
+    deploymentLockHeld?: boolean;
     dockerCommand?: string;
     dockerContext?: string;
     dockerHost?: string;
@@ -15,6 +17,7 @@ export interface ConsumeImageUpOptions {
     envFilePath?: string | null;
     pull?: boolean;
     runDocker?: DockerCommandRunner;
+    now?: () => Date;
 }
 export interface ConsumeImageUpResult {
     containerName: string;

package/dist/distribution/consumeImage.js

@@ -1,9 +1,9 @@
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { acquireHomeDeploymentLock, captureCandidateDiagnostics, createDockerDeploymentLabels, homeDeploymentExists, normalizeDeploymentName, readHomeDeploymentRecord, resolveDockerDeploymentTarget, sanitizeCandidateDiagnostic, verifyDockerDeploymentTarget, writeHomeDeployment } from "../deployment/index.js";
+import { acquireHomeDeploymentLock, activationBeforeStart, captureCandidateDiagnostics, createDockerDeploymentLabels, listHomeDeploymentRecords, HomeDeploymentRecordingError, normalizeDeploymentName, sanitizeCandidateDiagnostic, recordDeploymentRollback, resolveHomeRecordPath, writeHomeDeployment } from "../deployment/index.js";
 import { SpawnfileError } from "../shared/index.js";
-import { deriveDeploymentName, derivePersistentMountVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+import { readPreviousSource, resolveExistingOrNewTarget, 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";
@@ -67,7 +67,9 @@ export const consumeImageUp = async (imageRef, options = {}) => {
     const isExplicitName = Boolean(options.deploymentName);
     // Hold an exclusive lock for the whole operation so a concurrent `up` for the
     // same deployment cannot race on the record or orphan a container.
-    const releaseLock = await acquireHomeDeploymentLock(deploymentName);
+    const releaseLock = options.deploymentLockHeld
+        ? async () => undefined
+        : await acquireHomeDeploymentLock(deploymentName);
     try {
         return await consumeImageUpLocked(imageRef, parsedRef, deploymentName, isExplicitName, options);
     }
@@ -77,7 +79,8 @@ export const consumeImageUp = async (imageRef, options = {}) => {
 };
 const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExplicitName, options) => {
     void parsedRef;
-    const alreadyExists = await homeDeploymentExists(deploymentName);
+    const previousRecord = (await listHomeDeploymentRecords()).find((entry) => entry.record.name === deploymentName)?.record;
+    const alreadyExists = previousRecord !== undefined;
     if (alreadyExists && !isExplicitName) {
         throw new SpawnfileError("validation_error", `Deployment "${deploymentName}" already exists (derived from image ${imageRef}). ` +
             `To redeploy it, re-run with --deployment ${deploymentName}; ` +
@@ -143,11 +146,15 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
         const daimonDockerSecurityArgs = await resolveDaimonDockerSecurityArgsForImage(imageRef, report, runDocker, workDir);
         volumeReservation = await acquireExclusiveVolumeReservations(report, deploymentName, containerName, imageRef, runDocker);
         const previousContainer = await inspectContainerSnapshot(runDocker, containerName);
+        const now = options.now ?? (() => new Date());
+        let stoppedAt;
         if (previousContainer !== null) {
             await runDocker(["rename", containerName, backupName]);
             try {
                 await runDocker(["stop", backupName]);
                 await assertContainerStopped(runDocker, backupName, previousContainer.id);
+                if (report.recording)
+                    stoppedAt = now().getTime();
             }
             catch (error) {
                 try {
@@ -181,7 +188,9 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
         }
         runArgs.push(imageRef);
         let candidateId;
+        let activation = {};
         try {
+            activation = report.recording ? await activationBeforeStart(stoppedAt, now) : {};
             const runOutput = (await runDocker(runArgs)).toString("utf8").trim();
             const observedId = runOutput.split("\n").pop()?.trim();
             if (!observedId || !/^[a-f0-9]{64}$/u.test(observedId)) {
@@ -194,7 +203,9 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
             const record = {
                 auth_profile: options.authProfileName ?? null,
                 compile_fingerprint: inspection.compileFingerprint,
-                created_at: new Date().toISOString(),
+                created_at: now().toISOString(),
+                ...activation,
+                ...(report.recording ? { recording: report.recording } : {}),
                 ...(options.envFilePath ? { env_file: path.resolve(options.envFilePath) } : {}),
                 manager: "docker",
                 name: deploymentName,
@@ -215,7 +226,7 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
                 ],
                 version: "spawnfile.deployment.v2"
             };
-            const written = await writeHomeDeployment(record, report);
+            const written = await writeHomeDeployment(record, report, previousRecord);
             if (previousContainer !== null) {
                 await runDocker(["rm", "-f", previousContainer.id]).catch(() => undefined);
             }
@@ -229,6 +240,11 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
             };
         }
         catch (error) {
+            if (error instanceof HomeDeploymentRecordingError) {
+                if (previousContainer !== null)
+                    await runDocker(["rm", "-f", previousContainer.id]).catch(() => undefined);
+                throw error;
+            }
             const diagnostics = candidateId ? await captureCandidateDiagnostics({
                 candidateId, deploymentName, runDocker, secretValues: Object.values(env)
             }) : null;
@@ -236,7 +252,7 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
                 ? `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);
+                await rollbackCandidateContainer(runDocker, candidateId, containerName, previousContainer, backupName, report.recording && activation.activated_at ? () => recordDeploymentRollback(resolveHomeRecordPath(deploymentName), { name: deploymentName, created_at: activation.activated_at, ...activation }, report, `${JSON.stringify(report, null, 2)}\n`, now().toISOString()) : undefined);
             }
             catch (rollbackError) {
                 throw failure(rollbackError);
@@ -253,27 +269,3 @@ const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExpli
         }
     }
 };
-const readPreviousSource = async (deploymentName) => {
-    try {
-        const existing = await readHomeDeploymentRecord(deploymentName);
-        if (existing.source.kind !== "image") {
-            return null;
-        }
-        return { digest: existing.source.digest, ref: existing.source.ref };
-    }
-    catch {
-        return null;
-    }
-};
-const resolveExistingOrNewTarget = async (deploymentName, alreadyExists, options) => {
-    if (alreadyExists && !options.dockerContext && !options.dockerHost) {
-        const existing = await readHomeDeploymentRecord(deploymentName);
-        await verifyDockerDeploymentTarget(existing.target, { dockerCommand: options.dockerCommand });
-        return existing.target;
-    }
-    return resolveDockerDeploymentTarget({
-        context: options.dockerContext ?? null,
-        dockerCommand: options.dockerCommand,
-        dockerHost: options.dockerHost ?? null
-    });
-};

package/dist/distribution/consumeImageLifecycle.d.ts

@@ -11,7 +11,10 @@ export interface ExclusiveVolumeReservation {
 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 defaultCandidateReadinessTimeoutMs = 600000;
+export declare const candidateReadinessTimeoutEnv = "SPAWNFILE_CANDIDATE_READINESS_TIMEOUT_MS";
+export declare const resolveCandidateReadinessTimeoutMs: (env?: NodeJS.ProcessEnv) => number;
 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>;
+export declare const rollbackCandidateContainer: (runDocker: DockerCommandRunner, candidateId: string | undefined, candidateName: string, previous: ContainerSnapshot | null, backupName: string, onCandidateRemoved?: () => Promise<void>) => Promise<void>;

package/dist/distribution/consumeImageLifecycle.js

@@ -154,12 +154,22 @@ const parseCandidateState = (raw) => {
         throw new SpawnfileError("runtime_error", "Candidate container returned invalid readiness state");
     }
 };
-const candidateReadinessTimeoutMs = 120_000;
+export const defaultCandidateReadinessTimeoutMs = 600_000;
+export const candidateReadinessTimeoutEnv = "SPAWNFILE_CANDIDATE_READINESS_TIMEOUT_MS";
+// Large orgs can take minutes to boot; the budget is overridable per host.
+// Anything other than a positive integer falls back to the default.
+export const resolveCandidateReadinessTimeoutMs = (env = process.env) => {
+    const raw = env[candidateReadinessTimeoutEnv]?.trim();
+    if (!raw || !/^[0-9]+$/u.test(raw))
+        return defaultCandidateReadinessTimeoutMs;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) && value > 0 ? value : defaultCandidateReadinessTimeoutMs;
+};
 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;
+    const deadline = Date.now() + resolveCandidateReadinessTimeoutMs();
     for (;;) {
         const { snapshot, state } = parseCandidateState(await runDocker([
             "container", "inspect", "--format", "{{json .Id}}\n{{json .Name}}\n{{json .State}}", candidateId
@@ -202,7 +212,7 @@ export const restorePreviousContainer = async (runDocker, previous, backupName,
         throw new SpawnfileError("runtime_error", "Prior container rollback state could not be verified");
     }
 };
-export const rollbackCandidateContainer = async (runDocker, candidateId, candidateName, previous, backupName) => {
+export const rollbackCandidateContainer = async (runDocker, candidateId, candidateName, previous, backupName, onCandidateRemoved) => {
     const failed = [];
     if (candidateId !== undefined) {
         try {
@@ -212,6 +222,7 @@ export const rollbackCandidateContainer = async (runDocker, candidateId, candida
                     throw new Error("identity");
                 await runDocker(["rm", "-f", candidateId]);
             }
+            await onCandidateRemoved?.();
         }
         catch {
             failed.push("candidate cleanup");

package/dist/distribution/consumeImageSupport.d.ts

@@ -1,3 +1,5 @@
+import { type DockerDeploymentTarget } from "../deployment/index.js";
+import type { ConsumeImageUpOptions } from "./consumeImage.js";
 import type { ParsedImageReference } from "./imageRef.js";
 import type { DistributionReport } from "./types.js";
 import type { DistributionPersistentMount } from "./types.js";
@@ -28,3 +30,8 @@ export interface ResolveImageEnvironmentInput {
  */
 export declare const resolveImageEnvironment: (input: ResolveImageEnvironmentInput) => Record<string, string>;
 export declare const renderEnvFileContent: (env: Record<string, string>) => string;
+export declare const readPreviousSource: (deploymentName: string) => Promise<{
+    digest: string | null;
+    ref: string;
+} | null>;
+export declare const resolveExistingOrNewTarget: (deploymentName: string, alreadyExists: boolean, options: ConsumeImageUpOptions) => Promise<DockerDeploymentTarget>;

package/dist/distribution/consumeImageSupport.js

@@ -1,3 +1,4 @@
+import { readHomeDeploymentRecord, resolveDockerDeploymentTarget, verifyDockerDeploymentTarget } from "../deployment/index.js";
 import { randomBytes } from "node:crypto";
 import { createExclusiveReattachVolumeName } from "../shared/index.js";
 const GENERATED_RUNTIME_SECRET_NAMES = new Set([
@@ -76,3 +77,27 @@ export const renderEnvFileContent = (env) => Object.entries(env)
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, value]) => `${name}=${value}`)
     .join("\n") + "\n";
+export const readPreviousSource = async (deploymentName) => {
+    try {
+        const existing = await readHomeDeploymentRecord(deploymentName);
+        if (existing.source.kind !== "image") {
+            return null;
+        }
+        return { digest: existing.source.digest, ref: existing.source.ref };
+    }
+    catch {
+        return null;
+    }
+};
+export const resolveExistingOrNewTarget = async (deploymentName, alreadyExists, options) => {
+    if (alreadyExists && !options.dockerContext && !options.dockerHost) {
+        const existing = await readHomeDeploymentRecord(deploymentName);
+        await verifyDockerDeploymentTarget(existing.target, { dockerCommand: options.dockerCommand });
+        return existing.target;
+    }
+    return resolveDockerDeploymentTarget({
+        context: options.dockerContext ?? null,
+        dockerCommand: options.dockerCommand,
+        dockerHost: options.dockerHost ?? null
+    });
+};

package/dist/distribution/distributionReportSchema.d.ts

@@ -39,6 +39,35 @@ export declare const distributionReportSchema: z.ZodObject<{
         published_port: z.ZodNumber;
     }, z.core.$strict>>;
     ports: z.ZodArray<z.ZodNumber>;
+    recording: z.ZodOptional<z.ZodObject<{
+        keep_ms: z.ZodNumber;
+        memory_mount_ids: z.ZodArray<z.ZodString>;
+        recording_mount_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            node_id: z.ZodString;
+            slug: z.ZodString;
+            directory: z.ZodString;
+            keep_ms: z.ZodNumber;
+            networks: z.ZodArray<z.ZodString>;
+            memory: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                declared_by: z.ZodString;
+                ledger_path: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>;
+            feeds: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                volume_name: z.ZodString;
+            }, z.core.$strict>>;
+            resources: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodEnum<{
+                    git: "git";
+                    bundle: "bundle";
+                }>;
+            }, z.core.$strict>>;
+            snapshots: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
     resources: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodUnion<readonly [z.ZodLiteral<"bundle">, z.ZodLiteral<"git">, z.ZodLiteral<"volume">]>;
@@ -65,6 +94,7 @@ export declare const distributionReportSchema: z.ZodObject<{
         node_ids: z.ZodArray<z.ZodString>;
         published_port: z.ZodNullable<z.ZodNumber>;
         runtime: z.ZodString;
+        telemetry_mount_ids: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         workspace_path: z.ZodString;
     }, z.core.$strict>>;
     secrets: z.ZodObject<{
@@ -90,6 +120,23 @@ export declare const distributionReportSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     version: z.ZodLiteral<"spawnfile.distribution-report.v1">;
+    workspace_git_resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agent_node_ids: z.ZodArray<z.ZodString>;
+        declared_by: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        commit: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>>>;
+    workspace_bundles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agent_node_ids: z.ZodArray<z.ZodString>;
+        declared_by: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        sha256: z.ZodString;
+        origin: z.ZodOptional<z.ZodEnum<{
+            built: "built";
+            prebuilt: "prebuilt";
+        }>>;
+    }, z.core.$strict>>>;
     world_bindings: z.ZodOptional<z.ZodObject<{
         artifact_path: z.ZodLiteral<"/spawnfile/world-bindings.json">;
         digest: z.ZodString;

package/dist/distribution/distributionReportSchema.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { SpawnfileError } from "../shared/index.js";
+import { recordingReportSchema } from "../report/index.js";
 import { DISTRIBUTION_ENGINE_KINDS, DISTRIBUTION_REPORT_VERSION, WORLD_BINDINGS_IMAGE_PATH } from "./types.js";
 const secretEntrySchema = z.object({
     generated: z.boolean(),
@@ -41,6 +42,10 @@ const runtimeInstanceSchema = z.object({
     node_ids: z.array(z.string()),
     published_port: portSchema.nullable(),
     runtime: z.string().min(1),
+    // node id -> persistent mount id for per-agent telemetry; every pi/Daimon
+    // image this compiler builds carries it, so a strict schema without it
+    // refused image-mode `up` of the compiler's own output.
+    telemetry_mount_ids: z.record(z.string().min(1), instanceIdSchema).optional(),
     workspace_path: containerPathSchema
 }).strict();
 export const distributionReportSchema = z.object({
@@ -94,6 +99,7 @@ export const distributionReportSchema = z.object({
         published_port: portSchema
     }).strict()),
     ports: z.array(portSchema),
+    recording: recordingReportSchema.optional(),
     resources: z.array(z.object({
         id: z.string().min(1),
         kind: z.union([z.literal("bundle"), z.literal("git"), z.literal("volume")]),
@@ -110,6 +116,20 @@ export const distributionReportSchema = z.object({
         surface: z.array(secretEntrySchema)
     }).strict(),
     version: z.literal(DISTRIBUTION_REPORT_VERSION),
+    workspace_git_resources: z.array(z.object({
+        agent_node_ids: z.array(z.string().min(1)).min(1),
+        declared_by: z.string().min(1).optional(),
+        id: z.string().min(1),
+        commit: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u),
+        sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u)
+    }).strict()).optional(),
+    workspace_bundles: z.array(z.object({
+        agent_node_ids: z.array(z.string().min(1)).min(1),
+        declared_by: z.string().min(1).optional(),
+        id: z.string().min(1),
+        sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+        origin: z.enum(["built", "prebuilt"]).optional()
+    }).strict()).optional(),
     world_bindings: z.object({
         artifact_path: z.literal(WORLD_BINDINGS_IMAGE_PATH),
         digest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),

package/dist/distribution/renderImageInterface.js

@@ -80,7 +80,7 @@ export const renderImageInterface = (report, options) => {
     lines.push("");
     lines.push(`next: spawnfile up ${summary.imageRef} --auth-profile <profile>`);
     if (summary.requiredSecrets.length > 0) {
-        lines.push("  supply the required secrets above via that profile or --env-file");
+        lines.push("  supply the required secrets above via that profile or --runtime-env-file");
     }
     return lines.join("\n");
 };

package/dist/distribution/types.d.ts

@@ -1,4 +1,5 @@
 import type { ModelAuthMethod } from "../shared/index.js";
+import type { RecordingReport, WorkspaceResourceOwnership } from "../report/index.js";
 export type DistributionSecretCategory = "model" | "project" | "runtime" | "surface";
 export interface DistributionSecretEntry {
     generated: boolean;
@@ -56,6 +57,7 @@ export interface DistributionRuntimeInstance {
     node_ids: string[];
     published_port: number | null;
     runtime: string;
+    telemetry_mount_ids?: Record<string, string>;
     workspace_path: string;
 }
 export declare const DISTRIBUTION_ENGINE_KINDS: readonly ["agy", "claude", "codex", "grok", "pi", "scripted"];
@@ -86,10 +88,23 @@ export interface DistributionReport {
     persistent_mounts: DistributionPersistentMount[];
     port_mappings: DistributionPortMapping[];
     ports: number[];
+    recording?: RecordingReport;
     resources: DistributionWorkspaceResource[];
     runtime_instances: DistributionRuntimeInstance[];
     secrets: Record<DistributionSecretCategory, DistributionSecretEntry[]>;
     version: "spawnfile.distribution-report.v1";
+    /** Recording-only pins; ids are workspace resource ids, never scoped report keys. */
+    workspace_git_resources?: Array<WorkspaceResourceOwnership & {
+        id: string;
+        commit: string;
+        sha256: string;
+    }>;
+    /** Recording-only bundle identity; no creator-host paths or URLs are published. */
+    workspace_bundles?: Array<WorkspaceResourceOwnership & {
+        id: string;
+        sha256: string;
+        origin?: string;
+    }>;
     world_bindings?: DistributionWorldBindingsEvidence;
 }
 export declare const DISTRIBUTION_REPORT_VERSION = "spawnfile.distribution-report.v1";