@sentropic/h2a-runtime 0.98.5 → 0.98.6

package/dist/native-terminal/server.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { fstatSync, lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync, unlinkSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, 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, resolve } from "node:path";
@@ -9,7 +9,8 @@ import { NativeTerminalHost, defaultOwnerHostProbe, readProcessStartTime, } from
 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 { NATIVE_TERMINAL_SOCKET_MAX_PATH_BYTES, assertNativeTerminalSocketPathWithinLimit, assertPrivateNativeTerminalSocketDirectory, inspectPrivateNativeTerminalSocket, sameNativeTerminalSocket, } from "./socket-path.js";
 import { listNativeTerminalPgidEntries, loadRegistry } from "../registry.js";
-import { readBootId, readPidNamespaceId } from "../proc-identity.js";
+import { classifyDurableProcFrame, readProcessFrame, } from "../proc-identity.js";
+import { NativeTerminalPublicationRefusal } from "./publication-refusal.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";
@@ -169,7 +170,14 @@ function dispatch(host, context, request) {
             return host.attachObserver(sessionId(params));
         case "acquire-controller": {
             const record = requiredRecord(params, "params");
-            const lease = host.acquireController(requiredIdentifier(record.id, "session id"), requiredIdentifier(record.controllerId, "controller id"), controllerActivity(record.activity));
+            if (record.takeover !== undefined && typeof record.takeover !== "boolean") {
+                throw new TypeError("terminal controller takeover must be a boolean");
+            }
+            const lease = host.acquireController(requiredIdentifier(record.id, "session id"), requiredIdentifier(record.controllerId, "controller id"), controllerActivity(record.activity), {
+                ...(record.takeover !== undefined ? { takeover: record.takeover } : {}),
+                ...(record.pid !== undefined ? { pid: requiredInteger(record.pid, "controller pid") } : {}),
+                ...(record.tty !== undefined ? { tty: requiredString(record.tty, "controller tty") } : {}),
+            });
             context.leases.set(lease.id, lease);
             return lease;
         }
@@ -354,19 +362,6 @@ function consumeFrames(host, context, chunk) {
         context.socket.destroy();
     }
 }
-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, signal) {
     if (process.platform !== "linux" || process.getuid === undefined) {
         throw new Error("native terminal socket publication requires Linux abstract Unix sockets");
@@ -405,11 +400,13 @@ async function socketPublicationLockSecret(socketPath, signal) {
         || 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}`);
+        // T4: a lock-id that is not a private owned file is a coded refusal,
+        // never an undifferentiated startup crash.
+        throw new NativeTerminalPublicationRefusal("H2A_PUBLICATION_LOCK_ID_MALFORMED");
     }
     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}`);
+        throw new NativeTerminalPublicationRefusal("H2A_PUBLICATION_LOCK_ID_MALFORMED");
     }
     return secret;
 }
@@ -444,7 +441,7 @@ async function acquireSocketPublicationLock(socketPath, signal) {
 }
 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 timer = setTimeout(() => deadline.abort(new NativeTerminalPublicationRefusal("H2A_PUBLICATION_LOCK_TIMEOUT")), SOCKET_PUBLICATION_LOCK_TIMEOUT_MS);
     const boundedSignal = signal === undefined ? deadline.signal : AbortSignal.any([signal, deadline.signal]);
     try {
         const lock = await acquireSocketPublicationLock(socketPath, boundedSignal);
@@ -496,14 +493,23 @@ function rollbackEndpoint(socketPath, owned) {
     }
     catch { /* Unknown sidecar ownership is never cleanup authority. */ }
 }
-async function recordEndpointOwner(socketPath, socket, processOwner = { pid: process.pid, startTime: readProcessStartTime(process.pid) }, signal) {
+async function recordEndpointOwner(socketPath, socket, processOwner = { pid: process.pid, startTime: readProcessStartTime(process.pid) }, signal, frame, 
+/**
+ * Stamp a frame OTHER than the reader's current one: used only by the
+ * proof-preservation pass, which re-records an identity that a durable row
+ * already PROVED dead at a PREVIOUS boot of this machine. Every stamped
+ * value (pid, start-time, boot, namespace, machine) then comes from that
+ * one row — a coherent epoch — never a mix of a dead boot's numbers with
+ * the current boot's frame.
+ */
+stampFrame) {
     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) {
+    frame = stampFrame ?? frame;
+    if (startTime === undefined || frame.bootId === undefined || frame.pidNamespace === undefined) {
         throw new Error("cannot certify native host process identity");
     }
     const temporary = `${socketPath}.owner.${process.pid}.${randomUUID()}.tmp`;
@@ -527,7 +533,10 @@ async function recordEndpointOwner(socketPath, socket, processOwner = { pid: pro
         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);
+        await abortable(writeFile(openedFile, JSON.stringify({ ...socket, pid, startTime, bootId: frame.bootId,
+            pidNamespace: frame.pidNamespace, ...(frame.machineId !== undefined ? { machineId: frame.machineId } : {}),
+            ...(frame.nsNet !== undefined ? { nsNet: frame.nsNet } : {}),
+            ...(frame.bootTimeMs !== undefined ? { bootTimeMs: frame.bootTimeMs } : {}) }), signal === undefined ? {} : { signal }), signal);
         signal?.throwIfAborted();
         await abortable(rename(temporary, `${socketPath}.owner`), signal);
     }
@@ -563,12 +572,12 @@ async function recordEndpointOwner(socketPath, socket, processOwner = { pid: pro
  * 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) {
+export async function proveNativeTerminalEndpointAbsent(socketPath, failure, readFrame = readProcessFrame, ownerProbe = defaultOwnerHostProbe) {
     const code = failure?.code;
     if (code !== "ENOENT" && code !== "ECONNREFUSED")
         return false;
     await ensurePrivateSocketDirectory(socketPath);
-    return withSocketPublicationLock(socketPath, signal => proveEndpointAbsentUnderLock(socketPath, signal));
+    return withSocketPublicationLock(socketPath, signal => proveEndpointAbsentUnderLock(socketPath, signal, readPublicationFrame(readFrame), ownerProbe));
 }
 function canonicalizePath(targetPath) {
     const resolved = resolve(targetPath);
@@ -587,7 +596,7 @@ function canonicalizePath(targetPath) {
         }
     }
 }
-function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST_PROC_ROOT ?? "/proc") {
+function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST_PROC_ROOT ?? "/proc", ownerProbe = defaultOwnerHostProbe) {
     if (process.env.H2A_TEST_PROC_UNAVAILABLE) {
         return { state: "unknown", reason: "simulated /proc observation unavailable" };
     }
@@ -611,6 +620,15 @@ function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST
             reason: `cannot canonicalize target socket path: ${socketPath}`,
         };
     }
+    const targetDirectory = statSync(dirname(targetCanonical));
+    let targetSocket;
+    try {
+        targetSocket = statSync(targetCanonical);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
     for (const entry of entries) {
         if (!/^\d+$/.test(entry))
             continue;
@@ -654,14 +672,24 @@ function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST
         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}`,
-            };
+        let sameCandidateSocket = false;
+        if (targetSocket) {
+            try {
+                sameCandidateSocket = sameNativeTerminalSocket(statSync(candidateSocket), targetSocket);
+            }
+            catch { /* An absent published name supplies no direct inode evidence. */ }
         }
-        if (candidateCanonical !== targetCanonical)
+        // Staged stems collide between the primary and lf1 endpoints. A native
+        // publication keeps its full basename; only direct socket identity can
+        // override a different endpoint name or a different resolved path.
+        if (!sameCandidateSocket && basename(resolve(candidateSocket)) !== basename(targetCanonical))
+            continue;
+        // An ancestor alias can have been retargeted since bind. Its current
+        // resolution alone cannot exclude the old target; pinned bind evidence can.
+        const candidateAliased = candidateCanonical !== undefined && candidateCanonical !== resolve(candidateSocket);
+        const couldServeTarget = candidateCanonical === undefined
+            || candidateCanonical === targetCanonical || sameCandidateSocket || candidateAliased;
+        if (!couldServeTarget)
             continue;
         const candDir = dirname(candidateSocket);
         let isStagingCandidate = false;
@@ -689,20 +717,20 @@ function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST
             };
         }
         let hasSocketFd = false;
-        let unixSockets;
+        const descriptorLinks = new Map();
+        let unreadableDescriptor;
         for (const fd of fds) {
-            let link;
             try {
-                link = readlinkSync(join(fdDir, fd));
+                descriptorLinks.set(fd, 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)}`,
-                };
+                unreadableDescriptor = `cannot readlink /proc/${pid}/fd/${fd}: ${String(err)}`;
             }
+        }
+        let unixSockets;
+        for (const link of descriptorLinks.values()) {
             const inode = /^socket:\[(\d+)\]$/.exec(link)?.[1];
             if (!inode)
                 continue;
@@ -722,25 +750,70 @@ function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST
             // 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
-                && isStagedSocketName(basename(boundPath), candidateSocket, pid))))
+            if (!boundPath || !boundPath.startsWith("/"))
                 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)
-                && isStagedSocketName(basename(canonicalBound), candidateSocket, pid))) {
+            let sameSocket = false;
+            if (targetSocket) {
+                try {
+                    sameSocket = sameNativeTerminalSocket(statSync(boundPath), targetSocket);
+                }
+                catch { /* An unlinked staging name has no filesystem inode to compare. */ }
+            }
+            const stagedForTarget = isStagedSocketName(basename(boundPath), socketPath, pid);
+            if (sameSocket) {
                 hasSocketFd = true;
                 break;
             }
+            // Prefer the pinned directory even when its old pathname resolves again:
+            // a replacement directory at that name is a different endpoint. The bind
+            // directory is canonical, so its FD stays attributable after alias loss.
+            // Never compare the sockfs inode with a VFS inode.
+            // The Unix-table row above belongs to a socket this PID actually holds.
+            const nativeListener = boundPath === candidateSocket
+                || isStagedSocketName(basename(boundPath), candidateSocket, pid);
+            if (!nativeListener)
+                continue;
+            let boundDirectory;
+            for (const [fd, path] of descriptorLinks) {
+                if (path !== dirname(boundPath) && path !== `${dirname(boundPath)} (deleted)`)
+                    continue;
+                try {
+                    const info = statSync(join(fdDir, fd));
+                    if (info.isDirectory() && (path === dirname(boundPath) || info.nlink === 0)) {
+                        boundDirectory = info;
+                        break;
+                    }
+                }
+                catch { /* Missing directory evidence remains unknown below. */ }
+            }
+            if (boundDirectory && !sameNativeTerminalSocket(boundDirectory, targetDirectory))
+                continue;
+            if (boundDirectory && (stagedForTarget || basename(boundPath) === basename(targetCanonical))) {
+                hasSocketFd = true;
+                break;
+            }
+            // Older hosts have no directory FD. Resolvable bind evidence can still
+            // attribute them; only an opaque listener of this same endpoint remains
+            // unknown. Distinct endpoint names were excluded before FD inspection.
+            if (canonicalBound === targetCanonical || (canonicalBound !== undefined
+                && dirname(canonicalBound) === dirname(targetCanonical) && stagedForTarget)) {
+                hasSocketFd = true;
+                break;
+            }
+            if (canonicalBound !== undefined && !candidateAliased)
+                continue;
+            return { state: "unknown", reason: `cannot attribute bound socket directory for host pid ${pid}` };
         }
+        if (!hasSocketFd && unreadableDescriptor)
+            return { state: "unknown", reason: unreadableDescriptor };
         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 });
+        const probe = ownerProbe({ pid, startTime });
         if (probe === "alive") {
             return { state: "live", pid, startTime };
         }
@@ -750,7 +823,71 @@ function findActiveHostServingSocket(socketPath, procRoot = process.env.H2A_TEST
     }
     return { state: "absent" };
 }
-async function proveEndpointAbsentUnderLock(socketPath, signal) {
+function readPublicationFrame(readFrame) {
+    const frame = readFrame();
+    if (frame.machineId === undefined || !/^[0-9a-f]{32}$/.test(frame.machineId) || /^0+$/.test(frame.machineId)) {
+        throw new NativeTerminalPublicationRefusal("H2A_MACHINE_ID_UNREADABLE");
+    }
+    if (classifyDurableProcFrame(frame, frame) !== "current") {
+        throw new NativeTerminalPublicationRefusal("H2A_PROC_FRAME_UNKNOWN");
+    }
+    return frame;
+}
+/** A refused connect says only that nobody accepts now. All five refusals
+ * must complete within the global budget; every attempt has its own timer.
+ * Abort destroys the socket and cancels the interval before the lock releases. */
+async function repeatedlyRefusesConnection(socketPath, socketPresent, signal) {
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(new NativeTerminalPublicationRefusal("H2A_ENDPOINT_PROBE_TIMEOUT")), 2_000);
+    const bounded = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    try {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            bounded.throwIfAborted();
+            const refusal = await new Promise((resolve, reject) => {
+                const connection = createConnection(socketPath);
+                const finish = (error, refused = false) => {
+                    clearTimeout(unitTimer);
+                    bounded.removeEventListener("abort", cancel);
+                    connection.destroy();
+                    if (error !== undefined)
+                        reject(error);
+                    else
+                        resolve(refused);
+                };
+                const cancel = () => finish(bounded.reason);
+                const unitTimer = setTimeout(() => finish(new NativeTerminalPublicationRefusal("H2A_ENDPOINT_PROBE_TIMEOUT")), 500);
+                bounded.addEventListener("abort", cancel, { once: true });
+                connection.once("connect", () => finish());
+                connection.once("error", error => {
+                    const code = error.code;
+                    if (code === "ECONNREFUSED" || (!socketPresent && code === "ENOENT"))
+                        finish(undefined, true);
+                    else
+                        finish(error);
+                });
+            });
+            if (!refusal)
+                return false;
+            if (attempt < 4) {
+                await new Promise((resolve, reject) => {
+                    const cancel = () => { clearTimeout(interval); reject(bounded.reason); };
+                    const interval = setTimeout(() => { bounded.removeEventListener("abort", cancel); resolve(); }, 250);
+                    bounded.addEventListener("abort", cancel, { once: true });
+                    if (bounded.aborted)
+                        cancel();
+                });
+            }
+        }
+        bounded.throwIfAborted();
+        return true;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Caller holds withSocketPublicationLock through classification, probes,
+ * inode recheck, reclamation, link and owner stamping (R2). */
+async function proveEndpointAbsentUnderLock(socketPath, signal, currentFrame, ownerProbe = defaultOwnerHostProbe) {
     signal?.throwIfAborted();
     let socket;
     try {
@@ -760,95 +897,135 @@ async function proveEndpointAbsentUnderLock(socketPath, signal) {
         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;
-    }
+    // Normative order: active scan, all three sources, classification, probes.
+    // A live host serving this endpoint — including an OLDER published host
+    // during an upgrade (scenario 9) — is the strongest refusal there is: the
+    // candidate must never unlink or republish over it.
+    // Seam symmetry (F4): the scan liveness probe is the INJECTED ownerProbe so
+    // the "zero probes for stale-boot sources" assertions observe this path too.
+    const activeScan = findActiveHostServingSocket(socketPath, undefined, ownerProbe);
+    if (activeScan.state === "live")
+        throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_LIVE_OWNER");
     if (activeScan.state === "unknown") {
-        throw new Error(`terminal host state is unprovable (${activeScan.reason}): ${socketPath}`);
+        // The frozen literal carries the sense (T8); the scan's own reason (e.g.
+        // which /proc view was unreadable) rides as `cause` so operators keep the
+        // diagnostic the old generic throw used to inline.
+        throw Object.assign(new NativeTerminalPublicationRefusal("H2A_ENDPOINT_SCAN_UNKNOWN"), {
+            cause: new Error(activeScan.reason),
+        });
     }
+    let sidecar;
+    const ownerPath = `${socketPath}.owner`;
     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}`);
+            throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_OWNER_MALFORMED");
         }
-        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}`);
+        try {
+            const parsed = JSON.parse(await abortable(readFile(ownerPath, "utf8"), signal));
+            // Valid JSON that is not an object (null, a bare string, a number) is
+            // the same coded refusal (T4): the shape is validated BEFORE any
+            // property access, never an undifferentiated TypeError crash (exit 1).
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_OWNER_MALFORMED");
+            }
+            sidecar = parsed;
+        }
+        catch (error) {
+            if (signal?.aborted || error instanceof NativeTerminalPublicationRefusal)
+                throw error;
+            // Unparseable sidecar content is a coded refusal (T4), never an
+            // undifferentiated crash: the file is local fail-closed evidence.
+            throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_OWNER_MALFORMED");
+        }
+        if (!Number.isSafeInteger(sidecar.pid) || sidecar.pid <= 0 || !Number.isSafeInteger(sidecar.startTime) ||
+            sidecar.startTime < 0 || !Number.isSafeInteger(sidecar.dev) || !Number.isSafeInteger(sidecar.ino) ||
+            typeof sidecar.bootId !== "string" || typeof sidecar.pidNamespace !== "string" ||
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(sidecar.bootId) || !/^\d+$/.test(sidecar.pidNamespace) ||
+            (sidecar.machineId !== undefined && typeof sidecar.machineId !== "string")) {
+            throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_OWNER_MALFORMED");
         }
-        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 (!snapshot.known && snapshot.reason !== "registry is absent")
+        throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_REGISTRY_UNKNOWN");
     if (registry.state === "unknown" || registry.unreadable.length > 0)
+        throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_REGISTRY_UNKNOWN");
+    const canonicalTarget = canonicalizePath(socketPath);
+    if (!canonicalTarget)
+        throw new Error(`cannot canonicalize socket path: ${socketPath}`);
+    const matches = (path) => path !== undefined && canonicalizePath(path) === canonicalTarget;
+    const attributedRows = registry.entries.filter(row => matches(row.ownerHostSocketPath));
+    const attributedPgid = snapshot.known ? snapshot.entries.filter(entry => matches(entry.owner?.socketPath)) : [];
+    // Legacy sidecars are local, unattributed evidence (R3); registry and pgid
+    // records without a machine anchor remain blocking foreign frames (R1).
+    const sidecarVerdict = sidecar?.machineId === undefined ? undefined : classifyDurableProcFrame(sidecar, currentFrame);
+    const classifiedPgid = attributedPgid.map(entry => ({ entry, verdict: classifyDurableProcFrame(entry.frame, currentFrame) }));
+    const classifiedRows = attributedRows.map(row => ({ row, verdict: classifyDurableProcFrame({
+            pidNamespace: row.pgidPidNamespace, bootId: row.pgidBootId, machineId: row.pgidMachineId,
+        }, currentFrame) }));
+    if ((socket && sidecar && !sameNativeTerminalSocket(socket, sidecar)) || sidecarVerdict === "foreign-frame" ||
+        classifiedPgid.some(item => item.verdict === "foreign-frame") || classifiedRows.some(item => item.verdict === "foreign-frame"))
         return false;
-    const rows = registry.entries.filter(entry => entry.ownerHostSocketPath && canonicalizePath(entry.ownerHostSocketPath) === canonicalTarget);
-    if (rows.some(row => row.pgidBootId !== readBootId() || row.pgidPidNamespace !== readPidNamespaceId()))
+    // Owners are derived only AFTER every source has been classified.
+    const currentOwners = [];
+    if (sidecarVerdict === "current" && sidecar)
+        currentOwners.push(sidecar);
+    for (const { entry, verdict } of classifiedPgid)
+        if (verdict === "current" && entry.owner)
+            currentOwners.push(entry.owner);
+    for (const { row, verdict } of classifiedRows)
+        if (verdict === "current") {
+            if (row.ownerHostPid === undefined)
+                return false;
+            currentOwners.push({ pid: row.ownerHostPid, ...(row.ownerHostStartTime !== undefined ? { startTime: row.ownerHostStartTime } : {}) });
+        }
+    const uniqueOwners = [...new Map(currentOwners.map(owner => [`${owner.pid}:${owner.startTime}`, owner])).values()];
+    const ownersDead = uniqueOwners.every(owner => owner.startTime !== undefined && ownerProbe(owner) === "dead");
+    const sidecarProvesDeath = sidecarVerdict === "stale-boot" || (sidecarVerdict === "current" && ownersDead);
+    // Even a run of refusals cannot prove a new, unattributed holder dead.
+    if (!await repeatedlyRefusesConnection(socketPath, socket !== undefined, signal))
         return false;
-    if (owners.some(owner => owner.startTime === undefined || defaultOwnerHostProbe(owner) !== "dead"))
+    let preBootInode = false;
+    try {
+        const final = await abortable(lstat(socketPath), signal);
+        if (!socket || !sameNativeTerminalSocket(socket, final))
+            return false;
+        preBootInode = currentFrame.bootTimeMs !== undefined && Number.isFinite(currentFrame.bootTimeMs) && currentFrame.bootTimeMs > 0 &&
+            final.birthtimeMs > 0 && final.birthtimeMs < currentFrame.bootTimeMs;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        if (socket)
+            return false;
+    }
+    if (!ownersDead)
+        return false;
+    const staleProof = classifiedRows.find(item => item.verdict === "stale-boot" && item.row.ownerHostPid !== undefined && item.row.ownerHostStartTime !== undefined)?.row;
+    const currentDead = uniqueOwners[0];
+    // Stale rows prove the death of their AUTHORS, never the absence of a NEW
+    // holder of the pathname (R4-probe): they cannot bypass the age/liveness
+    // proof. Without a sidecar death proof or a CURRENT-boot owner positively
+    // probed dead, an existing socket yields publication only to the pre-boot
+    // inode proof (R3 combo 4): an inode created during this boot may have a
+    // live, unattributed holder that refused every connect probe.
+    if (socket && !sidecarProvesDeath && currentDead === undefined && !preBootInode)
         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);
+    if (socket && currentDead !== undefined) {
+        await recordEndpointOwner(socketPath, socket, { pid: currentDead.pid, startTime: currentDead.startTime }, signal, currentFrame);
+    }
+    else if (socket && !sidecarProvesDeath && staleProof !== undefined) {
+        await recordEndpointOwner(socketPath, socket, { pid: staleProof.ownerHostPid, startTime: staleProof.ownerHostStartTime }, signal, currentFrame, { bootId: staleProof.pgidBootId, pidNamespace: staleProof.pgidPidNamespace, machineId: staleProof.pgidMachineId });
     }
-    return socket === undefined || owners.length > 0;
+    return true;
 }
-async function removeStaleSocket(socketPath, signal) {
+async function removeStaleSocket(socketPath, signal, frame, ownerProbe = defaultOwnerHostProbe) {
     for (;;) {
         signal?.throwIfAborted();
         let stale;
@@ -860,11 +1037,8 @@ async function removeStaleSocket(socketPath, signal) {
                 return;
             throw error;
         }
-        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}`);
+        if (!await proveEndpointAbsentUnderLock(socketPath, signal, frame, ownerProbe)) {
+            throw new NativeTerminalPublicationRefusal("H2A_STALE_SOCKET_UNPROVEN");
         }
         try {
             const current = await abortable(inspectPrivateNativeTerminalSocket(socketPath), signal);
@@ -958,7 +1132,7 @@ function stagingSocketPath(socketPath) {
     assertNativeTerminalSocketPathWithinLimit(stagedPath, "terminal host staging socket path");
     return stagedPath;
 }
-async function publishSocket(stagedPath, socketPath, signal) {
+async function publishSocket(stagedPath, socketPath, signal, frame, ownerProbe = defaultOwnerHostProbe) {
     signal.throwIfAborted();
     const staged = await abortable(inspectPrivateNativeTerminalSocket(stagedPath), signal);
     try {
@@ -967,8 +1141,8 @@ async function publishSocket(stagedPath, 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}`);
+        if (!await proveEndpointAbsentUnderLock(socketPath, signal, frame, ownerProbe)) {
+            throw new NativeTerminalPublicationRefusal("H2A_ENDPOINT_OWNER_UNPROVEN");
         }
     }
     for (let attempt = 0; attempt < 200; attempt += 1) {
@@ -985,7 +1159,7 @@ async function publishSocket(stagedPath, socketPath, signal) {
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
-            await removeStaleSocket(socketPath, signal);
+            await removeStaleSocket(socketPath, signal, frame, ownerProbe);
         }
     }
     throw new Error("terminal host socket publication retry limit exceeded");
@@ -1005,7 +1179,7 @@ const LISTENER_EXHAUSTION_WINDOW_MS = 60_000;
 const UNUSABLE_LISTENER_ERRNOS = new Set(["ERR_SERVER_CLOSED", "EADDRINUSE", "EADDRNOTAVAIL", "EBADF", "EINVAL", "ENOTSOCK", "EACCES"]);
 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 timer = setTimeout(() => deadline.abort(new NativeTerminalPublicationRefusal("H2A_SOCKET_PUBLICATION_TIMEOUT")), SOCKET_PUBLICATION_LOCK_TIMEOUT_MS);
     const signal = options.signal === undefined ? deadline.signal : AbortSignal.any([options.signal, deadline.signal]);
     try {
         return await initializeNativeTerminalHostServer({ ...options, signal });
@@ -1067,13 +1241,27 @@ async function initializeNativeTerminalHostServer(options) {
             sockets.delete(socket);
         });
     });
-    const stagedPath = stagingSocketPath(options.socketPath);
+    // bind(2) retains this literal path in /proc/net/unix. Resolve its directory
+    // before binding so it agrees with the retained directory FD even if an
+    // ancestor symlink is later removed. Keep the published path and grammar.
+    const stagedPath = stagingSocketPath(join(realpathSync(dirname(options.socketPath)), basename(options.socketPath)));
+    let directoryFd;
+    const closeDirectory = () => {
+        if (directoryFd !== undefined) {
+            closeSync(directoryFd);
+            directoryFd = undefined;
+        }
+    };
     let ownedSocket;
     // Assigned once the published close is built; the listener-failure handler
     // (installed before that object exists) tears the server down through it.
     let closePublished;
     let initializationFailure;
     try {
+        // Keep the real directory inode observable through /proc/<pid>/fd even
+        // after its pathname is deleted. The bind name and staging grammar stay
+        // compatible with older readers; no private-state census is introduced.
+        directoryFd = openSync(dirname(stagedPath), constants.O_RDONLY | constants.O_DIRECTORY);
         await abortable(new Promise((resolve, reject) => {
             server.once("error", reject);
             server.listen(stagedPath, () => {
@@ -1142,12 +1330,16 @@ async function initializeNativeTerminalHostServer(options) {
         };
         // Capture the listener's inode before any publication await can suspend.
         ownedSocket = lstatSync(stagedPath);
+        if (!sameNativeTerminalSocket(fstatSync(directoryFd), statSync(dirname(stagedPath)))) {
+            throw new Error("terminal host socket directory changed during bind");
+        }
         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);
+                const frame = readPublicationFrame(options.readFrame ?? readProcessFrame);
+                const published = await publishSocket(stagedPath, options.socketPath, signal, frame, options.ownerProbe ?? defaultOwnerHostProbe);
+                await recordEndpointOwner(options.socketPath, published, undefined, signal, frame);
                 return published;
             }
             catch (pubError) {
@@ -1163,14 +1355,19 @@ async function initializeNativeTerminalHostServer(options) {
         }
     }
     catch (error) {
-        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);
+        try {
+            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));
+        }
+        finally {
+            closeDirectory();
         }
-        await abortable(closed, AbortSignal.timeout(SOCKET_PUBLICATION_CLEANUP_TIMEOUT_MS));
         throw error;
     }
     readyForRequests = true;
@@ -1208,7 +1405,7 @@ async function initializeNativeTerminalHostServer(options) {
             });
             if (stopError !== undefined)
                 throw stopError;
-        })();
+        })().finally(closeDirectory);
         return closing;
     };
     closePublished = doClose;