@sentropic/h2a-runtime 0.98.1 → 0.98.3

package/dist/native-terminal/server.js

@@ -1,13 +1,40 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, link, lstat, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { fstatSync, lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync, unlinkSync } from "node:fs";
+import { chmod, link, lstat, mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
-import { basename, dirname, isAbsolute, join } from "node:path";
-import { NativeTerminalHost, } from "./host.js";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { NativeTerminalHost, defaultOwnerHostProbe, readProcessStartTime, } from "./host.js";
 import { NATIVE_TERMINAL_MAX_FRAME_BYTES, NATIVE_TERMINAL_MAX_CONNECTIONS, NATIVE_TERMINAL_MAX_ERROR_MESSAGE_CHARS, NATIVE_TERMINAL_MAX_IDENTIFIER_CHARS, NATIVE_TERMINAL_MAX_PENDING_RESPONSE_BYTES_PER_CONNECTION, NATIVE_TERMINAL_MAX_PENDING_RESPONSE_BYTES_TOTAL, NATIVE_TERMINAL_MAX_PENDING_RESPONSES_PER_CONNECTION, NATIVE_TERMINAL_PROTOCOL_VERSION, isNativeTerminalStopSignal, isRecord, parseNativeTerminalRequest, } from "./protocol.js";
 import { assertNativeTerminalSocketPathWithinLimit, assertPrivateNativeTerminalSocketDirectory, inspectPrivateNativeTerminalSocket, sameNativeTerminalSocket, } from "./socket-path.js";
+import { listNativeTerminalPgidEntries, loadRegistry } from "../registry.js";
+import { readBootId, readPidNamespaceId } from "../proc-identity.js";
 const SOCKET_PUBLICATION_LOCK_TIMEOUT_MS = 5_000;
 const SOCKET_PUBLICATION_LOCK_RETRY_MS = 25;
 const SOCKET_PUBLICATION_LOCK_ID_FILE = ".h2a-native-terminal.lock-id";
+const SOCKET_PUBLICATION_CLEANUP_TIMEOUT_MS = 100;
+async function abortable(operation, signal) {
+    if (signal === undefined)
+        return operation;
+    let aborted;
+    try {
+        const result = await Promise.race([
+            operation,
+            new Promise((_, reject) => {
+                aborted = () => reject(signal.reason);
+                if (signal.aborted)
+                    aborted();
+                else
+                    signal.addEventListener("abort", aborted, { once: true });
+            }),
+        ]);
+        signal.throwIfAborted();
+        return result;
+    }
+    finally {
+        if (aborted !== undefined)
+            signal.removeEventListener("abort", aborted);
+    }
+}
 function requiredRecord(value, label) {
     if (!isRecord(value))
         throw new TypeError(`${label} must be an object`);
@@ -323,17 +350,20 @@ function consumeFrames(host, context, chunk) {
         context.socket.destroy();
     }
 }
-async function socketAcceptsConnections(socketPath) {
-    return new Promise((resolve) => {
+async function socketAcceptsConnections(socketPath, signal) {
+    return abortable(new Promise((resolve) => {
         const socket = createConnection(socketPath);
+        const cancel = () => socket.destroy();
+        signal?.addEventListener("abort", cancel, { once: true });
+        socket.once("close", () => signal?.removeEventListener("abort", cancel));
         socket.once("connect", () => {
             socket.destroy();
             resolve(true);
         });
         socket.once("error", () => resolve(false));
-    });
+    }), signal);
 }
-async function socketPublicationLockSecret(socketPath) {
+async function socketPublicationLockSecret(socketPath, signal) {
     if (process.platform !== "linux" || process.getuid === undefined) {
         throw new Error("native terminal socket publication requires Linux abstract Unix sockets");
     }
@@ -341,13 +371,14 @@ async function socketPublicationLockSecret(socketPath) {
     const identityPath = join(directory, SOCKET_PUBLICATION_LOCK_ID_FILE);
     const temporaryPath = join(directory, `.${SOCKET_PUBLICATION_LOCK_ID_FILE}.${process.pid}.${randomUUID()}.tmp`);
     try {
-        await writeFile(temporaryPath, `${randomUUID()}\n`, {
+        await abortable(writeFile(temporaryPath, `${randomUUID()}\n`, {
             flag: "wx",
             mode: 0o600,
-        });
-        await chmod(temporaryPath, 0o600);
+            signal,
+        }), signal);
+        await abortable(chmod(temporaryPath, 0o600), signal);
         try {
-            await link(temporaryPath, identityPath);
+            await abortable(link(temporaryPath, identityPath), signal);
         }
         catch (error) {
             if (error.code !== "EEXIST")
@@ -356,82 +387,484 @@ async function socketPublicationLockSecret(socketPath) {
     }
     finally {
         try {
-            await unlink(temporaryPath);
+            await abortable(unlink(temporaryPath), signal);
         }
         catch (error) {
-            if (error.code !== "ENOENT")
+            if (signal?.aborted)
+                unlinkIfPresent(temporaryPath);
+            else if (error.code !== "ENOENT")
                 throw error;
         }
     }
-    const identity = await lstat(identityPath);
+    const identity = await abortable(lstat(identityPath), signal);
     if (!identity.isFile()
         || identity.isSymbolicLink()
         || identity.uid !== process.getuid()
         || (identity.mode & 0o777) !== 0o600) {
         throw new Error(`terminal socket publication lock identity is not a private owned file: ${identityPath}`);
     }
-    const secret = (await readFile(identityPath, "utf8")).trim();
+    const secret = (await abortable(readFile(identityPath, "utf8"), signal)).trim();
     if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(secret)) {
         throw new Error(`terminal socket publication lock identity is malformed: ${identityPath}`);
     }
     return secret;
 }
-async function acquireSocketPublicationLock(socketPath) {
-    const secret = await socketPublicationLockSecret(socketPath);
+async function acquireSocketPublicationLock(socketPath, signal) {
+    const secret = await socketPublicationLockSecret(socketPath, signal);
     const address = `\0h2a-terminal-lock-${createHash("sha256")
         .update(`${process.getuid?.() ?? "unknown"}:${socketPath}:${secret}`)
         .digest("hex")}`;
     const deadline = Date.now() + SOCKET_PUBLICATION_LOCK_TIMEOUT_MS;
     for (;;) {
-        const lock = createServer();
+        signal?.throwIfAborted();
+        const lock = createServer(socket => socket.destroy());
         try {
-            await new Promise((resolve, reject) => {
+            await abortable(new Promise((resolve, reject) => {
                 lock.once("error", reject);
                 lock.listen(address, () => {
                     lock.removeListener("error", reject);
                     resolve();
                 });
-            });
+            }), signal);
             return lock;
         }
         catch (error) {
+            lock.close();
             if (error.code !== "EADDRINUSE"
                 || Date.now() >= deadline) {
                 throw error;
             }
-            await new Promise((resolve) => setTimeout(resolve, SOCKET_PUBLICATION_LOCK_RETRY_MS));
+            await abortable(new Promise((resolve) => setTimeout(resolve, SOCKET_PUBLICATION_LOCK_RETRY_MS)), signal);
         }
     }
 }
-async function withSocketPublicationLock(socketPath, operation) {
-    const lock = await acquireSocketPublicationLock(socketPath);
+async function withSocketPublicationLock(socketPath, operation, signal) {
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(new Error("terminal socket publication lock timed out")), SOCKET_PUBLICATION_LOCK_TIMEOUT_MS);
+    const boundedSignal = signal === undefined ? deadline.signal : AbortSignal.any([signal, deadline.signal]);
     try {
-        return await operation();
+        const lock = await acquireSocketPublicationLock(socketPath, boundedSignal);
+        try {
+            boundedSignal.throwIfAborted();
+            return await operation(boundedSignal);
+        }
+        finally {
+            await abortable(new Promise((resolve, reject) => {
+                lock.close((error) => error && error.code !== "ERR_SERVER_NOT_RUNNING" ? reject(error) : resolve());
+            }), AbortSignal.timeout(SOCKET_PUBLICATION_CLEANUP_TIMEOUT_MS));
+        }
     }
     finally {
-        await new Promise((resolve, reject) => {
-            lock.close((error) => error ? reject(error) : resolve());
-        });
+        clearTimeout(timer);
+    }
+}
+function unlinkIfPresent(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function unlinkOwnedPath(path, owned) {
+    try {
+        const current = lstatSync(path);
+        if (sameNativeTerminalSocket(current, owned))
+            unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function rollbackEndpoint(socketPath, owned) {
+    unlinkOwnedPath(socketPath, owned);
+    const ownerPath = `${socketPath}.owner`;
+    try {
+        const identity = lstatSync(ownerPath);
+        if (!identity.isFile() || identity.uid !== process.getuid?.() || (identity.mode & 0o777) !== 0o600)
+            return;
+        const owner = JSON.parse(readFileSync(ownerPath, "utf8"));
+        if (owner.pid === process.pid && owner.startTime === readProcessStartTime(process.pid)
+            && sameNativeTerminalSocket(owner, owned))
+            unlinkOwnedPath(ownerPath, identity);
+    }
+    catch { /* Unknown sidecar ownership is never cleanup authority. */ }
+}
+async function recordEndpointOwner(socketPath, socket, processOwner = { pid: process.pid, startTime: readProcessStartTime(process.pid) }, signal) {
+    signal?.throwIfAborted();
+    if (process.env.H2A_TEST_FAIL_OWNER_WRITE) {
+        throw new Error("simulated failure recording endpoint owner");
+    }
+    const { pid, startTime } = processOwner;
+    const bootId = readBootId(), pidNamespace = readPidNamespaceId();
+    if (startTime === undefined || bootId === undefined || pidNamespace === undefined) {
+        throw new Error("cannot certify native host process identity");
+    }
+    const temporary = `${socketPath}.owner.${process.pid}.${randomUUID()}.tmp`;
+    let file;
+    try {
+        const openedFile = await abortable(open(temporary, "wx", 0o600).then((opened) => {
+            if (signal?.aborted) {
+                // A cancelled open may finish after rollback. Its unique pathname and
+                // descriptor still belong to this publication, never to a successor.
+                try {
+                    unlinkOwnedPath(temporary, fstatSync(opened.fd));
+                }
+                finally {
+                    void opened.close().catch(() => { });
+                }
+                signal.throwIfAborted();
+            }
+            file = opened;
+            return opened;
+        }), signal);
+        signal?.throwIfAborted();
+        // Write through the already-open inode: cancellation can unlink it without
+        // a delayed write recreating the temporary pathname.
+        await abortable(writeFile(openedFile, JSON.stringify({ ...socket, pid, startTime, bootId, pidNamespace }), signal === undefined ? {} : { signal }), signal);
+        signal?.throwIfAborted();
+        await abortable(rename(temporary, `${socketPath}.owner`), signal);
+    }
+    finally {
+        // Invalidate the rename source before releasing the publication lock. A
+        // delayed rename either already committed (and is rolled back by its
+        // publisher) or can no longer install an owner after cancellation.
+        try {
+            await abortable(unlink(temporary).catch(error => { if (error.code !== "ENOENT")
+                throw error; }), signal);
+        }
+        catch (error) {
+            if (!signal?.aborted)
+                throw error;
+            // No asynchronous rollback can be left targeting a shared pathname.
+            // Invalidate the unique source now, before the exclusion lock is closed.
+            if (file !== undefined)
+                unlinkOwnedPath(temporary, fstatSync(file.fd));
+            else
+                unlinkIfPresent(temporary);
+            signal.throwIfAborted();
+        }
+        finally {
+            // An aborted write may still be unwinding. Its descriptor owns only the
+            // unlinked inode and must not hold up listener/lock cleanup.
+            void file?.close().catch(() => { });
+        }
+    }
+}
+/**
+ * ENOENT/ECONNREFUSED are candidates, never proof by themselves. Serialize
+ * with publication and re-read both the socket and its durable process
+ * identity. A live or unreadable owner keeps the endpoint unknown.
+ * No socket is removed by an inventory; publication owns reclamation.
+ */
+export async function proveNativeTerminalEndpointAbsent(socketPath, failure) {
+    const code = failure?.code;
+    if (code !== "ENOENT" && code !== "ECONNREFUSED")
+        return false;
+    await ensurePrivateSocketDirectory(socketPath);
+    return withSocketPublicationLock(socketPath, signal => proveEndpointAbsentUnderLock(socketPath, signal));
+}
+function canonicalizePath(targetPath) {
+    const resolved = resolve(targetPath);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        const dir = dirname(resolved);
+        const base = basename(resolved);
+        try {
+            const realDir = realpathSync(dir);
+            return join(realDir, base);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST_PROC_ROOT ?? "/proc") {
+    if (process.env.H2A_TEST_PROC_UNAVAILABLE) {
+        return { state: "unknown", reason: "simulated /proc observation unavailable" };
+    }
+    if (process.platform !== "linux") {
+        return { state: "unknown", reason: "platform does not support /proc host observation" };
+    }
+    let entries;
+    try {
+        entries = readdirSync(procRoot);
+    }
+    catch (error) {
+        return {
+            state: "unknown",
+            reason: `cannot read ${procRoot}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const targetCanonical = canonicalizePath(socketPath);
+    if (!targetCanonical) {
+        return {
+            state: "unknown",
+            reason: `cannot canonicalize target socket path: ${socketPath}`,
+        };
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        const pid = Number(entry);
+        if (pid === process.pid)
+            continue;
+        const pidDir = join(procRoot, entry);
+        let procStat;
+        try {
+            procStat = statSync(pidDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT" || err.code === "ESRCH")
+                continue;
+            return {
+                state: "unknown",
+                reason: `cannot stat /proc/${pid}: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (process.getuid && procStat.uid !== process.getuid()) {
+            continue;
+        }
+        let cmdline;
+        try {
+            cmdline = readFileSync(join(pidDir, "cmdline"), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT" || err.code === "ESRCH")
+                continue;
+            return {
+                state: "unknown",
+                reason: `cannot read /proc/${pid}/cmdline: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        const args = cmdline.split("\0");
+        const idx = args.indexOf("--socket");
+        if (idx === -1 || idx + 1 >= args.length)
+            continue;
+        const candidateSocket = args[idx + 1];
+        const isHost = args.some(arg => arg.includes("process.js") || (arg.includes("native-terminal") && !arg.includes("op.js")));
+        if (!isHost)
+            continue;
+        const candidateCanonical = canonicalizePath(candidateSocket);
+        if (!candidateCanonical) {
+            // The alias used at host startup was deleted; canonicalization cannot prove absence
+            return {
+                state: "unknown",
+                reason: `cannot canonicalize host socket path ${candidateSocket} for host pid ${pid}`,
+            };
+        }
+        if (candidateCanonical !== targetCanonical)
+            continue;
+        const candDir = dirname(candidateSocket);
+        const candStem = basename(candidateSocket).slice(0, 8).replace(/[^A-Za-z0-9_.-]/g, "_");
+        let isStagingCandidate = false;
+        try {
+            const dirEntries = readdirSync(candDir);
+            isStagingCandidate = dirEntries.some(name => name.startsWith(`.${candStem}.${pid}.`));
+        }
+        catch { }
+        if (isStagingCandidate)
+            continue;
+        const fdDir = join(pidDir, "fd");
+        let fds;
+        try {
+            fds = readdirSync(fdDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT" || err.code === "ESRCH")
+                continue;
+            return {
+                state: "unknown",
+                reason: `cannot inspect /proc/${pid}/fd: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        let hasSocketFd = false;
+        let unixSockets;
+        for (const fd of fds) {
+            let link;
+            try {
+                link = readlinkSync(join(fdDir, fd));
+            }
+            catch (err) {
+                if (err.code === "ENOENT" || err.code === "ESRCH")
+                    continue;
+                return {
+                    state: "unknown",
+                    reason: `cannot readlink /proc/${pid}/fd/${fd}: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+            const inode = /^socket:\[(\d+)\]$/.exec(link)?.[1];
+            if (!inode)
+                continue;
+            if (!unixSockets) {
+                try {
+                    unixSockets = new Map(readFileSync(join(pidDir, "net", "unix"), "utf8")
+                        .split("\n").flatMap(line => {
+                        const row = /^\S+\s+\S+\s+\S+\s+\S+\s+\S+\s+\S+\s+(\d+)(?:\s+(.*))?$/.exec(line);
+                        return row?.[2] ? [[row[1], row[2]]] : [];
+                    }));
+                }
+                catch (error) {
+                    return { state: "unknown", reason: `cannot inspect /proc/${pid}/net/unix: ${String(error)}` };
+                }
+            }
+            const boundPath = unixSockets.get(inode);
+            // Stdio and journal IPC are Unix socket pairs too. Only the native
+            // listener's canonical or PID-attributed staged address proves service,
+            // including a listener whose filesystem pathname has been unlinked.
+            if (!boundPath || (boundPath !== candidateSocket && !(dirname(boundPath) === candDir
+                && basename(boundPath).startsWith(`.${candStem}.${pid}.`) && boundPath.endsWith(".sock"))))
+                continue;
+            const canonicalBound = canonicalizePath(boundPath);
+            if (!canonicalBound)
+                return { state: "unknown", reason: `cannot canonicalize bound socket for host pid ${pid}` };
+            if (canonicalBound === targetCanonical || (dirname(canonicalBound) === dirname(targetCanonical)
+                && basename(canonicalBound).startsWith(`.${candStem}.${pid}.`))) {
+                hasSocketFd = true;
+                break;
+            }
+        }
+        if (!hasSocketFd)
+            continue;
+        const startTime = readProcessStartTime(pid);
+        if (startTime === undefined) {
+            return { state: "unknown", reason: `cannot read start time for host pid ${pid}` };
+        }
+        const probe = defaultOwnerHostProbe({ pid, startTime });
+        if (probe === "alive") {
+            return { state: "live", pid, startTime };
+        }
+        if (probe === "unresolvable") {
+            return { state: "unknown", reason: `host pid ${pid} liveness probe is unresolvable` };
+        }
+    }
+    return { state: "absent" };
+}
+async function proveEndpointAbsentUnderLock(socketPath, signal) {
+    signal?.throwIfAborted();
+    let socket;
+    try {
+        socket = await abortable(inspectPrivateNativeTerminalSocket(socketPath), signal);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (socket) {
+        // A listener may have appeared since the failed inventory connection.
+        // Only an explicit refusal qualifies; permissions and all other errors
+        // remain unknown, including a changed socket incarnation.
+        const refusal = await abortable(new Promise((resolve, reject) => {
+            const connection = createConnection(socketPath);
+            const cancel = () => connection.destroy();
+            signal?.addEventListener("abort", cancel, { once: true });
+            connection.once("close", () => signal?.removeEventListener("abort", cancel));
+            connection.setTimeout(1_000, () => { connection.destroy(); reject(new Error("terminal host connection timed out")); });
+            connection.once("connect", () => { connection.destroy(); resolve(false); });
+            connection.once("error", error => error.code === "ECONNREFUSED" ? resolve(true) : reject(error));
+        }), signal);
+        if (!refusal || !sameNativeTerminalSocket(socket, await abortable(inspectPrivateNativeTerminalSocket(socketPath), signal)))
+            return false;
+    }
+    // Independent proof of host vivacity: a live host that lost its pathname
+    // but still serves must never allow a second writer.
+    // /proc read errors => unknown, never absent.
+    const activeScan = findActiveHostServingSocket(socketPath);
+    if (activeScan.state === "live") {
+        return false;
+    }
+    if (activeScan.state === "unknown") {
+        throw new Error(`terminal host state is unprovable (${activeScan.reason}): ${socketPath}`);
+    }
+    try {
+        const ownerPath = `${socketPath}.owner`;
+        const info = await abortable(lstat(ownerPath), signal);
+        if (!info.isFile() || info.uid !== process.getuid?.() || (info.mode & 0o777) !== 0o600) {
+            throw new Error(`native endpoint owner identity is not a private owned file: ${ownerPath}`);
+        }
+        const owner = JSON.parse(await abortable(readFile(ownerPath, "utf8"), signal));
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0 || !Number.isSafeInteger(owner.startTime) ||
+            owner.startTime < 0 || !Number.isSafeInteger(owner.dev) || !Number.isSafeInteger(owner.ino) ||
+            typeof owner.bootId !== "string" || typeof owner.pidNamespace !== "string") {
+            throw new Error(`native endpoint owner identity is malformed: ${ownerPath}`);
+        }
+        if (socket && !sameNativeTerminalSocket(socket, owner))
+            return false;
+        if (owner.bootId !== readBootId() || owner.pidNamespace !== readPidNamespaceId())
+            return false;
+        if (defaultOwnerHostProbe(owner) !== "dead")
+            return false;
+        if (socket)
+            return true;
+        // A pre-upgrade publisher may have replaced and then lost the pathname
+        // without updating this sidecar. Its durable PTY owners must also be dead.
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
     }
+    // Pre-upgrade hosts already persist this identity for each PTY. A stale
+    // socket without any attribution is unprovable; never infer death from
+    // a bare PID, a socket's age, or an empty/error-collapsed registry.
+    const snapshot = listNativeTerminalPgidEntries();
+    if (!snapshot.known) {
+        // This decoder deliberately calls an ENOENT registry "unknown" for
+        // orphan reaping. For endpoint discovery, no file means no attribution;
+        // it proves absence only when the socket is also absent under the lock.
+        if (snapshot.reason === "registry is absent")
+            return socket === undefined;
+        throw new Error(`native endpoint owner registry is unknown: ${snapshot.reason}`);
+    }
+    const canonicalTarget = canonicalizePath(socketPath);
+    if (!canonicalTarget) {
+        throw new Error(`cannot canonicalize socket path: ${socketPath}`);
+    }
+    const owners = snapshot.entries
+        .filter(entry => entry.owner?.socketPath && canonicalizePath(entry.owner.socketPath) === canonicalTarget)
+        .map(entry => entry.owner);
+    const registry = loadRegistry();
+    if (registry.state === "unknown" || registry.unreadable.length > 0)
+        return false;
+    const rows = registry.entries.filter(entry => entry.ownerHostSocketPath && canonicalizePath(entry.ownerHostSocketPath) === canonicalTarget);
+    if (rows.some(row => row.pgidBootId !== readBootId() || row.pgidPidNamespace !== readPidNamespaceId()))
+        return false;
+    if (owners.some(owner => owner.startTime === undefined || defaultOwnerHostProbe(owner) !== "dead"))
+        return false;
+    if (socket && owners.length > 0) {
+        // Preserve the death proof before the supervisor reaps/prunes the last
+        // pre-upgrade PTY row. Reclamation must still have attribution then.
+        const owner = owners[0];
+        await recordEndpointOwner(socketPath, socket, { pid: owner.pid, startTime: owner.startTime }, signal);
+    }
+    return socket === undefined || owners.length > 0;
 }
-async function removeStaleSocket(socketPath) {
+async function removeStaleSocket(socketPath, signal) {
     for (;;) {
+        signal?.throwIfAborted();
         let stale;
         try {
-            stale = await inspectPrivateNativeTerminalSocket(socketPath);
+            stale = await abortable(inspectPrivateNativeTerminalSocket(socketPath), signal);
         }
         catch (error) {
             if (error.code === "ENOENT")
                 return;
             throw error;
         }
-        if (await socketAcceptsConnections(socketPath)) {
+        if (await socketAcceptsConnections(socketPath, signal)) {
             throw new Error(`terminal host socket is already active: ${socketPath}`);
         }
+        if (!await proveEndpointAbsentUnderLock(socketPath, signal)) {
+            throw new Error(`terminal host owner death is unproven; refusing stale socket reclamation: ${socketPath}`);
+        }
         try {
-            const current = await inspectPrivateNativeTerminalSocket(socketPath);
+            const current = await abortable(inspectPrivateNativeTerminalSocket(socketPath), signal);
             if (sameNativeTerminalSocket(stale, current)) {
-                await unlink(socketPath);
+                // Do not leave an uncancellable deletion queued against a successor.
+                unlinkOwnedPath(socketPath, stale);
                 return;
             }
         }
@@ -457,44 +890,73 @@ async function ensurePrivateSocketDirectory(socketPath) {
 }
 function stagingSocketPath(socketPath) {
     const directory = dirname(socketPath);
-    const stem = basename(socketPath).slice(0, 24).replace(/[^A-Za-z0-9_.-]/g, "_");
+    const stem = basename(socketPath).slice(0, 8).replace(/[^A-Za-z0-9_.-]/g, "_");
     const stagedPath = join(directory, `.${stem}.${process.pid}.${randomUUID().slice(0, 8)}.sock`);
     // The staged name is longer than the published one; a publishable path can
     // still overflow the kernel sun_path budget at the bind step.
     assertNativeTerminalSocketPathWithinLimit(stagedPath, "terminal host staging socket path");
     return stagedPath;
 }
-async function publishSocket(stagedPath, socketPath) {
-    const staged = await inspectPrivateNativeTerminalSocket(stagedPath);
+async function publishSocket(stagedPath, socketPath, signal) {
+    signal.throwIfAborted();
+    const staged = await abortable(inspectPrivateNativeTerminalSocket(stagedPath), signal);
+    try {
+        await abortable(inspectPrivateNativeTerminalSocket(socketPath), signal);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        if (!await proveEndpointAbsentUnderLock(socketPath, signal)) {
+            throw new Error(`terminal host owner death is unproven; refusing socket publication: ${socketPath}`);
+        }
+    }
     for (let attempt = 0; attempt < 200; attempt += 1) {
+        signal.throwIfAborted();
         try {
-            await link(stagedPath, socketPath);
-            const published = await inspectPrivateNativeTerminalSocket(socketPath);
+            await abortable(link(stagedPath, socketPath), signal);
+            const published = await abortable(inspectPrivateNativeTerminalSocket(socketPath), signal);
             if (!sameNativeTerminalSocket(staged, published)) {
                 throw new Error("terminal host published socket identity does not match its staged socket");
             }
-            await unlink(stagedPath);
+            await abortable(unlink(stagedPath), signal);
             return published;
         }
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
-            await removeStaleSocket(socketPath);
+            await removeStaleSocket(socketPath, signal);
         }
     }
     throw new Error("terminal host socket publication retry limit exceeded");
 }
 export async function startNativeTerminalHostServer(options) {
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(new Error("terminal host socket publication timed out")), SOCKET_PUBLICATION_LOCK_TIMEOUT_MS);
+    const signal = options.signal === undefined ? deadline.signal : AbortSignal.any([options.signal, deadline.signal]);
+    try {
+        return await initializeNativeTerminalHostServer({ ...options, signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function initializeNativeTerminalHostServer(options) {
+    options.signal?.throwIfAborted();
     if (!isAbsolute(options.socketPath))
         throw new Error("terminal host socket path must be absolute");
-    await ensurePrivateSocketDirectory(options.socketPath);
+    await abortable(ensurePrivateSocketDirectory(options.socketPath), options.signal);
     const sockets = new Set();
     const responseBudget = { pendingBytes: 0 };
+    let readyForRequests = false;
     const server = createServer((socket) => {
         if (sockets.size >= NATIVE_TERMINAL_MAX_CONNECTIONS) {
             socket.destroy();
             return;
         }
+        // A visible socket is not yet a completed publication: its durable owner
+        // record and publication lock must finish before health/PTY admission.
+        if (!readyForRequests)
+            socket.pause();
         const context = {
             socket,
             leases: new Map(),
@@ -526,28 +988,46 @@ export async function startNativeTerminalHostServer(options) {
     const stagedPath = stagingSocketPath(options.socketPath);
     let ownedSocket;
     try {
-        await new Promise((resolve, reject) => {
+        await abortable(new Promise((resolve, reject) => {
             server.once("error", reject);
             server.listen(stagedPath, () => {
                 server.removeListener("error", reject);
                 resolve();
             });
-        });
-        await chmod(stagedPath, 0o600);
-        ownedSocket = await withSocketPublicationLock(options.socketPath, () => publishSocket(stagedPath, options.socketPath));
+        }), options.signal);
+        // Capture the listener's inode before any publication await can suspend.
+        ownedSocket = lstatSync(stagedPath);
+        await abortable(chmod(stagedPath, 0o600), options.signal);
+        await withSocketPublicationLock(options.socketPath, async (signal) => {
+            try {
+                signal.throwIfAborted();
+                const published = await publishSocket(stagedPath, options.socketPath, signal);
+                await recordEndpointOwner(options.socketPath, published, undefined, signal);
+                return published;
+            }
+            catch (pubError) {
+                // A link may have committed without resolving its promise. Invalidate
+                // its source first, then remove only this listener's published inode.
+                unlinkOwnedPath(stagedPath, ownedSocket);
+                rollbackEndpoint(options.socketPath, ownedSocket);
+                throw pubError;
+            }
+        }, options.signal);
     }
     catch (error) {
-        await new Promise((resolve) => server.close(() => resolve()));
-        try {
-            await unlink(stagedPath);
-        }
-        catch (cleanupError) {
-            if (cleanupError.code !== "ENOENT") {
-                throw cleanupError;
-            }
+        for (const socket of sockets)
+            socket.destroy();
+        const closed = new Promise((resolve) => server.close(() => resolve()));
+        if (ownedSocket !== undefined) {
+            unlinkOwnedPath(stagedPath, ownedSocket);
+            rollbackEndpoint(options.socketPath, ownedSocket);
         }
+        await abortable(closed, AbortSignal.timeout(SOCKET_PUBLICATION_CLEANUP_TIMEOUT_MS));
         throw error;
     }
+    readyForRequests = true;
+    for (const socket of sockets)
+        socket.resume();
     let closing;
     return Object.freeze({
         socketPath: options.socketPath,
@@ -568,15 +1048,12 @@ export async function startNativeTerminalHostServer(options) {
                 }
                 for (const socket of sockets)
                     socket.destroy();
-                await new Promise((resolve, reject) => {
+                await abortable(new Promise((resolve, reject) => {
                     server.close((error) => error ? reject(error) : resolve());
-                });
+                }), AbortSignal.timeout(SOCKET_PUBLICATION_CLEANUP_TIMEOUT_MS));
                 await withSocketPublicationLock(options.socketPath, async () => {
                     try {
-                        const current = await inspectPrivateNativeTerminalSocket(options.socketPath);
-                        if (sameNativeTerminalSocket(current, ownedSocket)) {
-                            await unlink(options.socketPath);
-                        }
+                        rollbackEndpoint(options.socketPath, ownedSocket);
                     }
                     catch (error) {
                         if (error.code !== "ENOENT")