@sentropic/h2a-runtime 0.97.11 → 0.97.12

package/dist/native-terminal/host.js

@@ -1,5 +1,6 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
 // Durable session identity (incl. pgid) lives in the single registry store by
 // design — one local store per the owner's durable-state direction (see the
 // longer rationale on `persistNativeTerminalPgid`/`readNativeTerminalPgid` in
@@ -8,6 +9,9 @@ import { randomUUID } from "node:crypto";
 // ONLY for pgid durability across a host crash, nothing else here reads or
 // writes registry state.
 import { listNativeTerminalPgidEntries, persistNativeTerminalPgid, pruneNativeTerminalPgidEntry, readNativeTerminalPgid, } from "../registry.js";
+// The pid-namespace/boot/machine anchor a durable row is only re-provable
+// within — the SAME definition the row was written with (see proc-identity.ts).
+import { readBootId, readMachineId, readPidNamespaceId } from "../proc-identity.js";
 import { TerminalReplayBuffer, } from "./replay-buffer.js";
 import { NATIVE_TERMINAL_DEFAULT_MAX_SESSIONS, NATIVE_TERMINAL_MAX_IDENTIFIER_CHARS, NATIVE_TERMINAL_MAX_SESSIONS, } from "./protocol.js";
 function isErrnoException(error) {
@@ -228,6 +232,231 @@ export function groupCarriesSessionToken(pgid, expectedToken) {
     }
     return false;
 }
+/** Only these two errno values mean "this pid is gone", never "unreadable". */
+function isGoneErrno(error) {
+    return (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ESRCH"));
+}
+/**
+ * State (field 3) and process-group id (field 5) of one `/proc/.../stat` line.
+ * Anchors on the LAST `") "` for the reason `readProcessStartTime` documents at
+ * length (a `comm` field can itself contain spaces and parentheses). Returns
+ * undefined when the line cannot be parsed — the caller must treat that as
+ * "unknown", never as a state.
+ */
+function parseStatStateAndPgrp(raw) {
+    const splitAt = raw.lastIndexOf(") ");
+    if (splitAt < 0)
+        return undefined;
+    const fields = raw.slice(splitAt + 2).split(" ");
+    const state = fields[0];
+    const pgrp = Number(fields[2]);
+    if (state === undefined || state.length === 0)
+        return undefined;
+    if (!Number.isInteger(pgrp))
+        return undefined;
+    return { state, pgrp };
+}
+/**
+ * Whether the proc filesystem mounted at `procRoot` HIDES other processes
+ * (`hidepid=1`/`2`/`invisible`, i.e. systemd's `ProtectProc=`). Under
+ * `hidepid=2` a live process owned by another uid is not even listed by
+ * `readdir`, so a census cannot detect it by reading anything: only the mount
+ * option itself reveals that the view is partial.
+ *
+ * Three-valued on purpose: `true` = positively hidden, `false` = positively NOT
+ * hidden, `undefined` = the mount table could not be read OR describes no proc
+ * mount at `procRoot` at all, neither of which is evidence of a complete view.
+ * Callers requiring a complete view must accept `false` only.
+ */
+function procMountHidesProcesses(procRoot) {
+    let raw;
+    try {
+        raw = readFileSync(`${procRoot}/self/mountinfo`, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    // `false` is a POSITIVE claim ("this mount does not hide processes"), so it
+    // may only be returned once a line actually describing this proc mount was
+    // seen. A mount table that names no such mount (a fixture tree, a reader
+    // pointed at a copy, an unexpected layout) leaves the frame unknown — the
+    // same epistemic state as a table that could not be read.
+    let sawProcMountAtRoot = false;
+    for (const line of raw.split("\n")) {
+        // mountinfo: `id parent major:minor root mountPoint options... - fstype source superOptions`.
+        const separator = line.indexOf(" - ");
+        if (separator < 0)
+            continue;
+        if (line.split(" ")[4] !== procRoot)
+            continue;
+        const post = line.slice(separator + 3).split(" ");
+        if (post[0] !== "proc")
+            continue;
+        sawProcMountAtRoot = true;
+        const option = (post[2] ?? "")
+            .split(",")
+            .find((candidate) => candidate.startsWith("hidepid="));
+        if (option === undefined)
+            continue;
+        const value = option.slice("hidepid=".length);
+        if (value !== "0" && value !== "off")
+            return true;
+    }
+    return sawProcMountAtRoot ? false : undefined;
+}
+/**
+ * The EFFECTIVE state of a thread group (`/proc/<tgid>/task/*`): `"Z"` only
+ * when EVERY task is a zombie, otherwise the state of the first task that is
+ * not. Undefined when the task list, or any task's `stat`, could not be read —
+ * including a task that vanished mid-read, which does NOT prove the process
+ * gone (a surviving sibling thread keeps it alive).
+ *
+ * This exists because `/proc/<tgid>/stat` reports the state of the thread-group
+ * LEADER task alone. A process whose main thread called `pthread_exit()` while
+ * another thread keeps running is a DELAYED zombie: the leader is `Z`, the
+ * process is ALIVE, executes code and can fork (`ps` shows `Zl <defunct>`).
+ * Reading the leader's `Z` as "this member is dead" is a false death verdict.
+ */
+function threadGroupState(pid, procRoot) {
+    let tids;
+    try {
+        tids = readdirSync(`${procRoot}/${pid}/task`);
+    }
+    catch {
+        return undefined;
+    }
+    let seen = 0;
+    for (const tid of tids) {
+        if (!/^\d+$/.test(tid))
+            continue;
+        let raw;
+        try {
+            raw = readFileSync(`${procRoot}/${pid}/task/${tid}/stat`, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const parsed = parseStatStateAndPgrp(raw);
+        if (parsed === undefined)
+            return undefined;
+        seen += 1;
+        if (parsed.state !== "Z")
+            return parsed.state;
+    }
+    return seen === 0 ? undefined : "Z";
+}
+/**
+ * One census of process group `pgid`: pid -> EFFECTIVE state, for every process
+ * the scan could see. Undefined means the census could not be taken COMPLETELY
+ * — distinct from an empty map, which means "the scan ran and showed no
+ * member". Refuses to answer at all unless:
+ *
+ *  - the platform is Linux and the proc mount positively does NOT hide
+ *    processes (see `procMountHidesProcesses`);
+ *  - every `stat` it needed either read successfully or failed with
+ *    ENOENT/ESRCH, the ONLY two errors that mean "this pid exited mid-scan".
+ *    EACCES, EIO or anything else means a member exists that we cannot see, so
+ *    the whole census is unknown;
+ *  - every zombie member's own task list confirmed all its threads are zombies
+ *    (see `threadGroupState`).
+ */
+function censusProcessGroup(pgid, procRoot) {
+    if (process.platform !== "linux")
+        return undefined;
+    if (procMountHidesProcesses(procRoot) !== false)
+        return undefined;
+    let names;
+    try {
+        names = readdirSync(procRoot);
+    }
+    catch {
+        return undefined;
+    }
+    const members = new Map();
+    for (const name of names) {
+        if (!/^\d+$/.test(name))
+            continue;
+        let raw;
+        try {
+            raw = readFileSync(`${procRoot}/${name}/stat`, "utf8");
+        }
+        catch (error) {
+            if (isGoneErrno(error))
+                continue; // exited mid-scan: not a member
+            return undefined; // unreadable: a member may exist that we cannot see
+        }
+        const parsed = parseStatStateAndPgrp(raw);
+        if (parsed === undefined)
+            return undefined;
+        if (parsed.pgrp !== pgid)
+            continue;
+        const pid = Number(name);
+        if (parsed.state !== "Z") {
+            members.set(pid, parsed.state);
+            continue;
+        }
+        // A `Z` leader task proves nothing about the process: check every thread.
+        const effective = threadGroupState(pid, procRoot);
+        if (effective === undefined)
+            return undefined;
+        members.set(pid, effective);
+    }
+    return members;
+}
+/**
+ * True iff two CONSECUTIVE censuses of `pgid` both positively show the SAME,
+ * non-empty set of members and every one of them is a ZOMBIE down to its last
+ * thread — a group that is DEAD for containment: a zombie is an exit status
+ * waiting to be collected by its parent, it executes nothing, and no terminal
+ * work can ever resume in it.
+ *
+ * Why this needs its own probe: `kill(-pgid, 0)` answers ALIVE for such a
+ * group (a zombie is still attached to its pgid), and a zombie's
+ * `/proc/<pid>/environ` is empty, so it can carry no session token either.
+ * Without this re-check, the leader-absent branch of
+ * `#verifyGroupLeaderIdentity` classifies the group as
+ * `membership-unprovable` — an unidentifiable SURVIVOR — and a socket is then
+ * contained on account of processes that are already dead. Emitting
+ * `kill(-pgid, SIGKILL)` there would not help either: a zombie cannot be
+ * killed again, so the confirmation poll would run to its timeout.
+ *
+ * What this DOES fail closed on (answer `false`, i.e. "not proven dead"):
+ * non-Linux; a proc mount that hides processes or whose mount table could not
+ * be read; any member `stat` unreadable for a reason other than "it exited";
+ * any zombie member whose thread list could not be fully read; a group with no
+ * member at all (which contradicts the liveness probe that led here and is
+ * therefore not evidence of anything); and two censuses that disagree.
+ *
+ * DECLARED LIMIT, not closed by this: a census is not atomic. A live member can
+ * fork a child that inherits the pgid and exit before its own `stat` is read;
+ * the second census is what makes that shape answer `false` (the child is
+ * listed, or the member set changed), which NARROWS the race rather than
+ * eliminating it. The residual requires a member to fork and exit inside both
+ * censuses while leaving an identical, all-zombie pid set behind — and the
+ * consequence of the residual is bounded by what a caller does with a `true`:
+ * nothing is ever signalled on this path.
+ *
+ * `procRoot` is injected ONLY by tests (a `/proc`-shaped fixture tree, and a
+ * function form so a test can make the two censuses see different trees);
+ * production always reads the real `/proc`.
+ */
+export function groupIsOnlyZombies(pgid, procRoot = "/proc") {
+    const root = () => (typeof procRoot === "function" ? procRoot() : procRoot);
+    const first = censusProcessGroup(pgid, root());
+    if (first === undefined || first.size === 0)
+        return false;
+    for (const state of first.values())
+        if (state !== "Z")
+            return false;
+    const second = censusProcessGroup(pgid, root());
+    if (second === undefined || second.size !== first.size)
+        return false;
+    for (const [pid, state] of second) {
+        if (state !== "Z" || !first.has(pid))
+            return false;
+    }
+    return true;
+}
 function processExists(pid) {
     try {
         process.kill(pid, 0);
@@ -280,8 +509,26 @@ export const defaultOwnerHostProbe = (owner) => {
 function delay(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
-const NATIVE_TERMINAL_FORCE_KILL_TIMEOUT_MS = 30_000;
+/** How long a group kill waits for the OS to report the group empty before
+ * reporting it timed out. Exported so a caller that budgets a wait around a
+ * reap (the functional suite) derives it from this value instead of copying it. */
+export const NATIVE_TERMINAL_FORCE_KILL_TIMEOUT_MS = 30_000;
 const NATIVE_TERMINAL_FORCE_KILL_POLL_INTERVAL_MS = 50;
+/** Deferred pty-exit prune: retry spacing and attempt budget (hygiene only —
+ * see `#schedulePruneOfExitedSession`). 8 x 25 ms bounds how long a contended
+ * registry keeps one exited session's timer alive. */
+const NATIVE_TERMINAL_PRUNE_RETRY_DELAY_MS = 25;
+const NATIVE_TERMINAL_PRUNE_MAX_ATTEMPTS = 8;
+function readCurrentProcFrame() {
+    const pidNamespace = readPidNamespaceId();
+    const bootId = readBootId();
+    const machineId = readMachineId();
+    return {
+        ...(pidNamespace !== undefined ? { pidNamespace } : {}),
+        ...(bootId !== undefined ? { bootId } : {}),
+        ...(machineId !== undefined ? { machineId } : {}),
+    };
+}
 export class NativeTerminalHost {
     #generation;
     #replayBytesPerSession;
@@ -289,17 +536,24 @@ export class NativeTerminalHost {
     #spawner;
     #sessions = new Map();
     #registryPath;
+    #socketPath;
     #reaper;
     #log;
     #forceKillTimeoutMs;
     #forceKillPollIntervalMs;
     #readLeaderStartTime;
     #findGroupMemberToken;
+    #groupIsOnlyZombies;
+    #readFrame;
     #pgidGuardCounters = {
         recycled: 0,
+        staleBoot: 0,
+        foreignFrame: 0,
         membershipUnprovable: 0,
         unverifiedLegacy: 0,
         tokenVerified: 0,
+        zombieGroup: 0,
+        groupDrained: 0,
     };
     constructor(options) {
         if (options.generation.trim().length === 0 ||
@@ -319,6 +573,15 @@ export class NativeTerminalHost {
         this.#maxSessions = maxSessions;
         this.#spawner = options.spawner;
         this.#registryPath = options.registryPath;
+        // NORMALIZED before it is ever recorded: this string is the socket
+        // ATTRIBUTION a supervisor's socket-scoped containment decision is derived
+        // from (see `RegistryEntry.ownerHostSocketPath`), and two spellings of the
+        // same socket — a doubled separator, a "." segment, a relative path —
+        // would compare unequal and fail OPEN. The supervisor normalizes its own
+        // socket path the same way, and normalizes the row's value at comparison
+        // time so rows written before this still match.
+        this.#socketPath =
+            options.socketPath === undefined ? undefined : resolve(options.socketPath);
         this.#reaper = options.reaper ?? posixProcessGroupReaper;
         this.#log =
             options.log ??
@@ -334,12 +597,14 @@ export class NativeTerminalHost {
             options.readLeaderStartTime ?? readProcessStartTime;
         this.#findGroupMemberToken =
             options.findGroupMemberToken ?? groupCarriesSessionToken;
+        this.#groupIsOnlyZombies = options.groupIsOnlyZombies ?? groupIsOnlyZombies;
+        this.#readFrame = options.readFrame ?? readCurrentProcFrame;
     }
     get generation() {
         return this.#generation;
     }
     /**
-     * COUNTABLE per arch condition 1/2: the four DISCERNIBLE outcomes of the
+     * COUNTABLE per arch condition 1/2: the five DISCERNIBLE outcomes of the
      * group-leader-identity guard, so "has this guard ever refused (and why),
      * or ever proceeded WITHOUT the fast leader-start-time proof" is
      * answerable later without re-deriving it from raw logs.
@@ -350,15 +615,30 @@ export class NativeTerminalHost {
      * counted at all (it is the expected common case). `unverifiedLegacy` is
      * an UNPROVEN proceed (the kill WAS emitted) on a row with no baseline —
      * neither a leader-start-time nor a group-token — to check against at
-     * all, the fail-open branch of `#verifyGroupLeaderIdentity`. Never
-     * collapsed: a proven kill and an unproven one must never look alike
-     * here, exactly as a refusal and a proceed must never look alike — see
+     * all, the fail-open branch of `#verifyGroupLeaderIdentity`.
+     * `zombieGroup` is neither a refusal nor a kill: the group was found
+     * reduced to zombies, i.e. already dead, so NOTHING was emitted and the
+     * reap is reported confirmed. `groupDrained` is its sibling: the group was
+     * still there when the checks began and the OS positively reported it EMPTY
+     * when they ended. `staleBoot` is a refusal that PROVES the group gone (the
+     * row predates this boot), counted apart from `recycled` because the two
+     * rest on different facts. `foreignFrame` is a refusal that proves NOTHING
+     * because the row was written in a frame this reader cannot prove is its
+     * own, counted apart from `membershipUnprovable`, which judged a group in
+     * this reader's own process space. Never collapsed: a proven kill, an
+     * unproven one, a refusal that proves death, a refusal that proves nothing,
+     * and an already-dead group must never look alike here — see
      * `NativeTerminalReapOutcome`'s `cause`/`verified`.
      */
     get pgidGuardCounters() {
         return { ...this.#pgidGuardCounters };
     }
     create(options) {
+        if (options.launchFence && (options.launchFence.generation !== this.#generation ||
+            typeof options.launchFence.incarnation !== "string" ||
+            !/^[0-9a-f-]{36}$/.test(options.launchFence.incarnation))) {
+            throw new Error("invalid native launch fence");
+        }
         if (options.id.trim().length === 0 ||
             options.id.length > NATIVE_TERMINAL_MAX_IDENTIFIER_CHARS) {
             throw new RangeError(`terminal session id must contain 1-${NATIVE_TERMINAL_MAX_IDENTIFIER_CHARS} characters`);
@@ -399,20 +679,23 @@ export class NativeTerminalHost {
             // killed has no other way to learn this session's pgid). A session
             // whose pgid did not durably persist would be unreapable after a host
             // crash — refuse to create it rather than leave an untracked child.
-            // The OWNER attribution (this host's own pid + start-time) rides along
-            // on the same durable write: it is what lets a LATER reconcile pass
-            // prove THIS host is dead (not just unreachable) before ever reaping
-            // this row — see `reconcileDeadHostOrphans`. The GROUP-LEADER's own
-            // start-time (leader pid == pgid) and the GROUP token both ride along
-            // the same write for the SAME reason one level down: they are what
-            // let a LATER kill re-prove the group itself is still the one this
-            // row was written for, not a recycled pgid — see
+            // The OWNER attribution (this host's own pid + start-time, plus the
+            // socket it serves) rides along on the same durable write: the pid and
+            // start-time are what let a LATER reconcile pass prove THIS host is
+            // dead (not just unreachable) before ever reaping this row, and the
+            // socket is what keeps a fail-closed containment decision SCOPED to the
+            // supervisor that owns it — see `reconcileDeadHostOrphans`. The
+            // GROUP-LEADER's own start-time (leader pid == pgid) and the GROUP
+            // token both ride along the same write for the SAME reason one level
+            // down: they are what let a LATER kill re-prove the group itself is
+            // still the one this row was written for, not a recycled pgid — see
             // `#verifyGroupLeaderIdentity`.
             const ownStartTime = readProcessStartTime(process.pid);
             const leaderStartTime = this.#readLeaderStartTime(pty.pgid);
             persistNativeTerminalPgid(options.id, pty.pgid, this.#registryPath, {
                 pid: process.pid,
                 ...(ownStartTime === undefined ? {} : { startTime: ownStartTime }),
+                ...(this.#socketPath === undefined ? {} : { socketPath: this.#socketPath }),
             }, leaderStartTime, groupToken);
         }
         catch (error) {
@@ -426,8 +709,9 @@ export class NativeTerminalHost {
         }
         const record = {
             id: options.id,
-            incarnation: randomUUID(),
+            incarnation: options.launchFence?.incarnation ?? randomUUID(),
             pty,
+            groupToken,
             replay: new TerminalReplayBuffer(this.#replayBytesPerSession),
             status: "running",
             exit: null,
@@ -464,6 +748,14 @@ export class NativeTerminalHost {
         record.exitSubscription = record.pty.onExit((event) => {
             if (record.exit !== null)
                 return;
+            // A durable row exists to make this session reapable after THIS host
+            // dies. Once the group is confirmed empty the row can no longer make
+            // anything reapable — it is a stale record that a later host death would
+            // re-examine against whatever holds that pgid NUMBER by then. Drop it
+            // on POSITIVE proof only (see `#pruneDurableRowIfGroupEmpty`), and OFF
+            // this callback: this is node-pty's own synchronous exit callback on the
+            // host's event loop (see `#schedulePruneOfExitedSession`).
+            this.#schedulePruneOfExitedSession(record, "its pty exited");
             const exit = {
                 exitCode: event.exitCode,
             };
@@ -678,6 +970,15 @@ export class NativeTerminalHost {
                 if (outcome.status !== "dead") {
                     errors.push(new Error(`terminal session ${record.id} pgid=${record.pty.pgid} did not confirm dead within ${this.#forceKillTimeoutMs}ms`));
                 }
+                else {
+                    // PROVEN empty by the call above, so the durable row cannot make
+                    // anything reapable any more — the same staleness the pty-exit path
+                    // prunes, reached through the shutdown path instead. This one DOES
+                    // wait for the lock: `forceStopAll` is the graceful-shutdown path, it
+                    // is already asynchronous, and the row should be gone before the host
+                    // exits rather than left to a timer that may never fire.
+                    this.#pruneDurableRowIfGroupEmpty(record, "forceStopAll proved its group dead", { waitForLock: true });
+                }
             }
             catch (error) {
                 errors.push(error);
@@ -696,8 +997,20 @@ export class NativeTerminalHost {
      * this signals NOTHING and returns `"refused"` after logging a LOUD
      * diagnostic — a silent no-op here would recreate the exact
      * invisible-orphan bug this mechanism exists to close.
+     *
+     * `expectedPgid` and `expected.groupToken` are the caller's IMMUTABLE
+     * snapshot of the row, and BOTH are re-compared against the row as it reads
+     * NOW — the same compare-and-delete identity `pruneNativeTerminalPgidEntry`
+     * uses, applied to the kill side. Comparing the pgid NUMBER alone is not
+     * enough: session ids are caller-chosen, so a live host can recreate the
+     * same id within one reconcile pass, and its new PTY leader can be handed
+     * back the pid number the snapshotted group just freed. The re-read then
+     * matches, every identity check below verifies against the NEW row's own
+     * baselines, and a LIVE group is killed. The token is a per-session
+     * `randomUUID`, so a successor never matches it. A caller that omits the
+     * token (a legacy row carries none) does not constrain it.
      */
-    async reapOrphan(sessionId, signal = "SIGKILL", expectedPgid) {
+    async reapOrphan(sessionId, signal = "SIGKILL", expectedPgid, expected) {
         const lookup = readNativeTerminalPgid(sessionId, this.#registryPath);
         if (lookup.status === "unresolved") {
             this.#log(`REFUSING to reap terminal session ${sessionId}: pgid could not be resolved (${lookup.reason}). PROCESSES MAY HAVE SURVIVED — no group kill was issued.`);
@@ -712,10 +1025,30 @@ export class NativeTerminalHost {
                 cause: "pgid-mismatch",
             };
         }
+        // Checked AFTER the pgid, so the common rewrite keeps the diagnostic that
+        // names both pgid numbers. This one catches what that check cannot see: the
+        // row was rewritten for a DIFFERENT group that happens to carry the same
+        // pgid number — the successor's PTY leader was handed back the pid number
+        // the snapshotted group had just freed.
+        if (expected?.groupToken !== undefined &&
+            lookup.groupToken !== expected.groupToken) {
+            this.#log(`REFUSING to reap terminal session ${sessionId}: pgid=${lookup.pgid} still matches the immutable snapshot, but the registry row now carries a DIFFERENT group token — it describes another group under the same session id, reachable at the same pid number. PROCESSES MAY HAVE SURVIVED — no group kill was issued. cause=pgid-mismatch sessionId=${sessionId} resolvedPgid=${lookup.pgid}`);
+            return {
+                sessionId,
+                status: "refused",
+                reason: `the re-resolved row carries a different group token than the immutable snapshot (pgid=${lookup.pgid})`,
+                cause: "pgid-mismatch",
+            };
+        }
         const outcome = await this.#killGroupAndConfirmDead(lookup.pgid, signal, `orphan ${sessionId}`, {
             sessionId,
             persistedLeaderStartTime: lookup.leaderStartTime,
             persistedGroupToken: lookup.groupToken,
+            persistedFrame: {
+                ...(lookup.pidNamespace !== undefined ? { pidNamespace: lookup.pidNamespace } : {}),
+                ...(lookup.bootId !== undefined ? { bootId: lookup.bootId } : {}),
+                ...(lookup.machineId !== undefined ? { machineId: lookup.machineId } : {}),
+            },
         });
         if (outcome.status === "dead") {
             return {
@@ -743,6 +1076,47 @@ export class NativeTerminalHost {
      * of acting, never merely inherited. POSITIVE proof only (INV-1) —
      * ambiguity always REFUSES, never kills. In order:
      *
+     *  0. The row's FRAME (`pgidPidNamespace`/`pgidBootId`/`pgidMachineId`,
+     *     see proc-identity.ts) is checked FIRST, because every comparison below
+     *     is between a number persisted then and a number read now, and that is
+     *     meaningless across a pid namespace, a reboot or a machine. Three cases:
+     *     - SAME, KNOWN pid namespace, DIFFERENT boot id, SAME, KNOWN machine id
+     *       -> the row is from a previous boot of this very pid space on this
+     *       very machine, and a reboot ends every process of the boot before
+     *       it. That is POSITIVE proof that every process this row describes
+     *       has ended — the strongest form of the `recycled` proof, not an
+     *       absence of one. REFUSE (nothing is ever signalled: the pgid NUMBER
+     *       may well be held by an unrelated live group now, and it must not be
+     *       touched) with cause `"stale-boot"`, which reconcile reads as proof
+     *       and prunes the row on. The machine id is what makes this a proof:
+     *       the init pid namespace has the SAME inode on every kernel and a boot
+     *       id is random per boot, so without it the very same two fields are
+     *       also what a row written by ANOTHER machine sharing this registry
+     *       (a networked `$HOME`) looks like — and that machine's group may be
+     *       alive. DECLARED EXCEPTIONS, out of model: a process checkpointed
+     *       before the reboot and restored after it (CRIU) can carry its pid
+     *       across boots, and two machines cloned from one image without
+     *       regenerating machine-id(5) are indistinguishable. h2a never
+     *       checkpoints a PTY host, and a deployment that restores one, or that
+     *       shares one registry between machines with duplicated machine ids,
+     *       must not rely on this proof.
+     *     - Any other mismatch — including an UNKNOWN namespace, boot id or
+     *       (for the boot proof) machine id on either side -> REFUSE, cause
+     *       `"foreign-frame"` (a start-time mismatch would otherwise be read as
+     *       `recycled` and prune the row; a coincidental MATCH would authorize a
+     *       kill at a group this row never described). A pid number means
+     *       nothing outside the frame it was resolved in, so neither proof is
+     *       available there, and neither is any local inspection: blocking.
+     *     - A row that records NO pid-space frame is not refused here — that
+     *       would strand every row written before the field existed — but it
+     *       cannot earn the `recycled` PROOF either (see branch 2).
+     *     DECLARED LIMIT, outside this guard: the already-empty short-circuit in
+     *     `#killGroupAndConfirmDead` answers BEFORE this frame check, so a row
+     *     whose pgid number is empty in this reader's process space is reported
+     *     reaped (and pruned) whatever frame it records. Within one machine that
+     *     is the pre-existing behaviour every row has always had; across
+     *     machines sharing one registry it is NOT a proof, and that deployment
+     *     shape is not covered.
      *  1. Leader **readable**, no start-time baseline was ever persisted (a
      *     legacy row, or a write-time read failure) -> nothing to compare
      *     against -> cannot be checked for recycling at all, so this PROCEEDS
@@ -757,7 +1131,12 @@ export class NativeTerminalHost {
      *     baseline -> the OS reused `pgid` for an unrelated process since
      *     this row was written -> REFUSE, cause `"recycled"` (the defensive
      *     save: without this check, `killGroup` below would have signalled
-     *     an innocent third party).
+     *     an innocent third party). `"recycled"` is also a POSITIVE proof that
+     *     the original group is gone — reconcile prunes the row on it — so it
+     *     requires the row to carry BOTH frame fields (matched in step 0). A row
+     *     with no frame takes the blocking `"membership-unprovable"` instead: the
+     *     mismatch is real, but it cannot prove anything about this reader's pid
+     *     space.
      *  3. Leader **readable**, start-time **MATCHES** -> the group is
      *     provably the one this row was written for -> PROCEED,
      *     `verified: true`.
@@ -774,8 +1153,26 @@ export class NativeTerminalHost {
      *       independent of the leader -> PROCEED, `verified: true`, cause
      *       `"token-verified"`.
      *     - a persisted token exists and NO surviving member carries it ->
-     *       cannot positively prove this group's identity by any means ->
-     *       REFUSE, cause `"membership-unprovable"` (conservative
+     *       ONE re-check before refusing: a group the OS reports alive whose
+     *       every member is a ZOMBIE is already dead (see
+     *       `groupIsOnlyZombies` — a zombie is attached to its pgid, executes
+     *       nothing, and its environ is empty so it could never have carried
+     *       the token). That is `alreadyDead`, cause `"zombie-group"`:
+     *       NOTHING is signalled and the reap is reported CONFIRMED, because
+     *       a group with no live member cannot resume terminal work and a
+     *       group-kill would only poll to its timeout.
+     *     - the census did not prove the group all-zombie -> ONE last probe
+     *       before refusing: the liveness check that admitted this group ran
+     *       BEFORE every check above, and those checks take real time (two full
+     *       `/proc` censuses among them). A group whose last members were
+     *       collected meanwhile is EMPTY now, and the OS says so. `isGroupAlive`
+     *       answering ESRCH is the same positive proof of death the
+     *       short-circuit in `#killGroupAndConfirmDead` and its confirmation
+     *       poll already act on, so this cannot manufacture a death verdict —
+     *       a live group, leaderless or `Zl`, still answers ALIVE and is still
+     *       refused. That is `alreadyDead`, cause `"group-drained"`.
+     *     - otherwise -> cannot positively prove this group's identity by any
+     *       means -> REFUSE, cause `"membership-unprovable"` (conservative
      *       refuse-and-leak: this may well be our OWN orphan, already fully
      *       dead, but we cannot tell that apart from a live unrelated group
      *       we simply cannot identify). DISTINCT from `"recycled"` in the
@@ -783,7 +1180,67 @@ export class NativeTerminalHost {
      *       else's" and "cannot prove it is ours" are different epistemic
      *       states.
      */
-    #verifyGroupLeaderIdentity(pgid, persistedLeaderStartTime, persistedGroupToken, sessionId) {
+    #verifyGroupLeaderIdentity(pgid, persistedLeaderStartTime, persistedGroupToken, sessionId, frame = {}) {
+        // FRAME CHECK, before any pid-based comparison. Every proof below compares a
+        // number persisted earlier with a number read now, and that is meaningful
+        // only while both were taken in the same pid namespace and after the same
+        // boot (see proc-identity.ts). A row that records a frame which does not
+        // match this reader's is unusable in BOTH directions: a start-time mismatch
+        // would be read as "recycled" (pruning the row and releasing the socket on a
+        // proof that does not hold), and a coincidental MATCH would authorize a
+        // group SIGKILL at a group this row never described. Refuse, blocking, which
+        // is the behaviour that predates the `recycled` outcome.
+        //
+        // ONE mismatch is different, and is separated out below: same pid namespace,
+        // different BOOT, same MACHINE. That is not an absence of proof, it is the
+        // strongest proof available — a reboot ends every process of the boot
+        // before it — so it prunes instead of blocking. It is still a refusal:
+        // nothing is signalled, because an unrelated live group may hold the pgid
+        // number by now.
+        const anchoredFrame = frame.pidNamespace !== undefined && frame.bootId !== undefined;
+        if (frame.pidNamespace !== undefined || frame.bootId !== undefined) {
+            const current = this.#readFrame();
+            // The boot proof is admissible only inside ONE pid space, KNOWN on both
+            // sides: a pid resolved in another namespace is a different process, and
+            // an unknown namespace on either side is no statement at all.
+            const sameKnownPidNamespace = frame.pidNamespace !== undefined &&
+                current.pidNamespace !== undefined &&
+                frame.pidNamespace === current.pidNamespace;
+            // ...and only on ONE machine, KNOWN on both sides. The init pid
+            // namespace has the same inode on every kernel and boot ids are random
+            // per boot, so "same namespace, different boot" is ALSO what a row written
+            // by another machine sharing this registry looks like — a machine whose
+            // group may be alive right now. Only the machine id tells the two apart.
+            const sameKnownMachine = frame.machineId !== undefined &&
+                current.machineId !== undefined &&
+                frame.machineId === current.machineId;
+            const differentKnownBoot = frame.bootId !== undefined &&
+                current.bootId !== undefined &&
+                frame.bootId !== current.bootId;
+            if (sameKnownPidNamespace && sameKnownMachine && differentKnownBoot) {
+                // PROOF, not an absence of one: a reboot ends every process of the
+                // boot before it, so every process this row describes has ended. The
+                // pgid NUMBER may be held by an unrelated live group now, which is
+                // exactly why nothing is signalled here and why no diagnostic may
+                // point anyone at it.
+                this.#pgidGuardCounters.staleBoot += 1;
+                this.#log(`NOT signalling process group pgid=${pgid} for session ${sessionId}: this row was written at boot ${String(frame.bootId)} and this reader is at boot ${String(current.bootId)}, in the same pid namespace ${String(current.pidNamespace)} on the same machine ${String(current.machineId)} — the reboot ENDED every process this row describes, so its group is PROVEN gone. The number pgid=${pgid} may belong to an unrelated live group now and must NOT be killed. cause=stale-boot sessionId=${sessionId} pgid=${pgid}`);
+                return { proceed: false, cause: "stale-boot" };
+            }
+            if (frame.pidNamespace !== current.pidNamespace ||
+                frame.bootId !== current.bootId) {
+                // Says WHY nothing could be proven, because the two shapes call for
+                // different checks by whoever reads this: a boot change that only lacks
+                // the machine proof is either a reboot of this machine or another
+                // machine; anything else is another (or an unknown) pid space.
+                const why = sameKnownPidNamespace && differentKnownBoot
+                    ? `a different boot in the same pid namespace inode is what a previous boot of THIS machine looks like, but also what ANOTHER machine sharing this registry looks like, and the machine ids that would tell them apart are ${frame.machineId === undefined || current.machineId === undefined ? "not known on both sides" : "DIFFERENT"}`
+                    : "no pid or start-time on it can be re-proven here";
+                this.#pgidGuardCounters.foreignFrame += 1;
+                this.#log(`REFUSING to act on process group pgid=${pgid} for session ${sessionId}: this row records pid namespace ${String(frame.pidNamespace)}, boot ${String(frame.bootId)} and machine ${String(frame.machineId)}, but this reader is in pid namespace ${String(current.pidNamespace)} at boot ${String(current.bootId)} on machine ${String(current.machineId)} — ${why}. Inspecting pgid=${pgid} HERE proves nothing about this row. PROCESSES MAY SURVIVE UNCOLLECTED. cause=foreign-frame sessionId=${sessionId} pgid=${pgid}`);
+                return { proceed: false, cause: "foreign-frame" };
+            }
+        }
         const currentStartTime = this.#readLeaderStartTime(pgid);
         if (currentStartTime !== undefined) {
             if (persistedLeaderStartTime === undefined) {
@@ -792,6 +1249,16 @@ export class NativeTerminalHost {
                 return { proceed: true, verified: false, cause: "unverified-legacy" };
             }
             if (currentStartTime !== persistedLeaderStartTime) {
+                if (!anchoredFrame) {
+                    // The mismatch is real, but "the pgid was RECYCLED, so the original
+                    // group is gone" is a claim about ONE pid namespace and ONE boot, and
+                    // this row cannot pin either (written before the anchor existed). Keep
+                    // refusing — blocking, row kept — instead of pruning on a proof this
+                    // row cannot support.
+                    this.#pgidGuardCounters.membershipUnprovable += 1;
+                    this.#log(`REFUSING to kill process group pgid=${pgid} for session ${sessionId}: current leader start-time (${currentStartTime}) DIFFERS from the persisted start-time (${persistedLeaderStartTime}), but this row records no pid-namespace/boot anchor, so that mismatch cannot PROVE the original group is gone. PROCESSES MAY SURVIVE UNCOLLECTED. cause=membership-unprovable sessionId=${sessionId} pgid=${pgid}`);
+                    return { proceed: false, cause: "membership-unprovable" };
+                }
                 this.#pgidGuardCounters.recycled += 1;
                 this.#log(`REFUSING to kill process group pgid=${pgid} for session ${sessionId}: current leader start-time (${currentStartTime}) DIFFERS from the persisted start-time (${persistedLeaderStartTime}) — pgid was RECYCLED to an unrelated process since this row was written. PROCESSES MAY SURVIVE UNCOLLECTED. cause=recycled sessionId=${sessionId} pgid=${pgid}`);
                 return { proceed: false, cause: "recycled" };
@@ -810,6 +1277,28 @@ export class NativeTerminalHost {
             this.#log(`PROCEEDING to kill process group pgid=${pgid} for session ${sessionId}: the leader is unreadable, but a surviving GROUP MEMBER carries the persisted session token — positive proof of membership. cause=token-verified sessionId=${sessionId} pgid=${pgid}`);
             return { proceed: true, verified: true, cause: "token-verified" };
         }
+        // Last re-check before a refusal that would contain a whole socket: a
+        // group whose every remaining member is a ZOMBIE is already dead. This is
+        // the shape a host SIGKILL leaves behind when the guardian's parent-death
+        // broadcast lands, the leader is reaped first, and some member's exit
+        // status has not been collected yet — the leader is unreadable and a
+        // zombie's environ is empty, so neither anchor above could answer.
+        if (this.#groupIsOnlyZombies(pgid)) {
+            this.#pgidGuardCounters.zombieGroup += 1;
+            this.#log(`NOT signalling process group pgid=${pgid} for session ${sessionId}: the leader is UNREADABLE and every remaining member of the group is a ZOMBIE — the group is already dead (a zombie executes nothing and cannot be killed again), so this reap is CONFIRMED without emitting any signal. cause=zombie-group sessionId=${sessionId} pgid=${pgid}`);
+            return { proceed: false, alreadyDead: true, cause: "zombie-group" };
+        }
+        // The liveness probe that admitted this group ran BEFORE the frame read,
+        // the leader read, the token scan and two full /proc censuses. A group
+        // that finished draining across that work is empty NOW — ask the OS once
+        // more rather than block a socket on a group it answers ESRCH for. This is
+        // the same positive proof the short-circuit above this guard acts on: a
+        // live group still answers ALIVE and still falls through to the refusal.
+        if (!this.#reaper.isGroupAlive(pgid)) {
+            this.#pgidGuardCounters.groupDrained += 1;
+            this.#log(`NOT signalling process group pgid=${pgid} for session ${sessionId}: the leader is UNREADABLE and no member carried the token, but the group is now confirmed EMPTY by the OS — it finished draining while this reap was identifying it, so the reap is CONFIRMED without emitting any signal. cause=group-drained sessionId=${sessionId} pgid=${pgid}`);
+            return { proceed: false, alreadyDead: true, cause: "group-drained" };
+        }
         this.#pgidGuardCounters.membershipUnprovable += 1;
         this.#log(`REFUSING to kill process group pgid=${pgid} for session ${sessionId}: the group leader is UNREADABLE and no surviving member carries the persisted session token — cannot positively prove this group's identity. PROCESSES MAY SURVIVE UNCOLLECTED. cause=membership-unprovable sessionId=${sessionId} pgid=${pgid}`);
         return { proceed: false, cause: "membership-unprovable" };
@@ -857,8 +1346,16 @@ export class NativeTerminalHost {
         }
         let verified;
         if (verify) {
-            const verdict = this.#verifyGroupLeaderIdentity(pgid, verify.persistedLeaderStartTime, verify.persistedGroupToken, verify.sessionId);
+            const verdict = this.#verifyGroupLeaderIdentity(pgid, verify.persistedLeaderStartTime, verify.persistedGroupToken, verify.sessionId, verify.persistedFrame);
             if (!verdict.proceed) {
+                if (verdict.alreadyDead) {
+                    // The group was found reduced to zombies, or confirmed empty by the
+                    // OS after the checks: dead, with no signal emitted and nothing left
+                    // to wait for. Reported exactly like the already-empty short-circuit
+                    // above — no `verified` flag, because this proves the group's STATE,
+                    // not its identity.
+                    return { status: "dead", elapsedMs: 0 };
+                }
                 return { status: "refused", cause: verdict.cause };
             }
             verified = verdict.verified;
@@ -891,6 +1388,78 @@ export class NativeTerminalHost {
             await delay(this.#forceKillPollIntervalMs);
         }
     }
+    /**
+     * Drop a session's durable pgid row, but ONLY on the OS's positive proof
+     * that its process group is empty — the same asymmetry every other decision
+     * here applies, one step further: a row is the ONLY way a later pass can
+     * reach a group that outlived its session leader (the ordinary orphan: a
+     * shell that exits normally leaving a backgrounded descendant), so an
+     * ambiguous probe must KEEP the row. `isGroupAlive` answers "alive" for
+     * EPERM and for anything it cannot decide, which is exactly the fail-safe
+     * direction here.
+     *
+     * Best-effort and never throws: pruning is hygiene, and a registry that
+     * cannot be written must not turn a pty exit or a host shutdown into a
+     * failure. A row left behind is the pre-existing behaviour, not a new risk.
+     */
+    #pruneDurableRowIfGroupEmpty(record, because, options) {
+        try {
+            // Rows are keyed by session id alone, so a same-id session created
+            // elsewhere owns this key now. Prune only a row that still points at THIS
+            // session's group — never someone else's durable record. The cheap read
+            // below skips the lock entirely for the common "group still alive" case;
+            // the delete itself re-verifies the row UNDER the lock (compare-and-
+            // delete), because this read and that delete are not one critical section.
+            const row = readNativeTerminalPgid(record.id, this.#registryPath);
+            if (row.status !== "resolved" || row.pgid !== record.pty.pgid)
+                return "settled";
+            if (this.#reaper.isGroupAlive(record.pty.pgid))
+                return "settled";
+            const outcome = pruneNativeTerminalPgidEntry(record.id, this.#registryPath, { pgid: record.pty.pgid, groupToken: record.groupToken }, { waitForLock: options.waitForLock });
+            if (outcome === "lock-unavailable")
+                return "lock-unavailable";
+            if (outcome === "pruned") {
+                this.#log(`pruned the durable pgid row of terminal session ${record.id} (pgid=${record.pty.pgid}): ${because} and the OS reports the group empty`);
+            }
+            return "settled";
+        }
+        catch (error) {
+            this.#log(`could not prune the durable pgid row of terminal session ${record.id} (pgid=${record.pty.pgid}): ${String(error)}`);
+            return "settled";
+        }
+    }
+    /**
+     * Run the pty-exit prune OFF node-pty's synchronous `onExit` callback, and
+     * never waiting for the registry lock.
+     *
+     * Why both: `onExit` runs on this host's event loop, the loop that serves
+     * every other session's I/O, and taking the registry lock costs up to
+     * LOCK_MAX_WAIT_MS (4 s) of BUSY-WAIT when another process holds it (see
+     * file-lock.ts). Paying that inline freezes the whole host for seconds for
+     * what is only row hygiene. So each attempt asks for the lock ONCE and, when
+     * it is held, retries on a timer for a bounded number of attempts before
+     * giving up and leaving the row (a stale row is the pre-existing behaviour,
+     * and any later pass re-derives its verdict from the group itself).
+     *
+     * This opens NO window in which a live tree loses its row: the decision is
+     * made entirely at prune time, from a fresh row read, a fresh `isGroupAlive`
+     * proof and a compare-and-delete — never from the fact that an exit was once
+     * observed.
+     */
+    #schedulePruneOfExitedSession(record, because, attempt = 1) {
+        setTimeout(() => {
+            const outcome = this.#pruneDurableRowIfGroupEmpty(record, because, {
+                waitForLock: false,
+            });
+            if (outcome !== "lock-unavailable")
+                return;
+            if (attempt >= NATIVE_TERMINAL_PRUNE_MAX_ATTEMPTS) {
+                this.#log(`giving up on pruning the durable pgid row of terminal session ${record.id} (pgid=${record.pty.pgid}) after ${attempt} attempts: the registry lock stayed held. The stale row is left for a later pass.`);
+                return;
+            }
+            this.#schedulePruneOfExitedSession(record, because, attempt + 1);
+        }, attempt === 1 ? 0 : NATIVE_TERMINAL_PRUNE_RETRY_DELAY_MS);
+    }
     #requireSession(id) {
         const record = this.#sessions.get(id);
         if (!record)
@@ -989,13 +1558,22 @@ export class NativeTerminalHost {
  *    (unresolvable is treated exactly like alive: never guess).
  *  - `ownerProbe` reports "dead" (pid gone, or recycled — a live pid whose
  *    start-time no longer matches) -> reap that entry's orphan process group
- *    via `reap`, then prune the entry once the reap is CONFIRMED (`"reaped"`
- *    only — a `"reap-timed-out"` leaves the row for a future pass instead of
- *    losing the only durable record of an unconfirmed pgid).
+ *    via `reap`, then prune the entry once the reap is CONFIRMED (`"reaped"`)
+ *    or once the refusal itself PROVED the original group gone
+ *    (`cause: "recycled"` -> `"pruned-recycled-pgid"`; `cause: "stale-boot"`
+ *    -> `"pruned-stale-boot-row"`). A `"reap-timed-out"`, or a refusal that
+ *    leaves the group's fate unknown, keeps the row for a future pass instead
+ *    of losing the only durable record of an unconfirmed pgid.
  *
- * Best-effort per entry: one entry's failure does not stop the pass over the
- * rest (each entry is an independent host/session; a single problem entry
- * must never mask the others).
+ * Best-effort per entry, and this is a SAFETY property, not politeness: every
+ * entry's evaluation (owner probe, reap, row re-read, prune) is wrapped, so one
+ * entry's failure never stops the pass over the rest. Each entry is an
+ * independent host/session, and the socket-scoped containment decision a caller
+ * derives from this pass can only be right if the pass actually reached the row
+ * that concerns it — an abort half-way through leaves every later row
+ * unevaluated while the caller reads one failure as a cleanup hiccup. A failure
+ * is reported as `"reap-failed"` for that entry, WITH its attribution, and its
+ * row is kept.
  */
 export async function reconcileDeadHostOrphans(options = {}) {
     const signal = options.signal ?? "SIGKILL";
@@ -1015,13 +1593,58 @@ export async function reconcileDeadHostOrphans(options = {}) {
                 ...(options.registryPath !== undefined ? { registryPath: options.registryPath } : {}),
                 log,
             });
-            return (sessionId, pgid, sig) => reconcileHost.reapOrphan(sessionId, sig, pgid);
+            return (sessionId, pgid, sig, expected) => reconcileHost.reapOrphan(sessionId, sig, pgid, expected);
         })();
     const snapshot = listNativeTerminalPgidEntries(options.registryPath);
     if (!snapshot.known) {
         log(`REFUSING to reconcile native-terminal orphans: registry unreadable (${snapshot.reason}). NOTHING was reaped.`);
         return { status: "refused", reason: snapshot.reason };
     }
+    /**
+     * Re-read ONE row from the durable store, for the `pgid-mismatch` path
+     * below: the reap resolved a pgid different from this pass's snapshot, so
+     * the row was rewritten (a same-id session recreated) in between.
+     *
+     * THREE-STATE, and the three must never be collapsed. "The store reads fine
+     * and holds no such row" is a POSITIVE answer — nothing is owed — while "the
+     * store could not be read at all" is an absence of information about a row
+     * whose owner is not known to be alive and whose group was never probed.
+     * Flattening the second into the first downgrades a blocking verdict to a
+     * non-blocking `skipped-row-changed` and lets a caller start a host over a
+     * group whose fate was never decided.
+     */
+    const rereadEntry = (sessionId) => {
+        const fresh = listNativeTerminalPgidEntries(options.registryPath);
+        if (!fresh.known)
+            return { known: false, reason: fresh.reason };
+        return {
+            known: true,
+            entry: fresh.entries.find((candidate) => candidate.sessionId === sessionId),
+        };
+    };
+    /**
+     * Drop one row whose group this pass PROVED gone. Never throws: at this point
+     * the proof already holds, so a registry that cannot be written must not turn
+     * a confirmed containment into a failure — it leaves a stale row a later pass
+     * re-derives the same verdict from, which is the pre-existing behaviour, not a
+     * surviving group. Compare-and-delete (see `pruneNativeTerminalPgidEntry`): a
+     * row rewritten for the same session id by a LIVE host is never deleted.
+     */
+    const pruneProvenGoneRow = (entry) => {
+        const { sessionId } = entry;
+        try {
+            const outcome = pruneNativeTerminalPgidEntry(sessionId, options.registryPath, {
+                pgid: entry.pgid,
+                ...(entry.groupToken !== undefined ? { groupToken: entry.groupToken } : {}),
+            });
+            if (outcome === "kept") {
+                log(`native-terminal session ${sessionId}: nothing was pruned — the durable row is either already gone (a concurrent pass pruned it) or no longer describes the group this pass proved gone (pgid=${entry.pgid}), i.e. a live host owns that session id now. Either way it is not ours to delete.`);
+            }
+        }
+        catch (error) {
+            log(`native-terminal session ${sessionId}: could not prune the durable row of a group this pass PROVED gone (${String(error)}) — the containment verdict stands; the stale row is left for a later pass.`);
+        }
+    };
     const outcomes = [];
     for (const entry of snapshot.entries) {
         if (!entry.owner) {
@@ -1030,50 +1653,173 @@ export async function reconcileDeadHostOrphans(options = {}) {
             continue;
         }
         const owner = entry.owner;
-        const verdict = ownerProbe(owner);
-        if (verdict === "alive") {
-            log(`skipping native-terminal session ${entry.sessionId}: owning host pid=${owner.pid} is still alive — reaping nothing.`);
-            outcomes.push({ sessionId: entry.sessionId, status: "skipped-alive", ownerPid: owner.pid });
-            continue;
-        }
-        if (verdict === "unresolvable") {
-            log(`skipping native-terminal session ${entry.sessionId}: owning host pid=${owner.pid} liveness is unresolvable — treating conservatively as alive, reaping nothing.`);
-            outcomes.push({
-                sessionId: entry.sessionId,
-                status: "skipped-unresolvable",
-                ownerPid: owner.pid,
-            });
-            continue;
-        }
-        // verdict === "dead": PROVEN — the owner pid is gone, or was recycled.
-        log(`native-terminal session ${entry.sessionId}: owning host pid=${owner.pid} is PROVEN DEAD — reaping its orphan process group pgid=${entry.pgid}.`);
-        const outcome = await reap(entry.sessionId, entry.pgid, signal);
-        if (outcome.status === "reaped") {
-            pruneNativeTerminalPgidEntry(entry.sessionId, options.registryPath);
-            outcomes.push({
-                sessionId: entry.sessionId,
-                status: "reaped",
-                ownerPid: owner.pid,
-                pgid: entry.pgid,
-            });
-        }
-        else if (outcome.status === "reap-timed-out") {
-            log(`native-terminal session ${entry.sessionId}: reap did not confirm dead within the timeout — leaving the record for a future pass.`);
-            outcomes.push({
-                sessionId: entry.sessionId,
-                status: "reap-timed-out",
-                ownerPid: owner.pid,
-                pgid: entry.pgid,
-            });
+        // From here on, EVERY failure is contained to THIS entry: each entry is an
+        // independent host/session, and a pass that aborts half-way never evaluates
+        // the rows it had not reached — including the one that would have contained
+        // the caller's own socket. A caller reading such a failure as a cleanup
+        // hiccup then starts a host over a PTY group whose fate was never decided.
+        const attribution = {
+            ownerPid: owner.pid,
+            ...(owner.socketPath !== undefined ? { ownerSocketPath: owner.socketPath } : {}),
+            pgid: entry.pgid,
+        };
+        // Whether THIS entry's owner was positively proven dead before anything
+        // else was attempted. A failure below is contained either way, but a
+        // diagnostic must not assert a death the probe never returned (see
+        // `ownerDeathUnproven`).
+        let ownerProvenDead = false;
+        try {
+            const verdict = ownerProbe(owner);
+            if (verdict === "alive") {
+                log(`skipping native-terminal session ${entry.sessionId}: owning host pid=${owner.pid} is still alive — reaping nothing.`);
+                outcomes.push({ sessionId: entry.sessionId, status: "skipped-alive", ownerPid: owner.pid });
+                continue;
+            }
+            if (verdict === "unresolvable") {
+                log(`skipping native-terminal session ${entry.sessionId}: owning host pid=${owner.pid} liveness is unresolvable — treating conservatively as alive, reaping nothing.`);
+                outcomes.push({
+                    sessionId: entry.sessionId,
+                    status: "skipped-unresolvable",
+                    ownerPid: owner.pid,
+                });
+                continue;
+            }
+            // verdict === "dead": PROVEN — the owner pid is gone, or was recycled.
+            ownerProvenDead = true;
+            log(`native-terminal session ${entry.sessionId}: owning host pid=${owner.pid} is PROVEN DEAD — reaping its orphan process group pgid=${entry.pgid}.`);
+            // A row that carries a token constrains the reap on pgid AND token; a
+            // legacy row carries none and is called exactly as before.
+            const outcome = entry.groupToken === undefined
+                ? await reap(entry.sessionId, entry.pgid, signal)
+                : await reap(entry.sessionId, entry.pgid, signal, {
+                    groupToken: entry.groupToken,
+                });
+            if (outcome.status === "refused" && outcome.cause === "pgid-mismatch") {
+                // The row was REWRITTEN between this pass's snapshot and the reap's own
+                // lookup, so `reapOrphan` refused BEFORE probing any group — the one
+                // refusal cause that never observed liveness at all. Blocking a caller
+                // on it would be a verdict derived from a row that no longer exists, so
+                // re-read the row once and decide from what it says NOW.
+                //
+                // RE-READ, NEVER RE-TARGET: the re-read is used only to decide whether
+                // anything is still owed, never as the pgid to act on. Killing the group
+                // a rewritten row now points at is exactly the TOCTOU the immutable
+                // snapshot exists to prevent (`reapOrphan`'s `expectedPgid`), and the
+                // functional regression "should refuse reconciliation when the fresh
+                // PGID lookup differs from its immutable snapshot" holds that line. A
+                // row that still names a proven-dead owner therefore keeps the caused
+                // refusal — fail closed — and the NEXT pass snapshots the new pgid and
+                // reaps it properly.
+                const reread = rereadEntry(entry.sessionId);
+                if (!reread.known) {
+                    // NOT "the row is gone": the store answered nothing at all, about a
+                    // row whose owner is proven dead and whose group was never probed.
+                    // Fail closed on this entry's own attribution, like every other
+                    // per-entry failure.
+                    throw new Error(`the durable store could not be re-read after a pgid-mismatch refusal (${reread.reason})`);
+                }
+                const fresh = reread.entry;
+                if (fresh?.owner === undefined) {
+                    const reason = fresh === undefined
+                        ? "the row is gone"
+                        : "the row lost its owning-host attribution";
+                    log(`native-terminal session ${entry.sessionId}: the durable row changed under this pass (${reason}) — nothing was signalled, reaping nothing.`);
+                    outcomes.push({
+                        sessionId: entry.sessionId,
+                        status: "skipped-row-changed",
+                        reason,
+                    });
+                    continue;
+                }
+                const freshVerdict = ownerProbe(fresh.owner);
+                if (freshVerdict !== "dead") {
+                    log(`native-terminal session ${entry.sessionId}: the durable row was rewritten under this pass and now names owning host pid=${fresh.owner.pid}, whose liveness is "${freshVerdict}" — reaping nothing.`);
+                    outcomes.push({
+                        sessionId: entry.sessionId,
+                        status: freshVerdict === "alive" ? "skipped-alive" : "skipped-unresolvable",
+                        ownerPid: fresh.owner.pid,
+                    });
+                    continue;
+                }
+                log(`native-terminal session ${entry.sessionId}: the durable row was rewritten under this pass (snapshot pgid=${entry.pgid}, now pgid=${fresh.pgid}) and still names a PROVEN DEAD owner pid=${fresh.owner.pid} — keeping the refusal; NOTHING was signalled, and the next pass will act on the row it snapshots itself.`);
+            }
+            if (outcome.status === "refused" && outcome.cause === "recycled") {
+                // POSITIVE proof that the original group is GONE, not that one
+                // survived: the pgid number is held by an unrelated live leader of a
+                // different start-time, which the kernel could not have issued while any
+                // member of the original group still referenced that number. Prune the
+                // stale row — leaving it would re-derive this same verdict on every
+                // later pass — and never point an operator at that pgid.
+                pruneProvenGoneRow(entry);
+                log(`native-terminal session ${entry.sessionId}: pgid=${entry.pgid} is now held by an UNRELATED live process group leader, which PROVES the original process group of this session is gone — pruning the stale durable row. NOTHING was signalled; pgid=${entry.pgid} must NOT be killed, it does not belong to this session.`);
+                outcomes.push({
+                    sessionId: entry.sessionId,
+                    status: "pruned-recycled-pgid",
+                    ...attribution,
+                    reason: outcome.reason,
+                });
+            }
+            else if (outcome.status === "refused" && outcome.cause === "stale-boot") {
+                // POSITIVE proof that the original group is GONE, exactly like
+                // `recycled` and for a stronger reason: the row was written before this
+                // boot, in this reader's own pid namespace on this same machine (the
+                // machine id is what rules out another machine sharing this registry
+                // — see `#verifyGroupLeaderIdentity`), and a reboot ends every
+                // process of the boot before it. Prune the stale row — leaving it would
+                // re-derive this same verdict on every later pass, holding the socket
+                // until whatever unrelated process inherited the pgid NUMBER exits —
+                // and never point an operator at that number.
+                pruneProvenGoneRow(entry);
+                log(`native-terminal session ${entry.sessionId}: this durable row was written under a PREVIOUS boot, which ENDED every process it describes — pruning the stale durable row. NOTHING was signalled; pgid=${entry.pgid} must NOT be killed, a live unrelated group may hold that number now.`);
+                outcomes.push({
+                    sessionId: entry.sessionId,
+                    status: "pruned-stale-boot-row",
+                    ...attribution,
+                    reason: outcome.reason,
+                });
+            }
+            else if (outcome.status === "reaped") {
+                pruneProvenGoneRow(entry);
+                outcomes.push({
+                    sessionId: entry.sessionId,
+                    status: "reaped",
+                    ...attribution,
+                });
+            }
+            else if (outcome.status === "reap-timed-out") {
+                log(`native-terminal session ${entry.sessionId}: reap did not confirm dead within the timeout — leaving the record for a future pass.`);
+                outcomes.push({
+                    sessionId: entry.sessionId,
+                    status: "reap-timed-out",
+                    ...attribution,
+                });
+            }
+            else {
+                log(`native-terminal session ${entry.sessionId}: reap refused (${outcome.reason}).`);
+                outcomes.push({
+                    sessionId: entry.sessionId,
+                    status: "reap-refused",
+                    ...attribution,
+                    reason: outcome.reason,
+                    ...(outcome.cause !== undefined ? { cause: outcome.cause } : {}),
+                });
+            }
         }
-        else {
-            log(`native-terminal session ${entry.sessionId}: reap refused (${outcome.reason}).`);
+        catch (error) {
+            // Nothing was PROVEN about this row's group: the probe, the reap or the
+            // re-read failed. The durable row is kept, nothing was signalled, and the
+            // failure is reported WITH this row's attribution so a socket-scoped
+            // caller can fail closed on exactly the socket it belongs to. When the
+            // OWNER PROBE is what failed, the owner's own liveness is unknown too —
+            // the containment is the same, but it is flagged so no diagnostic calls
+            // that owner proven dead.
+            log(`native-terminal session ${entry.sessionId}: reap FAILED before proving anything about pgid=${entry.pgid} (${String(error)})${ownerProvenDead ? "" : " — the OWNING HOST's own liveness was never proven either"} — NOTHING was signalled or confirmed, and the durable row is kept for a later pass.`);
             outcomes.push({
                 sessionId: entry.sessionId,
-                status: "reap-refused",
-                ownerPid: owner.pid,
-                pgid: entry.pgid,
-                reason: outcome.reason,
+                status: "reap-failed",
+                ...attribution,
+                reason: String(error),
+                ...(ownerProvenDead ? {} : { ownerDeathUnproven: true }),
             });
         }
     }