@duckmind/dm-darwin-x64 0.66.5 → 0.66.7

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

@@ -0,0 +1,1017 @@
+import { logExtension } from "../extension-log.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { recordRunner } from "../widget-state.js";
+import { incrementDegradationCount, recordDegradationOnce } from "../degradation-ledger.js";
+import { detectFileKind } from "../file-kinds.js";
+import { detectFileRole } from "../file-role.js";
+import { classifyGeneratedOrArtifactDetailed } from "../generated-artifacts.js";
+import { isTestFile } from "../file-utils.js";
+import { getPrimaryDispatchGroup } from "../language-policy.js";
+import { resolveLanguageRootForFile } from "../language-profile.js";
+import { logLatency, phaseFinished, phaseStarted } from "../latency-logger.js";
+import { isSpawnableCommand } from "../installer/index.js";
+import { isAbsoluteFilePath, isWindowsPath, normalizeEphemeralMapKey, normalizeMapKey } from "../path-utils.js";
+import { loadDmLensProjectConfig } from "../project-lens-config.js";
+import { RUNTIME_CONFIG, getRunnerTimeoutFloorMs } from "../runtime-config.js";
+import { probeToolAsync } from "../tool-probe.js";
+import { classifyDiagnostic } from "./diagnostic-taxonomy.js";
+import { classifyProbeFailure, logAvailabilityDecision, startHostStallSampler, transientRetryDelayMs } from "./runners/utils/availability-policy.js";
+import { recordAvailabilityProbeOverrun, getDispatchAvailabilityGeneration } from "./runners/utils/runner-helpers.js";
+import { createAvailabilityProbeFlight } from "../availability-probe-flight.js";
+import { applyDispositions } from "../diagnostic-dispositions.js";
+import { applyInlineSuppressions } from "./inline-suppressions.js";
+import { getToolPlan } from "./plan.js";
+import { resolveRunnerPath } from "./runner-context.js";
+import { classifyObservedRunner, COLLECT_LATER_THRESHOLD_MS, observeRunnerLatency } from "./collect-later-tier.js";
+import { deferRunnerFindings } from "./pending-runner-findings.js";
+import { ADOPTED_ROOT_RUNNER_ALLOWLIST, filterGroupsForAdoptedRoot } from "./adopted-root-runners.js";
+import { applyRulePolicy, resolvedRulePolicyMap, rulePolicyMapFromConfig } from "./rule-policy.js";
+import { getToolProfile } from "./tool-profile.js";
+import { hasUsableResult, isRunnerClaimSource, isRunnerSkipReason } from "./types.js";
+const dispatcherProbeFlights = createAvailabilityProbeFlight({ generation: () => getDispatchAvailabilityGeneration() });
+import { DELTA_UNUSED_PROMOTION_NOTE, formatDiagnostics } from "./utils/format-utils.js";
+import { registerRunnerId } from "./known-runner-ids.js";
+
+export class RunnerRegistry {
+  runners = new Map;
+  register(runner) {
+    if (this.runners.has(runner.id))
+      return;
+    this.runners.set(runner.id, runner);
+    registerRunnerId(runner.id);
+  }
+  get(id) {
+    return this.runners.get(id);
+  }
+  getForKind(kind, filePath) {
+    const matching = [];
+    const isTest = filePath ? isTestFile(filePath) : false;
+    for (const runner of this.runners.values()) {
+      if (isTest && runner.skipTestFiles)
+        continue;
+      if (runnerAppliesToKind(runner, kind)) {
+        matching.push(runner);
+      }
+    }
+    return matching.sort((a, b) => a.priority - b.priority);
+  }
+  list() {
+    return Array.from(this.runners.values());
+  }
+  clear() {
+    this.runners.clear();
+  }
+}
+function runnerAppliesToKind(runner, kind) {
+  return runner.appliesTo.length === 0 || kind !== undefined && runner.appliesTo.includes(kind);
+}
+export function normalizeCacheKey(cmd) {
+  const normalized = cmd.replace(/\.(cmd|exe)$/i, "").toLowerCase();
+  return `session.toolCache.${normalized}`;
+}
+const TOOL_PROBE_TIMEOUT_MS = 5000;
+function transientRetryKey(command) {
+  return `${normalizeCacheKey(command)}.retryAt`;
+}
+function transientAttemptsKey(command) {
+  return `${normalizeCacheKey(command)}.transientAttempts`;
+}
+export async function checkToolAvailability(command, facts) {
+  const key = normalizeCacheKey(command);
+  const cached = facts.getSessionFact(key);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const retryAt = facts.getSessionFact(transientRetryKey(command));
+  if (retryAt !== undefined && Date.now() < retryAt)
+    return false;
+  if (!await isSpawnableCommand(command)) {
+    facts.setSessionFact(key, false);
+    return false;
+  }
+  try {
+    const sampler = startHostStallSampler();
+    const startedAt = Date.now();
+    let result;
+    let hostStallMs;
+    let probeJoined = false;
+    try {
+      const shared = dispatcherProbeFlights.run(`dispatcher:${key}`, () => probeToolAsync(command, ["--version"], {
+        timeout: TOOL_PROBE_TIMEOUT_MS
+      }));
+      probeJoined = shared.joined;
+      result = await shared.promise;
+    } finally {
+      hostStallMs = sampler.stop();
+    }
+    const elapsedMs = Date.now() - startedAt;
+    recordAvailabilityProbeOverrun(command, key, elapsedMs, TOOL_PROBE_TIMEOUT_MS, result.failure);
+    if (result.status === 0) {
+      facts.setSessionFact(key, true);
+      facts.setSessionFact(transientRetryKey(command), 0);
+      facts.setSessionFact(transientAttemptsKey(command), 0);
+      logAvailabilityDecision({
+        tool: command,
+        verdict: "available",
+        outcome: "success",
+        cause: "ok",
+        elapsedMs,
+        latched: true,
+        classifiedBy: probeJoined ? "joined" : "probe",
+        hostStallMs,
+        budgetMs: TOOL_PROBE_TIMEOUT_MS
+      });
+      return true;
+    }
+    const { outcome, cause, evidence } = classifyProbeFailure(result, {
+      hostStallMs,
+      unclassifiedFailureOutcome: "missing"
+    });
+    let retryAfterMs;
+    if (outcome === "transient") {
+      const attempts = (facts.getSessionFact(transientAttemptsKey(command)) ?? 0) + 1;
+      facts.setSessionFact(transientAttemptsKey(command), attempts);
+      retryAfterMs = transientRetryDelayMs(attempts, cause);
+      facts.setSessionFact(transientRetryKey(command), Date.now() + retryAfterMs);
+    } else {
+      facts.setSessionFact(key, false);
+      facts.setSessionFact(transientAttemptsKey(command), 0);
+    }
+    logAvailabilityDecision({
+      tool: command,
+      verdict: "unavailable",
+      outcome,
+      cause,
+      elapsedMs,
+      latched: outcome !== "transient",
+      hostStallMs,
+      ...retryAfterMs !== undefined && { retryAfterMs },
+      budgetMs: TOOL_PROBE_TIMEOUT_MS,
+      classifiedBy: probeJoined ? "joined" : "probe",
+      evidence
+    });
+    return false;
+  } catch {
+    facts.setSessionFact(key, false);
+    return false;
+  }
+}
+function readFilePrefix(filePath, maxBytes = 4096) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, "r");
+    const buffer = Buffer.alloc(maxBytes);
+    const bytesRead = fs.readSync(fd, buffer, 0, maxBytes, 0);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } catch {
+    return;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {}
+    }
+  }
+}
+export function createDispatchContext(filePath, cwd, pi, facts, blockingOnly, modifiedRanges, projectRoot, writeIndex, telemetryModel, telemetryProvider, sessionGeneration, sessionId, analysisRootMode) {
+  const absoluteFilePath = resolveRunnerPath(cwd, filePath);
+  const normalizedProjectRoot = normalizeMapKey(path.resolve(projectRoot ?? cwd));
+  const normalizedCwd = normalizeMapKey(resolveLanguageRootForFile(absoluteFilePath, cwd));
+  const normalizedFilePath = normalizeMapKey(absoluteFilePath);
+  const kindFilePath = !isWindowsPath(filePath) && filePath.includes("\\") ? path.resolve(cwd, filePath) : absoluteFilePath;
+  const kind = detectFileKind(kindFilePath);
+  const contentPrefix = readFilePrefix(normalizedFilePath);
+  const fileRole = detectFileRole(normalizedFilePath, contentPrefix);
+  const generatedDetail = fileRole === "generated" ? classifyGeneratedOrArtifactDetailed(normalizedFilePath, {
+    content: contentPrefix,
+    includeDeclarations: false
+  }) : undefined;
+  const projectConfig = loadDmLensProjectConfig(normalizedCwd);
+  const rulePolicy = resolvedRulePolicyMap(normalizedProjectRoot);
+  return {
+    filePath: normalizedFilePath,
+    projectRoot: normalizedProjectRoot,
+    cwd: normalizedCwd,
+    kind,
+    fileRole,
+    analysisRootMode,
+    generatedEvidence: generatedDetail?.evidence,
+    generatedLineShapeMean: generatedDetail?.lineShapeMean,
+    pi,
+    autofix: false,
+    deltaMode: !pi.getFlag("no-delta"),
+    facts,
+    projectConfig,
+    rulePolicy,
+    blockingOnly,
+    modifiedRanges,
+    writeIndex,
+    sessionGeneration,
+    sessionId,
+    telemetryModel,
+    telemetryProvider,
+    toolCwdMemo: {},
+    async hasTool(command) {
+      return checkToolAvailability(command, facts);
+    },
+    log(message, level) {
+      logExtension({
+        subsystem: "dispatch",
+        ...level !== undefined && { level },
+        message,
+        metadata: { filePath: normalizedFilePath, kind }
+      });
+    }
+  };
+}
+function filterDelta(after, before, keyFn) {
+  const beforeSet = new Set((before ?? []).map(keyFn));
+  const afterSet = new Set(after.map(keyFn));
+  const fixed = (before ?? []).filter((d) => !afterSet.has(keyFn(d)));
+  const newItems = after.filter((d) => !beforeSet.has(keyFn(d)));
+  return { new: newItems, fixed };
+}
+function semanticRank(semantic) {
+  if (semantic === "blocking")
+    return 4;
+  if (semantic === "warning")
+    return 3;
+  if (semantic === "fixed")
+    return 2;
+  if (semantic === "silent")
+    return 1;
+  return 0;
+}
+function toolPriority(tool, defectClass) {
+  return getToolProfile(tool, defectClass).dedupPriority;
+}
+function dedupeOverlappingDiagnostics(diagnostics) {
+  const byKey = new Map;
+  for (const d of diagnostics) {
+    const defectClass = d.defectClass ?? classifyDiagnostic(d);
+    const line = d.line ?? 1;
+    const column = d.column ?? 1;
+    const ruleKey = d.rule || d.id || "unknown";
+    const key = `${d.filePath}:${line}:${column}:${defectClass}:${ruleKey}`;
+    const current = byKey.get(key);
+    if (!current) {
+      byKey.set(key, { ...d, defectClass });
+      continue;
+    }
+    const currScore = semanticRank(current.semantic) * 100 + toolPriority(current.tool, defectClass);
+    const nextScore = semanticRank(d.semantic) * 100 + toolPriority(d.tool, defectClass);
+    if (nextScore > currScore) {
+      byKey.set(key, { ...d, defectClass });
+    }
+  }
+  return [...byKey.values()];
+}
+function suppressLintOverlapsWithLsp(diagnostics) {
+  const lspBySpanClass = new Set;
+  const lspByLine = new Set;
+  const isLintTool = (tool) => {
+    return getToolProfile(tool).lintLike;
+  };
+  for (const d of diagnostics) {
+    if (d.tool !== "lsp")
+      continue;
+    const line = d.line ?? 1;
+    const defectClass = d.defectClass ?? classifyDiagnostic(d);
+    lspBySpanClass.add(`${d.filePath}:${line}:${defectClass}`);
+    lspByLine.add(`${d.filePath}:${line}`);
+  }
+  if (lspByLine.size === 0)
+    return diagnostics;
+  return diagnostics.filter((d) => {
+    if (d.tool === "lsp")
+      return true;
+    if (!isLintTool(d.tool))
+      return true;
+    if (d.semantic === "blocking" || d.severity === "error")
+      return true;
+    const line = d.line ?? 1;
+    const defectClass = d.defectClass ?? classifyDiagnostic(d);
+    const key = `${d.filePath}:${line}:${defectClass}`;
+    if (lspBySpanClass.has(key))
+      return false;
+    if (defectClass === "unknown") {
+      return !lspByLine.has(`${d.filePath}:${line}`);
+    }
+    return true;
+  });
+}
+export function suppressTrivyConfigDockerOverlap(diagnostics) {
+  const hadolintLines = new Set;
+  for (const d of diagnostics) {
+    if (d.tool === "hadolint") {
+      hadolintLines.add(`${d.filePath}:${d.line ?? 1}`);
+    }
+  }
+  if (hadolintLines.size === 0)
+    return diagnostics;
+  return diagnostics.filter((d) => d.tool !== "trivy-config" || !hadolintLines.has(`${d.filePath}:${d.line ?? 1}`));
+}
+function isUnusedValueDiagnostic(d) {
+  const raw = `${d.id ?? ""} ${d.rule ?? ""} ${d.message ?? ""}`.toLowerCase();
+  if (raw.includes("no-unused"))
+    return true;
+  if (/\b(6133|6192|6196)\b/.test(raw))
+    return true;
+  const rule = String(d.rule ?? "").toLowerCase();
+  if (rule.includes("unused"))
+    return true;
+  const message = d.message.toLowerCase();
+  return message.includes("is declared but its value is never read") || message.includes("is assigned a value but never used") || message.includes("declared but never used") || message.includes("unused");
+}
+function promoteDeltaUnusedToBlockers(diagnostics) {
+  return diagnostics.map((d) => {
+    if (!isUnusedValueDiagnostic(d))
+      return d;
+    if (d.semantic === "blocking" || d.severity === "error")
+      return d;
+    return {
+      ...d,
+      severity: "error",
+      semantic: "blocking",
+      promotionNote: DELTA_UNUSED_PROMOTION_NOTE,
+      fixSuggestion: d.fixSuggestion ?? "Remove the unused declaration or rename with '_' prefix if intentionally unused."
+    };
+  });
+}
+function buildCoverageNotice(ctx, runnerLatencies, dedupe) {
+  if (!ctx.kind)
+    return;
+  const lspEnabled = !ctx.pi.getFlag("no-lsp");
+  const primary = getPrimaryDispatchGroup(ctx.kind, lspEnabled);
+  if (!primary || primary.runnerIds.length === 0)
+    return;
+  const relevant = runnerLatencies.filter((r) => primary.runnerIds.includes(r.runnerId));
+  if (relevant.length === 0)
+    return;
+  const unconfirmedServerIds = [
+    ...new Set(relevant.flatMap((r) => r.unconfirmedServerIds ?? []))
+  ];
+  if (unconfirmedServerIds.length > 0) {
+    const deferredIds = new Set(relevant.flatMap((r) => r.deferredServerIds ?? []));
+    const markerFor = (ids) => {
+      const shown = ids.slice(0, 4);
+      const remainder = ids.length - shown.length;
+      return `${shown.join(", ")}${remainder > 0 ? ` +${remainder}` : ""}`;
+    };
+    const deferredServerIds = unconfirmedServerIds.filter((id) => deferredIds.has(id));
+    const silentServerIds = unconfirmedServerIds.filter((id) => !deferredIds.has(id));
+    const dedupeSet = (ids) => [...new Set(ids)].map(normalizeEphemeralMapKey).sort((a, b) => Number(a > b) - Number(a < b)).join(",");
+    const onceKey = `${ctx.kind}:${ctx.filePath}:${dedupeSet(silentServerIds)}|${dedupeSet(deferredServerIds)}`;
+    if (dedupe) {
+      if (coverageNoticeSeen.has(onceKey))
+        return;
+      coverageNoticeSeen.add(onceKey);
+    }
+    const coverageParts = [];
+    if (deferredServerIds.length > 0) {
+      coverageParts.push(`coverage: ${markerFor(deferredServerIds)} deferred — diagnostics are incomplete; findings arrive at turn end if the scan lands.`);
+    }
+    if (silentServerIds.length > 0) {
+      coverageParts.push(`coverage: ${markerFor(silentServerIds)} silent — diagnostics are incomplete (not a clean result).`);
+    }
+    return {
+      id: `coverage-partial:${ctx.kind}:${path.basename(ctx.filePath)}`,
+      message: coverageParts.join(`
+`),
+      filePath: ctx.filePath,
+      severity: "warning",
+      semantic: "warning",
+      tool: "dm-lens"
+    };
+  }
+  const primaryHasCoverage = relevant.some(hasUsableResult);
+  if (primaryHasCoverage)
+    return;
+  const primaryStillInFlight = relevant.some((r) => r.status === "pending" || r.status === "deferred");
+  if (primaryStillInFlight)
+    return;
+  const plan = getToolPlan(ctx.kind);
+  const fallbackRunnerIds = new Set((plan?.groups ?? []).filter((group) => !group.runnerIds.every((runnerId) => primary.runnerIds.includes(runnerId))).flatMap((group) => group.runnerIds).filter((runnerId) => !primary.runnerIds.includes(runnerId)));
+  const STRUCTURAL_RUNNERS = new Set([
+    "tree-sitter",
+    "ast-grep-napi",
+    "spellcheck",
+    "fact-rules",
+    "opengrep"
+  ]);
+  const TYPE_CAPABLE_FALLBACK_RUNNERS = new Set(["mypy"]);
+  const anyFallbackHasCoverage = runnerLatencies.some((r) => fallbackRunnerIds.has(r.runnerId) && !STRUCTURAL_RUNNERS.has(r.runnerId) && hasUsableResult(r) && (!plan?.capabilities.includes("types") || TYPE_CAPABLE_FALLBACK_RUNNERS.has(r.runnerId)));
+  if (anyFallbackHasCoverage)
+    return;
+  const onceKey = `${ctx.kind}:${ctx.filePath}`;
+  if (dedupe) {
+    if (coverageNoticeSeen.has(onceKey))
+      return;
+    coverageNoticeSeen.add(onceKey);
+  }
+  return {
+    id: `coverage-unavailable:${ctx.kind}:${path.basename(ctx.filePath)}`,
+    message: `DM-lens ${ctx.kind} analysis unavailable — a language tool is missing, timed out, or failed to run, or the LSP server isn't ready yet, so this file was not fully checked (not a clean result).`,
+    filePath: ctx.filePath,
+    severity: "warning",
+    semantic: "warning",
+    tool: "dm-lens"
+  };
+}
+const latencyReports = [];
+const coverageNoticeSeen = new Set;
+const generatedSkipRecorded = new Set;
+export function getLatencyReports() {
+  return [...latencyReports];
+}
+export function clearLatencyReports() {
+  latencyReports.length = 0;
+}
+export function clearCoverageNoticeState() {
+  coverageNoticeSeen.clear();
+  generatedSkipRecorded.clear();
+}
+export function formatLatencyReport(report) {
+  const lines = [];
+  lines.push(`
+═══════════════════════════════════════════════════════════════`);
+  lines.push(`\uD83D\uDCCA DISPATCH LATENCY REPORT: ${report.filePath.split("/").pop()}`);
+  lines.push(`   Kind: ${report.fileKind || "unknown"} | Total: ${report.totalDurationMs}ms`);
+  lines.push(`───────────────────────────────────────────────────────────────`);
+  lines.push(`Runner                          Duration  Status    Issues  Semantic`);
+  lines.push(`───────────────────────────────────────────────────────────────`);
+  for (const r of report.runners) {
+    const name = r.runnerId.padEnd(30);
+    const dur = `${r.durationMs}ms`.padStart(8);
+    const status = r.status.padStart(9);
+    const issues = String(r.diagnosticCount).padStart(6);
+    const sem = r.semantic.padStart(8);
+    const slowMarker = r.durationMs > 500 ? " \uD83D\uDD25" : r.durationMs > 100 ? " ⚡" : "";
+    lines.push(`${name}${dur}${status}${issues}${sem}${slowMarker}`);
+  }
+  lines.push(`───────────────────────────────────────────────────────────────`);
+  lines.push(`Total: ${report.runners.length} runners | Stopped early: ${report.stoppedEarly}`);
+  lines.push(`Diagnostics: ${report.totalDiagnostics} (${report.blockers} blockers, ${report.warnings} warnings)`);
+  const sorted = [...report.runners].sort((a, b) => b.durationMs - a.durationMs);
+  if (sorted.length > 0 && sorted[0].durationMs > 100) {
+    lines.push(`
+\uD83D\uDC0C Slowest runners:`);
+    for (const r of sorted.slice(0, 3)) {
+      if (r.durationMs > 50) {
+        lines.push(`   ${r.runnerId}: ${r.durationMs}ms (${r.status})`);
+      }
+    }
+  }
+  lines.push(`═══════════════════════════════════════════════════════════════`);
+  return lines.join(`
+`);
+}
+async function runGroup(ctx, group, registry, onRunnerResult) {
+  const diagnostics = [];
+  const latencies = [];
+  let hadBlocker = false;
+  const runnerIds = group.filterKinds ? group.runnerIds.filter((id) => {
+    const runner = registry.get(id);
+    return runner && ctx.kind && group.filterKinds?.includes(ctx.kind);
+  }) : group.runnerIds;
+  const semantic = group.semantic ?? "warning";
+  for (const runnerId of runnerIds) {
+    const runnerStart = Date.now();
+    const runner = registry.get(runnerId);
+    if (!runner) {
+      latencies.push({
+        runnerId,
+        startTime: runnerStart,
+        endTime: Date.now(),
+        durationMs: 0,
+        status: "skipped",
+        diagnosticCount: 0,
+        semantic: "unknown"
+      });
+      logLatency({
+        type: "runner",
+        filePath: ctx.filePath,
+        runnerId,
+        durationMs: 0,
+        status: "not_registered",
+        diagnosticCount: 0,
+        semantic: "unknown"
+      });
+      continue;
+    }
+    if (runner.skipTestFiles && isTestFile(ctx.filePath)) {
+      latencies.push({
+        runnerId,
+        startTime: runnerStart,
+        endTime: Date.now(),
+        durationMs: Date.now() - runnerStart,
+        status: "test_file_skipped",
+        diagnosticCount: 0,
+        semantic: "none"
+      });
+      logLatency({
+        type: "runner",
+        filePath: ctx.filePath,
+        runnerId,
+        durationMs: 0,
+        status: "test_file_skipped",
+        diagnosticCount: 0,
+        semantic: "none"
+      });
+      continue;
+    }
+    const appliesToCurrentKind = runnerAppliesToKind(runner, ctx.kind);
+    if (!appliesToCurrentKind) {
+      const runnerEnd = Date.now();
+      latencies.push({
+        runnerId,
+        startTime: runnerStart,
+        endTime: runnerEnd,
+        durationMs: 0,
+        status: "skipped",
+        diagnosticCount: 0,
+        semantic: "unknown"
+      });
+      logLatency({
+        type: "runner",
+        filePath: ctx.filePath,
+        runnerId,
+        durationMs: 0,
+        status: "skipped",
+        diagnosticCount: 0,
+        semantic: "unknown",
+        metadata: { reason: "applies_to", kind: ctx.kind }
+      });
+      continue;
+    }
+    let shouldRun = true;
+    if (runner.when) {
+      try {
+        shouldRun = await runner.when(ctx);
+      } catch (error) {
+        ctx.log(`Runner ${runner.id} precondition failed: ${error}`);
+        shouldRun = false;
+      }
+    }
+    if (!shouldRun) {
+      latencies.push({
+        runnerId,
+        startTime: runnerStart,
+        endTime: Date.now(),
+        durationMs: Date.now() - runnerStart,
+        status: "when_skipped",
+        diagnosticCount: 0,
+        semantic: runner.id
+      });
+      logLatency({
+        type: "runner",
+        filePath: ctx.filePath,
+        runnerId,
+        durationMs: 0,
+        status: "when_skipped",
+        diagnosticCount: 0,
+        semantic: "when_condition"
+      });
+      continue;
+    }
+    const projectRoot = ctx.projectRoot ?? ctx.cwd;
+    const observedTier = ctx.writeIndex === undefined ? "inline" : classifyObservedRunner(projectRoot, runner.id);
+    if (observedTier === "collect-later") {
+      const markedAtMs = Date.now();
+      const deferred = runRunner(ctx, runner, semantic).then((result) => {
+        const durationMs = Date.now() - markedAtMs;
+        const tier = observeRunnerLatency({
+          projectRoot,
+          runnerId: runner.id,
+          durationMs,
+          timedOut: result.failureKind === "timeout"
+        });
+        if (tier !== observedTier) {
+          logLatency({
+            type: "phase",
+            filePath: ctx.filePath,
+            phase: "runner_collect_later_tier_flip",
+            durationMs: 0,
+            metadata: {
+              runnerId: runner.id,
+              from: observedTier,
+              to: tier,
+              projectRoot
+            }
+          });
+        }
+        if (tier === "collect-later") {
+          incrementDegradationCount({
+            kind: "runner-collect-later",
+            subject: `${projectRoot}:${runner.id}`,
+            reason: `observed ${durationMs}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`
+          });
+        }
+        logLatency({
+          type: "runner",
+          filePath: ctx.filePath,
+          runnerId: runner.id,
+          startedAt: new Date(markedAtMs).toISOString(),
+          durationMs,
+          status: result.status,
+          diagnosticCount: result.diagnostics.length,
+          semantic: result.semantic ?? semantic,
+          metadata: {
+            tier: "collect-later",
+            delivered: "turn_end",
+            ...failureRowMetadata(result)
+          }
+        });
+        return result;
+      });
+      deferRunnerFindings({
+        filePath: ctx.filePath,
+        cwd: ctx.cwd,
+        projectRoot,
+        runnerId: runner.id,
+        markedAtMs,
+        writeIndex: ctx.writeIndex,
+        promise: deferred,
+        session: ctx.sessionGeneration,
+        sessionId: ctx.sessionId
+      });
+      latencies.push({
+        runnerId: runner.id,
+        startTime: runnerStart,
+        endTime: runnerStart,
+        durationMs: 0,
+        status: "pending",
+        diagnosticCount: 0,
+        semantic
+      });
+      recordRunner(ctx.filePath, runner.id, "pending", 0, 0, ctx.writeIndex);
+      logLatency({
+        type: "runner",
+        filePath: ctx.filePath,
+        runnerId: runner.id,
+        durationMs: 0,
+        status: "pending",
+        diagnosticCount: 0,
+        semantic,
+        metadata: { tier: "collect-later", delivered: "turn_end" }
+      });
+      continue;
+    }
+    const result = await runRunner(ctx, runner, semantic);
+    onRunnerResult?.(runnerId, result);
+    const runnerEnd = Date.now();
+    const duration = runnerEnd - runnerStart;
+    const tier = ctx.writeIndex === undefined ? "inline" : observeRunnerLatency({
+      projectRoot,
+      runnerId: runner.id,
+      durationMs: duration,
+      timedOut: result.failureKind === "timeout"
+    });
+    if (tier !== observedTier) {
+      logLatency({
+        type: "phase",
+        filePath: ctx.filePath,
+        phase: "runner_collect_later_tier_flip",
+        durationMs: 0,
+        metadata: {
+          runnerId: runner.id,
+          from: observedTier,
+          to: tier,
+          projectRoot
+        }
+      });
+    }
+    if (tier === "collect-later") {
+      incrementDegradationCount({
+        kind: "runner-collect-later",
+        subject: `${projectRoot}:${runner.id}`,
+        reason: `observed ${duration}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`
+      });
+    }
+    const skipReason = result.status === "skipped" && isRunnerSkipReason(result.skipReason) ? result.skipReason : undefined;
+    const claimSource = result.status === "skipped" && isRunnerClaimSource(result.claimSource) ? result.claimSource : undefined;
+    latencies.push({
+      runnerId,
+      startTime: runnerStart,
+      endTime: runnerEnd,
+      durationMs: duration,
+      status: result.status,
+      diagnosticCount: result.diagnostics.length,
+      semantic: result.semantic ?? semantic,
+      ...result.failureKind !== undefined && {
+        failureKind: result.failureKind
+      },
+      ...skipReason !== undefined && {
+        skipReason
+      },
+      ...claimSource !== undefined && {
+        claimSource
+      },
+      ...result.unconfirmedServerIds !== undefined && {
+        unconfirmedServerIds: result.unconfirmedServerIds
+      },
+      ...result.deferredServerIds !== undefined && {
+        deferredServerIds: result.deferredServerIds
+      }
+    });
+    logLatency({
+      type: "runner",
+      filePath: ctx.filePath,
+      runnerId,
+      startedAt: new Date(runnerStart).toISOString(),
+      durationMs: duration,
+      status: result.status,
+      diagnosticCount: result.diagnostics.length,
+      semantic: result.semantic ?? semantic,
+      diagnostics: result.diagnostics.length > 0 ? result.diagnostics.map((d) => ({
+        rule: d.rule,
+        message: d.message.slice(0, 120),
+        line: d.line,
+        semantic: d.semantic
+      })) : undefined,
+      metadata: failureRowMetadata(result) ?? (skipReason ? { skipReason, ...claimSource !== undefined && { claimSource } } : undefined)
+    });
+    recordRunner(ctx.filePath, runnerId, result.status, result.diagnostics.length, duration, ctx.writeIndex);
+    diagnostics.push(...result.diagnostics);
+    const resultSemantic = result.semantic ?? semantic;
+    if (resultSemantic === "blocking" && result.diagnostics.length > 0 || result.diagnostics.some((d) => d.semantic === "blocking")) {
+      hadBlocker = true;
+    }
+    if (group.mode === "fallback" && result.status === "succeeded") {
+      break;
+    }
+  }
+  return { diagnostics, latencies, hadBlocker };
+}
+export async function dispatchForFile(ctx, groups, registry, onRunnerResult, options) {
+  const _overallStart = Date.now();
+  if (ctx.analysisRootMode === "adopted") {
+    const planned = groups.flatMap((g) => g.runnerIds);
+    groups = filterGroupsForAdoptedRoot(groups);
+    const admitted = new Set(groups.flatMap((g) => g.runnerIds));
+    logLatency({
+      type: "phase",
+      filePath: ctx.filePath,
+      phase: "dispatch_adopted_root_allowlist",
+      durationMs: 0,
+      metadata: {
+        admissionList: ADOPTED_ROOT_RUNNER_ALLOWLIST.join(","),
+        admitted: groups.flatMap((g) => g.runnerIds).join(","),
+        refused: planned.flatMap((id) => admitted.has(id) ? [] : [id]).join(","),
+        noAdmittedRunner: groups.length === 0
+      }
+    });
+    if (groups.length === 0) {
+      return {
+        diagnostics: [],
+        blockers: [],
+        warnings: [],
+        baselineWarningCount: 0,
+        fixed: [],
+        resolvedCount: 0,
+        output: "",
+        blockerOutput: "",
+        hasBlockers: false
+      };
+    }
+  }
+  if (ctx.fileRole === "generated") {
+    const evidence = ctx.generatedEvidence;
+    const lineShapeMean = ctx.generatedLineShapeMean;
+    if (!generatedSkipRecorded.has(ctx.filePath)) {
+      generatedSkipRecorded.add(ctx.filePath);
+      logLatency({
+        type: "phase",
+        filePath: ctx.filePath,
+        phase: "dispatch_skipped_generated",
+        durationMs: 0,
+        metadata: {
+          evidence: evidence ?? "unknown",
+          ...lineShapeMean !== undefined && { lineShapeMean }
+        }
+      });
+    }
+    return {
+      diagnostics: [],
+      blockers: [],
+      warnings: [],
+      baselineWarningCount: 0,
+      fixed: [],
+      resolvedCount: 0,
+      output: "",
+      blockerOutput: "",
+      hasBlockers: false
+    };
+  }
+  const allDiagnostics = [];
+  let stopped = false;
+  const runnerLatencies = [];
+  const allRunnerIds = groups.flatMap((g) => g.runnerIds);
+  logLatency({
+    type: "phase",
+    filePath: ctx.filePath,
+    phase: "dispatch_start",
+    durationMs: 0,
+    metadata: {
+      groupCount: groups.length,
+      kind: ctx.kind,
+      runners: allRunnerIds.join(",")
+    }
+  });
+  const groupResults = await Promise.all(groups.map((group) => runGroup(ctx, group, registry, onRunnerResult)));
+  const baselinePathSafe = isAbsoluteFilePath(ctx.filePath);
+  if (ctx.deltaMode && !baselinePathSafe) {
+    recordDegradationOnce({
+      kind: "dispatch-non-absolute-baseline-path",
+      subject: ctx.filePath,
+      reason: "dispatchForFile requires an absolute ctx.filePath to key the delta baseline (refs #2489)"
+    });
+  }
+  const baselineAbsKey = `session.baseline.${ctx.filePath}`;
+  const previousBaseline = ctx.deltaMode && baselinePathSafe ? ctx.facts.getBoundedSessionFact(baselineAbsKey) : undefined;
+  const baselineWarnings = previousBaseline?.filter((d) => d.semantic === "warning" || d.semantic === "none");
+  const baselineWarningCount = baselineWarnings?.length ?? 0;
+  for (const { diagnostics: groupDiags, latencies, hadBlocker } of groupResults) {
+    runnerLatencies.push(...latencies);
+    allDiagnostics.push(...groupDiags);
+    if (hadBlocker)
+      stopped = true;
+  }
+  const dedupedDiagnostics = dedupeOverlappingDiagnostics(allDiagnostics);
+  const fileContent = ctx.facts.getFileFact(ctx.filePath, "file.content") ?? "";
+  const rulePolicy = ctx.rulePolicy ?? rulePolicyMapFromConfig(loadDmLensProjectConfig(ctx.projectRoot ?? ctx.cwd).rules);
+  const applyOutputFilters = (diags) => {
+    const dockerOverlap = suppressTrivyConfigDockerOverlap(diags);
+    const overlap = suppressLintOverlapsWithLsp(dockerOverlap);
+    const inline = applyInlineSuppressions(overlap, fileContent);
+    const disposition = applyDispositions(inline, ctx.projectRoot ?? ctx.cwd, ctx.filePath, fileContent);
+    return applyRulePolicy(disposition, rulePolicy, {
+      root: ctx.projectRoot ?? ctx.cwd,
+      filePath: ctx.filePath
+    });
+  };
+  let visibleDiagnostics = applyOutputFilters(dedupedDiagnostics);
+  let resolvedCount = 0;
+  if (ctx.deltaMode && previousBaseline) {
+    const filtered = filterDelta(visibleDiagnostics, applyOutputFilters(previousBaseline), (d) => d.id);
+    visibleDiagnostics = promoteDeltaUnusedToBlockers(filtered.new);
+    resolvedCount = filtered.fixed.length;
+  }
+  if (ctx.deltaMode && baselinePathSafe) {
+    ctx.facts.setBoundedSessionFact(baselineAbsKey, [...dedupedDiagnostics]);
+  }
+  const blockers = visibleDiagnostics.filter((d) => d.semantic === "blocking");
+  const warnings = visibleDiagnostics.filter((d) => d.semantic === "warning" || d.semantic === "none");
+  const fixedItems = visibleDiagnostics.filter((d) => d.semantic === "fixed");
+  const worklogIdentity = {
+    model: ctx.telemetryModel,
+    provider: ctx.telemetryProvider
+  };
+  if (fixedItems.length > 0) {
+    import("../fix-worklog.js").then(({ appendToWorklog }) => {
+      appendToWorklog(ctx.cwd, fixedItems, true, worklogIdentity);
+    }).catch(() => {});
+  }
+  const fixableWarnings = warnings.filter((d) => d.fixable);
+  if (fixableWarnings.length > 0) {
+    import("../fix-worklog.js").then(({ appendToWorklog }) => {
+      appendToWorklog(ctx.cwd, fixableWarnings, false, worklogIdentity);
+    }).catch(() => {});
+  }
+  const inlineBlockers = blockers;
+  const inlineFixed = fixedItems;
+  const coverageNotice = buildCoverageNotice(ctx, runnerLatencies, options?.dedupeCoverageNotice ?? true);
+  const blockerOutput = formatDiagnostics(inlineBlockers, "blocking");
+  let output = blockerOutput;
+  output += formatDiagnostics(inlineFixed, "fixed");
+  if (coverageNotice) {
+    output += formatDiagnostics([coverageNotice], "warning", 1);
+    warnings.push(coverageNotice);
+  }
+  const pendingRunners = runnerLatencies.filter((runner) => runner.status === "pending").map((runner) => runner.runnerId);
+  if (pendingRunners.length > 0) {
+    output += `
+⏳ Pending runners (reported at turn end): ${pendingRunners.join(", ")}
+`;
+  }
+  const overallEnd = Date.now();
+  const latencyReport = {
+    filePath: ctx.filePath,
+    fileKind: ctx.kind,
+    overallStartMs: _overallStart,
+    overallEndMs: overallEnd,
+    totalDurationMs: overallEnd - _overallStart,
+    runners: runnerLatencies,
+    stoppedEarly: stopped,
+    totalDiagnostics: visibleDiagnostics.length,
+    blockers: blockers.length,
+    warnings: warnings.length
+  };
+  latencyReports.push(latencyReport);
+  if (latencyReports.length > 100) {
+    latencyReports.shift();
+  }
+  const sumMs = runnerLatencies.reduce((s, r) => s + r.durationMs, 0);
+  const wallClockMs = latencyReport.totalDurationMs;
+  logLatency({
+    type: "tool_result",
+    filePath: ctx.filePath,
+    durationMs: wallClockMs,
+    wallClockMs,
+    sumMs,
+    parallelGainMs: Math.max(0, sumMs - wallClockMs),
+    result: "dispatch_complete",
+    metadata: {
+      runners: runnerLatencies.map((r) => ({
+        id: r.runnerId,
+        startedAt: new Date(r.startTime).toISOString(),
+        duration: r.durationMs,
+        status: r.status
+      })),
+      totalDiagnostics: visibleDiagnostics.length,
+      blockers: blockers.length,
+      baselineHit: previousBaseline !== undefined,
+      baselineWarningCount
+    }
+  });
+  return {
+    latencyReport,
+    diagnostics: visibleDiagnostics,
+    blockers,
+    warnings,
+    baselineWarningCount,
+    fixed: fixedItems,
+    resolvedCount,
+    output,
+    blockerOutput,
+    hasBlockers: blockers.length > 0
+  };
+}
+const RUNNER_TIMEOUT_MS = RUNTIME_CONFIG.dispatch.runnerTimeoutMs;
+function looksLikeDiagnosticCodePath(value) {
+  if (!value)
+    return false;
+  const text = value.trim();
+  if (!text)
+    return false;
+  const base = path.basename(text.replace(/\\/g, "/"));
+  if (/^lsp:\d+(?::\d+)?$/i.test(text) || /^lsp:\d+(?::\d+)?$/i.test(base)) {
+    return true;
+  }
+  if (/^similarity[-:]/i.test(text) || /^similarity[-:]/i.test(base)) {
+    return true;
+  }
+  if (/^[a-z-]+:\d+(?::\d+)?$/i.test(text) || /^[a-z-]+:\d+(?::\d+)?$/i.test(base)) {
+    return true;
+  }
+  return false;
+}
+function normalizeDiagnosticFilePath(ctx, rawPath) {
+  if (typeof rawPath === "string" && looksLikeDiagnosticCodePath(rawPath)) {
+    ctx.log(`runner path normalization: ignored diagnostic code-like path '${rawPath}', using current file`);
+    return resolveRunnerPath(ctx.cwd, ctx.filePath);
+  }
+  return resolveRunnerPath(ctx.cwd, rawPath || ctx.filePath);
+}
+function failureRowMetadata(result) {
+  return result.status === "failed" && result.failureKind ? {
+    failureKind: result.failureKind,
+    failureMessage: result.failureMessage
+  } : undefined;
+}
+async function runRunner(ctx, runner, defaultSemantic) {
+  const timeoutMs = Math.max(runner.timeoutMs ?? RUNNER_TIMEOUT_MS, getRunnerTimeoutFloorMs());
+  let timer;
+  const phaseToken = phaseStarted(runner.id);
+  try {
+    const result = await Promise.race([
+      runner.run(ctx).finally(() => clearTimeout(timer)),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Runner ${runner.id} timed out after ${timeoutMs}ms`)), timeoutMs);
+      })
+    ]);
+    const diagnostics = result.diagnostics.map((d) => ({
+      ...d,
+      filePath: normalizeDiagnosticFilePath(ctx, d.filePath)
+    }));
+    return {
+      ...result,
+      diagnostics,
+      semantic: result.semantic ?? defaultSemantic
+    };
+  } catch (error) {
+    clearTimeout(timer);
+    ctx.log(`Runner ${runner.id} failed: ${error}`);
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      status: "failed",
+      diagnostics: [],
+      semantic: defaultSemantic,
+      failureKind: message.includes("timed out") ? "timeout" : "exception",
+      failureMessage: message.slice(0, 200)
+    };
+  } finally {
+    phaseFinished(phaseToken);
+  }
+}