spawnfile 0.1.12 → 0.1.14

package/dist/deployment/dockerLogs.js

@@ -1,6 +1,7 @@
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { dockerContextNameForTarget } from "./target.js";
+import { redactSensitiveText } from "../shared/index.js";
 const execFile = promisify(execFileCallback);
 const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
 const withDockerTarget = (record, args) => {
@@ -17,16 +18,7 @@ const normalizeTail = (tail) => typeof tail === "number" && Number.isInteger(tai
 const redactKnownSecrets = (text, secretValues) => secretValues
     .filter((secret) => secret.length > 0)
     .reduce((redacted, secret) => redacted.replaceAll(secret, "[REDACTED]"), text);
-const redactTokenLikeText = (text) => {
-    let redacted = text;
-    redacted = redacted.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, "Bearer [REDACTED]");
-    redacted = redacted.replace(/\bmagt_v1_[A-Za-z0-9_-]{16,}\b/g, "[REDACTED]");
-    redacted = redacted.replace(/\b(?:sk|sk-proj)-[A-Za-z0-9_-]{20,}\b/g, "[REDACTED]");
-    redacted = redacted.replace(/\b([A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*=)([^\s"'`]+)/gi, "$1[REDACTED]");
-    redacted = redacted.replace(/("([^"]*(?:api[_-]?key|token|secret|password)[^"]*)"\s*:\s*")([^"]+)(")/gi, "$1[REDACTED]$4");
-    return redacted;
-};
-export const redactDockerLogText = (text, secretValues = []) => redactTokenLikeText(redactKnownSecrets(text, secretValues));
+export const redactDockerLogText = (text, secretValues = []) => redactSensitiveText(redactKnownSecrets(text, secretValues));
 const combineLogStreams = (stdout, stderr) => {
     if (!stdout) {
         return stderr;

package/dist/deployment/dockerManager.d.ts

@@ -1,6 +1,11 @@
 import type { DeploymentRecordSource } from "./record.js";
+import type { OrganizationReadinessEvidence } from "../compiler/organizationReadyEvidence.js";
+import { type DockerProbeExecFile } from "./dockerProbeGateway.js";
+import { type OrganizationReadiness } from "./organizationReady.js";
 import { type DockerDeploymentTarget, type DockerTargetExecFile } from "./target.js";
 import { type DeploymentRecord } from "./record.js";
+import { type OrganizationHandoff, type OrganizationHandoffInput } from "./organizationHandoffTypes.js";
+import type { OpaqueTargetHandle, SelectedTargetReceipt } from "../target/index.js";
 export interface DockerDeploymentNodeInput {
     id: string;
     kind: "agent" | "team";
@@ -20,6 +25,12 @@ export interface DockerDeploymentRunInvocationInput {
 export interface DockerDeploymentReportInput {
     compile_fingerprint?: string;
     container?: {
+        moltnet?: {
+            server_plans: Array<{
+                mode: "external" | "managed";
+                network_id: string;
+            }>;
+        };
         runtime_instances: Array<{
             id: string;
         }>;
@@ -34,14 +45,39 @@ export interface WriteDockerDeploymentRecordInput {
     deploymentName?: string;
     envFilePath?: string;
     imageTag: string;
+    networkIds?: string[];
     nodes: DockerDeploymentNodeInput[];
     outputDirectory: string;
+    organizationHandoff?: OrganizationHandoffInput;
+    organizationHandoffHandle?: OpaqueTargetHandle;
     projectRoot: string;
+    runId?: string;
     runMetadata?: DockerDeploymentRunMetadata;
     runtimeInstanceIds: string[];
     source?: DeploymentRecordSource;
     target: DockerDeploymentTarget;
 }
+export declare const createDockerOrganizationHandoffSession: (input: {
+    readonly bindingDigest: string;
+    readonly containerName: string;
+    readonly deploymentLabels: Readonly<Record<string, string>>;
+    readonly descriptorDigest: string;
+    readonly organizationHandoff: OrganizationHandoffInput;
+    readonly runId: string;
+    readonly selectedTarget: SelectedTargetReceipt;
+    readonly selectedTargetReceiptDigest: string;
+}) => {
+    readonly authorityInput: {
+        readonly bindingDigest: string;
+        readonly containerName: string;
+        readonly deploymentLabels: Readonly<Record<string, string>>;
+        readonly descriptorDigest: string;
+        readonly handoff: OrganizationHandoff;
+        readonly selectedTarget: SelectedTargetReceipt;
+        readonly selectedTargetReceiptDigest: string;
+    };
+    readonly organizationHandoff: OrganizationHandoff;
+};
 export declare const createDockerDeploymentUnitId: (deploymentName: string) => string;
 export declare const createDockerDeploymentRecord: (input: WriteDockerDeploymentRecordInput) => DeploymentRecord;
 export declare const createDockerProjectLabel: (projectRoot: string, projectName?: string) => string;
@@ -52,8 +88,23 @@ export declare const writeDockerDeploymentRecordForRun: (input: {
     imageTag: string;
     invocation: DockerDeploymentRunInvocationInput;
     outputDirectory: string;
+    organizationHandoff?: OrganizationHandoffInput;
+    organizationHandoffHandle?: OpaqueTargetHandle;
     report: DockerDeploymentReportInput;
     runMetadata?: DockerDeploymentRunMetadata;
     targetExecFile?: DockerTargetExecFile;
     targetTimeoutMs?: number;
 }) => Promise<string | null>;
+export interface ProbeDockerOrganizationReadinessInput {
+    dockerCommand?: string;
+    evidence: OrganizationReadinessEvidence;
+    execFile?: DockerProbeExecFile;
+    record: DeploymentRecord;
+    timeoutMs?: number;
+}
+/**
+ * Performs the single manager-owned inspection, public health checks, and
+ * bounded artifact reads needed to reconcile immutable compiler evidence.
+ * It deliberately returns a safe value only; upProject owns both persistence writes.
+ */
+export declare const probeDockerOrganizationReadiness: (input: ProbeDockerOrganizationReadinessInput) => Promise<OrganizationReadiness>;

package/dist/deployment/dockerManager.js

@@ -1,9 +1,29 @@
 import path from "node:path";
 import { normalizeProjectLabelSlug } from "../distribution/index.js";
+import { resolveNoopolisRunId } from "../runtime/index.js";
 import { SpawnfileError } from "../shared/index.js";
+import { inspectDockerDeployment } from "./dockerInspect.js";
 import { normalizeDeploymentName } from "./names.js";
+import { createDockerProbeGateway } from "./dockerProbeGateway.js";
+import { organizationReadinessFromProbeError, reconcileOrganizationReadiness } from "./organizationReady.js";
 import { resolveDockerDeploymentTarget } from "./target.js";
 import { writeDeploymentRecord } from "./record.js";
+import { createOrganizationHandoff } from "./organizationHandoffTypes.js";
+export const createDockerOrganizationHandoffSession = (input) => {
+    const organizationHandoff = createOrganizationHandoff(input.runId, input.organizationHandoff);
+    return Object.freeze({
+        authorityInput: Object.freeze({
+            bindingDigest: input.bindingDigest,
+            containerName: input.containerName,
+            deploymentLabels: input.deploymentLabels,
+            descriptorDigest: input.descriptorDigest,
+            handoff: organizationHandoff,
+            selectedTarget: input.selectedTarget,
+            selectedTargetReceiptDigest: input.selectedTargetReceiptDigest
+        }),
+        organizationHandoff
+    });
+};
 const resolveProjectSlug = (projectRoot) => {
     const base = path.basename(projectRoot).toLowerCase() === "spawnfile"
         ? path.basename(path.dirname(projectRoot))
@@ -24,13 +44,25 @@ export const createDockerDeploymentRecord = (input) => {
         manager: "docker",
         name,
         output_directory: path.resolve(input.outputDirectory),
+        ...(input.runId ? { run_id: input.runId } : {}),
+        ...(input.runId && input.organizationHandoff
+            ? { organization_handoff: createOrganizationHandoff(input.runId, input.organizationHandoff) }
+            : {}),
+        ...(input.runId && input.organizationHandoff && input.organizationHandoffHandle
+            ? { organization_handoff_handle: input.organizationHandoffHandle }
+            : {}),
         source: input.source ?? { kind: "project", root: path.resolve(input.projectRoot) },
         target: input.target,
         units: [
             {
                 container_id: input.runMetadata?.containerId ?? null,
                 container_name: input.containerName,
-                contains: input.nodes.map((node) => ({ id: node.id, kind: node.kind })),
+                contains: [
+                    ...input.nodes.map((node) => ({ id: node.id, kind: node.kind })),
+                    ...[...new Set(input.networkIds ?? [])]
+                        .sort()
+                        .map((id) => ({ id, kind: "network" }))
+                ],
                 id: createDockerDeploymentUnitId(name),
                 image_id: input.runMetadata?.imageId ?? null,
                 image_tag: input.imageTag,
@@ -60,9 +92,20 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
         deploymentName: input.invocation.deploymentName,
         envFilePath: input.envFilePath,
         imageTag: input.imageTag,
+        networkIds: input.report.container?.moltnet?.server_plans
+            .filter((server) => server.mode === "managed")
+            .map((server) => server.network_id),
         nodes: input.report.nodes,
         outputDirectory: input.outputDirectory,
+        ...(input.organizationHandoff ? { organizationHandoff: input.organizationHandoff } : {}),
+        ...(input.organizationHandoffHandle ? { organizationHandoffHandle: input.organizationHandoffHandle } : {}),
         projectRoot: input.report.root,
+        // Sourced from the host process env at record-write time, not the
+        // compile report: `spawnfile run`/`up --detach` always call
+        // ensureNoopolisRunId() before compiling (src/compiler/CLAUDE.md), so by
+        // the time this record is written the run id — if any — is already on
+        // process.env. A bare host env with no run id yields no `run_id` field.
+        runId: resolveNoopolisRunId(process.env),
         runMetadata: input.runMetadata,
         runtimeInstanceIds: input.report.container?.runtime_instances.map((instance) => instance.id) ?? [],
         target: await resolveDockerDeploymentTarget({
@@ -74,3 +117,77 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
         })
     });
 };
+const recordCorrelation = (record) => ({
+    compileFingerprint: record.compile_fingerprint,
+    deploymentName: record.name,
+    runId: record.run_id ?? null,
+    unitCount: record.units.length,
+    unitId: record.units[0]?.id ?? "invalid-unit"
+});
+/**
+ * Performs the single manager-owned inspection, public health checks, and
+ * bounded artifact reads needed to reconcile immutable compiler evidence.
+ * It deliberately returns a safe value only; upProject owns both persistence writes.
+ */
+export const probeDockerOrganizationReadiness = async (input) => {
+    const correlation = recordCorrelation(input.record);
+    try {
+        const inspections = await inspectDockerDeployment(input.record, {
+            dockerCommand: input.dockerCommand,
+            execFile: input.execFile,
+            timeoutMs: input.timeoutMs
+        });
+        const unit = input.record.units[0];
+        const inspected = unit ? inspections.get(unit.id) ?? null : null;
+        if (!unit || !inspected) {
+            return reconcileOrganizationReadiness({
+                evidence: input.evidence, inspection: null, probe: null, record: correlation
+            });
+        }
+        const gateway = createDockerProbeGateway(input.record, unit, {
+            dockerCommand: input.dockerCommand,
+            execFile: input.execFile,
+            inspection: inspected,
+            timeoutMs: input.timeoutMs
+        });
+        const inspection = await gateway.inspectUnit();
+        if (input.evidence.hasExternalMoltnet || !input.evidence.worldBindings) {
+            return reconcileOrganizationReadiness({
+                evidence: input.evidence, inspection, probe: null, record: correlation
+            });
+        }
+        const networks = [];
+        for (const network of input.evidence.networks) {
+            if (network.mode !== "managed" || network.internalPort === null) {
+                return reconcileOrganizationReadiness({
+                    evidence: input.evidence, inspection, probe: null, record: correlation
+                });
+            }
+            const health = await gateway.httpGet(network.internalPort, "/healthz");
+            if (!health.ok) {
+                return organizationReadinessFromProbeError(input.evidence, correlation, new Error(health.error ?? "probe unavailable"));
+            }
+            networks.push({
+                healthOk: health.ok,
+                id: network.id
+            });
+        }
+        const configs = new Map();
+        for (const network of input.evidence.networks) {
+            for (const node of network.nodes) {
+                const result = await gateway.exec(["cat", node.configPath]);
+                configs.set(node.configPath, result.stdout);
+            }
+        }
+        const bindings = await gateway.exec(["cat", input.evidence.worldBindings.artifactPath]);
+        return reconcileOrganizationReadiness({
+            evidence: input.evidence,
+            inspection,
+            probe: { configs, networks, worldBindings: bindings.stdout },
+            record: correlation
+        });
+    }
+    catch (error) {
+        return organizationReadinessFromProbeError(input.evidence, correlation, error);
+    }
+};

package/dist/deployment/dockerProbeGateway.js

@@ -19,6 +19,63 @@ const withDockerTarget = (record, args) => {
     }
     return args;
 };
+const imageRefForUnit = (unit) => unit.image_id
+    ? (/^[a-f0-9]{64}$/u.test(unit.image_id) ? `sha256:${unit.image_id}` : unit.image_id)
+    : unit.image_tag;
+const redactProbeText = (value, limit) => value
+    .replace(/\s+/gu, " ")
+    .replace(/(bearer|token|password|passwd|secret|authorization)[=: ]+(?:bearer[ ]+)?[^ ]+/giu, "$1=[redacted]")
+    .replace(/https?:\/\/[^ ]+/giu, "[url redacted]")
+    .slice(0, limit);
+const boundedProbeFailure = (error) => {
+    if (!error || typeof error !== "object")
+        return redactProbeText(String(error), 240) || "probe failed";
+    const candidate = error;
+    const hasStatus = typeof candidate.status === "number" || typeof candidate.status === "string";
+    const hasCode = typeof candidate.code === "number" || typeof candidate.code === "string";
+    const status = hasStatus
+        ? `status ${String(candidate.status)}`
+        : hasCode
+            ? `exit ${String(candidate.code)}`
+            : "failed";
+    const stderr = typeof candidate.stderr === "string"
+        ? redactProbeText(candidate.stderr, 240)
+        : "";
+    const message = typeof candidate.message === "string" ? redactProbeText(candidate.message, 160) : "";
+    if (error instanceof Error && !stderr)
+        return message || "probe failed";
+    if (stderr)
+        return `docker probe ${status}: ${stderr}`;
+    if (message)
+        return hasStatus || hasCode ? `docker probe ${status}: ${message}` : message;
+    return `docker probe ${status}`;
+};
+const parseCurlHttpOutput = (stdout) => {
+    const match = /\n(\d{3})$/u.exec(stdout);
+    if (!match || match.index === undefined) {
+        return { body: "", error: "malformed HTTP probe response", ok: false };
+    }
+    const status = Number(match[1]);
+    const body = stdout.slice(0, match.index);
+    return status >= 200 && status <= 299
+        ? { body, ok: true }
+        : { body, error: `HTTP ${status}`, ok: false };
+};
+const httpProbeArgs = (targetRef, imageRef, url) => [
+    "run",
+    "--rm",
+    "--network",
+    `container:${targetRef}`,
+    "--entrypoint",
+    "curl",
+    imageRef,
+    "-sS",
+    "--output",
+    "-",
+    "--write-out",
+    "\\n%{http_code}",
+    url
+];
 export const createDockerProbeGateway = (record, unit, options) => {
     const dockerCommand = options.dockerCommand ?? "docker";
     const runExec = options.execFile ?? execFile;
@@ -30,15 +87,17 @@ export const createDockerProbeGateway = (record, unit, options) => {
     return {
         exec,
         async httpGet(port, requestPath, headers = {}) {
+            if (Object.keys(headers).length > 0) {
+                return { body: "", error: "HTTP probe headers are forbidden", ok: false };
+            }
             const url = `http://127.0.0.1:${port}${requestPath.startsWith("/") ? requestPath : `/${requestPath}`}`;
             try {
-                const headerArgs = Object.entries(headers).flatMap(([name, value]) => ["-H", `${name}: ${value}`]);
-                const result = await exec(["curl", "-fsS", ...headerArgs, url]);
-                return { body: result.stdout, ok: true };
+                const targetRef = targetRefForUnit(unit);
+                const result = await runExec(dockerCommand, withDockerTarget(record, httpProbeArgs(targetRef, imageRefForUnit(unit), url)), { timeout });
+                return parseCurlHttpOutput(result.stdout);
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                return { body: "", error: message, ok: false };
+                return { body: "", error: boundedProbeFailure(error), ok: false };
             }
         },
         async inspectUnit() {

package/dist/deployment/dockerRecover.d.ts

@@ -0,0 +1,17 @@
+import type { DeploymentRecord } from "./record.js";
+import { type DockerTargetExecFile } from "./target.js";
+export interface RecoverDockerDeploymentRecordsOptions {
+    contains?: DeploymentRecord["units"][number]["contains"];
+    context: string;
+    dockerCommand?: string;
+    execFile?: DockerTargetExecFile;
+    outputDirectory: string;
+    projectLabel: string;
+    runtimeInstanceIds?: string[];
+    sourceRoot: string;
+    timeoutMs?: number;
+}
+export declare const recoverDockerDeploymentRecords: (options: RecoverDockerDeploymentRecordsOptions) => Promise<Array<{
+    path: string;
+    record: DeploymentRecord;
+}>>;

package/dist/deployment/dockerRecover.js

@@ -0,0 +1,137 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+import { dockerDeploymentLabelKeys } from "./dockerLabels.js";
+import { resolveDockerDeploymentTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const toStringOrNull = (value) => typeof value === "string" && value.length > 0 ? value : null;
+const labelsFrom = (inspection) => {
+    const labels = inspection.Config?.Labels;
+    if (!isRecord(labels)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(labels).filter((entry) => typeof entry[1] === "string"));
+};
+const withContext = (context, args) => [
+    "--context",
+    context,
+    ...args
+];
+const containerNameFrom = (inspection) => {
+    const name = toStringOrNull(inspection.Name);
+    return name ? name.replace(/^\//u, "") : null;
+};
+const parseInspections = (stdout) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        throw new SpawnfileError("runtime_error", `Unable to parse recovered Docker container inspection: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return Array.isArray(parsed) ? parsed.filter(isRecord) : [];
+};
+const deploymentNameFor = (labels) => labels[dockerDeploymentLabelKeys.deployment] ?? null;
+const buildUnit = (inspection, labels, contains, runtimeInstanceIds) => {
+    const unitId = labels[dockerDeploymentLabelKeys.unit];
+    const imageTag = toStringOrNull(inspection.Config?.Image);
+    if (!unitId || !imageTag) {
+        return null;
+    }
+    return {
+        container_id: toStringOrNull(inspection.Id),
+        container_name: containerNameFrom(inspection),
+        contains,
+        id: unitId,
+        image_id: toStringOrNull(inspection.Image),
+        image_tag: imageTag,
+        kind: "container",
+        runtime_instances: runtimeInstanceIds
+    };
+};
+const groupByDeployment = (inspections, options, target) => {
+    const records = new Map();
+    const unitsByDeployment = new Map();
+    const contains = options.contains ?? [];
+    const runtimeInstanceIds = options.runtimeInstanceIds ?? [];
+    for (const inspection of inspections) {
+        const labels = labelsFrom(inspection);
+        if (labels[dockerDeploymentLabelKeys.project] !== options.projectLabel) {
+            continue;
+        }
+        const name = deploymentNameFor(labels);
+        const compileFingerprint = labels[dockerDeploymentLabelKeys.compileFingerprint];
+        const runId = labels[dockerDeploymentLabelKeys.runId];
+        if (!name || !compileFingerprint) {
+            continue;
+        }
+        const unit = buildUnit(inspection, labels, contains, runtimeInstanceIds);
+        if (!unit) {
+            continue;
+        }
+        const seenUnits = unitsByDeployment.get(name) ?? new Set();
+        if (seenUnits.has(unit.id)) {
+            throw new SpawnfileError("validation_error", `Recovered deployment "${name}" has multiple containers for unit "${unit.id}"`);
+        }
+        seenUnits.add(unit.id);
+        unitsByDeployment.set(name, seenUnits);
+        const existing = records.get(name);
+        if (existing
+            && (existing.compile_fingerprint !== compileFingerprint
+                || existing.run_id !== runId)) {
+            throw new SpawnfileError("validation_error", `Recovered deployment "${name}" has inconsistent identity labels`);
+        }
+        const record = existing ?? {
+            auth_profile: null,
+            compile_fingerprint: compileFingerprint,
+            created_at: toStringOrNull(inspection.Created) ?? new Date().toISOString(),
+            manager: "docker",
+            name,
+            output_directory: options.outputDirectory,
+            ...(runId ? { run_id: runId } : {}),
+            source: { kind: "project", root: options.sourceRoot },
+            target,
+            units: [],
+            version: "spawnfile.deployment.v2"
+        };
+        record.units.push(unit);
+        records.set(name, record);
+    }
+    return [...records.values()]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((record) => ({
+        path: `docker-context://${options.context}/${record.name}`,
+        record: {
+            ...record,
+            units: [...record.units].sort((left, right) => left.id.localeCompare(right.id))
+        }
+    }));
+};
+export const recoverDockerDeploymentRecords = async (options) => {
+    const resolved = {
+        dockerCommand: options.dockerCommand ?? "docker",
+        execFile: options.execFile ?? execFile,
+        timeoutMs: options.timeoutMs ?? 10_000
+    };
+    const target = await resolveDockerDeploymentTarget({
+        context: options.context,
+        dockerCommand: resolved.dockerCommand,
+        execFile: resolved.execFile,
+        timeoutMs: resolved.timeoutMs
+    });
+    const { stdout: listStdout } = await resolved.execFile(resolved.dockerCommand, withContext(options.context, [
+        "ps",
+        "-a",
+        "--filter",
+        `label=${dockerDeploymentLabelKeys.version}`,
+        "--format",
+        "{{.ID}}"
+    ]), { timeout: resolved.timeoutMs });
+    const ids = listStdout.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
+    if (ids.length === 0) {
+        return [];
+    }
+    const { stdout } = await resolved.execFile(resolved.dockerCommand, withContext(options.context, ["inspect", ...ids]), { timeout: resolved.timeoutMs });
+    return groupByDeployment(parseInspections(stdout), options, target);
+};

package/dist/deployment/dockerTeardown.d.ts

@@ -0,0 +1,32 @@
+import type { DeploymentRecord } from "./record.js";
+/** Same injectable exec shape as `artifactsExportDocker.ts`/`dockerInspect.ts` — real
+ * Docker calls are the default, tests inject a fake. */
+export type DockerTeardownExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface DockerTeardownRunnerOptions {
+    dockerCommand: string;
+    execFile: DockerTeardownExecFile;
+    timeoutMs: number;
+}
+export interface DockerRemovalOutcome {
+    error: string | null;
+    removed: boolean;
+}
+/**
+ * `docker rm -f <containerRef>` — force-removes a container whether it is running or
+ * already stopped. A container Docker reports as already gone ("No such container")
+ * counts as removed: `spawnfile down` is idempotent (calling it twice, or after the
+ * container died on its own, is a success, not a partial failure).
+ */
+export declare const removeDockerContainer: (target: DeploymentRecord["target"], containerRef: string, options: DockerTeardownRunnerOptions) => Promise<DockerRemovalOutcome>;
+/**
+ * `docker volume rm -f <volumeName>` — only called when the caller explicitly opts into
+ * volume removal (`spawnfile down --volumes`; the default is to retain volumes). A volume
+ * Docker reports as already gone ("No such volume") also counts as removed.
+ */
+export declare const removeDockerVolume: (target: DeploymentRecord["target"], volumeName: string, options: DockerTeardownRunnerOptions) => Promise<DockerRemovalOutcome>;
+export declare const defaultDockerTeardownExecFile: DockerTeardownExecFile;

package/dist/deployment/dockerTeardown.js

@@ -0,0 +1,61 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { dockerContextNameForTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const withDockerTarget = (target, args) => {
+    const context = dockerContextNameForTarget(target);
+    if (context) {
+        return ["--context", context, ...args];
+    }
+    if (target.kind === "host") {
+        return ["--host", target.value, ...args];
+    }
+    return args;
+};
+const toErrorMessage = (error) => {
+    if (typeof error === "object" && error !== null && "stderr" in error) {
+        const stderr = error.stderr;
+        if (typeof stderr === "string" && stderr.length > 0) {
+            return stderr.trim();
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+};
+/**
+ * `docker rm -f <containerRef>` — force-removes a container whether it is running or
+ * already stopped. A container Docker reports as already gone ("No such container")
+ * counts as removed: `spawnfile down` is idempotent (calling it twice, or after the
+ * container died on its own, is a success, not a partial failure).
+ */
+export const removeDockerContainer = async (target, containerRef, options) => {
+    try {
+        await options.execFile(options.dockerCommand, withDockerTarget(target, ["rm", "-f", containerRef]), { timeout: options.timeoutMs });
+        return { error: null, removed: true };
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        if (/No such container/i.test(message)) {
+            return { error: null, removed: true };
+        }
+        return { error: message, removed: false };
+    }
+};
+/**
+ * `docker volume rm -f <volumeName>` — only called when the caller explicitly opts into
+ * volume removal (`spawnfile down --volumes`; the default is to retain volumes). A volume
+ * Docker reports as already gone ("No such volume") also counts as removed.
+ */
+export const removeDockerVolume = async (target, volumeName, options) => {
+    try {
+        await options.execFile(options.dockerCommand, withDockerTarget(target, ["volume", "rm", "-f", volumeName]), { timeout: options.timeoutMs });
+        return { error: null, removed: true };
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        if (/No such volume/i.test(message)) {
+            return { error: null, removed: true };
+        }
+        return { error: message, removed: false };
+    }
+};
+export const defaultDockerTeardownExecFile = execFile;

package/dist/deployment/downDeployment.d.ts

@@ -0,0 +1,34 @@
+import { type DeploymentLifecycleCorrelation } from "./deploymentLifecycleCorrelation.js";
+import { type DockerTeardownExecFile } from "./dockerTeardown.js";
+import { type DownReceipt } from "./downReceiptTypes.js";
+export interface DownDeploymentOptions {
+    /** Where the deployment record + compile report already live (the compile's own
+     * `--out` directory) — same convention as `exportRunArtifacts`'s `compiledOutputDirectory`. */
+    compiledOutputDirectory: string;
+    deploymentName: string;
+    dockerCommand?: string;
+    execFile?: DockerTeardownExecFile;
+    /** Auto-runs `spawnfile artifacts export` to this directory before tearing down, when
+     * this run has no export-index yet. Mutually satisfying with `force` — either one
+     * clears the export-before-teardown guard, `exportTo` by doing the export, `force` by
+     * deliberately skipping it. */
+    exportTo?: string;
+    /** Deliberately discards un-exported artifacts and proceeds without exporting. */
+    force?: boolean;
+    readerImage?: string;
+    /** Also removes this deployment's named volumes. Default: retain (see CLAUDE.md's
+     * folder rule — this is the only reversible-by-default lifecycle boundary spawnfile
+     * has: containers are cheap to recreate, the durable stores are not). */
+    removeVolumes?: boolean;
+    expectedLifecycleCorrelation?: DeploymentLifecycleCorrelation;
+    timeoutMs?: number;
+}
+/**
+ * `spawnfile down` — record-driven teardown: resolves the deployment record, enforces the
+ * export-before-teardown invariant, `docker rm -f`s every recorded container unit, and
+ * (only with `--volumes`) removes named volumes. Always returns a `spawnfile.down-
+ * receipt.v1`, even when some units/volumes failed to remove (`errors` carries the
+ * per-item failures; a partial failure is never silently swallowed, but it also never
+ * stops the rest of the teardown from being attempted).
+ */
+export declare const downDeployment: (options: DownDeploymentOptions) => Promise<DownReceipt>;