pi-lens 4.1.6 → 4.2.1

package/dist/clients/effective-config.js

@@ -401,7 +401,7 @@ async function fileView(absolute, resolved, homeDir, workspaceCwd, lspConfig) {
         resolvedCwd: homeRelativePath(resolveToolCwd("runner", id, absolute, {
             cwd: workspaceCwd,
             suppressTelemetry: true,
-        }), homeDir),
+        }).cwd, homeDir),
     }));
     return {
         path: homeRelativePath(absolute, homeDir),

package/dist/clients/extension-log.js

@@ -211,6 +211,48 @@ function inCaptureWindow(fn) {
 function isCaptureSeam(prop) {
     return (prop === "on" || (typeof prop === "string" && prop.startsWith("register")));
 }
+/**
+ * True for a host SCHEMA value that happens to be callable.
+ *
+ * A tool definition's `parameters` is DATA the host reads, not a pi-lens
+ * callback — but the schema builder pi-lens imports is host-provided
+ * (`clients/deps/typebox.ts`: the host resolves the bare `typebox`
+ * specifier), and on a host whose builders are ArkType-style the schema is a
+ * FUNCTION. `@oh-my-pi/pi-coding-agent` rewrites an extension's `typebox`
+ * import to its own `src/extensibility/legacy-typebox.ts`, which re-exports
+ * `@oh-my-pi/omptype`'s builders; those return a callable whose prototype
+ * carries `toJsonSchema`/`assert`. `inCaptureWindow` returns a plain rest
+ * wrapper with neither, so the host falls off its ark branch, the wire schema
+ * degrades to `undefined`, and every xd:// device renders `type Args =
+ * unknown` and rejects every call with `root: schema must be an object or
+ * boolean` (#3195).
+ *
+ * The predicate IS the host's own, copied from `@oh-my-pi/pi-ai@18.2.4`
+ * `src/utils/schema/wire.ts:21-27` (`isArkSchema`) — the same test the host's
+ * `applyToolProxy` (`@oh-my-pi/pi-coding-agent@18.2.4`
+ * `src/extensibility/tool-proxy.ts:26`) uses to leave a callable schema
+ * unbound for exactly this hazard ("`bind()` … drops the schema surface …
+ * so a bound schema later stringifies to `undefined`"). Matching it means
+ * pi-lens declines to wrap precisely the values the host reads as schemas,
+ * and still wraps everything else.
+ * `tests/clients/pi-host-callable-schema-contract.test.ts` asserts against
+ * that upstream predicate (and against a fixture measured from a real
+ * `@oh-my-pi/omptype@18.2.4` schema), not against this copy of it.
+ *
+ * Deliberately NOT an allow-list of handler keys (`execute`, `renderResult`,
+ * `handler` — the measured set today): that is `isCaptureSeam`'s #1434 S1a
+ * mistake one level down (defect shape 34, spelling enumerator). The host's
+ * own `ToolDefinition` already declares `onSession`, `renderCall` and
+ * `shellEnv`, and `registerCommand` takes `getArgumentCompletions`; the day
+ * pi-lens adopts one of those, an allow-list drops its console capture
+ * SILENTLY — the #1333 regression this seam exists to prevent — while this
+ * predicate keeps wrapping it.
+ */
+function isCallableSchema(value) {
+    return (typeof value === "function" &&
+        typeof value.toJsonSchema === "function" &&
+        typeof value.assert === "function");
+}
 /**
  * Wrap every function value found in `value`, in place. Handles the two
  * shapes a `register*`/`on` call takes today: a function passed directly
@@ -218,6 +260,11 @@ function isCaptureSeam(prop) {
  * function ONE level inside a plain options/definition object
  * (`options.handler`, `tool.execute`).
  *
+ * Only the property walk screens for a callable schema (#3195): every
+ * function pi-lens passes as a register argument DIRECTLY is a handler
+ * (`on`, `registerMessageRenderer`), measured across the whole activation,
+ * so a schema can only ever arrive as a property of a definition object.
+ *
  * Deliberately NOT recursive past that one level (#1434 perf review): a tool
  * definition's `parameters`/`schema` is a large, deeply nested TypeBox object
  * that holds no functions, but walking its full tree on every `registerTool`
@@ -249,7 +296,7 @@ function wrapFunctionsInPlace(value) {
     const obj = value;
     for (const key of Object.keys(obj)) {
         const propValue = obj[key];
-        if (typeof propValue === "function") {
+        if (typeof propValue === "function" && !isCallableSchema(propValue)) {
             assignWrapped(obj, key, propValue);
         }
     }

package/dist/clients/file-kinds.js

@@ -4,7 +4,10 @@
  * Centralized file type detection to avoid duplication across clients.
  * Maps file extensions and paths to semantic file kinds.
  */
-import { basename, extname } from "node:path";
+import { basename, extname, win32 } from "node:path";
+import * as path from "node:path";
+import { isWindowsPath } from "./path-utils.js";
+import { findNearestDirWithMarker } from "./workspace-topology.js";
 // --- Extension Maps ---
 export const KIND_EXTENSIONS = {
     clojure: [".clj", ".cljc", ".cljs", ".edn"],
@@ -40,6 +43,9 @@ export const KIND_EXTENSIONS = {
         ".cu",
         // HIP
         ".hip",
+        // CUDA/HIP header convention; clang's driver table omits `.cuh`, but
+        // projects use it for C++ headers that must remain in the cxx kind (#2986).
+        ".cuh",
         // Objective-C
         ".m",
         ".mm",
@@ -179,6 +185,22 @@ export const SPECIAL_FILENAMES = [
     })),
 ];
 // --- Detection Functions ---
+/**
+ * Helm renders YAML-looking files as Go templates before they become YAML.
+ * Require the shared chart-root marker before promoting a YAML template, so
+ * ordinary repositories can use a `templates/` directory without entering
+ * Helm dispatch. `.tpl` remains extension-classified below.
+ */
+export function isHelmYamlTemplatePath(filePath) {
+    const templatesSegment = isWindowsPath(filePath)
+        ? /[\\/]templates[\\/]/i
+        : /\/templates\//i;
+    if (!templatesSegment.test(filePath) || !/\.ya?ml$/i.test(filePath)) {
+        return false;
+    }
+    const pathApi = isWindowsPath(filePath) ? win32 : path;
+    return Boolean(findNearestDirWithMarker(pathApi.dirname(filePath), "chartYamlPath"));
+}
 /**
  * Detect the file kind from a file path.
  * Returns the semantic file kind or undefined if unknown.
@@ -187,6 +209,9 @@ export function detectFileKind(filePath) {
     if (!filePath || typeof filePath !== "string") {
         return undefined;
     }
+    if (isHelmYamlTemplatePath(filePath)) {
+        return "helm-template";
+    }
     // Check special filenames first
     const base = basename(filePath);
     for (const { pattern, kind } of SPECIAL_FILENAMES) {

package/dist/clients/file-role.js

@@ -34,6 +34,24 @@ function isTypeStub(content) {
         /^export\s+type\s+\{/.test(l));
     return typeOnlyLines.length / lines.length >= 0.75;
 }
+// Shared filename predicate (#2928). The parity test iterates the runner's
+// discovery table; additional conventions are pinned in file-role.test.ts.
+// Keep the case-preserved basename for CamelCase suffixes (contest.java is source).
+function testFileNameMatches(rawBase, base) {
+    return (base.includes(".test.") ||
+        base.includes(".spec.") ||
+        base.includes("_test.") ||
+        base.includes("_spec.") ||
+        base.startsWith("test_") ||
+        base.startsWith("spec_") ||
+        /(Test|Tests|TestCase)\.(java|kt|kts|cs|fs|php)$/.test(rawBase));
+}
+/** Filename-only classification for consumers with their own directory policy. */
+export function isTestFileName(filePath) {
+    const windowsShaped = isWindowsPath(filePath);
+    const rawBase = windowsShaped ? win32.basename(filePath) : basename(filePath);
+    return testFileNameMatches(rawBase, rawBase.toLowerCase());
+}
 /**
  * Classify the structural role of a file. Pass `content` for higher
  * accuracy (enables generated-code detection, barrel detection, etc.).
@@ -57,27 +75,9 @@ export function detectFileRole(filePath, content) {
         .replace(/\\/g, "/")
         .toLowerCase();
     // --- Test ---
-    // Suffix conventions informed by the test-runner table
-    // (SOURCE_TO_TEST_PATTERNS + RUNNERS kinds in
-    // clients/test-runner-client.ts); hand-written, not iterated from it —
-    // see #2928 for the single-classifier fold:
-    // - `_test.` infix: Go (`*_test.go`), pytest (`*_test.py`), ExUnit
-    //   (`*_test.exs`), Dart (`*_test.dart`). The underscore anchor keeps
-    //   this precise: `contest.py` and `latest.ts` do not match.
-    // - `_spec.` infix: RSpec (`*_spec.rb`).
-    // - CamelCase `*Test(s).<ext>` suffix, matched case-SENSITIVELY on the
-    //   raw basename: JUnit/Surefire (`*Test.java`, `*TestCase.java`),
-    //   Kotlin (`*Test.kt`), dotnet (`*Test.cs`/`*Tests.cs`), PHPUnit
-    //   (`*Test.php`). Case matters: Surefire's `*Test.java` does not match
-    //   `contest.java`, so neither do we.
-    if (base.includes(".test.") ||
-        base.includes(".spec.") ||
-        base.includes("_test.") ||
-        base.includes("_spec.") ||
-        base.startsWith("test_") ||
-        base.startsWith("spec_") ||
-        /(Test|Tests|TestCase)\.(java|kt|kts|cs|fs|php)$/.test(rawBase) ||
-        dir.includes("/__tests__/") ||
+    // #2928: dirname has no trailing slash; match direct __tests__ children too.
+    if (testFileNameMatches(rawBase, base) ||
+        /(^|[\\/])__tests__([\\/]|$)/.test(dir) ||
         dir.includes("/test/") ||
         dir.includes("/tests/") ||
         dir.includes("/spec/") ||

package/dist/clients/file-utils.js

@@ -2,9 +2,11 @@
  * Shared file path utilities for pi-lens
  */
 import * as fs from "node:fs";
+import { createHash } from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Minimatch } from "./deps/minimatch.js";
+import { detectFileRole } from "./file-role.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";
@@ -22,7 +24,7 @@ import { safeSpawnAsync } from "./safe-spawn.js";
  * Override: set PILENS_DATA_DIR=/some/path — each project gets its own
  * subdirectory named after a sanitized form of its absolute path, e.g.
  *   PILENS_DATA_DIR=~/.pi-lens/projects
- *   → ~/.pi-lens/projects/home-user-myapp/
+ *   → ~/.pi-lens/projects/home-user-myapp-<8-hex-hash>/
  *
  * This keeps project folders clean and avoids creating .pi-lens folders
  * inside user projects.
@@ -34,14 +36,150 @@ export function getProjectDataDir(cwd) {
         return legacyProjectDir;
     }
     const base = configuredBase || path.join(getGlobalPiLensDir(), "projects");
-    const normalized = normalizeFilePath(path.resolve(cwd));
-    const slug = normalized
+    const resolvedBase = base.trim();
+    const memoKey = `${resolvedBase}\0${path.resolve(cwd)}`;
+    const cached = settledDataDirs.get(memoKey);
+    if (cached !== undefined)
+        return cached;
+    const canonical = canonicalProjectRoot(cwd);
+    const readable = projectDataDirReadableSlug(canonical.root);
+    const hash = projectDataDirRootHash(canonical.root);
+    const slug = `${readable || "default"}-${hash}`;
+    const dir = path.join(resolvedBase, slug);
+    const settled = settleProjectDataDir(resolvedBase, readable || "default", dir, memoKey, canonical.fallback);
+    return settled;
+}
+/**
+ * The human-readable half of the project data-dir slug: the absolute root
+ * with separators folded to dashes and anything else stripped.
+ *
+ * #2874: this form ALONE is not an identity — `src/pi-lens` and
+ * `src/pi/lens` fold to the same string. It is only ever combined with
+ * {@link projectDataDirRootHash}. Never use it as a directory name alone.
+ */
+function projectDataDirReadableSlug(canonicalRoot) {
+    const normalized = normalizeFilePath(canonicalRoot);
+    return normalized
         .replace(/^[a-z]:/i, "") // strip Windows drive letter
         .replace(/\/+/g, "-") // separators → dashes
         .replace(/[^A-Za-z0-9-]/g, "") // strip anything else
         .replace(/^-+/, "") // trim leading dashes
         .replace(/-+$/, ""); // trim trailing dashes
-    return path.join(base.trim(), slug || "default");
+}
+/**
+ * The canonical root is the resolved absolute path for both slug halves.
+ * `realpathSync` is probed only to expose a fallback boundary failure; using
+ * its result would let one root spelling change identity when the boundary
+ * recovers. The hash is the first 8 hex chars of SHA-256 over that root. A
+ * collision needs the same readable slug and the same 32-bit prefix, so the
+ * practical collision population is readable-slug twin pairs. Pinned on
+ * purpose because changing it renames every directory.
+ */
+function canonicalProjectRoot(cwd) {
+    const resolved = path.resolve(cwd);
+    try {
+        // Probe the root, but keep the resolved spelling as the identity in both
+        // success and fallback cases. Resolving only on success would let a
+        // transient boundary failure choose a second data directory.
+        fs.realpathSync(resolved);
+    }
+    catch {
+        // Best-effort: the root may not exist yet.
+        return { root: resolved, fallback: true };
+    }
+    return { root: resolved, fallback: false };
+}
+function projectDataDirRootHash(canonicalRoot) {
+    return createHash("sha256").update(canonicalRoot).digest("hex").slice(0, 8);
+}
+const pendingDataDirMigrations = [];
+const settledDataDirs = new Map();
+export function resetProjectDataDirSessionState() {
+    pendingDataDirMigrations.splice(0);
+}
+/**
+ * One-time upgrade from a pre-#2874 slug directory to its hashed name.
+ * When the old directory exists and the new one does not, the state moves
+ * with one atomic `renameSync` (same parent, so same filesystem). When both
+ * exist the new one wins and nothing moves. Either case queues one
+ * {@link ProjectDataDirMigration} for the session-start drain, which emits
+ * the `data_dir_migrated` record. Best-effort throughout: on any failure the
+ * caller gets the pre-existing directory and behavior is unchanged.
+ *
+ * No ledger import here on purpose: `probe-home-state.ts` documents that a
+ * direct edge between this module and `degradation-ledger.ts` in either
+ * direction adds `no-client-cycles` violations, so the record is emitted by
+ * the drain site in `runtime-session.ts` instead.
+ */
+function settleProjectDataDir(base, oldSlug, dir, memoKey, identityFallback) {
+    const oldDir = path.join(base, oldSlug);
+    const newExists = fs.existsSync(dir);
+    const oldExists = fs.existsSync(oldDir);
+    if (!oldExists) {
+        if (identityFallback && pendingDataDirMigrations.length < 32) {
+            pendingDataDirMigrations.push({
+                to: dir,
+                outcome: "identity-fallback",
+            });
+        }
+        // Steady state: nothing to migrate from.
+        settledDataDirs.set(memoKey, dir);
+        return dir;
+    }
+    if (!newExists) {
+        try {
+            fs.renameSync(oldDir, dir);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                if (fs.existsSync(dir)) {
+                    settledDataDirs.set(memoKey, dir);
+                    return dir;
+                }
+                if (fs.existsSync(oldDir))
+                    return oldDir;
+                return dir;
+            }
+            // Best-effort: retain the old directory and publish one bounded
+            // failure notice for this process's memo key.
+            if (pendingDataDirMigrations.length < 32) {
+                pendingDataDirMigrations.push({
+                    to: dir,
+                    outcome: "rename-failed",
+                });
+            }
+            settledDataDirs.set(memoKey, oldDir);
+            return oldDir;
+        }
+    }
+    // Either the rename just moved the state, or both directories already
+    // existed and the new one wins. Queue one migration for the drain.
+    settledDataDirs.set(memoKey, dir);
+    if (pendingDataDirMigrations.length < 32) {
+        pendingDataDirMigrations.push({
+            to: dir,
+            outcome: newExists ? "coexisting" : "renamed",
+        });
+    }
+    return dir;
+}
+/**
+ * Drain the queued {@link ProjectDataDirMigration}s, clearing the queue.
+ * Called once per session start by `handleSessionStart`; each queued outcome is
+ * therefore recorded at most once per session. Test-only callers must not rely
+ * on queue depth across drains.
+ */
+export function drainProjectDataDirMigrations() {
+    return pendingDataDirMigrations.splice(0);
+}
+/**
+ * Test-only reset for the settled-directory memo. The memo is a pure
+ * performance cache (one `existsSync` pair saved per latched directory), so
+ * clearing it changes no observable behavior — it lets a test stage an
+ * old-slug directory AFTER learning the new name, then resolve again.
+ */
+export function _resetProjectDataDirMemoForTests() {
+    settledDataDirs.clear();
 }
 /**
  * The project-data path to SHOW an agent or a human, for a file that
@@ -167,6 +305,14 @@ export const EXCLUDED_DIRS = [
     ".next",
     ".pi-lens",
     ".pi", // pi agent directory
+    // The SAME agent, rebranded: pi derives its config-dir name as
+    // `pkg.piConfig?.configDir || ".pi"` (pi-coding-agent 0.85.1,
+    // `dist/bundle/chunks/chunk-JVUZSMYM.js`), so a redistribution spells its
+    // `<configDir>/agent/sessions` history `.omp/agent/sessions` instead.
+    // #3112: a project-local one was walked entry-by-entry and spent the whole
+    // startup-scan entry budget, so a five-file project reported
+    // `too-many-entries` and never warmed its caches.
+    ".omp",
     ".ruff_cache", // Python linter cache
     ".worktrees",
     ".claude",
@@ -871,15 +1017,15 @@ export async function detectFileChangedAfterCommand(filePath, command, args, cwd
  * Check if file path is a test/fixture/mock file.
  * Used by secrets scanner, rate command, and dispatch runners
  * to skip these files (false positives on fake credentials, etc).
+ *
+ * Delegate naming/directory classification to file-role (#2928). Fixtures,
+ * mocks and test helpers remain this skip gate's separate policy.
  */
 export function isTestFile(filePath) {
+    if (detectFileRole(filePath) === "test")
+        return true;
     const normalized = filePath.replace(/\\/g, "/");
-    return (normalized.includes(".test.") ||
-        normalized.includes(".spec.") ||
-        normalized.includes("/test/") ||
-        normalized.includes("/tests/") ||
-        normalized.includes("__tests__/") ||
-        normalized.includes("test-utils") ||
+    return (normalized.includes("test-utils") ||
         normalized.startsWith("test-") ||
         normalized.includes(".fixture.") ||
         normalized.includes(".mock."));

package/dist/clients/finding-delivery-gate.js

@@ -270,25 +270,64 @@ export const DELIVERY_SURFACES = {
     // drifting edit already re-touched the file — a fresh pending pair
     // supersedes this one), with both drop arms counted in the
     // `late_auxiliary_findings` latency record rather than silenced.
+    //
+    // #3102: freshness is only half the gate. The survivors also take the shared
+    // `clients/dispatch/finding-policy.ts` stack (inline `pi-lens-ignore` →
+    // stored dispositions → `.pi-lens.json` rule policy) the per-edit dispatcher,
+    // `mode=full` and the `source=lsp` probe lane apply — without it a finding
+    // the agent marked `false-positive` re-reported on every drain. Per #3088
+    // round-2 F4, the evidence is the CALL TEXT of that filter, which exists
+    // nowhere else in this file: a bare `applyFindingPolicy` would also be
+    // satisfied by an import line or an unrelated caller.
     "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"']),
+        "client caches whose grace window expired).", ["gateFindingsByPathFreshness", "applyFindingPolicy"], ['store: "late-auxiliary-findings"', "applyFindingPolicy(gate.live, {"]),
     "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-" +
-        "gate that carry-over window.", "live", [], {
-        status: "partial",
-        partialReason: "A carried-over cascade result (run.carriedTurns > 0) is rendered " +
-            "without an age label. Follow-up: surface carriedTurns as an explicit " +
-            "label when > 0, or route through formatCacheAgeLabel using the run's " +
-            "own timestamp.",
-    }),
+        "later turn (bounded by a carry cap) — a carried-over result renders " +
+        "with an explicit `(carried N turns · scanned Xm ago)` label (#3167, " +
+        "#3168 F3), so the agent can tell it from a fresh observation.", "live", ["cascadeCarrySuffix("], { evidenceMin: 1 }),
     "runtime-turn:cascade-coverage-advisory": labeled(RUNTIME_TURN_FILE, "Turn-end cascade-coverage-gap advisories (graph/binding/budget).", "Explains what the cascade check could NOT confirm this turn — not a " +
         "finding with a cited path, an absence-of-coverage disclosure computed " +
-        "from this turn's own indeterminate-run list.", "live", [], {
-        status: "partial",
-        partialReason: "Same cascade carry-over caveat as runtime-turn:cascade-blocker.",
-    }),
+        "from this turn's own indeterminate-run list. An advisory computed from " +
+        "a carried indeterminate run is labeled `(carried N turns · <age>)` " +
+        "(#3167, #3168 F4 — dropped on mixed carried/fresh buckets). The age " +
+        "half reads `scan age unknown` on this surface today: no indeterminate-" +
+        "run producer stamps `observedAt` (only the resolved-found plumb does, " +
+        "`clients/cascade-format.ts`), and one unstamped carried run collapses " +
+        "the whole bucket's age rather than claiming the stamped runs' (#3168 " +
+        "F13). The carry COUNT is always real.", "live", ["withCarryLabel("], { evidenceMin: 3 }),
+    // #3102: the cold-neighbour cascade run is BUILT here, in the quiet-window
+    // reconcile (`onResolvedFound` in index.ts), a turn earlier than the
+    // `runtime-turn:cascade-blocker` render that finally carries it — so it is
+    // its own delivery lane, and it was the one that rendered raw LSP findings
+    // with no policy filter at all. The evidence is the CALL TEXT of the shared
+    // filter (#3088 round-2 F4): a bare `applyFindingPolicy` would also be
+    // satisfied by the import line.
+    "cascade-format:resolved-found-run": gated("clients/cascade-format.ts", "Cold-neighbour ERROR diagnostics formatted into the turn-end cascade " +
+        "run by `buildResolvedFoundCascadeRun` (quiet-window reconcile of a " +
+        "cascade touch that skipped its in-lane wait).", ["applyFindingPolicy"], ["applyFindingPolicy(retained, {"]),
+    // #3157: the IN-LANE cascade — a different delivery lane from the
+    // quiet-window run above, and the one #3102's sweep cleared WRONGLY. Its four
+    // display sites (passive cold snapshot, fresh touch, touch-error fallback,
+    // degraded fallback) assemble `CascadeNeighborResult.diagnostics` and reach
+    // the agent through `formatCascadeNeighborDiagnostics` without ever entering
+    // the dispatcher's `applyOutputFilters` pipeline: the sweep's file-level
+    // verdict ("the per-edit dispatch path, which already filters in
+    // dispatcher.ts") was true only of the per-edit RUNNER output in
+    // `runners/lsp.ts`, which is a different call site in a different file.
+    //
+    // Evidence is the CALL TEXT (#3088 round-2 F4), counted: `cascadeDisplay(` is
+    // the one seam all four sites route through, so `evidenceMin: 4` is the count
+    // of display sites in the file and dropping ANY of them back to a raw
+    // `convertLspDiagnostics` reds this suite. Identity-stubbing the callee
+    // instead is caught behaviourally — it reds twelve cases in
+    // `tests/clients/inlane-cascade-finding-policy.test.ts`, which is a stronger
+    // signal than the R2 proximity heuristic. Residual, stated: a FIFTH display
+    // site that open-codes the conversion keeps the count at 4 and is caught by
+    // review, not by this row.
+    "dispatch-integration:in-lane-cascade": gated("clients/dispatch/integration.ts", "In-lane per-edit cascade neighbour ERROR diagnostics, rendered into the " +
+        "turn-end cascade block by `computeCascadeForFile`.", ["applyCascadeDisplayPolicy"], ["cascadeDisplay("], { evidenceMin: 4 }),
     "runtime-turn:call-graph-advisory": labeled(RUNTIME_TURN_FILE, "Turn-end 📊 call-graph impact advisory.", "`runtime.callGraph` is a session-lifetime in-memory structure; this " +
         "round does not verify or gate ITS OWN freshness policy (how/when it " +
         "incorporates edits made earlier in the session).", "live", [], {
@@ -296,13 +335,15 @@ export const DELIVERY_SURFACES = {
         partialReason: "call-graph freshness/invalidation policy is out of this PR's scope — " +
             "tracked as a follow-up, not silently assumed fresh.",
     }),
-    "lens-diagnostics:mode-full": gated(LENS_DIAGNOSTICS_FILE, "`lens_diagnostics mode=full` report.", [
-        "applyDispositions",
-        "applyRulePolicy",
-        "reconcileProjectDiagnosticsSnapshot",
-    ], [
-        "applyDispositions(",
-        "applyRulePolicy(",
+    // #3088 round 2 F4: this row used to name `applyDispositions`/`applyRulePolicy`
+    // with whole-file evidence literals. Once #3088 folded mode=full's stack onto
+    // `applyFindingPolicy`, those two literals survived only in UNRELATED
+    // mode=delta helpers in the same file, so deleting the entire policy stack out
+    // of `applyInlineSuppressionsToSummaries` left this gate — and the ratchet —
+    // green while five behaviour cases redded. The evidence is now the call text
+    // of the merge's own filter, which exists nowhere else in the file.
+    "lens-diagnostics:mode-full": gated(LENS_DIAGNOSTICS_FILE, "`lens_diagnostics mode=full` report.", ["applyFindingPolicy", "reconcileProjectDiagnosticsSnapshot"], [
+        "applyFindingPolicy(summary.diagnostics, {",
         "reconcileProjectDiagnosticsSnapshot(",
     ]),
     "lens-diagnostics:mode-all": gated(LENS_DIAGNOSTICS_FILE, "`lens_diagnostics mode=all` report (widget-state read).", ["reconcileStaleWidgetFiles", "reconcileStaleWidgetDependencyBlockers"], ["reconcileStaleWidgetFiles(", "reconcileStaleWidgetDependencyBlockers("]),
@@ -342,13 +383,18 @@ export const DELIVERY_SURFACES = {
         "the shared workspace-diagnostics cache: createWorkspaceDiagnosticsCacheContext " +
         "is the tool's entry, and its lookup() applies the #671/#672 freshness stack " +
         "(own-file mtime + reverse-dependency mtimes via isEntryFresh) plus the " +
-        "#1095 content binding.", [
+        "#1095 content binding. #3088: every route out of this tool — fresh, " +
+        "cache replay, single file, directory — also passes applyProbeFindingPolicy, " +
+        "the stored-disposition / .pi-lens.json rule-policy / inline pi-lens-ignore " +
+        "stack the per-edit dispatch path and mode=full apply.", [
         "createWorkspaceDiagnosticsCacheContext",
         "isEntryFresh",
         "cacheCtx.lookup",
+        "applyProbeFindingPolicy",
     ], [
         "createWorkspaceDiagnosticsCacheContext(resolvedCwd)",
         "cacheCtx.lookup(file, scopeKey)",
+        "applyProbeFindingPolicy(",
     ]),
     "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 " +

package/dist/clients/format-service.js

@@ -15,6 +15,7 @@ import * as path from "node:path";
 import { recordFormatter } from "./widget-state.js";
 import { FileTime } from "./file-time.js";
 import { loadFormatters } from "./formatters-lazy.js";
+import { bounded } from "./deadline-utils.js";
 // --- Configuration ---
 /** Reserved for future batching; formatting currently runs one selected formatter per file. */
 const DEFAULT_FORMATTER_CONCURRENCY = 1;
@@ -69,7 +70,7 @@ export class FormatService {
             };
         }
         // Run formatters with limited concurrency
-        const results = await this.runFormattersWithConcurrency(absolutePath, formatters);
+        const results = await this.runFormattersWithConcurrency(absolutePath, formatters, DEFAULT_FORMATTER_CONCURRENCY, options.signal, options.budgetMs, options.hook);
         // Record new file state after formatting
         this.fileTime.read(absolutePath);
         for (const [index, result] of results.entries()) {
@@ -84,7 +85,7 @@ export class FormatService {
                 name: formatters[i].name,
                 success: r.success,
                 changed: r.changed,
-                error: r.error,
+                ...(r.error === undefined ? {} : { error: r.error }),
                 outcome: r.outcome,
             })),
             anyChanged,
@@ -94,25 +95,46 @@ export class FormatService {
     /**
      * Run the selected formatter with timeout protection.
      */
-    async runFormattersWithConcurrency(filePath, formatters, _concurrency = DEFAULT_FORMATTER_CONCURRENCY) {
+    async runFormattersWithConcurrency(filePath, formatters, _concurrency = DEFAULT_FORMATTER_CONCURRENCY, signal, budgetMs = 30_000, hook = "tool_result_edit") {
         const results = [];
+        const startedAt = Date.now();
         for (const formatter of formatters) {
-            // #1097: keep the timer handle so it can be cleared once the race
-            // settles. An uncleared, REF'D 30s setTimeout that outlives a fast
-            // `formatFile` win would keep a one-shot `pi --print` process alive for
-            // up to 30s after completion (same uncleared-race-timeout class as the
-            // LSP client-wait leak fixed in clients/lsp/index.ts).
-            let formatTimer;
+            const remainingMs = budgetMs - (Date.now() - startedAt);
+            if (remainingMs <= 0) {
+                results.push({
+                    success: false,
+                    changed: false,
+                    outcome: "failed",
+                    error: `Formatter aggregate budget exhausted before ${formatter.name}`,
+                });
+                continue;
+            }
+            // The shared bound owns both the aggregate timer and abort listener.
+            // This keeps one total formatter budget per file instead of re-arming a
+            // 30s timer for every formatter.
             try {
-                const timeoutMs = 30000;
-                const timeoutPromise = new Promise((_, reject) => {
-                    formatTimer = setTimeout(() => reject(new Error(`Formatter ${formatter.name} timed out after ${timeoutMs}ms`)), timeoutMs);
+                const result = await bounded(loadFormatters().then(({ formatFile }) => formatFile(filePath, formatter)), {
+                    ms: remainingMs,
+                    signal,
+                    hook,
+                    label: "formatter-aggregate",
                 });
-                const result = await Promise.race([
-                    loadFormatters().then(({ formatFile }) => formatFile(filePath, formatter)),
-                    timeoutPromise,
-                ]);
-                results.push(result);
+                if (result)
+                    results.push(result);
+                else if (signal?.aborted) {
+                    // Caller cancellation is intentional. Do not turn Escape into a
+                    // formatter failure or requeue record.
+                    break;
+                }
+                else {
+                    results.push({
+                        success: false,
+                        changed: false,
+                        outcome: "failed",
+                        error: `Formatter ${formatter.name} exceeded aggregate budget`,
+                    });
+                    break;
+                }
             }
             catch (error) {
                 // A timeout or thrown error here is a real failure (#2413): the
@@ -125,10 +147,6 @@ export class FormatService {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
-            finally {
-                if (formatTimer)
-                    clearTimeout(formatTimer);
-            }
         }
         return results;
     }