@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/installer/index.js

@@ -383,6 +383,12 @@ export const TOOLS = [
         name: "Bash Language Server",
         checkCommand: "bash-language-server",
         checkArgs: ["--version"],
+        // The #2188 sweep measured a 9,667ms cold `--version` start with closed
+        // stdin — close enough to the 10s installer default that modest host
+        // contention pushes it over and emits a false verification degradation.
+        // 20s gives the same kind of headroom Vue's 30s bound gives its own
+        // slower cold start (#2176), without inventing a shared literal (#2194).
+        verificationTimeoutMs: 20_000,
         installStrategy: "npm",
         packageName: "bash-language-server",
         binaryName: "bash-language-server",
@@ -419,6 +425,11 @@ export const TOOLS = [
         name: "VSCode JSON Language Server",
         checkCommand: "vscode-json-language-server",
         checkArgs: ["--version"],
+        // The #2188 sweep measured an 11,047ms cold `--version` start with closed
+        // stdin — over the 10s installer default, so a cold or contended host can
+        // see a false verification degradation before the binary ever answers.
+        // 20s mirrors the bash-language-server bound above (#2194).
+        verificationTimeoutMs: 20_000,
         installStrategy: "npm",
         packageName: "vscode-langservers-extracted",
         binaryName: "vscode-json-language-server",
@@ -465,7 +476,8 @@ export const TOOLS = [
         id: "helm",
         name: "Helm",
         checkCommand: "helm",
-        checkArgs: ["version", "--short"],
+        // intended: version --short — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "github",
         binaryName: "helm",
         github: {
@@ -543,6 +555,11 @@ export const TOOLS = [
         name: "Prisma Language Server",
         checkCommand: "prisma-language-server",
         checkArgs: ["--version"],
+        // #2169: a real closed-stdin cold run measured 27,265ms, and a warm-cache
+        // rerun still took 9,860ms — well past the 10s installer default. 40s
+        // keeps the same margin-over-worst-observed ratio Vue's 30s bound uses
+        // (#2176) rather than trimming it for a slower binary.
+        verificationTimeoutMs: 40_000,
         installStrategy: "npm",
         packageName: "@prisma/language-server",
         binaryName: "prisma-language-server",
@@ -552,6 +569,10 @@ export const TOOLS = [
         name: "Vue Language Server",
         checkCommand: "vue-language-server",
         checkArgs: ["--version"],
+        // Vue's launcher loads the full language-service bundle before answering
+        // --version. Its cold start exceeds the dispatch probe budget on some hosts
+        // even though warm starts complete quickly (#2176).
+        verificationTimeoutMs: 30_000,
         installStrategy: "npm",
         packageName: "@vue/language-server",
         binaryName: "vue-language-server",
@@ -561,6 +582,10 @@ export const TOOLS = [
         name: "Svelte Language Server",
         checkCommand: "svelteserver",
         checkArgs: ["--version"],
+        // #2169: a real closed-stdin cold run measured 12,410ms — over the 10s
+        // installer default, matching the bash/JSON class of false verification
+        // degradation from a cold-cache host (#2194). 20s mirrors that bound.
+        verificationTimeoutMs: 20_000,
         installStrategy: "npm",
         packageName: "svelte-language-server",
         binaryName: "svelteserver",
@@ -569,7 +594,9 @@ export const TOOLS = [
         id: "markdownlint",
         name: "markdownlint-cli2",
         checkCommand: "markdownlint-cli2",
-        checkArgs: ["--version"],
+        // `--version` is interpreted as a file glob by markdownlint-cli2. Use
+        // stdin with globs disabled so verification cannot scan the workspace.
+        checkArgs: ["--no-globs", "-"],
         installStrategy: "npm",
         packageName: "markdownlint-cli2",
         binaryName: "markdownlint-cli2",
@@ -784,7 +811,8 @@ export const TOOLS = [
         id: "spotbugs",
         name: "SpotBugs",
         checkCommand: "spotbugs",
-        checkArgs: ["-version"],
+        // intended: -version — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "archive",
         binaryName: "spotbugs",
         archive: {
@@ -1030,7 +1058,8 @@ export const TOOLS = [
         id: "gitleaks",
         name: "gitleaks",
         checkCommand: "gitleaks",
-        checkArgs: ["version"],
+        // intended: version — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "github",
         binaryName: "gitleaks",
         github: {
@@ -1144,7 +1173,8 @@ export const TOOLS = [
         id: "terraform-ls",
         name: "terraform-ls",
         checkCommand: "terraform-ls",
-        checkArgs: ["version"],
+        // intended: version — unverified against real binary (shape 16), do not wire until probed
+        checkArgs: ["--version"],
         installStrategy: "github",
         binaryName: "terraform-ls",
         github: {
@@ -1216,6 +1246,7 @@ export const TOOLS = [
         id: "cue",
         name: "CUE",
         checkCommand: "cue",
+        // Probed locally with CUE v0.17.1: `cue version` exits 0.
         checkArgs: ["version"],
         installStrategy: "github",
         binaryName: "cue",
@@ -1324,6 +1355,10 @@ export const TOOLS = [
         },
     },
 ];
+/** Return the bounded managed-binary verification budget for a registered tool. */
+export function getToolVerificationTimeout(tool) {
+    return tool.verificationTimeoutMs ?? 10_000;
+}
 const ensureInFlight = new Map();
 const installFailureReasons = new Map();
 /** Last honest install refusal/failure reason for callers that need diagnostics. */
@@ -1621,8 +1656,13 @@ export async function checkProbeCache(toolId) {
     try {
         await fs.access(entry.path);
         const stat = await fs.stat(entry.path);
-        if (stat.mtimeMs !== entry.mtimeMs) {
-            logSessionStart(`auto-install probe-cache ${toolId}: miss (mtime changed)`);
+        // #2300: size alongside mtime, from the same stat — a binary replaced
+        // in-place within the same coarse-granularity mtime tick would otherwise
+        // pass this check unnoticed. `entry.sizeBytes` absent (pre-#2300 entry)
+        // fails open to the mtime-only check (see the field's doc comment).
+        if (stat.mtimeMs !== entry.mtimeMs ||
+            (entry.sizeBytes !== undefined && stat.size !== entry.sizeBytes)) {
+            logSessionStart(`auto-install probe-cache ${toolId}: miss (mtime/size changed)`);
             delete cache[toolId];
             markProbeCacheChange(toolId, null);
             return undefined;
@@ -1650,6 +1690,7 @@ export async function updateProbeCache(toolId, resolvedPath, transient = false)
         const entry = {
             path: resolvedPath,
             mtimeMs: stat.mtimeMs,
+            sizeBytes: stat.size,
             cachedAt: Date.now(),
             ...(transient && { transient: true }),
         };
@@ -1681,6 +1722,14 @@ export function resetProbeCacheStateForTesting() {
         _probeCacheFlushTimer = null;
     }
 }
+/**
+ * Exported for testing only. Read the `ensureTool` in-flight map directly
+ * (#1968's ABA regression: a second writer replacing an entry mid-flight,
+ * then a late-settling first run evicting it with a bare delete-by-key).
+ */
+export function _peekEnsureInFlightForTesting() {
+    return ensureInFlight;
+}
 // --- Check Functions ---
 const pathWalkMemo = new Map();
 function hashSync(value) {
@@ -1765,6 +1814,7 @@ export async function isSpawnableCommand(command) {
 export function isLspTransportRequiredError(output) {
     return /Connection (?:input|output) stream is not set|Use arguments of createConnection/i.test(output);
 }
+const lspTransportRequiredMatcher = /Connection (?:input|output) stream is not set|Use arguments of createConnection/i;
 /**
  * Parse the exact version pinned in a TOOLS `packageName` spec, e.g.
  * `"jscpd@3.5.10"` -> `"3.5.10"`. Scoped packages (`"@ast-grep/cli"`) have no
@@ -1796,7 +1846,7 @@ function extractVersionToken(output) {
  */
 const lastManagedInstallVersion = new Map();
 /**
- * Verify a tool binary actually works by running --version
+ * Verify a tool binary actually works by running its configured checkArgs.
  * This catches broken symlinks, partial installs, and corrupted binaries.
  * `onVersionOutput`, when provided, receives the raw stdout on a successful
  * (exit 0) probe — used to piggyback version-pin drift detection onto this
@@ -1822,7 +1872,7 @@ onTransient,
  * sensitive caller on the dispatch hot path passes a shorter one and treats
  * the expiry as transient rather than as a verdict (#1657).
  */
-timeoutMs = 10000) {
+timeoutMs = 10000, verificationArgs = ["--version"]) {
     // #2015: safeSpawnAsync instead of raw spawn. Raw spawn's timeout
     // SIGTERMed only cmd.exe on Windows (.cmd shims run shell:true), orphaning
     // the grandchild node process - which kept scanning, held handles against
@@ -1849,16 +1899,29 @@ timeoutMs = 10000) {
     // there), so no shell option exists or is needed here.
     void useShell;
     try {
-        const result = await safeSpawnAsync(execPath, ["--version"], {
+        const result = await safeSpawnAsync(execPath, verificationArgs, {
             timeout: timeoutMs,
+            input: "",
+            // A broken or version-blind language server can emit a bundled
+            // megabytes-long diagnostic on stderr. Keep verification bounded even
+            // when the child reaches its normal timeout first.
+            maxOutputBytes: 64 * 1024,
+            matchWhileStreaming: lspTransportRequiredMatcher,
         });
         const output = `${result.stdout}\n${result.stderr}`;
+        if (result.outputTruncated) {
+            recordDegradationOnce({
+                kind: "installer-verification-output-truncated",
+                subject: binPath,
+                reason: `verification output exceeded 65536 bytes (${verificationArgs.join(" ")})`,
+            });
+        }
         if (result.status === 0 && !result.error) {
-            debugLog(`Verified: ${binPath} (version: ${result.stdout.trim()})`);
+            debugLog(`Verified: ${binPath} (${verificationArgs.join(" ")}: ${result.stdout.trim()})`);
             onVersionOutput?.(result.stdout);
             return true;
         }
-        if (isLspTransportRequiredError(output)) {
+        if (result.streamingMatch || isLspTransportRequiredError(output)) {
             // Valid stdio LSP server that rejects `--version` (#208) — the
             // transport-required error proves the binary works.
             debugLog(`Verified (stdio LSP, transport-required): ${binPath}`);
@@ -1868,7 +1931,13 @@ timeoutMs = 10000) {
         // verdict from the binary (#1569 transient semantics).
         if (result.signal !== undefined || result.spawnFailure)
             onTransient?.();
-        logSessionStart(`auto-install verify: failed for ${binPath} (kind=${result.signal ? `killed-signal=${result.signal}` : result.error ? "spawn-error" : "exit-nonzero"}${result.status !== null ? `, exit=${result.status}` : ""})`);
+        const kind = result.spawnFailure?.kind ??
+            (result.signal
+                ? `killed-signal=${result.signal}`
+                : result.error
+                    ? "spawn-error"
+                    : "exit-nonzero");
+        logSessionStart(`auto-install verify: failed for ${binPath} (check=${verificationArgs.join(" ")}, kind=${kind}${result.status !== null ? `, exit=${result.status}` : ""})`);
         return false;
     }
     catch (err) {
@@ -1938,7 +2007,7 @@ export async function getAllToolStatuses() {
         }
         // 2. Check npm global
         if (tool.installStrategy === "npm") {
-            const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id);
+            const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, undefined, tool.checkArgs, getToolVerificationTimeout(tool));
             if (npmPath) {
                 status.installed = true;
                 status.source = "npm-global";
@@ -1949,7 +2018,7 @@ export async function getAllToolStatuses() {
         }
         // 3. Check pip user install
         if (tool.installStrategy === "pip") {
-            const pipPath = await findPipUserToolPath(tool.binaryName || tool.id);
+            const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, undefined, tool.checkArgs, getToolVerificationTimeout(tool));
             if (pipPath) {
                 status.installed = true;
                 status.source = "pip-user";
@@ -1981,7 +2050,7 @@ export async function getAllToolStatuses() {
         const localPath = installerPlatform() === "win32" ? `${localBase}.cmd` : localBase;
         try {
             await fs.access(localPath);
-            if (await verifyToolBinary(localPath)) {
+            if (await verifyToolBinary(localPath, undefined, undefined, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 status.installed = true;
                 status.source = "pi-lens-auto";
                 status.path = localPath;
@@ -2150,7 +2219,7 @@ async function getToolPathResolved(toolId, onTransient) {
         const cmdPath = `${localBase}.cmd`;
         try {
             await fs.access(cmdPath);
-            if (await verifyToolBinary(cmdPath, recordVersion, onTransient)) {
+            if (await verifyToolBinary(cmdPath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 return cmdPath;
             }
             logSessionStart(`auto-install verify: ${cmdPath} exists but is broken, will reinstall`);
@@ -2163,7 +2232,7 @@ async function getToolPathResolved(toolId, onTransient) {
         const exePath = `${localBase}.exe`;
         try {
             await fs.access(exePath);
-            if (await verifyToolBinary(exePath, recordVersion, onTransient)) {
+            if (await verifyToolBinary(exePath, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 return exePath;
             }
             logSessionStart(`auto-install verify: ${exePath} exists but is broken, will reinstall`);
@@ -2175,7 +2244,7 @@ async function getToolPathResolved(toolId, onTransient) {
     if (installerPlatform() !== "win32") {
         try {
             await fs.access(localBase);
-            if (await verifyToolBinary(localBase, recordVersion, onTransient)) {
+            if (await verifyToolBinary(localBase, recordVersion, onTransient, getToolVerificationTimeout(tool), tool.checkArgs)) {
                 return localBase;
             }
             logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
@@ -2191,7 +2260,7 @@ async function getToolPathResolved(toolId, onTransient) {
     if (tool.platformPackage) {
         const platformBin = resolvePlatformPackageBinary(tool);
         if (platformBin &&
-            (await verifyToolBinary(platformBin, undefined, onTransient))) {
+            (await verifyToolBinary(platformBin, undefined, onTransient, getToolVerificationTimeout(tool), tool.checkArgs))) {
             logSessionStart(`auto-install ${toolId}: resolved platform-package binary at ${platformBin}`);
             return platformBin;
         }
@@ -2213,14 +2282,14 @@ async function getToolPathResolved(toolId, onTransient) {
         return tool.checkCommand;
     }
     if (tool.installStrategy === "npm") {
-        const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, onTransient);
+        const npmPath = await findNpmGlobalToolPath(tool.binaryName || tool.id, onTransient, tool.checkArgs, getToolVerificationTimeout(tool));
         if (npmPath) {
             return npmPath;
         }
     }
     // For pip tools, also probe user-level script locations
     if (tool.installStrategy === "pip") {
-        const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, onTransient);
+        const pipPath = await findPipUserToolPath(tool.binaryName || tool.id, onTransient, tool.checkArgs, getToolVerificationTimeout(tool));
         if (pipPath) {
             return pipPath;
         }
@@ -2248,6 +2317,18 @@ async function findGitHubToolPath(binaryName) {
     }
     return undefined;
 }
+/** Resolve a release-managed binary without probing PATH first. */
+export async function findManagedToolBinary(toolId) {
+    const tool = TOOLS.find((candidate) => candidate.id === toolId);
+    if (!tool)
+        return undefined;
+    if (tool.installStrategy !== "github" &&
+        tool.installStrategy !== "maven" &&
+        tool.installStrategy !== "archive") {
+        return undefined;
+    }
+    return findGitHubToolPath(tool.binaryName || tool.id);
+}
 function hasExecutableExtension(name) {
     return /\.(exe|bat|cmd|ps1)$/i.test(name);
 }
@@ -2278,7 +2359,7 @@ function getArchiveBinaryCandidates(binaryName, platform, assetName) {
     candidates.add(`${binaryName}.cmd`);
     return [...candidates];
 }
-async function findNpmGlobalToolPath(binaryName, onTransient) {
+async function findNpmGlobalToolPath(binaryName, onTransient, verificationArgs = ["--version"], verificationTimeoutMs = 10_000) {
     const isWindows = process.platform === "win32";
     const binDirs = await getNpmGlobalBinCandidates(onTransient);
     for (const dir of binDirs) {
@@ -2291,7 +2372,7 @@ async function findNpmGlobalToolPath(binaryName, onTransient) {
         for (const candidate of candidates) {
             try {
                 await fs.access(candidate);
-                if (await verifyToolBinary(candidate, undefined, onTransient)) {
+                if (await verifyToolBinary(candidate, undefined, onTransient, verificationTimeoutMs, verificationArgs)) {
                     return candidate;
                 }
             }
@@ -2332,7 +2413,7 @@ async function getNpmGlobalBinCandidates(onTransient) {
     }
     return dirs;
 }
-async function findPipUserToolPath(binaryName, onTransient) {
+async function findPipUserToolPath(binaryName, onTransient, verificationArgs = ["--version"], verificationTimeoutMs = 10_000) {
     const isWindows = process.platform === "win32";
     const userBaseCandidates = await getPythonUserBaseCandidates();
     for (const userBase of userBaseCandidates) {
@@ -2365,7 +2446,7 @@ async function findPipUserToolPath(binaryName, onTransient) {
             for (const candidate of candidates) {
                 try {
                     await fs.access(candidate);
-                    if (await verifyToolBinary(candidate, undefined, onTransient)) {
+                    if (await verifyToolBinary(candidate, undefined, onTransient, verificationTimeoutMs, verificationArgs)) {
                         return candidate;
                     }
                 }
@@ -2837,8 +2918,10 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: "npm",
+                    checkArgs: tool.checkArgs,
                     packageName: tool.packageName,
                     binaryName: tool.binaryName,
+                    verificationTimeoutMs: tool.verificationTimeoutMs,
                 });
                 break;
             }
@@ -2849,6 +2932,7 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: tool.installStrategy,
+                    checkArgs: tool.checkArgs,
                     packageName: tool.packageName,
                 });
                 break;
@@ -2856,7 +2940,11 @@ export function getRefreshableManagedTools() {
             case "github": {
                 if (!tool.github)
                     continue;
-                refreshable.push({ toolId: tool.id, strategy: "github" });
+                refreshable.push({
+                    toolId: tool.id,
+                    strategy: "github",
+                    checkArgs: tool.checkArgs,
+                });
                 break;
             }
             case "maven": {
@@ -2865,6 +2953,7 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: "maven",
+                    checkArgs: tool.checkArgs,
                     pinnedCoordinate: mavenCoordinate(tool.maven),
                 });
                 break;
@@ -2880,6 +2969,7 @@ export function getRefreshableManagedTools() {
                 refreshable.push({
                     toolId: tool.id,
                     strategy: "archive",
+                    checkArgs: tool.checkArgs,
                     pinnedCoordinate: url,
                 });
                 break;
@@ -2951,7 +3041,8 @@ async function probeManagedToolVersion(tool) {
         return undefined;
     try {
         const result = await safeSpawnAsync(cached.path, tool.checkArgs, {
-            timeout: 10_000,
+            timeout: getToolVerificationTimeout(tool),
+            input: "",
             ignoreAmbientSignal: true,
             resourceLabel: `tool-refresh-version:${tool.id}`,
         });
@@ -3187,8 +3278,8 @@ async function verifyRefreshedArtifact(tool, installedPath) {
         await updateProbeCache(tool.id, installedPath);
         return true;
     }
-    if (!(await verifyToolBinary(installedPath))) {
-        logSessionStart(`managed-tool-refresh ${tool.id}: refreshed artifact at ${installedPath} failed its --version check`);
+    if (!(await verifyToolBinary(installedPath, undefined, undefined, getToolVerificationTimeout(tool), tool.checkArgs))) {
+        logSessionStart(`managed-tool-refresh ${tool.id}: refreshed artifact at ${installedPath} failed its verification check`);
         return false;
     }
     // Record the NEW mtime rather than leaving the persisted entry to miss its
@@ -3643,7 +3734,7 @@ async function installArchiveTool(tool) {
         return undefined;
     }
 }
-async function installNpmTool(packageName, binaryName) {
+async function installNpmTool(packageName, binaryName, verificationArgs = ["--version"], verificationTimeoutMs = 10_000) {
     try {
         // Ensure tools directory exists
         await fs.mkdir(TOOLS_DIR, { recursive: true });
@@ -3727,7 +3818,7 @@ async function installNpmTool(packageName, binaryName) {
             lastAttemptTransient = false;
             isValid = await verifyToolBinary(binPath, undefined, () => {
                 lastAttemptTransient = true;
-            });
+            }, verificationTimeoutMs, verificationArgs);
             if (isValid)
                 break;
             if (attempt < 3) {
@@ -4022,7 +4113,7 @@ export async function installTool(toolId) {
             case "npm": {
                 if (!tool.packageName || !tool.binaryName)
                     return false;
-                const npmPath = await installNpmTool(tool.packageName, tool.binaryName);
+                const npmPath = await installNpmTool(tool.packageName, tool.binaryName, tool.checkArgs, getToolVerificationTimeout(tool));
                 if (npmPath !== undefined) {
                     // #1746 review F4: an install just resolved this package's range
                     // against the registry, so record it as freshly checked. Otherwise a
@@ -4316,7 +4407,13 @@ async function ensureToolResolved(toolId, opts) {
         return await ensurePromise;
     }
     finally {
-        ensureInFlight.delete(inFlightKey);
+        // Identity-guarded release (#1968's pattern): delete only if THIS run is
+        // still the registered one. A bare delete-by-key lets a late-settling run
+        // evict a live successor a second writer registered under the same key
+        // mid-flight, after which the next caller starts a duplicate ensure/install.
+        if (ensureInFlight.get(inFlightKey) === ensurePromise) {
+            ensureInFlight.delete(inFlightKey);
+        }
     }
 }
 // --- Integration Helpers ---

package/node_modules/pi-lens/dist/clients/installer/managed-tool-refresh.js

@@ -259,6 +259,8 @@ async function installedRefreshCandidates() {
         candidates.push({
             toolId: tool.toolId,
             strategy: tool.strategy,
+            checkArgs: tool.checkArgs,
+            verificationTimeoutMs: tool.verificationTimeoutMs ?? 10_000,
             ...(tool.packageName !== undefined && { packageName: tool.packageName }),
             ...(tool.binaryName !== undefined && { binaryName: tool.binaryName }),
         });
@@ -513,7 +515,7 @@ async function performNpmRefresh(candidate, packageName, now) {
     // drops npm entries that do not.
     const binaryName = candidate.binaryName;
     const binPath = resolveManagedNpmBinPath(binaryName);
-    const verified = await verifyToolBinary(binPath);
+    const verified = await verifyToolBinary(binPath, undefined, undefined, candidate.verificationTimeoutMs, candidate.checkArgs);
     if (!verified) {
         recordDegradationOnce({
             kind: "managed-tool-refresh",

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

@@ -70,7 +70,7 @@ import { acquireQuarantinePidFileLock } from "./bounded-pid-file-lock.js";
 import { spawnCollectStdoutResult, unrefChildAndPipes, } from "./child-unref.js";
 import { incrementDegradationCount, recordDegradationOnce, } from "./degradation-ledger.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
-import { isInstanceRegistryEnabled, readInstanceRegistry, } from "./instance-registry.js";
+import { isInstanceRegistryEnabled, pruneDeadInstances as pruneDeadRegistryInstances, readInstanceRegistry, } from "./instance-registry.js";
 import { logLatency } from "./latency-logger.js";
 const isWindows = process.platform === "win32";
 /**
@@ -1226,8 +1226,8 @@ export async function sweepOrphans() {
 /** Drop dead-parent AND stale-heartbeat (#525, record-cleanup-only)
  *  instances from the registry. Re-reads immediately before
  *  writing (rather than reusing the earlier `readInstanceRegistry()` snapshot)
- *  to narrow — not eliminate — the last-writer-wins race already accepted for
- *  slice 1's read-modify-write model.
+ *  under the instance-registry lock so the reaper cannot lose a registration
+ *  or heartbeat while pruning.
  *
  *  Exported for the #1217 concurrency regression test; `sweepOrphans` is the
  *  only production caller.
@@ -1244,17 +1244,8 @@ export async function sweepOrphans() {
  *  rename, which the hand-rolled copy did not, and puts this writer back on
  *  the same scheme as the other writer of this same file. */
 export async function pruneDeadInstances(deadPids) {
-    const target = path.join(getGlobalPiLensDir(), "instances.json");
     try {
-        const raw = await fs.promises.readFile(target, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (!parsed || !Array.isArray(parsed.instances))
-            return;
-        const remaining = parsed.instances.filter((entry) => !deadPids.has(entry.pid));
-        if (remaining.length === parsed.instances.length)
-            return;
-        await fs.promises.mkdir(getGlobalPiLensDir(), { recursive: true });
-        await writeFileAtomicAsync(target, JSON.stringify({ instances: remaining }));
+        await pruneDeadRegistryInstances(deadPids);
     }
     catch {
         // best-effort

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

@@ -0,0 +1,145 @@
+/** Cross-process mutual exclusion for the machine-global instance registry. */
+import * as fs from "node:fs";
+import { randomInt } from "node:crypto";
+import * as path from "node:path";
+import { incrementDegradationCount } from "./degradation-ledger.js";
+const LOCK_STALE_MS = 5_000;
+const LOCK_WAIT_MS = 500;
+const LOCK_MIN_BACKOFF_MS = 5;
+const LOCK_MAX_BACKOFF_MS = 25;
+function lockPath(target) {
+    return `${target}.lock`;
+}
+function ownerPid(lock) {
+    try {
+        const pid = Number(fs.readFileSync(lock, "utf8").trim().split(/\s+/)[0]);
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPidAlive(pid) {
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code !== "ESRCH";
+    }
+}
+function staleLock(lock) {
+    try {
+        const stat = fs.statSync(lock);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS)
+            return true;
+        const pid = ownerPid(lock);
+        return pid !== undefined && !isPidAlive(pid);
+    }
+    catch {
+        return false;
+    }
+}
+function recordLockTimeout(target) {
+    incrementDegradationCount({
+        kind: "instance-registry-lock-timeout",
+        subject: path.resolve(target),
+        reason: `lock acquisition exhausted for ${path.basename(target)}`,
+    });
+}
+function backoffMs() {
+    return randomInt(LOCK_MIN_BACKOFF_MS, LOCK_MAX_BACKOFF_MS + 1);
+}
+function backoff() {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, backoffMs());
+}
+function ownsLock(lock) {
+    return ownerPid(lock) === process.pid;
+}
+async function releaseLock(lock) {
+    // Residual TOCTOU: ownership and unlink are separate syscalls, so a stale
+    // takeover can still replace the lock between them.
+    if (ownsLock(lock))
+        await fs.promises.unlink(lock).catch(() => { });
+}
+function releaseLockSync(lock) {
+    if (!ownsLock(lock))
+        return;
+    try {
+        fs.unlinkSync(lock);
+    }
+    catch {
+        // A stale takeover may have displaced the lock after ownership was read.
+    }
+}
+function takeOverStale(lock) {
+    if (!staleLock(lock))
+        return;
+    const displaced = `${lock}.stale-${process.pid}-${Date.now()}`;
+    try {
+        fs.renameSync(lock, displaced);
+        fs.unlinkSync(displaced);
+    }
+    catch {
+        // Another owner may have released or taken over it first.
+    }
+}
+function isLockContention(error) {
+    const code = error?.code;
+    return code === "EEXIST" || code === "EPERM" || code === "EBUSY";
+}
+export async function withInstanceRegistryLock(target, op) {
+    const lock = lockPath(target);
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    await fs.promises.mkdir(path.dirname(target), { recursive: true });
+    while (Date.now() <= deadline) {
+        try {
+            await fs.promises.writeFile(lock, `${process.pid} ${Date.now()}\n`, {
+                flag: "wx",
+            });
+        }
+        catch (error) {
+            if (!isLockContention(error))
+                throw error;
+            takeOverStale(lock);
+            if (Date.now() <= deadline)
+                await new Promise((resolve) => setTimeout(resolve, backoffMs()));
+            continue;
+        }
+        try {
+            return await op();
+        }
+        finally {
+            await releaseLock(lock);
+        }
+    }
+    recordLockTimeout(target);
+    return undefined;
+}
+export function withInstanceRegistryLockSync(target, op) {
+    const lock = lockPath(target);
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    while (Date.now() <= deadline) {
+        try {
+            fs.writeFileSync(lock, `${process.pid} ${Date.now()}\n`, { flag: "wx" });
+            try {
+                return op();
+            }
+            finally {
+                releaseLockSync(lock);
+            }
+        }
+        catch (error) {
+            if (!isLockContention(error))
+                throw error;
+            takeOverStale(lock);
+            if (Date.now() <= deadline)
+                backoff();
+        }
+    }
+    recordLockTimeout(target);
+    return undefined;
+}