@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

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

@@ -1823,80 +1823,62 @@ onTransient,
  * the expiry as transient rather than as a verdict (#1657).
  */
 timeoutMs = 10000) {
-    return new Promise((resolve) => {
-        const isWindows = installerPlatform() === "win32";
-        const hasKnownWindowsExt = /\.(cmd|exe|ps1)$/i.test(binPath);
-        // On Windows, resolve the best executable path:
-        // - extensionless → prefer .cmd (cmd.exe-safe)
-        // - .ps1 → prefer .cmd sibling to avoid PowerShell execution-policy hangs
-        // - .cmd / .exe → use as-is
-        let execPath = isWindows && !hasKnownWindowsExt ? `${binPath}.cmd` : binPath;
-        let useShell = isWindows && /\.(cmd|bat)$/i.test(execPath);
-        if (isWindows && /\.ps1$/i.test(execPath)) {
-            const cmdSibling = `${execPath.slice(0, -4)}.cmd`;
-            if (require("node:fs").existsSync(cmdSibling)) {
-                execPath = cmdSibling;
-                useShell = true;
-            }
-            else {
-                // Fall back to running without shell — cmd.exe can't run .ps1
-                useShell = false;
-            }
+    // #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
+    // the cleanup rm, and turned one slow cold-start verify into an
+    // install/verify/reinstall loop (23 SIGTERMs observed in one day).
+    // lifetimeCoupled tree-kill prevents orphans; result.signal gives a typed
+    // kill-reason for transient classification.
+    const isWindows = installerPlatform() === "win32";
+    const hasKnownWindowsExt = /\.(cmd|exe|ps1)$/i.test(binPath);
+    // On Windows, resolve the best executable path:
+    // - extensionless → prefer .cmd (cmd.exe-safe)
+    // - .ps1 → prefer .cmd sibling to avoid PowerShell execution-policy hangs
+    // - .cmd / .exe → use as-is
+    let execPath = isWindows && !hasKnownWindowsExt ? `${binPath}.cmd` : binPath;
+    if (isWindows && /\.ps1$/i.test(execPath)) {
+        const cmdSibling = `${execPath.slice(0, -4)}.cmd`;
+        if (require("node:fs").existsSync(cmdSibling)) {
+            execPath = cmdSibling;
         }
-        // When shell:true (Windows .cmd), bake args into the command string to avoid DEP0190.
-        const spawnCmd = useShell ? `"${execPath}" --version` : execPath;
-        let proc;
-        try {
-            proc = spawn(spawnCmd, useShell ? [] : ["--version"], {
-                timeout: timeoutMs,
-                stdio: ["ignore", "pipe", "pipe"],
-                shell: useShell,
-            });
+    }
+    const useShell = isWindows && /\.(cmd|bat)$/i.test(execPath);
+    // safe-spawn routes .cmd/.bat through its cmd.exe wrapper internally
+    // (shell:false always at the child boundary; the wrapper string is built
+    // there), so no shell option exists or is needed here.
+    void useShell;
+    try {
+        const result = await safeSpawnAsync(execPath, ["--version"], {
+            timeout: timeoutMs,
+        });
+        const output = `${result.stdout}\n${result.stderr}`;
+        if (result.status === 0 && !result.error) {
+            debugLog(`Verified: ${binPath} (version: ${result.stdout.trim()})`);
+            onVersionOutput?.(result.stdout);
+            return true;
         }
-        catch (err) {
-            // SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
-            // bug class, #533) — best-effort verify, resolve rather than reject.
-            // The prober itself never ran, so this says nothing about the binary.
-            logSessionStart(`auto-install verify: spawn threw for ${binPath} (${err instanceof Error ? err.message : String(err)})`);
-            onTransient?.();
-            resolve(false);
-            return;
+        if (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}`);
+            return true;
         }
-        let stdout = "";
-        let stderr = "";
-        proc.stdout?.on("data", (data) => (stdout += data));
-        proc.stderr?.on("data", (data) => (stderr += data));
-        proc.on("exit", (code, signal) => {
-            if (code === 0) {
-                debugLog(`Verified: ${binPath} (version: ${stdout.trim()})`);
-                onVersionOutput?.(stdout);
-                resolve(true);
-            }
-            else if (isLspTransportRequiredError(`${stdout}\n${stderr}`)) {
-                // Valid stdio LSP server that rejects `--version` (#208) — the
-                // transport-required error proves the binary works.
-                debugLog(`Verified (stdio LSP, transport-required): ${binPath}`);
-                resolve(true);
-            }
-            else {
-                // `code === null` (usually paired with a `signal`) means the
-                // spawn timeout fired and the process was killed before it could
-                // exit on its own — a stall, not a verdict from the binary.
-                if (code === null || signal)
-                    onTransient?.();
-                logSessionStart(`auto-install verify: failed for ${binPath} (exit=${code}${signal ? `, signal=${signal}` : ""})`);
-                resolve(false);
-            }
-        });
-        proc.on("error", (err) => {
-            const errno = err.code;
-            if (errno === "EAGAIN" || errno === "EBUSY" || errno === "ETIMEDOUT") {
-                onTransient?.();
-            }
-            logSessionStart(`auto-install verify: error for ${binPath}: ${err.message}`);
-            resolve(false);
-        });
-    });
+        // A kill (timeout fired) or spawn-boundary failure is a stall, not a
+        // 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}` : ""})`);
+        return false;
+    }
+    catch (err) {
+        // Spawn-boundary throw (Windows `spawn UNKNOWN`/EINVAL, the pidusage
+        // bug class, #533) — best-effort verify, resolve rather than reject.
+        // The prober itself never ran, so this says nothing about the binary.
+        logSessionStart(`auto-install verify: spawn threw for ${binPath} (${err instanceof Error ? err.message : String(err)})`);
+        onTransient?.();
+        return false;
+    }
 }
 /**
  * Get detailed status for all tools
@@ -3005,7 +2987,10 @@ export async function acquireManagedInstallGate(context) {
         };
     }
     if (!assertInstallAllowed(context)) {
-        return { ok: false, reason: `project trust: ${projectTrustDenialReason()}` };
+        return {
+            ok: false,
+            reason: `project trust: ${projectTrustDenialReason()}`,
+        };
     }
     // Held for the whole strategy call, not just the final write — a refresh
     // can race a concurrent `ensureTool` install of the SAME tool into the SAME
@@ -3580,7 +3565,9 @@ async function installArchiveTool(tool) {
         await fs.rm(tmpArchive, { force: true });
         if (!extracted.ok) {
             logSessionStart(`archive-install ${tool.id}: extraction failed: ${extracted.stderr} — keeping installed version`);
-            await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
+            await fs
+                .rm(tmpExtractDir, { recursive: true, force: true })
+                .catch(() => { });
             return undefined;
         }
         // Tree bundle (no launcher): the whole extracted tree IS the artifact. Verify
@@ -3596,7 +3583,9 @@ async function installArchiveTool(tool) {
             }
             catch {
                 logSessionStart(`archive-install ${tool.id}: tree marker not found at ${tmpMarker} after extraction — keeping installed version`);
-                await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
+                await fs
+                    .rm(tmpExtractDir, { recursive: true, force: true })
+                    .catch(() => { });
                 return undefined;
             }
             await swapExtractedDir(tool.id, tmpExtractDir, extractDir);
@@ -3616,7 +3605,9 @@ async function installArchiveTool(tool) {
         }
         catch {
             logSessionStart(`archive-install ${tool.id}: launcher not found at ${tmpResolvedInner} after extraction — keeping installed version`);
-            await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
+            await fs
+                .rm(tmpExtractDir, { recursive: true, force: true })
+                .catch(() => { });
             return undefined;
         }
         if (!isWindows)
@@ -3645,7 +3636,9 @@ async function installArchiveTool(tool) {
     }
     catch (err) {
         await fs.rm(tmpArchive, { force: true }).catch(() => { });
-        await fs.rm(tmpExtractDir, { recursive: true, force: true }).catch(() => { });
+        await fs
+            .rm(tmpExtractDir, { recursive: true, force: true })
+            .catch(() => { });
         logSessionStart(`archive-install ${tool.id}: install failed: ${err.message} — keeping installed version`);
         return undefined;
     }
@@ -3729,8 +3722,12 @@ async function installNpmTool(packageName, binaryName) {
         // postinstall scripts that complete asynchronously after npm exits 0.
         debugLog(`Verifying ${binaryName}...`);
         let isValid = false;
+        let lastAttemptTransient = false;
         for (let attempt = 1; attempt <= 3; attempt++) {
-            isValid = await verifyToolBinary(binPath);
+            lastAttemptTransient = false;
+            isValid = await verifyToolBinary(binPath, undefined, () => {
+                lastAttemptTransient = true;
+            });
             if (isValid)
                 break;
             if (attempt < 3) {
@@ -3738,6 +3735,18 @@ async function installNpmTool(packageName, binaryName) {
                 await new Promise((r) => setTimeout(r, 1000 * attempt));
             }
         }
+        if (!isValid && lastAttemptTransient) {
+            // #2015: a killed/spawn-failed prober is NOT a verdict about the
+            // binary (#1569 semantics). Cold-start verifies on fresh installs
+            // legitimately exceed the budget on Windows (Defender/OneDrive
+            // first-touch scanning of new node_modules). Deleting a possibly-
+            // healthy install here is what turned one slow verify into the
+            // reinstall loop - keep the installation; the next ensureTool
+            // re-probes the existing binary via discovery instead of
+            // reinstalling from scratch.
+            logSessionStart(`auto-install ${packageName}: verification inconclusive (transient); keeping installation for re-probe`);
+            return undefined;
+        }
         if (!isValid) {
             logSessionStart(`auto-install ${packageName}: installed but verification failed, cleaning up`);
             // Clean up the broken installation

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

@@ -776,7 +776,10 @@ function parseNonNegativeMs(raw) {
  * would make the whole backstop silently return zero rows, and this is the
  * one part of the fix that cannot be checked from a Windows dev machine.
  */
-export const POSIX_PS_ARGS = ["-eo", "pid=,ppid=,etime=,args="];
+export const POSIX_PS_ARGS = [
+    "-eo",
+    "pid=,ppid=,etime=,args=",
+];
 /** Parse `ps -o etime` output: `[[dd-]hh:]mm:ss`. Returns undefined for any
  *  shape the column did not produce (a `ps` without the column emits the
  *  command line where the token was expected). */
@@ -795,7 +798,7 @@ export function ageMsFromPosixEtime(raw) {
     if (parts.some((part) => !Number.isFinite(part)))
         return undefined;
     const [hours, minutes, seconds] = parts.length === 3 ? parts : [0, parts[0], parts[1]];
-    return (((days * 24 + hours) * 60 * 60 + minutes * 60 + seconds) * 1000);
+    return ((days * 24 + hours) * 60 * 60 + minutes * 60 + seconds) * 1000;
 }
 /**
  * Fire-and-forget REGISTRY-INDEPENDENT backstop sweep (#658): finds

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

@@ -36,7 +36,7 @@ import { getGlobalPiLensDir } from "./file-utils.js";
 // import is actually invoked.
 import { realIsPidAlive } from "./instance-reaper.js";
 import { normalizeFilePath } from "./path-utils.js";
-import { getSubagentIdentity, isSubagentSession, } from "./subagent-mode.js";
+import { getSubagentIdentity, isSubagentSession } from "./subagent-mode.js";
 function registryPath() {
     return path.join(getGlobalPiLensDir(), "instances.json");
 }
@@ -429,7 +429,9 @@ export function computeResourceFootprint(instances, isPidAlive) {
  */
 export async function getResourceFootprint(isPidAlive = realIsPidAlive) {
     const instances = await readInstanceRegistry();
-    const deadPids = new Set(instances.filter((instance) => !isPidAlive(instance.pid)).map((instance) => instance.pid));
+    const deadPids = new Set(instances
+        .filter((instance) => !isPidAlive(instance.pid))
+        .map((instance) => instance.pid));
     if (deadPids.size > 0) {
         // Fire-and-forget: a health-report read must never block on, or fail
         // because of, a registry write.

package/node_modules/pi-lens/dist/clients/jscpd-client.js

@@ -238,7 +238,12 @@ export class JscpdClient {
                 ".",
                 ...(hasConfig
                     ? []
-                    : ["--min-lines", String(minLines), "--min-tokens", String(minTokens)]),
+                    : [
+                        "--min-lines",
+                        String(minLines),
+                        "--min-tokens",
+                        String(minTokens),
+                    ]),
                 "--reporters",
                 "json",
                 "--output",

package/node_modules/pi-lens/dist/clients/knip-client.js

@@ -134,7 +134,9 @@ export function classifyKnipBinary(binary, targetDir) {
     if (binary === null)
         return "managed-or-path";
     const relative = path.relative(path.resolve(targetDir), path.resolve(binary));
-    return relative === "" || relative.startsWith("..") || path.isAbsolute(relative)
+    return relative === "" ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative)
         ? "global"
         : "project";
 }
@@ -199,9 +201,7 @@ export class KnipClient {
      */
     recordedToolchains = new Set();
     constructor(verbose = false) {
-        this.log = verbose
-            ? createSubsystemLogger("knip")
-            : () => { };
+        this.log = verbose ? createSubsystemLogger("knip") : () => { };
     }
     /** Re-arm content-keyed reuse at the session boundary. */
     resetSessionState() {
@@ -223,7 +223,13 @@ export class KnipClient {
      * repos often have no package.json at their own root).
      */
     resolveProjectRoot(startDir, homeDirOverride) {
-        return findNearestMarkerRoot(startDir, ["package.json", "knip.json", "knip.ts", "knip.config.js", "knip.config.ts"], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
+        return findNearestMarkerRoot(startDir, [
+            "package.json",
+            "knip.json",
+            "knip.ts",
+            "knip.config.js",
+            "knip.config.ts",
+        ], { boundaries: [".git", ".hg", ".svn"], homeDir: homeDirOverride });
     }
     /**
      * Check if knip CLI is available, auto-install if not.
@@ -332,8 +338,7 @@ export class KnipClient {
             this.log(`Analysis already in flight for ${key}; sharing result`);
             return existing;
         }
-        const promise = this.runAnalyze(key)
-            .then((result) => {
+        const promise = this.runAnalyze(key).then((result) => {
             const executed = { ...result, execution: "executed" };
             if (result.success && options.projectSeq !== undefined) {
                 this.completedByProject.set(key, {
@@ -343,12 +348,17 @@ export class KnipClient {
                 });
             }
             return executed;
-        })
-            .finally(() => {
-            this.inFlight.delete(key);
         });
-        this.inFlight.set(key, promise);
-        return promise;
+        // Identity-guarded release (#1968, #1967's pattern): delete only if
+        // THIS build is still the registered one. A bare delete-by-key lets a
+        // late-settling build A evict a live build B that replaced the entry
+        // mid-flight, and the next caller starts a duplicate.
+        const wrapped = promise.finally(() => {
+            if (this.inFlight.get(key) === wrapped)
+                this.inFlight.delete(key);
+        });
+        this.inFlight.set(key, wrapped);
+        return wrapped;
     }
     readMemoFileSignal(filePath) {
         try {
@@ -371,9 +381,12 @@ export class KnipClient {
     matchesMemoSignal(targetDir, signal) {
         const current = {
             packageJson: this.readMemoFileSignal(path.join(targetDir, "package.json")),
-            config: signal.config ? this.readMemoFileSignal(signal.config.path) : null,
+            config: signal.config
+                ? this.readMemoFileSignal(signal.config.path)
+                : null,
         };
-        return (JSON.stringify(current.packageJson) === JSON.stringify(signal.packageJson) &&
+        return (JSON.stringify(current.packageJson) ===
+            JSON.stringify(signal.packageJson) &&
             JSON.stringify(current.config) === JSON.stringify(signal.config));
     }
     async runAnalyze(targetDir) {
@@ -593,7 +606,8 @@ export class KnipClient {
         if (pinned.size === 0)
             return result;
         const isPinnedDepIssue = (issue) => (issue.type === "dependency" || issue.type === "devDependency") &&
-            (pinned.has(issue.name) || (!!issue.package && pinned.has(issue.package)));
+            (pinned.has(issue.name) ||
+                (!!issue.package && pinned.has(issue.package)));
         const issues = result.issues.filter((issue) => !isPinnedDepIssue(issue));
         const unusedDeps = result.unusedDeps.filter((issue) => !isPinnedDepIssue(issue));
         return unusedDeps.length === result.unusedDeps.length

package/node_modules/pi-lens/dist/clients/language-profile.js

@@ -279,7 +279,10 @@ export async function collectSourceFilesForWarmup(rootDir, maxFiles = MAX_WARMUP
             if (entry.isDirectory()) {
                 // Never checked symlinks — always follows them (unlike
                 // source-filter.ts's collectSourceFiles*, refs #191).
-                if (!shouldRecurseIntoDir(entry, fullPath, { ignoreMatcher, followSymlinks: true })) {
+                if (!shouldRecurseIntoDir(entry, fullPath, {
+                    ignoreMatcher,
+                    followSymlinks: true,
+                })) {
                     continue;
                 }
                 stack.push(fullPath);

package/node_modules/pi-lens/dist/clients/latency-logger.js

@@ -73,6 +73,10 @@ let recentPhases = [];
  * their own work. `lsp_scanner_coverage_gap` reports the touch's elapsed time for
  * joinability. Letting any of them win `lastPhase` would attribute a `loop_block`
  * to the record instead of to the touch that is actually stalled.
+ *
+ * #1996: `cache_usage_summary` is a zero-duration session rollup over earlier
+ * usage records. It reports no new work and therefore cannot own last-phase
+ * stall attribution.
  */
 const LAST_PHASE_EXCLUDED = new Set([
     "loop_block",
@@ -82,6 +86,7 @@ const LAST_PHASE_EXCLUDED = new Set([
     "agent_end_deferred_mutation_drain",
     "agent_end_deferred_mutation_requeue",
     "session_end_bus_rollup",
+    "cache_usage_summary",
     "lsp_aux_wait_outcome",
     "tool_set_mutation",
     "availability_decision",
@@ -221,7 +226,11 @@ export function phaseFinished(token) {
     if (!liveBrackets.delete(token))
         return;
     closedBrackets = [
-        { phase: token.phase, startedAt: token.startedAt, closedAt: new Date().toISOString() },
+        {
+            phase: token.phase,
+            startedAt: token.startedAt,
+            closedAt: new Date().toISOString(),
+        },
         ...closedBrackets,
     ].slice(0, CLOSED_BRACKET_CAP);
 }
@@ -507,7 +516,9 @@ export function resetCurrentPhaseForSession() {
 }
 export function logLatency(entry) {
     const ts = new Date().toISOString();
-    if (entry.type === "phase" && entry.phase && !LAST_PHASE_EXCLUDED.has(entry.phase)) {
+    if (entry.type === "phase" &&
+        entry.phase &&
+        !LAST_PHASE_EXCLUDED.has(entry.phase)) {
         recentPhases = [{ phase: entry.phase, ts }, ...recentPhases].slice(0, RECENT_PHASE_CAP);
     }
     if (isTestMode()) {

package/node_modules/pi-lens/dist/clients/lens-config.js

@@ -111,7 +111,7 @@ export function loadPiLensGlobalConfig(configPath = getPiLensGlobalConfigPath())
                 formatSection.mode = format.mode;
             }
             else {
-                // #533: a present-but-invalid mode (e.g. "immedaite") warns and
+                // #533: a present-but-invalid mode (e.g. "immedaite") warns and // spellchecker:disable-line
                 // falls back; an absent mode stays silent.
                 if ("mode" in format) {
                     warnInvalid('format.mode must be "immediate" or "deferred"');

package/node_modules/pi-lens/dist/clients/lens-map.js

@@ -224,7 +224,12 @@ export function aggregateGraphToFiles(graph, options) {
                 }
             }
             else {
-                files.set(id, { id, path: id, language: node.language || "", symbolCount: 0 });
+                files.set(id, {
+                    id,
+                    path: id,
+                    language: node.language || "",
+                    symbolCount: 0,
+                });
             }
             continue;
         }
@@ -394,8 +399,8 @@ function seededPosition(id, width, height) {
     const hx = fnv1a(id);
     const hy = fnv1a(`${id}\u0000y`);
     return {
-        x: (hx % 10000) / 10000 * width,
-        y: (hy % 10000) / 10000 * height,
+        x: ((hx % 10000) / 10000) * width,
+        y: ((hy % 10000) / 10000) * height,
     };
 }
 /**

package/node_modules/pi-lens/dist/clients/live-bus-emitter.js

@@ -1,6 +1,6 @@
 import { recordDegradation } from "./degradation-ledger.js";
 import { probeCtxActive } from "./session-lifecycle.js";
-import { logBusEvent, } from "./bus-events-logger.js";
+import { logBusEvent } from "./bus-events-logger.js";
 const STALE_CTX_MESSAGE = "This extension ctx is stale after session replacement";
 /** Ledger a dead activation once, at the publisher's occurrence-window guard. */
 export function recordStaleBusFailure(subject, error) {

package/node_modules/pi-lens/dist/clients/lsp/config.js

@@ -74,9 +74,7 @@ async function readLSPConfig(configPath) {
         content = await fs.readFile(configPath, "utf-8");
     }
     catch (error) {
-        if (error instanceof Error &&
-            "code" in error &&
-            error.code === "ENOENT") {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
             return undefined;
         }
         warnInvalidLSPConfig(configPath, error);
@@ -218,7 +216,8 @@ export async function initLSPConfig(cwd) {
         if (config.serverOverrides) {
             for (const [id, entry] of Object.entries(config.serverOverrides)) {
                 if (entry && typeof entry === "object" && !Array.isArray(entry)) {
-                    const initOpts = entry.initializationOptions;
+                    const initOpts = entry
+                        .initializationOptions;
                     if (initOpts !== undefined &&
                         typeof initOpts === "object" &&
                         initOpts !== null &&
@@ -291,8 +290,7 @@ export function getServersForFileWithConfig(filePath) {
  * now report the same primary-vs-auxiliary split for the same file.
  */
 export function primaryServerId(filePath) {
-    return getServersForFileWithConfig(filePath).find((s) => s.role !== "auxiliary")
-        ?.id;
+    return getServersForFileWithConfig(filePath).find((s) => s.role !== "auxiliary")?.id;
 }
 /**
  * Look up an initializationOptions override for a built-in server.