@mrclrchtr/supi-code-intelligence 6.4.0 → 7.0.0

package/src/tool/code_health/guidance.ts

@@ -1,8 +1,6 @@
 export const toolDescription =
-  "Report live diagnostics and language-server health. Diagnostic snapshots do not prove that the whole workspace is clean; server inventory and route-status counts are always workspace-wide.";
+  "Report live diagnostics and language-server health. Use refresh:true when you need fresh diagnostic evidence; without it, diagnostics may be a tracked-file snapshot. Diagnostic snapshots do not prove that the whole workspace is clean; server inventory and route-status counts are always workspace-wide.";
 
 export const promptSnippet = "check live diagnostics and language-server health";
 
-export const promptGuidelines = [
-  "Use code_health with `refresh: true` before relying on diagnostics that can be stale.",
-];
+export const promptGuidelines: string[] = [];

package/src/tool/code_health/markdown.ts

@@ -1,10 +1,4 @@
-/**
- * Markdown renderer for code_health results.
- *
- * Renders structured health data from the code_health executor into
- * readable markdown sections keyed by requested `include` values.
- */
-
+/** Markdown renderer for code_health results. */
 import type { CapabilityWarningReport } from "../../analysis/capability/capability-warnings.ts";
 import {
   formatProjectServerRoot,
@@ -16,7 +10,9 @@ import {
   formatProcessCrashRecovery,
   formatRefreshElapsed,
   formatSourceTracking,
+  formatSourceTrackingDetails,
   formatStaleDiagnosticRestarts as formatStaleDiagnosticRestartsText,
+  formatStartupRetry,
   isFileReadinessPending,
 } from "./refresh-outcome.ts";
 import type {
@@ -52,49 +48,52 @@ function renderRefreshStatus(
   hasDiagnostics: boolean,
   cwd: string,
 ): void {
-  if (!hasDiagnostics) return;
-
-  switch (data.refresh.kind) {
-    case "completed": {
-      const fileReadinessPending = isFileReadinessPending(data.refresh, data.semanticState);
-      lines.push(
-        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh, fileReadinessPending, false))}`,
-      );
-      renderSourceTracking(lines, data.refresh);
-      lines.push(`**Stale assessment**: ${asSentence(staleAssessmentText(data.refresh))}`);
-      lines.push("");
-      return;
-    }
-    case "failed": {
-      const evidence = data.refresh.diagnosticEvidence
-        ? `; ${formatDiagnosticEvidence(data.refresh.diagnosticEvidence)}`
-        : "";
-      const processCrashRecovery = data.refresh.processCrashRecovery
-        ? formatProcessCrashRecovery(data.refresh.processCrashRecovery)
-        : null;
-      const staleRestart = formatStaleDiagnosticRestarts(data.refresh);
-      lines.push(
-        `**${refreshAttemptLabel(data.refresh)}**: failed — ${data.refresh.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence}`,
-      );
-      renderSourceTracking(lines, data.refresh);
-      lines.push("");
-      return;
-    }
-    case "not-attempted":
-      lines.push(`**Diagnostic refresh attempt**: not started — ${data.refresh.reason}`);
-      if (data.refresh.lastAttempt) renderLastAttempt(lines, data.refresh.lastAttempt, cwd);
-      lines.push("");
-      return;
-    case "not-requested":
-      if (data.refresh.lastAttempt) {
-        renderRetainedAttempt(lines, data.refresh.lastAttempt, cwd);
-      } else {
-        lines.push(
-          "**Diagnostic refresh attempt**: not requested this session. Use `refresh: true` to try one.",
-        );
-      }
-      lines.push("");
+  if (!hasDiagnostics && data.refresh.kind !== "completed" && data.refresh.kind !== "failed") {
+    return;
+  }
+  if (data.refresh.kind === "completed") {
+    renderCompletedRefreshStatus(lines, data);
+    return;
+  }
+  if (data.refresh.kind === "failed") {
+    renderFailedRefreshStatus(lines, data.refresh);
+    return;
+  }
+  if (data.refresh.kind === "not-attempted") {
+    lines.push(`**Diagnostic refresh attempt**: not started — ${data.refresh.reason}`);
+    if (data.refresh.lastAttempt) renderLastAttempt(lines, data.refresh.lastAttempt, cwd);
+    lines.push("");
+    return;
+  }
+  if (data.refresh.lastAttempt) {
+    renderRetainedAttempt(lines, data.refresh.lastAttempt, cwd);
+  } else {
+    lines.push(
+      "**Diagnostic refresh attempt**: not requested this session. Use `refresh: true` to try one.",
+    );
   }
+  lines.push("");
+}
+
+function renderCompletedRefreshStatus(lines: string[], data: HealthData): void {
+  if (data.refresh.kind !== "completed") return;
+  const fileReadinessPending = isFileReadinessPending(data.refresh, data.semanticState);
+  lines.push(
+    `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh, fileReadinessPending, false))}`,
+  );
+  renderSourceTracking(lines, data.refresh);
+  lines.push(`**Stale assessment**: ${asSentence(staleAssessmentText(data.refresh))}`);
+  lines.push("");
+}
+
+function renderFailedRefreshStatus(
+  lines: string[],
+  attempt: Extract<HealthRefreshAttempt, { kind: "failed" }>,
+): void {
+  const outcome = failedRefreshText(attempt, false);
+  lines.push(`**${refreshAttemptLabel(attempt)}**: ${asSentence(outcome)}`);
+  renderSourceTracking(lines, attempt);
+  lines.push("");
 }
 
 function completedRefreshText(
@@ -103,11 +102,13 @@ function completedRefreshText(
   includeSourceTracking = true,
 ): string {
   const processCrashRecovery = formatProcessCrashRecovery(attempt.processCrashRecovery);
+  const startupRetry = formatStartupRetry(attempt.startupRetry);
   const noOp =
     !fileReadinessPending &&
     attempt.attemptedActiveClients === 0 &&
     attempt.restartedClients === 0 &&
-    processCrashRecovery === null;
+    processCrashRecovery === null &&
+    startupRetry === null;
   const base = fileReadinessPending
     ? "readiness pending — LSP may still be warming; retry shortly"
     : noOp
@@ -119,18 +120,20 @@ function completedRefreshText(
     includeSourceTracking ? sourceTracking : null,
     staleRestart,
     processCrashRecovery,
+    startupRetry,
   ].filter((value): value is string => value !== null);
   const withOutcome = outcome.length > 0 ? `${base}; ${outcome.join("; ")}` : base;
+  const withScope = `${withOutcome}; maintenance scope: ${refreshOperationScopeText(attempt)}`;
   return attempt.operationScope === "workspace-runtime"
-    ? `${withOutcome}; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
-    : withOutcome;
+    ? `${withScope}; maintenance evidence: ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
+    : withScope;
 }
 
 function renderSourceTracking(
   lines: string[],
   attempt: Pick<HealthRefreshAttempt, "sourceTracking">,
 ): void {
-  const sourceTracking = formatSourceTracking(attempt.sourceTracking);
+  const sourceTracking = formatSourceTrackingDetails(attempt.sourceTracking);
   if (sourceTracking) lines.push(`**Source discovery**: ${asSentence(sourceTracking)}`);
 }
 
@@ -157,7 +160,7 @@ function renderLastAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd:
   const outcome = refreshAttemptOutcome(attempt);
   const label = refreshAttemptLabel(attempt);
   lines.push(
-    `**Previous ${label.toLowerCase()}**: ${asSentence(outcome)} Started ${formatRefreshElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
+    `**Previous ${label.toLowerCase()}**: ${asSentence(outcome)} Started ${formatRefreshElapsed(Date.now() - attempt.attemptedAt)}; requested evidence scope: ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}.`,
   );
 }
 
@@ -165,21 +168,35 @@ function renderRetainedAttempt(lines: string[], attempt: HealthRefreshAttempt, c
   const label =
     attempt.operationScope === "file-runtime" ? "File LSP maintenance" : "Diagnostic refresh";
   lines.push(
-    `**${label}**: not requested for this call. Previous attempt ${asSentence(refreshAttemptOutcome(attempt))} Started ${formatRefreshElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
+    `**${label}**: not requested for this call. Previous attempt ${asSentence(refreshAttemptOutcome(attempt))} Started ${formatRefreshElapsed(Date.now() - attempt.attemptedAt)}; requested evidence scope: ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}.`,
   );
 }
 
 function refreshAttemptOutcome(attempt: HealthRefreshAttempt): string {
   if (attempt.kind === "completed") return completedRefreshText(attempt);
+  return failedRefreshText(attempt);
+}
+
+function failedRefreshText(
+  attempt: Extract<HealthRefreshAttempt, { kind: "failed" }>,
+  includeSourceTracking = true,
+): string {
   const processCrashRecovery = attempt.processCrashRecovery
     ? formatProcessCrashRecovery(attempt.processCrashRecovery)
     : null;
+  const startupRetry = attempt.startupRetry ? formatStartupRetry(attempt.startupRetry) : null;
   const staleRestart = formatStaleDiagnosticRestarts(attempt);
-  const sourceTracking = formatSourceTracking(attempt.sourceTracking);
+  const sourceTracking = includeSourceTracking
+    ? formatSourceTracking(attempt.sourceTracking)
+    : null;
   const evidence = attempt.diagnosticEvidence
-    ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
+    ? `; maintenance evidence: ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
     : "";
-  return `failed — ${attempt.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${sourceTracking ? `; ${sourceTracking}` : ""}${evidence}`;
+  return `failed — ${stripTrailingPunctuation(attempt.reason)}; maintenance scope: ${refreshOperationScopeText(attempt)}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${startupRetry ? `; ${startupRetry}` : ""}${sourceTracking ? `; ${sourceTracking}` : ""}${evidence}`;
+}
+
+function stripTrailingPunctuation(text: string): string {
+  return text.replace(/[.!?]+$/, "");
 }
 
 function refreshOperationScopeText(attempt: HealthRefreshAttempt): string {

package/src/tool/code_health/refresh-outcome.ts

@@ -1,6 +1,8 @@
 import type {
   ProcessCrashRecoveryEntry,
   ProcessCrashRecoveryReport,
+  StartupRetryEntry,
+  StartupRetryReport,
 } from "@mrclrchtr/supi-lsp/api";
 import type { SemanticHealthState } from "../../session/health-types.ts";
 import type { SourceTrackingReport } from "../../substrate/lsp/source-tracking.ts";
@@ -65,14 +67,52 @@ function formatProcessCrashRecoveryEntry(entry: ProcessCrashRecoveryEntry): stri
   return `${entry.name} @ ${entry.root}: ${outcome}${action}${failure}`;
 }
 
+/** Format initial-start retry counts for the compact health view. */
+export function formatCompactStartupRetry(
+  report: StartupRetryReport | null | undefined,
+): string | null {
+  if (!report || (report.recoveredRoutes === 0 && report.failedRoutes === 0)) return null;
+  return `startup retry: ${report.recoveredRoutes} route${plural(report.recoveredRoutes)} recovered (${report.failedRoutes} failed)`;
+}
+
+/** Format initial-start retry counts and bounded route entries. */
+export function formatStartupRetry(report: StartupRetryReport | null | undefined): string | null {
+  const summary = formatCompactStartupRetry(report);
+  if (!summary || !report) return summary;
+  const entries = report.entries.map(formatStartupRetryEntry);
+  const omitted =
+    report.omittedEntries > 0
+      ? `${report.omittedEntries} more route${plural(report.omittedEntries)}`
+      : null;
+  const details = [...entries, omitted]
+    .filter((value): value is string => value !== null)
+    .join("; ");
+  return details ? `${summary}; ${details}` : summary;
+}
+
+function formatStartupRetryEntry(entry: StartupRetryEntry): string {
+  const outcome = entry.outcome.replaceAll("-", " ");
+  const action = entry.nextAction ? `; next: ${entry.nextAction.replaceAll("-", " ")}` : "";
+  const failure = entry.failureMessage ? `; ${entry.failureMessage}` : "";
+  return `${entry.name} @ ${entry.root}: ${outcome}${action}${failure}`;
+}
+
 /** Format source discovery and bounded tracking counts separately from diagnostics. */
 export function formatSourceTracking(
   report: SourceTrackingReport | null | undefined,
+): string | null {
+  const details = formatSourceTrackingDetails(report);
+  return details ? `source discovery: ${details}` : null;
+}
+
+/** Format source tracking counts without a label for a standalone heading. */
+export function formatSourceTrackingDetails(
+  report: SourceTrackingReport | null | undefined,
 ): string | null {
   if (!report) return null;
   const inventory =
     report.status === "complete" ? "complete" : `limited (${report.reason ?? "unknown reason"})`;
-  return `source discovery: ${inventory}; ${report.observedFileCount} source files observed, ${report.discovered.length} discovered, ${report.tracked.length} tracked, ${report.unsupported.length} unsupported, ${report.unavailable.length} unavailable, ${report.deferred} deferred`;
+  return `${inventory}; ${report.observedFileCount} source files observed, ${report.discovered.length} discovered, ${report.tracked.length} tracked, ${report.skipped.length} skipped, ${report.unavailable.length} unavailable, ${report.deferred} deferred`;
 }
 
 /** Format the age of a retained refresh attempt for a status line. */

package/src/tool/code_health/refresh-status.ts

@@ -3,13 +3,22 @@ import {
   type ProcessCrashRecoveryEntry,
   type ProcessCrashRecoveryOutcome,
   type ProcessCrashRecoveryReport,
+  type StartupRetryEntry,
+  type StartupRetryReport,
 } from "@mrclrchtr/supi-lsp/api";
 import {
   formatCompactProcessCrashRecovery,
+  formatCompactStartupRetry,
   formatProcessCrashRecovery,
   formatStaleDiagnosticRestarts,
+  formatStartupRetry,
   isFileReadinessPending,
 } from "./refresh-outcome.ts";
+import {
+  formatCompactMaintenanceEvidence,
+  formatMaintenanceEvidence,
+  formatMaintenanceScope,
+} from "./scope.ts";
 import { readSemanticHealthState } from "./semantic-state.ts";
 
 /** Render current and retained health refresh status for the TUI. */
@@ -19,7 +28,7 @@ export function readSourceTrackingStatus(source: Record<string, unknown> | null)
   if (!source || (source.status !== "complete" && source.status !== "limited")) return null;
   const reason =
     source.status === "limited" && typeof source.reason === "string" ? ` (${source.reason})` : "";
-  return `${source.status}${reason}: ${readNumber(source.observedFileCount)} observed, ${readArrayLength(source.discovered)} discovered, ${readArrayLength(source.tracked)} tracked, ${readArrayLength(source.unsupported)} unsupported, ${readArrayLength(source.unavailable)} unavailable, ${readNumber(source.deferred)} deferred`;
+  return `${source.status}${reason}: ${readNumber(source.observedFileCount)} observed, ${readArrayLength(source.discovered)} discovered, ${readArrayLength(source.tracked)} tracked, ${readArrayLength(source.skipped)} skipped, ${readArrayLength(source.unavailable)} unavailable, ${readNumber(source.deferred)} deferred`;
 }
 
 export function readRefreshStatus(data: Record<string, unknown> | null): string | null {
@@ -49,18 +58,31 @@ function formatCompletedRefreshStatus(
   const processCrashRecovery = formatProcessCrashRecovery(
     readProcessCrashRecovery(refresh.processCrashRecovery),
   );
+  const startupRetry = formatStartupRetry(readStartupRetry(refresh.startupRetry));
   const noOp =
-    !fileReadinessPending && attempted === 0 && restarted === 0 && processCrashRecovery === null;
+    !fileReadinessPending &&
+    attempted === 0 &&
+    restarted === 0 &&
+    processCrashRecovery === null &&
+    startupRetry === null;
   const label = refreshAttemptLabel(refresh);
   const base = fileReadinessPending
     ? `${label} waiting — LSP may still be warming; retry shortly`
     : noOp
       ? `${label} completed no-op`
       : `${label} completed: ${attempted} clients targeted`;
-  const outcomes = formatRefreshOutcomes(refresh, restarted, processCrashRecovery, noOp);
+  const outcomes = formatRefreshOutcomes({
+    refresh,
+    restarted,
+    processCrashRecovery,
+    startupRetry,
+    noOp,
+  });
   const withOutcome = outcomes.length > 0 ? `${base}; ${outcomes.join("; ")}` : base;
-  const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
-  const withEvidence = evidence ? `${withOutcome}; ${evidence}` : withOutcome;
+  const maintenanceScope = formatMaintenanceScope(refresh);
+  const withScope = maintenanceScope ? `${withOutcome}; ${maintenanceScope}` : withOutcome;
+  const evidence = formatMaintenanceEvidence(readRecord(refresh.diagnosticEvidence));
+  const withEvidence = evidence ? `${withScope}; ${evidence}` : withScope;
   const stale = readRecord(refresh.staleAssessment);
   return stale?.suspected === true
     ? `${withEvidence}; stale pattern suspected in ${readNumber(stale.matchedFileCount)} files`
@@ -71,23 +93,26 @@ function formatFailedRefreshStatus(refresh: Record<string, unknown>): string {
   const processCrashRecovery = formatProcessCrashRecovery(
     readProcessCrashRecovery(refresh.processCrashRecovery),
   );
+  const startupRetry = formatStartupRetry(readStartupRetry(refresh.startupRetry));
   const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
-  const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
+  const maintenanceScope = formatMaintenanceScope(refresh);
+  const evidence = formatMaintenanceEvidence(readRecord(refresh.diagnosticEvidence));
   const reason = typeof refresh.reason === "string" ? `: ${refresh.reason}` : "";
-  return `${refreshAttemptLabel(refresh)} failed${reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence ? `; ${evidence}` : ""}`;
+  return `${refreshAttemptLabel(refresh)} failed${reason}${maintenanceScope ? `; ${maintenanceScope}` : ""}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${startupRetry ? `; ${startupRetry}` : ""}${evidence ? `; ${evidence}` : ""}`;
 }
-
-function formatRefreshOutcomes(
-  refresh: Record<string, unknown>,
-  restarted: number,
-  processCrashRecovery: string | null,
-  noOp: boolean,
-): string[] {
+function formatRefreshOutcomes(options: {
+  refresh: Record<string, unknown>;
+  restarted: number;
+  processCrashRecovery: string | null;
+  startupRetry: string | null;
+  noOp: boolean;
+}): string[] {
   const outcomes: string[] = [];
-  if (refresh.operationScope === "workspace-runtime" && !noOp) {
-    outcomes.push(formatStaleDiagnosticRestarts(restarted));
+  if (options.refresh.operationScope === "workspace-runtime" && !options.noOp) {
+    outcomes.push(formatStaleDiagnosticRestarts(options.restarted));
   }
-  if (processCrashRecovery) outcomes.push(processCrashRecovery);
+  if (options.processCrashRecovery) outcomes.push(options.processCrashRecovery);
+  if (options.startupRetry) outcomes.push(options.startupRetry);
   return outcomes;
 }
 
@@ -100,10 +125,12 @@ export function readCompactRefreshStatus(data: Record<string, unknown> | null):
   const processCrashRecovery = formatCompactProcessCrashRecovery(
     readProcessCrashRecovery(refresh.processCrashRecovery),
   );
+  const startupRetry = formatCompactStartupRetry(readStartupRetry(refresh.startupRetry));
+  const maintenanceScope = formatMaintenanceScope(refresh);
   if (refresh.kind === "failed") {
     const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
     return (
-      [sourceTracking, staleRestart, processCrashRecovery]
+      [maintenanceScope, sourceTracking, staleRestart, processCrashRecovery, startupRetry]
         .filter((value): value is string => value !== null)
         .join("; ") || null
     );
@@ -112,6 +139,7 @@ export function readCompactRefreshStatus(data: Record<string, unknown> | null):
   if (
     !sourceTracking &&
     !processCrashRecovery &&
+    !startupRetry &&
     readNumber(refresh.restartedClients) === 0 &&
     !fileReadinessPending
   ) {
@@ -120,7 +148,14 @@ export function readCompactRefreshStatus(data: Record<string, unknown> | null):
 
   const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
   const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
-  return [sourceTracking, staleRestart, processCrashRecovery, readiness]
+  return [
+    maintenanceScope,
+    sourceTracking,
+    staleRestart,
+    processCrashRecovery,
+    startupRetry,
+    readiness,
+  ]
     .filter((value): value is string => value !== null)
     .join("; ");
 }
@@ -132,17 +167,26 @@ export function readPreviousRefreshStatus(data: Record<string, unknown> | null):
   }
   const attempt = readRecord(refresh.lastAttempt);
   if (!attempt) return null;
-  const evidence = formatCompactDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  const evidence = formatCompactMaintenanceEvidence(readRecord(attempt.diagnosticEvidence));
   const sourceTracking = formatSourceTracking(readRecord(attempt.sourceTracking));
   const processCrashRecovery = formatCompactProcessCrashRecovery(
     readProcessCrashRecovery(attempt.processCrashRecovery),
   );
+  const startupRetry = formatCompactStartupRetry(readStartupRetry(attempt.startupRetry));
   const staleRestart = formatStaleDiagnosticRestartsForRecord(attempt);
   const fileReadinessPending =
     attempt.kind === "completed" &&
     isFileReadinessPending(attempt, readSemanticHealthState(data?.semanticState));
   const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
-  const outcome = [readiness, sourceTracking, staleRestart, processCrashRecovery, evidence]
+  const outcome = [
+    readiness,
+    formatMaintenanceScope(attempt),
+    sourceTracking,
+    staleRestart,
+    processCrashRecovery,
+    startupRetry,
+    evidence,
+  ]
     .filter((value): value is string => value !== null)
     .join("; ");
   if (attempt.kind === "failed") {
@@ -180,16 +224,25 @@ function formatStaleDiagnosticRestartsForRecord(attempt: Record<string, unknown>
 function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   const attempt = readRecord(refresh.lastAttempt);
   if (!attempt) return "";
-  const evidence = formatDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  const evidence = formatMaintenanceEvidence(readRecord(attempt.diagnosticEvidence));
   const sourceTracking = formatSourceTracking(readRecord(attempt.sourceTracking));
   const staleRestart = formatStaleDiagnosticRestartsForRecord(attempt);
   const processCrashRecovery = formatProcessCrashRecovery(
     readProcessCrashRecovery(attempt.processCrashRecovery),
   );
+  const startupRetry = formatStartupRetry(readStartupRetry(attempt.startupRetry));
   const fileReadinessPending =
     attempt.kind === "completed" && isFileReadinessPending(attempt, null);
   const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
-  const outcome = [readiness, sourceTracking, staleRestart, processCrashRecovery, evidence]
+  const outcome = [
+    readiness,
+    formatMaintenanceScope(attempt),
+    sourceTracking,
+    staleRestart,
+    processCrashRecovery,
+    startupRetry,
+    evidence,
+  ]
     .filter((value): value is string => value !== null)
     .join("; ");
   if (attempt.kind === "failed") {
@@ -212,18 +265,6 @@ function readArrayLength(value: unknown): number {
   return Array.isArray(value) ? value.length : 0;
 }
 
-function formatCompactDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
-  const counts = readEvidenceCounts(evidence);
-  if (!counts) return null;
-  return `req ${counts[0]} · conf ${counts[1]} · unconf ${counts[2]} · failed ${counts[3]} · removed ${counts[4]}`;
-}
-
-function formatDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
-  const counts = readEvidenceCounts(evidence);
-  if (!counts) return null;
-  return `${counts[0]} requested, ${counts[1]} confirmed, ${counts[2]} unconfirmed, ${counts[3]} failed, ${counts[4]} removed`;
-}
-
 export function isPendingFileReadiness(data: Record<string, unknown> | null): boolean {
   const observation = readRecord(data?.diagnosticObservation);
   const scope = readRecord(observation?.scope);
@@ -234,6 +275,43 @@ export function isPendingFileReadiness(data: Record<string, unknown> | null): bo
   return isFileReadinessPending(attempt, readSemanticHealthState(data?.semanticState));
 }
 
+function readStartupRetry(value: unknown): StartupRetryReport | null {
+  const report = readRecord(value);
+  if (!report) return null;
+  const recoveredRoutes = report.recoveredRoutes;
+  const failedRoutes = report.failedRoutes;
+  const omittedEntries = report.omittedEntries;
+  if (
+    !isEvidenceCount(recoveredRoutes) ||
+    !isEvidenceCount(failedRoutes) ||
+    !isEvidenceCount(omittedEntries) ||
+    !Array.isArray(report.entries) ||
+    report.entries.length > MAX_PROCESS_CRASH_RECOVERY_ENTRIES
+  ) {
+    return null;
+  }
+  const entries = report.entries
+    .map(readStartupRetryEntry)
+    .filter((entry): entry is StartupRetryEntry => entry !== null);
+  if (entries.length !== report.entries.length) return null;
+  return { recoveredRoutes, failedRoutes, entries, omittedEntries };
+}
+
+function readStartupRetryEntry(value: unknown): StartupRetryEntry | null {
+  const entry = readRecord(value);
+  if (!entry || typeof entry.name !== "string" || typeof entry.root !== "string") return null;
+  if (entry.outcome !== "recovered" && entry.outcome !== "retry-failed") return null;
+  if (entry.nextAction !== undefined && entry.nextAction !== "refresh") return null;
+  if (entry.failureMessage !== undefined && typeof entry.failureMessage !== "string") return null;
+  return {
+    name: entry.name,
+    root: entry.root,
+    outcome: entry.outcome,
+    ...(entry.nextAction !== undefined ? { nextAction: entry.nextAction } : {}),
+    ...(entry.failureMessage !== undefined ? { failureMessage: entry.failureMessage } : {}),
+  };
+}
+
 function readProcessCrashRecovery(value: unknown): ProcessCrashRecoveryReport | null {
   const report = readRecord(value);
   if (!report) return null;
@@ -267,7 +345,7 @@ function readProcessCrashRecoveryEntry(value: unknown): ProcessCrashRecoveryEntr
   if (
     entry.nextAction !== undefined &&
     entry.nextAction !== "use-exact-file" &&
-    entry.nextAction !== "reload-workspace"
+    entry.nextAction !== "refresh"
   ) {
     return null;
   }
@@ -290,18 +368,6 @@ function isProcessCrashRecoveryOutcome(value: unknown): value is ProcessCrashRec
   );
 }
 
-function readEvidenceCounts(evidence: Record<string, unknown> | null): number[] | null {
-  if (!evidence) return null;
-  const counts = [
-    evidence.requested,
-    evidence.confirmed,
-    evidence.unconfirmed,
-    evidence.failed,
-    evidence.removed,
-  ];
-  return counts.every(isEvidenceCount) ? counts : null;
-}
-
 function isEvidenceCount(value: unknown): value is number {
   return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }

package/src/tool/code_health/scope.ts

@@ -0,0 +1,78 @@
+/** Formatting for diagnostic result and maintenance scopes and their evidence. */
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+export function withDiagnosticScope(summary: string, data: Record<string, unknown> | null): string {
+  const scope = formatDiagnosticScope(readDiagnosticScope(data));
+  return scope ? `${summary} — evidence scope: ${scope}` : summary;
+}
+
+function readDiagnosticScope(data: Record<string, unknown> | null): Record<string, unknown> | null {
+  return readRecord(readRecord(data?.diagnosticObservation)?.scope);
+}
+
+function formatDiagnosticScope(scope: Record<string, unknown> | null): string | null {
+  if (scope?.kind === "file" && typeof scope.path === "string") {
+    return `live file diagnostic request for ${scope.path}`;
+  }
+  if (scope?.kind === "tracked-files") {
+    return typeof scope.filter === "string"
+      ? `tracked-file diagnostic snapshot under ${scope.filter}`
+      : "tracked-file diagnostic snapshot";
+  }
+  return null;
+}
+
+export function formatCompactDiagnosticEvidence(
+  evidence: Record<string, unknown> | null,
+  scopeKind: string | null,
+): string | null {
+  const counts = readEvidenceCounts(evidence);
+  if (!counts) return null;
+  const scopeLabel = scopeKind === "file" ? "file" : "tracked-file";
+  return `${scopeLabel} evidence req ${counts[0]} · conf ${counts[1]} · unconf ${counts[2]} · failed ${counts[3]} · removed ${counts[4]}`;
+}
+
+export function formatDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
+  const counts = readEvidenceCounts(evidence);
+  if (!counts) return null;
+  return `${counts[0]} requested, ${counts[1]} confirmed, ${counts[2]} unconfirmed, ${counts[3]} failed, ${counts[4]} removed`;
+}
+
+export function formatMaintenanceEvidence(evidence: Record<string, unknown> | null): string | null {
+  const counts = readEvidenceCounts(evidence);
+  if (!counts) return null;
+  return `maintenance evidence: ${counts[0]} requested, ${counts[1]} confirmed, ${counts[2]} unconfirmed, ${counts[3]} failed, ${counts[4]} removed`;
+}
+
+export function formatCompactMaintenanceEvidence(
+  evidence: Record<string, unknown> | null,
+): string | null {
+  const counts = readEvidenceCounts(evidence);
+  if (!counts) return null;
+  return `maintenance evidence req ${counts[0]} · conf ${counts[1]} · unconf ${counts[2]} · failed ${counts[3]} · removed ${counts[4]}`;
+}
+
+export function formatMaintenanceScope(refresh: Record<string, unknown>): string | null {
+  if (refresh.operationScope === "file-runtime") return "maintenance scope: file runtime";
+  if (refresh.operationScope === "workspace-runtime") return "maintenance scope: workspace runtime";
+  return null;
+}
+
+function readEvidenceCounts(evidence: Record<string, unknown> | null): number[] | null {
+  if (!evidence) return null;
+  const counts = [
+    evidence.requested,
+    evidence.confirmed,
+    evidence.unconfirmed,
+    evidence.failed,
+    evidence.removed,
+  ];
+  return counts.every(isEvidenceCount) ? counts : null;
+}
+
+function isEvidenceCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}

package/src/tool/code_health/spec.ts

@@ -18,7 +18,7 @@ export const codeHealthSpec = {
       refresh: Type.Optional(
         Type.Boolean({
           description:
-            "Attempt diagnostic and required process-crash recovery before collecting; result reports the outcome.",
+            "Retry failed LSP routes and collect fresh diagnostic health evidence; result reports route recovery separately from diagnostic confirmation.",
         }),
       ),
       include: Type.Optional(