@code-yeongyu/senpi 2026.9.27-4 → 2026.9.28-2

package/dist/modes/rpc/host-gc-evidence.js

@@ -0,0 +1,128 @@
+/**
+ * The evidence `host gc` needs before it may remove an endpoint: whether anything still runs behind
+ * it, and whether anything still answers on it. Each answer errs toward "alive" - a record that
+ * cannot be proven dead, a probe that neither connects nor is refused, a claim whose owner cannot be
+ * read - because the cost of keeping a dead directory is disk, and the cost of removing a live one
+ * is every session its host holds.
+ *
+ * Reading only: nothing here writes, unlinks or signals.
+ */
+import { lstat, readdir } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { basename, dirname, join } from "node:path";
+import { ProcessIdentityUnreadableError, parseDaemonPidFile, processMatchesPidFile, } from "../app-server/daemon/process.js";
+import { generationPaths } from "./host-daemon-paths.js";
+import { parseJson, readFileOrUndefined } from "./host-daemon-state.js";
+import { claimOwnerIsLive, readSessionPathClaims } from "./host-reservations.js";
+import { readSocketSecret, resolveSocketTransportAddress, socketSecretPath } from "./socket-transport.js";
+/** A connect that neither succeeds nor fails within this budget counts as an answer. */
+const SOCKET_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * The three-part test, in the order its answers are reported: (a) no generation pidfile names a live
+ * process - the pointer's generation included, since its record lives under `generations/` too - (b) no
+ * session-path claim has a live owner, (c) the public socket - and every `.next-*` successor bind beside
+ * it - refuses the connection or does not exist.
+ */
+export async function endpointInUse(paths, socket) {
+    if (await anyGenerationLive(paths))
+        return { inUse: "live_generation" };
+    for (const claim of await readSessionPathClaims(paths.reservationsDir)) {
+        if (await claimOwnerIsLive(claim.owner))
+            return { inUse: "live_claim" };
+    }
+    const silence = await socketSilence(socket);
+    if (silence === undefined)
+        return { inUse: "reachable" };
+    // A successor mid-handoff listens on `<socket>.next-<gen>` before it registers anywhere.
+    const successors = (await socketSiblings(socket)).filter((name) => name.startsWith(`${basename(socket)}.next-`));
+    for (const successor of successors) {
+        if ((await socketSilence(join(dirname(socket), successor))) === undefined)
+            return { inUse: "reachable" };
+    }
+    return { inUse: undefined, silence };
+}
+/** Every entry beside `socket` that belongs to it: `<name>.next-*` successor binds and `<name>.shield-*`. */
+export async function socketSiblings(socket) {
+    const name = basename(socket);
+    const entries = await readdir(dirname(socket)).catch(() => []);
+    return entries.filter((entry) => entry.startsWith(`${name}.next-`) || entry.startsWith(`${name}.shield-`));
+}
+/** EVERY generation, not only the pointer's: a predecessor draining after a handoff is still serving. */
+async function anyGenerationLive(paths) {
+    for (const instanceId of await readdir(paths.generationsDir).catch(() => [])) {
+        const record = generationRecord(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));
+        if (record !== undefined && (await recordIsLive(record)))
+            return true;
+    }
+    return false;
+}
+/**
+ * A pidfile's process, or nothing when it names none. A record whose identity guard does not parse
+ * still names a pid, and is read as unguarded rather than as absent: its process may be running.
+ */
+function generationRecord(text) {
+    if (text === undefined)
+        return undefined;
+    const record = parseDaemonPidFile(text);
+    if (record !== undefined)
+        return record;
+    const pid = parseJson(text)?.pid;
+    return typeof pid === "number" && Number.isInteger(pid) && pid > 0 ? { pid, processStartTime: null } : undefined;
+}
+/** Live and still the recorded process; a live pid whose identity cannot be read counts as live. */
+async function recordIsLive(record) {
+    try {
+        return await processMatchesPidFile(record);
+    }
+    catch (error) {
+        if (error instanceof ProcessIdentityUnreadableError)
+            return true;
+        throw error;
+    }
+}
+/**
+ * How the socket proved silent, or `undefined` when it did not: only ECONNREFUSED and ENOENT prove
+ * nobody listens. A connect that succeeds, times out or fails any other way is treated as an answer.
+ * ECONNREFUSED counts only when the entry IS a socket: Linux refuses a connect to a regular file the
+ * same way it refuses a dead socket, and a file named where the socket should be is not ours to unlink.
+ */
+async function socketSilence(socket) {
+    let secret;
+    if (process.platform === "win32") {
+        // The pipe name includes the secret; without one no client can reach the pipe either.
+        secret = await readSocketSecret(socketSecretPath(socket)).catch(() => undefined);
+        if (secret === undefined)
+            return "socket_absent";
+    }
+    return new Promise((resolveProbe) => {
+        const connection = createConnection(resolveSocketTransportAddress(socket, process.platform, secret));
+        const finish = (value) => {
+            clearTimeout(timeout);
+            connection.destroy();
+            resolveProbe(value);
+        };
+        const timeout = setTimeout(() => finish(undefined), SOCKET_PROBE_TIMEOUT_MS);
+        connection.once("connect", () => finish(undefined));
+        connection.once("error", (error) => {
+            if (error.code === "ECONNREFUSED")
+                void refusedBySocket(socket).then(finish);
+            else if (error.code === "ENOENT")
+                finish("socket_absent");
+            else
+                finish(undefined);
+        });
+    });
+}
+/** A refusal proves silence only from a socket entry; an entry of any other type is an answer. */
+async function refusedBySocket(socket) {
+    // Named pipes and abstract sockets have no filesystem entry to be of the wrong type.
+    if (process.platform === "win32" || socket.startsWith("\0"))
+        return "socket_refused";
+    try {
+        return (await lstat(socket)).isSocket() ? "socket_refused" : undefined;
+    }
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "ENOENT" ? "socket_absent" : undefined;
+    }
+}
+//# sourceMappingURL=host-gc-evidence.js.map

package/dist/modes/rpc/host-gc-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-gc-evidence.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-gc-evidence.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The evidence `host gc` needs before it may remove an endpoint: whether anything still runs behind\n * it, and whether anything still answers on it. Each answer errs toward \"alive\" - a record that\n * cannot be proven dead, a probe that neither connects nor is refused, a claim whose owner cannot be\n * read - because the cost of keeping a dead directory is disk, and the cost of removing a live one\n * is every session its host holds.\n *\n * Reading only: nothing here writes, unlinks or signals.\n */\nimport { lstat, readdir } from \"node:fs/promises\";\nimport { createConnection } from \"node:net\";\nimport { basename, dirname, join } from \"node:path\";\nimport {\n\ttype DaemonPidFile,\n\tProcessIdentityUnreadableError,\n\tparseDaemonPidFile,\n\tprocessMatchesPidFile,\n} from \"../app-server/daemon/process.ts\";\nimport { generationPaths, type HostDaemonDirectory } from \"./host-daemon-paths.ts\";\nimport { parseJson, readFileOrUndefined } from \"./host-daemon-state.ts\";\nimport { claimOwnerIsLive, readSessionPathClaims } from \"./host-reservations.ts\";\nimport { readSocketSecret, resolveSocketTransportAddress, socketSecretPath } from \"./socket-transport.ts\";\n\nexport type EndpointInUse = \"live_generation\" | \"live_claim\" | \"reachable\";\n\nexport type SocketSilence = \"socket_refused\" | \"socket_absent\";\n\n/** A connect that neither succeeds nor fails within this budget counts as an answer. */\nconst SOCKET_PROBE_TIMEOUT_MS = 2_000;\n\n/**\n * The three-part test, in the order its answers are reported: (a) no generation pidfile names a live\n * process - the pointer's generation included, since its record lives under `generations/` too - (b) no\n * session-path claim has a live owner, (c) the public socket - and every `.next-*` successor bind beside\n * it - refuses the connection or does not exist.\n */\nexport async function endpointInUse(\n\tpaths: HostDaemonDirectory,\n\tsocket: string,\n): Promise<{ readonly inUse: EndpointInUse } | { readonly inUse: undefined; readonly silence: SocketSilence }> {\n\tif (await anyGenerationLive(paths)) return { inUse: \"live_generation\" };\n\tfor (const claim of await readSessionPathClaims(paths.reservationsDir)) {\n\t\tif (await claimOwnerIsLive(claim.owner)) return { inUse: \"live_claim\" };\n\t}\n\tconst silence = await socketSilence(socket);\n\tif (silence === undefined) return { inUse: \"reachable\" };\n\t// A successor mid-handoff listens on `<socket>.next-<gen>` before it registers anywhere.\n\tconst successors = (await socketSiblings(socket)).filter((name) => name.startsWith(`${basename(socket)}.next-`));\n\tfor (const successor of successors) {\n\t\tif ((await socketSilence(join(dirname(socket), successor))) === undefined) return { inUse: \"reachable\" };\n\t}\n\treturn { inUse: undefined, silence };\n}\n\n/** Every entry beside `socket` that belongs to it: `<name>.next-*` successor binds and `<name>.shield-*`. */\nexport async function socketSiblings(socket: string): Promise<readonly string[]> {\n\tconst name = basename(socket);\n\tconst entries = await readdir(dirname(socket)).catch(() => [] as string[]);\n\treturn entries.filter((entry) => entry.startsWith(`${name}.next-`) || entry.startsWith(`${name}.shield-`));\n}\n\n/** EVERY generation, not only the pointer's: a predecessor draining after a handoff is still serving. */\nasync function anyGenerationLive(paths: HostDaemonDirectory): Promise<boolean> {\n\tfor (const instanceId of await readdir(paths.generationsDir).catch(() => [] as string[])) {\n\t\tconst record = generationRecord(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));\n\t\tif (record !== undefined && (await recordIsLive(record))) return true;\n\t}\n\treturn false;\n}\n\n/**\n * A pidfile's process, or nothing when it names none. A record whose identity guard does not parse\n * still names a pid, and is read as unguarded rather than as absent: its process may be running.\n */\nfunction generationRecord(text: string | undefined): DaemonPidFile | undefined {\n\tif (text === undefined) return undefined;\n\tconst record = parseDaemonPidFile(text);\n\tif (record !== undefined) return record;\n\tconst pid = parseJson(text)?.pid;\n\treturn typeof pid === \"number\" && Number.isInteger(pid) && pid > 0 ? { pid, processStartTime: null } : undefined;\n}\n\n/** Live and still the recorded process; a live pid whose identity cannot be read counts as live. */\nasync function recordIsLive(record: DaemonPidFile): Promise<boolean> {\n\ttry {\n\t\treturn await processMatchesPidFile(record);\n\t} catch (error: unknown) {\n\t\tif (error instanceof ProcessIdentityUnreadableError) return true;\n\t\tthrow error;\n\t}\n}\n\n/**\n * How the socket proved silent, or `undefined` when it did not: only ECONNREFUSED and ENOENT prove\n * nobody listens. A connect that succeeds, times out or fails any other way is treated as an answer.\n * ECONNREFUSED counts only when the entry IS a socket: Linux refuses a connect to a regular file the\n * same way it refuses a dead socket, and a file named where the socket should be is not ours to unlink.\n */\nasync function socketSilence(socket: string): Promise<SocketSilence | undefined> {\n\tlet secret: Buffer | undefined;\n\tif (process.platform === \"win32\") {\n\t\t// The pipe name includes the secret; without one no client can reach the pipe either.\n\t\tsecret = await readSocketSecret(socketSecretPath(socket)).catch(() => undefined);\n\t\tif (secret === undefined) return \"socket_absent\";\n\t}\n\treturn new Promise((resolveProbe) => {\n\t\tconst connection = createConnection(resolveSocketTransportAddress(socket, process.platform, secret));\n\t\tconst finish = (value: SocketSilence | undefined): void => {\n\t\t\tclearTimeout(timeout);\n\t\t\tconnection.destroy();\n\t\t\tresolveProbe(value);\n\t\t};\n\t\tconst timeout = setTimeout(() => finish(undefined), SOCKET_PROBE_TIMEOUT_MS);\n\t\tconnection.once(\"connect\", () => finish(undefined));\n\t\tconnection.once(\"error\", (error: NodeJS.ErrnoException) => {\n\t\t\tif (error.code === \"ECONNREFUSED\") void refusedBySocket(socket).then(finish);\n\t\t\telse if (error.code === \"ENOENT\") finish(\"socket_absent\");\n\t\t\telse finish(undefined);\n\t\t});\n\t});\n}\n\n/** A refusal proves silence only from a socket entry; an entry of any other type is an answer. */\nasync function refusedBySocket(socket: string): Promise<SocketSilence | undefined> {\n\t// Named pipes and abstract sockets have no filesystem entry to be of the wrong type.\n\tif (process.platform === \"win32\" || socket.startsWith(\"\\0\")) return \"socket_refused\";\n\ttry {\n\t\treturn (await lstat(socket)).isSocket() ? \"socket_refused\" : undefined;\n\t} catch (error: unknown) {\n\t\treturn error instanceof Error && \"code\" in error && error.code === \"ENOENT\" ? \"socket_absent\" : undefined;\n\t}\n}\n"]}

package/dist/modes/rpc/host-gc.d.ts

@@ -0,0 +1,28 @@
+import { type EndpointInUse, type SocketSilence } from "./host-gc-evidence.ts";
+export type HostGcKeptReason = EndpointInUse | "locked" | "legacy_layout" | "unknown_identity" | "failed";
+/** A sibling a removal left in place because of what it is. */
+export interface HostGcSkippedEntry {
+    readonly path: string;
+    readonly type: "directory";
+}
+export interface HostGcEntry<Reason extends string> {
+    readonly socket: string | null;
+    readonly dir: string;
+    readonly reason: Reason;
+    /** Removed entries only, and only when a sibling was left in place. */
+    readonly skipped?: readonly HostGcSkippedEntry[];
+    /** `failed` entries only: the message of what threw. */
+    readonly error?: string;
+}
+export interface HostGcResult {
+    readonly removed: readonly HostGcEntry<SocketSilence>[];
+    readonly kept: readonly HostGcEntry<HostGcKeptReason>[];
+}
+export interface HostGcOptions {
+    readonly _test?: {
+        /** Runs inside an endpoint's ensure lock, before any evidence is read. */
+        readonly afterLockAcquired?: (socket: string) => Promise<void>;
+    };
+}
+export declare function gcHostEndpoints(agentDir: string, options?: HostGcOptions): Promise<HostGcResult>;
+//# sourceMappingURL=host-gc.d.ts.map

package/dist/modes/rpc/host-gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-gc.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-gc.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,KAAK,aAAa,EAAiB,KAAK,aAAa,EAAkB,MAAM,uBAAuB,CAAC;AAE9G,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,QAAQ,GAAG,eAAe,GAAG,kBAAkB,GAAG,QAAQ,CAAC;AAE1G,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW,CAAC,MAAM,SAAS,MAAM;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,CAAC,gBAAgB,CAAC,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE;QAChB,0EAA0E;QAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/D,CAAC;CACF;AAKD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAqB1G"}

package/dist/modes/rpc/host-gc.js

@@ -0,0 +1,110 @@
+/**
+ * `senpi host gc`: reclaims the endpoint directories of hosts that are PROVABLY gone, and nothing else.
+ *
+ * Endpoint state accumulates by design - `endpoint.json` outlives every generation so `status --all`
+ * can still name an endpoint whose host exited - and this is the only path that ever removes it. It
+ * never runs implicitly (not inside `ensure`, not inside `status`), it never signals a process, and it
+ * removes an endpoint only on three-part evidence evaluated INSIDE that endpoint's ensure lock, the one
+ * `ensureHost` serializes on (`hostEnsureLockTarget`), so an ensure can neither start a host into a
+ * directory being removed nor have its fresh registration removed under it. Every endpoint that fails
+ * any part of the evidence is kept, with the reason:
+ *
+ *     live_generation   a generation pidfile (any, the pointer's included) names a live process
+ *     live_claim        a session-path claim in `reservations/` has a live owner
+ *     reachable         the socket (or a `.next-*` successor bind) did not refuse the connection
+ *     locked            the ensure lock was not free within 2 s
+ *     legacy_layout     the agent dir predates layout 2; its flat files belong to a legacy host
+ *     unknown_identity  nothing in the directory names its socket, so its lock cannot be taken
+ *     failed            reading the evidence or removing the endpoint threw; `error` says what
+ *
+ * A removal goes siblings first, the socket next and the endpoint directory LAST: until the directory
+ * is gone the endpoint is still listed, so a removal that fails part-way is finished by a later gc
+ * instead of leaving a socket nothing names. A sibling that is a directory is not a socket's leftover
+ * and not gc's to delete; it stays, and is reported under `skipped`. One endpoint's failure is recorded
+ * and the run goes on to the next.
+ */
+import { lstat, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { HOST_DAEMON_LAYOUT, hostDaemonDirectoryPaths } from "./host-daemon-paths.js";
+import { parseJson, readFileOrUndefined } from "./host-daemon-state.js";
+import { listHostEndpoints } from "./host-endpoints.js";
+import { acquireHostEnsureLock } from "./host-ensure-lock.js";
+import { endpointInUse, socketSiblings } from "./host-gc-evidence.js";
+/** 2 s, the budget a concurrent ensure's critical section gets before gc reports `locked`. */
+const GC_LOCK_WAIT_MS = 2_000;
+export async function gcHostEndpoints(agentDir, options = {}) {
+    const removed = [];
+    const kept = [];
+    const legacy = await legacyFlatDirectory(agentDir);
+    if (legacy !== undefined)
+        kept.push({ socket: null, dir: legacy, reason: "legacy_layout" });
+    for (const endpoint of await listHostEndpoints(agentDir)) {
+        if (endpoint.socket === null) {
+            kept.push({ socket: null, dir: endpoint.dir, reason: "unknown_identity" });
+            continue;
+        }
+        const entry = { socket: endpoint.socket, dir: endpoint.dir };
+        try {
+            const outcome = await gcEndpoint(endpoint.socket, endpoint.dir, options);
+            if (!outcome.removed)
+                kept.push({ ...entry, reason: outcome.reason });
+            else if (outcome.skipped.length === 0)
+                removed.push({ ...entry, reason: outcome.reason });
+            else
+                removed.push({ ...entry, reason: outcome.reason, skipped: outcome.skipped });
+        }
+        catch (error) {
+            kept.push({ ...entry, reason: "failed", error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { removed, kept };
+}
+async function gcEndpoint(socket, dir, options) {
+    const release = await acquireEnsureLock(socket);
+    if (release === undefined)
+        return { removed: false, reason: "locked" };
+    try {
+        await options._test?.afterLockAcquired?.(socket);
+        const evidence = await endpointInUse(hostDaemonDirectoryPaths(dir), socket);
+        if (evidence.inUse !== undefined)
+            return { removed: false, reason: evidence.inUse };
+        const skipped = await removeEndpoint(socket, dir);
+        return { removed: true, reason: evidence.silence, skipped };
+    }
+    finally {
+        await release();
+    }
+}
+/** Siblings by their actual type, then the socket, then the directory that lists the endpoint. */
+async function removeEndpoint(socket, dir) {
+    const skipped = [];
+    for (const sibling of await socketSiblings(socket)) {
+        const path = join(dirname(socket), sibling);
+        const entry = await lstat(path).catch((error) => {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (entry?.isDirectory())
+            skipped.push({ path, type: "directory" });
+        else if (entry !== undefined)
+            await rm(path, { force: true });
+    }
+    await rm(socket, { force: true });
+    await rm(dir, { recursive: true, force: true });
+    return skipped;
+}
+/** The ensure lock of `socket`, taken exactly as `ensureHost` takes it; `undefined` when not free in time. */
+async function acquireEnsureLock(socket) {
+    return acquireHostEnsureLock(socket, GC_LOCK_WAIT_MS).catch(() => undefined);
+}
+/** The flat daemon directory when it holds state but no layout-2 marker: a legacy host's, never touched. */
+async function legacyFlatDirectory(agentDir) {
+    const flatDir = join(agentDir, "rpc-host-daemon");
+    const marker = parseJson(await readFileOrUndefined(join(flatDir, "layout.json")).catch(() => undefined));
+    if (marker?.layout === HOST_DAEMON_LAYOUT)
+        return undefined;
+    const hasState = (await readFileOrUndefined(join(flatDir, "host.pid")).catch(() => undefined)) !== undefined;
+    return hasState ? flatDir : undefined;
+}
+//# sourceMappingURL=host-gc.js.map

package/dist/modes/rpc/host-gc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-gc.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-gc.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `senpi host gc`: reclaims the endpoint directories of hosts that are PROVABLY gone, and nothing else.\n *\n * Endpoint state accumulates by design - `endpoint.json` outlives every generation so `status --all`\n * can still name an endpoint whose host exited - and this is the only path that ever removes it. It\n * never runs implicitly (not inside `ensure`, not inside `status`), it never signals a process, and it\n * removes an endpoint only on three-part evidence evaluated INSIDE that endpoint's ensure lock, the one\n * `ensureHost` serializes on (`hostEnsureLockTarget`), so an ensure can neither start a host into a\n * directory being removed nor have its fresh registration removed under it. Every endpoint that fails\n * any part of the evidence is kept, with the reason:\n *\n *     live_generation   a generation pidfile (any, the pointer's included) names a live process\n *     live_claim        a session-path claim in `reservations/` has a live owner\n *     reachable         the socket (or a `.next-*` successor bind) did not refuse the connection\n *     locked            the ensure lock was not free within 2 s\n *     legacy_layout     the agent dir predates layout 2; its flat files belong to a legacy host\n *     unknown_identity  nothing in the directory names its socket, so its lock cannot be taken\n *     failed            reading the evidence or removing the endpoint threw; `error` says what\n *\n * A removal goes siblings first, the socket next and the endpoint directory LAST: until the directory\n * is gone the endpoint is still listed, so a removal that fails part-way is finished by a later gc\n * instead of leaving a socket nothing names. A sibling that is a directory is not a socket's leftover\n * and not gc's to delete; it stays, and is reported under `skipped`. One endpoint's failure is recorded\n * and the run goes on to the next.\n */\nimport { lstat, rm } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { HOST_DAEMON_LAYOUT, hostDaemonDirectoryPaths } from \"./host-daemon-paths.ts\";\nimport { parseJson, readFileOrUndefined } from \"./host-daemon-state.ts\";\nimport { listHostEndpoints } from \"./host-endpoints.ts\";\nimport { acquireHostEnsureLock } from \"./host-ensure-lock.ts\";\nimport { type EndpointInUse, endpointInUse, type SocketSilence, socketSiblings } from \"./host-gc-evidence.ts\";\n\nexport type HostGcKeptReason = EndpointInUse | \"locked\" | \"legacy_layout\" | \"unknown_identity\" | \"failed\";\n\n/** A sibling a removal left in place because of what it is. */\nexport interface HostGcSkippedEntry {\n\treadonly path: string;\n\treadonly type: \"directory\";\n}\n\nexport interface HostGcEntry<Reason extends string> {\n\treadonly socket: string | null;\n\treadonly dir: string;\n\treadonly reason: Reason;\n\t/** Removed entries only, and only when a sibling was left in place. */\n\treadonly skipped?: readonly HostGcSkippedEntry[];\n\t/** `failed` entries only: the message of what threw. */\n\treadonly error?: string;\n}\n\nexport interface HostGcResult {\n\treadonly removed: readonly HostGcEntry<SocketSilence>[];\n\treadonly kept: readonly HostGcEntry<HostGcKeptReason>[];\n}\n\nexport interface HostGcOptions {\n\treadonly _test?: {\n\t\t/** Runs inside an endpoint's ensure lock, before any evidence is read. */\n\t\treadonly afterLockAcquired?: (socket: string) => Promise<void>;\n\t};\n}\n\n/** 2 s, the budget a concurrent ensure's critical section gets before gc reports `locked`. */\nconst GC_LOCK_WAIT_MS = 2_000;\n\nexport async function gcHostEndpoints(agentDir: string, options: HostGcOptions = {}): Promise<HostGcResult> {\n\tconst removed: HostGcEntry<SocketSilence>[] = [];\n\tconst kept: HostGcEntry<HostGcKeptReason>[] = [];\n\tconst legacy = await legacyFlatDirectory(agentDir);\n\tif (legacy !== undefined) kept.push({ socket: null, dir: legacy, reason: \"legacy_layout\" });\n\tfor (const endpoint of await listHostEndpoints(agentDir)) {\n\t\tif (endpoint.socket === null) {\n\t\t\tkept.push({ socket: null, dir: endpoint.dir, reason: \"unknown_identity\" });\n\t\t\tcontinue;\n\t\t}\n\t\tconst entry = { socket: endpoint.socket, dir: endpoint.dir };\n\t\ttry {\n\t\t\tconst outcome = await gcEndpoint(endpoint.socket, endpoint.dir, options);\n\t\t\tif (!outcome.removed) kept.push({ ...entry, reason: outcome.reason });\n\t\t\telse if (outcome.skipped.length === 0) removed.push({ ...entry, reason: outcome.reason });\n\t\t\telse removed.push({ ...entry, reason: outcome.reason, skipped: outcome.skipped });\n\t\t} catch (error: unknown) {\n\t\t\tkept.push({ ...entry, reason: \"failed\", error: error instanceof Error ? error.message : String(error) });\n\t\t}\n\t}\n\treturn { removed, kept };\n}\n\nasync function gcEndpoint(\n\tsocket: string,\n\tdir: string,\n\toptions: HostGcOptions,\n): Promise<\n\t| { readonly removed: true; readonly reason: SocketSilence; readonly skipped: readonly HostGcSkippedEntry[] }\n\t| { readonly removed: false; readonly reason: HostGcKeptReason }\n> {\n\tconst release = await acquireEnsureLock(socket);\n\tif (release === undefined) return { removed: false, reason: \"locked\" };\n\ttry {\n\t\tawait options._test?.afterLockAcquired?.(socket);\n\t\tconst evidence = await endpointInUse(hostDaemonDirectoryPaths(dir), socket);\n\t\tif (evidence.inUse !== undefined) return { removed: false, reason: evidence.inUse };\n\t\tconst skipped = await removeEndpoint(socket, dir);\n\t\treturn { removed: true, reason: evidence.silence, skipped };\n\t} finally {\n\t\tawait release();\n\t}\n}\n\n/** Siblings by their actual type, then the socket, then the directory that lists the endpoint. */\nasync function removeEndpoint(socket: string, dir: string): Promise<readonly HostGcSkippedEntry[]> {\n\tconst skipped: HostGcSkippedEntry[] = [];\n\tfor (const sibling of await socketSiblings(socket)) {\n\t\tconst path = join(dirname(socket), sibling);\n\t\tconst entry = await lstat(path).catch((error: unknown) => {\n\t\t\tif (error instanceof Error && \"code\" in error && error.code === \"ENOENT\") return undefined;\n\t\t\tthrow error;\n\t\t});\n\t\tif (entry?.isDirectory()) skipped.push({ path, type: \"directory\" });\n\t\telse if (entry !== undefined) await rm(path, { force: true });\n\t}\n\tawait rm(socket, { force: true });\n\tawait rm(dir, { recursive: true, force: true });\n\treturn skipped;\n}\n\n/** The ensure lock of `socket`, taken exactly as `ensureHost` takes it; `undefined` when not free in time. */\nasync function acquireEnsureLock(socket: string): Promise<(() => Promise<void>) | undefined> {\n\treturn acquireHostEnsureLock(socket, GC_LOCK_WAIT_MS).catch(() => undefined);\n}\n\n/** The flat daemon directory when it holds state but no layout-2 marker: a legacy host's, never touched. */\nasync function legacyFlatDirectory(agentDir: string): Promise<string | undefined> {\n\tconst flatDir = join(agentDir, \"rpc-host-daemon\");\n\tconst marker = parseJson(await readFileOrUndefined(join(flatDir, \"layout.json\")).catch(() => undefined));\n\tif (marker?.layout === HOST_DAEMON_LAYOUT) return undefined;\n\tconst hasState = (await readFileOrUndefined(join(flatDir, \"host.pid\")).catch(() => undefined)) !== undefined;\n\treturn hasState ? flatDir : undefined;\n}\n"]}

package/dist/modes/rpc/host-generations.d.ts

@@ -1,4 +1,4 @@
-import { type HostDaemonPaths } from "./host-daemon-paths.ts";
+import { type HostDaemonDirectory, type HostDaemonPaths } from "./host-daemon-paths.ts";
 /** One generation that is still running, as the daemon directory and the OS describe it. */
 export interface HostGenerationRow {
     readonly instanceId: string;
@@ -30,5 +30,13 @@ export interface PrunedDaemonState {
  * LEFT - an ensure writing one right now must not be mistaken for a generation that ended.
  */
 export declare function pruneDeadGenerations(paths: HostDaemonPaths): Promise<PrunedDaemonState>;
-export declare function readGenerationRows(paths: HostDaemonPaths): Promise<readonly HostGenerationRow[]>;
+/**
+ * Every generation of this daemon that is still running, newest ordinal last. A record naming a
+ * dead pid is omitted rather than reported as history: `host status` answers who is alive now.
+ * `includeDead` is for the reader that must not prune (`host status --all`): a dead record is then
+ * reported as a row with `alive: false` instead of being dropped, so the stale state stays visible.
+ */
+export declare function readGenerationRows(paths: HostDaemonDirectory, options?: {
+    readonly includeDead?: boolean;
+}): Promise<readonly HostGenerationRow[]>;
 //# sourceMappingURL=host-generations.d.ts.map

package/dist/modes/rpc/host-generations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-generations.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-generations.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK/E,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mGAAmG;IACnG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IACjC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoB7F;AAUD,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAoBtG"}
+{"version":3,"file":"host-generations.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-generations.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKzG,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mGAAmG;IACnG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IACjC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoB7F;AAMD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACvC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,GAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9C,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAsBvC"}

package/dist/modes/rpc/host-generations.js

@@ -47,31 +47,36 @@ export async function pruneDeadGenerations(paths) {
     }
     return { generations, claims, pointer: pointerRemoved };
 }
+function memoryOf(metrics) {
+    return { rss_mb: metrics.rss_mb, host_rss_mb: metrics.host_rss_mb };
+}
 /**
  * Every generation of this daemon that is still running, newest ordinal last. A record naming a
  * dead pid is omitted rather than reported as history: `host status` answers who is alive now.
+ * `includeDead` is for the reader that must not prune (`host status --all`): a dead record is then
+ * reported as a row with `alive: false` instead of being dropped, so the stale state stays visible.
  */
-function memoryOf(metrics) {
-    return { rss_mb: metrics.rss_mb, host_rss_mb: metrics.host_rss_mb };
-}
-export async function readGenerationRows(paths) {
+export async function readGenerationRows(paths, options = {}) {
     const pointer = parseJson(await readFileOrUndefined(paths.pointerFile).catch(() => undefined));
     const currentId = typeof pointer?.instance_id === "string" ? pointer.instance_id : undefined;
     const claims = await readSessionPathClaims(paths.reservationsDir);
     const rows = [];
     for (const instanceId of await readdir(paths.generationsDir).catch(() => [])) {
         const record = parseJson(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));
-        if (typeof record?.pid !== "number" || !processIsLive(record.pid))
+        if (typeof record?.pid !== "number")
+            continue;
+        const alive = processIsLive(record.pid);
+        if (!alive && options.includeDead !== true)
             continue;
         rows.push({
             instanceId,
             generation: typeof record.generation === "number" ? record.generation : 0,
             pid: record.pid,
             engineVersion: typeof record.engineVersion === "string" ? record.engineVersion : null,
-            ...memoryOf(await readHostProcessMetrics(record.pid)),
+            ...(alive ? memoryOf(await readHostProcessMetrics(record.pid)) : { rss_mb: null, host_rss_mb: null }),
             sessions: claims.filter((claim) => claim.owner.instanceId === instanceId).length,
             current: instanceId === currentId,
-            alive: true,
+            alive,
         });
     }
     return rows.sort((left, right) => left.generation - right.generation);

package/dist/modes/rpc/host-generations.js.map

@@ -1 +1 @@
-{"version":3,"file":"host-generations.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-generations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which generations of one daemon are still RUNNING, and what a dead one leaves behind.\n *\n * The daemon directory accumulates a record per generation, and nothing used to remove one: after a\n * handoff, an idle exit or a kill, `generations/<instanceId>/host.pid` stayed, the pointer could go\n * on naming a process nobody runs, and `reservations/` kept claims of hosts that had been gone for\n * days (#1893: the directory described only dead pids while three supervisors were alive). Reading\n * it therefore has to mean pruning it - a record that names a pid nobody is running is not history,\n * it is a lie about what serves this endpoint.\n *\n * Both answers come from files rather than from the socket on purpose: a generation that no longer\n * answers is exactly what an operator is looking for, and a superseded host holding gigabytes\n * cannot be asked how many sessions it has.\n */\nimport { readdir, rm } from \"node:fs/promises\";\nimport { processIsLive } from \"../app-server/daemon/process.ts\";\nimport { generationPaths, type HostDaemonPaths } from \"./host-daemon-paths.ts\";\nimport { parseJson, readFileOrUndefined } from \"./host-daemon-state.ts\";\nimport { type HostProcessMetrics, readHostProcessMetrics } from \"./host-process-metrics.ts\";\nimport { claimOwnerIsLive, readSessionPathClaims } from \"./host-reservations.ts\";\n\n/** One generation that is still running, as the daemon directory and the OS describe it. */\nexport interface HostGenerationRow {\n\treadonly instanceId: string;\n\treadonly generation: number;\n\treadonly pid: number;\n\treadonly engineVersion: string | null;\n\t/** Resident memory of that generation's process tree, `null` where the platform hides it. */\n\treadonly rss_mb: number | null;\n\t/** Resident memory of that generation's own supervisor and host processes, without their tools. */\n\treadonly host_rss_mb: number | null;\n\t/** Session files this generation still claims in `reservations/`. */\n\treadonly sessions: number;\n\t/** True for the generation the pointer names: the one serving the socket. */\n\treadonly current: boolean;\n\treadonly alive: boolean;\n}\n\n/** What one prune removed, so a caller can report it instead of guessing. */\nexport interface PrunedDaemonState {\n\t/** Instance ids whose generation directory named a dead pid. */\n\treadonly generations: readonly string[];\n\t/** Session paths whose claim named a dead owner. */\n\treadonly claims: readonly string[];\n\t/** Whether the pointer itself named one of those dead generations. */\n\treadonly pointer: boolean;\n}\n\n/**\n * Drops every record of a generation that is no longer running: its directory, the pointer while it\n * still names it, and the session-path claims its pid published. A record that cannot be parsed is\n * LEFT - an ensure writing one right now must not be mistaken for a generation that ended.\n */\nexport async function pruneDeadGenerations(paths: HostDaemonPaths): Promise<PrunedDaemonState> {\n\tconst pointer = parseJson(await readFileOrUndefined(paths.pointerFile).catch(() => undefined));\n\tconst pointedAt = typeof pointer?.instance_id === \"string\" ? pointer.instance_id : undefined;\n\tconst generations: string[] = [];\n\tfor (const instanceId of await readdir(paths.generationsDir).catch(() => [] as string[])) {\n\t\tconst record = parseJson(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));\n\t\tif (typeof record?.pid !== \"number\" || processIsLive(record.pid)) continue;\n\t\tawait rm(generationPaths(paths, instanceId).dir, { recursive: true, force: true }).catch(() => undefined);\n\t\tgenerations.push(instanceId);\n\t}\n\tconst pointerRemoved = pointedAt !== undefined && generations.includes(pointedAt);\n\t// The pointer outliving its generation is what makes a client probe a socket nobody serves.\n\tif (pointerRemoved) await rm(paths.pointerFile, { force: true }).catch(() => undefined);\n\tconst claims: string[] = [];\n\tfor (const claim of await readSessionPathClaims(paths.reservationsDir)) {\n\t\tif (await claimOwnerIsLive(claim.owner)) continue;\n\t\tawait rm(claim.file, { force: true }).catch(() => undefined);\n\t\tclaims.push(claim.owner.sessionPath);\n\t}\n\treturn { generations, claims, pointer: pointerRemoved };\n}\n\n/**\n * Every generation of this daemon that is still running, newest ordinal last. A record naming a\n * dead pid is omitted rather than reported as history: `host status` answers who is alive now.\n */\nfunction memoryOf(metrics: HostProcessMetrics): Pick<HostGenerationRow, \"rss_mb\" | \"host_rss_mb\"> {\n\treturn { rss_mb: metrics.rss_mb, host_rss_mb: metrics.host_rss_mb };\n}\n\nexport async function readGenerationRows(paths: HostDaemonPaths): Promise<readonly HostGenerationRow[]> {\n\tconst pointer = parseJson(await readFileOrUndefined(paths.pointerFile).catch(() => undefined));\n\tconst currentId = typeof pointer?.instance_id === \"string\" ? pointer.instance_id : undefined;\n\tconst claims = await readSessionPathClaims(paths.reservationsDir);\n\tconst rows: HostGenerationRow[] = [];\n\tfor (const instanceId of await readdir(paths.generationsDir).catch(() => [] as string[])) {\n\t\tconst record = parseJson(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));\n\t\tif (typeof record?.pid !== \"number\" || !processIsLive(record.pid)) continue;\n\t\trows.push({\n\t\t\tinstanceId,\n\t\t\tgeneration: typeof record.generation === \"number\" ? record.generation : 0,\n\t\t\tpid: record.pid,\n\t\t\tengineVersion: typeof record.engineVersion === \"string\" ? record.engineVersion : null,\n\t\t\t...memoryOf(await readHostProcessMetrics(record.pid)),\n\t\t\tsessions: claims.filter((claim) => claim.owner.instanceId === instanceId).length,\n\t\t\tcurrent: instanceId === currentId,\n\t\t\talive: true,\n\t\t});\n\t}\n\treturn rows.sort((left, right) => left.generation - right.generation);\n}\n"]}
+{"version":3,"file":"host-generations.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-generations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which generations of one daemon are still RUNNING, and what a dead one leaves behind.\n *\n * The daemon directory accumulates a record per generation, and nothing used to remove one: after a\n * handoff, an idle exit or a kill, `generations/<instanceId>/host.pid` stayed, the pointer could go\n * on naming a process nobody runs, and `reservations/` kept claims of hosts that had been gone for\n * days (#1893: the directory described only dead pids while three supervisors were alive). Reading\n * it therefore has to mean pruning it - a record that names a pid nobody is running is not history,\n * it is a lie about what serves this endpoint.\n *\n * Both answers come from files rather than from the socket on purpose: a generation that no longer\n * answers is exactly what an operator is looking for, and a superseded host holding gigabytes\n * cannot be asked how many sessions it has.\n */\nimport { readdir, rm } from \"node:fs/promises\";\nimport { processIsLive } from \"../app-server/daemon/process.ts\";\nimport { generationPaths, type HostDaemonDirectory, type HostDaemonPaths } from \"./host-daemon-paths.ts\";\nimport { parseJson, readFileOrUndefined } from \"./host-daemon-state.ts\";\nimport { type HostProcessMetrics, readHostProcessMetrics } from \"./host-process-metrics.ts\";\nimport { claimOwnerIsLive, readSessionPathClaims } from \"./host-reservations.ts\";\n\n/** One generation that is still running, as the daemon directory and the OS describe it. */\nexport interface HostGenerationRow {\n\treadonly instanceId: string;\n\treadonly generation: number;\n\treadonly pid: number;\n\treadonly engineVersion: string | null;\n\t/** Resident memory of that generation's process tree, `null` where the platform hides it. */\n\treadonly rss_mb: number | null;\n\t/** Resident memory of that generation's own supervisor and host processes, without their tools. */\n\treadonly host_rss_mb: number | null;\n\t/** Session files this generation still claims in `reservations/`. */\n\treadonly sessions: number;\n\t/** True for the generation the pointer names: the one serving the socket. */\n\treadonly current: boolean;\n\treadonly alive: boolean;\n}\n\n/** What one prune removed, so a caller can report it instead of guessing. */\nexport interface PrunedDaemonState {\n\t/** Instance ids whose generation directory named a dead pid. */\n\treadonly generations: readonly string[];\n\t/** Session paths whose claim named a dead owner. */\n\treadonly claims: readonly string[];\n\t/** Whether the pointer itself named one of those dead generations. */\n\treadonly pointer: boolean;\n}\n\n/**\n * Drops every record of a generation that is no longer running: its directory, the pointer while it\n * still names it, and the session-path claims its pid published. A record that cannot be parsed is\n * LEFT - an ensure writing one right now must not be mistaken for a generation that ended.\n */\nexport async function pruneDeadGenerations(paths: HostDaemonPaths): Promise<PrunedDaemonState> {\n\tconst pointer = parseJson(await readFileOrUndefined(paths.pointerFile).catch(() => undefined));\n\tconst pointedAt = typeof pointer?.instance_id === \"string\" ? pointer.instance_id : undefined;\n\tconst generations: string[] = [];\n\tfor (const instanceId of await readdir(paths.generationsDir).catch(() => [] as string[])) {\n\t\tconst record = parseJson(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));\n\t\tif (typeof record?.pid !== \"number\" || processIsLive(record.pid)) continue;\n\t\tawait rm(generationPaths(paths, instanceId).dir, { recursive: true, force: true }).catch(() => undefined);\n\t\tgenerations.push(instanceId);\n\t}\n\tconst pointerRemoved = pointedAt !== undefined && generations.includes(pointedAt);\n\t// The pointer outliving its generation is what makes a client probe a socket nobody serves.\n\tif (pointerRemoved) await rm(paths.pointerFile, { force: true }).catch(() => undefined);\n\tconst claims: string[] = [];\n\tfor (const claim of await readSessionPathClaims(paths.reservationsDir)) {\n\t\tif (await claimOwnerIsLive(claim.owner)) continue;\n\t\tawait rm(claim.file, { force: true }).catch(() => undefined);\n\t\tclaims.push(claim.owner.sessionPath);\n\t}\n\treturn { generations, claims, pointer: pointerRemoved };\n}\n\nfunction memoryOf(metrics: HostProcessMetrics): Pick<HostGenerationRow, \"rss_mb\" | \"host_rss_mb\"> {\n\treturn { rss_mb: metrics.rss_mb, host_rss_mb: metrics.host_rss_mb };\n}\n\n/**\n * Every generation of this daemon that is still running, newest ordinal last. A record naming a\n * dead pid is omitted rather than reported as history: `host status` answers who is alive now.\n * `includeDead` is for the reader that must not prune (`host status --all`): a dead record is then\n * reported as a row with `alive: false` instead of being dropped, so the stale state stays visible.\n */\nexport async function readGenerationRows(\n\tpaths: HostDaemonDirectory,\n\toptions: { readonly includeDead?: boolean } = {},\n): Promise<readonly HostGenerationRow[]> {\n\tconst pointer = parseJson(await readFileOrUndefined(paths.pointerFile).catch(() => undefined));\n\tconst currentId = typeof pointer?.instance_id === \"string\" ? pointer.instance_id : undefined;\n\tconst claims = await readSessionPathClaims(paths.reservationsDir);\n\tconst rows: HostGenerationRow[] = [];\n\tfor (const instanceId of await readdir(paths.generationsDir).catch(() => [] as string[])) {\n\t\tconst record = parseJson(await readFileOrUndefined(generationPaths(paths, instanceId).pidFile));\n\t\tif (typeof record?.pid !== \"number\") continue;\n\t\tconst alive = processIsLive(record.pid);\n\t\tif (!alive && options.includeDead !== true) continue;\n\t\trows.push({\n\t\t\tinstanceId,\n\t\t\tgeneration: typeof record.generation === \"number\" ? record.generation : 0,\n\t\t\tpid: record.pid,\n\t\t\tengineVersion: typeof record.engineVersion === \"string\" ? record.engineVersion : null,\n\t\t\t...(alive ? memoryOf(await readHostProcessMetrics(record.pid)) : { rss_mb: null, host_rss_mb: null }),\n\t\t\tsessions: claims.filter((claim) => claim.owner.instanceId === instanceId).length,\n\t\t\tcurrent: instanceId === currentId,\n\t\t\talive,\n\t\t});\n\t}\n\treturn rows.sort((left, right) => left.generation - right.generation);\n}\n"]}

package/dist/modes/rpc/host-handoff.d.ts

@@ -1,4 +1,6 @@
 import type { HostLifecyclePolicyInput } from "./host-lifecycle.ts";
+/** The longest a handoff holds the ensure lock: its probe of the running host, then the successor's start. */
+export declare const HANDOFF_LOCK_HOLD_MS: number;
 export interface HandoffHostOptions {
     readonly socket: string;
     readonly agentDir?: string;
@@ -16,6 +18,8 @@ export interface HandoffHostOptions {
         };
         /** Runs after the public socket identity is captured and before the successor is spawned. */
         readonly beforeSpawn?: () => Promise<void>;
+        /** Runs once the successor is spawned and its generation recorded, before its answer is awaited. */
+        readonly afterSpawn?: (pid: number) => Promise<void>;
         readonly platform?: NodeJS.Platform;
     };
 }
@@ -52,4 +56,6 @@ export type HandoffResult = {
  * whether an upgrade is warranted (`decideHostAction`); this performs the one it asked for.
  */
 export declare function handoffHost(options: HandoffHostOptions): Promise<HandoffResult>;
+/** The handoff itself, for a caller that already holds this socket's ensure lock: an ensure's upgrade. */
+export declare function handoffHostLocked(options: HandoffHostOptions): Promise<HandoffResult>;
 //# sourceMappingURL=host-handoff.d.ts.map

package/dist/modes/rpc/host-handoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-handoff.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-handoff.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAIpE,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,mFAAmF;IACnF,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE;QAChB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QACrC,6FAA6F;QAC7F,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;SAAE,CAAC;QAC5F,6FAA6F;QAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;KACpC,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,MAAM,cAAc;AACzB,8EAA8E;AAC5E,SAAS;AACX,gFAAgF;GAC9E,qBAAqB;AACvB,8DAA8D;GAC5D,qBAAqB;AACvB,6FAA6F;GAC3F,eAAe;AACjB,gFAAgF;GAC9E,iBAAiB;AACnB,2EAA2E;GACzE,sBAAsB;AACxB,kGAAkG;GAChG,uBAAuB,CAAC;AAE3B,MAAM,MAAM,aAAa,GACtB;IACA,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC3B,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEL;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAiBrF"}
+{"version":3,"file":"host-handoff.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/host-handoff.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAMpE,8GAA8G;AAC9G,eAAO,MAAM,oBAAoB,QAAuD,CAAC;AAQzF,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,mFAAmF;IACnF,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE;QAChB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;QACrC,6FAA6F;QAC7F,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;SAAE,CAAC;QAC5F,6FAA6F;QAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,oGAAoG;QACpG,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;KACpC,CAAC;CACF;AAED,yFAAyF;AACzF,MAAM,MAAM,cAAc;AACzB,8EAA8E;AAC5E,SAAS;AACX,gFAAgF;GAC9E,qBAAqB;AACvB,8DAA8D;GAC5D,qBAAqB;AACvB,6FAA6F;GAC3F,eAAe;AACjB,gFAAgF;GAC9E,iBAAiB;AACnB,2EAA2E;GACzE,sBAAsB;AACxB,kGAAkG;GAChG,uBAAuB,CAAC;AAE3B,MAAM,MAAM,aAAa,GACtB;IACA,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC3B,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEL;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAQrF;AAED,0GAA0G;AAC1G,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAgB3F"}

package/dist/modes/rpc/host-handoff.js

@@ -22,26 +22,50 @@
  *
  * win32 has neither a renameable named pipe nor SIGUSR1, so every entry point here refuses
  * with `upgrade_unsupported`; upgrades there apply after a drain-stop or an idle exit.
+ *
+ * A handoff changes who serves the socket, so it runs inside the endpoint's ENSURE lock, like an
+ * ensure and `host gc`: an ensure arriving meanwhile attaches to whichever generation the handoff
+ * left registered, and gc never judges the endpoint halfway through.
  */
 import { createDaemonDirectories, createHostDaemonPaths } from "./host-daemon-paths.js";
 import { provenOwner, readHostRegistration } from "./host-daemon-registration.js";
 import { GENERATION_HANDOFF_CAPABILITY } from "./host-decision.js";
+import { acquireHostEnsureLock } from "./host-ensure-lock.js";
 import { probeProtocolInfo } from "./host-probe.js";
-import { startSuccessor } from "./host-successor.js";
+import { SUCCESSOR_START_BUDGET_MS, startSuccessor } from "./host-successor.js";
+const HANDOFF_PROBE_TIMEOUT_MS = 10_000;
+/** The longest a handoff holds the ensure lock: its probe of the running host, then the successor's start. */
+export const HANDOFF_LOCK_HOLD_MS = HANDOFF_PROBE_TIMEOUT_MS + SUCCESSOR_START_BUDGET_MS;
+/**
+ * How long a handoff waits for the lock. The longest holder is an ensure that probes the running host
+ * and then hands it off itself (its upgrade path); 10 s of headroom for a slow runner.
+ */
+const HANDOFF_LOCK_WAIT_MS = HANDOFF_PROBE_TIMEOUT_MS + HANDOFF_LOCK_HOLD_MS + 10_000;
 /**
  * Hands the socket to a new generation of this build. Forced by design: the caller decides
  * whether an upgrade is warranted (`decideHostAction`); this performs the one it asked for.
  */
 export async function handoffHost(options) {
-    const platform = options._test?.platform ?? process.platform;
-    if (platform === "win32")
+    if (handoffUnsupported(options))
+        return { action: "refuse", reason: "upgrade_unsupported", upgradeable: false };
+    const release = await acquireHostEnsureLock(options.socket, HANDOFF_LOCK_WAIT_MS);
+    try {
+        return await handoffHostLocked(options);
+    }
+    finally {
+        await release();
+    }
+}
+/** The handoff itself, for a caller that already holds this socket's ensure lock: an ensure's upgrade. */
+export async function handoffHostLocked(options) {
+    if (handoffUnsupported(options))
         return { action: "refuse", reason: "upgrade_unsupported", upgradeable: false };
     const paths = createHostDaemonPaths({
         socket: options.socket,
         ...(options.agentDir ? { agentDir: options.agentDir } : {}),
     });
     await createDaemonDirectories(paths);
-    const host = await probeProtocolInfo(options.socket, 10_000);
+    const host = await probeProtocolInfo(options.socket, HANDOFF_PROBE_TIMEOUT_MS);
     if (!host)
         return { action: "refuse", reason: "no_host", upgradeable: false };
     if (!host.capabilities.includes(GENERATION_HANDOFF_CAPABILITY)) {
@@ -53,4 +77,7 @@ export async function handoffHost(options) {
         return { action: "refuse", reason: "unknown_owner", upgradeable: true };
     return startSuccessor({ options, paths, host, owner });
 }
+function handoffUnsupported(options) {
+    return (options._test?.platform ?? process.platform) === "win32";
+}
 //# sourceMappingURL=host-handoff.js.map

package/dist/modes/rpc/host-handoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"host-handoff.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAoDrD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA2B;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IAC7D,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACzG,MAAM,KAAK,GAAG,qBAAqB,CAAC;QACnC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3D,CAAC,CAAC;IACH,MAAM,uBAAuB,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7D,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IAC9E,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IAChF,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACpF,OAAO,cAAc,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACxD,CAAC","sourcesContent":["/**\n * Replacing a running daemon without ending the work it is doing.\n *\n * An upgrade cannot mean \"kill the host and start a newer one\": one machine-wide daemon\n * holds every client's sessions, so that is a data-loss operation dressed as a version\n * bump. A GENERATION HANDOFF replaces the process while the work continues:\n *\n *   1. the successor binds `<public>.next-<gen>` - never the live public path, which it\n *      has no right to unlink - and only renames its own entry over the public path once\n *      its host answers, and only while that path still holds the exact socket this\n *      handoff was decided against (`--replace <dev>:<ino>`);\n *   2. the predecessor is then asked to DRAIN with SIGUSR1: it stops accepting, keeps\n *      every connection it is already proxying, parks each retained session as its turn\n *      settles, and exits through its ordinary idle path;\n *   3. clients that arrive in between reach whichever generation owns the path at that\n *      instant - both are alive and serving.\n *\n * Two guards make this safe rather than merely clever. SIGUSR1 has a DEFAULT DISPOSITION OF\n * TERMINATE, so a host that does not advertise `generation_handoff` is never signalled - it\n * would die, taking its sessions with it. And a host whose pidfile identity cannot be proven\n * is never signalled either (I1), because \"the process at this pid\" is not evidence.\n *\n * win32 has neither a renameable named pipe nor SIGUSR1, so every entry point here refuses\n * with `upgrade_unsupported`; upgrades there apply after a drain-stop or an idle exit.\n */\nimport { createDaemonDirectories, createHostDaemonPaths } from \"./host-daemon-paths.ts\";\nimport { provenOwner, readHostRegistration } from \"./host-daemon-registration.ts\";\nimport { GENERATION_HANDOFF_CAPABILITY } from \"./host-decision.ts\";\nimport type { HostLifecyclePolicyInput } from \"./host-lifecycle.ts\";\nimport { probeProtocolInfo } from \"./host-probe.ts\";\nimport { startSuccessor } from \"./host-successor.ts\";\n\nexport interface HandoffHostOptions {\n\treadonly socket: string;\n\treadonly agentDir?: string;\n\t/** Extra CLI arguments the successor's host child is launched with (provider pinning, extensions). */\n\treadonly hostArgs?: readonly string[];\n\t/** Environment for the successor; a `null` value removes an inherited variable. */\n\treadonly env?: Readonly<Record<string, string | null>>;\n\treadonly policy?: HostLifecyclePolicyInput;\n\treadonly _test?: {\n\t\treadonly readinessTimeoutMs?: number;\n\t\t/** Builds the spawnable command from supervisor argv; tests point it at the source entry. */\n\t\treadonly launch?: (args: readonly string[]) => { command: string; args: readonly string[] };\n\t\t/** Runs after the public socket identity is captured and before the successor is spawned. */\n\t\treadonly beforeSpawn?: () => Promise<void>;\n\t\treadonly platform?: NodeJS.Platform;\n\t};\n}\n\n/** Why a handoff did not happen. Every one of them leaves the running host untouched. */\nexport type HandoffRefusal =\n\t/** Nothing is serving the socket: there is no generation to hand off from. */\n\t| \"no_host\"\n\t/** The running host predates the drain handler; signalling it would kill it. */\n\t| \"handoff_unsupported\"\n\t/** win32: a named pipe can be neither renamed nor drained. */\n\t| \"upgrade_unsupported\"\n\t/** The pidfile cannot prove which process serves this socket, so it may not be signalled. */\n\t| \"unknown_owner\"\n\t/** The public socket stopped being the one this handoff was decided against. */\n\t| \"socket_replaced\"\n\t/** `<public>.next-<gen>` would exceed the platform's socket path limit. */\n\t| \"socket_path_too_long\"\n\t/** The successor never answered on the public socket; it was stopped and nothing was replaced. */\n\t| \"successor_unavailable\";\n\nexport type HandoffResult =\n\t| {\n\t\t\treadonly action: \"handoff\";\n\t\t\treadonly pid: number;\n\t\t\treadonly socket: string;\n\t\t\treadonly generation: number;\n\t\t\treadonly instanceId: string;\n\t  }\n\t| {\n\t\t\treadonly action: \"refuse\";\n\t\t\treadonly reason: HandoffRefusal;\n\t\t\treadonly upgradeable: boolean;\n\t\t\treadonly detail?: string;\n\t  };\n\n/**\n * Hands the socket to a new generation of this build. Forced by design: the caller decides\n * whether an upgrade is warranted (`decideHostAction`); this performs the one it asked for.\n */\nexport async function handoffHost(options: HandoffHostOptions): Promise<HandoffResult> {\n\tconst platform = options._test?.platform ?? process.platform;\n\tif (platform === \"win32\") return { action: \"refuse\", reason: \"upgrade_unsupported\", upgradeable: false };\n\tconst paths = createHostDaemonPaths({\n\t\tsocket: options.socket,\n\t\t...(options.agentDir ? { agentDir: options.agentDir } : {}),\n\t});\n\tawait createDaemonDirectories(paths);\n\tconst host = await probeProtocolInfo(options.socket, 10_000);\n\tif (!host) return { action: \"refuse\", reason: \"no_host\", upgradeable: false };\n\tif (!host.capabilities.includes(GENERATION_HANDOFF_CAPABILITY)) {\n\t\treturn { action: \"refuse\", reason: \"handoff_unsupported\", upgradeable: false };\n\t}\n\tconst registered = await readHostRegistration(paths);\n\tconst owner = await provenOwner(registered, options.socket);\n\tif (!owner) return { action: \"refuse\", reason: \"unknown_owner\", upgradeable: true };\n\treturn startSuccessor({ options, paths, host, owner });\n}\n"]}
+{"version":3,"file":"host-handoff.js","sourceRoot":"","sources":["../../../src/modes/rpc/host-handoff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Replacing a running daemon without ending the work it is doing.\n *\n * An upgrade cannot mean \"kill the host and start a newer one\": one machine-wide daemon\n * holds every client's sessions, so that is a data-loss operation dressed as a version\n * bump. A GENERATION HANDOFF replaces the process while the work continues:\n *\n *   1. the successor binds `<public>.next-<gen>` - never the live public path, which it\n *      has no right to unlink - and only renames its own entry over the public path once\n *      its host answers, and only while that path still holds the exact socket this\n *      handoff was decided against (`--replace <dev>:<ino>`);\n *   2. the predecessor is then asked to DRAIN with SIGUSR1: it stops accepting, keeps\n *      every connection it is already proxying, parks each retained session as its turn\n *      settles, and exits through its ordinary idle path;\n *   3. clients that arrive in between reach whichever generation owns the path at that\n *      instant - both are alive and serving.\n *\n * Two guards make this safe rather than merely clever. SIGUSR1 has a DEFAULT DISPOSITION OF\n * TERMINATE, so a host that does not advertise `generation_handoff` is never signalled - it\n * would die, taking its sessions with it. And a host whose pidfile identity cannot be proven\n * is never signalled either (I1), because \"the process at this pid\" is not evidence.\n *\n * win32 has neither a renameable named pipe nor SIGUSR1, so every entry point here refuses\n * with `upgrade_unsupported`; upgrades there apply after a drain-stop or an idle exit.\n *\n * A handoff changes who serves the socket, so it runs inside the endpoint's ENSURE lock, like an\n * ensure and `host gc`: an ensure arriving meanwhile attaches to whichever generation the handoff\n * left registered, and gc never judges the endpoint halfway through.\n */\nimport { createDaemonDirectories, createHostDaemonPaths } from \"./host-daemon-paths.ts\";\nimport { provenOwner, readHostRegistration } from \"./host-daemon-registration.ts\";\nimport { GENERATION_HANDOFF_CAPABILITY } from \"./host-decision.ts\";\nimport { acquireHostEnsureLock } from \"./host-ensure-lock.ts\";\nimport type { HostLifecyclePolicyInput } from \"./host-lifecycle.ts\";\nimport { probeProtocolInfo } from \"./host-probe.ts\";\nimport { SUCCESSOR_START_BUDGET_MS, startSuccessor } from \"./host-successor.ts\";\n\nconst HANDOFF_PROBE_TIMEOUT_MS = 10_000;\n\n/** The longest a handoff holds the ensure lock: its probe of the running host, then the successor's start. */\nexport const HANDOFF_LOCK_HOLD_MS = HANDOFF_PROBE_TIMEOUT_MS + SUCCESSOR_START_BUDGET_MS;\n\n/**\n * How long a handoff waits for the lock. The longest holder is an ensure that probes the running host\n * and then hands it off itself (its upgrade path); 10 s of headroom for a slow runner.\n */\nconst HANDOFF_LOCK_WAIT_MS = HANDOFF_PROBE_TIMEOUT_MS + HANDOFF_LOCK_HOLD_MS + 10_000;\n\nexport interface HandoffHostOptions {\n\treadonly socket: string;\n\treadonly agentDir?: string;\n\t/** Extra CLI arguments the successor's host child is launched with (provider pinning, extensions). */\n\treadonly hostArgs?: readonly string[];\n\t/** Environment for the successor; a `null` value removes an inherited variable. */\n\treadonly env?: Readonly<Record<string, string | null>>;\n\treadonly policy?: HostLifecyclePolicyInput;\n\treadonly _test?: {\n\t\treadonly readinessTimeoutMs?: number;\n\t\t/** Builds the spawnable command from supervisor argv; tests point it at the source entry. */\n\t\treadonly launch?: (args: readonly string[]) => { command: string; args: readonly string[] };\n\t\t/** Runs after the public socket identity is captured and before the successor is spawned. */\n\t\treadonly beforeSpawn?: () => Promise<void>;\n\t\t/** Runs once the successor is spawned and its generation recorded, before its answer is awaited. */\n\t\treadonly afterSpawn?: (pid: number) => Promise<void>;\n\t\treadonly platform?: NodeJS.Platform;\n\t};\n}\n\n/** Why a handoff did not happen. Every one of them leaves the running host untouched. */\nexport type HandoffRefusal =\n\t/** Nothing is serving the socket: there is no generation to hand off from. */\n\t| \"no_host\"\n\t/** The running host predates the drain handler; signalling it would kill it. */\n\t| \"handoff_unsupported\"\n\t/** win32: a named pipe can be neither renamed nor drained. */\n\t| \"upgrade_unsupported\"\n\t/** The pidfile cannot prove which process serves this socket, so it may not be signalled. */\n\t| \"unknown_owner\"\n\t/** The public socket stopped being the one this handoff was decided against. */\n\t| \"socket_replaced\"\n\t/** `<public>.next-<gen>` would exceed the platform's socket path limit. */\n\t| \"socket_path_too_long\"\n\t/** The successor never answered on the public socket; it was stopped and nothing was replaced. */\n\t| \"successor_unavailable\";\n\nexport type HandoffResult =\n\t| {\n\t\t\treadonly action: \"handoff\";\n\t\t\treadonly pid: number;\n\t\t\treadonly socket: string;\n\t\t\treadonly generation: number;\n\t\t\treadonly instanceId: string;\n\t  }\n\t| {\n\t\t\treadonly action: \"refuse\";\n\t\t\treadonly reason: HandoffRefusal;\n\t\t\treadonly upgradeable: boolean;\n\t\t\treadonly detail?: string;\n\t  };\n\n/**\n * Hands the socket to a new generation of this build. Forced by design: the caller decides\n * whether an upgrade is warranted (`decideHostAction`); this performs the one it asked for.\n */\nexport async function handoffHost(options: HandoffHostOptions): Promise<HandoffResult> {\n\tif (handoffUnsupported(options)) return { action: \"refuse\", reason: \"upgrade_unsupported\", upgradeable: false };\n\tconst release = await acquireHostEnsureLock(options.socket, HANDOFF_LOCK_WAIT_MS);\n\ttry {\n\t\treturn await handoffHostLocked(options);\n\t} finally {\n\t\tawait release();\n\t}\n}\n\n/** The handoff itself, for a caller that already holds this socket's ensure lock: an ensure's upgrade. */\nexport async function handoffHostLocked(options: HandoffHostOptions): Promise<HandoffResult> {\n\tif (handoffUnsupported(options)) return { action: \"refuse\", reason: \"upgrade_unsupported\", upgradeable: false };\n\tconst paths = createHostDaemonPaths({\n\t\tsocket: options.socket,\n\t\t...(options.agentDir ? { agentDir: options.agentDir } : {}),\n\t});\n\tawait createDaemonDirectories(paths);\n\tconst host = await probeProtocolInfo(options.socket, HANDOFF_PROBE_TIMEOUT_MS);\n\tif (!host) return { action: \"refuse\", reason: \"no_host\", upgradeable: false };\n\tif (!host.capabilities.includes(GENERATION_HANDOFF_CAPABILITY)) {\n\t\treturn { action: \"refuse\", reason: \"handoff_unsupported\", upgradeable: false };\n\t}\n\tconst registered = await readHostRegistration(paths);\n\tconst owner = await provenOwner(registered, options.socket);\n\tif (!owner) return { action: \"refuse\", reason: \"unknown_owner\", upgradeable: true };\n\treturn startSuccessor({ options, paths, host, owner });\n}\n\nfunction handoffUnsupported(options: HandoffHostOptions): boolean {\n\treturn (options._test?.platform ?? process.platform) === \"win32\";\n}\n"]}