@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/dispatch/integration.js

@@ -4,6 +4,7 @@
  * Provides utilities for integrating the declarative dispatch system
  * with the existing index.ts tool_result handler.
  */
+import { CASCADE_DIAGNOSTICS_TTL_MS } from "../cascade-types.js";
 import { getDiagnosticLogger } from "../diagnostic-logger.js";
 import { detectFileKind } from "../file-kinds.js";
 import { getLspCapableKinds, getPrimaryDispatchGroup, } from "../language-policy.js";
@@ -16,6 +17,7 @@ export { clearLatencyReports, formatLatencyReport, getLatencyReports };
 import * as nodeFs from "node:fs";
 import * as nodePath from "node:path";
 import { fileURLToPath } from "node:url";
+import { CASCADE_NEIGHBOUR_BUDGET, deriveCascadeNeighbourBudget, } from "../cascade-budget.js";
 import { formatCascadeNeighborDiagnostics } from "../cascade-format.js";
 import { logCascade } from "../cascade-logger.js";
 import { getDiagnosticTracker } from "../diagnostic-tracker.js";
@@ -25,7 +27,8 @@ import { getServersForFileWithConfig } from "../lsp/config.js";
 import { getLSPService } from "../lsp/index.js";
 import { isExternalOrVendorFile, normalizeMapKey } from "../path-utils.js";
 import { getProjectIgnoreMatcher } from "../file-utils.js";
-import { resetAstGrepUnsupportedLanguageLog } from "./runners/ast-grep-napi.js";
+import { resetAstGrepNapiLoadState, resetAstGrepUnsupportedLanguageLog, } from "./runners/ast-grep-napi.js";
+import { resetTreeSitterClientLoadState } from "../tree-sitter-shared.js";
 import { isTestRoleCollateral } from "../collateral-test-role.js";
 import { clearReviewGraphWorkspaceCache, getGraphBuildInfoForGraph, getGraphImportChanges, graphBuildInfoIsTrustworthy, } from "../review-graph/builder.js";
 import { buildReverseDependencyIndexFromGraph, getAffectedFilesFromIndex, patchReverseDependencyIndex, writeReverseDependencyIndexToSnapshot, } from "../reverse-deps.js";
@@ -298,13 +301,18 @@ export function resetDispatchBaselines(cwd) {
     if (cwd)
         applyProjectLensConfig(cwd);
     resetAstGrepUnsupportedLanguageLog();
+    // #1567: a genuine-failure verdict or a live transient cooldown on the
+    // napi load latch is session-scoped state, not process-lifetime state.
+    resetAstGrepNapiLoadState();
+    // #1592: same shape for the web-tree-sitter load latch — an evaluation-
+    // shaped rejection is session-scoped state, not process-lifetime state.
+    resetTreeSitterClientLoadState();
     sessionFacts.clearAll();
     resetSessionSlopScore();
     clearCoverageNoticeState();
     clearReviewGraphWorkspaceCache();
     clearReverseDepsIndexCache();
     clearModuleGraphCache();
-    neighborTouchCache.clear();
     recentlyCleanNeighborCache.clear();
     primaryFilesThisTurn.clear();
     cascadeDiagnosticBaselines.clear();
@@ -325,13 +333,11 @@ let cascadeSessionStats = {
 export function getCascadeSessionStats() {
     return { ...cascadeSessionStats };
 }
-const neighborTouchCache = new Map();
 const recentlyCleanNeighborCache = new Map();
-/** O(1) entry counts of this module's turn-bounded caches (#1123 item 2
- *  memory attribution) — both are `Map.size` reads, never iterated. */
+/** O(1) entry count of this module's turn-bounded cache (#1123 item 2
+ *  memory attribution) — a `Map.size` read, never iterated. */
 export function getDispatchCascadeCacheStats() {
     return {
-        neighborTouchCacheSize: neighborTouchCache.size,
         recentlyCleanNeighborCacheSize: recentlyCleanNeighborCache.size,
     };
 }
@@ -346,14 +352,12 @@ function ensureCascadeTurnScope(turnSeq) {
         return;
     cascadeTurnScope = turnSeq;
     primaryFilesThisTurn.clear();
-    neighborTouchCache.clear();
     for (const [key, entry] of recentlyCleanNeighborCache) {
         if (turnSeq - entry.turnSeq > RECENTLY_CLEAN_TTL_TURNS) {
             recentlyCleanNeighborCache.delete(key);
         }
     }
 }
-const CASCADE_TTL_MS = 240_000;
 const MAX_PER_FILE = RUNTIME_CONFIG.pipeline.cascadeMaxDiagnosticsPerFile;
 const MAX_FILES = RUNTIME_CONFIG.pipeline.cascadeMaxFiles;
 /**
@@ -411,11 +415,17 @@ function readBoundToCurrentDisk(rawDiags) {
  * a future flag cannot be silently missed at just one of the several gate sites:
  *  - `inconclusive` (#1093/#571): the notify/diagnostics wait lapsed its deadline,
  *    so a resolved `[]` is NOT a confirmed clean (the #533 false-clean trap).
- *  - a COVERAGE GAP (#1470): an auxiliary's push wait was cut off by the aux grace
- *    timer, so the merged result is missing whatever that scanner would have said.
- *    Such a touch is deliberately NOT `inconclusive` (the primary answered), which
- *    is exactly why it needs naming here: reading `!inconclusive` alone would let a
- *    hung opengrep wipe a live footer finding and seed the recently-clean cache.
+ *    #1549: this now means a PRIMARY's deadline lapsed. A slow auxiliary lands in
+ *    the coverage-gap bullet below instead of collapsing the whole touch, so this
+ *    predicate still fails closed for it while the primary's findings survive —
+ *    which is the point: the two disqualifiers were doing one job for two causes.
+ *  - a COVERAGE GAP (#1470/#1493): an auxiliary never reported — its push wait was
+ *    cut off by the aux grace timer (#1470), or it stayed silent with no stored
+ *    publication for this content (#1493) — so the merged result is missing whatever
+ *    that scanner would have said. Such a touch is deliberately NOT `inconclusive`
+ *    (the primary answered), which is exactly why it needs naming here: reading
+ *    `!inconclusive` alone would let a hung or silent opengrep wipe a live footer
+ *    finding and seed the recently-clean cache.
  *  - `binding.boundToCurrentDisk === false` (#1095): the diagnostics were computed
  *    against a DIFFERENT disk state than what is on disk now (the server's view
  *    diverged / a pre-fix buffer) — not an observation of current disk. `true` and
@@ -429,6 +439,25 @@ function readBoundToCurrentDisk(rawDiags) {
 function readInconclusive(rawDiags) {
     return rawDiags?.inconclusive === true;
 }
+/**
+ * #1549: an inconclusive `neighbor_touch` row used to carry NO attribution, so a
+ * forensic sweep could only infer the cause from duration histograms. `touchFile`
+ * now names the PRIMARY server(s) whose deadline produced the verdict and which
+ * deadline it was (`notify-write` vs `diagnostics-wait`, or `mixed`) — carry both
+ * into cascade.log so the record stands on its own. Read off the wrapper, like
+ * every other flag here (#1179).
+ */
+function readInconclusiveAttribution(rawDiags) {
+    const wrapper = rawDiags;
+    return {
+        ...(wrapper?.inconclusiveServerIds?.length && {
+            inconclusiveServerIds: [...wrapper.inconclusiveServerIds],
+        }),
+        ...(wrapper?.inconclusiveReason && {
+            inconclusiveReason: wrapper.inconclusiveReason,
+        }),
+    };
+}
 function isConfirmedTouch(rawDiags) {
     return (!readInconclusive(rawDiags) &&
         touchCoverageGap(rawDiags).length === 0 &&
@@ -439,7 +468,9 @@ const REVERSE_DEPS_MAX_WARM_ROOTS = 8;
 const REVERSE_DEPS_IDLE_EVICT_MS_DEFAULT = 20 * 60_000;
 function reverseDepsIdleEvictMs() {
     const value = Number.parseInt(process.env.PI_LENS_REVERSE_DEPS_IDLE_EVICT_MS ?? "", 10);
-    return Number.isSafeInteger(value) && value > 0 ? value : REVERSE_DEPS_IDLE_EVICT_MS_DEFAULT;
+    return Number.isSafeInteger(value) && value > 0
+        ? value
+        : REVERSE_DEPS_IDLE_EVICT_MS_DEFAULT;
 }
 function deleteReverseDepsEntry(key) {
     const entry = reverseDepsIndexCache.get(key);
@@ -500,8 +531,9 @@ export function _seedReverseDepsIndexCacheForTests(key, index, generation) {
 // one-hop set is always the floor (it sorts first, before depth-2). Both
 // env-tunable; set depth to 1 to restore the old one-hop-only behaviour.
 const CASCADE_TRANSITIVE_DEPTH = Math.max(1, Number.parseInt(process.env.PI_LENS_CASCADE_TRANSITIVE_DEPTH ?? "2", 10) || 2);
-const CASCADE_NEIGHBOUR_BUDGET = Math.max(MAX_FILES, Number.parseInt(process.env.PI_LENS_CASCADE_NEIGHBOUR_BUDGET ?? "40", 10) ||
-    40);
+// #1462: the cap itself, and the derivation that narrows it when this run has
+// already spent the settle window, live in clients/cascade-budget.ts alongside
+// `cascadeSettleWaitMs` — the two knobs only make sense read together.
 // Exported (not just module-local) so the MCP warm-analyze seam
 // (clients/mcp/analyze.ts, #536) can gate its own buildOrUpdateGraph call on
 // the SAME file-kind eligibility this cascade path uses — one source of truth
@@ -605,8 +637,12 @@ function updateWordIndexForCascade(args) {
 export async function computeCascadeForFile(filePath, cwd, options = {}) {
     const reverseDepsTimersToRelease = new Set();
     const reverseDepsEntriesAtStart = new Set(reverseDepsIndexCache.values());
+    // #1462: legacy callers use this run's age when sizing the neighbour walk.
+    // The pipeline supplies a live turn_end clock so deferred work does not charge
+    // time that elapsed before turn_end began waiting.
+    const cascadeStart = Date.now();
     try {
-        const { hasBlockers = false, dbg, turnSeq = 0, writeSeq, seqState, fileContent, wordIndex, onWordIndexUpdated, } = options;
+        const { hasBlockers = false, dbg, turnSeq = 0, writeSeq, seqState, turnEndCascadeSettleStart, fileContent, wordIndex, onWordIndexUpdated, } = options;
         ensureCascadeTurnScope(turnSeq);
         if (hasBlockers) {
             logCascade({
@@ -672,12 +708,24 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
         let importerSet = new Set();
         let callerSet = new Set();
         let referenceCount = 0;
+        let cascadeCandidateCount = 0;
+        let cascadeEligibleCount = 0;
+        let cascadeFilterDroppedCount = 0;
         // #1446 item 4: how many eligible neighbors the flat CASCADE_NEIGHBOUR_BUDGET
         // cut off, distinct from candidates dropped by the filters above it
         // (missing on disk, vendor, ignored, already-primary-this-turn) — those are
         // never actionable regardless of budget, so counting them as "truncated"
         // would overstate what a larger budget could actually recover.
         let cascadeBudgetTruncated = 0;
+        let transitiveTruncated = false;
+        // #1462: the budget actually in force for THIS run and the settle time left
+        // when it was sized. Both are overwritten inside the graph branch below,
+        // which is the only path that reaches `cascade_result` — the other branch
+        // returns a `non_code` skip before any of this is logged.
+        let cascadeNeighbourBudget = CASCADE_NEIGHBOUR_BUDGET;
+        let cascadeBudgetRemainingMs = 0;
+        let cascadeBudgetZone = "fits";
+        let cascadeDeliveryWindowMs = 0;
         if (CASCADE_GRAPH_KINDS.has(fileKind)) {
             const graphStart = Date.now();
             const graph = await buildOrUpdateGraph(cwd, [normalizedFile], sessionFacts, seqState);
@@ -959,6 +1007,29 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                     });
                 }
             }
+            // #1462: size the rest of this run against the on-time window it has NOT
+            // already spent. Derived HERE — after the graph build, the reverse-deps
+            // refresh and the LSP-reference expansion, which is where the measured
+            // overruns were bought — and used for both the transitive BFS cap and the
+            // final slice, so a rescued run expands less as well as walking less.
+            // Narrowing happens ONLY inside the rescue band (see cascade-budget.ts):
+            // a run that is merely late keeps the whole set and is delivered complete
+            // by #1443's carry-over, because a dropped neighbour is lost for good
+            // while a late one is not. A wired callback that cannot observe an active
+            // turn_end wait uses zero elapsed time rather than charging pre-turn age.
+            {
+                const settleStart = turnEndCascadeSettleStart?.();
+                const elapsedMs = turnEndCascadeSettleStart
+                    ? settleStart !== undefined && Number.isFinite(settleStart)
+                        ? Math.max(0, Date.now() - settleStart)
+                        : 0
+                    : Date.now() - cascadeStart;
+                const decision = deriveCascadeNeighbourBudget({ elapsedMs });
+                cascadeNeighbourBudget = decision.budget;
+                cascadeBudgetRemainingMs = decision.remainingMs;
+                cascadeBudgetZone = decision.zone;
+                cascadeDeliveryWindowMs = decision.deliveryWindowMs;
+            }
             // Bounded transitive expansion: add depth>1 dependents (indirect
             // importers/callers/referencers) so the blast radius isn't limited to one
             // hop. The one-hop sets above remain the floor (they sort first); these
@@ -966,8 +1037,9 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             if (CASCADE_TRANSITIVE_DEPTH > 1) {
                 const transitive = computeTransitiveImpact(graph, normalizedFile, {
                     maxDepth: CASCADE_TRANSITIVE_DEPTH,
-                    maxHits: CASCADE_NEIGHBOUR_BUDGET,
+                    maxHits: cascadeNeighbourBudget,
                 });
+                transitiveTruncated = transitive.truncated;
                 const added = [
                     ...new Set(transitive.hits
                         .map((hit) => hit.file)
@@ -1003,6 +1075,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             // touched solely for cascade diagnostics. Composes the shared `detectFileRole`
             // seam; a classifier failure RETAINS the candidate (honest — never a false
             // clean). The project ignore filter below is separate and unchanged (#297).
+            cascadeCandidateCount = impact.neighborFiles.length;
             impact.directImporters = impact.directImporters.filter((f) => !isTestRoleCollateral(f));
             impact.directCallers = impact.directCallers.filter((f) => !isTestRoleCollateral(f));
             impact.neighborFiles = impact.neighborFiles.filter((f) => !isTestRoleCollateral(f));
@@ -1029,8 +1102,42 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 const rank = (p) => importerSet.has(p) ? 0 : callerSet.has(p) ? 1 : 2;
                 return rank(a) - rank(b);
             });
-            cascadeBudgetTruncated = Math.max(0, eligibleNeighbors.length - CASCADE_NEIGHBOUR_BUDGET);
-            sortedNeighbors = eligibleNeighbors.slice(0, CASCADE_NEIGHBOUR_BUDGET);
+            cascadeEligibleCount = eligibleNeighbors.length;
+            cascadeFilterDroppedCount = Math.max(0, cascadeCandidateCount - cascadeEligibleCount);
+            cascadeBudgetTruncated = Math.max(0, eligibleNeighbors.length - cascadeNeighbourBudget);
+            sortedNeighbors = eligibleNeighbors.slice(0, cascadeNeighbourBudget);
+            if (cascadeBudgetTruncated > 0 || transitiveTruncated) {
+                const budget = {
+                    candidateCount: cascadeCandidateCount,
+                    eligibleCount: cascadeEligibleCount,
+                    selectedCount: sortedNeighbors.length,
+                    truncatedCount: cascadeBudgetTruncated,
+                    ...(transitiveTruncated && { transitiveTruncated: true }),
+                };
+                const detailParts = [
+                    ...(cascadeBudgetTruncated > 0
+                        ? [
+                            `cascade neighbor budget checked ${budget.selectedCount} of ${budget.eligibleCount} eligible dependents ` +
+                                `(${budget.truncatedCount} omitted)`,
+                        ]
+                        : []),
+                    ...(transitiveTruncated
+                        ? [
+                            "transitive expansion was capped before all eligible dependents were enumerated",
+                        ]
+                        : []),
+                ];
+                const detail = detailParts.join("; ");
+                impact.indeterminate = impact.indeterminate
+                    ? {
+                        ...impact.indeterminate,
+                        detail: impact.indeterminate.detail
+                            ? `${impact.indeterminate.detail}; ${detail}`
+                            : detail,
+                        budget,
+                    }
+                    : { reason: "budget_truncated", detail, budget };
+            }
         }
         else {
             logCascade({
@@ -1056,7 +1163,13 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             callerCount: impact.directCallers.length,
             referenceCount: Math.max(0, referenceCount),
             riskFlags: impact.riskFlags,
-            metadata: { neighbors: sortedNeighbors.slice(0, 10) },
+            metadata: {
+                neighbors: sortedNeighbors.slice(0, 10),
+                candidateNeighborCount: cascadeCandidateCount,
+                eligibleNeighborCount: cascadeEligibleCount,
+                filterDroppedCount: cascadeFilterDroppedCount,
+                budgetTrimmedCount: cascadeBudgetTruncated,
+            },
         });
         const lspService = getLSPService();
         // Hoist passive snapshot once — used for auto-propagating LSPs and fallback path.
@@ -1079,28 +1192,33 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
         // the latter must not collapse into a clean-looking result (#1104 honesty
         // rule, same doctrine as #1023's graph-degraded indeterminate marker).
         let fallbackBindingRejected = false;
+        const noLspCandidatePaths = new Set();
         // #1444: neighbours whose in-lane wait was skipped for the quiet-window
         // reconcile to answer later. Logged on `cascade_result` so a cascade that
         // deferred EVERY neighbour is distinguishable from a genuine leaf (both are
         // `neighborCount: 0` with no output otherwise).
         let collectLaterSkipped = 0;
-        // #1446 item 5: `recentlyCleanNeighborCache` and `neighborTouchCache` hits
-        // are the whole point of both caches, but neither was ever counted — the
-        // only visible signal was 267s/day of touch wall time with no way to tell
-        // whether the caches were absorbing repeat work or every touch was cold.
+        // #1446 item 5: `recentlyCleanNeighborCache` hits are the whole point of the
+        // cache, but they were never counted — the only visible signal was 267s/day
+        // of touch wall time with no way to tell whether the cache was absorbing
+        // repeat work or every touch was cold. (#1899 removed the sibling
+        // `cacheHits` counter along with the dead `neighborTouchCache`.)
         let recentlyCleanHits = 0;
-        let cacheHits = 0;
         // F1 (#1446 follow-up): `coldTouches` must be counted at the point each
         // neighbour's OUTCOME is actually known, not derived from `coldSnapshotPaths`
         // (finalized earlier, before the cache-hit checks below run against it). Using
         // the pre-outcome list let a neighbour double-count (cold-snapshot AND cache/
         // recently-clean hit) or vanish from every bucket (an `activePaths` neighbour —
-        // e.g. Python/Go — that misses both caches). These four counters partition the
-        // touched-neighbour set `[...activePaths, ...coldSnapshotPaths]` exactly once
-        // each: a neighbour with no LSP server configured is the only outcome
-        // deliberately excluded (never attempted, no bucket).
+        // e.g. Python/Go — that misses both caches). These counters partition the
+        // selected-neighbour outcomes; passive snapshots and no-server selections are
+        // tracked separately instead of silently disappearing from the denominator.
+        // `coldTouches` includes every genuine active touch attempt, while
+        // `touchFailures` is its separate bounded failure subtype.
         let deferredTouches = 0;
         let coldTouches = 0;
+        let passiveSnapshotHits = 0;
+        let noLspConfigured = 0;
+        let touchFailures = 0;
         if (sortedNeighbors.length > 0) {
             const snapshotPaths = sortedNeighbors.filter(shouldReadCascadeFromSnapshot);
             const activePaths = sortedNeighbors.filter((n) => !shouldReadCascadeFromSnapshot(n));
@@ -1115,7 +1233,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 const snapshotAgeSec = entry
                     ? Math.round((Date.now() - entry.ts) / 1000)
                     : undefined;
-                const ttlFresh = entry != null && Date.now() - entry.ts < CASCADE_TTL_MS;
+                const ttlFresh = entry != null && Date.now() - entry.ts < CASCADE_DIAGNOSTICS_TTL_MS;
                 // #1095: content binding is the INNER gate; TTL stays the outer bound.
                 //   false     → the server's diagnostics were computed against a DIFFERENT
                 //               disk state (e.g. the PRE-fix content) — don't trust or
@@ -1163,6 +1281,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 // had no remaining purpose and is simply dropped rather than migrated.
                 const diags = convertLspDiagnostics(entry.diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), neighborPath);
                 producedLspData = true;
+                passiveSnapshotHits++;
                 const durationMs = Date.now() - neighborStart;
                 logCascade({
                     phase: "neighbor_snapshot",
@@ -1184,7 +1303,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 // LSP warning on the neighbor is preserved. Keyed by the primary edit's
                 // `writeSeq` so a genuinely newer per-edit write still wins the
                 // WriteOrderingGuard. `observedAt = entry.ts` (the snapshot's own publish
-                // time, up to CASCADE_TTL_MS old) — NOT now() — so replaying an aging
+                // time, up to CASCADE_DIAGNOSTICS_TTL_MS old) — NOT now() — so replaying an aging
                 // snapshot never re-arms the mtime-staleness gate (the same #1092
                 // re-arming defect this PR fixes for cache hits).
                 //
@@ -1214,7 +1333,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 const cacheKey = normalizeMapKey(neighborPath);
                 const passiveEntry = allDiags.get(cacheKey);
                 const hasFreshPassiveErrors = passiveEntry != null &&
-                    Date.now() - passiveEntry.ts < CASCADE_TTL_MS &&
+                    Date.now() - passiveEntry.ts < CASCADE_DIAGNOSTICS_TTL_MS &&
                     passiveEntry.diags.some((d) => d.severity === 1);
                 const recentlyClean = recentlyCleanNeighborCache.get(cacheKey);
                 if (recentlyClean &&
@@ -1244,33 +1363,13 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                         durationMs,
                     };
                 }
-                // A5: skip re-touch if this neighbor was already diagnosed at the current
-                // write sequence. A new write (higher writeSeq) invalidates the cache entry.
-                const cached = writeSeq != null ? neighborTouchCache.get(cacheKey) : undefined;
-                if (cached?.turnSeq === turnSeq && cached?.writeSeq === writeSeq) {
-                    producedLspData = true;
-                    cacheHits++;
-                    const durationMs = Date.now() - neighborStart;
-                    logCascade({
-                        phase: "neighbor_snapshot",
-                        filePath,
-                        neighborFile: neighborPath,
-                        diagnosticCount: cached.diagnostics.length,
-                        durationMs,
-                        autoPropagate: false,
-                        snapshotMissing: false,
-                        metadata: { cachedWriteSeq: writeSeq },
-                    });
-                    return {
-                        filePath: neighborPath,
-                        reason: neighborReason(importerSet, callerSet, neighborPath),
-                        diagnostics: cached.diagnostics,
-                        lspTouched: false,
-                        durationMs,
-                    };
-                }
+                // #1899: the A5 same-write cache read stood here. See the removal note
+                // at the module's cache declarations — the gate could only pass inside
+                // a single write, which never runs two cascades.
                 const configuredServerCount = getServersForFileWithConfig(neighborPath).length;
                 if (configuredServerCount === 0) {
+                    noLspConfigured++;
+                    noLspCandidatePaths.add(cacheKey);
                     logCascade({
                         phase: "neighbor_fallback",
                         filePath,
@@ -1341,8 +1440,8 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                                     },
                                 });
                                 // Deliberately NOT cached as clean/diagnosed — the wait was
-                                // skipped, not resolved, so neither neighborTouchCache nor
-                                // recentlyCleanNeighborCache may treat this as a real answer
+                                // skipped, not resolved, so recentlyCleanNeighborCache must
+                                // not treat this as a real answer
                                 // (#240 doctrine). Return undefined: the degraded-fallback
                                 // path below still has a chance to surface a passive/stale
                                 // snapshot, same as any other "no fresh data this touch" case.
@@ -1367,13 +1466,27 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 // which is finalized before any of the above checks run and includes
                 // neighbours that resolve via cache/recently-clean instead.
                 coldTouches++;
+                // #1720: language-server scope only, matching the tier-aware touch
+                // above (`clientScope: "primary"`, integration.ts:1826). A neighbor's
+                // content did not change — only its import target did — so an
+                // auxiliary scanner's (ast-grep/opengrep/typos) file-local verdict for
+                // it cannot have changed; only cross-file type semantics (the
+                // language server) can. `reconcileCascadeNeighborLspErrors` already
+                // merges errors-only and preserves the neighbor's existing aux
+                // findings by construction (see its doc comment and
+                // `cascadeReconcilableLspErrors` above), so an `"all"`-scope touch
+                // paid full aux notify traffic and aux confirmation-wait latency for
+                // a re-derivation nothing downstream ever reads. `"primary"` resolves
+                // per `neighborPath` (`getClientForFile` → `getServersForFileWithConfig`),
+                // so a multi-language neighbor still gets its OWN language server,
+                // not the primary edit's.
                 const rawDiags = await lspService.touchFile(neighborPath, content, {
                     diagnostics: "document",
                     collectDiagnostics: true,
                     maxClientWaitMs: isColdSnapshot ? 1000 : 2000,
                     silent: true,
                     source: "cascade",
-                    clientScope: "all",
+                    clientScope: "primary",
                 });
                 if (!rawDiags)
                     return undefined;
@@ -1392,9 +1505,10 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 const confirmed = isConfirmedTouch(rawDiags);
                 const bindingRejected = readBoundToCurrentDisk(rawDiags) === false;
                 const inconclusive = readInconclusive(rawDiags);
-                // #1470: the third, independent reason a touch is unconfirmed — an
-                // auxiliary our grace timer cut off. Logged alongside the other two so
-                // cascade.log alone still tells the three apart.
+                // #1470/#1493: the third, independent reason a touch is unconfirmed — an
+                // auxiliary that never reported, cut off by our grace timer or silent
+                // with nothing published for this content. Logged alongside the other two
+                // so cascade.log alone still tells the three apart.
                 const unconfirmedServerIds = touchCoverageGap(rawDiags);
                 // #692: `source: "cascade"` no longer overrides `rule` (see the
                 // doc comment on the sibling call above) — dropped rather than
@@ -1405,15 +1519,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 // wrapper and are unaffected by this copy (the shape-5 fix).
                 const diags = convertLspDiagnostics(rawDiags.diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE), neighborPath);
                 const durationMs = Date.now() - neighborStart;
-                // Cache only a confirmed answer. An inconclusive or binding-rejected
-                // result must not become a confirmed cache hit on the next cascade.
-                if (writeSeq != null && confirmed) {
-                    neighborTouchCache.set(cacheKey, {
-                        turnSeq,
-                        writeSeq,
-                        diagnostics: diags,
-                    });
-                }
+                // #1899: the A5 same-write cache write stood here.
                 if (diags.length === 0) {
                     // Only a CONFIRMED clean touch may seed the recently-clean cache
                     // (#1095: a bound-false touch is unconfirmed, exactly like inconclusive).
@@ -1446,7 +1552,12 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                     // stays conditional since "bound" carries no extra signal.
                     metadata: {
                         inconclusive,
-                        ...(bindingRejected && { bindingState: bindingStateLabel(false) }),
+                        // #1549: WHICH primary and WHICH deadline, present only when the
+                        // touch actually reported itself inconclusive.
+                        ...(inconclusive && readInconclusiveAttribution(rawDiags)),
+                        ...(bindingRejected && {
+                            bindingState: bindingStateLabel(false),
+                        }),
                         ...(unconfirmedServerIds.length > 0 && {
                             unconfirmedServerIds: [...unconfirmedServerIds],
                         }),
@@ -1476,6 +1587,15 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                     diagnostics: diags,
                     lspTouched: true,
                     ...(inconclusive && { inconclusive: true }),
+                    // #1459: carry the coverage gap to the agent-facing surface. A
+                    // scanner whose breaker was open, whose resync the fan-out gate
+                    // deferred, or whom the aux grace timer cut off never looked at this
+                    // file — without this the neighbour reaches the agent as
+                    // `{ diagnostics: [] }` with no marker, which is the false-clean the
+                    // touch already refuses to claim for itself.
+                    ...(unconfirmedServerIds.length > 0 && {
+                        unconfirmedServerIds: [...unconfirmedServerIds],
+                    }),
                     durationMs,
                 };
             }));
@@ -1488,10 +1608,11 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                         neighbors.push(result.value);
                 }
                 else {
+                    touchFailures++;
                     // A3: one failed LSP doesn't kill the rest — fall back to passive snapshot
                     dbg?.(`cascade neighbor touch error for ${neighborPath}: ${result.reason}`);
                     const entry = allDiags.get(normalizeMapKey(neighborPath));
-                    const ttlFresh = entry != null && Date.now() - entry.ts < CASCADE_TTL_MS;
+                    const ttlFresh = entry != null && Date.now() - entry.ts < CASCADE_DIAGNOSTICS_TTL_MS;
                     // #1104: consult binding before trusting a TTL-fresh fallback snapshot —
                     // MATCH #1100/#1095 semantics (false → skip, "unknown" → keep the
                     // pre-#1104 TTL-only behavior, true → use). Without this, a failed
@@ -1538,8 +1659,15 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             }
         }
         // CR-3/A2: degraded fallback when no neighbor produced trustworthy LSP data —
-        // not merely when the graph returned zero neighbors.
-        if (!producedLspData) {
+        // not merely when the graph returned zero neighbors. In a mixed run, only
+        // candidates that had no configured LSP may use passive fallback; broadening
+        // to unrelated cache entries would make the partial active result misleading.
+        if (producedLspData && noLspCandidatePaths.size > 0) {
+            const bindingRejected = appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, filePath, noLspCandidatePaths);
+            if (bindingRejected)
+                fallbackBindingRejected = true;
+        }
+        else if (!producedLspData) {
             const bindingRejected = appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, filePath);
             if (bindingRejected)
                 fallbackBindingRejected = true;
@@ -1570,6 +1698,12 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             };
         }
         const filesWithErrors = visibleNeighbors.filter((n) => n.diagnostics.length > 0).length;
+        const selectedOutcomeCount = passiveSnapshotHits +
+            recentlyCleanHits +
+            deferredTouches +
+            coldTouches +
+            noLspConfigured;
+        const selectedOutcomeGap = Math.max(0, sortedNeighbors.length - selectedOutcomeCount);
         logCascade({
             phase: "cascade_result",
             filePath,
@@ -1578,6 +1712,16 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
             metadata: {
                 filesWithErrors,
                 hasOutput: formatted.length > 0,
+                indeterminateReason: impact.indeterminate?.reason,
+                candidateNeighborCount: cascadeCandidateCount,
+                eligibleNeighborCount: cascadeEligibleCount,
+                filterDroppedCount: cascadeFilterDroppedCount,
+                selectedNeighborCount: sortedNeighbors.length,
+                selectedOutcomeCount,
+                selectedOutcomeGap,
+                passiveSnapshotHits,
+                noLspConfigured,
+                touchFailures,
                 // #1444: >0 means "answers are still outstanding", not "nothing found".
                 collectLaterSkipped,
                 // Log when cascade ran but found nothing — distinguishes "clean" from "no signal"
@@ -1586,21 +1730,42 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                 // #1446 item 5: cache effectiveness as a number instead of an inference
                 // from `coldSnapshot`/`snapshotMissing` flags scattered across
                 // per-neighbor `neighbor_touch`/`neighbor_snapshot` rows.
-                // F1: cacheHits + recentlyCleanHits + deferredTouches + coldTouches
-                // partition `[...activePaths, ...coldSnapshotPaths]` exactly — each
-                // counter increments at the point its neighbour's outcome is actually
-                // decided, not from `coldSnapshotPaths` (a pre-outcome list finalized
-                // before the cache-hit checks run). A neighbour with no LSP server
-                // configured is the one deliberately uncounted outcome (never touched).
-                cacheHits,
+                // F1: recentlyCleanHits + deferredTouches + coldTouches
+                // retain their outcome semantics. Passive snapshots and no-server selections
+                // complete the selected-neighbor denominator; touchFailures is a bounded
+                // subtype of coldTouches, not an additional outcome.
                 recentlyCleanHits,
                 deferredTouches,
                 coldTouches,
                 // #1446 item 4: the budget in force and how many eligible candidates
                 // it cut off this run — the correctness half (a truncated run being
-                // silently discarded) is #1443; this is observability only.
-                neighborBudget: CASCADE_NEIGHBOUR_BUDGET,
+                // silently discarded) is #1443.
+                // #1462: `neighborBudget` is now the DERIVED budget (still "the one in
+                // force"); `neighborBudgetCeiling` is the flat cap, `budgetRemainingMs`
+                // the on-time window left when it was sized, and `budgetZone` the rule
+                // that decided it. Only `budgetZone: "narrowed"` shortens a walk — the
+                // other three keep the flat cap, so a row where budget < ceiling is a
+                // deliberate rescue, never a cold-start stub. `budgetDeliveryWindowMs`
+                // records how long the pipeline (turn_end settle + quiet-window drain)
+                // keeps a slow run alive, which is why the other zones can afford to
+                // stay wide.
+                //
+                // NOTE for whoever reads these rows: `budgetTruncated` INVERTS under a
+                // narrowed budget — it is `eligible - budget`, so a smaller budget
+                // mechanically raises it. Compare truncation WITHIN a zone, never
+                // across one.
+                neighborBudget: cascadeNeighbourBudget,
+                neighborBudgetCeiling: CASCADE_NEIGHBOUR_BUDGET,
+                budgetRemainingMs: cascadeBudgetRemainingMs,
+                budgetZone: cascadeBudgetZone,
+                budgetDeliveryWindowMs: cascadeDeliveryWindowMs,
                 budgetTruncated: cascadeBudgetTruncated,
+                transitiveTruncated,
+                budgetTrimmedCount: cascadeBudgetTruncated,
+                budgetDerivationDisabled: cascadeBudgetZone === "no-rescue-window",
+                budgetDerivationDisabledReason: cascadeBudgetZone === "no-rescue-window"
+                    ? "no-rescue-window"
+                    : undefined,
                 neighbors: visibleNeighbors.slice(0, 10).map((n) => ({
                     file: n.filePath.replace(/\\/g, "/").split("/").slice(-2).join("/"),
                     diagnostics: n.diagnostics.length,
@@ -1624,6 +1789,7 @@ export async function computeCascadeForFile(filePath, cwd, options = {}) {
                     diagnosticCount: diagCount,
                     skipReason: "indeterminate",
                     indeterminate: impact.indeterminate,
+                    selectedNeighborPaths: sortedNeighbors.slice(),
                 };
             }
             const skipReason = visibleNeighbors.length === 0 ? "no_neighbors" : "clean";
@@ -1701,7 +1867,7 @@ function applyCascadeDeltaBaselines(neighbors) {
  * because its content binding was rejected (#1104) — the caller folds this
  * into the run-level `fallbackBindingRejected` flag for the honesty check.
  */
-function appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, filePath) {
+function appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, filePath, allowedPaths) {
     const now = Date.now();
     const seen = new Set(neighbors.map((n) => normalizeMapKey(n.filePath)));
     let bindingRejected = false;
@@ -1710,6 +1876,8 @@ function appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, fi
         const diagKey = normalizeMapKey(diagPath);
         if (diagKey === normalizedFileKey || seen.has(diagKey))
             continue;
+        if (allowedPaths && !allowedPaths.has(diagKey))
+            continue;
         if (primaryFilesThisTurn.has(diagKey))
             continue;
         if (isExternalOrVendorFile(diagPath, cwd))
@@ -1723,7 +1891,7 @@ function appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, fi
             continue;
         if (!nodeFs.existsSync(diagPath))
             continue;
-        if (now - ts > CASCADE_TTL_MS)
+        if (now - ts > CASCADE_DIAGNOSTICS_TTL_MS)
             continue;
         // #1104: a TTL-fresh entry is not automatically trustworthy — consult
         // binding the same way the reconcile path (#1100) and the touch-error