pi-lens 4.1.2 → 4.1.4

package/dist/clients/file-utils.js

@@ -4,11 +4,12 @@
 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 { 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 { 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();
@@ -213,19 +288,18 @@ function expandGitignorePattern(pattern) {
         return [body];
     return [body, `**/${body}`];
 }
-function matchesGitignorePattern(pattern, relativePath, isDirectory) {
+function matchesGitignorePattern(pattern, relativePath, isDirectory, matchExpanded) {
     const candidate = stripLeadingSlashes(normalizeIgnorePath(relativePath));
     if (!candidate)
         return false;
     const candidates = isDirectory ? [candidate, `${candidate}/`] : [candidate];
-    const options = { dot: true, nocase: process.platform === "win32" };
     return expandGitignorePattern(pattern).some((expanded) => {
         if (isDirectory && expanded.endsWith("/**")) {
             const prefix = expanded.slice(0, -3);
             if (candidate === prefix || candidate.startsWith(`${prefix}/`))
                 return true;
         }
-        return candidates.some((value) => minimatch(value, expanded, options));
+        return candidates.some((value) => matchExpanded(value, expanded));
     });
 }
 export function readGitignorePatterns(rootDir, layer = "gitignore") {
@@ -252,6 +326,14 @@ function ancestorDirsBetween(rootDir, targetDir) {
     return dirs;
 }
 function buildProjectIgnoreMatcher(resolvedRoot, patterns) {
+    const consumedIgnoreSources = new Map();
+    // `signature` lets a caller that already statted the file reuse that one
+    // stat (#2016's class on this seam: never re-derive a value you just
+    // computed). Callers with no signature in hand still pay their own stat.
+    const rememberIgnoreSource = (filePath, signature = fileFreshnessSignature(filePath)) => {
+        consumedIgnoreSources.set(filePath, { path: filePath, ...signature });
+    };
+    rememberIgnoreSource(path.join(resolvedRoot, ".gitignore"));
     const nestedCache = new Map();
     // #783: layer a NESTED `.pi-lens.json`'s `ignore` field the same way a
     // nested `.gitignore` is already layered — each ancestor directory between
@@ -266,7 +348,26 @@ function buildProjectIgnoreMatcher(resolvedRoot, patterns) {
     const patternsForDir = (dir) => {
         if (dir === resolvedRoot)
             return patterns;
+        const cached = nestedCache.get(dir);
+        const now = Date.now();
+        // #2071: inside the cadence window this directory's rules are frozen, so
+        // no stat runs and every verdict already memoized under `dir` stays
+        // derivable from exactly these patterns. Before this gate the freshness
+        // check ran per call while `patternMemo` did not, which is what let a
+        // fresh path and a memoized path in the same directory return opposite
+        // verdicts for the same rule. Externally edited nested sources are
+        // therefore picked up within PROJECT_IGNORE_FRESHNESS_CADENCE_MS, the
+        // same bound #2159 already accepted for the root sources.
+        // pi-authored `.gitignore` writes keep their instant path through
+        // `invalidateProjectIgnoreMatcherForPath`.
+        if (cached !== undefined &&
+            now - cached.checkedAtMs < PROJECT_IGNORE_FRESHNESS_CADENCE_MS) {
+            return cached.patterns;
+        }
         const gitignoreSig = gitignoreSignature(dir);
+        // One stat, two consumers. `rememberIgnoreSource` used to stat the same
+        // file a second time on the line below this one.
+        rememberIgnoreSource(path.join(dir, ".gitignore"), gitignoreSig);
         // #1105: gate on size too. `findPiLensConfigInDir` returns `size` alongside
         // `mtimeMs` (both from one stat), and `gitignoreSignature` reads both for
         // the nested `.gitignore`, so an mtime-preserving, length-changing edit to
@@ -274,11 +375,13 @@ function buildProjectIgnoreMatcher(resolvedRoot, patterns) {
         const pilensInfo = findPiLensConfigInDir(dir);
         const pilensMtime = pilensInfo?.mtimeMs ?? -1;
         const pilensSize = pilensInfo?.size ?? -1;
-        const cached = nestedCache.get(dir);
         if (cached?.gitignoreMtimeMs === gitignoreSig.mtimeMs &&
             cached?.gitignoreSize === gitignoreSig.size &&
             cached?.pilensMtimeMs === pilensMtime &&
             cached?.pilensSize === pilensSize) {
+            // Unchanged: re-arm the shared clock so the next window is measured
+            // from this check, not from the build that first populated the entry.
+            cached.checkedAtMs = now;
             return cached.patterns;
         }
         const nestedConfig = loadPiLensConfigInDir(dir);
@@ -287,12 +390,19 @@ function buildProjectIgnoreMatcher(resolvedRoot, patterns) {
             ...parseGitignoreContent(nestedConfig.ignore.join("\n"), "pilens"),
         ];
         nestedCache.set(dir, {
+            checkedAtMs: now,
             gitignoreMtimeMs: gitignoreSig.mtimeMs,
             gitignoreSize: gitignoreSig.size,
             pilensMtimeMs: pilensMtime,
             pilensSize: pilensSize,
             patterns: nextPatterns,
         });
+        // #2071: drift is the SINGLE trigger. The rules under `dir` just changed,
+        // so every verdict computed under the superseded rules dies in the same
+        // step that supersedes them. `cached === undefined` is a first build, not
+        // a change, and has no verdicts to drop.
+        if (cached !== undefined)
+            dropVerdictsUnder(dir);
         return nextPatterns;
     };
     // Per-matcher path → pattern-verdict memo. The matcher itself is cached by
@@ -317,6 +427,44 @@ function buildProjectIgnoreMatcher(resolvedRoot, patterns) {
     // already flagged as ignored, so it doesn't reintroduce the per-file cost
     // this memo exists to avoid for the common (not-ignored) case.
     const patternMemo = new Map();
+    /**
+     * Drop every memoized verdict at or below `subtree`, leaving `nestedCache`
+     * alone. `patternsForDir` calls this the moment it rebuilds a directory's
+     * patterns, which is why it must NOT evict the entry that rebuild just
+     * wrote. `invalidateSubtree` layers the eviction on top for the write-hook
+     * path, where the caller knows the source changed but has not re-read it.
+     */
+    function dropVerdictsUnder(subtree) {
+        const resolvedSubtree = path.resolve(subtree);
+        for (const key of patternMemo.keys()) {
+            const memoPath = key.slice(2);
+            const relative = path.relative(resolvedSubtree, memoPath);
+            if (!relative ||
+                (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+                patternMemo.delete(key);
+            }
+        }
+    }
+    const invalidateSubtree = (subtree) => {
+        dropVerdictsUnder(subtree);
+        nestedCache.delete(path.resolve(subtree));
+    };
+    // Compile expanded gitignore globs once per matcher instance. Relative-path
+    // resolution remains outside this cache, so nested ignore scopes cannot leak
+    // verdicts between sibling trees. The instance lifetime bounds this map.
+    const gitignoreGlobOptions = {
+        dot: true,
+        nocase: process.platform === "win32",
+    };
+    const compiledGlobs = new Map();
+    const matchExpanded = (value, expanded) => {
+        let compiled = compiledGlobs.get(expanded);
+        if (compiled === undefined) {
+            compiled = new Minimatch(expanded, gitignoreGlobOptions);
+            compiledGlobs.set(expanded, compiled);
+        }
+        return compiled.match(value);
+    };
     // #703 perf follow-up: `normalizeEphemeralMapKey` (cheap slash-fold +
     // Windows-lowercase, zero fs I/O), NOT `normalizeMapKey` (realpath-backed).
     // This runs on every `isIgnored` call that reaches this branch — walks
@@ -343,6 +491,13 @@ function buildProjectIgnoreMatcher(resolvedRoot, patterns) {
     return {
         rootDir: resolvedRoot,
         patterns,
+        getConsumedIgnoreSources: () => [...consumedIgnoreSources.values()],
+        refreshConsumedIgnoreSource(filePath) {
+            // The freshness sweep refreshes this baseline after invalidation.
+            if (consumedIgnoreSources.has(filePath))
+                rememberIgnoreSource(filePath);
+        },
+        invalidateSubtree,
         ensureTrackedIndex() {
             return collectTrackedFiles(resolvedRoot).then(() => undefined);
         },
@@ -370,7 +525,7 @@ function buildProjectIgnoreMatcher(resolvedRoot, patterns) {
                         const relative = path.relative(dir, resolved);
                         const normalized = normalizeIgnorePath(relative);
                         for (const pattern of dirPatterns) {
-                            if (!matchesGitignorePattern(pattern, normalized, isDirectory))
+                            if (!matchesGitignorePattern(pattern, normalized, isDirectory, matchExpanded))
                                 continue;
                             ignored = !pattern.negated;
                             layer = pattern.layer;
@@ -413,6 +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.
+ * 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);
@@ -428,6 +594,12 @@ function globalConfigSignature() {
 function gitignoreSignature(rootDir) {
     return fileFreshnessSignature(path.join(rootDir, ".gitignore"));
 }
+function hasIgnoreSourceDrift(sources) {
+    return sources.some((source) => {
+        const current = fileFreshnessSignature(source.path);
+        return current.mtimeMs !== source.mtimeMs || current.size !== source.size;
+    });
+}
 /**
  * The project config file found by the same upward walk as the loader. Cache
  * invalidation must track the actual file found, not only a file directly under
@@ -446,6 +618,44 @@ export function getProjectIgnoreMatcher(rootDir) {
     const lensConfig = lensConfigInfo(resolvedRoot);
     const globalSig = globalConfigSignature();
     const cached = projectIgnoreMatcherCache.get(resolvedRoot);
+    // A path can be discovered during the previous matcher lookup. Publish only
+    // previously unseen sources so a walk cannot replace a pre-edit baseline.
+    //
+    // This runs BEFORE the sweep below, and the order is load-bearing. A nested
+    // source can only be published on a call AFTER the one that consumed it.
+    // With the publish second, the sweep never saw a source during the window in
+    // which it was discovered, yet still reset `lastIgnoreFreshnessCheckMs`, so
+    // the first sweep that could see it ran a FULL cadence later. Pickup was up
+    // to 2x cadence, not 1x: measured stale at 2 s and 3 s, fresh at 4 s. The
+    // baseline is protected by the `known` set, not by the ordering, so moving
+    // the publish earlier cannot let a walk overwrite a pre-edit baseline.
+    if (cached) {
+        const known = new Set(cached.ignoreSources.map((source) => source.path));
+        for (const source of cached.matcher.getConsumedIgnoreSources()) {
+            if (!known.has(source.path))
+                cached.ignoreSources.push(source);
+        }
+    }
+    if (cached &&
+        Date.now() - cached.lastIgnoreFreshnessCheckMs >=
+            PROJECT_IGNORE_FRESHNESS_CADENCE_MS) {
+        cached.lastIgnoreFreshnessCheckMs = Date.now();
+        if (hasIgnoreSourceDrift(cached.ignoreSources)) {
+            for (const source of cached.ignoreSources) {
+                if (hasIgnoreSourceDrift([source])) {
+                    const sourceIndex = cached.ignoreSources.findIndex((cachedSource) => cachedSource.path === source.path);
+                    invalidateProjectIgnoreMatcherForPath(source.path);
+                    cached.matcher.refreshConsumedIgnoreSource(source.path);
+                    const refreshedSource = cached.matcher
+                        .getConsumedIgnoreSources()
+                        .find((current) => current.path === source.path);
+                    if (sourceIndex !== -1 && refreshedSource !== undefined) {
+                        cached.ignoreSources.splice(sourceIndex, 1, refreshedSource);
+                    }
+                }
+            }
+        }
+    }
     if (cached?.gitignoreMtimeMs === gitignoreSig.mtimeMs &&
         cached?.gitignoreSize === gitignoreSig.size &&
         cached?.lensConfigPath === lensConfig.path &&
@@ -463,6 +673,8 @@ export function getProjectIgnoreMatcher(rootDir) {
     const projectConfig = loadPiLensProjectConfig(resolvedRoot, lensConfig.info);
     const matcher = createProjectIgnoreMatcher(resolvedRoot, projectConfig.ignore, getGlobalIgnorePatterns());
     projectIgnoreMatcherCache.set(resolvedRoot, {
+        ignoreSources: [...matcher.getConsumedIgnoreSources()],
+        lastIgnoreFreshnessCheckMs: Date.now(),
         gitignoreMtimeMs: gitignoreSig.mtimeMs,
         gitignoreSize: gitignoreSig.size,
         lensConfigPath: lensConfig.path,
@@ -474,9 +686,50 @@ export function getProjectIgnoreMatcher(rootDir) {
     });
     return matcher;
 }
+/**
+ * Invalidate the cached matcher state affected by a written `.gitignore`.
+ *
+ * Root changes discard the whole matcher because they change its base pattern
+ * set. Nested changes evict only verdicts in that directory's subtree; the
+ * matcher and compiled-glob memo remain reusable for unrelated trees.
+ */
+export function invalidateProjectIgnoreMatcherForPath(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    if (path.basename(resolvedPath).toLowerCase() !== ".gitignore")
+        return;
+    for (const [cachedRoot, cached] of projectIgnoreMatcherCache) {
+        if (!isUnderDir(resolvedPath, cachedRoot))
+            continue;
+        if (normalizeFilePath(resolvedPath) ===
+            normalizeFilePath(path.join(cachedRoot, ".gitignore"))) {
+            projectIgnoreMatcherCache.delete(cachedRoot);
+            continue;
+        }
+        cached.matcher.invalidateSubtree(path.dirname(resolvedPath));
+    }
+}
 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/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
@@ -240,6 +268,7 @@ export const DELIVERY_SURFACES = {
     // `late_auxiliary_findings` latency record rather than silenced.
     "runtime-turn:late-auxiliary-findings": gated(RUNTIME_TURN_FILE, "Turn-end late-auxiliary LSP findings (collect-later probe of aux " +
         "client caches whose grace window expired).", ["gateFindingsByPathFreshness"], ['store: "late-auxiliary-findings"']),
+    "runtime-turn:late-runner-findings": gated(RUNTIME_TURN_FILE, "Turn-end CLI runner findings collected after the post-write path.", ["gateFindingsByPathFreshness"], ['store: "late-runner-findings"'], { evidenceMin: 2 }),
     "runtime-turn:cascade-blocker": labeled(RUNTIME_TURN_FILE, "Turn-end 🧪 cascade neighbor blocker.", "Cascade results settle synchronously this turn where possible " +
         "(`settleCascadeRuns`), but an unsettled compute can carry over to a " +
         "later turn (bounded by a carry cap) — this round does not freshness-" +
@@ -293,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
@@ -319,8 +349,20 @@ export const DELIVERY_SURFACES = {
     "git-guard:commit-blocked": labeled("clients/git-guard.ts", "Git-guard commit/push 🔴 COMMIT BLOCKED verdict (--lens-guard).", "Synchronous preflight rejection returned inline with the failed git " +
         "command — no stored state is delivered, so 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"),
+    "shared-checkout-guard:worktree-mutation-blocked": labeled("clients/shared-checkout-guard.ts", "Shared-checkout 🔴 WORKING-TREE CHANGE BLOCKED verdict (--lens-checkout-guard).", "Synchronous preflight rejection returned inline with the failed git " +
+        "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 / 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/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),
                 });
             }