pi-lens 4.1.0 → 4.1.2

package/dist/clients/safe-spawn.js

@@ -37,6 +37,38 @@ export function hasSpawnFailureKind(error, kind) {
         "kind" in error &&
         error.kind === kind);
 }
+/**
+ * #2010: derive teardown evidence from observed timestamps.
+ *
+ * Pure by design so every branch is deterministically unit-testable,
+ * including the natural-exit-at-budget-expiry race where the timeout
+ * callback arms a kill against an already-dead child.
+ *
+ * - No recorded kill start (the guard saw the child already dying), no
+ *   observed death at all, or death PREDATING the kill start: the child
+ *   left on its own -> "exited", ms 0. Claiming a kill we cannot
+ *   distinguish from a natural exit would be invented evidence.
+ * - Death observed after the kill started: "escalate-kill" when the
+ *   SIGKILL escalation fired, otherwise "killed-by-signal"; ms is the
+ *   observed gap (floor 0 - clock jitter must never produce a negative).
+ */
+export function resolveTeardownOutcome(input) {
+    // Another path (abort / output-limit) owns this death: emitting teardown
+    // evidence here would describe a kill this timeout didn't perform.
+    if (input.killStartedAtMs === undefined ||
+        input.deathObservedAtMs === undefined) {
+        return undefined;
+    }
+    // True natural-exit race: the child beat the budget-expired kill by a
+    // hair - death observed before (or exactly at) the kill start.
+    if (input.deathObservedAtMs <= input.killStartedAtMs) {
+        return { ms: 0, outcome: "exited" };
+    }
+    return {
+        ms: Math.max(0, input.deathObservedAtMs - input.killStartedAtMs),
+        outcome: input.escalated ? "escalate-kill" : "killed-by-signal",
+    };
+}
 function toError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
@@ -74,7 +106,12 @@ function cwdIsUnresolvableSync(cwd) {
  */
 function commandProbablyPresent(command) {
     const exts = process.platform === "win32"
-        ? ["", ...(process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)]
+        ? [
+            "",
+            ...(process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+                .split(";")
+                .filter(Boolean),
+        ]
         : [""];
     const existsWithExt = (base) => {
         for (const ext of exts) {
@@ -192,7 +229,15 @@ function killPidTreeSync(pid) {
         return;
     }
     try {
-        process.kill(pid, "SIGKILL");
+        // #2026: negative pid = whole process group (POSIX children spawn
+        // detached), reaching grandchildren too. Any failure (ESRCH = already
+        // gone, EPERM = raced) falls through to the direct-child attempt.
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            process.kill(pid, "SIGKILL");
+        }
     }
     catch {
         // Child already exited.
@@ -268,10 +313,16 @@ function cmdEscapeArg(arg) {
  * that already worked. The `chcp 65001` prefix forces the UTF-8 code page (so
  * tool output isn't mangled by the system code page) and, as a side benefit,
  * keeps the (possibly quoted) command off the front of the line, avoiding
- * cmd.exe's `/s` outer-quote-stripping quirk.
+ * cmd.exe's `/s` outer-quote-stripping quirk. #2023: chcp is invoked via its
+ * absolute `%SystemRoot%\System32\chcp.com` path and chained with `&`, not
+ * `&&` — a child environment whose PATH cannot resolve System32 used to fail
+ * the bare `chcp` lookup, and `&&` then short-circuited EVERY .cmd/.bat spawn
+ * into exit 1 with empty output. With the pin plus `&`, even a chcp failure
+ * can never suppress the real command.
  */
 export function buildWindowsShellCommand(command, args) {
-    return `chcp 65001 >nul 2>&1 && ${[command, ...args].map(cmdEscapeArg).join(" ")}`;
+    const chcp = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\chcp.com`;
+    return `${chcp} 65001 >nul 2>&1 & ${[command, ...args].map(cmdEscapeArg).join(" ")}`;
 }
 /**
  * The extensions this resolver treats as executable suffixes on their own,
@@ -859,6 +910,15 @@ export async function safeSpawnAsync(command, args, options) {
         // a ref'd 1s timer that outlives the child it was escalating against
         // would keep a one-shot `pi --print` process alive for up to 1s.
         let escalationTimer;
+        let teardownStartedAtMs;
+        let teardownEscalated = false;
+        // #2010: teardown evidence for the spawn's OWN timeout. The wall clock
+        // starts when the budget expires and the tree-kill is issued, and stops
+        // when the process tree is observed dead (`await killPromise` settles)
+        // - measured SEPARATELY from the budget itself, so a slow teardown is
+        // visible instead of silently inflating "how long the tool ran".
+        // `teardownEscalated` names whether SIGTERM sufficed or the SIGKILL
+        // escalation fired (POSIX; Windows taskkill /F is always forceful).
         // #1114: `child.killed` is set by Node the moment `kill()` successfully
         // SENDS a signal, not when the child actually dies — so gating the
         // escalation on `!child.killed` right after a successful `SIGTERM` send
@@ -994,6 +1054,14 @@ export async function safeSpawnAsync(command, args, options) {
             return;
         }
         let child;
+        // #2026: on POSIX, run the child in its OWN process group (detached).
+        // killTree/killPidTreeSync then signal the whole GROUP (-pid), which
+        // makes grandchildren (npm -> node, sh -> sleep, etc.) die with their
+        // tool instead of surviving every timeout as orphans. Detachment stops
+        // direct terminal-signal delivery, so EVERY POSIX pid registers for
+        // lifetime cleanup - pi's signal/exit handlers forward the kill,
+        // preserving die-with-host semantics.
+        const posixProcessGroup = process.platform !== "win32";
         try {
             child = spawn(spawnCmd, spawnArgs, {
                 cwd: spawnCwd,
@@ -1001,6 +1069,7 @@ export async function safeSpawnAsync(command, args, options) {
                 windowsHide: true,
                 shell: false,
                 windowsVerbatimArguments,
+                detached: posixProcessGroup,
             });
         }
         catch (err) {
@@ -1022,7 +1091,10 @@ export async function safeSpawnAsync(command, args, options) {
             }));
             return;
         }
-        if (options?.lifetimeCoupled && child.pid) {
+        if (child.pid && (posixProcessGroup || options?.lifetimeCoupled)) {
+            // #2026: POSIX registers unconditionally - detached children no
+            // longer receive terminal signals directly, so the lifetime
+            // cleanup's signal forwarding IS their die-with-host path.
             installLifetimeCleanup();
             lifetimeState.pids.add(child.pid);
         }
@@ -1066,11 +1138,56 @@ export async function safeSpawnAsync(command, args, options) {
                     child.kill("SIGKILL");
                 }
             }
+            else if (posixProcessGroup && child.pid && child.pid > 0) {
+                // #2026: signal the whole process group. Grandchildren spawned
+                // by the tool share its group, so one signal reaches the whole
+                // tree; a negative-pid ESRCH means it already exited.
+                const pgid = -child.pid;
+                try {
+                    process.kill(pgid, "SIGTERM");
+                }
+                catch {
+                    child.kill("SIGTERM");
+                }
+                // #2027 round-1: gate the SIGKILL escalation on GROUP liveness,
+                // not direct-child death - a tool can exit instantly on SIGTERM
+                // while a SIGTERM-hardy grandchild keeps the group alive. The
+                // timer stays REF'D for group mode (max 1s tail after resolve):
+                // it is the only backstop for this group once finalize deletes
+                // the pid from lifetimeState.
+                escalationTimer = setTimeout(() => {
+                    let groupAlive = true;
+                    try {
+                        process.kill(pgid, 0);
+                    }
+                    catch {
+                        groupAlive = false;
+                    }
+                    if (!groupAlive)
+                        return;
+                    teardownEscalated = true;
+                    logLatency({
+                        type: "phase",
+                        phase: "spawn_group_kill_escalation",
+                        filePath: "",
+                        durationMs: 0,
+                        metadata: { pgid: child.pid },
+                    });
+                    try {
+                        process.kill(pgid, "SIGKILL");
+                    }
+                    catch {
+                        // Raced with group exit.
+                    }
+                }, 1000);
+            }
             else {
                 child.kill("SIGTERM");
                 escalationTimer = setTimeout(() => {
-                    if (!closed)
+                    if (!closed) {
+                        teardownEscalated = true;
                         child.kill("SIGKILL");
+                    }
                 }, 1000);
             }
         };
@@ -1119,14 +1236,21 @@ export async function safeSpawnAsync(command, args, options) {
         // boolean here, before any await, means `waitForPipeIdle` can check
         // "did close already happen" synchronously the moment it runs.
         let closeSeen = false;
+        // #2010: WHEN death was observed - the stop-clock for teardown evidence
+        // and the discriminator for its outcome. A close that predates the
+        // budget-expired kill means the child exited on its own ("exited"), no
+        // matter that the timer callback raced and armed a kill anyway.
+        let closedAtMs;
         child.on("close", () => {
             closeSeen = true;
+            closedAtMs ??= Date.now();
         });
         // Timeout handling - KILL the process, don't just abandon it
         const timeoutId = setTimeout(() => {
             timedOut = true;
             if (!killed && !child.killed) {
                 killed = true;
+                teardownStartedAtMs = Date.now();
                 killPromise = killTree();
             }
         }, timeout);
@@ -1267,11 +1391,14 @@ export async function safeSpawnAsync(command, args, options) {
             await killPromise;
             if (resolved)
                 return;
-            // #1109: the child has exited — if killTree armed the non-Windows
-            // SIGTERM→SIGKILL escalation timer and it hasn't fired yet, clear it
-            // so it doesn't linger as a ref'd handle after this promise resolves.
-            if (escalationTimer)
+            // #1109: the child has exited - clear the non-Windows escalation
+            // timer so it doesn't linger as a ref'd handle. #2027 EXCEPTION:
+            // in POSIX group mode the timer is the liveness-gated SIGKILL
+            // backstop for SIGTERM-hardy grandchildren; it stays armed and
+            // self-cleans within 1s of firing (max 1s ref'd tail).
+            if (escalationTimer && !posixProcessGroup) {
                 clearTimeout(escalationTimer);
+            }
             // #1673 review F1: latch the verdict as DECIDED here, before the
             // idle-pipe wait — not after it. `code`/`signal`/`timedOut`/`aborted`
             // are already fixed by this point (they don't change during the
@@ -1294,6 +1421,15 @@ export async function safeSpawnAsync(command, args, options) {
             const signalInfo = signal ? { signal } : {};
             if (timedOut) {
                 const cause = new Error(`Process timed out after ${timeout}ms (killed with ${signal || "SIGTERM"})`);
+                // #2010: teardown evidence lives ONLY on the timeout path - it
+                // describes how long the tree took to die after the budget
+                // expired, and how it died ("exited" = the child beat the signal;
+                // "killed-by-signal" / "escalate-kill" = how WE ended it).
+                const timeoutTeardown = resolveTeardownOutcome({
+                    killStartedAtMs: teardownStartedAtMs,
+                    deathObservedAtMs: closedAtMs,
+                    escalated: teardownEscalated,
+                });
                 resolve({
                     stdout,
                     stderr,
@@ -1301,6 +1437,7 @@ export async function safeSpawnAsync(command, args, options) {
                     error: cause,
                     failure: "timeout",
                     ...signalInfo,
+                    ...(timeoutTeardown && { timeoutTeardown }),
                     spawnFailure: new SpawnFailureError("timeout", cause.message, cause),
                     ...outputInfo,
                     resourceUsage,
@@ -1383,8 +1520,10 @@ export async function safeSpawnAsync(command, args, options) {
             closed = true;
             clearTimeout(timeoutId);
             abortSignal?.removeEventListener("abort", onAbort);
-            if (escalationTimer)
+            // #2027: group-mode timer stays armed as the grandchild backstop.
+            if (escalationTimer && !posixProcessGroup) {
                 clearTimeout(escalationTimer);
+            }
             if (child.pid)
                 lifetimeState.pids.delete(child.pid);
             const resourceUsage = finishResourceUsage();

package/dist/clients/security-scan-client.js

@@ -89,9 +89,7 @@ export class SecurityScanClient {
      */
     constructor(toolName, verbose = false) {
         this.toolName = toolName;
-        this.log = verbose
-            ? createSubsystemLogger(toolName)
-            : () => { };
+        this.log = verbose ? createSubsystemLogger(toolName) : () => { };
     }
     /**
      * Resolve (once) whether the scanner is usable, sharing the probe promise

package/dist/clients/session-event-guard.js

@@ -0,0 +1,184 @@
+/**
+ * One home for "this event arrived on a ctx the SDK already invalidated"
+ * (#1925).
+ *
+ * pi invalidates a captured extension ctx when the session is replaced —
+ * `ctx.newSession()`, `ctx.fork()`, `ctx.switchSession()`, `ctx.reload()`.
+ * Every accessor on that ctx then throws from the SDK's `assertActive()`
+ * (`core/extensions/loader.js` in the installed
+ * `@earendil-works/pi-coding-agent`). An event already queued when the swap
+ * happens still reaches pi-lens, carrying the dead ctx, and the first
+ * unguarded `ctx.signal` / `ctx.ui` / `ctx.cwd` read throws.
+ *
+ * That throw does not escape into pi's loop. `ExtensionRunner.emit` wraps every
+ * handler call in a try/catch and routes the error to `emitError`
+ * (`core/extensions/runner.js:586-606` in the installed SDK), so the throw
+ * surfaces as an extension error report against pi-lens. The report names the
+ * wrong cause. It reads as a pi-lens handler bug when the real event is a
+ * benign race with a session swap, it says nothing about which handler keeps
+ * losing, and it counts nothing. This wrapper converts that noisy misattributed
+ * error into a counted, bounded, attributable skip.
+ *
+ * #1924 fixed that for `agent_settled` with an inline try/catch. #1925 found
+ * four more handlers with the same shape. Five inline copies of one policy is
+ * the parallel-state defect AGENTS.md names, so the policy lives here instead.
+ * `agent_settled` is a consumer of this path, not a special case.
+ *
+ * ## What this module actually covers
+ *
+ * Not every `pi.on` registration in `index.ts` goes through here, and the doc
+ * used to read as if they all did. Seven do today:
+ *
+ * - {@link wrapSessionEventHandler} — `tool_result`, `turn_start`,
+ *   `agent_end`, `turn_end`, `agent_settled` (#1925) and `session_start`
+ *   (#1929). All six return nothing, so a skipped event resolving to
+ *   `undefined` is exactly their own early-exit value.
+ * - {@link wrapSessionEventHandlerWithResult} — `context` (#1929), which must
+ *   hand the host back a message list on the live path.
+ *
+ * Five registrations stay unwrapped on purpose: `resources_discover`,
+ * `session_before_fork`, `tool_call`, `session_shutdown`, and `message_end`.
+ * `tests/clients/session-event-guard-sweep.test.ts` is the source of truth for
+ * that split. It scans every registration in `index.ts` and reds unless the
+ * handler is wrapped or carries a written reason, so this paragraph can go
+ * stale but the contract cannot.
+ *
+ * The wrapper does three things and nothing else:
+ *
+ * 1. **Probes once, before dispatch.** {@link probeCtxActive} answers `false`
+ *    only when an `assertActive()`-wrapped accessor threw the SDK's own stale
+ *    message. `undefined` (no ctx, unexpected shape, unrecognised throw) is
+ *    inconclusive and always dispatches — never guess a session dead.
+ * 2. **Still classifies a stale throw that races in mid-handler.** The probe
+ *    is a point-in-time read; the swap can land between the probe and the
+ *    handler's own first ctx read, and for an async handler it can land at any
+ *    await. Both the synchronous throw and the rejected promise are
+ *    classified by {@link isStaleExtensionCtxError}.
+ * 3. **Makes the skip visible.** One bounded record and one ledger kind for
+ *    the whole class, keyed by the event name so aggregation still answers
+ *    WHICH handler is being skipped. A silent guard and a guard that never
+ *    fires read identically from a log, which is exactly how vacuous guards
+ *    survive review.
+ *
+ * Anything that is NOT the SDK's stale-ctx error propagates unchanged. The
+ * wrapper narrows nothing else: a handler bug must stay as loud as it was.
+ */
+import { emitBounded } from "./bounded-telemetry.js";
+import { probeCtxActive } from "./session-lifecycle.js";
+/**
+ * The pi SDK invalidates a captured `pi`/command ctx after a session
+ * replacement or reload; every later `pi.*` call then throws with this
+ * signature. Matched by MESSAGE — not by `===` against a captured instance —
+ * so a fire-and-forget task that races a session swap can recognise the benign
+ * stale-ctx throw and degrade to a no-op. Substring-matched on the stable
+ * "stale after session replacement or reload" phrase so it survives incidental
+ * wording changes around it.
+ *
+ * Deliberately a NARROWER match than {@link probeCtxActive}'s (which accepts
+ * the shorter "stale after session replacement", the message
+ * `ExtensionRunner.invalidate()` uses for its own probe path). Widening this
+ * one is a behavior change: it decides which throws get swallowed.
+ */
+export function isStaleExtensionCtxError(err) {
+    return (err instanceof Error &&
+        err.message.includes("stale after session replacement or reload"));
+}
+/**
+ * Record one skipped session event. Bounded per event name: the ledger counts
+ * every occurrence exactly, and only the first per event name this session
+ * also writes the detailed `latency.log` row, so a replaced session whose
+ * queue drains a hundred stale events cannot storm the log.
+ */
+function recordStaleSkip(eventName, detectedAt) {
+    emitBounded("session_event_stale_ctx_skip", eventName, {
+        durationMs: 0,
+        metadata: { event: eventName, detectedAt },
+    }, {
+        ledgerKind: "extension-ctx-stale",
+        risingEdgePer: "identity",
+        reason: `${eventName} skipped: extension ctx is stale (${detectedAt})`,
+    });
+}
+function isThenable(value) {
+    return (typeof value?.then === "function");
+}
+/**
+ * The one policy. Both public wrappers are this function with a different
+ * stale-path value, so the probe point, the classification, and the record can
+ * never drift apart between a void handler and a value-returning one.
+ */
+function guardSessionEvent(eventName, handler, onStaleResult, options) {
+    const skip = (event, detectedAt) => {
+        recordStaleSkip(eventName, detectedAt);
+        try {
+            options.dbg?.(`${eventName} skipped: extension ctx is stale after session replacement or reload`);
+        }
+        catch {
+            // A debug sink must never decide whether an event is handled.
+        }
+        return onStaleResult(event);
+    };
+    return (event, ctx) => {
+        // `false` is the only confirmed verdict. `undefined` means the probe
+        // could not tell, and an inconclusive probe must dispatch.
+        if (probeCtxActive(ctx) === false)
+            // SAFETY: `R` is the handler's declared return type, which is either a
+            // plain value or a promise of one. `skip` yields `Awaited<R>`, the
+            // settled form. TypeScript cannot see that a host awaiting an `R` is
+            // equally satisfied by the settled value, but every `pi.on` caller
+            // either awaits the result or ignores it, so both forms behave the
+            // same at the call site. The same reasoning covers the two casts
+            // below.
+            return skip(event, "pre-dispatch");
+        try {
+            const result = handler(event, ctx);
+            if (isThenable(result)) {
+                // Recover the rejection in place. The host awaits the same promise
+                // it would have awaited anyway; it just resolves instead.
+                // SAFETY: the recovered promise settles to `Awaited<R>`, which the
+                // host consumes exactly as it would an `R` — see the note above.
+                return Promise.resolve(result).catch((err) => {
+                    if (isStaleExtensionCtxError(err))
+                        return skip(event, "mid-handler");
+                    throw err;
+                });
+            }
+            return result;
+        }
+        catch (err) {
+            if (isStaleExtensionCtxError(err))
+                // SAFETY: a synchronous handler's `R` is already its settled form,
+                // so `Awaited<R>` and `R` coincide here — see the note above.
+                return skip(event, "mid-handler");
+            throw err;
+        }
+    };
+}
+/**
+ * Wrap one `pi.on` handler so a stale ctx becomes an observable no-op instead
+ * of a throw into the host.
+ *
+ * The returned function keeps the handler's own signature and its return
+ * value, so a wrapped registration is a drop-in for the bare one. A skipped
+ * event resolves to `undefined`, which is what every handler wrapped this way
+ * already returns on its early-exit paths.
+ *
+ * Use {@link wrapSessionEventHandlerWithResult} when `undefined` is NOT the
+ * handler's own no-op value.
+ */
+export function wrapSessionEventHandler(eventName, handler, options = {}) {
+    return guardSessionEvent(eventName, handler, () => undefined, options);
+}
+/**
+ * {@link wrapSessionEventHandler} for a handler whose return value the host
+ * consumes (#1929).
+ *
+ * The live path returns exactly what the handler returned. The stale path
+ * returns `onStaleResult(event)` instead of assuming `undefined`, so a handler
+ * whose no-op value is something else does not get one silently substituted.
+ * Probe, classification, and the bounded record are identical to the void
+ * wrapper's — they are the same function underneath.
+ */
+export function wrapSessionEventHandlerWithResult(eventName, handler, options) {
+    return guardSessionEvent(eventName, handler, options.onStaleResult, options);
+}

package/dist/clients/session-summary.js

@@ -31,7 +31,9 @@ export function formatSlopScoreSummary(summary) {
     }
     const topRules = summary.ruleCounts.slice(0, 3);
     const detail = topRules.length > 0
-        ? "  (" + topRules.map((entry) => entry.ruleId + " ×" + entry.count).join(", ") + ")"
+        ? "  (" +
+            topRules.map((entry) => entry.ruleId + " ×" + entry.count).join(", ") +
+            ")"
         : "";
     return `Slop score: ${summary.scorePerKloc.toFixed(1)}/KLOC${detail}`;
 }

package/dist/clients/sg-runner.js

@@ -151,9 +151,7 @@ export class SgRunner {
      */
     sweepDurablyMissing = [];
     constructor(verbose = false) {
-        this.log = verbose
-            ? createSubsystemLogger("sg-runner")
-            : () => { };
+        this.log = verbose ? createSubsystemLogger("sg-runner") : () => { };
     }
     /**
      * Check if ast-grep CLI is available, auto-install if not.

package/dist/clients/source-filter.js

@@ -72,9 +72,9 @@ export function sourceTwinCandidates(filePath) {
         : ext === ".cjs"
             ? [".cts", ".ts", ".tsx", ".mts"]
             : ext === ".jsx"
-                // Deliberately retain the broad fallback: a .jsx next to a .ts
-                // is treated as a build artifact even without a .tsx sibling.
-                ? [".tsx", ".ts", ".mts", ".cts"]
+                ? // Deliberately retain the broad fallback: a .jsx next to a .ts
+                    // is treated as a build artifact even without a .tsx sibling.
+                    [".tsx", ".ts", ".mts", ".cts"]
                 : ext === ".js"
                     ? [".ts", ".tsx", ".mts", ".cts"]
                     : [];
@@ -251,7 +251,7 @@ function classifySkipGeneratedOrArtifact(filePath, options) {
     });
 }
 function shouldSkipGeneratedOrArtifact(filePath, options) {
-    return classifySkipGeneratedOrArtifact(filePath, options).verdict === "generated";
+    return (classifySkipGeneratedOrArtifact(filePath, options).verdict === "generated");
 }
 /**
  * Extract the basename (filename without extension) from a path.
@@ -281,7 +281,8 @@ export function findSourceSibling(filePath, probeCache) {
     const dir = getDir(filePath);
     const base = getBasename(filePath);
     for (const [sourceExt, shadowedExts] of Object.entries(SOURCE_PRECEDENCE)) {
-        if (!sourceExtsForCompiledExt(sourceExt).length && shadowedExts.includes(ext)) {
+        if (!sourceExtsForCompiledExt(sourceExt).length &&
+            shadowedExts.includes(ext)) {
             const siblingPath = path.join(dir, base + sourceExt);
             if (probeExists(siblingPath, probeCache))
                 return siblingPath;
@@ -296,7 +297,10 @@ export function findSourceSibling(filePath, probeCache) {
  * Omit for the original, uncached behavior.
  */
 function sourceExtsForCompiledExt(sourceExt) {
-    return sourceExt === ".ts" || sourceExt === ".tsx" || sourceExt === ".mts" || sourceExt === ".cts"
+    return sourceExt === ".ts" ||
+        sourceExt === ".tsx" ||
+        sourceExt === ".mts" ||
+        sourceExt === ".cts"
         ? [sourceExt]
         : [];
 }
@@ -391,11 +395,15 @@ function classifyEntry(entry, fullPath, cfg, probeCache, skipCounters) {
         return { recurseInto: fullPath };
     }
     if (entry.isFile()) {
-        if (ignoreMatcher.isIgnored(fullPath, false))
-            return {};
+        // #1974: extension gate before isIgnored — isIgnored recompiles minimatch
+        // patterns per ancestor dir per call, so a large ignored-but-not-dir-
+        // prunable pile (e.g. wal/*.log) should never pay that cost for files
+        // the extension gate would have dropped anyway.
         const ext = path.extname(entry.name).toLowerCase();
         if (!extensions.has(ext))
             return {};
+        if (ignoreMatcher.isIgnored(fullPath, false))
+            return {};
         // Skip if this is a build artifact or generated/codegen output.
         // #1107: counted separately (both are observability-only — neither
         // changes what gets skipped) so an invisible coverage hole (a real

package/dist/clients/source-walker.js

@@ -31,7 +31,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { isExcludedDirName } from "./file-utils.js";
 import { isGeneratedArtifactDirectoryName } from "./generated-artifacts.js";
-import { createDeadline, yieldIfOverBudget, } from "./cooperative-budget.js";
+import { createDeadline, yieldIfOverBudget } from "./cooperative-budget.js";
 /**
  * Read a directory's entries, returning `[]` for a permission-denied or
  * missing directory instead of throwing. Shared by every walker below — a

package/dist/clients/spawn-timeout-cooldown.js

@@ -0,0 +1,96 @@
+/**
+ * Session-scoped cooldown for commands whose spawn TIMED OUT (#1995).
+ *
+ * Live evidence: one wedged `markdownlint-cli2.cmd` on Windows charged its
+ * failure budget three times for a single edit — availability verification
+ * (30s, SIGTERM), autofix `--fix` (30s), and the lint runner (15s) each paid
+ * separately, because a positive probe/cache verdict said nothing about the
+ * command's ability to COMPLETE. Total post-edit cost: 52-60 seconds.
+ *
+ * This seam is the shared negative evidence:
+ * - `noteSpawnTimeout` records that a resolved command timed out, in which
+ *   phase, and what wrapper kind it had; every record emits one bounded
+ *   latency row so the session stays auditable.
+ * - `isInSpawnTimeoutCooldown` is consulted by every invocation path for that
+ *   command — verification, autofix, and lint — so ONE wedged executable
+ *   consumes at most ONE bounded failure budget per edit (invariant 1) and a
+ *   timeout/skipped result is never re-reported as clean (invariant 4).
+ *
+ * Durability contract: SESSION. A hot loop of edits must not retry (a wedged
+ * `.cmd` shim does not heal between edits), but a new session may — the
+ * executable or its environment may have changed. Reset is registered in the
+ * session-state registry (`spawn-timeout-cooldown:latches`) and wired into
+ * `handleSessionStart`.
+ */
+import path from "node:path";
+import { logLatency } from "./latency-logger.js";
+const COOLDOWN_STATE_KEY = Symbol.for("pi-lens:spawn-timeout-cooldown");
+const _global = globalThis;
+if (!_global[COOLDOWN_STATE_KEY]) {
+    _global[COOLDOWN_STATE_KEY] = { timedOutByCommand: new Map() };
+}
+const timedOutByCommand = _global[COOLDOWN_STATE_KEY].timedOutByCommand;
+/** Wrapper kind for the telemetry record: how the command will be launched. */
+function wrapperKindOf(command) {
+    const ext = path.extname(command);
+    return ext ? ext.slice(1) : "bare";
+}
+/**
+ * Cooldown key: the command's basename minus extension, lowercased.
+ *
+ * Deliberately NOT the full resolved path: the three lanes resolve the same
+ * physical binary through different helpers (PATH-resolved absolute,
+ * `<cwd>/node_modules/.bin/...`, bare name), and cross-lane sharing is the
+ * entire point (#1995 - otherwise each lane pays its own first budget).
+ */
+function cooldownKey(command) {
+    return path
+        .basename(command)
+        .replace(/\.[^.]+$/, "")
+        .toLowerCase();
+}
+export function noteSpawnTimeout(input) {
+    const key = cooldownKey(input.command);
+    timedOutByCommand.set(key, {
+        tool: input.tool,
+        command: input.command,
+        phase: input.phase,
+        atMs: Date.now(),
+    });
+    logLatency({
+        type: "phase",
+        toolName: input.tool,
+        phase: "spawn_timeout_cooldown",
+        filePath: input.command,
+        durationMs: input.durationMs ?? 0,
+        status: "cooldown_armed",
+        metadata: {
+            command: input.command,
+            wrapperKind: wrapperKindOf(input.command),
+            timeoutPhase: input.phase,
+            ...(input.durationMs !== undefined && {
+                timeoutBudgetMs: input.durationMs,
+            }),
+            ...(input.teardown && {
+                teardownMs: input.teardown.ms,
+                teardownOutcome: input.teardown.outcome,
+            }),
+        },
+    });
+}
+/**
+ * True while `command` is cooling down after a spawn timeout. Every
+ * invocation path for this command should skip WITHOUT spawning and report
+ * an honest "not checked" outcome (skipped / 0-fixes), never clean.
+ */
+export function isInSpawnTimeoutCooldown(command) {
+    return timedOutByCommand.has(cooldownKey(command));
+}
+/**
+ * Session-start re-arm seam (registered in the session-state registry):
+ * a new session may retry a command the previous session cooled down -
+ * the executable or its environment may have changed.
+ */
+export function resetSpawnTimeoutCooldowns() {
+    timedOutByCommand.clear();
+}