@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/instance-registry.js

@@ -12,19 +12,18 @@
  * File shape: `{ instances: InstanceEntry[] }`. Missing or corrupt file is
  * treated as `{ instances: [] }` — this module must never throw on a read.
  *
- * Concurrency: every write is read-modify-write-whole-file with an atomic
- * tmp+rename (same pattern as clients/review-graph/builder.ts). Two
- * processes racing a write is a KNOWN, ACCEPTED race for slice 1
- * (last-writer-wins) — a lost update here only means a stale/missing
- * observability entry, never data corruption (the tmp+rename guarantees the
- * file itself is always valid JSON). A future slice can add file locking or
- * per-pid shard files if this proves too lossy in practice.
+ * Concurrency: every whole-file writer holds the adjacent `<registry>.lock`
+ * O_EXCL lock across its read-modify-write. Contenders use 5-25ms jittered
+ * backoff for up to 500ms; stale locks older than 5s or owned by a dead pid
+ * are displaced and reclaimed. A crash can still leave a stale lock during
+ * that window, so takeover remains deliberately bounded and observable.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeFileAtomic, writeFileAtomicAsync } from "./atomic-write.js";
 import { recordDegradationOnce } from "./degradation-ledger.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
+import { withInstanceRegistryLock, withInstanceRegistryLockSync, } from "./instance-registry-lock.js";
 // #735: reuse the #449/#525 reaper's exact conservative liveness check
 // (`process.kill(pid, 0)`, ESRCH-only-means-dead) rather than inventing a
 // second one — see realIsPidAlive's own docstring, which already calls out
@@ -34,13 +33,19 @@ import { getGlobalPiLensDir } from "./file-utils.js";
 // use on both sides happens inside function bodies, never at module-
 // evaluation time, so both modules are fully initialized before either
 // import is actually invoked.
-import { realIsPidAlive } from "./instance-reaper.js";
+import { realIsPidAlive, STALE_HEARTBEAT_MS } from "./instance-reaper.js";
 import { normalizeFilePath } from "./path-utils.js";
+import { getProcessSingleton } from "./process-singletons.js";
 import { getSubagentIdentity, isSubagentSession } from "./subagent-mode.js";
 function registryPath() {
     return path.join(getGlobalPiLensDir(), "instances.json");
 }
 // --- Kill switch (lazy, memoized — house style per clients/runtime-config.ts) ---
+// #2146 class-sweep verdict: STAYS at module scope. Duplicating this memo
+// across module evaluations is wasteful, not wrong — every copy re-reads the
+// same `process.env` and reaches the same answer, so no caller can observe a
+// disagreement. Only state that is WRONG when duplicated moves to
+// `process-singletons.ts`.
 let _enabledCache;
 /**
  * `PI_LENS_INSTANCE_REGISTRY=0` disables the registry entirely: every
@@ -140,6 +145,16 @@ async function writeRegistryAsync(file) {
     // never a thrown error for the caller.
     await writeFileAtomicAsync(target, JSON.stringify(file));
 }
+const REGISTRY_WRITE_RETRIES = 3;
+async function writeRegistryWithRetry(mutate, isCommitted) {
+    await withInstanceRegistryLock(registryPath(), async () => {
+        for (let attempt = 0; attempt < REGISTRY_WRITE_RETRIES; attempt++) {
+            await writeRegistryAsync(mutate(await readRegistryAsync()));
+            if (isCommitted(await readRegistryAsync()))
+                return;
+        }
+    });
+}
 function writeRegistrySync(file) {
     const dir = getGlobalPiLensDir();
     const target = registryPath();
@@ -152,16 +167,73 @@ function writeRegistrySync(file) {
     writeFileAtomic(target, JSON.stringify(file));
 }
 // --- Mutations (all read-modify-write whole file) ---
-/** Create/overwrite this process's entry. */
-export async function registerInstance(projectRoot) {
+/**
+ * Every root an entry serves, oldest first (#2130).
+ *
+ * The single reader for root identity in this module — no caller may compare
+ * `entry.projectRoot` directly, or a host's secondary roots become invisible
+ * again. Folds a pre-#2130 entry (no `projectRoots`) back to its scalar root,
+ * and drops non-string / empty members so a hand-edited or torn file cannot
+ * make a comparison throw.
+ */
+export function getInstanceRoots(entry) {
+    const listed = Array.isArray(entry.projectRoots)
+        ? entry.projectRoots.filter((root) => typeof root === "string" && root.length > 0)
+        : [];
+    if (listed.length > 0)
+        return listed;
+    return typeof entry.projectRoot === "string" && entry.projectRoot.length > 0
+        ? [entry.projectRoot]
+        : [];
+}
+/**
+ * Bound on the per-host root set (#2130). A host that legitimately serves many
+ * worktrees must not grow an unbounded path list inside a file every other
+ * pi-lens process reads on every heartbeat. Eviction drops the OLDEST
+ * NON-PRIMARY root: `projectRoot` is the host's own working directory and the
+ * one the shared-checkout guard most needs, so it is never evicted.
+ * Deliberately smaller than `SESSION_ROOT_CAP` (128,
+ * `clients/lsp/session-roots.ts:45`) because that set lives in memory for one
+ * process while this one is serialized to disk for all of them.
+ */
+const INSTANCE_ROOT_CAP = 32;
+/**
+ * The SINGLE owner of root-set semantics: dedupe, append order, and
+ * primary-preserving cap eviction (#2130).
+ *
+ * Both writers — `registerInstance` (the full session-start registration) and
+ * `registerInstanceRoot` (the lightweight add a declined secondary-root start
+ * performs) — fold through this, so the two can never disagree about what the
+ * set means. Pure, so the rule is testable without touching the filesystem.
+ */
+export function mergeInstanceRoots(priorRoots, normalizedRoot) {
+    const roots = priorRoots.includes(normalizedRoot)
+        ? [...priorRoots]
+        : [...priorRoots, normalizedRoot];
+    // Evict from index 1 upward so the primary at index 0 survives.
+    while (roots.length > INSTANCE_ROOT_CAP)
+        roots.splice(1, 1);
+    return roots;
+}
+/**
+ * Register `projectRoot` for this process, ADDITIVELY (#2130).
+ *
+ * Creates the entry on first call and pins `projectRoot` as the primary. Every
+ * later call for a different root APPENDS to `projectRoots` instead of
+ * overwriting — that overwrite is the defect #2130 records, where a subagent
+ * temp worktree's session start made the host advertise a temp dir as its root.
+ * Re-registering a root already in the set is a no-op for the set (the
+ * heartbeat/rss fields still refresh).
+ */
+export function registerInstance(projectRoot) {
+    return queueRegistryMutation(() => registerInstanceNow(projectRoot));
+}
+async function registerInstanceNow(projectRoot) {
     if (!isInstanceRegistryEnabled())
         return;
     const pid = process.pid;
     const normalizedRoot = normalizeFilePath(projectRoot);
-    const file = await readRegistryAsync();
     const now = new Date().toISOString();
-    const others = file.instances.filter((entry) => entry.pid !== pid);
-    const existing = file.instances.find((entry) => entry.pid === pid);
     const identity = isSubagentSession() ? getSubagentIdentity() : undefined;
     const subagent = identity
         ? {
@@ -171,17 +243,96 @@ export async function registerInstance(projectRoot) {
             runId: identity.runId,
         }
         : undefined;
-    others.push({
-        pid,
-        startedAt: existing?.startedAt ?? now,
-        projectRoot: normalizedRoot,
-        lspChildren: existing?.lspChildren ?? [],
-        lspChildCount: existing?.lspChildren?.length ?? 0,
-        rssBytes: process.memoryUsage().rss,
-        heartbeatAt: now,
-        ...(subagent ? { subagent } : {}),
+    await writeRegistryWithRetry((file) => {
+        const others = file.instances.filter((entry) => entry.pid !== pid);
+        const existing = file.instances.find((entry) => entry.pid === pid);
+        // #2130 round 2, class sweep. A `recordLspChild` that arrives before
+        // this call synthesizes the entry from `process.cwd()` and stamps
+        // `rootSource: "lsp-fallback"` to say so. Pinning made that GUESS
+        // permanent: the real session root joined the set behind it, and the
+        // host went on advertising a directory nobody asked it to serve —
+        // #2130's symptom reached through a different writer. So the first
+        // REAL registration takes the pin from a guessed primary. Any other
+        // `rootSource` ("session-cwd", "service-cwd") IS evidence of the root
+        // and keeps its pin, with this root appending behind it as usual.
+        //
+        // Review round 1, F1: ONLY index 0 is the guess. Everything behind it
+        // was appended by `registerInstanceRoot`, which is a declined
+        // secondary-root start recording a root it genuinely serves and which
+        // does not clear `rootSource`. Discarding the whole set would drop
+        // those, blinding the shared-checkout guard (#2107) to a live root —
+        // the same harm, inverted. Re-seed with the real root so it pins, then
+        // fold the rest back through `mergeInstanceRoots` so dedupe, order,
+        // and the cap stay single-owned.
+        const existingRoots = existing ? getInstanceRoots(existing) : [];
+        const roots = existing?.rootSource === "lsp-fallback"
+            ? existingRoots
+                .slice(1)
+                .reduce((acc, root) => mergeInstanceRoots(acc, root), [normalizedRoot])
+            : mergeInstanceRoots(existingRoots, normalizedRoot);
+        others.push({
+            pid,
+            startedAt: existing?.startedAt ?? now,
+            projectRoot: roots[0] ?? normalizedRoot,
+            projectRoots: roots,
+            lspChildren: existing?.lspChildren ?? [],
+            lspChildCount: existing?.lspChildren?.length ?? 0,
+            rssBytes: process.memoryUsage().rss,
+            heartbeatAt: now,
+            ...(subagent ? { subagent } : {}),
+        });
+        return { instances: others };
+    }, (file) => file.instances.some((entry) => entry.pid === pid));
+}
+/**
+ * Add ONE root to this process's existing entry (#2130), without any of
+ * `registerInstance`'s other side effects — no RSS resample, no `startedAt`
+ * reseed, no subagent-identity capture.
+ *
+ * This is what a DECLINED session start performs. `registerInstance` lives in
+ * the full-start body, below the #473/#2129 secondary gate, so a
+ * `secondary-root` start never reaches it. Without this call the temp root
+ * would be absent from `instances.json` entirely: the shared-checkout guard
+ * and warm attach would have LESS information about it than before #2130, and
+ * `deregisterInstanceRoot` would have nothing to remove.
+ *
+ * NEVER creates an entry. A declined start has no host entry to append to only
+ * when this process never registered one (the registry was reaped, or the
+ * primary's start has not landed yet). Synthesizing one here would write the
+ * TEMP root as `projectRoot` — reproducing the exact clobber #2130 is about —
+ * so this returns quietly instead. The next `registerInstance` re-creates the
+ * entry with the real root pinned.
+ *
+ * Shares the serialization tail with every other same-process registry
+ * mutation, so it cannot interleave its read-modify-write with a concurrent
+ * `registerInstance` and silently revert it (#1724).
+ */
+export function registerInstanceRoot(projectRoot) {
+    return queueRegistryMutation(() => registerInstanceRootNow(projectRoot));
+}
+async function registerInstanceRootNow(projectRoot) {
+    if (!isInstanceRegistryEnabled())
+        return;
+    const pid = process.pid;
+    const normalizedRoot = normalizeFilePath(projectRoot);
+    await withInstanceRegistryLock(registryPath(), async () => {
+        const file = await readRegistryAsync();
+        const idx = file.instances.findIndex((entry) => entry.pid === pid);
+        if (idx === -1)
+            return;
+        const current = file.instances[idx];
+        const priorRoots = getInstanceRoots(current);
+        const roots = mergeInstanceRoots(priorRoots, normalizedRoot);
+        if (roots.length === priorRoots.length &&
+            roots.every((root, index) => root === priorRoots[index]))
+            return;
+        file.instances[idx] = {
+            ...current,
+            projectRoot: roots[0] ?? current.projectRoot,
+            projectRoots: roots,
+        };
+        await writeRegistryAsync(file);
     });
-    await writeRegistryAsync({ instances: others });
 }
 /** Update this process's heartbeat/rss (and, since #620, host CPU% + live
  *  LSP children's rss/CPU%). Cheap — safe to call every turn end. */
@@ -189,40 +340,43 @@ export async function updateHeartbeat(patch = {}) {
     if (!isInstanceRegistryEnabled())
         return;
     const pid = process.pid;
-    const file = await readRegistryAsync();
-    const idx = file.instances.findIndex((entry) => entry.pid === pid);
-    if (idx === -1) {
-        // No prior registerInstance in this run (e.g. registry file was reaped
-        // out from under us, or heartbeat fired before session_start finished) —
-        // nothing to update against; skip rather than fabricate a projectRoot.
-        return;
-    }
-    const now = new Date().toISOString();
-    const current = file.instances[idx];
-    const lspChildren = patch.childUsage
-        ? current.lspChildren.map((child) => {
-            const usage = patch.childUsage?.[child.pid];
-            if (!usage)
-                return child;
-            return {
-                ...child,
-                rssBytes: usage.rssBytes ?? child.rssBytes,
-                cpuPercent: usage.cpuPercent ?? child.cpuPercent,
-            };
-        })
-        : current.lspChildren;
-    file.instances[idx] = {
-        ...current,
-        rssBytes: patch.rssBytes ?? process.memoryUsage().rss,
-        cpuPercent: patch.cpuPercent ?? current.cpuPercent,
-        lspChildren,
-        lspChildCount: lspChildren.length,
-        heartbeatAt: now,
-    };
-    await writeRegistryAsync(file);
+    await withInstanceRegistryLock(registryPath(), async () => {
+        const file = await readRegistryAsync();
+        const idx = file.instances.findIndex((entry) => entry.pid === pid);
+        if (idx === -1) {
+            // No prior registerInstance in this run (e.g. registry file was reaped
+            // out from under us, or heartbeat fired before session_start finished) —
+            // nothing to update against; skip rather than fabricate a projectRoot.
+            return;
+        }
+        const now = new Date().toISOString();
+        const current = file.instances[idx];
+        const lspChildren = patch.childUsage
+            ? current.lspChildren.map((child) => {
+                const usage = patch.childUsage?.[child.pid];
+                if (!usage)
+                    return child;
+                return {
+                    ...child,
+                    rssBytes: usage.rssBytes ?? child.rssBytes,
+                    cpuPercent: usage.cpuPercent ?? child.cpuPercent,
+                };
+            })
+            : current.lspChildren;
+        file.instances[idx] = {
+            ...current,
+            rssBytes: patch.rssBytes ?? process.memoryUsage().rss,
+            cpuPercent: patch.cpuPercent ?? current.cpuPercent,
+            lspChildren,
+            lspChildCount: lspChildren.length,
+            heartbeatAt: now,
+        };
+        await writeRegistryAsync(file);
+    });
 }
-// Every mutation below (`recordLspChild`, `removeLspChild`) reads the WHOLE
-// registry file, edits this process's own `lspChildren`, and writes the whole
+// Every mutation routed through this tail (`registerInstance`,
+// `registerInstanceRoot`, `recordLspChild`, `removeLspChild`) reads the WHOLE
+// registry file, edits this process's own entry, and writes the whole
 // file back. Two such mutations from the SAME process — e.g. a client-ceiling
 // eviction's `removeLspChild(victimPid)` racing the replacement spawn's
 // `recordLspChild(newChild)` that follows it — are ordinary concurrent async
@@ -236,22 +390,50 @@ export async function updateHeartbeat(patch = {}) {
 // and "remove" can never interleave their read-modify-write against each
 // other — the single seam both the forced-shutdown and self-crash
 // deregistration paths route through.
-let registryChildMutationTail = Promise.resolve();
-function queueRegistryChildMutation(op) {
-    const run = registryChildMutationTail.then(op);
-    registryChildMutationTail = run.catch(() => { });
+//
+// #2146: the tail must be the PROCESS's one serialization point, and module
+// scope did not deliver that. pi evaluates the pi-lens module graph up to nine
+// times per process, so this module had up to nine tails, each serializing only
+// its own callers. The dogfood run measured the consequence directly: three
+// `instance-registry-corrupt` records inside nine seconds, with two project
+// roots and one live instance's entry lost from `instances.json` — exactly the
+// torn read-modify-write this tail exists to prevent, reintroduced by
+// duplication rather than by a missing await. Keying it on `globalThis` makes
+// every evaluation queue onto the same tail.
+const REGISTRY_TAIL_FAMILY = "instance-registry.mutation-tail";
+/** Bump when the tail cell's shape changes. */
+const REGISTRY_TAIL_VERSION = 1;
+function registryTailState() {
+    return getProcessSingleton(REGISTRY_TAIL_FAMILY, REGISTRY_TAIL_VERSION, () => ({
+        tail: Promise.resolve(),
+    }));
+}
+function queueRegistryMutation(op) {
+    const state = registryTailState();
+    const run = state.tail.then(op);
+    state.tail = run.catch(() => { });
     return run;
 }
+/**
+ * Test-only: resolve once every registry mutation queued so far has landed.
+ *
+ * Several production call sites fire registry writes and deliberately do not
+ * await them (`void registerInstance(...)` in the session_start handler), so a
+ * test that reads the file straight afterwards races them. Queuing an empty op
+ * on the same tail joins the queue rather than sleeping on it, which keeps the
+ * wait exact instead of timing-dependent.
+ */
+export function _settleRegistryMutationsForTests() {
+    return queueRegistryMutation(async () => { });
+}
 /** Append/replace (by pid) an LSP child under this process's entry. */
 export function recordLspChild(entry) {
-    return queueRegistryChildMutation(() => recordLspChildNow(entry));
+    return queueRegistryMutation(() => recordLspChildNow(entry));
 }
 async function recordLspChildNow(entry) {
     if (!isInstanceRegistryEnabled())
         return;
     const pid = process.pid;
-    const file = await readRegistryAsync();
-    const idx = file.instances.findIndex((inst) => inst.pid === pid);
     const now = new Date().toISOString();
     const childEntry = {
         pid: entry.pid,
@@ -260,30 +442,61 @@ async function recordLspChildNow(entry) {
         marker: entry.marker,
         spawnedAt: now,
     };
-    if (idx === -1) {
-        // registerInstance hasn't run yet in this process (or was reaped) —
-        // synthesize a minimal entry so the child is still tracked.
-        file.instances.push({
-            pid,
-            startedAt: now,
-            projectRoot: normalizeFilePath(process.cwd()),
-            lspChildren: [childEntry],
-            lspChildCount: 1,
-            rssBytes: process.memoryUsage().rss,
-            heartbeatAt: now,
-        });
-    }
-    else {
-        const current = file.instances[idx];
-        const filtered = current.lspChildren.filter((child) => child.pid !== entry.pid);
-        filtered.push(childEntry);
-        file.instances[idx] = {
-            ...current,
-            lspChildren: filtered,
-            lspChildCount: filtered.length,
-        };
-    }
-    await writeRegistryAsync(file);
+    const hostIdentity = getSubagentIdentity();
+    await writeRegistryWithRetry((file) => {
+        const idx = file.instances.findIndex((inst) => inst.pid === pid);
+        if (idx === -1) {
+            // registerInstance hasn't run yet in this process (or was reaped) —
+            // synthesize a minimal entry so the child is still tracked.
+            recordDegradationOnce({
+                kind: "instance-registry-registration-missing",
+                subject: String(pid),
+                reason: "synthesizing host entry while recording an LSP child",
+            });
+            const identity = entry.sessionIdentity;
+            if (!identity?.projectRoot) {
+                recordDegradationOnce({
+                    kind: "instance-registry-identity-fallback",
+                    subject: String(pid),
+                    reason: "session cwd unavailable; using process cwd",
+                });
+            }
+            const projectRoot = normalizeFilePath(identity?.projectRoot ?? process.cwd());
+            file.instances.push({
+                pid,
+                startedAt: identity?.startedAt ?? now,
+                projectRoot,
+                rootSource: identity?.rootSource ?? "lsp-fallback",
+                projectRoots: [projectRoot],
+                lspChildren: [childEntry],
+                lspChildCount: 1,
+                rssBytes: process.memoryUsage().rss,
+                heartbeatAt: now,
+                ...(hostIdentity
+                    ? {
+                        subagent: {
+                            marker: hostIdentity.marker,
+                            agentType: hostIdentity.agentName,
+                            parentPid: hostIdentity.parentPid,
+                            runId: hostIdentity.runId,
+                        },
+                    }
+                    : {}),
+            });
+        }
+        else {
+            const current = file.instances[idx];
+            const filtered = current.lspChildren.filter((child) => child.pid !== entry.pid);
+            filtered.push(childEntry);
+            file.instances[idx] = {
+                ...current,
+                lspChildren: filtered,
+                lspChildCount: filtered.length,
+            };
+        }
+        return file;
+    }, (file) => file.instances.some((instance) => instance.pid === pid &&
+        instance.lspChildren.some((child) => child.pid === entry.pid)));
 }
 /**
  * Remove an LSP child (by pid) from this process's entry. `expectedMarker`,
@@ -299,33 +512,35 @@ async function recordLspChildNow(entry) {
  * of that exact pid, well inside the OS's pid-reuse latency.
  */
 export function removeLspChild(pid, expectedMarker) {
-    return queueRegistryChildMutation(() => removeLspChildNow(pid, expectedMarker));
+    return queueRegistryMutation(() => removeLspChildNow(pid, expectedMarker));
 }
 async function removeLspChildNow(pid, expectedMarker) {
     if (!isInstanceRegistryEnabled())
         return;
     const selfPid = process.pid;
-    const file = await readRegistryAsync();
-    const idx = file.instances.findIndex((inst) => inst.pid === selfPid);
-    if (idx === -1)
-        return;
-    const current = file.instances[idx];
-    const filtered = current.lspChildren.filter((child) => {
-        if (child.pid !== pid)
-            return true; // keep — different pid
-        if (expectedMarker && child.marker && child.marker !== expectedMarker) {
-            return true; // keep — pid recycled onto a differently-marked child
-        }
-        return false; // drop — this is the child we're deregistering
+    await withInstanceRegistryLock(registryPath(), async () => {
+        const file = await readRegistryAsync();
+        const idx = file.instances.findIndex((inst) => inst.pid === selfPid);
+        if (idx === -1)
+            return;
+        const current = file.instances[idx];
+        const filtered = current.lspChildren.filter((child) => {
+            if (child.pid !== pid)
+                return true; // keep — different pid
+            if (expectedMarker && child.marker && child.marker !== expectedMarker) {
+                return true; // keep — pid recycled onto a differently-marked child
+            }
+            return false; // drop — this is the child we're deregistering
+        });
+        if (filtered.length === current.lspChildren.length)
+            return; // nothing removed
+        file.instances[idx] = {
+            ...current,
+            lspChildren: filtered,
+            lspChildCount: filtered.length,
+        };
+        await writeRegistryAsync(file);
     });
-    if (filtered.length === current.lspChildren.length)
-        return; // nothing removed
-    file.instances[idx] = {
-        ...current,
-        lspChildren: filtered,
-        lspChildCount: filtered.length,
-    };
-    await writeRegistryAsync(file);
 }
 /**
  * Remove this process's entry entirely. SYNC fs only — safe to call from
@@ -336,11 +551,98 @@ export function deregisterInstance() {
     if (!isInstanceRegistryEnabled())
         return;
     const pid = process.pid;
-    const file = readRegistrySync();
-    const remaining = file.instances.filter((entry) => entry.pid !== pid);
-    if (remaining.length === file.instances.length)
-        return; // nothing to remove
-    writeRegistrySync({ instances: remaining });
+    withInstanceRegistryLockSync(registryPath(), () => {
+        const file = readRegistrySync();
+        const remaining = file.instances.filter((entry) => entry.pid !== pid);
+        if (remaining.length === file.instances.length)
+            return;
+        writeRegistrySync({ instances: remaining });
+    });
+}
+/**
+ * Drop ONE root from this process's entry (#2130) — the scoped counterpart to
+ * {@link deregisterInstance}, for a worktree this host stops serving while the
+ * host itself keeps running.
+ *
+ * SYNC fs inside, matching `deregisterInstance`'s `session_shutdown` contract
+ * (#234: no child spawns at teardown; this function spawns none). Removing the
+ * LAST root removes the whole entry — a host serving no root is not a peer any
+ * caller should find. Removing the primary promotes the next root to
+ * `projectRoot` rather than leaving a stale scalar behind.
+ *
+ * QUEUED, unlike `deregisterInstance` (#2130 round 2). The two look alike but
+ * run at opposite ends of a process's life. `deregisterInstance` runs as the
+ * HOST exits, where a queued write may never get a turn, so it must bypass the
+ * tail and write immediately. This one runs at a SECONDARY's shutdown, where
+ * the process lives on and the ordering is what matters: a declined start fires
+ * `void registerInstanceRoot(cwd)` onto the tail (index.ts:1851) and never
+ * awaits it, so a short-lived subagent reaching shutdown first would remove a
+ * root that had not been added yet. The removal found nothing, the queued add
+ * landed behind it, and the temp root LEAKED until host exit or cap eviction.
+ * Sharing the tail makes remove-after-add hold by construction.
+ *
+ * The returned promise resolves when the removal has landed. Callers in
+ * teardown paths may fire and forget it — the tail still orders the write —
+ * but they can no longer read the file straight afterwards and expect the
+ * removal to be visible.
+ */
+export function deregisterInstanceRoot(projectRoot) {
+    return queueRegistryMutation(async () => deregisterInstanceRootNow(projectRoot));
+}
+function deregisterInstanceRootNow(projectRoot) {
+    if (!isInstanceRegistryEnabled())
+        return;
+    const pid = process.pid;
+    const normalizedRoot = normalizeFilePath(projectRoot);
+    withInstanceRegistryLockSync(registryPath(), () => {
+        const file = readRegistrySync();
+        const idx = file.instances.findIndex((entry) => entry.pid === pid);
+        if (idx === -1)
+            return;
+        const current = file.instances[idx];
+        const remainingRoots = getInstanceRoots(current).filter((root) => root !== normalizedRoot);
+        if (remainingRoots.length === getInstanceRoots(current).length)
+            return;
+        if (remainingRoots.length === 0) {
+            writeRegistrySync({
+                instances: file.instances.filter((entry) => entry.pid !== pid),
+            });
+            return;
+        }
+        file.instances[idx] = {
+            ...current,
+            projectRoot: remainingRoots[0],
+            projectRoots: remainingRoots,
+        };
+        writeRegistrySync(file);
+    });
+}
+/**
+ * True when `a` and `b` are the same directory, or one contains the other.
+ * Compared on SEGMENT boundaries, so `/repo-backup` never matches `/repo`.
+ */
+function rootsOverlap(a, b) {
+    if (a === b)
+        return true;
+    const [shorter, longer] = a.length < b.length ? [a, b] : [b, a];
+    return longer.startsWith(shorter.endsWith("/") ? shorter : `${shorter}/`);
+}
+export function selectLivePeerInstances(entries, root, now = Date.now(), isPidAlive = realIsPidAlive, match = "exact") {
+    const normalizedRoot = normalizeFilePath(root);
+    return entries
+        .filter((entry) => entry.pid !== process.pid &&
+        // #2130: a host serves a SET of roots. Matching only
+        // `entry.projectRoot` made every secondary root invisible, so a peer
+        // working in the same checkout under its second root read as "no
+        // peer" — and the shared-checkout guard then allowed the destructive
+        // command it exists to block.
+        getInstanceRoots(entry).some((entryRoot) => match === "exact"
+            ? entryRoot === normalizedRoot
+            : rootsOverlap(entryRoot, normalizedRoot)) &&
+        isPidAlive(entry.pid) &&
+        Number.isFinite(Date.parse(entry.heartbeatAt)) &&
+        now - Date.parse(entry.heartbeatAt) <= STALE_HEARTBEAT_MS)
+        .sort((a, b) => Date.parse(a.startedAt) - Date.parse(b.startedAt));
 }
 /**
  * PURE aggregation over a registry snapshot: "how much CPU/RAM is pi-lens
@@ -383,9 +685,11 @@ export function computeResourceFootprint(instances, isPidAlive) {
     const perInstance = liveInstances.map((instance) => {
         const lspChildRssBytes = instance.lspChildren.reduce((sum, child) => sum + (child.rssBytes ?? 0), 0);
         const lspChildCpuPercent = instance.lspChildren.reduce((sum, child) => sum + (child.cpuPercent ?? 0), 0);
+        const roots = getInstanceRoots(instance);
         return {
             pid: instance.pid,
-            projectRoot: instance.projectRoot,
+            projectRoot: roots[0] ?? instance.projectRoot,
+            projectRoots: roots,
             rssBytes: instance.rssBytes ?? 0,
             cpuPercent: instance.cpuPercent ?? 0,
             lspChildCount: instance.lspChildren.length,
@@ -448,13 +752,19 @@ export async function getResourceFootprint(isPidAlive = realIsPidAlive) {
  *  an earlier snapshot) to narrow — not eliminate — the last-writer-wins race
  *  already accepted for this module's read-modify-write model (see the
  *  module docstring). Mirrors clients/instance-reaper.ts's
- *  `pruneDeadInstances`, kept local here rather than imported to avoid
- *  reaching back across the same import edge `realIsPidAlive` already
- *  crosses in the other direction. */
+ *  `pruneDeadInstances` in the reaper delegates here so this module owns the
+ *  registry lock seam without creating a dependency on the reaper. */
+export async function pruneDeadInstances(deadPids) {
+    const result = await withInstanceRegistryLock(registryPath(), async () => {
+        const file = await readRegistryAsync();
+        const remaining = file.instances.filter((entry) => !deadPids.has(entry.pid));
+        if (remaining.length === file.instances.length)
+            return "no-match";
+        await writeRegistryAsync({ instances: remaining });
+        return "pruned";
+    });
+    return result ?? "could-not-acquire";
+}
 async function prunePids(deadPids) {
-    const file = await readRegistryAsync();
-    const remaining = file.instances.filter((entry) => !deadPids.has(entry.pid));
-    if (remaining.length === file.instances.length)
-        return;
-    await writeRegistryAsync({ instances: remaining });
+    await pruneDeadInstances(deadPids);
 }