@duckmind/dm-linux-x64 0.65.5 → 0.65.7

package/extensions/dm-lens/dist/clients/dispatch/integration.js

@@ -0,0 +1,1463 @@
+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";
+import { formatSlopScoreSummary } from "../session-summary.js";
+import { clearCoverageNoticeState, clearLatencyReports, createDispatchContext, dispatchForFile, formatLatencyReport, getLatencyReports, RunnerRegistry } from "./dispatcher.js";
+import { recordDegradationOnce } from "../degradation-ledger.js";
+import { FactStore, setFactStoreEvictionReporter } from "./fact-store.js";
+import { TOOL_PLANS } from "./plan.js";
+
+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 { applyCascadeDisplayPolicy, formatCascadeNeighborDiagnostics, recordCascadeFindingPolicy } from "../cascade-format.js";
+import { logCascade } from "../cascade-logger.js";
+import { getDiagnosticTracker } from "../diagnostic-tracker.js";
+import { classifyCascadeWaitTier, isTierAwareCascadeEnabled, recordOutstandingCascadeTouch } from "../lsp/cascade-tier.js";
+import { bindingStateLabel, touchCoverageGap } from "../lsp/diagnostic-binding.js";
+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 { 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";
+import { buildOrUpdateGraph, computeImpactCascade, computeTransitiveImpact, formatImpactCascade } from "../review-graph/service.js";
+import { clearModuleGraphCache } from "../review-graph/workspace-modules.js";
+import { releaseWorkspaceTopologyIdleTimers } from "../workspace-topology.js";
+import { RUNTIME_CONFIG } from "../runtime-config.js";
+import { findCompiledClassesDir, hasJavaBuildDescriptor } from "../tool-policy.js";
+import { removeWordIndexDocumentAsync, updateWordIndexDocumentForEdit, WORD_INDEX_MAX_BYTES } from "../word-index.js";
+import { reconcileCascadeNeighborLspErrors } from "../widget-state.js";
+import { findAuxiliaryProfileForSource } from "./auxiliary-lsp.js";
+import { registerProvider, runProviders } from "./fact-runner.js";
+import { commentFactProvider } from "./facts/comment-facts.js";
+import { fileContentProvider } from "./facts/file-content.js";
+import { functionFactProvider } from "./facts/function-facts.js";
+import { importFactProvider } from "./facts/import-facts.js";
+import { tryCatchFactProvider } from "./facts/try-catch-facts.js";
+import { resolveRunnerPath, toRunnerDisplayPath } from "./runner-context.js";
+import { registerDefaultRunners } from "./runners/index.js";
+import { convertLspDiagnostics } from "./utils/lsp-diagnostics.js";
+registerProvider(fileContentProvider);
+registerProvider(tryCatchFactProvider);
+registerProvider(functionFactProvider);
+registerProvider(commentFactProvider);
+registerProvider(importFactProvider);
+import { registerRule } from "./fact-rule-runner.js";
+import { asyncNoiseRule } from "./rules/async-noise.js";
+import { asyncUnnecessaryWrapperRule } from "./rules/async-unnecessary-wrapper.js";
+import { corsWildcardRule } from "./rules/cors-wildcard.js";
+import { errorObscuringRule } from "./rules/error-obscuring.js";
+import { errorSwallowingRule } from "./rules/error-swallowing.js";
+import { highComplexityRule } from "./rules/high-complexity.js";
+import { highFanOutRule } from "./rules/high-fan-out.js";
+import { highImportCouplingRule } from "./rules/high-import-coupling.js";
+import { missingErrorPropagationRule } from "./rules/missing-error-propagation.js";
+import { commentedCredentialsRule } from "./rules/no-commented-credentials.js";
+import { passThroughWrappersRule } from "./rules/pass-through-wrappers.js";
+import { placeholderCommentsRule } from "./rules/placeholder-comments.js";
+import { unsafeBoundaryRule } from "./rules/unsafe-boundary.js";
+import { loadDmLensProjectConfig } from "../project-lens-config.js";
+registerRule(errorObscuringRule);
+registerRule(errorSwallowingRule);
+registerRule(asyncNoiseRule);
+registerRule(passThroughWrappersRule);
+registerRule(placeholderCommentsRule);
+registerRule(highComplexityRule);
+registerRule(unsafeBoundaryRule);
+registerRule(asyncUnnecessaryWrapperRule);
+registerRule(missingErrorPropagationRule);
+registerRule(highFanOutRule);
+registerRule(highImportCouplingRule);
+registerRule(corsWildcardRule);
+registerRule(commentedCredentialsRule);
+export function applyProjectLensConfig(cwd) {
+  return loadDmLensProjectConfig(cwd);
+}
+const sessionFacts = new FactStore("dispatch");
+setFactStoreEvictionReporter((subject, axis, reason) => {
+  if (axis === "pinned-over-budget") {
+    recordDegradationOnce({
+      kind: "fact-store-pinned-over-budget",
+      subject,
+      reason
+    });
+    return;
+  }
+  recordDegradationOnce({
+    kind: "fact-store-capacity-eviction",
+    subject: `${subject}:${axis}`,
+    reason
+  });
+});
+const sessionRunnerRegistry = new RunnerRegistry;
+registerDefaultRunners(sessionRunnerRegistry);
+const LSP_CAPABLE_KINDS = new Set(getLspCapableKinds());
+const FACT_RULE_IDS = new Set([
+  "error-obscuring",
+  "error-swallowing",
+  "async-noise",
+  "pass-through-wrappers",
+  "placeholder-comments",
+  "high-complexity",
+  "unsafe-boundary",
+  "async-unnecessary-wrapper",
+  "missing-error-propagation",
+  "high-fan-out",
+  "commented-out-code",
+  "duplicate-string-literal",
+  "function-in-loop",
+  "cors-wildcard",
+  "dynamic-regexp",
+  "max-switch-cases",
+  "no-commented-credentials",
+  "no-boolean-params",
+  "high-import-coupling",
+  "no-complex-conditionals"
+]);
+const sessionSlopRuleCounts = new Map;
+let sessionSlopDiagnosticCount = 0;
+let sessionWrittenLineCount = 0;
+const astGrepWarnDebounceTimers = new Map;
+const AST_GREP_WARN_DEBOUNCE_MS = 2000;
+function scheduleAstGrepWarningScan(filePath, cwd, pi, logContext) {
+  const existing = astGrepWarnDebounceTimers.get(filePath);
+  if (existing)
+    clearTimeout(existing);
+  const timer = setTimeout(() => {
+    astGrepWarnDebounceTimers.delete(filePath);
+    runAstGrepWarningScan(filePath, cwd, pi, logContext).catch(() => {});
+  }, AST_GREP_WARN_DEBOUNCE_MS);
+  astGrepWarnDebounceTimers.set(filePath, timer);
+}
+export async function runAstGrepWarningScan(filePath, cwd, pi, logContext, facts = sessionFacts) {
+  const ctx = createDispatchContext(filePath, cwd, pi, facts, false);
+  if (ctx.kind !== "jsts")
+    return;
+  facts.beginDispatchFor(ctx.filePath);
+  try {
+    const group = {
+      mode: "all",
+      runnerIds: ["ast-grep"],
+      filterKinds: ["jsts"]
+    };
+    await runProviders(ctx);
+    const result = await dispatchForFile(ctx, [group], sessionRunnerRegistry);
+    if (result.diagnostics.length === 0)
+      return;
+    const logger = getDiagnosticLogger();
+    for (const d of result.diagnostics) {
+      logger.logCaught(d, logContext, false);
+    }
+  } finally {
+    facts.endDispatchFor(ctx.filePath);
+  }
+}
+function resetSessionSlopScore() {
+  sessionSlopRuleCounts.clear();
+  sessionSlopDiagnosticCount = 0;
+  sessionWrittenLineCount = 0;
+}
+function detectFactRuleId(diagnostic) {
+  if (diagnostic.rule && FACT_RULE_IDS.has(diagnostic.rule)) {
+    return diagnostic.rule;
+  }
+  if (diagnostic.tool && FACT_RULE_IDS.has(diagnostic.tool)) {
+    return diagnostic.tool;
+  }
+  if (diagnostic.id) {
+    const prefix = diagnostic.id.split(":", 1)[0];
+    if (FACT_RULE_IDS.has(prefix)) {
+      return prefix;
+    }
+  }
+  return;
+}
+function trackSessionSlopStats(ctx, diagnostics) {
+  const lineCount = ctx.facts.getFileFact(ctx.filePath, "file.lineCount");
+  if (typeof lineCount === "number" && Number.isFinite(lineCount) && lineCount > 0) {
+    sessionWrittenLineCount += lineCount;
+  }
+  for (const diagnostic of diagnostics) {
+    const ruleId = detectFactRuleId(diagnostic);
+    if (!ruleId)
+      continue;
+    sessionSlopDiagnosticCount += 1;
+    sessionSlopRuleCounts.set(ruleId, (sessionSlopRuleCounts.get(ruleId) ?? 0) + 1);
+  }
+}
+export function getDispatchSlopScoreSummary() {
+  if (sessionSlopDiagnosticCount === 0 || sessionWrittenLineCount <= 0) {
+    return;
+  }
+  const totalKlocWritten = sessionWrittenLineCount / 1000;
+  const ruleCounts = [...sessionSlopRuleCounts.entries()].map(([ruleId, count]) => ({ ruleId, count })).sort((a, b) => b.count - a.count || a.ruleId.localeCompare(b.ruleId));
+  return {
+    totalRuleDiagnostics: sessionSlopDiagnosticCount,
+    totalKlocWritten,
+    scorePerKloc: sessionSlopDiagnosticCount / totalKlocWritten,
+    ruleCounts
+  };
+}
+export function getDispatchSlopScoreLine() {
+  const summary = getDispatchSlopScoreSummary();
+  if (!summary)
+    return "";
+  return formatSlopScoreSummary(summary);
+}
+const SPOTBUGS_SUPPORTED_KINDS = new Set(["java", "kotlin"]);
+function withSpotbugsGroup(kind, groups, ctx) {
+  if (!SPOTBUGS_SUPPORTED_KINDS.has(kind))
+    return groups;
+  if (!ctx.pi.getFlag("lens-spotbugs"))
+    return groups;
+  if (!hasJavaBuildDescriptor(ctx.cwd) || !findCompiledClassesDir(ctx.cwd)) {
+    return groups;
+  }
+  if (groups.some((group) => group.runnerIds.includes("spotbugs")))
+    return groups;
+  return [
+    ...groups,
+    {
+      mode: "all",
+      runnerIds: ["spotbugs"],
+      filterKinds: [kind],
+      semantic: "warning"
+    }
+  ];
+}
+function withPrimaryPolicyGroup(kind, groups, pi) {
+  const lspEnabled = !pi.getFlag("no-lsp");
+  const normalizedGroups = lspEnabled ? groups : groups.map((group) => {
+    const runnerIds = group.runnerIds.filter((id) => id !== "lsp");
+    if (runnerIds.length === 0)
+      return null;
+    return {
+      ...group,
+      runnerIds
+    };
+  }).filter((group) => group !== null);
+  const primary = getPrimaryDispatchGroup(kind, lspEnabled);
+  if (!primary)
+    return normalizedGroups;
+  const alreadyHasPrimary = normalizedGroups.some((group) => {
+    if (group.mode !== primary.mode)
+      return false;
+    if (group.runnerIds.length !== primary.runnerIds.length)
+      return false;
+    return group.runnerIds.every((id, index) => primary.runnerIds[index] === id);
+  });
+  if (alreadyHasPrimary)
+    return normalizedGroups;
+  return [primary, ...normalizedGroups];
+}
+export function getDispatchGroupsForKind(kind, pi) {
+  const plan = TOOL_PLANS[kind];
+  if (!plan) {
+    const lspEnabled = !pi.getFlag("no-lsp");
+    const policyGroup = getPrimaryDispatchGroup(kind, lspEnabled);
+    if (policyGroup)
+      return [policyGroup];
+    if (lspEnabled && LSP_CAPABLE_KINDS.has(kind)) {
+      return [
+        { mode: "all", runnerIds: ["lsp"], filterKinds: [kind] }
+      ];
+    }
+    return [];
+  }
+  return withPrimaryPolicyGroup(kind, plan.groups, pi);
+}
+export function resetDispatchBaselines(cwd) {
+  if (cwd)
+    applyProjectLensConfig(cwd);
+  resetAstGrepUnsupportedLanguageLog();
+  resetAstGrepNapiLoadState();
+  resetTreeSitterClientLoadState();
+  sessionFacts.clearAll();
+  resetSessionSlopScore();
+  clearCoverageNoticeState();
+  clearReviewGraphWorkspaceCache();
+  clearReverseDepsIndexCache();
+  clearModuleGraphCache();
+  recentlyCleanNeighborCache.clear();
+  primaryFilesThisTurn.clear();
+  cascadeSessionStats = {
+    runs: 0,
+    diagnosticsSurfaced: 0,
+    coldSnapshotTouches: 0
+  };
+  for (const timer of astGrepWarnDebounceTimers.values())
+    clearTimeout(timer);
+  astGrepWarnDebounceTimers.clear();
+}
+let cascadeSessionStats = {
+  runs: 0,
+  diagnosticsSurfaced: 0,
+  coldSnapshotTouches: 0
+};
+export function getCascadeSessionStats() {
+  return { ...cascadeSessionStats };
+}
+const recentlyCleanNeighborCache = new Map;
+export function getDispatchCascadeCacheStats() {
+  return {
+    recentlyCleanNeighborCacheSize: recentlyCleanNeighborCache.size,
+    sessionFactEntries: sessionFacts.getSessionFactEntryCount()
+  };
+}
+const RECENTLY_CLEAN_TTL_TURNS = 5;
+let cascadeTurnScope = 0;
+const primaryFilesThisTurn = new Set;
+function ensureCascadeTurnScope(turnSeq) {
+  if (turnSeq === cascadeTurnScope)
+    return;
+  cascadeTurnScope = turnSeq;
+  primaryFilesThisTurn.clear();
+  for (const [key, entry] of recentlyCleanNeighborCache) {
+    if (turnSeq - entry.turnSeq > RECENTLY_CLEAN_TTL_TURNS) {
+      recentlyCleanNeighborCache.delete(key);
+    }
+  }
+}
+const MAX_PER_FILE = RUNTIME_CONFIG.pipeline.cascadeMaxDiagnosticsPerFile;
+const MAX_FILES = RUNTIME_CONFIG.pipeline.cascadeMaxFiles;
+const MAX_POLICY_INPUT_PER_FILE = MAX_PER_FILE * 4;
+function cascadeReconcilableLspErrors(rawDiags, neighborPath) {
+  return convertLspDiagnostics(rawDiags.filter((d) => d.severity === 1 && !findAuxiliaryProfileForSource(d.source)).slice(0, MAX_PER_FILE), neighborPath);
+}
+function readBoundToCurrentDisk(rawDiags) {
+  return rawDiags?.binding?.boundToCurrentDisk;
+}
+function readInconclusive(rawDiags) {
+  return rawDiags?.inconclusive === true;
+}
+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 && readBoundToCurrentDisk(rawDiags) !== false;
+}
+const reverseDepsIndexCache = new Map;
+const REVERSE_DEPS_MAX_WARM_ROOTS = 8;
+const REVERSE_DEPS_IDLE_EVICT_MS_DEFAULT = 20 * 60000;
+function reverseDepsIdleEvictMs() {
+  const value = Number.parseInt(process.env.DM_LENS_REVERSE_DEPS_IDLE_EVICT_MS ?? "", 10);
+  return Number.isSafeInteger(value) && value > 0 ? value : REVERSE_DEPS_IDLE_EVICT_MS_DEFAULT;
+}
+function deleteReverseDepsEntry(key) {
+  const entry = reverseDepsIndexCache.get(key);
+  if (entry?.idleTimer !== undefined)
+    clearTimeout(entry.idleTimer);
+  if (entry)
+    entry.idleTimer = undefined;
+  reverseDepsIndexCache.delete(key);
+}
+function touchReverseDepsEntry(key, entry, armIdleTimer = true) {
+  entry.lastUsedAt = Date.now();
+  if (entry.idleTimer !== undefined)
+    clearTimeout(entry.idleTimer);
+  entry.idleTimer = undefined;
+  if (!armIdleTimer)
+    return;
+  const stamp = entry.lastUsedAt;
+  entry.idleTimer = setTimeout(() => {
+    if (reverseDepsIndexCache.get(key) !== entry || entry.lastUsedAt !== stamp)
+      return;
+    deleteReverseDepsEntry(key);
+  }, reverseDepsIdleEvictMs());
+  entry.idleTimer.unref?.();
+}
+function setReverseDepsEntry(key, entry, armIdleTimer = true) {
+  const previous = reverseDepsIndexCache.get(key);
+  if (previous?.idleTimer !== undefined) {
+    clearTimeout(previous.idleTimer);
+    previous.idleTimer = undefined;
+  }
+  const resident = { ...entry, lastUsedAt: Date.now() };
+  reverseDepsIndexCache.set(key, resident);
+  touchReverseDepsEntry(key, resident, armIdleTimer);
+  while (reverseDepsIndexCache.size > REVERSE_DEPS_MAX_WARM_ROOTS) {
+    const victim = [...reverseDepsIndexCache.entries()].sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)[0];
+    if (!victim)
+      break;
+    deleteReverseDepsEntry(victim[0]);
+  }
+}
+function reverseDepsReuseEnabled() {
+  const raw = process.env.DM_LENS_REVERSE_DEPS_REUSE;
+  return raw !== "0" && raw !== "false";
+}
+export function clearReverseDepsIndexCache() {
+  for (const key of reverseDepsIndexCache.keys())
+    deleteReverseDepsEntry(key);
+}
+export function _getReverseDepsIndexCacheKeysForTests() {
+  return [...reverseDepsIndexCache.entries()].sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt).map(([key]) => key);
+}
+export function _seedReverseDepsIndexCacheForTests(key, index, generation) {
+  setReverseDepsEntry(key, { index, savedToSnapshot: false, generation });
+}
+const CASCADE_TRANSITIVE_DEPTH = Math.max(1, Number.parseInt(process.env.DM_LENS_CASCADE_TRANSITIVE_DEPTH ?? "2", 10) || 2);
+export const CASCADE_GRAPH_KINDS = new Set([
+  "jsts",
+  "python",
+  "go",
+  "rust",
+  "ruby",
+  "cxx"
+]);
+function isIgnoredCascadeNeighbor(filePath, cwd) {
+  try {
+    return getProjectIgnoreMatcher(cwd).isIgnored(filePath, false);
+  } catch {
+    return false;
+  }
+}
+async function updateWordIndexForCascade(args) {
+  const { wordIndex, filePath, content, onUpdated, dbg } = args;
+  if (!wordIndex || !wordIndex.forward)
+    return;
+  if (content === undefined)
+    return;
+  const byteLength = Buffer.byteLength(content, "utf-8");
+  if (byteLength > WORD_INDEX_MAX_BYTES) {
+    await removeWordIndexDocumentAsync(wordIndex, filePath);
+    dbg?.(`word-index per-edit: dropped ${filePath} (over size cap)`);
+  } else {
+    await updateWordIndexDocumentForEdit(wordIndex, {
+      path: filePath,
+      content
+    });
+    dbg?.(`word-index per-edit: updated ${filePath}`);
+  }
+  onUpdated?.(wordIndex);
+}
+export async function computeCascadeForFile(filePath, cwd, options = {}) {
+  const reverseDepsTimersToRelease = new Set;
+  const reverseDepsEntriesAtStart = new Set(reverseDepsIndexCache.values());
+  const cascadeStart = Date.now();
+  try {
+    const { hasBlockers = false, dbg, turnSeq = 0, writeSeq, projectRoot, seqState, turnEndCascadeSettleStart, fileContent, wordIndex, onWordIndexUpdated } = options;
+    ensureCascadeTurnScope(turnSeq);
+    if (hasBlockers) {
+      logCascade({
+        phase: "cascade_skip",
+        filePath,
+        reason: "primary_has_blockers"
+      });
+      return {
+        filePath,
+        result: undefined,
+        neighborCount: 0,
+        diagnosticCount: 0,
+        skipReason: "blockers"
+      };
+    }
+    const fileKind = detectFileKind(filePath);
+    if (!fileKind) {
+      logCascade({ phase: "cascade_skip", filePath, reason: "non_code_file" });
+      return {
+        filePath,
+        result: undefined,
+        neighborCount: 0,
+        diagnosticCount: 0,
+        skipReason: "non_code"
+      };
+    }
+    const normalizedFile = resolveRunnerPath(cwd, filePath);
+    const normalizedFileKey = normalizeMapKey(normalizedFile);
+    primaryFilesThisTurn.add(normalizedFileKey);
+    await updateWordIndexForCascade({
+      wordIndex,
+      filePath: nodePath.resolve(filePath),
+      content: fileContent,
+      onUpdated: onWordIndexUpdated,
+      dbg
+    });
+    let impact = {
+      filePath: normalizedFile,
+      changedSymbols: [],
+      directImporters: [],
+      directCallers: [],
+      neighborFiles: [],
+      riskFlags: []
+    };
+    let sortedNeighbors = [];
+    let importerSet = new Set;
+    let callerSet = new Set;
+    let referenceCount = 0;
+    let cascadeCandidateCount = 0;
+    let cascadeEligibleCount = 0;
+    let cascadeFilterDroppedCount = 0;
+    let cascadeBudgetTruncated = 0;
+    let transitiveTruncated = false;
+    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);
+      const graphMs = Date.now() - graphStart;
+      const graphBuildInfo = getGraphBuildInfoForGraph(graph);
+      const graphBuildInfoTrustworthy = graphBuildInfoIsTrustworthy(graph);
+      const workspaceKey = normalizeMapKey(cwd);
+      const cachedReverseDeps = reverseDepsIndexCache.get(workspaceKey);
+      if (cachedReverseDeps) {
+        touchReverseDepsEntry(workspaceKey, cachedReverseDeps, false);
+        reverseDepsTimersToRelease.add(workspaceKey);
+      }
+      const importDelta = getGraphImportChanges(graph);
+      const deltaContiguous = importDelta !== undefined && importDelta.fromGeneration !== undefined && cachedReverseDeps !== undefined && cachedReverseDeps.generation === importDelta.fromGeneration;
+      const importChanges = deltaContiguous ? importDelta.changes : undefined;
+      const importsChanged = importChanges?.some((change) => change.existedBefore !== change.existsAfter || change.priorTargets.length !== change.newTargets.length || change.priorTargets.some((target, index) => target !== change.newTargets[index]));
+      const canReuse = reverseDepsReuseEnabled() && cachedReverseDeps !== undefined && (graph.buildGeneration !== undefined && cachedReverseDeps.generation === graph.buildGeneration || importChanges !== undefined && !importsChanged);
+      let reverseDepsIndex;
+      let reverseDepsSaved;
+      if (canReuse && cachedReverseDeps) {
+        reverseDepsIndex = cachedReverseDeps.index;
+        reverseDepsSaved = cachedReverseDeps.savedToSnapshot;
+        cachedReverseDeps.generation = graph.buildGeneration;
+        logCascade({
+          phase: "reverse_deps_cache",
+          filePath,
+          durationMs: Date.now() - graphStart,
+          metadata: {
+            action: "reused_unchanged",
+            savedToSnapshot: reverseDepsSaved,
+            importsFileCount: Object.keys(reverseDepsIndex.imports).length,
+            importedByFileCount: Object.keys(reverseDepsIndex.importedBy).length
+          }
+        });
+      } else if (cachedReverseDeps && importChanges && importsChanged) {
+        reverseDepsIndex = patchReverseDependencyIndex(cachedReverseDeps.index, importChanges);
+        reverseDepsSaved = writeReverseDependencyIndexToSnapshot({
+          cwd,
+          index: reverseDepsIndex,
+          dbg
+        });
+        setReverseDepsEntry(workspaceKey, {
+          index: reverseDepsIndex,
+          savedToSnapshot: reverseDepsSaved,
+          generation: graph.buildGeneration
+        }, false);
+        reverseDepsTimersToRelease.add(workspaceKey);
+        logCascade({
+          phase: "reverse_deps_cache",
+          filePath,
+          durationMs: Date.now() - graphStart,
+          metadata: {
+            action: "patched_import_changes",
+            changedFileCount: importChanges.length,
+            savedToSnapshot: reverseDepsSaved
+          }
+        });
+      } else {
+        reverseDepsIndex = buildReverseDependencyIndexFromGraph({
+          cwd,
+          graph
+        });
+        reverseDepsSaved = writeReverseDependencyIndexToSnapshot({
+          cwd,
+          index: reverseDepsIndex,
+          dbg
+        });
+        setReverseDepsEntry(workspaceKey, {
+          index: reverseDepsIndex,
+          savedToSnapshot: reverseDepsSaved,
+          generation: graph.buildGeneration
+        }, false);
+        reverseDepsTimersToRelease.add(workspaceKey);
+        logCascade({
+          phase: "reverse_deps_cache",
+          filePath,
+          durationMs: Date.now() - graphStart,
+          metadata: {
+            action: "refresh_from_review_graph",
+            savedToSnapshot: reverseDepsSaved,
+            importsFileCount: Object.keys(reverseDepsIndex.imports).length,
+            importedByFileCount: Object.keys(reverseDepsIndex.importedBy).length,
+            importEdgeCount: Object.values(reverseDepsIndex.imports).reduce((total, imports) => total + imports.length, 0)
+          }
+        });
+      }
+      const graphFileCount = new Set([...graph.nodes.values()].flatMap((n) => n.filePath ? [n.filePath] : [])).size;
+      logCascade({
+        phase: "graph_build",
+        filePath,
+        graphBuiltMs: graphMs,
+        graphReused: graphBuildInfo.reused,
+        graphNodeCount: graph.nodes.size,
+        graphFileCount,
+        graphChangedSymbolCount: (graph.changedSymbolsByFile.get(normalizedFileKey) ?? []).length,
+        metadata: {
+          graphBuildMode: graphBuildInfo.mode,
+          skipReason: graphBuildInfo.skipReason,
+          sourceFileCount: graphBuildInfo.sourceFileCount,
+          maxFileCount: graphBuildInfo.maxFileCount,
+          seqFastpathFallback: graphBuildInfo.seqFastpathFallback
+        }
+      });
+      impact = computeImpactCascade(graph, normalizedFile, cwd);
+      if ((graphBuildInfo.mode === "skipped" || graph.persistCoverage?.partial === true || !graphBuildInfoTrustworthy) && !impact.indeterminate) {
+        const coverage = graph.persistCoverage;
+        impact.indeterminate = {
+          reason: "graph_degraded",
+          detail: !graphBuildInfoTrustworthy ? "review graph coverage unknown — build state unavailable for this graph" : graphBuildInfo.mode === "skipped" ? graphBuildInfo.skipReason === "too_many_files" ? graphBuildInfo.sourceFileCountTruncated ? `review graph disabled — more than ${graphBuildInfo.maxFileCount ?? "?"} files (cap ${graphBuildInfo.maxFileCount ?? "?"})` : `review graph disabled — ${graphBuildInfo.sourceFileCount ?? "?"} files over the ${graphBuildInfo.maxFileCount ?? "?"} cap` : graphBuildInfo.skipReason === "unsafe_root" ? "review graph skipped — workspace root is at/above home dir" : `review graph unavailable (${graphBuildInfo.skipReason ?? "skipped"})` : coverage?.sourceFilesTruncated ? "review graph partial — source walk stopped at its visited-entry budget" : "review graph partial — persisted graph coverage is incomplete",
+          sourceFileCount: graphBuildInfo.sourceFileCount,
+          maxFileCount: graphBuildInfo.maxFileCount
+        };
+      }
+      const reverseDepNeighbors = getAffectedFilesFromIndex(reverseDepsIndex, normalizedFile, 1, MAX_FILES * 2);
+      logCascade({
+        phase: "reverse_deps_cache",
+        filePath,
+        metadata: {
+          action: "merge_neighbors",
+          depth: 1,
+          neighborCount: reverseDepNeighbors.length,
+          neighbors: reverseDepNeighbors.slice(0, 10)
+        }
+      });
+      if (reverseDepNeighbors.length > 0) {
+        impact.directImporters = [
+          ...new Set([...impact.directImporters, ...reverseDepNeighbors])
+        ];
+        impact.neighborFiles = [
+          ...new Set([...impact.neighborFiles, ...reverseDepNeighbors])
+        ];
+        logCascade({
+          phase: "neighbor_snapshot",
+          filePath,
+          neighborFile: "[reverse-deps-cache]",
+          diagnosticCount: reverseDepNeighbors.length,
+          autoPropagate: false,
+          metadata: { reverseDepsCache: true }
+        });
+      }
+      if (impact.changedSymbols.length > 0) {
+        const lspService = getLSPService();
+        const symbolNodeIds = graph.symbolNodesByFile.get(normalizedFileKey) ?? [];
+        const refFiles = new Set;
+        const refsStart = Date.now();
+        for (const symbolName of impact.changedSymbols.slice(0, 3)) {
+          const symbolNodeId = symbolNodeIds.find((id) => {
+            const node = graph.nodes.get(id);
+            return node?.symbolName === symbolName;
+          });
+          if (!symbolNodeId)
+            continue;
+          const node = graph.nodes.get(symbolNodeId);
+          const line = Number(node?.metadata?.line ?? 0);
+          const column = Number(node?.metadata?.column ?? 0);
+          if (line <= 0)
+            continue;
+          let refsTimer;
+          try {
+            const refs = await Promise.race([
+              lspService.references(normalizedFile, line - 1, column - 1, false),
+              new Promise((_, reject) => {
+                refsTimer = setTimeout(() => reject(new Error("timeout")), 750);
+              })
+            ]);
+            for (const ref of refs) {
+              let resolved;
+              try {
+                resolved = ref.uri.startsWith("file://") ? fileURLToPath(ref.uri) : ref.uri;
+              } catch {
+                continue;
+              }
+              if (normalizeMapKey(resolved) !== normalizedFileKey && nodeFs.existsSync(resolved)) {
+                refFiles.add(normalizeMapKey(resolved));
+              }
+            }
+          } catch {} finally {
+            if (refsTimer !== undefined)
+              clearTimeout(refsTimer);
+          }
+          if (Date.now() - refsStart > 1200)
+            break;
+        }
+        if (refFiles.size > 0) {
+          impact.neighborFiles = [
+            ...new Set([...impact.neighborFiles, ...refFiles])
+          ];
+          logCascade({
+            phase: "neighbor_snapshot",
+            filePath,
+            neighborFile: "[lsp-references]",
+            diagnosticCount: refFiles.size,
+            durationMs: Date.now() - refsStart,
+            autoPropagate: false,
+            metadata: { lspReferences: true }
+          });
+        }
+      }
+      {
+        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;
+      }
+      if (CASCADE_TRANSITIVE_DEPTH > 1) {
+        const transitive = computeTransitiveImpact(graph, normalizedFile, {
+          maxDepth: CASCADE_TRANSITIVE_DEPTH,
+          maxHits: cascadeNeighbourBudget
+        });
+        transitiveTruncated = transitive.truncated;
+        const added = [
+          ...new Set(transitive.hits.map((hit) => hit.file).filter((file) => file && normalizeMapKey(file) !== normalizedFileKey))
+        ].filter((file) => !impact.neighborFiles.includes(file));
+        if (added.length > 0) {
+          impact.neighborFiles = [...impact.neighborFiles, ...added];
+          logCascade({
+            phase: "neighbor_snapshot",
+            filePath,
+            neighborFile: "[transitive-impact]",
+            diagnosticCount: added.length,
+            autoPropagate: false,
+            metadata: {
+              transitive: true,
+              maxDepth: CASCADE_TRANSITIVE_DEPTH,
+              maxDepthReached: transitive.maxDepthReached,
+              truncated: transitive.truncated
+            }
+          });
+        }
+      }
+      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));
+      importerSet = new Set(impact.directImporters);
+      callerSet = new Set(impact.directCallers);
+      const importerOrCallerSet = new Set([
+        ...impact.directImporters,
+        ...impact.directCallers
+      ]);
+      referenceCount = impact.neighborFiles.filter((n) => !importerOrCallerSet.has(n)).length;
+      const eligibleNeighbors = [...impact.neighborFiles].filter((n) => nodeFs.existsSync(n)).filter((n) => !isExternalOrVendorFile(n, cwd)).filter((n) => !isIgnoredCascadeNeighbor(n, cwd)).filter((n) => !primaryFilesThisTurn.has(normalizeMapKey(n))).sort((a, b) => {
+        const rank = (p) => importerSet.has(p) ? 0 : callerSet.has(p) ? 1 : 2;
+        return rank(a) - rank(b);
+      });
+      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({
+        phase: "cascade_skip",
+        filePath,
+        reason: "unsupported_graph_kind",
+        metadata: { fileKind }
+      });
+      return {
+        filePath,
+        result: undefined,
+        neighborCount: 0,
+        diagnosticCount: 0,
+        skipReason: "non_code"
+      };
+    }
+    logCascade({
+      phase: "neighbors_computed",
+      filePath,
+      neighborCount: sortedNeighbors.length,
+      totalNeighborCount: impact.neighborFiles.length,
+      importerCount: impact.directImporters.length,
+      callerCount: impact.directCallers.length,
+      referenceCount: Math.max(0, referenceCount),
+      riskFlags: impact.riskFlags,
+      metadata: {
+        neighbors: sortedNeighbors.slice(0, 10),
+        candidateNeighborCount: cascadeCandidateCount,
+        eligibleNeighborCount: cascadeEligibleCount,
+        filterDroppedCount: cascadeFilterDroppedCount,
+        budgetTrimmedCount: cascadeBudgetTruncated
+      }
+    });
+    const lspService = getLSPService();
+    const allDiags = await lspService.getAllDiagnostics();
+    const neighbors = [];
+    let producedLspData = false;
+    let coldSnapshotPaths = [];
+    let fallbackBindingRejected = false;
+    const noLspCandidatePaths = new Set;
+    let collectLaterSkipped = 0;
+    let recentlyCleanHits = 0;
+    let deferredTouches = 0;
+    let coldTouches = 0;
+    let passiveSnapshotHits = 0;
+    let noLspConfigured = 0;
+    let touchFailures = 0;
+    let policyElapsedMs = 0;
+    const policyCounts = {
+      suppressed: 0,
+      auxSuppressed: 0,
+      total: 0,
+      inputTruncated: 0
+    };
+    const cascadeDisplay = (rawDiags, neighborPath, neighborContent) => {
+      const started = Date.now();
+      const errors = rawDiags.filter((d) => d.severity === 1);
+      const policyInput = errors.slice(0, MAX_POLICY_INPUT_PER_FILE);
+      const result = applyCascadeDisplayPolicy(policyInput, {
+        cwd,
+        policyRoot: projectRoot ?? cwd,
+        filePath: neighborPath,
+        displayCap: MAX_PER_FILE,
+        ...neighborContent !== undefined && { content: neighborContent }
+      });
+      policyCounts.suppressed += result.suppressed;
+      policyCounts.auxSuppressed += result.auxSuppressed;
+      policyCounts.total += result.total;
+      policyCounts.inputTruncated += errors.length - policyInput.length;
+      policyElapsedMs += Date.now() - started;
+      return result.diagnostics;
+    };
+    if (sortedNeighbors.length > 0) {
+      const snapshotPaths = sortedNeighbors.filter(shouldReadCascadeFromSnapshot);
+      const activePaths = sortedNeighbors.filter((n) => !shouldReadCascadeFromSnapshot(n));
+      coldSnapshotPaths = [];
+      for (const neighborPath of snapshotPaths) {
+        const neighborStart = Date.now();
+        const entry = allDiags.get(normalizeMapKey(neighborPath));
+        const snapshotAgeSec = entry ? Math.round((Date.now() - entry.ts) / 1000) : undefined;
+        const ttlFresh = entry != null && Date.now() - entry.ts < CASCADE_DIAGNOSTICS_TTL_MS;
+        const boundToDisk = ttlFresh ? readBoundToCurrentDisk(entry) : undefined;
+        const bindingRejected = boundToDisk === false;
+        const snapshotValid = ttlFresh && !bindingRejected;
+        if (!snapshotValid) {
+          logCascade({
+            phase: "neighbor_snapshot",
+            filePath,
+            neighborFile: neighborPath,
+            diagnosticCount: 0,
+            durationMs: Date.now() - neighborStart,
+            autoPropagate: true,
+            snapshotMissing: entry == null,
+            snapshotAgeSec,
+            coldSnapshot: true,
+            ...bindingRejected && {
+              metadata: { bindingState: bindingStateLabel(boundToDisk) }
+            }
+          });
+          coldSnapshotPaths.push(neighborPath);
+          continue;
+        }
+        const diags = cascadeDisplay(entry.diags, neighborPath);
+        producedLspData = true;
+        passiveSnapshotHits++;
+        const durationMs = Date.now() - neighborStart;
+        logCascade({
+          phase: "neighbor_snapshot",
+          filePath,
+          neighborFile: neighborPath,
+          diagnosticCount: diags.length,
+          durationMs,
+          autoPropagate: true,
+          snapshotMissing: false,
+          snapshotAgeSec
+        });
+        reconcileCascadeNeighborLspErrors(neighborPath, cascadeReconcilableLspErrors(entry.diags, neighborPath), writeSeq, entry.ts);
+        neighbors.push({
+          filePath: neighborPath,
+          reason: neighborReason(importerSet, callerSet, neighborPath),
+          diagnostics: diags,
+          lspTouched: false,
+          durationMs
+        });
+      }
+      const touchResults = await Promise.allSettled([...activePaths, ...coldSnapshotPaths].map(async (neighborPath) => {
+        const isColdSnapshot = coldSnapshotPaths.includes(neighborPath);
+        const neighborStart = Date.now();
+        const cacheKey = normalizeMapKey(neighborPath);
+        const passiveEntry = allDiags.get(cacheKey);
+        const hasFreshPassiveErrors = passiveEntry != null && Date.now() - passiveEntry.ts < CASCADE_DIAGNOSTICS_TTL_MS && passiveEntry.diags.some((d) => d.severity === 1);
+        const recentlyClean = recentlyCleanNeighborCache.get(cacheKey);
+        if (recentlyClean && turnSeq - recentlyClean.turnSeq <= RECENTLY_CLEAN_TTL_TURNS && !hasFreshPassiveErrors) {
+          producedLspData = true;
+          recentlyCleanHits++;
+          const durationMs = Date.now() - neighborStart;
+          logCascade({
+            phase: "neighbor_snapshot",
+            filePath,
+            neighborFile: neighborPath,
+            diagnosticCount: 0,
+            durationMs,
+            autoPropagate: false,
+            snapshotMissing: false,
+            metadata: {
+              recentlyClean: true,
+              cleanTurnSeq: recentlyClean.turnSeq
+            }
+          });
+          return {
+            filePath: neighborPath,
+            reason: neighborReason(importerSet, callerSet, neighborPath),
+            diagnostics: [],
+            lspTouched: false,
+            durationMs
+          };
+        }
+        const configuredServerCount = getServersForFileWithConfig(neighborPath).length;
+        if (configuredServerCount === 0) {
+          noLspConfigured++;
+          noLspCandidatePaths.add(cacheKey);
+          logCascade({
+            phase: "neighbor_fallback",
+            filePath,
+            neighborFile: neighborPath,
+            fallbackUsed: false,
+            error: "no_lsp_server_configured"
+          });
+          return;
+        }
+        const content = await nodeFs.promises.readFile(neighborPath, "utf8");
+        if (isTierAwareCascadeEnabled()) {
+          try {
+            const snapshots = await lspService.getCapabilitySnapshots?.(neighborPath) ?? [];
+            const tier = classifyCascadeWaitTier(lspService, neighborPath, snapshots);
+            if (tier === "tier3-silent" || tier === "collect-later" || tier === "diagnostics-unsupported") {
+              const spawnedForTouch = await lspService.getClientForFile(neighborPath);
+              if (spawnedForTouch) {
+                const touchedAt = Date.now();
+                await lspService.touchFile(neighborPath, content, {
+                  diagnostics: "none",
+                  collectDiagnostics: false,
+                  silent: true,
+                  source: "cascade",
+                  clientScope: "primary"
+                });
+                if (tier === "diagnostics-unsupported") {
+                  logCascade({
+                    phase: "cascade_skip",
+                    filePath,
+                    neighborFile: neighborPath,
+                    durationMs: Date.now() - neighborStart,
+                    lspServerCount: configuredServerCount,
+                    coldSnapshot: isColdSnapshot,
+                    metadata: {
+                      serverId: spawnedForTouch.client.serverId,
+                      waitTier: tier
+                    }
+                  });
+                  return;
+                }
+                recordOutstandingCascadeTouch({
+                  filePath: neighborPath,
+                  serverId: spawnedForTouch.client.serverId,
+                  touchedAt
+                });
+                const durationMs = Date.now() - neighborStart;
+                if (tier === "collect-later")
+                  collectLaterSkipped++;
+                deferredTouches++;
+                logCascade({
+                  phase: "cascade_tier3_skip",
+                  filePath,
+                  neighborFile: neighborPath,
+                  durationMs,
+                  lspServerCount: configuredServerCount,
+                  coldSnapshot: isColdSnapshot,
+                  metadata: {
+                    serverId: spawnedForTouch.client.serverId,
+                    waitTier: tier
+                  }
+                });
+                return;
+              }
+            }
+          } catch (tierErr) {
+            dbg?.(`cascade tier-aware skip attempt failed for ${neighborPath}, falling back to full wait: ${tierErr}`);
+          }
+        }
+        coldTouches++;
+        const rawDiags = await lspService.touchFile(neighborPath, content, {
+          diagnostics: "document",
+          collectDiagnostics: true,
+          maxClientWaitMs: isColdSnapshot ? 1000 : 2000,
+          silent: true,
+          source: "cascade",
+          clientScope: "primary"
+        });
+        if (!rawDiags)
+          return;
+        const confirmed = isConfirmedTouch(rawDiags);
+        const bindingRejected = readBoundToCurrentDisk(rawDiags) === false;
+        const inconclusive = readInconclusive(rawDiags);
+        const unconfirmedServerIds = touchCoverageGap(rawDiags);
+        const diags = cascadeDisplay(rawDiags.diags, neighborPath, content);
+        const durationMs = Date.now() - neighborStart;
+        if (diags.length === 0) {
+          if (confirmed) {
+            recentlyCleanNeighborCache.set(cacheKey, {
+              turnSeq,
+              checkedAt: Date.now()
+            });
+          }
+        } else {
+          recentlyCleanNeighborCache.delete(cacheKey);
+        }
+        producedLspData = true;
+        logCascade({
+          phase: "neighbor_touch",
+          filePath,
+          neighborFile: neighborPath,
+          diagnosticCount: diags.length,
+          durationMs,
+          lspTouched: true,
+          lspServerCount: configuredServerCount,
+          coldSnapshot: isColdSnapshot,
+          metadata: {
+            inconclusive,
+            ...inconclusive && readInconclusiveAttribution(rawDiags),
+            ...bindingRejected && {
+              bindingState: bindingStateLabel(false)
+            },
+            ...unconfirmedServerIds.length > 0 && {
+              unconfirmedServerIds: [...unconfirmedServerIds]
+            }
+          }
+        });
+        if (confirmed) {
+          reconcileCascadeNeighborLspErrors(neighborPath, cascadeReconcilableLspErrors(rawDiags.diags, neighborPath), writeSeq);
+        }
+        return {
+          filePath: neighborPath,
+          reason: neighborReason(importerSet, callerSet, neighborPath),
+          diagnostics: diags,
+          lspTouched: true,
+          ...inconclusive && { inconclusive: true },
+          ...unconfirmedServerIds.length > 0 && {
+            unconfirmedServerIds: [...unconfirmedServerIds]
+          },
+          durationMs
+        };
+      }));
+      const allTouchPaths = [...activePaths, ...coldSnapshotPaths];
+      for (let i = 0;i < touchResults.length; i++) {
+        const result = touchResults[i];
+        const neighborPath = allTouchPaths[i];
+        if (result.status === "fulfilled") {
+          if (result.value)
+            neighbors.push(result.value);
+        } else {
+          touchFailures++;
+          dbg?.(`cascade neighbor touch error for ${neighborPath}: ${result.reason}`);
+          const entry = allDiags.get(normalizeMapKey(neighborPath));
+          const ttlFresh = entry != null && Date.now() - entry.ts < CASCADE_DIAGNOSTICS_TTL_MS;
+          const boundToDisk = ttlFresh ? readBoundToCurrentDisk(entry) : undefined;
+          const bindingRejected = boundToDisk === false;
+          if (bindingRejected)
+            fallbackBindingRejected = true;
+          logCascade({
+            phase: "neighbor_fallback",
+            filePath,
+            neighborFile: neighborPath,
+            fallbackUsed: true,
+            error: String(result.reason),
+            ...bindingRejected && {
+              metadata: { bindingState: bindingStateLabel(boundToDisk) }
+            }
+          });
+          const diags = ttlFresh && !bindingRejected ? cascadeDisplay(entry.diags, neighborPath) : [];
+          neighbors.push({
+            filePath: neighborPath,
+            reason: "fallback",
+            diagnostics: diags,
+            lspTouched: false
+          });
+        }
+      }
+    }
+    if (producedLspData && noLspCandidatePaths.size > 0) {
+      const bindingRejected = appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, filePath, cascadeDisplay, noLspCandidatePaths);
+      if (bindingRejected)
+        fallbackBindingRejected = true;
+    } else if (!producedLspData) {
+      const bindingRejected = appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, filePath, cascadeDisplay);
+      if (bindingRejected)
+        fallbackBindingRejected = true;
+      if (neighbors.some((n) => n.reason === "fallback")) {
+        logCascade({
+          phase: "neighbor_fallback",
+          filePath,
+          fallbackUsed: true,
+          neighborCount: neighbors.length
+        });
+      }
+    }
+    recordCascadeFindingPolicy({
+      filePath,
+      durationMs: policyElapsedMs,
+      suppressed: policyCounts.suppressed,
+      total: policyCounts.total,
+      auxSuppressed: policyCounts.auxSuppressed,
+      inputTruncated: policyCounts.inputTruncated
+    });
+    const visibleNeighbors = applyCascadeDeltaBaselines(neighbors);
+    const formatted = formatCascadeResult(cwd, impact, visibleNeighbors, impact.neighborFiles.length, policyCounts.suppressed, policyCounts.inputTruncated);
+    if (!formatted && fallbackBindingRejected && !impact.indeterminate) {
+      impact.indeterminate = {
+        reason: "lsp_binding_rejected",
+        detail: "cascade fallback diagnostics were withheld — stale snapshot content did not match current disk (binding rejected)"
+      };
+    }
+    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,
+      neighborCount: visibleNeighbors.length,
+      diagnosticCount: visibleNeighbors.reduce((sum, n) => sum + n.diagnostics.length, 0),
+      metadata: {
+        filesWithErrors,
+        hasOutput: formatted.length > 0,
+        indeterminateReason: impact.indeterminate?.reason,
+        candidateNeighborCount: cascadeCandidateCount,
+        eligibleNeighborCount: cascadeEligibleCount,
+        filterDroppedCount: cascadeFilterDroppedCount,
+        selectedNeighborCount: sortedNeighbors.length,
+        selectedOutcomeCount,
+        selectedOutcomeGap,
+        passiveSnapshotHits,
+        noLspConfigured,
+        touchFailures,
+        collectLaterSkipped,
+        noNeighbors: visibleNeighbors.length === 0,
+        noErrors: visibleNeighbors.length > 0 && filesWithErrors === 0,
+        recentlyCleanHits,
+        deferredTouches,
+        coldTouches,
+        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
+        }))
+      }
+    });
+    const diagCount = visibleNeighbors.reduce((sum, n) => sum + n.diagnostics.length, 0);
+    cascadeSessionStats.runs += 1;
+    cascadeSessionStats.diagnosticsSurfaced += diagCount;
+    cascadeSessionStats.coldSnapshotTouches += coldSnapshotPaths.length;
+    if (!formatted) {
+      if (impact.indeterminate) {
+        return {
+          filePath,
+          result: undefined,
+          neighborCount: visibleNeighbors.length,
+          diagnosticCount: diagCount,
+          skipReason: "indeterminate",
+          indeterminate: impact.indeterminate,
+          selectedNeighborPaths: sortedNeighbors.slice()
+        };
+      }
+      const skipReason = visibleNeighbors.length === 0 ? "no_neighbors" : "clean";
+      return {
+        filePath,
+        result: undefined,
+        neighborCount: visibleNeighbors.length,
+        diagnosticCount: diagCount,
+        skipReason
+      };
+    }
+    getDiagnosticTracker().trackShown(visibleNeighbors.flatMap((n) => n.diagnostics));
+    return {
+      filePath,
+      result: { filePath, impact, neighbors: visibleNeighbors, formatted },
+      neighborCount: visibleNeighbors.length,
+      diagnosticCount: diagCount,
+      ...impact.indeterminate && { indeterminate: impact.indeterminate }
+    };
+  } finally {
+    for (const key of reverseDepsTimersToRelease) {
+      const entry = reverseDepsIndexCache.get(key);
+      if (entry?.idleTimer !== undefined)
+        clearTimeout(entry.idleTimer);
+      if (entry)
+        entry.idleTimer = undefined;
+    }
+    for (const [key, entry] of reverseDepsIndexCache) {
+      if (entry.idleTimer !== undefined)
+        clearTimeout(entry.idleTimer);
+      entry.idleTimer = undefined;
+      if (!reverseDepsTimersToRelease.has(key) && reverseDepsEntriesAtStart.has(entry)) {
+        reverseDepsTimersToRelease.add(key);
+      }
+    }
+    for (const timer of astGrepWarnDebounceTimers.values())
+      clearTimeout(timer);
+    astGrepWarnDebounceTimers.clear();
+    releaseWorkspaceTopologyIdleTimers();
+  }
+}
+function diagnosticDeltaKey(diagnostic) {
+  return [
+    diagnostic.id,
+    diagnostic.rule ?? "",
+    diagnostic.line ?? 0,
+    diagnostic.column ?? 0,
+    diagnostic.message
+  ].join(":");
+}
+function applyCascadeDeltaBaselines(neighbors) {
+  return neighbors.map((neighbor) => {
+    const baselineKey = `session.baseline.cascade.${normalizeMapKey(neighbor.filePath)}`;
+    const previous = sessionFacts.getBoundedSessionFact(baselineKey);
+    sessionFacts.setBoundedSessionFact(baselineKey, [...neighbor.diagnostics]);
+    if (!previous)
+      return neighbor;
+    const before = new Set(previous.map(diagnosticDeltaKey));
+    return {
+      ...neighbor,
+      diagnostics: neighbor.diagnostics.filter((diagnostic) => !before.has(diagnosticDeltaKey(diagnostic)))
+    };
+  });
+}
+function appendFallbackNeighbors(neighbors, allDiags, normalizedFileKey, cwd, filePath, cascadeDisplay, allowedPaths) {
+  const now = Date.now();
+  const seen = new Set(neighbors.map((n) => normalizeMapKey(n.filePath)));
+  let bindingRejected = false;
+  for (const [diagPath, entry] of allDiags) {
+    const { diags, ts } = entry;
+    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))
+      continue;
+    if (isIgnoredCascadeNeighbor(diagPath, cwd))
+      continue;
+    if (isTestRoleCollateral(diagPath))
+      continue;
+    if (!nodeFs.existsSync(diagPath))
+      continue;
+    if (now - ts > CASCADE_DIAGNOSTICS_TTL_MS)
+      continue;
+    const boundToDisk = readBoundToCurrentDisk(entry);
+    if (boundToDisk === false) {
+      bindingRejected = true;
+      logCascade({
+        phase: "neighbor_fallback",
+        filePath,
+        neighborFile: diagPath,
+        fallbackUsed: false,
+        metadata: { bindingState: bindingStateLabel(false) }
+      });
+      continue;
+    }
+    const errors = cascadeDisplay(diags, diagPath);
+    if (errors.length === 0)
+      continue;
+    neighbors.push({
+      filePath: diagPath,
+      reason: "fallback",
+      diagnostics: errors,
+      lspTouched: false
+    });
+    seen.add(diagKey);
+    if (neighbors.length >= MAX_FILES)
+      break;
+  }
+  return bindingRejected;
+}
+function shouldReadCascadeFromSnapshot(filePath) {
+  return getServersForFileWithConfig(filePath).some((server) => server.autoPropagateDiagnostics === true);
+}
+function neighborReason(importerSet, callerSet, neighborPath) {
+  if (importerSet.has(neighborPath))
+    return "imports";
+  if (callerSet.has(neighborPath))
+    return "calls";
+  return "references";
+}
+function formatCascadeResult(cwd, impact, neighbors, totalNeighbors, policySuppressed, policyInputTruncated) {
+  const diagnosticsBlock = formatCascadeNeighborDiagnostics(cwd, neighbors, {
+    noun: "neighbor",
+    includeReason: true
+  });
+  if (!diagnosticsBlock && policyInputTruncated === 0)
+    return "";
+  const impactHeader = formatImpactCascade(impact, RUNTIME_CONFIG.pipeline.cascadeMaxFiles);
+  let out = !diagnosticsBlock ? "" : impactHeader ? `${impactHeader}
+${diagnosticsBlock}` : diagnosticsBlock;
+  const truncated = totalNeighbors - neighbors.length;
+  if (truncated > 0) {
+    const truncatedNames = impact.neighborFiles.slice(neighbors.length, neighbors.length + 3).map((p) => toRunnerDisplayPath(cwd, p)).join(", ");
+    const moreLabel = truncatedNames ? `${truncated} more dependent file(s): ${truncatedNames}` : `${truncated} more dependent file(s)`;
+    out += `
+... and ${moreLabel}`;
+  }
+  if (policyInputTruncated > 0) {
+    if (out)
+      out += `
+`;
+    out += `⚠️ Cascade did not evaluate ${policyInputTruncated} finding(s) — the per-neighbor ` + `policy input is bounded at ${MAX_POLICY_INPUT_PER_FILE}; no findings does NOT mean clean here.`;
+  }
+  if (policySuppressed > 0) {
+    out += `
+suppressed by disposition: ${policySuppressed} finding(s) (marked false-positive or won't-fix).`;
+  }
+  return out;
+}
+export async function dispatchLint(filePath, cwd, pi, modifiedRanges, projectRoot) {
+  const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, true, modifiedRanges, projectRoot);
+  sessionFacts.clearFileFactsFor(ctx.filePath);
+  try {
+    const kind = ctx.kind;
+    if (!kind)
+      return "";
+    const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
+    if (groups.length === 0)
+      return "";
+    await runProviders(ctx);
+    const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry);
+    trackSessionSlopStats(ctx, result.diagnostics);
+    return result.output;
+  } finally {
+    sessionFacts.endDispatchFor(ctx.filePath);
+  }
+}
+export async function dispatchLintWithResult(filePath, cwd, pi, modifiedRanges, logContext, options) {
+  const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, options?.blockingOnly ?? true, modifiedRanges, options?.projectRoot, options?.writeIndex, options?.telemetryModel, options?.telemetryProvider);
+  sessionFacts.clearFileFactsFor(ctx.filePath);
+  try {
+    const kind = ctx.kind;
+    if (!kind) {
+      return {
+        diagnostics: [],
+        blockers: [],
+        warnings: [],
+        baselineWarningCount: 0,
+        fixed: [],
+        resolvedCount: 0,
+        output: "",
+        blockerOutput: "",
+        hasBlockers: false
+      };
+    }
+    const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
+    if (groups.length === 0) {
+      return {
+        diagnostics: [],
+        blockers: [],
+        warnings: [],
+        baselineWarningCount: 0,
+        fixed: [],
+        resolvedCount: 0,
+        output: "",
+        blockerOutput: "",
+        hasBlockers: false
+      };
+    }
+    await runProviders(ctx);
+    const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry);
+    trackSessionSlopStats(ctx, result.diagnostics);
+    if (kind === "jsts" && logContext) {
+      scheduleAstGrepWarningScan(filePath, cwd, pi, logContext);
+    }
+    return result;
+  } finally {
+    sessionFacts.endDispatchFor(ctx.filePath);
+  }
+}
+export async function dispatchLintDetailed(filePath, cwd, pi, options) {
+  const empty = {
+    diagnostics: [],
+    blockers: [],
+    warnings: [],
+    baselineWarningCount: 0,
+    fixed: [],
+    resolvedCount: 0,
+    output: "",
+    blockerOutput: "",
+    hasBlockers: false
+  };
+  const ctx = createDispatchContext(filePath, cwd, pi, sessionFacts, options?.blockingOnly ?? false, options?.modifiedRanges, options?.projectRoot);
+  sessionFacts.clearFileFactsFor(ctx.filePath);
+  try {
+    const kind = ctx.kind;
+    if (!kind)
+      return { result: empty, runners: [] };
+    const groups = withSpotbugsGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
+    if (groups.length === 0)
+      return { result: empty, runners: [] };
+    const runners = [];
+    const sink = (runnerId, result) => {
+      runners.push({ runnerId, result });
+    };
+    await runProviders(ctx);
+    const result = await dispatchForFile(ctx, groups, sessionRunnerRegistry, sink);
+    trackSessionSlopStats(ctx, result.diagnostics);
+    return { result, runners };
+  } finally {
+    sessionFacts.endDispatchFor(ctx.filePath);
+  }
+}
+export function shouldDispatch(filePath) {
+  const kind = detectFileKind(filePath);
+  return kind !== undefined;
+}
+export async function getAvailableRunners(filePath) {
+  const kind = detectFileKind(filePath);
+  if (!kind)
+    return [];
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const pathForFilter = normalizedPath.startsWith("/") ? normalizedPath : `/${normalizedPath}`;
+  const runners = sessionRunnerRegistry.getForKind(kind, pathForFilter);
+  return runners.map((r) => r.id);
+}