@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.1

package/node_modules/@mrclrchtr/supi-lsp/src/config/tsconfig-extends.ts

@@ -0,0 +1,68 @@
+import * as path from "node:path";
+import ts from "typescript";
+import { normalizeTsconfigPath as normalizePath } from "./tsconfig-path.ts";
+
+/**
+ * Collect recognized local project configs declared by `extends`, including
+ * transitive dependencies and paths that do not exist yet.
+ */
+export function collectExtendedProjectConfigs(configPath: string): Set<string> {
+  const dependencies = new Set<string>();
+  const visited = new Set<string>();
+
+  const visit = (currentConfigPath: string): void => {
+    const normalizedConfigPath = normalizePath(currentConfigPath);
+    if (visited.has(normalizedConfigPath)) return;
+    visited.add(normalizedConfigPath);
+
+    const config = ts.readConfigFile(currentConfigPath, ts.sys.readFile).config;
+    if (!config || typeof config !== "object") return;
+
+    const extendsValues =
+      typeof config.extends === "string"
+        ? [config.extends]
+        : Array.isArray(config.extends)
+          ? config.extends.filter((value: unknown): value is string => typeof value === "string")
+          : [];
+
+    for (const extendsValue of extendsValues) {
+      const extendedConfigPath = resolveLocalExtendedConfigPath(currentConfigPath, extendsValue);
+      if (!extendedConfigPath) continue;
+
+      const normalizedExtendedConfigPath = normalizePath(extendedConfigPath);
+      dependencies.add(normalizedExtendedConfigPath);
+      visit(extendedConfigPath);
+    }
+  };
+
+  visit(configPath);
+  return dependencies;
+}
+
+/**
+ * Resolve a local project-config extends entry.
+ *
+ * Package names are not local paths and are deliberately ignored. TypeScript
+ * uses the `.json` suffix for extensionless local config references. Only
+ * recognized project-config names are tracked; arbitrary local JSON files may
+ * still be parsed by TypeScript but are outside this invalidation contract.
+ */
+function resolveLocalExtendedConfigPath(configPath: string, extendsValue: string): string | null {
+  if (!path.isAbsolute(extendsValue) && !/^\.{1,2}(?:[\\/]|$)/.test(extendsValue)) {
+    return null;
+  }
+
+  const resolved = path.resolve(path.dirname(configPath), extendsValue);
+  const candidate =
+    path.extname(resolved).toLowerCase() === ".json" ? resolved : `${resolved}.json`;
+  return isProjectConfigFileName(path.basename(candidate)) ? candidate : null;
+}
+
+/** Whether a file name is a tsconfig.json, jsconfig.json, or tsconfig.*.json name. */
+export function isProjectConfigFileName(name: string): boolean {
+  return (
+    name === "tsconfig.json" ||
+    name === "jsconfig.json" ||
+    (name.startsWith("tsconfig.") && name.endsWith(".json"))
+  );
+}

package/node_modules/@mrclrchtr/supi-lsp/src/config/tsconfig-path.ts

@@ -0,0 +1,8 @@
+import * as path from "node:path";
+import ts from "typescript";
+
+/** Normalize a path for tsconfig cache keys and comparisons. */
+export function normalizeTsconfigPath(target: string): string {
+  const resolved = path.resolve(target).replaceAll("\\", "/");
+  return ts.sys.useCaseSensitiveFileNames ? resolved : resolved.toLowerCase();
+}

package/node_modules/@mrclrchtr/supi-lsp/src/config/tsconfig-scope.ts

@@ -7,6 +7,10 @@
 
 import * as path from "node:path";
 import ts from "typescript";
+import { collectExtendedProjectConfigs } from "./tsconfig-extends.ts";
+import { normalizeTsconfigPath as normalizePath } from "./tsconfig-path.ts";
+
+export { isProjectConfigFileName } from "./tsconfig-extends.ts";
 
 interface ParsedProjectConfig {
   configPath: string;
@@ -19,8 +23,39 @@ interface ParsedProjectConfig {
   usesDefaultInclude: boolean;
 }
 
+interface ParsedProjectConfigCacheEntry {
+  parsed: ParsedProjectConfig | null;
+  dependencies: Set<string>;
+}
+
+/** Whether a file is inside the compilation scope of its nearest project config. */
+export type FileScopeStatus = "included" | "excluded" | "no-config" | "out-of-tree";
+
+/**
+ * The mechanism that produced a file scope decision.
+ *
+ * `extension` covers unsupported file extensions (checked before any pattern).
+ */
+export type ScopeDecisionBasis =
+  | "fileNames"
+  | "explicit"
+  | "include-pattern"
+  | "default-include"
+  | "exclude-pattern"
+  | "extension";
+
+/** An explainable tsconfig scope decision for one file. */
+export interface FileScopeDecision {
+  status: FileScopeStatus;
+  /** Decision mechanism; null when no decision applies (no-config, out-of-tree). */
+  basis: ScopeDecisionBasis | null;
+  /** Absolute path of the config that decided the file, when one exists. */
+  configPath: string | null;
+  caseSensitiveFileNames: boolean;
+}
+
 const nearestConfigCache = new Map<string, string | null>();
-const parsedConfigCache = new Map<string, ParsedProjectConfig | null>();
+const parsedConfigCache = new Map<string, ParsedProjectConfigCacheEntry>();
 
 const tsInternal = ts as typeof ts & {
   getFileMatcherPatterns?: (
@@ -47,14 +82,63 @@ const tsInternal = ts as typeof ts & {
  * @returns `true` if the file is excluded from compilation scope
  */
 export function isFileExcludedByTsconfig(filePath: string, cwd: string): boolean {
+  // Legacy filter semantics: only a resolved "excluded" decision filters a
+  // file. Out-of-tree and no-config files stay unfiltered; the decision API
+  // still reports those statuses honestly for consumers that want them.
+  return getFileScopeDecision(filePath, cwd).status === "excluded";
+}
+
+/**
+ * Compute the explainable tsconfig scope decision for one file.
+ *
+ * The decision carries the mechanism that produced it (the scope decision
+ * basis) so consumers can report why a file is inside or outside the nearest
+ * project config without re-deriving the scope logic.
+ */
+export function getFileScopeDecision(filePath: string, cwd: string): FileScopeDecision {
+  const caseSensitiveFileNames = ts.sys.useCaseSensitiveFileNames;
   const absolutePath = path.resolve(cwd, filePath);
+  if (isOutOfTree(cwd, absolutePath)) {
+    return {
+      status: "out-of-tree",
+      basis: null,
+      configPath: null,
+      caseSensitiveFileNames,
+    };
+  }
+
   const configPath = findNearestProjectConfig(path.dirname(absolutePath), cwd);
-  if (!configPath) return false;
+  if (!configPath) {
+    return {
+      status: "no-config",
+      basis: null,
+      configPath: null,
+      caseSensitiveFileNames,
+    };
+  }
 
   const parsed = parseProjectConfig(configPath);
-  if (!parsed) return false;
+  if (!parsed) {
+    return {
+      status: "no-config",
+      basis: null,
+      configPath,
+      caseSensitiveFileNames,
+    };
+  }
 
-  return !isFileInProjectScope(parsed, absolutePath);
+  const decision = decideFileScope(parsed, absolutePath);
+  return {
+    status: decision.included ? "included" : "excluded",
+    basis: decision.basis,
+    configPath: parsed.configPath,
+    caseSensitiveFileNames,
+  };
+}
+
+function isOutOfTree(cwd: string, absolutePath: string): boolean {
+  const relative = path.relative(path.resolve(cwd), absolutePath);
+  return relative.startsWith(`..${path.sep}`) || relative === "..";
 }
 
 /**
@@ -104,11 +188,15 @@ function getLocalProjectConfig(directory: string): string | null {
 function parseProjectConfig(configPath: string): ParsedProjectConfig | null {
   const normalizedConfigPath = normalizePath(configPath);
   const cached = parsedConfigCache.get(normalizedConfigPath);
-  if (cached !== undefined) return cached;
+  if (cached !== undefined) return cached.parsed;
 
+  const cacheEntry: ParsedProjectConfigCacheEntry = {
+    parsed: null,
+    dependencies: collectExtendedProjectConfigs(configPath),
+  };
   const parsed = ts.getParsedCommandLineOfConfigFile(configPath, {}, createParseConfigHost());
   if (!parsed) {
-    parsedConfigCache.set(normalizedConfigPath, null);
+    parsedConfigCache.set(normalizedConfigPath, cacheEntry);
     return null;
   }
 
@@ -119,7 +207,10 @@ function parseProjectConfig(configPath: string): ParsedProjectConfig | null {
     configDir,
     parsed.raw.include,
     parsed.raw.exclude,
-    usesDefaultInclude,
+    {
+      useDefaultInclude: usesDefaultInclude,
+      useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+    },
   );
   const supportedExtensions = new Set(getSupportedExtensions(parsed.options));
   if (parsed.options.resolveJsonModule) supportedExtensions.add(".json");
@@ -134,7 +225,8 @@ function parseProjectConfig(configPath: string): ParsedProjectConfig | null {
     supportedExtensions,
     usesDefaultInclude,
   } satisfies ParsedProjectConfig;
-  parsedConfigCache.set(normalizedConfigPath, result);
+  cacheEntry.parsed = result;
+  parsedConfigCache.set(normalizedConfigPath, cacheEntry);
   return result;
 }
 
@@ -147,15 +239,21 @@ function extractExplicitFiles(rawFiles: unknown, configDir: string): Set<string>
   );
 }
 
+interface FileMatcherOptions {
+  useDefaultInclude: boolean;
+  useCaseSensitiveFileNames: boolean;
+}
+
 function createFileMatchers(
   configDir: string,
   rawInclude: unknown,
   rawExclude: unknown,
-  useDefaultInclude: boolean,
+  options: FileMatcherOptions,
 ): {
   includeFilePattern: RegExp | null;
   excludePattern: RegExp | null;
 } {
+  const { useDefaultInclude, useCaseSensitiveFileNames } = options;
   const includeSpecs = Array.isArray(rawInclude)
     ? rawInclude.filter((entry): entry is string => typeof entry === "string")
     : undefined;
@@ -167,29 +265,45 @@ function createFileMatchers(
     excludeSpecs,
     useDefaultInclude ? ["**/*"] : includeSpecs,
   );
+  // normalizePath() lowercases paths when the filesystem is case-insensitive,
+  // so the include/exclude regexes must match case-insensitively too. Otherwise
+  // files created after the parse (absent from fileNames, tested against the
+  // include pattern) are wrongly declared excluded.
+  const regexFlags = useCaseSensitiveFileNames ? undefined : "i";
 
   return {
     includeFilePattern: matcherPatterns.includeFilePattern
-      ? new RegExp(matcherPatterns.includeFilePattern)
+      ? new RegExp(matcherPatterns.includeFilePattern, regexFlags)
       : null,
     excludePattern: matcherPatterns.excludePattern
-      ? new RegExp(matcherPatterns.excludePattern)
+      ? new RegExp(matcherPatterns.excludePattern, regexFlags)
       : null,
   };
 }
 
-function isFileInProjectScope(parsed: ParsedProjectConfig, absolutePath: string): boolean {
+function decideFileScope(
+  parsed: ParsedProjectConfig,
+  absolutePath: string,
+): { included: boolean; basis: ScopeDecisionBasis } {
   const normalizedPath = normalizePath(absolutePath);
-  if (parsed.fileNames.has(normalizedPath)) return true;
+  if (parsed.fileNames.has(normalizedPath)) return { included: true, basis: "fileNames" };
 
   const extension = path.extname(absolutePath).toLowerCase();
-  if (!parsed.supportedExtensions.has(extension)) return false;
+  if (!parsed.supportedExtensions.has(extension)) return { included: false, basis: "extension" };
 
-  if (parsed.explicitFiles) return parsed.explicitFiles.has(normalizedPath);
-  if (!isWithinOrEqual(parsed.configDir, absolutePath)) return false;
-  if (parsed.excludePattern?.test(normalizedPath)) return false;
-  if (parsed.usesDefaultInclude) return true;
-  return parsed.includeFilePattern ? parsed.includeFilePattern.test(normalizedPath) : false;
+  if (parsed.explicitFiles) {
+    return { included: parsed.explicitFiles.has(normalizedPath), basis: "explicit" };
+  }
+  // Include patterns are rooted at the config directory; a file outside it can
+  // only be in scope through the parse-time file set or an explicit files list.
+  if (!isWithinOrEqual(parsed.configDir, absolutePath)) {
+    return { included: false, basis: "include-pattern" };
+  }
+  if (parsed.excludePattern?.test(normalizedPath))
+    return { included: false, basis: "exclude-pattern" };
+  if (parsed.usesDefaultInclude) return { included: true, basis: "default-include" };
+  if (!parsed.includeFilePattern) return { included: false, basis: "include-pattern" };
+  return { included: parsed.includeFilePattern.test(normalizedPath), basis: "include-pattern" };
 }
 
 function getSupportedExtensions(options: ts.CompilerOptions): string[] {
@@ -229,11 +343,6 @@ function isWithinOrEqual(root: string, target: string): boolean {
   return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
 }
 
-function normalizePath(target: string): string {
-  const resolved = path.resolve(target).replaceAll("\\", "/");
-  return ts.sys.useCaseSensitiveFileNames ? resolved : resolved.toLowerCase();
-}
-
 /**
  * Clear cached nearest-config lookups and parsed project config state.
  * Useful for testing and after workspace file changes.
@@ -242,3 +351,46 @@ export function clearTsconfigCache(): void {
   nearestConfigCache.clear();
   parsedConfigCache.clear();
 }
+
+/**
+ * Invalidate cached state for one config file that changed, was created, or
+ * was deleted.
+ *
+ * Removes the changed config and every cached root config that depends on it,
+ * so the next decision re-reads current config data. The wholesale
+ * {@link clearTsconfigCache} stays for lifecycle events; change signals use
+ * this targeted invalidation instead.
+ */
+export function invalidateTsconfigCacheForConfig(configPath: string): void {
+  const normalizedConfigPath = normalizePath(configPath);
+  const invalidated = new Set([normalizedConfigPath]);
+
+  for (const [cachedConfigPath, cacheEntry] of parsedConfigCache) {
+    if (cacheEntry.dependencies.has(normalizedConfigPath)) invalidated.add(cachedConfigPath);
+  }
+
+  for (const cachedConfigPath of invalidated) {
+    parsedConfigCache.delete(cachedConfigPath);
+  }
+
+  for (const [key, value] of nearestConfigCache) {
+    if (value !== null && invalidated.has(normalizePath(value))) nearestConfigCache.delete(key);
+  }
+}
+
+/**
+ * Invalidate nearest-config lookups that found nothing under `dir`.
+ *
+ * Used when a config is created: directories below the new config that
+ * previously resolved to no config may now resolve to it.
+ */
+export function invalidateTsconfigCacheForConfigDir(dir: string): void {
+  const normalizedDir = normalizePath(dir);
+  for (const [key, value] of nearestConfigCache) {
+    if (value !== null) continue;
+    const keyDir = key.split("::", 1)[0];
+    if (keyDir === normalizedDir || keyDir.startsWith(`${normalizedDir}/`)) {
+      nearestConfigCache.delete(key);
+    }
+  }
+}

package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/evidence.ts

@@ -1,3 +1,7 @@
+/** Reason for a partial or unavailable single-file result when the push stays tentative. */
+export const TENTATIVE_PUSH_UNAVAILABLE_REASON =
+  "The current push publication is tentative: a later diagnostic republish for the same document synchronization is required.";
+
 /** A final evidence state for one tracked document. */
 export type DiagnosticEvidenceStatus = "confirmed" | "unconfirmed" | "failed" | "removed";
 

package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/workspace-sentinels.ts

@@ -1,20 +1,32 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { FileChangeType, type FileEvent } from "../config/types.ts";
-import { fileToUri } from "../utils.ts";
+import { fileToUri, uriToFile } from "../utils.ts";
 
 const IGNORED_DIRECTORIES = new Set(["node_modules", ".pnpm", ".git", "dist", "coverage"]);
 const ROOT_LOCKFILES = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"];
 
+export interface WorkspaceSentinelScanOptions {
+  /**
+   * Also track every regular source file (not just sentinels). The workspace
+   * refresh path uses this to discover files created since the last refresh;
+   * the diff then reports them as `sourceChanges` so the caller can pull them.
+   */
+  includeSourceFiles?: boolean;
+}
+
 /** Build a fresh snapshot of workspace sentinel files and their mtimes. */
-export function scanWorkspaceSentinels(cwd: string): Map<string, number> {
+export function scanWorkspaceSentinels(
+  cwd: string,
+  options: WorkspaceSentinelScanOptions = {},
+): Map<string, number> {
   const resolvedCwd = path.resolve(cwd);
   const snapshot = new Map<string, number>();
 
   if (!fs.existsSync(resolvedCwd)) return snapshot;
 
   try {
-    walkWorkspace(resolvedCwd, resolvedCwd, snapshot);
+    walkWorkspace(resolvedCwd, resolvedCwd, snapshot, options.includeSourceFiles ?? false);
   } catch {
     return snapshot;
   }
@@ -48,15 +60,34 @@ export function diffWorkspaceSentinelSnapshot(
   return changes.sort((a, b) => a.uri.localeCompare(b.uri));
 }
 
-/** Refresh a previous snapshot and return the new snapshot plus change events. */
+/**
+ * Refresh a previous snapshot and return the new snapshot plus change events.
+ *
+ * When `includeSourceFiles` is set, the returned `changes` list keeps
+ * sentinel-file events only; source-file events are returned separately in
+ * `sourceChanges` so the caller can act on them without interpreting every
+ * regular file edit as a config-level workspace change.
+ */
 export function syncWorkspaceSentinelSnapshot(
   cwd: string,
   previous: Map<string, number>,
-): { snapshot: Map<string, number>; changes: FileEvent[] } {
-  const snapshot = scanWorkspaceSentinels(cwd);
+  options: WorkspaceSentinelScanOptions = {},
+): { snapshot: Map<string, number>; changes: FileEvent[]; sourceChanges: FileEvent[] } {
+  const snapshot = scanWorkspaceSentinels(cwd, options);
+  const changes = diffWorkspaceSentinelSnapshot(previous, snapshot);
+  if (!options.includeSourceFiles) return { snapshot, changes, sourceChanges: [] };
+
+  const sourceChanges = changes.filter((change) => {
+    const filePath = uriToFile(change.uri);
+    return !isWorkspaceSentinelPath(filePath, cwd);
+  });
   return {
     snapshot,
-    changes: diffWorkspaceSentinelSnapshot(previous, snapshot),
+    changes: changes.filter((change) => {
+      const filePath = uriToFile(change.uri);
+      return isWorkspaceSentinelPath(filePath, cwd);
+    }),
+    sourceChanges,
   };
 }
 
@@ -66,7 +97,12 @@ export function isWorkspaceRecoveryTrigger(filePath: string, cwd: string): boole
   return isWorkspaceSentinelPath(path.resolve(root, filePath), root);
 }
 
-function walkWorkspace(root: string, directory: string, snapshot: Map<string, number>): void {
+function walkWorkspace(
+  root: string,
+  directory: string,
+  snapshot: Map<string, number>,
+  includeSourceFiles: boolean,
+): void {
   let entries: fs.Dirent[];
   try {
     entries = fs.readdirSync(directory, { withFileTypes: true });
@@ -80,14 +116,14 @@ function walkWorkspace(root: string, directory: string, snapshot: Map<string, nu
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (IGNORED_DIRECTORIES.has(entry.name)) continue;
-      walkWorkspace(root, path.join(directory, entry.name), snapshot);
+      walkWorkspace(root, path.join(directory, entry.name), snapshot, includeSourceFiles);
       continue;
     }
 
     if (!entry.isFile()) continue;
 
     const filePath = path.join(directory, entry.name);
-    if (!isWorkspaceSentinelPath(filePath, root)) continue;
+    if (!includeSourceFiles && !isWorkspaceSentinelPath(filePath, root)) continue;
     try {
       snapshot.set(filePath, fs.statSync(filePath).mtimeMs);
     } catch {

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-diagnostics.ts

@@ -5,6 +5,7 @@ import {
   mapCodeQueryResult,
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { LspClient } from "../client/client.ts";
+import type { DiagnosticEntry } from "../client/client-document-state.ts";
 import type { Diagnostic } from "../config/types.ts";
 import { relativeFilePathFromUri } from "../diagnostics/diagnostic-summary.ts";
 import { shouldIgnoreLspPath } from "../summary.ts";
@@ -27,15 +28,15 @@ export async function syncClientFileAndGetDiagnostics(
 }
 
 export function collectOutstandingDiagnosticsDetailed(
-  clients: Iterable<Pick<LspClient, "getAllDiagnostics">>,
+  clientEntries: Iterable<ReadonlyArray<DiagnosticEntry>>,
   cwd: string,
   excludePatterns: string[],
   maxSeverity: number,
 ): Array<{ file: string; diagnostics: Diagnostic[] }> {
   const fileDiags = new Map<string, Diagnostic[]>();
 
-  for (const client of clients) {
-    for (const entry of client.getAllDiagnostics()) {
+  for (const entries of clientEntries) {
+    for (const entry of entries) {
       const file = relativeFilePathFromUri(entry.uri, cwd);
       if (shouldIgnoreLspPath(file, cwd)) continue;
       if (isExcludedByPattern(file, excludePatterns)) continue;

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-recovery.ts

@@ -10,13 +10,13 @@ import type { Diagnostic, FileEvent } from "../config/types.ts";
 import {
   type DiagnosticEvidenceDocument,
   type DiagnosticEvidenceSummary,
-  emptyDiagnosticEvidence,
   summarizeDiagnosticEvidence,
 } from "../diagnostics/evidence.ts";
 import {
   assessStaleDiagnostics,
   type StaleDiagnosticAssessment,
 } from "../diagnostics/stale-diagnostics.ts";
+import type { WorkspaceDiagnosticReport } from "../session/runtime-diagnostics.ts";
 
 export interface WorkspaceRecoveryResult {
   /** Active clients targeted by the best-effort refresh, not confirmed successful refreshes. */
@@ -28,8 +28,10 @@ export interface WorkspaceRecoveryResult {
   restartedServers: string[];
   /** Stall signal of the first restarted route, when this pass restarted a client. */
   restartReason?: RecoveryRestartReason;
-  /** Final document-level evidence from the last refresh in this recovery pass. */
+  /** Final document-level evidence from this pass, starting from the caller's initial evidence when one was supplied. */
   diagnosticEvidence: DiagnosticEvidenceSummary;
+  /** Final diagnostic report captured after all refresh and recovery work. */
+  diagnosticReport: WorkspaceDiagnosticReport;
   /** Failure from the first refresh, when no later pass replaced it. */
   refreshFailureReason?: string;
   /** Wall-clock duration of the whole recovery pass, for telemetry. */
@@ -62,6 +64,7 @@ export interface WorkspaceRecoveryHost {
   isDiagnosticFile(filePath: string): boolean;
   getClientDiagnosticRoutes(): WorkspaceDiagnosticRoute[];
   getDiagnosticEvidence(): DiagnosticEvidenceSummary;
+  getWorkspaceDiagnosticReport(maxSeverity?: number): WorkspaceDiagnosticReport;
   getCwd(): string;
   restartClientsForFiles(
     filePaths: string[],
@@ -82,6 +85,13 @@ export function softRecoverWorkspaceDiagnostics(
 /**
  * Run a recovery pass, refreshing diagnostics and escalating if stale state remains.
  *
+ * When the caller already ran a refresh this pass, it can hand its evidence in
+ * `initialEvidence`; the recovery pass then skips its own initial refresh and
+ * still runs stale assessment and restart escalation on the current state.
+ * Caller evidence is only reused when the pass applies no watched-file changes:
+ * evidence captured before a change would otherwise be reported as current
+ * after it.
+ *
  * The pass observes request cancellation between its phases and propagates
  * the interruption as a rejection instead of swallowing it. A pass that
  * starts already cancelled rejects before any client or evidence work.
@@ -93,6 +103,8 @@ export async function recoverWorkspaceDiagnostics(
     restartIfStillStale?: boolean;
     maxWaitMs?: number;
     quietMs?: number;
+    /** Evidence from a refresh the caller already completed; skips this pass's own refresh when no watched-file changes apply. */
+    initialEvidence?: DiagnosticEvidenceSummary;
     control?: CodeRequestControl;
   } = {},
 ): Promise<WorkspaceRecoveryResult> {
@@ -100,22 +112,11 @@ export async function recoverWorkspaceDiagnostics(
   // evidence work may start for a pass the caller no longer awaits.
   throwIfCodeRequestInterrupted(options.control);
   const recoveryStartedAt = Date.now();
-  const attemptedClients = softRecoverWorkspaceDiagnostics(host, options.changes ?? []);
+  const initial = await collectInitialEvidence(host, options);
+  const attemptedClients = initial.attemptedClients;
   const attemptedServers = host.getRunningClientNames();
-  let diagnosticEvidence = emptyDiagnosticEvidence();
-  let refreshFailureReason: string | undefined;
-
-  try {
-    diagnosticEvidence = await host.refreshOpenDiagnostics({
-      maxWaitMs: options.maxWaitMs,
-      quietMs: options.quietMs,
-      ...options.control,
-    });
-  } catch (error) {
-    if (isCodeRequestInterruption(error, options.control)) throw error;
-    refreshFailureReason = errorMessage(error);
-    diagnosticEvidence = host.getDiagnosticEvidence();
-  }
+  let diagnosticEvidence = initial.diagnosticEvidence;
+  let refreshFailureReason = initial.refreshFailureReason;
 
   let staleAssessment = assessStaleDiagnostics(host.getOutstandingDiagnostics(1));
   let restartedClients = 0;
@@ -148,6 +149,7 @@ export async function recoverWorkspaceDiagnostics(
   // refresh-only pass must not report a clean result after the caller
   // cancelled the request.
   throwIfCodeRequestInterrupted(options.control);
+  const diagnosticReport = host.getWorkspaceDiagnosticReport(2);
 
   return recoveryResult();
 
@@ -159,6 +161,7 @@ export async function recoverWorkspaceDiagnostics(
       restartedServers: restartServerNames,
       ...(restartReason ? { restartReason } : {}),
       diagnosticEvidence,
+      diagnosticReport,
       ...(refreshFailureReason ? { refreshFailureReason } : {}),
       elapsedMs: Date.now() - recoveryStartedAt,
       staleAssessment,
@@ -173,6 +176,51 @@ interface RecoveryRestartTarget {
   files: string[];
 }
 
+/** Establish the pass's starting evidence: caller-supplied reuse or a fresh refresh. */
+async function collectInitialEvidence(
+  host: WorkspaceRecoveryHost,
+  options: {
+    changes?: FileEvent[];
+    initialEvidence?: DiagnosticEvidenceSummary;
+    maxWaitMs?: number;
+    quietMs?: number;
+    control?: CodeRequestControl;
+  },
+): Promise<{
+  attemptedClients: number;
+  diagnosticEvidence: DiagnosticEvidenceSummary;
+  refreshFailureReason?: string;
+}> {
+  const changes = options.changes ?? [];
+  if (options.initialEvidence !== undefined && changes.length === 0) {
+    // Reuse skips the soft invalidation: the caller already refreshed this
+    // pass, and clearing cached pull result IDs without a refresh only forces
+    // a full pull on a later pass.
+    return {
+      attemptedClients: host.getRunningClientCount(),
+      diagnosticEvidence: options.initialEvidence,
+    };
+  }
+  const attemptedClients = softRecoverWorkspaceDiagnostics(host, changes);
+  try {
+    return {
+      attemptedClients,
+      diagnosticEvidence: await host.refreshOpenDiagnostics({
+        maxWaitMs: options.maxWaitMs,
+        quietMs: options.quietMs,
+        ...options.control,
+      }),
+    };
+  } catch (error) {
+    if (isCodeRequestInterruption(error, options.control)) throw error;
+    return {
+      attemptedClients,
+      diagnosticEvidence: host.getDiagnosticEvidence(),
+      refreshFailureReason: errorMessage(error),
+    };
+  }
+}
+
 /**
  * Collect restart targets: push-only routes with a protocol-stall signal.
  *