@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

package/extensions/dm-lens/dist/clients/actionable-warnings.js

@@ -0,0 +1,1062 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { hashText, normalizeMessage, stableFindingId } from "./finding-identity.js";
+import { applyWorkspaceEdit, StaleWorkspaceEditContentError, workspaceEditDiskPaths } from "./lsp/edits.js";
+import { getLSPService } from "./lsp/capabilities.js";
+import { isUnderDir, normalizeMapKey } from "./path-utils.js";
+import { bounded, combineAbortSignals, withDeadline } from "./deadline-utils.js";
+import { armDeferredLspWork, awaitDeferredLspWork, registerDeferredLspWork } from "./deferred-lsp-work.js";
+import { incrementDegradationCount, recordDegradationOnce } from "./degradation-ledger.js";
+import { recordLspMutationBatch } from "./lsp-mutation.js";
+import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
+import { logActionableWarningsEvent } from "./actionable-warnings-logger.js";
+import { displayProjectDataPath, getProjectDataDir } from "./file-utils.js";
+import { commitDurableStore } from "./durable-store.js";
+import { establishToolAgreement } from "./tool-agreement.js";
+import { resolveLensToolName } from "./tool-config.js";
+let beforeWarningStateLockForTests = null;
+export function _setBeforeWarningStateLockForTests(hook) {
+  beforeWarningStateLockForTests = hook;
+}
+export function createActionableWarningId(args) {
+  return stableFindingId("aw:", {
+    cwd: args.cwd,
+    filePath: args.filePath,
+    parts: [
+      args.tool,
+      args.source,
+      args.code,
+      args.rule,
+      normalizeMessage(args.message),
+      args.line
+    ]
+  });
+}
+function legacyActionableWarningId(args) {
+  const rel = path.relative(args.cwd, args.filePath).replace(/\\/g, "/");
+  const legacyRelativeFile = rel && !rel.startsWith("..") ? rel : normalizeMapKey(args.filePath);
+  const parts = [
+    legacyRelativeFile,
+    args.tool ?? "",
+    args.source ?? "",
+    String(args.code ?? ""),
+    args.rule ?? "",
+    normalizeMessage(args.message),
+    String(args.line ?? "")
+  ];
+  return `aw:${hashText(parts.join("|"), 10)}`;
+}
+function actionSafety(action) {
+  const kind = action.kind ?? "";
+  if (!kind.startsWith("quickfix"))
+    return { eligible: false, reason: "not_quickfix" };
+  if (!action.isPreferred)
+    return { eligible: false, reason: "not_preferred" };
+  if (!action.edit)
+    return { eligible: false, reason: "no_edit" };
+  if (action.command)
+    return { eligible: false, reason: "has_command" };
+  return { eligible: true };
+}
+function serializeAction(action) {
+  const safety = actionSafety(action);
+  return {
+    title: action.title,
+    kind: action.kind,
+    isPreferred: action.isPreferred,
+    hasEdit: Boolean(action.edit),
+    hasCommand: Boolean(action.command),
+    autoFixEligible: safety.eligible,
+    skipReason: safety.reason
+  };
+}
+function deserializeSuppressionState(contents) {
+  try {
+    const parsed = JSON.parse(contents ?? "");
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function readSuppressionState(cwd) {
+  const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
+  try {
+    return deserializeSuppressionState(fs.readFileSync(statePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function updateWarningState(cwd, warnings) {
+  const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  const hook = beforeWarningStateLockForTests;
+  beforeWarningStateLockForTests = null;
+  hook?.();
+  commitDurableStore({
+    path: statePath,
+    deserialize: deserializeSuppressionState,
+    merge: (state) => {
+      const now = new Date().toISOString();
+      state.warnings ??= {};
+      for (const warning of warnings) {
+        const legacyId = warning.legacyId;
+        const legacyEntry = legacyId && legacyId !== warning.id ? state.warnings[legacyId] : undefined;
+        const existing = state.warnings[warning.id] ?? legacyEntry ?? {};
+        state.warnings[warning.id] = {
+          ...existing,
+          status: existing.status ?? "active",
+          firstSeenAt: existing.firstSeenAt ?? now,
+          lastSeenAt: now,
+          seenCount: (existing.seenCount ?? 0) + 1
+        };
+        if (legacyEntry && legacyId)
+          delete state.warnings[legacyId];
+      }
+      return state;
+    },
+    serialize: (state) => JSON.stringify(state, null, 2),
+    waitMs: 2000,
+    retryMs: 10,
+    timeoutMessage: "timed out acquiring actionable warning store lock",
+    onContention: "skip-log",
+    logContention: () => logActionableWarningsEvent({
+      event: "warning_state_write_dropped",
+      metadata: { reason: "lock_contention" }
+    })
+  });
+}
+function suppressionFor(cwd, id, args) {
+  const state = readSuppressionState(cwd);
+  const legacyId = legacyActionableWarningId({ cwd, ...args });
+  const entry = state.warnings?.[id] ?? (legacyId !== id ? state.warnings?.[legacyId] : undefined);
+  return {
+    suppressed: entry?.status === "suppressed",
+    reason: entry?.reason,
+    legacyId
+  };
+}
+export function recordFromDispatchDiagnostic(diagnostic, cwd) {
+  if (diagnostic.semantic !== "warning")
+    return;
+  if (diagnostic.severity === "error")
+    return;
+  if (!diagnostic.fixable && !diagnostic.fixSuggestion)
+    return;
+  const filePath = path.resolve(cwd, diagnostic.filePath);
+  const identityArgs = {
+    filePath,
+    tool: diagnostic.tool,
+    code: diagnostic.code,
+    rule: diagnostic.rule,
+    message: diagnostic.message,
+    line: diagnostic.line
+  };
+  const id = createActionableWarningId({ cwd, ...identityArgs });
+  const suppression = suppressionFor(cwd, id, identityArgs);
+  return {
+    id,
+    filePath,
+    displayPath: toRunnerDisplayPath(cwd, filePath),
+    line: diagnostic.line,
+    column: diagnostic.column,
+    severity: diagnostic.severity,
+    tool: diagnostic.tool,
+    code: diagnostic.code,
+    rule: diagnostic.rule,
+    message: diagnostic.message,
+    fixSuggestion: diagnostic.fixSuggestion,
+    fixKind: diagnostic.fixKind,
+    autoFixAvailable: diagnostic.autoFixAvailable,
+    actions: [],
+    suppressed: suppression.suppressed,
+    suppressionReason: suppression.reason,
+    legacyId: suppression.legacyId,
+    origin: "dispatch"
+  };
+}
+function lineInModifiedRanges(line, ranges) {
+  if (line === undefined)
+    return true;
+  if (ranges.length === 0)
+    return true;
+  return ranges.some((range) => line >= range.start - 2 && line <= range.end + 2);
+}
+export function recordFromLspDiagnostic(diag, filePath, cwd) {
+  const line = diag.range.start.line + 1;
+  const column = diag.range.start.character + 1;
+  const producer = diag.source && diag.source !== "lsp" ? diag.source : diag.serverId;
+  const source = diag.source ?? "lsp";
+  const code = diag.code === undefined ? undefined : String(diag.code);
+  const identityArgs = {
+    filePath,
+    tool: producer ?? "lsp",
+    source,
+    code,
+    message: diag.message,
+    line
+  };
+  const id = createActionableWarningId({ cwd, ...identityArgs });
+  const suppression = suppressionFor(cwd, id, identityArgs);
+  return {
+    id,
+    filePath,
+    displayPath: toRunnerDisplayPath(cwd, filePath),
+    line,
+    column,
+    severity: "warning",
+    tool: producer ?? "lsp",
+    source,
+    code,
+    rule: code ? `${source}:${code}` : source,
+    message: diag.message,
+    actions: [],
+    suppressed: suppression.suppressed,
+    suppressionReason: suppression.reason,
+    legacyId: suppression.legacyId,
+    origin: "lsp"
+  };
+}
+function mergeWarnings(records) {
+  const byId = new Map;
+  for (const record of records) {
+    const existing = byId.get(record.id);
+    if (!existing) {
+      byId.set(record.id, { ...record, actions: [...record.actions] });
+      continue;
+    }
+    existing.origin = existing.origin === record.origin ? existing.origin : "merged";
+    existing.fixSuggestion ??= record.fixSuggestion;
+    existing.fixKind ??= record.fixKind;
+    existing.autoFixAvailable ||= record.autoFixAvailable;
+    const seenActions = new Set(existing.actions.map((a) => `${a.kind ?? ""}|${a.title}`));
+    for (const action of record.actions) {
+      const key = `${action.kind ?? ""}|${action.title}`;
+      if (!seenActions.has(key)) {
+        existing.actions.push(action);
+        seenActions.add(key);
+      }
+    }
+  }
+  return [...byId.values()].sort((a, b) => a.displayPath.localeCompare(b.displayPath) || (a.line ?? 0) - (b.line ?? 0));
+}
+export const ACTIONABLE_WARNINGS_LSP_FILE_CAP = 25;
+export const ACTIONABLE_WARNINGS_LSP_BUDGET_MS = 2500;
+export const ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS = 60000;
+export const ACTIONABLE_WARNINGS_LSP_PULL_TIMEOUT_MS = 1e4;
+export const ACTIONABLE_WARNINGS_MAX_CODE_ACTIONS_PER_FILE = 25;
+export function _awaitDeferredLspPullForTest() {
+  return awaitDeferredLspWork();
+}
+async function boundedLspCall(call, deps) {
+  if (deps.signal?.aborted)
+    return;
+  const remainingMs = deps.deadlineAt !== undefined ? deps.deadlineAt - Date.now() : undefined;
+  if (remainingMs !== undefined && remainingMs <= 0)
+    return;
+  const inner = bounded(call().then((value) => ({ value })), {
+    ms: deps.pullTimeoutMs,
+    signal: deps.signal,
+    hook: deps.site.hook,
+    label: deps.site.label
+  });
+  const boxed = deps.deadlineAt !== undefined ? await withDeadline(inner, {
+    deadlineAt: deps.deadlineAt,
+    onTimeout: "undefined"
+  }) : await inner;
+  return boxed?.value;
+}
+function boundedNumber(value, fallback) {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+export async function buildActionableWarningsReport(args) {
+  const cwd = path.resolve(args.cwd);
+  const records = [...args.dispatchWarnings];
+  const lspService = getLSPService();
+  const observedAtByPath = new Map;
+  const buildStartedAt = new Date().toISOString();
+  logActionableWarningsEvent({
+    event: "report_started",
+    sessionId: args.sessionId,
+    metadata: {
+      turnIndex: args.turnIndex,
+      filesCount: args.files.length,
+      dispatchWarningsCount: args.dispatchWarnings.length,
+      deltaOnly: args.deltaOnly !== false,
+      includeLspCodeActions: args.includeLspCodeActions
+    }
+  });
+  if (args.includeLspCodeActions) {
+    const fileCap = Math.floor(boundedNumber(args.lspFileCap, ACTIONABLE_WARNINGS_LSP_FILE_CAP));
+    const budgetMs = boundedNumber(args.lspBudgetMs, ACTIONABLE_WARNINGS_LSP_BUDGET_MS);
+    const eligible = [];
+    let outsideRoot = 0;
+    for (const file of args.files) {
+      const filePath = path.resolve(cwd, file);
+      if (normalizeMapKey(filePath) === normalizeMapKey(cwd) || !isUnderDir(filePath, cwd)) {
+        outsideRoot++;
+        logActionableWarningsEvent({
+          event: "lsp_file_skipped",
+          sessionId: args.sessionId,
+          filePath,
+          metadata: { reason: "outside_project_root" }
+        });
+        continue;
+      }
+      if (!lspService.supportsLSP(filePath)) {
+        logActionableWarningsEvent({
+          event: "lsp_file_skipped",
+          sessionId: args.sessionId,
+          filePath,
+          metadata: { reason: "no_lsp_support" }
+        });
+        continue;
+      }
+      eligible.push(filePath);
+    }
+    if (outsideRoot > 0) {
+      args.dbg?.(`actionable_warnings: skipped ${outsideRoot} file(s) outside the project root`);
+    }
+    const capped = eligible.slice(0, fileCap);
+    if (capped.length < eligible.length) {
+      recordDegradationOnce({
+        kind: "actionable-warnings-cap",
+        subject: `${cwd}:file-cap`,
+        reason: `LSP enrichment capped at ${fileCap} file(s); ${eligible.length - capped.length} modified file(s) were not checked for code actions this turn`
+      });
+    }
+    const primed = [];
+    const cold = [];
+    for (const filePath of capped) {
+      const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : undefined;
+      const contentHash = content !== undefined ? createHash("sha256").update(content).digest("hex") : undefined;
+      const cached = contentHash !== undefined ? lspService.getLastKnownDiagnostics(filePath, contentHash) : undefined;
+      (cached !== undefined ? primed : cold).push({
+        filePath,
+        content,
+        cached
+      });
+    }
+    const deadline = Date.now() + budgetMs;
+    const exhausted = () => args.signal?.aborted === true || Date.now() >= deadline;
+    const pullTimeoutMs = boundedNumber(args.lspPullTimeoutMs, ACTIONABLE_WARNINGS_LSP_PULL_TIMEOUT_MS);
+    const inBandDeps = {
+      lspService,
+      pullTimeoutMs,
+      deadlineAt: deadline,
+      signal: args.signal,
+      site: { hook: "turn_end", label: "lspEnrichmentRoundTrip" }
+    };
+    let unchecked = 0;
+    const runInBand = async (targets) => {
+      for (const target of targets) {
+        if (exhausted()) {
+          unchecked += targets.length - targets.indexOf(target);
+          break;
+        }
+        records.push(...await enrichFileFromLsp(cwd, args, target, inBandDeps));
+        observedAtByPath.set(normalizeMapKey(target.filePath), new Date().toISOString());
+      }
+    };
+    await runInBand(primed);
+    if (cold.length > 0 && primed.length === 0) {
+      const deferredSignal = armDeferredLspWork();
+      if (deferredSignal === undefined) {
+        incrementDegradationCount({
+          kind: "actionable-warnings-cap",
+          subject: `${cwd}:deferral-declined`,
+          reason: `an earlier deferred LSP pull is still running; ${cold.length} file(s) went unchecked for code actions this turn. What IS preserved is the incumbent loop's work: when it lands, its per-file entries are merged into whatever report is persisted then, for every file whose fileSeq has not advanced. This turn's own cold files are the loss, and nothing re-derives them -- the next report is a delta over a different file set`
+        });
+        logActionableWarningsEvent({
+          event: "lsp_pull_deferral_declined",
+          sessionId: args.sessionId,
+          metadata: { turnIndex: args.turnIndex, files: cold.length }
+        });
+        args.dbg?.(`actionable_warnings: an earlier deferred LSP pull still holds the slot — skipping ${cold.length} fresh pull(s) this turn`);
+      } else {
+        const carried = [...records];
+        const deferredArgs = args;
+        const loopSignal = combineAbortSignals(args.signal, deferredSignal) ?? deferredSignal;
+        const deferredDeps = {
+          lspService,
+          pullTimeoutMs,
+          signal: loopSignal,
+          site: {
+            hook: "off_hook",
+            label: "deferredLspEnrichmentRoundTrip"
+          }
+        };
+        const deferredWork = (async () => {
+          await new Promise((resolve) => setTimeout(resolve, 0));
+          const deferredRecords = [...carried];
+          const deferredDeadline = Date.now() + ACTIONABLE_WARNINGS_DEFERRED_BUDGET_MS;
+          deferredDeps.deadlineAt = deferredDeadline;
+          let deferredUnchecked = 0;
+          let abortedMidLoop = false;
+          for (const target of cold) {
+            if (loopSignal.aborted || Date.now() >= deferredDeadline) {
+              abortedMidLoop = loopSignal.aborted;
+              deferredUnchecked += cold.length - cold.indexOf(target);
+              break;
+            }
+            deferredRecords.push(...await enrichFileFromLsp(cwd, deferredArgs, target, deferredDeps));
+            observedAtByPath.set(normalizeMapKey(target.filePath), new Date().toISOString());
+          }
+          if (deferredUnchecked > 0) {
+            recordDegradationOnce({
+              kind: "actionable-warnings-cap",
+              subject: `${cwd}:deferred-budget`,
+              reason: `deferred LSP enrichment stopped early; ${deferredUnchecked} file(s) were not checked for code actions`
+            });
+          }
+          if (abortedMidLoop || loopSignal.aborted) {
+            logActionableWarningsEvent({
+              event: "lsp_pull_aborted",
+              sessionId: deferredArgs.sessionId,
+              metadata: {
+                turnIndex: deferredArgs.turnIndex,
+                unchecked: deferredUnchecked
+              }
+            });
+            return;
+          }
+          deferredArgs.onDeferredReport?.(assembleReport(cwd, deferredArgs, deferredRecords, {
+            observedAtByPath,
+            fallbackObservedAt: buildStartedAt
+          }));
+        })().catch((err) => {
+          args.dbg?.(`actionable_warnings: deferred LSP pull failed: ${err}`);
+        });
+        registerDeferredLspWork(deferredSignal, deferredWork);
+        logActionableWarningsEvent({
+          event: "lsp_pull_deferred",
+          sessionId: args.sessionId,
+          metadata: { turnIndex: args.turnIndex, files: cold.length }
+        });
+        args.dbg?.(`actionable_warnings: no LSP cache primed this turn — deferring ${cold.length} fresh pull(s) off the turn_end hook`);
+      }
+    } else {
+      await runInBand(cold);
+    }
+    if (unchecked > 0) {
+      recordDegradationOnce({
+        kind: "actionable-warnings-cap",
+        subject: `${cwd}:wall-budget`,
+        reason: `LSP enrichment hit its ${Math.round(budgetMs)}ms turn budget; ${unchecked} file(s) were not checked for code actions this turn`
+      });
+    }
+  }
+  return assembleReport(cwd, args, records, {
+    observedAtByPath,
+    fallbackObservedAt: buildStartedAt
+  });
+}
+export async function enrichFileFromLsp(cwd, args, target, deps) {
+  const { lspService } = deps;
+  const { filePath } = target;
+  const out = [];
+  let diags;
+  let lspSource = "cache";
+  if (target.cached !== undefined) {
+    diags = target.cached;
+  } else {
+    if (deps.signal?.aborted) {
+      logActionableWarningsEvent({
+        event: "lsp_file_skipped",
+        sessionId: args.sessionId,
+        filePath,
+        metadata: { reason: "aborted" }
+      });
+      return out;
+    }
+    try {
+      if (target.content) {
+        const opened = await boundedLspCall(async () => {
+          await lspService.openFile(filePath, target.content);
+          return true;
+        }, deps);
+        if (opened === undefined) {
+          logActionableWarningsEvent({
+            event: "lsp_file_skipped",
+            sessionId: args.sessionId,
+            filePath,
+            metadata: {
+              reason: deps.signal?.aborted ? "aborted" : "open_timeout",
+              pullTimeoutMs: deps.pullTimeoutMs
+            }
+          });
+          return out;
+        }
+      }
+      const pulled = await boundedLspCall(() => lspService.getDiagnostics(filePath), deps);
+      if (pulled === undefined) {
+        logActionableWarningsEvent({
+          event: "lsp_file_skipped",
+          sessionId: args.sessionId,
+          filePath,
+          metadata: {
+            reason: deps.signal?.aborted ? "aborted" : "pull_timeout",
+            pullTimeoutMs: deps.pullTimeoutMs
+          }
+        });
+        return out;
+      }
+      diags = pulled;
+      lspSource = "fresh";
+    } catch (err) {
+      args.dbg?.(`actionable_warnings: LSP diagnostics failed for ${filePath}: ${err}`);
+      logActionableWarningsEvent({
+        event: "lsp_file_skipped",
+        sessionId: args.sessionId,
+        filePath,
+        metadata: { reason: "lsp_error", error: String(err) }
+      });
+      return out;
+    }
+  }
+  const ranges = args.modifiedRangesByFile.get(normalizeMapKey(filePath)) ?? [];
+  const diagsWarning = diags.filter((d) => d.severity === 2);
+  let deltaFiltered = 0;
+  let enriched = 0;
+  let actionPulls = 0;
+  let actionCapped = 0;
+  let budgetStopped = 0;
+  for (const diag of diagsWarning) {
+    if (deps.deadlineAt !== undefined && Date.now() >= deps.deadlineAt) {
+      budgetStopped = diagsWarning.length - diagsWarning.indexOf(diag);
+      break;
+    }
+    const line = diag.range.start.line + 1;
+    if (args.deltaOnly !== false && !lineInModifiedRanges(line, ranges)) {
+      deltaFiltered++;
+      continue;
+    }
+    if (actionPulls >= ACTIONABLE_WARNINGS_MAX_CODE_ACTIONS_PER_FILE) {
+      actionCapped++;
+      continue;
+    }
+    actionPulls++;
+    const record = recordFromLspDiagnostic(diag, filePath, cwd);
+    try {
+      const actions = await boundedLspCall(() => lspService.codeAction(filePath, diag.range.start.line, diag.range.start.character, diag.range.end.line, diag.range.end.character), deps);
+      record.actions = (actions ?? []).map(serializeAction).slice(0, 5);
+    } catch (err) {
+      args.dbg?.(`actionable_warnings: LSP codeAction failed for ${filePath}: ${err}`);
+    }
+    if (record.actions.length > 0) {
+      out.push(record);
+      enriched++;
+    }
+  }
+  if (actionCapped > 0) {
+    incrementDegradationCount({
+      kind: "actionable-warnings-cap",
+      subject: `${cwd}:code-action-fanout`,
+      reason: `a file exceeded the ${ACTIONABLE_WARNINGS_MAX_CODE_ACTIONS_PER_FILE}-warning code-action cap; ${actionCapped} warning(s) in ${toRunnerDisplayPath(cwd, filePath)} were NOT reported this turn`
+    });
+  }
+  if (budgetStopped > 0) {
+    incrementDegradationCount({
+      kind: "actionable-warnings-cap",
+      subject: `${cwd}:in-file-budget`,
+      reason: `the LSP enrichment wall budget expired part-way through a file; ${budgetStopped} warning(s) in ${toRunnerDisplayPath(cwd, filePath)} were NOT checked for fix actions`
+    });
+  }
+  logActionableWarningsEvent({
+    event: "lsp_file_checked",
+    sessionId: args.sessionId,
+    filePath,
+    metadata: {
+      diagsTotal: diags.length,
+      diagsWarning: diagsWarning.length,
+      deltaFiltered,
+      enriched,
+      actionCapped,
+      budgetStopped,
+      modifiedRangesCount: ranges.length,
+      lspSource
+    }
+  });
+  return out;
+}
+function assembleReport(cwd, args, records, stamps) {
+  const merged = mergeWarnings(records);
+  updateWarningState(cwd, merged);
+  const reportWarnings = merged.map(({ legacyId: _legacyId, ...rest }) => rest);
+  const byFile = new Map;
+  for (const warning of reportWarnings) {
+    const arr = byFile.get(warning.filePath) ?? [];
+    arr.push(warning);
+    byFile.set(warning.filePath, arr);
+  }
+  const generatedAt = new Date().toISOString();
+  const files = [...byFile.entries()].map(([filePath, warnings]) => ({
+    filePath,
+    displayPath: toRunnerDisplayPath(cwd, filePath),
+    fileSeq: args.fileSeqByPath?.get(normalizeMapKey(filePath)),
+    generatedAt: stamps?.observedAtByPath.get(normalizeMapKey(filePath)) ?? stamps?.fallbackObservedAt ?? generatedAt,
+    branchEpoch: args.branchEpoch,
+    branchScope: args.branchScope,
+    warnings
+  }));
+  const summary = summarizeReportFiles(files);
+  logActionableWarningsEvent({
+    event: "report_complete",
+    sessionId: args.sessionId,
+    metadata: { turnIndex: args.turnIndex, summary }
+  });
+  return {
+    generatedAt,
+    scope: "turn_delta",
+    sessionId: args.sessionId,
+    turnIndex: args.turnIndex,
+    projectSeqStart: args.projectSeqStart,
+    projectSeqEnd: args.projectSeqEnd,
+    deltaOnly: args.deltaOnly !== false,
+    includeLspCodeActions: args.includeLspCodeActions,
+    files,
+    summary
+  };
+}
+function summarizeReportFiles(files) {
+  const warnings = files.flatMap((file) => file.warnings);
+  const unsuppressed = warnings.filter((warning) => !warning.suppressed);
+  const allActions = warnings.flatMap((warning) => warning.actions);
+  const countTier = (tier) => unsuppressed.filter((warning) => warning.severity === tier).length;
+  return {
+    warnings: warnings.length,
+    unsuppressed: unsuppressed.length,
+    byTier: {
+      warning: countTier("warning"),
+      info: countTier("info"),
+      hint: countTier("hint")
+    },
+    suppressed: warnings.filter((warning) => warning.suppressed).length,
+    files: files.length,
+    actions: allActions.length,
+    autoFixEligible: allActions.filter((action) => action.autoFixEligible).length
+  };
+}
+function writeActionableWarningsReport(cacheManager, cwd, report) {
+  cacheManager.writeCache("actionable-warnings", report, cwd);
+}
+export function mergeActionableWarningsReports(args) {
+  const { persisted, incoming, origin } = args;
+  const deferredPublish = origin === "deferred";
+  const sessionMismatch = !deferredPublish && persisted?.sessionId !== undefined && persisted.sessionId !== incoming.sessionId;
+  const newerHalf = deferredPublish ? persisted?.files ?? [] : incoming.files;
+  const olderHalf = deferredPublish ? incoming.files : persisted?.files ?? [];
+  const newerReport = deferredPublish ? persisted : incoming;
+  const olderReport = deferredPublish ? incoming : persisted;
+  const byPath = new Map;
+  for (const entry of newerHalf) {
+    byPath.set(normalizeMapKey(entry.filePath), entry);
+  }
+  const droppedFiles = [];
+  let mergedFiles = 0;
+  for (const entry of olderHalf) {
+    if (!deferredPublish && entry.origin !== "deferred") {
+      args.dbg?.(`actionable_warnings: in-band publish dropped ${entry.displayPath || entry.filePath} -- its carry-forward window (from an earlier deferred publish) already closed`);
+      continue;
+    }
+    const key = normalizeMapKey(entry.filePath);
+    const incumbent = byPath.get(key);
+    const liveBaseline = args.getFileSeq !== undefined;
+    const baselineSeq = args.getFileSeq?.(entry.filePath) ?? incumbent?.fileSeq;
+    const stale = !deferredPublish && liveBaseline ? sessionMismatch || typeof entry.fileSeq === "number" && baselineSeq !== entry.fileSeq : typeof baselineSeq === "number" && typeof entry.fileSeq === "number" && baselineSeq > entry.fileSeq;
+    if (stale) {
+      droppedFiles.push(entry.displayPath || entry.filePath);
+      continue;
+    }
+    mergedFiles++;
+    const merged = incumbent ? incumbent.reVerified || incumbent.reVerifyIncomplete ? {
+      ...incumbent,
+      fileSeq: incumbent.fileSeq ?? entry.fileSeq,
+      generatedAt: olderStamp(incumbent.generatedAt ?? newerReport?.generatedAt, entry.generatedAt ?? olderReport?.generatedAt),
+      warnings: incumbent.warnings
+    } : {
+      ...incumbent,
+      fileSeq: incumbent.fileSeq ?? entry.fileSeq,
+      generatedAt: olderStamp(incumbent.generatedAt ?? newerReport?.generatedAt, entry.generatedAt ?? olderReport?.generatedAt),
+      branchEpoch: olderBranchEpoch(incumbent.branchEpoch, entry.branchEpoch),
+      branchScope: incumbent.branchScope === entry.branchScope ? incumbent.branchScope : undefined,
+      warnings: mergeWarnings([...incumbent.warnings, ...entry.warnings])
+    } : { ...entry };
+    if (deferredPublish) {
+      merged.origin = "deferred";
+    } else {
+      merged.origin = undefined;
+    }
+    byPath.set(key, merged);
+  }
+  const files = [...byPath.values()];
+  if (!deferredPublish) {
+    return {
+      report: { ...incoming, files, summary: summarizeReportFiles(files) },
+      mergedFiles,
+      droppedFiles,
+      droppedForSessionMismatch: sessionMismatch && droppedFiles.length > 0
+    };
+  }
+  const base = persisted ?? incoming;
+  return {
+    report: {
+      ...base,
+      generatedAt: newerStamp(persisted?.generatedAt, incoming.generatedAt) ?? base.generatedAt,
+      turnIndex: Math.max(base.turnIndex, incoming.turnIndex),
+      projectSeqStart: minDefined(persisted?.projectSeqStart, incoming.projectSeqStart),
+      projectSeqEnd: maxDefined(persisted?.projectSeqEnd, incoming.projectSeqEnd),
+      includeLspCodeActions: base.includeLspCodeActions || incoming.includeLspCodeActions,
+      files,
+      summary: summarizeReportFiles(files)
+    },
+    mergedFiles,
+    droppedFiles,
+    droppedForSessionMismatch: false
+  };
+}
+export function publishActionableWarningsReport(cacheManager, cwd, report, opts = {}) {
+  const origin = opts.origin ?? "in-band";
+  const persisted = cacheManager.readCache("actionable-warnings", cwd, Number.MAX_SAFE_INTEGER)?.data;
+  const merged = mergeActionableWarningsReports({
+    persisted,
+    incoming: report,
+    origin,
+    getFileSeq: opts.getFileSeq,
+    dbg: opts.dbg
+  });
+  writeActionableWarningsReport(cacheManager, cwd, merged.report);
+  appendActionableWarningsHistory(cwd, report);
+  if (merged.mergedFiles > 0) {
+    opts.dbg?.(`actionable_warnings: ${origin} publish merged ${merged.mergedFiles} persisted file entry/entries`);
+  }
+  if (origin === "in-band" && merged.droppedFiles.length > 0) {
+    const cause = merged.droppedForSessionMismatch ? "the publish crossed a session boundary" : "changed before this turn's in-band publish could keep them";
+    const reason = `${merged.droppedFiles.length} carried-forward entries: findings are LOST on this channel; ${cause} (files: ${merged.droppedFiles.slice(0, 3).join(", ")}${merged.droppedFiles.length > 3 ? ", ..." : ""})`;
+    incrementDegradationCount({
+      kind: "actionable-warnings-inband-superseded",
+      subject: `${path.resolve(cwd)}:inband-carry-superseded`,
+      reason
+    });
+    opts.dbg?.(`actionable_warnings: in-band publish dropped ${merged.droppedFiles.length} superseded carried-forward file entry/entries (${merged.droppedFiles.slice(0, 3).join(", ")}${merged.droppedFiles.length > 3 ? ", ..." : ""})`);
+  }
+  return merged;
+}
+function olderStamp(a, b) {
+  if (a === undefined)
+    return b;
+  if (b === undefined)
+    return a;
+  const at = Date.parse(a);
+  const bt = Date.parse(b);
+  if (!Number.isFinite(at))
+    return b;
+  if (!Number.isFinite(bt))
+    return a;
+  return at <= bt ? a : b;
+}
+function newerStamp(a, b) {
+  const older = olderStamp(a, b);
+  if (a === undefined)
+    return b;
+  if (b === undefined)
+    return a;
+  return older === a ? b : a;
+}
+function olderBranchEpoch(a, b) {
+  if (typeof a !== "number" || typeof b !== "number")
+    return;
+  return Math.min(a, b);
+}
+export function quickFixCreditEpoch(files, liveScope) {
+  let oldest;
+  for (const { branchEpoch, branchScope } of files) {
+    if (branchScope !== liveScope || !isBranchEpoch(branchEpoch))
+      return;
+    oldest = oldest === undefined ? branchEpoch : Math.min(oldest, branchEpoch);
+  }
+  return oldest;
+}
+function isBranchEpoch(value) {
+  return Number.isInteger(value) && value >= 0;
+}
+function minDefined(a, b) {
+  if (typeof a !== "number")
+    return b;
+  if (typeof b !== "number")
+    return a;
+  return Math.min(a, b);
+}
+function maxDefined(a, b) {
+  if (typeof a !== "number")
+    return b;
+  if (typeof b !== "number")
+    return a;
+  return Math.max(a, b);
+}
+export function writeDeferredActionableWarningsReport(args) {
+  const { mergedFiles, droppedFiles } = publishActionableWarningsReport(args.cacheManager, args.cwd, args.report, { origin: "deferred", getFileSeq: args.getFileSeq, dbg: args.dbg });
+  if (droppedFiles.length > 0) {
+    incrementDegradationCount({
+      kind: "actionable-warnings-deferred-superseded",
+      subject: `${path.resolve(args.cwd)}:deferred-file-superseded`,
+      reason: `${droppedFiles.length} changed file(s): warnings are LOST; unchanged files were merged into the persisted report (files: ${droppedFiles.slice(0, 3).join(", ")}${droppedFiles.length > 3 ? ", ..." : ""})`
+    });
+    args.dbg?.(`turn_end: deferred actionable-warnings dropped ${droppedFiles.length} superseded file entry/entries`);
+  }
+  args.dbg?.(`turn_end: deferred actionable-warnings merged ${mergedFiles} file entry/entries into the persisted report`);
+  return { mergedFiles, droppedFiles: droppedFiles.length };
+}
+export function getActionableWarningsHistoryPath(cwd) {
+  return path.join(getProjectDataDir(cwd), "actionable-warnings.jsonl");
+}
+export function appendActionableWarningsHistory(cwd, report) {
+  const entries = [];
+  for (const file of report.files) {
+    if (file.reVerifyIncomplete)
+      continue;
+    for (const warning of file.warnings) {
+      entries.push({
+        timestamp: report.generatedAt,
+        sessionId: report.sessionId,
+        turnIndex: report.turnIndex,
+        projectSeq: report.projectSeqEnd,
+        filePath: warning.filePath,
+        displayPath: warning.displayPath,
+        fileSeq: file.fileSeq,
+        line: warning.line,
+        column: warning.column,
+        severity: warning.severity,
+        tool: warning.tool,
+        source: warning.source,
+        rule: warning.rule,
+        code: warning.code,
+        message: warning.message,
+        fixKind: warning.fixKind,
+        autoFixAvailable: warning.autoFixAvailable,
+        actionCount: warning.actions.length,
+        autoFixEligibleActionCount: warning.actions.filter((action) => action.autoFixEligible).length,
+        suppressed: warning.suppressed,
+        suppressionReason: warning.suppressionReason,
+        origin: warning.origin,
+        warningId: warning.id
+      });
+    }
+  }
+  if (entries.length === 0)
+    return;
+  const historyPath = getActionableWarningsHistoryPath(cwd);
+  try {
+    fs.mkdirSync(path.dirname(historyPath), { recursive: true });
+    fs.appendFileSync(historyPath, `${entries.map((entry) => JSON.stringify(entry)).join(`
+`)}
+`, "utf8");
+  } catch {}
+}
+export function checkActionableWarningsReportFresh(args) {
+  const reportProjectSeqEnd = args.report.projectSeqEnd;
+  if (typeof reportProjectSeqEnd !== "number") {
+    return {
+      fresh: false,
+      reason: "missing_project_seq",
+      currentProjectSeq: args.currentProjectSeq
+    };
+  }
+  if (reportProjectSeqEnd !== args.currentProjectSeq) {
+    return {
+      fresh: false,
+      reason: "project_seq_mismatch",
+      reportProjectSeqEnd,
+      currentProjectSeq: args.currentProjectSeq
+    };
+  }
+  if (args.getFileSeq) {
+    for (const file of args.report.files) {
+      if (typeof file.fileSeq !== "number")
+        continue;
+      const currentFileSeq = args.getFileSeq(file.filePath);
+      if (currentFileSeq !== file.fileSeq) {
+        return {
+          fresh: false,
+          reason: "file_seq_mismatch",
+          reportProjectSeqEnd,
+          currentProjectSeq: args.currentProjectSeq,
+          filePath: file.filePath,
+          reportFileSeq: file.fileSeq,
+          currentFileSeq
+        };
+      }
+    }
+  }
+  return {
+    fresh: true,
+    reportProjectSeqEnd,
+    currentProjectSeq: args.currentProjectSeq
+  };
+}
+export async function applyConservativeActionableWarningFixes(args) {
+  const summary = {
+    considered: 0,
+    applied: 0,
+    changedFiles: [],
+    skipped: []
+  };
+  const changedFiles = new Set;
+  const appliedResults = [];
+  let failedCount = 0;
+  const lspService = getLSPService();
+  const maxFixes = Math.max(0, args.maxFixes ?? 5);
+  for (const file of args.report.files) {
+    if (summary.applied >= maxFixes)
+      break;
+    for (const warning of file.warnings) {
+      if (summary.applied >= maxFixes)
+        break;
+      if (warning.suppressed)
+        continue;
+      const eligibleActions = warning.actions.filter((action) => action.autoFixEligible);
+      if (eligibleActions.length !== 1) {
+        if (eligibleActions.length > 1)
+          summary.skipped.push({
+            id: warning.id,
+            reason: "multiple_eligible_actions"
+          });
+        continue;
+      }
+      summary.considered++;
+      const agreement = establishToolAgreement(warning.tool, args.cwd);
+      if (agreement.decision === "decline") {
+        recordDegradationOnce({
+          kind: "autofix-agreement-unavailable",
+          subject: agreement.subject,
+          reason: agreement.reason
+        });
+        summary.skipped.push({
+          id: warning.id,
+          reason: "tool_agreement_unavailable"
+        });
+        continue;
+      }
+      if (!warning.line || !warning.column) {
+        summary.skipped.push({ id: warning.id, reason: "missing_position" });
+        continue;
+      }
+      if (!lspService.supportsLSP(warning.filePath)) {
+        summary.skipped.push({ id: warning.id, reason: "no_lsp" });
+        continue;
+      }
+      try {
+        const content = fs.existsSync(warning.filePath) ? fs.readFileSync(warning.filePath, "utf-8") : undefined;
+        if (content)
+          await lspService.openFile(warning.filePath, content);
+        const line = warning.line - 1;
+        const character = warning.column - 1;
+        const actions = await lspService.codeAction(warning.filePath, line, character, line, character);
+        const title = eligibleActions[0]?.title;
+        const selected = actions.find((action) => action.title === title);
+        if (!selected) {
+          summary.skipped.push({ id: warning.id, reason: "action_not_found" });
+          continue;
+        }
+        const safety = actionSafety(selected);
+        if (!safety.eligible) {
+          summary.skipped.push({
+            id: warning.id,
+            reason: safety.reason ?? "not_safe"
+          });
+          continue;
+        }
+        if (args.mutationContext?.session && args.mutationContext.session.guardedWrite(warning.filePath, () => true) === undefined) {
+          summary.skipped.push({ id: warning.id, reason: "session_replaced" });
+          continue;
+        }
+        const edit = selected.edit;
+        if (edit.documentChanges?.some((change) => typeof change === "object" && change !== null && ("kind" in change))) {
+          summary.skipped.push({
+            id: warning.id,
+            reason: "resource_operation"
+          });
+          continue;
+        }
+        const target = fs.realpathSync.native(warning.filePath);
+        const writesOtherFile = workspaceEditDiskPaths(edit).some((diskPath) => fs.realpathSync.native(diskPath) !== target);
+        if (writesOtherFile) {
+          summary.skipped.push({ id: warning.id, reason: "multi_file_edit" });
+          continue;
+        }
+        const applied = await applyWorkspaceEdit(edit, args.cwd, {
+          expectedContent: new Map([[target, content ?? ""]]),
+          ...args.mutationContext ? {
+            mutationContext: {
+              ...args.mutationContext,
+              emitSummary: false
+            }
+          } : {}
+        });
+        appliedResults.push(applied);
+        for (const changedFile of applied.files)
+          changedFiles.add(changedFile);
+        summary.applied++;
+      } catch (err) {
+        if (err instanceof StaleWorkspaceEditContentError) {
+          summary.skipped.push({ id: warning.id, reason: "stale_content" });
+          continue;
+        }
+        failedCount++;
+        const partial = err.appliedWorkspaceEdit;
+        if (partial) {
+          appliedResults.push(partial);
+          for (const changedFile of partial.files)
+            changedFiles.add(changedFile);
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        args.dbg?.(`actionable_warnings_autofix failed for ${warning.id}: ${message}`);
+        summary.skipped.push({ id: warning.id, reason: "apply_failed" });
+      }
+    }
+  }
+  summary.changedFiles = [...changedFiles];
+  if (args.mutationContext && (summary.considered > 0 || appliedResults.length > 0)) {
+    recordLspMutationBatch(args.mutationContext, {
+      results: appliedResults,
+      considered: summary.considered,
+      completed: summary.applied,
+      failedCount,
+      status: failedCount > 0 ? "failed" : appliedResults.length > 0 ? "success" : "skipped",
+      bookkeep: false
+    });
+  }
+  return summary;
+}
+export function formatActionableWarningsAdvisory(report, cwd, host = "pi", filterBuiltReport) {
+  const filtered = filterBuiltReport?.(report);
+  const advisoryReport = filtered ? {
+    ...report,
+    files: filtered.files,
+    summary: summarizeReportFiles(filtered.files)
+  } : report;
+  if (advisoryReport.summary.unsuppressed === 0)
+    return;
+  const files = advisoryReport.files.filter((file) => file.warnings.some((warning) => !warning.suppressed));
+  const fileList = files.slice(0, 5).map((file) => `  ${file.displayPath}: ${file.warnings.filter((warning) => !warning.suppressed).length}${file.reVerifyIncomplete ? " (re-verify incomplete)" : ""}`).join(`
+`);
+  const more = files.length > 5 ? `
+  ... and ${files.length - 5} more file(s)` : "";
+  const safe = advisoryReport.summary.autoFixEligible > 0 ? ` ${advisoryReport.summary.autoFixEligible} appear to have conservative preferred quickfixes.` : "";
+  const byTier = advisoryReport.summary.byTier;
+  const quiet = byTier ? byTier.hint + byTier.info : 0;
+  const tierLine = quiet > 0 ? `${quiet} of those are hint/info tier — style opinions, worth fixing only while you are already in that code.` : undefined;
+  const reportPath = displayProjectDataPath(cwd, "cache", "actionable-warnings.json");
+  const diagnosticsTool = resolveLensToolName("lens_diagnostics", host);
+  return [
+    `\uD83D\uDFE1 Fixable warnings introduced this turn: ${advisoryReport.summary.unsuppressed}.${safe}`,
+    filtered && filtered.suppressed > 0 ? `suppressed by disposition: ${filtered.suppressed} finding(s).` : undefined,
+    tierLine,
+    diagnosticsTool ? `Use ${diagnosticsTool} with mode=delta to inspect these warnings.` : undefined,
+    fileList ? `Files:
+${fileList}${more}` : undefined,
+    "If continuing in these files, resolve warnings that are safe and relevant. Do not apply broad refactors unless requested.",
+    `Raw report (only if you need the JSON): ${reportPath}`
+  ].filter(Boolean).join(`
+`);
+}