spawnfile 0.1.14 → 0.1.18

package/dist/recording/read.js

@@ -0,0 +1,61 @@
+import { StringDecoder } from "node:string_decoder";
+import { z } from "zod";
+// Daimon's generated organization image uses its Node standalone base (runtime metadata),
+// and runs the Node daimon-runtime launcher. No optional container executable is required.
+const readChunkScript = `
+const fs = require('node:fs');
+try {
+  const fd = fs.openSync(process.argv[1], 'r');
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) throw {code:'NOT_REGULAR_FILE'};
+    const bytes = Buffer.alloc(Number(process.argv[3]));
+    const count = fs.readSync(fd, bytes, 0, bytes.length, Number(process.argv[2]));
+    process.stdout.write(JSON.stringify({size:stat.size, identity:stat.dev+':'+stat.ino, data:bytes.subarray(0,count).toString('base64')}));
+  } finally { fs.closeSync(fd); }
+} catch (error) {
+  if (error.code === 'ENOENT') process.stdout.write('null');
+  else { process.stderr.write(String(error.code || 'READ_FAILED')); process.exitCode = 1; }
+}`;
+const chunkSchema = z.object({
+    size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), identity: z.string().min(1),
+    data: z.string().regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u)
+}).strict().nullable();
+/** Each exec response is bounded (base64 adds 1/3); decode UTF-8 across byte boundaries.
+ * Pin the initial length/inode so appends cannot make sync chase a growing ledger forever. */
+export const readRecordingJsonl = async (exec, file, parser, chunkBytes = 256 * 1024) => {
+    const decoder = new StringDecoder("utf8");
+    let offset = 0, length, identity;
+    try {
+        if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0 || chunkBytes > 256 * 1024)
+            throw new Error("Invalid recording chunk size");
+        do {
+            const count = Math.min(chunkBytes, length === undefined ? chunkBytes : length - offset);
+            const { stdout } = await exec(["node", "-e", readChunkScript, file, String(offset), String(count)]);
+            const chunk = chunkSchema.parse(JSON.parse(stdout));
+            if (chunk === null) {
+                if (length !== undefined)
+                    throw new Error("Runtime file disappeared during read");
+                return { ...parser.finish(), missing: true };
+            }
+            length ??= chunk.size;
+            identity ??= chunk.identity;
+            if (identity !== chunk.identity || chunk.size < length)
+                throw new Error("Runtime file replaced or truncated during read");
+            const bytes = Buffer.from(chunk.data, "base64");
+            if (bytes.length > count || bytes.length < Math.min(count, length - offset))
+                throw new Error("Incomplete runtime file chunk");
+            const bounded = bytes.subarray(0, length - offset);
+            parser.write(decoder.write(bounded));
+            offset += bounded.length;
+        } while (offset < length);
+        parser.write(decoder.end());
+        return parser.finish();
+    }
+    catch (error) {
+        // The remote script emits codes only. Do not expose raw exec messages or partial stdout.
+        const reason = error instanceof Error && /^(?:Invalid recording|Runtime file|Incomplete runtime)/u.test(error.message)
+            ? error.message : "Runtime file exec or chunk decoding failed";
+        return { entries: [], errors: [], failure: reason };
+    }
+};

package/dist/recording/store.d.ts

@@ -0,0 +1,10 @@
+import type { MomentRecord, WakeMomentRow } from "./types.js";
+/** Project records share a directory, so each gets its own state subdirectory. */
+export declare const deploymentMomentsDirectory: (recordPath: string) => string;
+export declare const momentFileName: (row: WakeMomentRow) => string;
+export declare const withMomentStore: <T>(recordPath: string, slug: string, action: (directory: string) => Promise<T>) => Promise<T>;
+/** Caller holds the store lock. Existing records are never replaced, including non-exact ones. */
+export declare const writeMomentRecord: (directory: string, record: MomentRecord, row: WakeMomentRow) => Promise<boolean>;
+export declare const newestMomentInstant: (directory: string, agentId: string) => Promise<number>;
+/** Retention reads the recorded instant, never mtime; preserve all newest-instant ties. */
+export declare const pruneMomentRecords: (directory: string, agentId: string, now: Date, keepMs: number) => Promise<void>;

package/dist/recording/store.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import path from "node:path";
+import { acquirePidLock } from "../deployment/pidLock.js";
+import { syncDirectory, writeDurableFile } from "../filesystem/index.js";
+/** Project records share a directory, so each gets its own state subdirectory. */
+export const deploymentMomentsDirectory = (recordPath) => path.join(path.dirname(recordPath), ...(path.basename(recordPath) === "record.json" ? [] : [path.basename(recordPath, ".json")]), "moments");
+/** JSON object keys are sorted recursively; array order and all row values remain significant. */
+const canonicalJson = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.entries(value)
+            .filter(([, entry]) => entry !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+    return JSON.stringify(value);
+};
+export const momentFileName = (row) => {
+    const { started_at: startedAt, execution_id: executionId } = row;
+    const compact = new Date(startedAt).toISOString().replace(/[-:.]/gu, "");
+    const safeId = /^[A-Za-z0-9._-]{1,128}$/u.test(executionId)
+        ? executionId : `sha256-${createHash("sha256").update(executionId).digest("hex")}`;
+    const attempt = createHash("sha256").update(canonicalJson(row)).digest("hex").slice(0, 12);
+    return `${compact}-${safeId}-${attempt}.json`;
+};
+const ensurePrivateDirectory = async (directory) => {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`Moment directory is not a real directory: ${directory}`);
+};
+export const withMomentStore = async (recordPath, slug, action) => {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(slug))
+        throw new Error("Unsafe recording agent slug");
+    const root = deploymentMomentsDirectory(recordPath);
+    await ensurePrivateDirectory(root);
+    const directory = path.join(root, slug);
+    await ensurePrivateDirectory(directory);
+    const release = await acquirePidLock(path.join(directory, ".sync.lock"));
+    try {
+        return await action(directory);
+    }
+    finally {
+        await release();
+    }
+};
+/** Caller holds the store lock. Existing records are never replaced, including non-exact ones. */
+export const writeMomentRecord = async (directory, record, row) => {
+    const file = path.join(directory, momentFileName(row));
+    try {
+        const stat = await lstat(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`Moment is not a regular file: ${file}`);
+        const existing = JSON.parse(await readFile(file, "utf8"));
+        if (existing.agent !== record.agent || existing.wake?.executionId !== record.wake.executionId
+            || existing.wake?.startedAt !== record.wake.startedAt)
+            throw new Error(`Moment filename collision: ${file}`);
+        return false;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await writeDurableFile(file, `${JSON.stringify(record, null, 2)}\n`);
+    return true;
+};
+const storedMoments = async (directory, agentId) => {
+    const candidates = [];
+    for (const name of (await readdir(directory)).sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const file = path.join(directory, name), stat = await lstat(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`Moment is not a regular file: ${file}`);
+        const record = JSON.parse(await readFile(file, "utf8"));
+        const started = Date.parse(record.wake?.startedAt);
+        if (record.version !== "spawnfile.moment-record.v1" || record.agent !== agentId || !Number.isFinite(started)) {
+            throw new Error(`Invalid retained moment: ${file}`);
+        }
+        candidates.push({ file, started });
+    }
+    return candidates;
+};
+export const newestMomentInstant = async (directory, agentId) => (await storedMoments(directory, agentId)).reduce((latest, item) => Math.max(latest, item.started), -Infinity);
+/** Retention reads the recorded instant, never mtime; preserve all newest-instant ties. */
+export const pruneMomentRecords = async (directory, agentId, now, keepMs) => {
+    const candidates = await storedMoments(directory, agentId);
+    const newest = candidates.reduce((latest, item) => Math.max(latest, item.started), -Infinity);
+    const expired = candidates.filter((item) => item.started < newest && item.started < now.getTime() - keepMs);
+    for (const item of expired)
+        await unlink(item.file);
+    if (expired.length)
+        await syncDirectory(directory);
+};

package/dist/recording/sync.d.ts

@@ -0,0 +1,24 @@
+import { type DeployResources } from "../deployment/index.js";
+import type { RecordingAgentReport } from "../report/index.js";
+import type { UsageLedgerExec } from "../runtime/usageLedgerRead.js";
+import type { FeedLanding } from "../volume/index.js";
+import { type RecordingHistory } from "./history.js";
+export interface SyncMomentRecordsOptions {
+    recordPath: string;
+    agents: readonly RecordingAgentReport[];
+    execForAgent: (agent: RecordingAgentReport) => UsageLedgerExec;
+    readFeedHistory: (feed: RecordingAgentReport["feeds"][number]) => Promise<RecordingHistory<FeedLanding>>;
+    readDeployHistory?: (recordPath: string) => RecordingHistory<DeployResources> | Promise<RecordingHistory<DeployResources>>;
+    readChunkBytes?: number;
+    now?: () => Date;
+}
+export interface SyncMomentRecordsResult {
+    written: number;
+    skipped: number;
+    nonExact: number;
+    /** Operational errors cause nonzero exit; data errors only qualify exactness. */
+    failures: string[];
+    warnings: string[];
+}
+/** Artifact egress only. No turn, snapshot copy, network-history fetch, or source resolution. */
+export declare const syncMomentRecords: (options: SyncMomentRecordsOptions) => Promise<SyncMomentRecordsResult>;

package/dist/recording/sync.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { deployResourcesAt } from "../deployment/index.js";
+import { composeMomentRecord } from "./compose.js";
+import { readRecordingDeployHistory, recordingHistoryAt } from "./history.js";
+import { createMemoryLedgerParser, createWakeMomentsParser } from "./parse.js";
+import { readRecordingJsonl } from "./read.js";
+import { newestMomentInstant, pruneMomentRecords, withMomentStore, writeMomentRecord } from "./store.js";
+/** Artifact egress only. No turn, snapshot copy, network-history fetch, or source resolution. */
+export const syncMomentRecords = async (options) => {
+    const result = { written: 0, skipped: 0, nonExact: 0, failures: [], warnings: [] };
+    if (!options.agents.length)
+        return result;
+    const now = (options.now ?? (() => new Date()))();
+    if (!Number.isFinite(now.getTime()))
+        throw new Error("Recording requires a valid clock");
+    const deploy = await (options.readDeployHistory ?? readRecordingDeployHistory)(options.recordPath);
+    const deployTail = deploy.entries.at(-1);
+    const deployPendingSince = deployTail ? Date.parse(deployTail.activated_at) : -Infinity;
+    const currentDeployment = deployResourcesAt(deploy.entries, options.recordPath, now);
+    for (const agent of options.agents) {
+        try {
+            if (!Number.isSafeInteger(agent.keep_ms) || agent.keep_ms <= 0)
+                throw new Error("Invalid recording retention");
+            const exec = options.execForAgent(agent);
+            const directories = new Set([agent.directory, ...deploy.entries
+                    .filter((entry) => entry.deployment_id === path.resolve(options.recordPath))
+                    .flatMap((entry) => entry.recording_agents ?? []).filter((entry) => entry.node_id === agent.node_id)
+                    .map((entry) => entry.directory)]);
+            const errors = deploy.errors.map((error) => `Deploy history: ${error}`);
+            const rowsBySlug = new Map();
+            rowsBySlug.set(agent.slug, []);
+            for (const directory of directories) {
+                // Retention still runs when a log has become empty since the previous sync.
+                rowsBySlug.set(path.posix.basename(directory), rowsBySlug.get(path.posix.basename(directory)) ?? []);
+                const wake = await readRecordingJsonl(exec, path.posix.join(directory, "wake-moments.jsonl"), createWakeMomentsParser(), options.readChunkBytes);
+                if (wake.failure)
+                    throw new Error(`Wake moments unreadable: ${wake.failure}`);
+                errors.push(...wake.errors);
+                for (const row of wake.entries) {
+                    if (row.agent_id !== agent.node_id) {
+                        errors.push(`Foreign wake row for ${row.agent_id}`);
+                        continue;
+                    }
+                    const historical = recordingHistoryAt(deploy.entries, options.recordPath, row.started_at, agent.node_id).agent;
+                    const slug = historical?.slug ?? agent.slug;
+                    const rows = rowsBySlug.get(slug) ?? [];
+                    rows.push({ row, directory });
+                    rowsBySlug.set(slug, rows);
+                }
+            }
+            const memoryCache = Object.create(null);
+            const feedCache = new Map();
+            result.warnings.push(...errors.map((error) => `${agent.node_id}: ${error}`));
+            for (const [slug, rows] of rowsBySlug)
+                await withMomentStore(options.recordPath, slug, async (directory) => {
+                    const newest = rows.reduce((latest, { row }) => Math.max(latest, Date.parse(row.started_at)), await newestMomentInstant(directory, agent.node_id));
+                    for (const { row, directory: sourceDirectory } of rows) {
+                        const started = Date.parse(row.started_at);
+                        // Do not recreate already-pruned attempts on every sync while Daimon retains its row log.
+                        if (started < now.getTime() - agent.keep_ms && started < newest) {
+                            result.skipped += 1;
+                            continue;
+                        }
+                        const { agent: historical, deployment } = recordingHistoryAt(deploy.entries, options.recordPath, row.started_at, agent.node_id);
+                        const rowErrors = [...errors];
+                        if (deploy.publicationPending && started >= deployPendingSince)
+                            rowErrors.push("Deploy history publication pending");
+                        if (historical && historical.directory !== sourceDirectory)
+                            rowErrors.push("Wake row directory differs from activation recording facts");
+                        const feedLandings = Object.create(null);
+                        for (const feed of historical?.feeds ?? []) {
+                            const key = JSON.stringify([feed.id, feed.volume_name]);
+                            if (!feedCache.has(key)) {
+                                try {
+                                    feedCache.set(key, await options.readFeedHistory(feed));
+                                }
+                                catch {
+                                    feedCache.set(key, { entries: [], errors: [`cannot resolve or read host landing history for volume ${feed.volume_name}`] });
+                                }
+                            }
+                            const history = feedCache.get(key);
+                            feedLandings[feed.id] = history.entries.filter((entry) => entry.resource === feed.id && entry.volume === feed.volume_name);
+                            const tail = history.entries.at(-1);
+                            const pendingSince = tail ? Date.parse(tail.landed_at) : -Infinity;
+                            if (history.publicationPending && started >= pendingSince)
+                                rowErrors.push(`Feed ${feed.id}: history publication pending`);
+                            rowErrors.push(...history.errors.map((error) => `Feed ${feed.id}: ${error}`));
+                        }
+                        const memoryLedgers = Object.create(null);
+                        for (const bank of historical?.memory ?? []) {
+                            if (bank.ledger_path === null)
+                                continue;
+                            const current = agent.memory.some((entry) => entry.id === bank.id && entry.declared_by === bank.declared_by
+                                && entry.ledger_path === bank.ledger_path);
+                            // Older facts do not carry a physical volume ID. A different report cannot
+                            // establish that today's readable path still names the historical bank.
+                            if (!current || deployment?.report_sha256 !== currentDeployment?.report_sha256) {
+                                memoryLedgers[bank.ledger_path] = { entries: [], errors: ["Historical bank identity or mount cannot be verified in the current deployment"] };
+                                continue;
+                            }
+                            if (!memoryCache[bank.ledger_path]) {
+                                const ledger = await readRecordingJsonl(exec, bank.ledger_path, createMemoryLedgerParser(), options.readChunkBytes);
+                                memoryCache[bank.ledger_path] = ledger.failure || ledger.missing
+                                    ? { entries: [], errors: [`Ledger unreadable: ${ledger.failure ?? "runtime file is absent"}`] } : ledger;
+                            }
+                            memoryLedgers[bank.ledger_path] = memoryCache[bank.ledger_path];
+                        }
+                        const record = composeMomentRecord({ row, agentNodeId: agent.node_id, deploymentRecordPath: options.recordPath,
+                            feedLandings, deployResources: deploy.entries, memoryLedgers, errors: rowErrors, recordedAt: now.toISOString() });
+                        if (await writeMomentRecord(directory, record, row)) {
+                            result.written += 1;
+                            if (!record.exact)
+                                result.nonExact += 1;
+                        }
+                        else
+                            result.skipped += 1;
+                    }
+                    await pruneMomentRecords(directory, agent.node_id, now, agent.keep_ms);
+                });
+        }
+        catch (error) {
+            result.failures.push(`${agent.node_id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return result;
+};

package/dist/recording/types.d.ts

@@ -0,0 +1,45 @@
+import type { DeployResources } from "../deployment/index.js";
+import type { FeedLanding } from "../volume/index.js";
+export declare const WAKE_MOMENT_VERSION = "noopolis.daimon.wake-moment.v1";
+export declare const MOMENT_RECORD_VERSION = "spawnfile.moment-record.v1";
+/** The public, data-only row written by Daimon before each turn attempt. */
+export interface WakeMomentRow {
+    version: typeof WAKE_MOMENT_VERSION;
+    agent_id: string;
+    execution_id: string;
+    started_at: string;
+    deliveries: {
+        acceptance_id: string;
+        delivery_id: string;
+        kind: string;
+        occurred_at: string;
+    }[];
+    snapshots: {
+        id: string;
+        snapshot: string;
+        files: number;
+        copied: number;
+        linked: number;
+        skipped: number;
+    }[];
+    error?: string;
+}
+export interface MemoryLedgerEntry {
+    seq: number;
+    createdAt: string;
+}
+export interface MemoryLedgerRead {
+    entries: readonly MemoryLedgerEntry[];
+    errors?: readonly string[];
+}
+export interface ComposeMomentRecordInput {
+    row: WakeMomentRow;
+    agentNodeId: string;
+    deploymentRecordPath: string;
+    feedLandings: Readonly<Record<string, readonly FeedLanding[]>>;
+    deployResources: readonly DeployResources[];
+    memoryLedgers: Readonly<Record<string, MemoryLedgerRead>>;
+    errors?: readonly string[];
+    recordedAt: string;
+}
+export type { MomentRecord } from "./moment.js";

package/dist/recording/types.js

@@ -0,0 +1,2 @@
+export const WAKE_MOMENT_VERSION = "noopolis.daimon.wake-moment.v1";
+export const MOMENT_RECORD_VERSION = "spawnfile.moment-record.v1";

package/dist/release/drainControl.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The running organization's control plane, reached the way every other
+ * Spawnfile probe reaches a container's loopback: an ephemeral helper from the
+ * same image inside the target's network namespace. The bearer token goes to
+ * curl on stdin (`-H @-`), never on a command line another host process could
+ * read.
+ */
+export interface RuntimeControlTarget {
+    containerRef: string;
+    dockerArgs: readonly string[];
+    dockerCommand: string;
+    imageRef: string;
+    token: string;
+}
+export interface ControlResponse {
+    body: string;
+    status: number;
+}
+export type ControlCall = (target: RuntimeControlTarget, method: "GET" | "POST", route: string) => Promise<ControlResponse>;
+export declare const CONTROL_CALL_TIMEOUT_MS = 60000;
+export declare const controlHelperArgs: (target: RuntimeControlTarget, method: "GET" | "POST", route: string) => string[];
+export declare const parseHelperOutput: (stdout: string) => ControlResponse;
+export declare const helperControlCall: ControlCall;
+export type DrainState = "draining" | "drained" | null;
+export interface Availability {
+    drain: DrainState;
+    state: string;
+}
+/** The parts of `noopolis.daimon.work-availability.v1` a release reads. */
+export declare const parseAvailability: (response: ControlResponse, route: string) => Availability;
+export declare const requestDrain: (target: RuntimeControlTarget, call?: ControlCall) => Promise<Availability>;
+export declare const requestResume: (target: RuntimeControlTarget, call?: ControlCall) => Promise<Availability>;
+export interface WaitForDrainedOptions {
+    call?: ControlCall;
+    now?: () => number;
+    pollMs: number;
+    signal?: AbortSignal;
+    sleep?: (ms: number) => Promise<void>;
+    timeoutMs: number;
+}
+export type DrainWait = {
+    drained: true;
+    waitedMs: number;
+} | {
+    drained: false;
+    reason: "interrupted" | "timeout";
+    waitedMs: number;
+};
+/**
+ * Polls until no turn is running or admitted ("drained"), or the bound runs
+ * out. Running turns are never touched: on timeout the caller abandons the
+ * release and resumes; nothing here can stop a turn.
+ */
+export declare const waitForDrained: (target: RuntimeControlTarget, options: WaitForDrainedOptions) => Promise<DrainWait>;

package/dist/release/drainControl.js

@@ -0,0 +1,137 @@
+import { spawn } from "node:child_process";
+import { DAIMON_CONTROL_PORT } from "../runtime/daimon/config.js";
+import { ReleaseError } from "./types.js";
+export const CONTROL_CALL_TIMEOUT_MS = 60_000;
+const MAX_CONTROL_OUTPUT_BYTES = 1024 * 1024;
+export const controlHelperArgs = (target, method, route) => [
+    ...target.dockerArgs,
+    "run", "--rm", "-i", "--pull", "never",
+    "--network", `container:${target.containerRef}`,
+    "--entrypoint", "curl",
+    target.imageRef,
+    "-sS", "--max-time", "15", "-X", method, "-H", "@-",
+    "--output", "-", "--write-out", "\\n%{http_code}",
+    `http://127.0.0.1:${DAIMON_CONTROL_PORT}${route}`
+];
+const redact = (text, token) => (token ? text.split(token).join("[redacted]") : text).replace(/\s+/gu, " ").slice(0, 240);
+export const parseHelperOutput = (stdout) => {
+    const match = /\n(\d{3})$/u.exec(stdout);
+    if (!match || match.index === undefined) {
+        throw new ReleaseError("drain-failed", "the runtime control helper returned no HTTP status");
+    }
+    return { body: stdout.slice(0, match.index), status: Number(match[1]) };
+};
+export const helperControlCall = (target, method, route) => new Promise((resolve, reject) => {
+    const child = spawn(target.dockerCommand, controlHelperArgs(target, method, route), {
+        stdio: ["pipe", "pipe", "pipe"]
+    });
+    const out = [];
+    let bytes = 0;
+    let stderr = "";
+    let settled = false;
+    const finish = (error, value) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (error)
+            reject(error);
+        else
+            resolve(value);
+    };
+    const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        finish(new ReleaseError("drain-failed", `runtime control ${method} ${route} timed out`));
+    }, CONTROL_CALL_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_CONTROL_OUTPUT_BYTES) {
+            child.kill("SIGKILL");
+            finish(new ReleaseError("drain-failed", `runtime control ${method} ${route} answered more than the output bound`));
+            return;
+        }
+        out.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => { stderr = `${stderr}${chunk.toString("utf8")}`.slice(-2000); });
+    child.once("error", (error) => finish(new ReleaseError("drain-failed", `cannot start the runtime control helper: ${error.message}`)));
+    child.once("close", (code) => {
+        if (code !== 0) {
+            finish(new ReleaseError("drain-failed", `runtime control ${method} ${route} failed (exit ${code ?? "signal"}): ${redact(stderr, target.token)}`));
+            return;
+        }
+        try {
+            finish(null, parseHelperOutput(Buffer.concat(out).toString("utf8")));
+        }
+        catch (error) {
+            finish(error);
+        }
+    });
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(`Authorization: Bearer ${target.token}\n`);
+});
+/** The parts of `noopolis.daimon.work-availability.v1` a release reads. */
+export const parseAvailability = (response, route) => {
+    if (response.status === 404) {
+        throw new ReleaseError("drain-failed", `the running runtime has no ${route} control route; it predates reversible drain, so it cannot be released without killing turns`);
+    }
+    if (response.status === 401) {
+        throw new ReleaseError("drain-failed", `the runtime refused the control token on ${route}; SPAWNFILE_DAIMON_CONTROL_TOKEN in the env file must be the running deployment's token`);
+    }
+    if (response.status !== 200) {
+        throw new ReleaseError("drain-failed", `runtime control ${route} answered HTTP ${response.status}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(response.body);
+    }
+    catch {
+        throw new ReleaseError("drain-failed", `runtime control ${route} answered invalid JSON`);
+    }
+    const document = parsed;
+    if (document?.version !== "noopolis.daimon.work-availability.v1" || typeof document.state !== "string") {
+        throw new ReleaseError("drain-failed", `runtime control ${route} answered something other than a work-availability document`);
+    }
+    const drain = document.drain === undefined ? null : document.drain.state;
+    if (drain !== null && drain !== "draining" && drain !== "drained") {
+        throw new ReleaseError("drain-failed", `runtime control ${route} reported an unknown drain state`);
+    }
+    return { drain, state: document.state };
+};
+export const requestDrain = async (target, call = helperControlCall) => {
+    const availability = parseAvailability(await call(target, "POST", "/v2/drain"), "/v2/drain");
+    if (availability.drain === null) {
+        throw new ReleaseError("drain-failed", "the runtime accepted /v2/drain but does not report a drain; refusing to deploy over turns it may still admit");
+    }
+    return availability;
+};
+export const requestResume = async (target, call = helperControlCall) => {
+    const availability = parseAvailability(await call(target, "POST", "/v2/resume"), "/v2/resume");
+    if (availability.drain !== null) {
+        throw new ReleaseError("resume-failed", "the runtime answered /v2/resume but still reports a drain");
+    }
+    return availability;
+};
+/**
+ * Polls until no turn is running or admitted ("drained"), or the bound runs
+ * out. Running turns are never touched: on timeout the caller abandons the
+ * release and resumes; nothing here can stop a turn.
+ */
+export const waitForDrained = async (target, options) => {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const started = now();
+    for (;;) {
+        if (options.signal?.aborted)
+            return { drained: false, reason: "interrupted", waitedMs: now() - started };
+        const availability = parseAvailability(await (options.call ?? helperControlCall)(target, "GET", "/v2/availability"), "/v2/availability");
+        if (availability.drain === null) {
+            throw new ReleaseError("drain-failed", "the runtime stopped reporting the drain while a release was waiting on it (did it restart?)");
+        }
+        if (availability.drain === "drained")
+            return { drained: true, waitedMs: now() - started };
+        const remaining = options.timeoutMs - (now() - started);
+        if (remaining <= 0)
+            return { drained: false, reason: "timeout", waitedMs: now() - started };
+        await sleep(Math.min(options.pollMs, remaining));
+    }
+};

package/dist/release/drainPhase.d.ts

@@ -0,0 +1,37 @@
+import type { DockerDeploymentTarget } from "../deployment/index.js";
+import type { RuntimeControlTarget } from "./drainControl.js";
+import { type ReleasePaths } from "./ledger.js";
+import type { RunningUnit } from "./releaseDocker.js";
+import { type ReleaseDependencies, type ReleaseRequest } from "./releaseTypes.js";
+export declare const RELEASE_DRAIN_MARKER_VERSION: "spawnfile.release-drain.v1";
+/** Same precedence `up` applies: a process value overrides the env file. */
+export declare const resolveControlToken: (request: ReleaseRequest) => string | null;
+export declare const controlTargetFor: (request: ReleaseRequest, containerRef: string, imageRef: string) => RuntimeControlTarget;
+/** The same request, addressed at exactly this Docker daemon. */
+export declare const requestForTarget: (request: ReleaseRequest, target: DockerDeploymentTarget) => ReleaseRequest;
+export declare const clearDrainMarker: (paths: ReleasePaths) => Promise<void>;
+export declare const recoverInterruptedDrain: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths) => Promise<boolean>;
+export type DrainOutcome = {
+    drainMs: number;
+    kind: "drained";
+} | {
+    drainMs: number;
+    kind: "skipped";
+} | {
+    drainMs: number;
+    kind: "timeout";
+};
+/**
+ * Admission pauses, queued wakes stay queued, running turns finish. On a
+ * timeout or interruption the release is abandoned and admission resumed:
+ * nothing in this module, or anything it calls, stops a turn.
+ */
+export declare const drainForRelease: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, unit: RunningUnit | null) => Promise<DrainOutcome>;
+/** Resumes a container this release drained, keeping the marker if that fails. */
+export declare const resumeDrained: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, unit: RunningUnit) => Promise<void>;
+/**
+ * After a failed deploy, whatever container now holds the name is either the
+ * restored previous one (restarted, so it admits) or the original, still
+ * drained because the deploy failed before touching it. Resume either way.
+ */
+export declare const resumeAfterFailedDeploy: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, containerName: string) => Promise<void>;