@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

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/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-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;
     }
     /**

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();
@@ -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);

package/node_modules/pi-lens/dist/clients/finding-delivery-gate.js

@@ -87,17 +87,45 @@
  * degrade; they satisfy the same rule by dropping the authority marker
  * alongside the coordinate.
  *
- * ── Retirement (#1944) ────────────────────────────────────────────────────
- * Demote-not-drop assumes the agent CAN re-run to confirm. A past-EOF
- * demotion breaks that assumption: the file shrank past the cited lines, so
- * no re-run can ever speak to them, and the record re-served on every turn
- * end for the life of the session. Such a record is delivered ONCE, degraded,
- * then retired (`RuntimeCoordinator.retireDemotedPastEofBlocker`). The
- * suppression is recorded in the degradation ledger under
- * `demoted-finding-retired`, whose subject keeps the store and file, and the
- * delivered payload says so in its own words — so an empty advisory section
- * can only mean "nothing to say". Dependency-drift demotions keep in-bounds
- * coordinates the agent can act on and are NOT retired.
+ * ── Retirement (#1944, #1950, #2275) ──────────────────────────────────────
+ * Demote-not-drop assumes the agent CAN re-run to confirm. Retirement is what
+ * happens when re-serving a demotion forever stops being honest. Every kind
+ * of retirement records itself in the degradation ledger under
+ * `demoted-finding-retired`, whose subject keeps the store and the file
+ * (`inline-blocker:` / `widget-blocker:`), so an empty section can only mean
+ * "nothing to say". There are three, and they differ in WHY and in HOW MUCH
+ * they remove:
+ *
+ * 1. Past-EOF, unrecoverable (#1944). The file shrank past the cited lines,
+ *    so no re-run can ever speak to them. Delivered ONCE, degraded, then the
+ *    record is DROPPED (`RuntimeCoordinator.retireDemotedPastEofBlocker`).
+ *
+ * 2. Dependency-drift, inline-blocker channel (#1950). The coordinates are
+ *    still in bounds and a re-run COULD confirm them, so this is a delivery
+ *    cap, not a verdict: after `DEPENDENCY_DRIFT_MAX_DELIVERIES` turn-end
+ *    deliveries with no re-run the record is dropped from
+ *    `_pendingInlineBlockers`, and the LAST delivery carries a note saying it
+ *    will not be shown again and can still be confirmed
+ *    (`formatDeliveryCapNote`). Counting is deferred until the turn's content
+ *    is known not to be suppressed, so the count is deliveries the agent
+ *    actually received (#1950 fix round F1).
+ *
+ * 3. Dependency-drift, widget footer (#2275). The same cap number over the
+ *    widget store, which unlike the inline-blocker map backs MORE THAN ONE
+ *    surface — `lens_diagnostics mode=all` and `lens_diagnostic_mark` read
+ *    the same `allDiagnostics` list the footer draws from. So this retirement
+ *    HIDES rather than drops: the entry keeps its demotion and its place in
+ *    the error tally, gains `WidgetDiagnostic.footerRetired`, and only the
+ *    footer stops rendering it; mode=all carries the "capped, no longer shown
+ *    in the footer, re-run can still confirm" note in place of the inline
+ *    channel's last-delivery note. Its count is RENDERS, not turn ends — the
+ *    footer serves one record per pass, so `renderWidget` marks what it drew
+ *    and the turn-end step drains those marks. Dropping the record instead
+ *    would have made an unconfirmed LSP error read as CLEAN on mode=all.
+ *
+ * The rule the three share: a retirement may remove a finding from the
+ * surface that has re-served it, never from every surface at once, unless no
+ * re-run could ever confirm it (case 1).
  *
  * ── Explicit lag labels (the non-gated escape hatch) ──────────────────────
  * A store that cannot afford the freshness/disposition stack — because it
@@ -294,6 +322,7 @@ export const DELIVERY_SURFACES = {
     "agent-nudge:context-message": labeled("clients/agent-nudge.ts", "Post-edit file-touch nudge injected via `context`.", "Not a scanner finding store: no severity, no cited line, no cache — the " +
         "accumulator is drained and cleared at the moment of injection, so the " +
         "content IS the current state by construction.", "live"),
+    "test-runner-delivery:custom-entry": labeled("clients/test-runner-delivery.ts", "Post-agent test-runner failures in a non-context custom entry.", "The cache remains authoritative for pull diagnostics and the commit guard; this surface appends only after provenance validation and an idle recheck.", "live"),
     "project-diagnostics:persisted-snapshot": gated(LENS_DIAGNOSTICS_FILE, "Cross-session persisted project-diagnostics snapshot read.", ["reconcileProjectDiagnosticsSnapshot"], ["reconcileProjectDiagnosticsSnapshot("]),
     // ── #2028: the remaining agent-facing surfaces ──────────────────────────
     // Registered after #2028's root-cause review found the 🔴 STOP block
@@ -324,8 +353,16 @@ export const DELIVERY_SURFACES = {
         "command. Both inputs are read at decision time — the instance registry " +
         "and `git status` — so no stored finding is replayed and nothing can go " +
         "stale between detection and delivery.", "live"),
-    "read-guard-tool-lines:preflight-errors": labeled("clients/read-guard-tool-lines.ts", "Read-guard hashline BLOCKED / RE-READ REQUIRED preflight errors.", "Computed fresh per edit attempt and returned as that attempt's rejection — " +
-        "no cached findings are replayed, so there is no staleness window.", "live"),
+    "read-guard-tool-lines:preflight-errors": labeled("clients/read-guard-tool-lines.ts", "Read-guard hashline BLOCKED / RE-READ REQUIRED / PARTIAL APPLY / " +
+        "ALREADY APPLIED preflight errors (#2402).", "Computed fresh per edit attempt and returned as that attempt's rejection — " +
+        "no cached findings are replayed, so there is no staleness window. The " +
+        "PARTIAL APPLY and ALREADY APPLIED variants describe the same attempt's " +
+        "commit outcome; applied-edit recognition reads RuntimeCoordinator's " +
+        "session-scoped record, which resets with the session.", "live"),
+    "mutating-tool:adapter-preflight-errors": labeled("clients/mutating-tool.ts", "Shape-adapter BLOCKED preflight errors for hashline edit inputs the " +
+        "adapter recognized but could not resolve to a range (#2423).", "Computed fresh from the tool input on each attempt and returned as that " +
+        "attempt's rejection, so there is no staleness window. The adapters " +
+        "read only the call's own arguments; nothing cached is replayed.", "live"),
     "tool-call:duplicate-export-blocker": labeled("clients/runtime-tool-call.ts", "Duplicate-export STOP rejection returned inline with the failed edit.", "Synchronous preflight rejection computed per edit attempt; no stored state.", "live"),
     "agent-behavior:thrashing-notice": labeled("clients/agent-behavior-client.ts", "In-result thrashing/blind-write detection notice.", "Ephemeral notice computed at detection time inside the same tool result — " +
         "no persistence and no cache, so nothing can be stale.", "live"),

package/node_modules/pi-lens/dist/clients/format-service.js

@@ -73,7 +73,7 @@ export class FormatService {
         // Record new file state after formatting
         this.fileTime.read(absolutePath);
         for (const [index, result] of results.entries()) {
-            recordFormatter(absolutePath, formatters[index]?.name ?? "unknown", result.changed, result.success);
+            recordFormatter(absolutePath, formatters[index]?.name ?? "unknown", result.changed, result.success, result.outcome);
         }
         // Build summary
         const anyChanged = results.some((r) => r.changed);
@@ -85,6 +85,7 @@ export class FormatService {
                 success: r.success,
                 changed: r.changed,
                 error: r.error,
+                outcome: r.outcome,
             })),
             anyChanged,
             allSucceeded,
@@ -114,9 +115,13 @@ export class FormatService {
                 results.push(result);
             }
             catch (error) {
+                // A timeout or thrown error here is a real failure (#2413): the
+                // formatter ran and did not complete, distinct from an unavailable
+                // executable (which formatFile classifies before spawning).
                 results.push({
                     success: false,
                     changed: false,
+                    outcome: "failed",
                     error: error instanceof Error ? error.message : String(error),
                 });
             }