@sentropic/h2a 0.97.11 → 0.98.0

package/dist/runtime/local-files/succession-lock.js

@@ -2,7 +2,8 @@
  * Succession lock (v4) — single-machine succession protocol.
  *
  * Extracted from `runtime/upgrade/index.ts` (Lot 4, step 1: neutral
- * intra-package move — zero behaviour change). This is the shared lock primitive
+ * intra-package move). Lot 4 §2 adds fail-closed host and boot provenance before
+ * any death proof. This is the shared lock primitive
  * used by the auto-upgrade prefix lock today, and (later lots) by the identity
  * binding lock. It is a LEAF: it imports only `node:fs/os/crypto/child_process`
  * and nothing from the store, so `upgrade/index.ts` and `local-files/locks.ts`
@@ -11,11 +12,11 @@
  * The full protocol proof-sketch (I1–I7, Lemmas A–C) lives with the code below,
  * moved unchanged from its original location.
  */
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { hostname } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 // ---------------------------------------------------------------------------
 // Prefix lock (v4): single-machine succession protocol.
 //
@@ -97,28 +98,87 @@ export function safeAtIso(at) {
     }
     return `epoch-ms:${at}`;
 }
-function readHostId() {
+const MACHINE_ID_RE = /^[0-9a-f]{32}$/;
+const IO_PLATFORM_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const STATIC_COMMAND_ENV = { LC_ALL: "C", TZ: "UTC0" };
+function isNullMachineId(value) {
+    return /^0+$/.test(value.replaceAll("-", ""));
+}
+function sysctlPath(platform) {
+    return platform === "darwin"
+        ? "/usr/sbin/sysctl"
+        : platform === "freebsd" || platform === "openbsd"
+            ? "/sbin/sysctl"
+            : "/usr/sbin/sysctl";
+}
+function weakHost(hostnameReader) {
     try {
-        const v = readFileSync("/etc/machine-id", "utf8").trim();
-        if (v)
-            return v;
+        const host = hostnameReader().trim();
+        if (host)
+            return { host, hostKind: "weak" };
     }
     catch {
-        // fall through to hostname
+        // fall through to sentinel
     }
-    try {
-        const h = hostname().trim();
-        if (h)
-            return h;
+    return { host: "unknown-host", hostKind: "weak" };
+}
+function parseIoPlatformUuid(output) {
+    const matches = output
+        .split("\n")
+        .map((line) => line.trim().match(/^"IOPlatformUUID"\s*=\s*"([0-9a-f-]+)"$/i)?.[1])
+        .filter((value) => value !== undefined);
+    if (matches.length !== 1 || !IO_PLATFORM_UUID_RE.test(matches[0]) || isNullMachineId(matches[0]))
+        return undefined;
+    return matches[0].toLowerCase();
+}
+/**
+ * Reads a machine-scoped host identity. The injected readers make source selection
+ * deterministic in tests without consulting process environment variables.
+ */
+export function readHostId(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const readFile = deps.readFile ?? ((path) => readFileSync(path, "utf8"));
+    const hostnameReader = deps.hostname ?? hostname;
+    if (platform === "linux") {
+        try {
+            const host = readFile("/etc/machine-id").trim();
+            if (MACHINE_ID_RE.test(host) && !isNullMachineId(host))
+                return { host, hostKind: "machine-id" };
+        }
+        catch {
+            // fall through to a weak hostname
+        }
     }
-    catch {
-        // fall through to sentinel
+    else if (platform === "darwin") {
+        try {
+            const ioreg = deps.ioreg ?? (() => {
+                const r = (deps.spawn ?? spawnSync)("/usr/sbin/ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], {
+                    encoding: "utf8",
+                    timeout: 2000,
+                    env: STATIC_COMMAND_ENV
+                });
+                return { status: r.status, stdout: typeof r.stdout === "string" ? r.stdout : null };
+            });
+            const result = ioreg();
+            const host = result.status === 0 && typeof result.stdout === "string"
+                ? parseIoPlatformUuid(result.stdout)
+                : undefined;
+            if (host !== undefined)
+                return { host, hostKind: "machine-id" };
+        }
+        catch {
+            // fall through to a weak hostname
+        }
     }
-    return "unknown-host";
+    return weakHost(hostnameReader);
 }
-function readBootId() {
+/** Reads the current boot identity; readers are injectable for platform simulations. */
+export function readBootId(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const readFile = deps.readFile ?? ((path) => readFileSync(path, "utf8"));
+    const spawn = deps.spawn ?? spawnSync;
     try {
-        const v = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+        const v = readFile("/proc/sys/kernel/random/boot_id").trim();
         if (v)
             return v;
     }
@@ -127,10 +187,10 @@ function readBootId() {
     }
     // Outside Linux prefer the stable session UUID (TZ-independent) when present.
     try {
-        const r = spawnSync("sysctl", ["-n", "kern.bootsessionuuid"], {
+        const r = spawn(sysctlPath(platform), ["-n", "kern.bootsessionuuid"], {
             encoding: "utf8",
             timeout: 2000,
-            env: { ...process.env, LC_ALL: "C", TZ: "UTC0" }
+            env: STATIC_COMMAND_ENV
         });
         const v = (r.stdout ?? "").trim();
         if (r.status === 0 && v)
@@ -140,10 +200,10 @@ function readBootId() {
         // best-effort
     }
     try {
-        const r = spawnSync("sysctl", ["-n", "kern.boottime"], {
+        const r = spawn(sysctlPath(platform), ["-n", "kern.boottime"], {
             encoding: "utf8",
             timeout: 2000,
-            env: { ...process.env, LC_ALL: "C", TZ: "UTC0" }
+            env: STATIC_COMMAND_ENV
         });
         const v = (r.stdout ?? "").trim();
         if (r.status === 0 && v)
@@ -156,9 +216,10 @@ function readBootId() {
 }
 // B2 decomposition: distinguish "this platform has no namespaces" (a KNOWN fact —
 // one space per host) from "the namespace exists but is unreadable" (a genuine
-// unknown). Only the latter is null; the former is the sentinel "host" so same-host
-// liveness stays decidable (macOS/Windows/BSD). `platform`/`readLink` are injected
-// only by tests (macOS/Windows/no-/proc sims); production passes none.
+// unknown). Only the latter is null; the former is the sentinel "host". Lot 4 §2
+// permits that no-namespace liveness proof only on darwin; Windows and BSD still fail
+// closed as undecidable. `platform`/`readLink` are injected only by tests
+// (macOS/Windows/no-/proc sims); production passes none.
 //
 // readPidNs is the CONSERVATIVE gate that decides reclaim at all: an unknown (null)
 // pid namespace makes even a PID-absent holder undecidable, because "absent" in an
@@ -210,9 +271,9 @@ function procMapsToSelf() {
  * so a reader using a different source never concludes "dead" from a
  * format/TZ-fragile comparison (C1).
  */
-// `platform`/`mapsToSelf` are injected only by tests (mis-mapped-/proc / non-Linux
-// sims); production passes none.
-export function procStartInfo(pid, platform = process.platform, mapsToSelf = procMapsToSelf) {
+// `platform`/`mapsToSelf`/`spawn` are injected only by tests (mis-mapped-/proc /
+// non-Linux sims); production passes none.
+export function procStartInfo(pid, platform = process.platform, mapsToSelf = procMapsToSelf, spawn = spawnSync) {
     // A start time is only trusted from a source whose value is STABLE for the life of the
     // process (never moving under a wall-clock step), else a clock jump while the lock is held
     // could make a live holder's start "differ" ⇒ a false death ⇒ two holders (I3).
@@ -224,7 +285,8 @@ export function procStartInfo(pid, platform = process.platform, mapsToSelf = pro
     // - darwin: `ps lstart` is the ABSOLUTE fork wall-clock time (p_starttime), stable ⇒ trusted.
     // - R-BSD: on FreeBSD/OpenBSD `ps` start is boot-relative and its boot time is re-derived on
     //   a clock step, so it is NOT stable. Every other non-Linux platform (incl. Windows, no ps)
-    //   ⇒ undefined (undatable ⇒ live). In doubt, never dead.
+    //   ⇒ undefined. Lock liveness on those platforms is already undecidable under Lot 4 §2.
+    //   In doubt, never dead.
     if (platform === "linux") {
         if (!mapsToSelf())
             return undefined;
@@ -247,10 +309,10 @@ export function procStartInfo(pid, platform = process.platform, mapsToSelf = pro
     if (platform !== "darwin")
         return undefined; // only darwin ps is a stable source
     try {
-        const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+        const r = spawn("/bin/ps", ["-o", "lstart=", "-p", String(pid)], {
             encoding: "utf8",
             timeout: 5000,
-            env: { ...process.env, LC_ALL: "C", TZ: "UTC0" }
+            env: STATIC_COMMAND_ENV
         });
         const v = (r.stdout ?? "").trim();
         if (r.status === 0 && v)
@@ -271,24 +333,28 @@ function startSource(s) {
 let ME_CACHE;
 /** This process's identity, computed once and memoized. */
 export function me() {
-    ME_CACHE ??= {
-        host: readHostId(),
-        boot: readBootId(),
-        ns: readPidNs(),
-        timeNs: readTimeNs(),
-        pid: process.pid,
-        start: procStartInfo(process.pid)?.start ?? null
-    };
+    ME_CACHE ??= (() => {
+        const host = readHostId();
+        return {
+            host: host.host,
+            hostKind: host.hostKind,
+            boot: readBootId(),
+            ns: readPidNs(),
+            timeNs: readTimeNs(),
+            pid: process.pid,
+            start: procStartInfo(process.pid)?.start ?? null
+        };
+    })();
     return ME_CACHE;
 }
 /** Fresh random token, >= 96 bits, never republished (H3). */
 function newToken() {
     return randomBytes(16).toString("hex");
 }
-export function makeLockRec(token, target) {
-    const self = me();
+function makeLockRecFor(self, token, target) {
     return {
         host: self.host,
+        hostKind: self.hostKind,
         boot: self.boot,
         ns: self.ns,
         timeNs: self.timeNs,
@@ -299,11 +365,14 @@ export function makeLockRec(token, target) {
         at: Date.now()
     };
 }
+export function makeLockRec(token, target) {
+    return makeLockRecFor(me(), token, target);
+}
 export function parseLockRec(raw) {
     if (typeof raw !== "object" || raw === null)
         throw new Error("bad lock record");
     const o = raw;
-    const { host, boot, ns, timeNs, pid, start, token, target, at } = o;
+    const { host, hostKind, boot, ns, timeNs, pid, start, token, target, operator, at } = o;
     // timeNs is a required field like host/boot/ns/pid/start: an absent field is a
     // malformed record → corrupt → fail-closed. No back-compat exception is carved
     // for a "v4 without timeNs" — the redesign was never published, so no such lock
@@ -312,6 +381,12 @@ export function parseLockRec(raw) {
     // as undatable ⇒ "live" (never reclaim, never a false death), not undecidable.
     if (typeof host !== "string" || host.length === 0)
         throw new Error("bad host");
+    // A missing provenance was written by versions <= 0.97.9. It is valid legacy
+    // state, but classifyLiveness treats it as unknown and therefore undecidable.
+    // Unknown values are corrupt and fail closed. Lot 5 must carry an instance UUID in
+    // a separate field rather than extending this persisted hostKind enum.
+    if (hostKind !== undefined && hostKind !== "machine-id" && hostKind !== "weak")
+        throw new Error("bad hostKind");
     if (boot !== null && typeof boot !== "string")
         throw new Error("bad boot");
     if (ns !== null && typeof ns !== "string")
@@ -322,14 +397,17 @@ export function parseLockRec(raw) {
         throw new Error("bad pid");
     if (start !== null && typeof start !== "string")
         throw new Error("bad start");
-    if (typeof token !== "string" || !LOCK_TOKEN_RE.test(token))
+    if (typeof token !== "string" || token.startsWith("legacy-") || !LOCK_TOKEN_RE.test(token))
         throw new Error("bad token");
     if (target !== undefined && typeof target !== "string")
         throw new Error("bad target");
+    if (operator !== undefined && (operator !== true || target === undefined))
+        throw new Error("bad operator");
     if (typeof at !== "number" || !Number.isFinite(at))
         throw new Error("bad at");
     return {
         host,
+        ...(hostKind !== undefined ? { hostKind } : {}),
         boot,
         ns,
         timeNs,
@@ -337,18 +415,81 @@ export function parseLockRec(raw) {
         start,
         token,
         ...(target !== undefined ? { target } : {}),
+        ...(operator === true ? { operator } : {}),
         at
     };
 }
-/** opus `read`: ENOENT -> absent, anything else unreadable -> corrupt (I1). */
-export function readLockRecord(path) {
+function parseLegacyLockHolder(raw, bytes) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("bad legacy lock record");
+    const o = raw;
+    const keys = Object.keys(o);
+    if (!keys.includes("pid")
+        || !keys.includes("hostname")
+        || !keys.includes("startedAt")
+        || !keys.every((key) => key === "pid" || key === "hostname" || key === "startedAt" || key === "protocol" || key === "fenceEpoch")) {
+        throw new Error("bad legacy lock fields");
+    }
+    if (typeof o.pid !== "number" || !Number.isInteger(o.pid) || o.pid <= 0)
+        throw new Error("bad legacy pid");
+    if (typeof o.hostname !== "string")
+        throw new Error("bad legacy hostname");
+    if (typeof o.startedAt !== "string")
+        throw new Error("bad legacy startedAt");
+    if (o.protocol !== undefined && typeof o.protocol !== "string")
+        throw new Error("bad legacy protocol");
+    if (o.fenceEpoch !== undefined && typeof o.fenceEpoch !== "string")
+        throw new Error("bad legacy fenceEpoch");
+    return {
+        kind: "legacy",
+        // Do not trim, decode/re-encode, or JSON.stringify the input: a final `\n`
+        // is part of this fencing token by design and is covered by T-legacy.
+        token: `legacy-${createHash("sha256").update(bytes).digest("hex")}`,
+        pid: o.pid,
+        hostname: o.hostname,
+        startedAt: o.startedAt,
+        ...(o.protocol !== undefined ? { protocol: o.protocol } : {}),
+        ...(o.fenceEpoch !== undefined ? { fenceEpoch: o.fenceEpoch } : {})
+    };
+}
+/** Advisory reader: distinguish failed reads from malformed file content. */
+function readLockHolderDetailed(path) {
+    let bytes;
     try {
-        return parseLockRec(JSON.parse(readFileSync(path, "utf8")));
+        bytes = readFileSync(path);
     }
     catch (e) {
-        return e?.code === "ENOENT" ? "absent" : "corrupt";
+        return errnoOf(e) === "ENOENT" ? "absent" : { kind: "io-error", code: errnoOf(e) };
+    }
+    try {
+        const parsed = JSON.parse(bytes.toString("utf8"));
+        try {
+            return parseLockRec(parsed);
+        }
+        catch {
+            return parseLegacyLockHolder(parsed, bytes);
+        }
+    }
+    catch {
+        return "corrupt";
     }
 }
+/** Legacy tokens fingerprint the exact raw bytes; read errors remain corrupt. */
+export function readLockHolder(path) {
+    const holder = readLockHolderDetailed(path);
+    return typeof holder === "object" && holder.kind === "io-error" ? "corrupt" : holder;
+}
+/**
+ * v4-only reader retained for existing protocol callers. A readable legacy holder
+ * remains `corrupt` here so a caller that was not explicitly upgraded to the
+ * distinct legacy view continues to fail closed.
+ */
+export function readLockRecord(path) {
+    const holder = readLockHolder(path);
+    return holder !== "absent" && holder !== "corrupt" && holder.kind === "legacy"
+        ? "corrupt"
+        : holder;
+}
 /**
  * opus `publish` (I1): a name appears only with complete, durable content.
  * Write tmp (wx + byte-count-checked write + fsync + close), then `link(2)`;
@@ -427,19 +568,24 @@ export function publishLockRecord(path, rec) {
  * safe "live" (undatable), and a corrupt "legacy" start yields "undecidable" (C1).
  */
 export function classifyLiveness(r, self, deps = {}) {
+    // Legacy records have no machine/boot/namespace/start provenance. In particular,
+    // even a same-host ESRCH PID may have been reused, so never probe it and never
+    // promote the holder to dead. The operator escape hatch consumes this token later.
+    if (r.kind === "legacy")
+        return { verdict: "undecidable", datable: false };
     const platform = deps.platform ?? process.platform;
     const probe = deps.probe ?? procStartInfo;
+    // Lot 4 §2 permits a death proof only for a strong machine identity on Linux or
+    // darwin, with the same known host and boot. Check this before every PID/start probe:
+    // cloned images can share a machine-id and an initial pid namespace inode.
+    if (platform !== "linux" && platform !== "darwin")
+        return { verdict: "undecidable", datable: false };
+    if (r.hostKind !== "machine-id" || self.hostKind !== "machine-id")
+        return { verdict: "undecidable", datable: false };
     if (r.host !== self.host)
-        return { verdict: "undecidable", datable: false }; // other machine
-    // B1: only a Linux boot_id is a stable, trustworthy boot identity, so a difference
-    // there is a previous boot ⇒ dead. Off Linux a boot difference must NOT short-circuit
-    // to undecidable (that wedged a Mac rebooted mid-lock forever); fall through to kill(0)
-    // (PID absent ⇒ dead, on every platform) then the start comparison (only conclusive
-    // where the start is datable — Linux /proc and darwin ps; on BSD/Windows it is undatable
-    // ⇒ live, so after a reboot a reused PID blocks until it exits, surfaced by R2).
-    if (r.boot && self.boot && r.boot !== self.boot && platform === "linux") {
-        return { verdict: "dead", datable: false };
-    }
+        return { verdict: "undecidable", datable: false };
+    if (r.boot === null || self.boot === null || r.boot !== self.boot)
+        return { verdict: "undecidable", datable: false };
     // An unreadable namespace on EITHER side is a genuine unknown — two records with a
     // null namespace must never be treated as co-located (null-equality).
     if (r.ns === null || self.ns === null)
@@ -500,21 +646,94 @@ export function livenessOf(r, self, deps = {}) {
 export function isCertainlyDead(r) {
     return classifyLiveness(r, me()).verdict === "dead";
 }
-function lockDenied(reason) {
-    return { acquired: false, release: () => { }, reason };
-}
-function invokeLockHook(fn, ctx) {
-    if (!fn)
-        return;
-    try {
-        fn(ctx);
-    }
-    catch {
-        // Observation-only: a test hook must never break the protocol.
+/**
+ * Token-fenced escape hatch, using the same one-shot SUCC election as acquisition.
+ * It never owns or republishes LOCK and never sends a destructive process signal.
+ * An automatic successor already elected for g excludes the operator. After g is
+ * removed, a pending automatic retire sees absence and may publish a fresh LOCK.
+ */
+export function breakLockAsOperator(lockPath, options) {
+    const g = options?.expectToken;
+    if (typeof g !== "string" || !LOCK_TOKEN_RE.test(g)
+        || (g.startsWith("legacy-") && !/^legacy-[a-f0-9]{64}$/.test(g))) {
+        return { broken: false, reason: "invalid-token", legacyRecords: 0 };
+    }
+    const holder = readLockHolder(lockPath);
+    if (holder === "absent" || holder === "corrupt") {
+        return { broken: false, reason: holder, legacyRecords: 0 };
+    }
+    const legacyRecords = holder.kind === "legacy" ? 1 : 0;
+    const context = {
+        token: holder.token, pid: holder.pid, legacyRecords,
+        ...(legacyRecords === 1 ? { diagnostic: {
+                code: "legacy-record",
+                command: `h2a identity unlock --token ${holder.token} --assert-dead`
+            } } : {})
+    };
+    const refused = (reason) => ({ broken: false, reason, ...context });
+    if (holder.token !== g)
+        return refused("token-mismatch");
+    const operatorSelf = me();
+    const verdict = classifyLiveness(holder, operatorSelf).verdict;
+    if (verdict === "live")
+        return refused("live");
+    if (verdict === "undecidable" && options.assertDead !== true)
+        return refused("assert-dead-required");
+    let t = g;
+    for (let depth = 0; depth < PREFIX_LOCK_MAX_CHAIN; depth++) {
+        // A retry never silently changes the requested target to a replacement owner.
+        const current = readLockHolder(lockPath);
+        if (current === "corrupt")
+            return refused("corrupt");
+        if (current === "absent" || current.token !== g)
+            return refused("token-mismatch");
+        const successor = {
+            ...makeLockRecFor(operatorSelf, newToken(), g),
+            ...(verdict === "undecidable" ? { operator: true } : {})
+        };
+        const published = publishLockRecord(succPathFor(lockPath, t), successor);
+        if (published.status === "error")
+            return refused(`error:${published.code}`);
+        if (published.status === "retry")
+            return refused("busy");
+        if (published.status === "exists") {
+            const link = readLockRecord(succPathFor(lockPath, t));
+            if (link === "absent")
+                return refused("busy");
+            if (link === "corrupt" || link.target !== g)
+                return refused("dead-undecidable");
+            const linkVerdict = classifyLiveness(link, operatorSelf).verdict;
+            if (linkVerdict !== "dead")
+                return refused(linkVerdict === "live" ? "busy" : "dead-undecidable");
+            t = link.token;
+            continue;
+        }
+        // Election makes this the sole successor. Re-read as the last action before
+        // unlink, including the raw-byte legacy token, so a winning LOCK survives.
+        const confirmed = readLockHolder(lockPath);
+        if (confirmed === "corrupt")
+            return refused("corrupt");
+        if (confirmed === "absent" || confirmed.token !== g) {
+            purgeSuccession(dirname(lockPath), lockPath, g);
+            return refused("token-mismatch");
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch (error) {
+            if (errnoOf(error) !== "ENOENT")
+                return refused(`error:${errnoOf(error)}`);
+        }
+        purgeSuccession(dirname(lockPath), lockPath, g);
+        return { broken: true, ...context };
     }
+    return refused("dead-undecidable");
 }
-/** opus `acquirePrefixLock`, plus M5 reasons and test-only critical hooks. */
-export function acquirePrefixLock(prefix, hooks = {}) {
+function lockDenied(reason) {
+    return { acquired: false, stillHeld: () => false, release: () => { }, reason };
+}
+/** Production acquisition. Extra JavaScript arguments cannot inject dependencies. */
+export function acquirePrefixLock(prefix, options = {}) {
     const lockPath = lockPathFor(prefix);
     try {
         mkdirSync(prefix, { recursive: true });
@@ -524,26 +743,39 @@ export function acquirePrefixLock(prefix, hooks = {}) {
     }
     const self = me();
     for (let round = 0; round < PREFIX_LOCK_MAX_ROUNDS; round++) {
-        if (round === 0) {
-            invokeLockHook(hooks.beforePublishLock, { prefix, lockPath, path: lockPath, round, depth: 0 });
+        if (options?.readFirst) {
+            const first = readLockHolderDetailed(lockPath);
+            // An I/O failure says nothing about presence; retain ordinary errno handling.
+            if (typeof first === "object" && first.kind === "io-error") {
+                // Fall through to ordinary publication.
+            }
+            else if (first !== "absent") {
+                if (first === "corrupt")
+                    return lockDenied("dead-undecidable");
+                const firstLiveness = classifyLiveness(first, self).verdict;
+                if (firstLiveness !== "dead") {
+                    return lockDenied(firstLiveness === "live" ? "busy" : "dead-undecidable");
+                }
+            }
+            // A preliminary death authorizes nothing: publish, then read/classify afresh.
         }
         const tok = newToken();
-        const pub = publishLockRecord(lockPath, makeLockRec(tok));
+        const pub = publishLockRecord(lockPath, makeLockRecFor(self, tok));
         if (pub.status === "ok")
             return makeLease(prefix, lockPath, tok);
         if (pub.status === "error")
             return lockDenied(`error:${pub.code}`);
         if (pub.status === "retry")
             continue;
-        const cur = readLockRecord(lockPath);
+        const cur = readLockRecord(lockPath); // fresh after EEXIST; sole entry to succession
         if (cur === "absent")
             continue; // released meanwhile
         if (cur === "corrupt")
             return lockDenied("dead-undecidable"); // fail closed
-        const live = livenessOf(cur, self);
+        const live = classifyLiveness(cur, self).verdict;
         if (live !== "dead")
             return lockDenied(live === "live" ? "busy" : "dead-undecidable");
-        const next = succeedDeadToken(prefix, lockPath, cur.token, hooks, round);
+        const next = succeedDeadToken(prefix, lockPath, cur.token, self);
         if (next !== "retry")
             return next;
     }
@@ -554,23 +786,13 @@ export function acquirePrefixLock(prefix, hooks = {}) {
  * SUCC(g) -> SUCC(r0) -> ...; publishing a link elects the sole live
  * successor (Lemma B). "retry" means the chain settled meanwhile (re-read).
  */
-function succeedDeadToken(prefix, lockPath, g, hooks, round) {
-    const self = me();
+function succeedDeadToken(prefix, lockPath, g, self) {
     let t = g;
     for (let depth = 0; depth < PREFIX_LOCK_MAX_CHAIN; depth++) {
         const tok = newToken();
-        const pub = publishLockRecord(succPathFor(lockPath, t), makeLockRec(tok, g));
+        const pub = publishLockRecord(succPathFor(lockPath, t), makeLockRecFor(self, tok, g));
         if (pub.status === "ok") {
-            invokeLockHook(hooks.afterPublishSucc, {
-                prefix,
-                lockPath,
-                path: succPathFor(lockPath, t),
-                token: tok,
-                target: g,
-                round,
-                depth
-            });
-            return retireDeadToken(prefix, lockPath, g, hooks, round, depth);
+            return retireDeadToken(prefix, lockPath, g, self);
         }
         if (pub.status === "error")
             return lockDenied(`error:${pub.code}`);
@@ -581,7 +803,7 @@ function succeedDeadToken(prefix, lockPath, g, hooks, round) {
             return "retry"; // chain already settled
         if (s === "corrupt" || s.target !== g)
             return lockDenied("dead-undecidable");
-        const live = livenessOf(s, self);
+        const live = classifyLiveness(s, self).verdict;
         if (live !== "dead")
             return lockDenied(live === "live" ? "busy" : "dead-undecidable");
         t = s.token; // it died: succeed it
@@ -593,19 +815,11 @@ function succeedDeadToken(prefix, lockPath, g, hooks, round) {
  * opus `retire`: targeted removal (S) of exactly g (Lemma C), then purge the
  * now-inert SUCC files targeting g (I5), then publish a fresh token.
  */
-function retireDeadToken(prefix, lockPath, g, hooks, round, depth) {
+function retireDeadToken(prefix, lockPath, g, self) {
     const cur = readLockRecord(lockPath);
     if (cur === "corrupt")
         return lockDenied("dead-undecidable"); // keep our SUCC: fail closed
     if (cur !== "absent" && cur.token === g) {
-        invokeLockHook(hooks.beforeRetireUnlink, {
-            prefix,
-            lockPath,
-            path: lockPath,
-            target: g,
-            round,
-            depth
-        });
         // Lemma C (targeted removal), hardened: re-read LOCK as the LAST step before the
         // unlink and remove it ONLY while it is STILL exactly g. Successor uniqueness
         // (Lemma B) + monotonicity (I2) prove LOCK cannot legally change from g under this
@@ -631,14 +845,6 @@ function retireDeadToken(prefix, lockPath, g, hooks, round, depth) {
             catch (e) {
                 unlinkCode = errnoOf(e);
             }
-            invokeLockHook(hooks.afterRetireUnlink, {
-                prefix,
-                lockPath,
-                path: lockPath,
-                target: g,
-                round,
-                depth
-            });
             // LOCK != g not established: keep our SUCC file, fail closed.
             if (unlinkCode !== undefined && unlinkCode !== "ENOENT") {
                 return lockDenied(`error:${unlinkCode}`);
@@ -649,7 +855,7 @@ function retireDeadToken(prefix, lockPath, g, hooks, round, depth) {
     // From here LOCK != g forever (I2): every SUCC targeting g is inert.
     purgeSuccession(prefix, lockPath, g); // unlink SUCC files whose target === g
     const tok = newToken();
-    const pub = publishLockRecord(lockPath, makeLockRec(tok));
+    const pub = publishLockRecord(lockPath, makeLockRecFor(self, tok));
     if (pub.status === "ok")
         return makeLease(prefix, lockPath, tok);
     if (pub.status === "exists" || pub.status === "retry")
@@ -662,6 +868,12 @@ function retireDeadToken(prefix, lockPath, g, hooks, round, depth) {
  */
 function makeLease(prefix, lockPath, token) {
     let done = false;
+    const stillHeld = () => {
+        if (done)
+            return false;
+        const cur = readLockRecord(lockPath);
+        return cur !== "absent" && cur !== "corrupt" && cur.token === token;
+    };
     const release = () => {
         if (done)
             return;
@@ -690,7 +902,7 @@ function makeLease(prefix, lockPath, token) {
         // best-effort
     }
     collectLockDebris(prefix, lockPath, token); // holder-only GC (I5-safe)
-    return { acquired: true, release, token };
+    return { acquired: true, stillHeld, release, token };
 }
 /** Unlink SUCC files whose target === g (called only when LOCK != g can hold). */
 function purgeSuccession(prefix, lockPath, g) {