@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-lens/dist/clients/event-loop-hold.js

@@ -0,0 +1,274 @@
+/**
+ * #2507: hold the event loop for the lifetime of in-flight work that would
+ * otherwise be kept alive by NOTHING.
+ *
+ * Every handle pi-lens owns on the way to an LSP answer is deliberately
+ * unref'd. `clients/lsp/launch.ts#unrefLspProcessHandles` unrefs the language
+ * server child AND its three stdio pipes so a settled one-shot `pi --print`
+ * can exit without waiting for a lingering server (the #1097/#1110 class);
+ * `clients/child-unref.ts` does the same for every fire-and-forget probe
+ * spawn; `bounded()` and several LSP waits unref their timers for the same
+ * reason. That is correct for an IDLE process and wrong for a BUSY one: in a
+ * headless child (`pi --mode json -p --no-extensions`, stdin ignored, no TUI,
+ * no other extension holding a socket or timer) an in-flight `lsp_diagnostics`
+ * call reaches a point where the only thing it is waiting on is an unref'd
+ * timer or an unref'd pipe, libuv finds no referenced handle, and Node exits 0
+ * IN THE MIDDLE of the tool call — no error, no result, no `turn_end`. The
+ * reporter measured it against pyright; the drain site the repro lands on is
+ * `LSPService.ensureWarmForSweep`'s warm-up retry backoff (an explicitly
+ * `.unref()`'d `setTimeout`), but it is one of many: any await whose only
+ * pending handle is unref'd has the same shape.
+ *
+ * The fix is NOT to stop unref'ing — that would leak a lingering server into
+ * every settled one-shot process, which is the reason the unref exists. It is
+ * to hold ONE referenced handle for exactly as long as something is in
+ * flight: a counted keep-alive, armed while at least one hold is taken and
+ * disarmed the moment the last one is released. Idle behaviour is therefore
+ * byte-identical to before — no hold, no timer, nothing referenced.
+ *
+ * Shape 15's screen (AGENTS.md), which this follows deliberately:
+ *  - a COUNTER of tokens, not a boolean, so overlapping tool calls each
+ *    release independently and a throwing/aborted caller still releases
+ *    (callers release from `finally`);
+ *  - a bounded lifetime PER HOLD, because a leaked hold is the INVERSE defect
+ *    (a process that can never exit). Each token gets {@link
+ *    getEventLoopHoldMaxMs} measured from its OWN acquire — derived from the
+ *    longest legitimate operation's ceiling (`getWorkspaceSweepMaxHoldAgeMs`,
+ *    the full-scan wall clock plus its safety margin) rather than a second,
+ *    independently-drifting literal. The keep-alive is armed for the SOONEST
+ *    outstanding deadline; when it fires, only tokens that are actually stale
+ *    are released (with a log record naming them), and it re-arms for
+ *    whatever remains. An epoch-anchored version of this — one timer from the
+ *    first hold, clearing every token when it fired — was #2649 review F1: a
+ *    call issued late in a legitimate 300s `lens_diagnostics mode=full` was
+ *    force-released seconds after starting, i.e. #2507's drain reproduced BY
+ *    the fix.
+ *
+ * There is deliberately NO session-boundary clear here, unlike
+ * `clients/lsp/workspace-sweep-hold.ts`. A `session_start` can land mid-turn
+ * (see `clients/bootstrap.ts`), so clearing holds on a session boundary would
+ * un-hold a tool call that is still running and reintroduce this exact defect
+ * for it. The hold is scoped to one call's try/finally, not to a session.
+ */
+import { claimPhaseOncePerSession, logLatency, releaseOncePerSessionPhase, } from "./latency-logger.js";
+import { getWorkspaceSweepMaxHoldAgeMs } from "./lsp/workspace-sweep-hold.js";
+import { getProcessSingleton } from "./process-singletons.js";
+/** The one row per session proving the keep-alive was taken (#2649 F2). */
+const EVENT_LOOP_HOLD_ARMED_PHASE = "event_loop_hold_armed";
+const EVENT_LOOP_HOLD_FAMILY = "event-loop-hold";
+const EVENT_LOOP_HOLD_VERSION = 1;
+/**
+ * Process-scoped on purpose: pi evaluates the pi-lens module graph more than
+ * once in one process (see `clients/process-singletons.ts`), and what is being
+ * counted here is a property of the PROCESS's event loop, not of one module
+ * evaluation. Two copies would arm two timers for one loop.
+ */
+function state() {
+    return getProcessSingleton(EVENT_LOOP_HOLD_FAMILY, EVENT_LOOP_HOLD_VERSION, () => ({ holds: new Map(), nextHoldId: 1, timer: undefined }));
+}
+/**
+ * Upper bound on how long ONE hold — each hold, measured from its OWN
+ * acquire — may keep this process alive. Derived from `lens_diagnostics
+ * mode=full`'s own wall-clock ceiling plus the shared
+ * `SWEEP_IDLE_SAFETY_MARGIN_MS` — the same derivation the workspace-sweep
+ * hold's max-hold-age failsafe uses, so the two cannot drift apart into a
+ * relationship where the longest legitimate tool call outlives the bound that
+ * is supposed to only catch bugs.
+ */
+export function getEventLoopHoldMaxMs() {
+    return getWorkspaceSweepMaxHoldAgeMs();
+}
+/**
+ * Arm the keep-alive for the SOONEST deadline any outstanding hold has — the
+ * earliest moment a token can become stale — never for a fixed epoch from the
+ * first hold (#2649 review F1).
+ *
+ * Round 1 armed once on 0→1 and cleared every token when it fired, so a call
+ * that started while an older one was still running inherited whatever was
+ * left of the FIRST call's bound: a `lens_diagnostics mode=full` legitimately
+ * running to its 300s ceiling force-released a healthy `lsp_diagnostics`
+ * issued at t=305s, which is #2507's own drain produced by the fix. The
+ * reviewer reproduced it in a real child with the bound shortened: both calls
+ * unsettled, `active=[]`, `EXIT code=0`.
+ *
+ * Soonest-deadline, not the youngest survivor's: the youngest would let an
+ * older survivor overstay its own max age by the whole age gap. Each token is
+ * released when IT is stale and never before.
+ */
+function armForNextDeadline(current) {
+    if (current.timer !== undefined)
+        return;
+    if (current.holds.size === 0)
+        return;
+    const maxMs = getEventLoopHoldMaxMs();
+    let soonest = Number.POSITIVE_INFINITY;
+    for (const entry of current.holds.values()) {
+        soonest = Math.min(soonest, entry.acquiredAt + maxMs);
+    }
+    // A past-due deadline is left negative on purpose: Node clamps any delay
+    // below 1ms to 1ms, so it fires on a later turn of the loop either way, and
+    // a hand-written floor here would be a guard naming a recurrence that
+    // cannot happen (#2649 verify F4 — probed: 5 re-arms at delay -5000
+    // completed in 5ms, and no test reds without the floor).
+    const delayMs = soonest - Date.now();
+    // NOT `unref()`'d — referencing the loop is this timer's entire job. It is
+    // also the failsafe: when it fires, whatever is stale is over either way.
+    current.timer = setTimeout(() => reapStaleHolds(), delayMs);
+}
+function disarmIfIdle(current) {
+    if (current.holds.size > 0)
+        return;
+    if (current.timer === undefined)
+        return;
+    clearTimeout(current.timer);
+    current.timer = undefined;
+}
+/**
+ * Release every hold that has outlived {@link getEventLoopHoldMaxMs} ON ITS
+ * OWN CLOCK, log what was released, and re-arm for whatever is still
+ * outstanding. Same shape as `clients/lsp/workspace-sweep-hold.ts`'s
+ * `reapStaleHolds` — deliberately a second, independent implementation rather
+ * than a shared ledger (that consolidation is tracked separately).
+ */
+function reapStaleHolds() {
+    const current = state();
+    current.timer = undefined;
+    try {
+        const maxMs = getEventLoopHoldMaxMs();
+        const now = Date.now();
+        const released = [];
+        for (const [holdId, entry] of current.holds) {
+            if (now - entry.acquiredAt <= maxMs)
+                continue;
+            current.holds.delete(holdId);
+            released.push(entry);
+        }
+        if (released.length > 0) {
+            recordForceReleased(released, current.holds.size, maxMs, now);
+        }
+    }
+    finally {
+        // A survivor is held by nothing until this re-arms — the drain — and
+        // forever if it never does — the leak. In a `finally` because this runs
+        // inside a timer callback, where anything that escapes is an uncaught
+        // exception, and because the round-2 code put the log between the reap
+        // and the re-arm: a throwing sink stranded the survivor (#2649 verify
+        // F3). The map is already consistent by here — entries are deleted
+        // before anything is logged.
+        armForNextDeadline(current);
+    }
+}
+/**
+ * The force-release record, and its own absorption. Telemetry may not break
+ * the guard it observes — the house rule spelled at
+ * `clients/runtime-tool-call.ts`'s blocked-attribution cleanup: a guard that
+ * fails because its telemetry broke is worse than no guard. Nothing here has
+ * a fallback sink to escalate to; the keep-alive's correctness does not
+ * depend on the row being written.
+ */
+function recordForceReleased(released, stillHeld, maxMs, now) {
+    try {
+        const oldestAcquiredAt = Math.min(...released.map((entry) => entry.acquiredAt));
+        logLatency({
+            type: "phase",
+            phase: "event_loop_hold_force_released",
+            filePath: "",
+            durationMs: now - oldestAcquiredAt,
+            metadata: {
+                maxHoldMs: maxMs,
+                releasedHolds: released.length,
+                stillHeld,
+                labels: [...new Set(released.map((entry) => entry.label))].slice(0, 8),
+            },
+        });
+    }
+    catch {
+        // see the doc comment — a broken sink must not reach the reap path
+    }
+}
+/**
+ * ONE row per session saying the keep-alive was actually taken (#2649 review
+ * F2). Without it the only record this module ever writes is the failsafe, so
+ * a silent log cannot distinguish "working as designed" from "never wired at
+ * all" — the #2526 gap shape. Claimed through the logger's own
+ * once-per-session mechanism rather than a private latch, so the "one row per
+ * session" a reader counts against is the same property `config_resolved`
+ * has.
+ */
+function recordFirstArm(entry, maxMs) {
+    try {
+        if (!claimPhaseOncePerSession(EVENT_LOOP_HOLD_ARMED_PHASE, "process")) {
+            return;
+        }
+        logLatency({
+            type: "phase",
+            phase: EVENT_LOOP_HOLD_ARMED_PHASE,
+            filePath: "",
+            durationMs: 0,
+            metadata: { label: entry.label, maxHoldMs: maxMs },
+        });
+    }
+    catch {
+        // This runs on the ACQUIRE path, and `normalizeToolDefinition` takes the
+        // hold outside its own try — so a throw here rejected the tool call with
+        // the sink's error instead of returning the tool's result (#2649 verify
+        // F3). Same house rule as `recordForceReleased` above: the hold is
+        // already taken and armed by this point, so absorbing the throw loses a
+        // log row and nothing else.
+    }
+}
+/**
+ * Take one hold for the lifetime of a piece of in-flight work, and return its
+ * release. Callers MUST release from a `finally` block: a throw, a rejection
+ * or an abort has to release exactly like a normal return, or the hold leaks
+ * and the process stops being able to exit.
+ *
+ * The release is identity-guarded and idempotent — calling it twice, or after
+ * the max-age failsafe already force-released it, is a no-op and never
+ * disarms another caller's hold.
+ */
+export function acquireEventLoopHold(label) {
+    const current = state();
+    const holdId = current.nextHoldId++;
+    const entry = { acquiredAt: Date.now(), label };
+    current.holds.set(holdId, entry);
+    const wasArmed = current.timer !== undefined;
+    armForNextDeadline(current);
+    if (!wasArmed)
+        recordFirstArm(entry, getEventLoopHoldMaxMs());
+    return () => {
+        const now = state();
+        if (!now.holds.delete(holdId))
+            return;
+        disarmIfIdle(now);
+    };
+}
+/** Test-only: how many holds are outstanding right now. */
+export function _eventLoopHoldCountForTests() {
+    return state().holds.size;
+}
+/**
+ * Test-only: the keep-alive handle's own state. `hasRef` is the property the
+ * whole fix rests on — a handle that is armed but unref'd holds nothing — so
+ * it is read from the live `Timeout` (`hasRef()`), not asserted from the
+ * source text.
+ */
+export function _eventLoopKeepAliveForTests() {
+    const timer = state().timer;
+    return {
+        armed: timer !== undefined,
+        hasRef: timer?.hasRef?.() === true,
+    };
+}
+/** Test-only: drop every hold and disarm, between tests. */
+export function _resetEventLoopHoldForTests() {
+    // This module's own phase only — never a blanket clear of a structure other
+    // producers claim in (`releaseOncePerSessionPhase`'s doc comment).
+    releaseOncePerSessionPhase(EVENT_LOOP_HOLD_ARMED_PHASE);
+    const current = state();
+    current.holds.clear();
+    if (current.timer !== undefined)
+        clearTimeout(current.timer);
+    current.timer = undefined;
+    current.nextHoldId = 1;
+}

package/node_modules/pi-lens/dist/clients/event-loop-monitor.js

@@ -88,14 +88,14 @@ export function startEventLoopMonitor(resolutionMs = 20) {
  * every block that tier cares about while keeping sub-second jitter — where
  * measurement slop rivals the signal — out of the verdict.
  */
-export const STALL_CLASSIFY_FLOOR_MS = 1000;
+const STALL_CLASSIFY_FLOOR_MS = 1000;
 /**
  * Slack allowed to the CPU budget before a block counts as unaccounted.
  * `process.cpuUsage()` and the histogram are sampled at slightly different
  * instants and the histogram quantizes, so a block whose CPU coverage is
  * within this much of exact is called `cpu-accounted`, not a stall.
  */
-export const STALL_CLASSIFY_SLOP_MS = 250;
+const STALL_CLASSIFY_SLOP_MS = 250;
 /**
  * Split a block into compute-vs-stall from the CPU it could possibly have
  * burned (#1980). Pure, so the discrimination is testable without the native

package/node_modules/pi-lens/dist/clients/extension-log.js

@@ -23,10 +23,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensDir } from "./file-utils.js";
+import { getGlobalPiLensLogDir } from "./probe-home-state.js";
 import { getMaxLogSizeMB } from "./log-cleanup.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
-export const EXTENSION_LOG_FILE = path.join(getGlobalPiLensDir(), "extension.log");
+export const EXTENSION_LOG_FILE = path.join(getGlobalPiLensLogDir(), "extension.log");
 const writer = createNdjsonLogger({
     filePath: EXTENSION_LOG_FILE,
     maxBytes: getMaxLogSizeMB() * 1024 * 1024,

package/node_modules/pi-lens/dist/clients/feature-hints.js

@@ -1,8 +1,9 @@
+import { escapeRegExp } from "./string-utils.js";
 function normalizeHintInput(value) {
     return value.replace(/\\/g, "/");
 }
 function hasHintToken(value, tokens) {
-    const escaped = tokens.map((token) => token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    const escaped = tokens.map((token) => escapeRegExp(token));
     const alternatives = escaped.join("|");
     // Path/word boundaries are deliberately explicit: a token must occupy a
     // segment (or a dot/dash/underscore-separated word), never an arbitrary

package/node_modules/pi-lens/dist/clients/file-kinds.js

@@ -92,7 +92,7 @@ export const KIND_EXTENSIONS = {
     zig: [".zig", ".zon"],
 };
 /** Return whether a path has an extension registered for the given file kind. */
-export function hasKindExtension(filePath, kind) {
+function hasKindExtension(filePath, kind) {
     const extension = extname(filePath).toLowerCase();
     return KIND_EXTENSIONS[kind].some((candidate) => candidate === extension);
 }
@@ -284,18 +284,6 @@ export const NON_CODE_KINDS = new Set([
     "toml",
     "yaml",
 ]);
-/**
- * Check if a file kind represents a code file (not config/markdown).
- */
-export function isCodeKind(kind) {
-    return CODE_KINDS.has(kind);
-}
-/**
- * Check if a file kind represents a text/config/doc/markup file.
- */
-export function isConfigKind(kind) {
-    return NON_CODE_KINDS.has(kind);
-}
 /**
  * Check if a file path resolves to a {@link CODE_KINDS} kind. Undetectable
  * files (unknown extension, e.g. `.coffee` from SOURCE_PRECEDENCE) are
@@ -351,31 +339,6 @@ export function getFileKindLabel(kind) {
     };
     return labels[kind] ?? kind;
 }
-/**
- * Get file extensions for a file kind.
- */
-export function getExtensionsForKind(kind) {
-    return [...(KIND_EXTENSIONS[kind] ?? [])];
-}
-/**
- * Check if a file should be scanned for linting/formatting.
- * Excludes test files, generated files, etc.
- */
-export function isScannableFile(filePath) {
-    const kind = detectFileKind(filePath);
-    if (!kind)
-        return false;
-    // Exclude test files for most kinds
-    const base = basename(filePath);
-    if (base.includes(".test.") ||
-        base.includes(".spec.") ||
-        base.startsWith("test-") ||
-        base.startsWith("spec-")) {
-        return false;
-    }
-    // Only scan code and config files
-    return isCodeKind(kind) || isConfigKind(kind);
-}
 /**
  * Get the language identifier for LSP/tools that use language IDs.
  */

package/node_modules/pi-lens/dist/clients/file-time.js

@@ -95,7 +95,12 @@ export class FileTime {
         const lockPromise = fn().finally(() => {
             globalState.locks.delete(absolutePath);
         });
-        globalState.locks.set(absolutePath, lockPromise.then(() => { }));
+        // The STORED lock promise must never reject unhandled: a rejecting fn
+        // (e.g. partial-apply's pre-write rejection, #2402) would otherwise leave
+        // an orphaned rejected promise on every withLock caller. Waiters awaiting
+        // the stored copy still resume — the finally above already deleted the
+        // lock entry by the time the rejection settles.
+        globalState.locks.set(absolutePath, lockPromise.then(() => { }, () => { }));
         return lockPromise;
     }
     /**
@@ -114,7 +119,7 @@ export class FileTime {
     }
 }
 // --- Error Type ---
-export class FileTimeError extends Error {
+class FileTimeError extends Error {
     filePath;
     reason;
     constructor(message, filePath, reason) {

package/node_modules/pi-lens/dist/clients/file-utils.js

@@ -5,10 +5,11 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Minimatch } from "./deps/minimatch.js";
+import { FRESHNESS_CADENCE_MS } from "./freshness-cadence.js";
 import { isInSpawnTimeoutCooldown, noteSpawnTimeout, } from "./spawn-timeout-cooldown.js";
 import { collectTrackedFiles, getTrackedFilesSnapshot, } from "./git-tracked-ignore.js";
 import { getGlobalIgnorePatterns, getPiLensGlobalConfigPath, } from "./lens-config.js";
-import { isUnderDir, normalizeEphemeralMapKey, normalizeFilePath, } from "./path-utils.js";
+import { homeRelativePath, isExternalOrVendorFile, isUnderDir, normalizeEphemeralMapKey, normalizeFilePath, toProjectRelativePath, } from "./path-utils.js";
 import { findPiLensConfigInDir, findPiLensProjectConfig, loadPiLensConfigInDir, loadPiLensProjectConfig, } from "./project-lens-config.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 /**
@@ -42,27 +43,101 @@ export function getProjectDataDir(cwd) {
         .replace(/-+$/, ""); // trim trailing dashes
     return path.join(base.trim(), slug || "default");
 }
+/**
+ * The project-data path to SHOW an agent or a human, for a file that
+ * {@link getProjectDataDir} owns.
+ *
+ * #2521: the turn-end actionable-warnings advisory told the agent to read a
+ * hardcoded `.pi-lens/cache/actionable-warnings.json`, but that spelling is
+ * only correct in the LEGACY arm of `getProjectDataDir` — a project with no
+ * `.pi-lens/` directory (the common case) stores the report under
+ * `~/.pi-lens/projects/<slug>/cache/`, and a `PILENS_DATA_DIR` project stores
+ * it somewhere else again. Agents followed the advisory literally and got
+ * `cat: .pi-lens/cache/actionable-warnings.json: No such file or directory`.
+ *
+ * Any instructional string that NAMES a project-data location must be built
+ * here, so the displayed path and the written path can never disagree. Guarded
+ * by `tests/clients/data-dir-display-path-sweep.test.ts`.
+ *
+ * Two output shapes, matching `toRunnerDisplayPath`'s convention
+ * (`clients/dispatch/runner-context.ts`) so one advisory never mixes styles:
+ *   - under `cwd` → a `/`-separated path relative to it
+ *     (`.pi-lens/cache/actionable-warnings.json`), which is what the legacy
+ *     arm produces and what an agent can paste straight into a shell.
+ *   - anywhere else → absolute, `/`-separated, and `~`-folded via
+ *     {@link homeRelativePath} so the default `~/.pi-lens/projects/...` store
+ *     does not leak the account name into agent context (#2440 F5).
+ *
+ * Pure string work on top of `getProjectDataDir`'s own resolution: it never
+ * stats the target, so it is safe to call for a file that has not been written
+ * yet and cannot throw on a surface whose whole job is to render a hint.
+ *
+ * The relative-or-absolute decision reuses `toProjectRelativePath`
+ * (`clients/path-utils.ts`) — the same shape-aware, non-stat'ing primitive
+ * `toRunnerDisplayPath` (`clients/dispatch/runner-context.ts`) composes for
+ * the analogous "relative path if under this root, else something else"
+ * decision — rather than a second hand-rolled `path.relative` fold. It is NOT
+ * `toRunnerDisplayPath` itself: that helper routes its result through
+ * `normalizeMapKey`, which on win32 calls `realpathSync.native()` (or, for a
+ * not-yet-existing path, lowercases the unresolved tail) — exactly the
+ * stat-and-mutate-casing behavior this function's contract above rules out.
+ */
+export function displayProjectDataPath(cwd, ...segments) {
+    const absolute = path.resolve(getProjectDataDir(cwd), ...segments);
+    const absolutePosix = absolute.replace(/\\/g, "/");
+    const relative = toProjectRelativePath(absolute, cwd);
+    if (relative !== absolutePosix) {
+        return relative;
+    }
+    // `toProjectRelativePath` fell back to the (posix-ified) absolute path —
+    // `absolute` is not under `cwd`. Fold `~` so the default
+    // `~/.pi-lens/projects/...` store does not leak the account name into
+    // agent context (#2440 F5). Posix-ify BEFORE the fold: `homeRelativePath`
+    // deliberately returns a path that is not under `$HOME` unchanged,
+    // separators included, so a `PILENS_DATA_DIR=D:\lens-data` store would
+    // otherwise render with backslashes while the legacy arm above renders
+    // with forward ones — `absolutePosix` is already folded, so this is a
+    // no-op fold, not a second one.
+    return homeRelativePath(absolutePosix);
+}
 /**
  * Machine-global pi-lens directory: `~/.pi-lens/` by default.
  *
- * Used for logs (latency, cascade, read-guard, tree-sitter, actionable-warnings,
- * sessionstart), tool binaries (`~/.pi-lens/tools/`, `~/.pi-lens/bin/`), the
- * cross-process instance registry (`instances.json`, #449/#525), the
- * auto-install probe cache, and other state that is intentionally NOT
- * project-scoped — it spans every project pi-lens has touched.
+ * Used for tool binaries (`~/.pi-lens/tools/`, `~/.pi-lens/bin/`), the
+ * cross-process instance registry (`instances.json`, #449/#525) and the
+ * orphan-backstop lease beside it, the auto-install probe cache, the
+ * canonical global config (`config.json`), LSP server storage (intelephense's
+ * index, PSES's per-PID session dir) and JVM runtimes — state that is
+ * intentionally NOT project-scoped, because it spans every project pi-lens
+ * has touched.
  *
  * Override: set `PI_LENS_HOME=/some/path` to relocate this ENTIRE root (every
- * caller below routes through this one function, so one env var covers all of
+ * caller routes through this one function, so one env var covers all of
  * them — see #525). Tests MUST set this to a per-worker temp dir in
  * `tests/support/vitest-setup.ts` rather than mocking each caller separately;
  * otherwise a test that exercises `registerInstance`/`sweepOrphans` or any
  * logger writes into the developer's REAL `~/.pi-lens` (dogfooded live: a
  * test-fixture instance survived in the real `instances.json` for 17h).
  *
+ * DELIBERATELY cwd-INDEPENDENT (#2506 round 3). Its sibling
+ * `getGlobalPiLensLogDir()` (`probe-home-state.ts`) carries the probe-home
+ * redirect; this one must not, because the things resolved here are shared
+ * machine state a session needs to KEEP: a pi session running from an agent
+ * worktree or a throwaway temp project must still find the tools it already
+ * installed and must still register in the one `instances.json` every other
+ * pi-lens process on the box reads. Redirecting THIS function (as round 2 of
+ * #2506 did) would silently give every worktree its own empty tool tree and
+ * its own private registry, so the reaper could never see across them — a
+ * worse defect than the telemetry pollution the redirect exists to stop.
+ *
  * Distinct from `getProjectDataDir(cwd)`, which respects `PILENS_DATA_DIR`
  * (project-scoped) and produces per-project subdirectories. Callers writing
  * project caches, snapshots, or worklogs should use `getProjectDataDir(cwd)`
  * instead — `PI_LENS_HOME` is the MACHINE-scoped sibling of that override.
+ * `getProjectDataDir` composes through THIS function, not the log one: a
+ * probe's project caches are already isolated by its own path slug, and a
+ * worktree session keeping its warm caches is the same "do not break the
+ * session" argument as the tools above.
  */
 export function getGlobalPiLensDir() {
     const override = process.env.PI_LENS_HOME?.trim();
@@ -227,7 +302,7 @@ function matchesGitignorePattern(pattern, relativePath, isDirectory, matchExpand
         return candidates.some((value) => matchExpanded(value, expanded));
     });
 }
-export function readGitignorePatterns(rootDir, layer = "gitignore") {
+function readGitignorePatterns(rootDir, layer = "gitignore") {
     const gitignorePath = path.join(rootDir, ".gitignore");
     try {
         return parseGitignoreContent(fs.readFileSync(gitignorePath, "utf-8"), layer);
@@ -493,8 +568,17 @@ export function createProjectIgnoreMatcher(rootDir, extraPatterns = [], globalPa
     return buildProjectIgnoreMatcher(resolvedRoot, patterns);
 }
 const projectIgnoreMatcherCache = new Map();
-/** Nested ignore sources are checked at most once per root per cadence window. */
-export const PROJECT_IGNORE_FRESHNESS_CADENCE_MS = 2_000;
+/**
+ * Nested ignore sources are checked at most once per root per cadence window.
+ * Sourced from the shared leaf (`freshness-cadence.ts`) rather than owning the
+ * value: `project-lens-config.ts`'s no-config discovery cache (#2483 round 2)
+ * needs the same cadence and cannot import it FROM here, because this module
+ * already imports `project-lens-config.ts` (the `clients/` acyclic-imports
+ * rule would reject the reverse edge). Re-exported under this name so the
+ * existing test imports (`tests/clients/project-ignore-freshness.test.ts` and
+ * siblings) are unaffected.
+ */
+export const PROJECT_IGNORE_FRESHNESS_CADENCE_MS = FRESHNESS_CADENCE_MS;
 function fileFreshnessSignature(filePath) {
     try {
         const stat = fs.statSync(filePath);
@@ -627,6 +711,25 @@ export function invalidateProjectIgnoreMatcherForPath(filePath) {
 export function isPathIgnoredByProject(filePath, rootDir, isDirectory = false) {
     return getProjectIgnoreMatcher(rootDir).isIgnored(filePath, isDirectory);
 }
+/**
+ * "Is this a project-source path pi-lens's bookkeeping should care about" —
+ * the `isPathIgnoredByProject` + `isExternalOrVendorFile` pair, previously
+ * hand-duplicated at each of its 2 call sites (`registerReadBridge` and
+ * `registerMutationBridge` in `index.ts`, both #2423). Consolidated here
+ * (#2450 review round 2, F4) when a THIRD call site — `tools/lsp-navigation.ts`
+ * threading the same gate onto its directly-threaded `LspMutationContext`, so
+ * the direct LSP-mutation path and the mutation-bridge fallback path apply
+ * the identical gate instead of the fallback silently being narrower. A
+ * caller still layers its own `no-read-guard`-style flag check on top; that
+ * flag has no file path to check against, so it stays outside this helper.
+ */
+export function isRecordableProjectPath(filePath, projectRoot) {
+    if (isPathIgnoredByProject(filePath, projectRoot, false))
+        return false;
+    if (isExternalOrVendorFile(filePath, projectRoot))
+        return false;
+    return true;
+}
 const projectIgnoreGlobsCache = new Map();
 export function getProjectIgnoreGlobs(rootDir) {
     const resolvedRoot = path.resolve(rootDir);
@@ -659,7 +762,11 @@ export function readGitignoreDirs(rootDir) {
         .map((entry) => entry.pattern);
 }
 function globToRegExp(glob) {
+    // Directory names use the same `*`-only dialect as read-guard exemptions.
+    // Collapse adjacent stars before compiling to avoid nullable-group
+    // backtracking on a non-matching name (#2622).
     const escaped = glob
+        .replace(/\*+/g, "*")
         .replace(/[.+^${}()|[\]\\]/g, "\\$&")
         .replace(/\*/g, ".*")
         .replace(/\?/g, ".");