@mrclrchtr/supi-code-intelligence 6.1.0 → 6.3.0

package/src/tool/code_health/markdown.ts

@@ -11,9 +11,15 @@ import {
   formatProjectServerRouteSummary,
   formatProjectServerStatusReason,
 } from "../../analysis/health/server-status.ts";
+import { makeRelative, renderFileScopeStatus } from "./file-scope-markdown.ts";
+import {
+  formatProcessCrashRecovery,
+  formatRefreshElapsed,
+  formatStaleDiagnosticRestarts as formatStaleDiagnosticRestartsText,
+  isFileReadinessPending,
+} from "./refresh-outcome.ts";
 import type {
   HealthData,
-  HealthDiagnosticObservation,
   HealthDiagnosticScope,
   HealthRefreshAttempt,
   HealthResultAssembly,
@@ -48,19 +54,25 @@ function renderRefreshStatus(
   if (!hasDiagnostics) return;
 
   switch (data.refresh.kind) {
-    case "completed":
+    case "completed": {
+      const fileReadinessPending = isFileReadinessPending(data.refresh, data.semanticState);
       lines.push(
-        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh))}`,
+        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh, fileReadinessPending))}`,
       );
       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}${evidence}`,
+        `**${refreshAttemptLabel(data.refresh)}**: failed — ${data.refresh.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence}`,
       );
       lines.push("");
       return;
@@ -84,14 +96,27 @@ function renderRefreshStatus(
 
 function completedRefreshText(
   attempt: Extract<HealthRefreshAttempt, { kind: "completed" }>,
+  fileReadinessPending = attempt.fileReadiness === "pending",
 ): string {
-  const base =
-    attempt.attemptedActiveClients === 0 && attempt.restartedClients === 0
+  const processCrashRecovery = formatProcessCrashRecovery(attempt.processCrashRecovery);
+  const noOp =
+    !fileReadinessPending &&
+    attempt.attemptedActiveClients === 0 &&
+    attempt.restartedClients === 0 &&
+    processCrashRecovery === null;
+  const base = fileReadinessPending
+    ? "readiness pending — LSP may still be warming; retry shortly"
+    : noOp
       ? "completed no-op — no active clients were targeted"
-      : `completed — ${attempt.attemptedActiveClients} active client${plural(attempt.attemptedActiveClients)} targeted, ${attempt.restartedClients} restarted`;
+      : `completed — ${attempt.attemptedActiveClients} active client${plural(attempt.attemptedActiveClients)} targeted`;
+  const staleRestart = noOp ? null : formatStaleDiagnosticRestarts(attempt);
+  const outcome = [staleRestart, processCrashRecovery].filter(
+    (value): value is string => value !== null,
+  );
+  const withOutcome = outcome.length > 0 ? `${base}; ${outcome.join("; ")}` : base;
   return attempt.operationScope === "workspace-runtime"
-    ? `${base}; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
-    : base;
+    ? `${withOutcome}; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
+    : withOutcome;
 }
 
 function refreshAttemptLabel(attempt: Pick<HealthRefreshAttempt, "operationScope">): string {
@@ -117,7 +142,7 @@ function renderLastAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd:
   const outcome = refreshAttemptOutcome(attempt);
   const label = refreshAttemptLabel(attempt);
   lines.push(
-    `**Previous ${label.toLowerCase()}**: ${asSentence(outcome)} Started ${formatElapsed(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 ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
   );
 }
 
@@ -125,24 +150,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 ${formatElapsed(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 ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
   );
 }
 
 function refreshAttemptOutcome(attempt: HealthRefreshAttempt): string {
-  return attempt.kind === "completed"
-    ? completedRefreshText(attempt)
-    : `failed — ${attempt.reason}${attempt.diagnosticEvidence ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}` : ""}`;
+  if (attempt.kind === "completed") return completedRefreshText(attempt);
+  const processCrashRecovery = attempt.processCrashRecovery
+    ? formatProcessCrashRecovery(attempt.processCrashRecovery)
+    : null;
+  const staleRestart = formatStaleDiagnosticRestarts(attempt);
+  const evidence = attempt.diagnosticEvidence
+    ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
+    : "";
+  return `failed — ${attempt.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence}`;
 }
 
 function refreshOperationScopeText(attempt: HealthRefreshAttempt): string {
   return attempt.operationScope === "file-runtime" ? "file runtime" : "workspace runtime";
 }
 
-function formatElapsed(milliseconds: number): string {
-  const seconds = Math.max(0, Math.round(milliseconds / 1_000));
-  if (seconds < 60) return `${seconds}s ago`;
-  return `${Math.round(seconds / 60)}m ago`;
+function formatStaleDiagnosticRestarts(attempt: {
+  kind?: HealthRefreshAttempt["kind"];
+  operationScope: HealthRefreshAttempt["operationScope"];
+  restartedClients?: number;
+}): string | null {
+  if (attempt.operationScope !== "workspace-runtime" || attempt.restartedClients === undefined) {
+    return null;
+  }
+  return formatStaleDiagnosticRestartsText(attempt.restartedClients);
 }
 
 function renderCapabilityWarningsSection(
@@ -193,49 +229,6 @@ function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string
   lines.push("");
 }
 
-/**
- * Render the tsconfig coverage verdict for a single-file health request.
- *
- * Written in plain vocabulary (no basis terms) so a reader without tsconfig
- * background can act on it: the sentence names the deciding config and states
- * whether the file's errors are part of workspace diagnostics. The structured
- * decision basis stays in the diagnostics.scope debug event.
- */
-function renderFileScopeStatus(
-  lines: string[],
-  observation: Extract<
-    HealthDiagnosticObservation,
-    { kind: "completed" | "partial" | "unavailable" }
-  >,
-  cwd: string,
-): void {
-  if (observation.scope.kind !== "file" || !observation.scopeStatus) return;
-
-  const decision = observation.scopeStatus;
-  switch (decision.status) {
-    case "included":
-      lines.push(
-        `**Tsconfig**: covered by ${formatConfigPath(decision.configPath, cwd)} — part of workspace diagnostics.`,
-      );
-      return;
-    case "excluded":
-      lines.push(
-        `**Tsconfig**: NOT covered by ${formatConfigPath(decision.configPath, cwd)} — not part of workspace diagnostics.`,
-      );
-      return;
-    case "no-config":
-      lines.push("**Tsconfig**: no tsconfig.json or jsconfig.json found — nothing filtered.");
-      return;
-    case "out-of-tree":
-      lines.push("**Tsconfig**: outside the project root — not part of workspace diagnostics.");
-  }
-}
-
-function formatConfigPath(configPath: string | null, cwd: string): string {
-  if (!configPath) return "no config";
-  return `\`${makeRelative(cwd, configPath)}\``;
-}
-
 function formatDiagnosticEvidence(evidence: {
   requested: number;
   confirmed: number;
@@ -250,7 +243,14 @@ function renderDiagnosticObservation(lines: string[], data: HealthData, cwd: str
   const observation = data.diagnostics;
   if (observation.kind === "not-requested") return;
   if (observation.kind === "unavailable") {
-    lines.push(`Diagnostics unavailable — ${asSentence(observation.reason)}`);
+    if (
+      observation.scope.kind === "file" &&
+      isFileReadinessPending(currentRefreshAttempt(data), data.semanticState)
+    ) {
+      lines.push("Diagnostics pending — LSP may still be warming; retry shortly.");
+    } else {
+      lines.push(`Diagnostics unavailable — ${asSentence(observation.reason)}`);
+    }
     return;
   }
   if (observation.kind === "partial") {
@@ -269,6 +269,10 @@ function renderDiagnosticObservation(lines: string[], data: HealthData, cwd: str
   renderDiagnosticEntries(lines, data, cwd);
 }
 
+function currentRefreshAttempt(data: HealthData): HealthRefreshAttempt | null {
+  return data.refresh.kind === "completed" || data.refresh.kind === "failed" ? data.refresh : null;
+}
+
 function asSentence(text: string): string {
   return /[.!?]$/.test(text) ? text : `${text}.`;
 }
@@ -371,7 +375,3 @@ function formatDiagnosticScope(scope: HealthDiagnosticScope, cwd: string): strin
 function plural(count: number): string {
   return count === 1 ? "" : "s";
 }
-
-function makeRelative(cwd: string, file: string): string {
-  return file.startsWith(cwd) ? file.slice(cwd.length + 1) : file;
-}

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

@@ -0,0 +1,76 @@
+import type {
+  ProcessCrashRecoveryEntry,
+  ProcessCrashRecoveryReport,
+} from "@mrclrchtr/supi-lsp/api";
+import type { SemanticHealthState } from "../../session/health-types.ts";
+
+/** Report whether a file health result is waiting for semantic readiness. */
+export function isFileReadinessPending(
+  attempt: { operationScope?: string; fileReadiness?: string } | null | undefined,
+  semanticState: SemanticHealthState | null | undefined,
+): boolean {
+  if (attempt?.operationScope !== undefined) {
+    return (
+      attempt.operationScope === "file-runtime" &&
+      (attempt.fileReadiness === "pending" ||
+        (attempt.fileReadiness === undefined && semanticState?.kind === "pending"))
+    );
+  }
+  return semanticState?.kind === "pending";
+}
+
+/** Format the outcome of stale-diagnostic client restarts. */
+export function formatStaleDiagnosticRestarts(restartedClients: number): string {
+  return `stale diagnostic restarts: ${restartedClients} client${plural(restartedClients)} restarted`;
+}
+
+/** Format process-crash counts for the compact health view. */
+export function formatCompactProcessCrashRecovery(
+  report: ProcessCrashRecoveryReport | null | undefined,
+): string | null {
+  if (
+    !report ||
+    (report.recoveredRoutes === 0 &&
+      report.skippedRoutes === 0 &&
+      report.failedRoutes === 0 &&
+      report.exhaustedRoutes === 0)
+  ) {
+    return null;
+  }
+  return `process-crash recovery: ${report.recoveredRoutes} route${plural(report.recoveredRoutes)} recovered (${report.skippedRoutes} skipped, ${report.failedRoutes} failed, ${report.exhaustedRoutes} exhausted)`;
+}
+
+/** Format process-crash counts and bounded route entries for detailed health output. */
+export function formatProcessCrashRecovery(
+  report: ProcessCrashRecoveryReport | null | undefined,
+): string | null {
+  const summary = formatCompactProcessCrashRecovery(report);
+  if (!summary || !report) return summary;
+  const entries = report.entries.map(formatProcessCrashRecoveryEntry);
+  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 formatProcessCrashRecoveryEntry(entry: ProcessCrashRecoveryEntry): 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 the age of a retained refresh attempt for a status line. */
+export function formatRefreshElapsed(milliseconds: number): string {
+  const seconds = Math.max(0, Math.round(milliseconds / 1_000));
+  if (seconds < 60) return `${seconds}s ago`;
+  return `${Math.round(seconds / 60)}m ago`;
+}
+
+function plural(count: number): string {
+  return count === 1 ? "" : "s";
+}

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

@@ -1,3 +1,17 @@
+import {
+  MAX_PROCESS_CRASH_RECOVERY_ENTRIES,
+  type ProcessCrashRecoveryEntry,
+  type ProcessCrashRecoveryOutcome,
+  type ProcessCrashRecoveryReport,
+} from "@mrclrchtr/supi-lsp/api";
+import {
+  formatCompactProcessCrashRecovery,
+  formatProcessCrashRecovery,
+  formatStaleDiagnosticRestarts,
+  isFileReadinessPending,
+} from "./refresh-outcome.ts";
+import { readSemanticHealthState } from "./semantic-state.ts";
+
 /** Render current and retained health refresh status for the TUI. */
 
 export function readRefreshStatus(data: Record<string, unknown> | null): string | null {
@@ -5,25 +19,10 @@ export function readRefreshStatus(data: Record<string, unknown> | null): string
   if (!refresh) return null;
 
   switch (refresh.kind) {
-    case "completed": {
-      const attempted = readNumber(refresh.attemptedActiveClients);
-      const restarted = readNumber(refresh.restartedClients);
-      const stale = readRecord(refresh.staleAssessment);
-      const noOp = attempted === 0 && restarted === 0;
-      const label = refreshAttemptLabel(refresh);
-      const base = noOp
-        ? `${label} completed no-op`
-        : `${label} completed: ${attempted} clients targeted, ${restarted} restarted`;
-      const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
-      const withEvidence = evidence ? `${base}; ${evidence}` : base;
-      return stale?.suspected === true
-        ? `${withEvidence}; stale pattern suspected in ${readNumber(stale.matchedFileCount)} files`
-        : withEvidence;
-    }
-    case "failed": {
-      const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
-      return `${refreshAttemptLabel(refresh)} failed${typeof refresh.reason === "string" ? `: ${refresh.reason}` : ""}${evidence ? `; ${evidence}` : ""}`;
-    }
+    case "completed":
+      return formatCompletedRefreshStatus(refresh, isPendingFileReadiness(data));
+    case "failed":
+      return formatFailedRefreshStatus(refresh);
     case "not-attempted":
       return `refresh attempt not started${formatLastRefreshSuffix(refresh)}`;
     case "not-requested":
@@ -33,6 +32,89 @@ export function readRefreshStatus(data: Record<string, unknown> | null): string
   }
 }
 
+function formatCompletedRefreshStatus(
+  refresh: Record<string, unknown>,
+  fileReadinessPending: boolean,
+): string {
+  const attempted = readNumber(refresh.attemptedActiveClients);
+  const restarted = readNumber(refresh.restartedClients);
+  const processCrashRecovery = formatProcessCrashRecovery(
+    readProcessCrashRecovery(refresh.processCrashRecovery),
+  );
+  const noOp =
+    !fileReadinessPending && attempted === 0 && restarted === 0 && processCrashRecovery === 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 withOutcome = outcomes.length > 0 ? `${base}; ${outcomes.join("; ")}` : base;
+  const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
+  const withEvidence = evidence ? `${withOutcome}; ${evidence}` : withOutcome;
+  const stale = readRecord(refresh.staleAssessment);
+  return stale?.suspected === true
+    ? `${withEvidence}; stale pattern suspected in ${readNumber(stale.matchedFileCount)} files`
+    : withEvidence;
+}
+
+function formatFailedRefreshStatus(refresh: Record<string, unknown>): string {
+  const processCrashRecovery = formatProcessCrashRecovery(
+    readProcessCrashRecovery(refresh.processCrashRecovery),
+  );
+  const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
+  const evidence = formatDiagnosticEvidence(readRecord(refresh.diagnosticEvidence));
+  const reason = typeof refresh.reason === "string" ? `: ${refresh.reason}` : "";
+  return `${refreshAttemptLabel(refresh)} failed${reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence ? `; ${evidence}` : ""}`;
+}
+
+function formatRefreshOutcomes(
+  refresh: Record<string, unknown>,
+  restarted: number,
+  processCrashRecovery: string | null,
+  noOp: boolean,
+): string[] {
+  const outcomes: string[] = [];
+  if (refresh.operationScope === "workspace-runtime" && !noOp) {
+    outcomes.push(formatStaleDiagnosticRestarts(restarted));
+  }
+  if (processCrashRecovery) outcomes.push(processCrashRecovery);
+  return outcomes;
+}
+
+/** Render only the material current recovery outcome for compact TUI chrome. */
+export function readCompactRefreshStatus(data: Record<string, unknown> | null): string | null {
+  const refresh = readRecord(data?.refresh);
+  if (!refresh || (refresh.kind !== "completed" && refresh.kind !== "failed")) return null;
+
+  const processCrashRecovery = formatCompactProcessCrashRecovery(
+    readProcessCrashRecovery(refresh.processCrashRecovery),
+  );
+  if (refresh.kind === "failed") {
+    const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
+    return (
+      [staleRestart, processCrashRecovery]
+        .filter((value): value is string => value !== null)
+        .join("; ") || null
+    );
+  }
+  const fileReadinessPending = isPendingFileReadiness(data);
+  if (
+    !processCrashRecovery &&
+    readNumber(refresh.restartedClients) === 0 &&
+    !fileReadinessPending
+  ) {
+    return null;
+  }
+
+  const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
+  const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
+  return [staleRestart, processCrashRecovery, readiness]
+    .filter((value): value is string => value !== null)
+    .join("; ");
+}
+
 export function readPreviousRefreshStatus(data: Record<string, unknown> | null): string | null {
   const refresh = readRecord(data?.refresh);
   if (!refresh || (refresh.kind !== "not-requested" && refresh.kind !== "not-attempted")) {
@@ -41,11 +123,23 @@ export function readPreviousRefreshStatus(data: Record<string, unknown> | null):
   const attempt = readRecord(refresh.lastAttempt);
   if (!attempt) return null;
   const evidence = formatCompactDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  const processCrashRecovery = formatCompactProcessCrashRecovery(
+    readProcessCrashRecovery(attempt.processCrashRecovery),
+  );
+  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, staleRestart, processCrashRecovery, evidence]
+    .filter((value): value is string => value !== null)
+    .join("; ");
   if (attempt.kind === "failed") {
-    return `last ${refreshAttemptLabel(attempt)} failed${evidence ? ` (${evidence})` : ""}`;
+    return `last ${refreshAttemptLabel(attempt)} failed${outcome ? ` (${outcome})` : ""}`;
   }
   if (attempt.kind === "completed") {
-    return `last ${refreshAttemptLabel(attempt)} completed${evidence ? ` (${evidence})` : ""}`;
+    const status = fileReadinessPending ? "waiting" : "completed";
+    return `last ${refreshAttemptLabel(attempt)} ${status}${outcome ? ` (${outcome})` : ""}`;
   }
   return null;
 }
@@ -54,16 +148,45 @@ function refreshAttemptLabel(attempt: Record<string, unknown>): string {
   return attempt.operationScope === "file-runtime" ? "file maintenance attempt" : "refresh attempt";
 }
 
+function formatStaleDiagnosticRestartsForRecord(attempt: Record<string, unknown>): string | null {
+  if (
+    attempt.operationScope !== "workspace-runtime" ||
+    typeof attempt.restartedClients !== "number"
+  ) {
+    return null;
+  }
+  const processCrashRecovery = formatProcessCrashRecovery(
+    readProcessCrashRecovery(attempt.processCrashRecovery),
+  );
+  const noOp =
+    attempt.kind === "completed" &&
+    readNumber(attempt.attemptedActiveClients) === 0 &&
+    attempt.restartedClients === 0 &&
+    processCrashRecovery === null;
+  return noOp ? null : formatStaleDiagnosticRestarts(attempt.restartedClients);
+}
+
 function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   const attempt = readRecord(refresh.lastAttempt);
   if (!attempt) return "";
   const evidence = formatDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  const staleRestart = formatStaleDiagnosticRestartsForRecord(attempt);
+  const processCrashRecovery = formatProcessCrashRecovery(
+    readProcessCrashRecovery(attempt.processCrashRecovery),
+  );
+  const fileReadinessPending =
+    attempt.kind === "completed" && isFileReadinessPending(attempt, null);
+  const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
+  const outcome = [readiness, staleRestart, processCrashRecovery, evidence]
+    .filter((value): value is string => value !== null)
+    .join("; ");
   if (attempt.kind === "failed") {
     const reason = typeof attempt.reason === "string" ? `: ${attempt.reason}` : "";
-    return `; last ${refreshAttemptLabel(attempt)} failed${reason}${evidence ? `; ${evidence}` : ""}`;
+    return `; last ${refreshAttemptLabel(attempt)} failed${reason}${outcome ? `; ${outcome}` : ""}`;
   }
   if (attempt.kind === "completed") {
-    return `; last ${refreshAttemptLabel(attempt)} completed${evidence ? `; ${evidence}` : ""}`;
+    const status = fileReadinessPending ? "waiting" : "completed";
+    return `; last ${refreshAttemptLabel(attempt)} ${status}${outcome ? `; ${outcome}` : ""}`;
   }
   return "";
 }
@@ -80,6 +203,72 @@ function formatDiagnosticEvidence(evidence: Record<string, unknown> | null): str
   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);
+  if (scope?.kind !== "file") return false;
+
+  const refresh = readRecord(data?.refresh);
+  const attempt = refresh && typeof refresh.operationScope === "string" ? refresh : null;
+  return isFileReadinessPending(attempt, readSemanticHealthState(data?.semanticState));
+}
+
+function readProcessCrashRecovery(value: unknown): ProcessCrashRecoveryReport | null {
+  const report = readRecord(value);
+  if (!report) return null;
+  const recoveredRoutes = report.recoveredRoutes;
+  const skippedRoutes = report.skippedRoutes;
+  const failedRoutes = report.failedRoutes;
+  const exhaustedRoutes = report.exhaustedRoutes;
+  const omittedEntries = report.omittedEntries;
+  if (
+    !isEvidenceCount(recoveredRoutes) ||
+    !isEvidenceCount(skippedRoutes) ||
+    !isEvidenceCount(failedRoutes) ||
+    !isEvidenceCount(exhaustedRoutes) ||
+    !isEvidenceCount(omittedEntries) ||
+    !Array.isArray(report.entries) ||
+    report.entries.length > MAX_PROCESS_CRASH_RECOVERY_ENTRIES
+  ) {
+    return null;
+  }
+  const entries = report.entries
+    .map(readProcessCrashRecoveryEntry)
+    .filter((entry): entry is ProcessCrashRecoveryEntry => entry !== null);
+  if (entries.length !== report.entries.length) return null;
+  return { recoveredRoutes, skippedRoutes, failedRoutes, exhaustedRoutes, entries, omittedEntries };
+}
+
+function readProcessCrashRecoveryEntry(value: unknown): ProcessCrashRecoveryEntry | null {
+  const entry = readRecord(value);
+  if (!entry || typeof entry.name !== "string" || typeof entry.root !== "string") return null;
+  if (!isProcessCrashRecoveryOutcome(entry.outcome)) return null;
+  if (
+    entry.nextAction !== undefined &&
+    entry.nextAction !== "use-exact-file" &&
+    entry.nextAction !== "reload-workspace"
+  ) {
+    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 isProcessCrashRecoveryOutcome(value: unknown): value is ProcessCrashRecoveryOutcome {
+  return (
+    value === "recovered" ||
+    value === "skipped-no-retained-file" ||
+    value === "recovery-failed" ||
+    value === "recovery-exhausted"
+  );
+}
+
 function readEvidenceCounts(evidence: Record<string, unknown> | null): number[] | null {
   if (!evidence) return null;
   const counts = [

package/src/tool/code_health/result.ts

@@ -19,6 +19,7 @@ export type {
   HealthDiagnosticEntry,
   HealthDiagnosticObservation,
   HealthDiagnosticScope,
+  HealthFileReadiness,
   HealthRefreshAttempt,
   HealthRefreshState,
   HealthSection,

package/src/tool/code_health/tui.ts

@@ -24,7 +24,12 @@ import {
   type ToolResult,
 } from "../../ui/tui/common.ts";
 import type { CodeHealthToolParams } from "./execute.ts";
-import { readPreviousRefreshStatus, readRefreshStatus } from "./refresh-status.ts";
+import {
+  isPendingFileReadiness,
+  readCompactRefreshStatus,
+  readPreviousRefreshStatus,
+  readRefreshStatus,
+} from "./refresh-status.ts";
 import { formatSemanticHealthState, readSemanticHealthState } from "./semantic-state.ts";
 
 /** ── renderCall ────────────────────────────────────────────────── */
@@ -125,6 +130,7 @@ function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme)
   const semanticRequested = sections.some(
     (section) => section.key === "diagnostics" || section.key === "servers",
   );
+  const fileReadinessPending = isPendingFileReadiness(data);
   const segments = sections.map((section) =>
     formatSectionSummary(
       section,
@@ -132,6 +138,7 @@ function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme)
         ? formatCompactDiagnosticEvidence(readDiagnosticEvidence(data))
         : null,
       theme,
+      fileReadinessPending,
     ),
   );
   if (semanticRequested) {
@@ -142,8 +149,8 @@ function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme)
       `${theme.fg("dim", "lsp")} ${theme.fg(statusColor, semanticStatus)}${routeSummary ? ` ${theme.fg("warning", routeSummary)}` : ""}`,
     );
   }
-  const previousRefresh = readPreviousRefreshStatus(data);
-  if (previousRefresh) segments.push(theme.fg("dim", previousRefresh));
+  const refreshStatus = readCompactRefreshStatus(data) ?? readPreviousRefreshStatus(data);
+  if (refreshStatus) segments.push(theme.fg("dim", refreshStatus));
   const capabilityWarningCount = readCapabilityWarnings(data).length;
   if (capabilityWarningCount > 0) {
     const label = capabilityWarningCount === 1 ? "capability warning" : "capability warnings";
@@ -158,11 +165,14 @@ function formatSectionSummary(
   section: HealthSectionSummary,
   coverage: string | null,
   theme: Theme,
+  fileReadinessPending: boolean,
 ): string {
   const label = sectionLabel(section.key);
   const coverageSuffix = coverage ? ` (${coverage})` : "";
   if (section.status === "unavailable" || !section.available) {
-    return `${theme.fg("dim", label)} ${theme.fg("warning", "unavailable")}${coverageSuffix}`;
+    const status =
+      section.key === "diagnostics" && fileReadinessPending ? "pending" : "unavailable";
+    return `${theme.fg("dim", label)} ${theme.fg("warning", status)}${coverageSuffix}`;
   }
   if (section.status === "partial") {
     return `${theme.fg("dim", label)} ${theme.fg("warning", "partial")}${coverageSuffix}`;
@@ -307,7 +317,10 @@ function buildDiagnosticSummary(data: Record<string, unknown> | null, theme: The
   const section = readHealthSections(data).find((entry) => entry.key === "diagnostics");
   if (!section) return new Text("", 0, 0);
   if (section.status === "unavailable" || !section.available) {
-    return new Text(theme.fg("warning", "Diagnostics unavailable"), 0, 0);
+    const label = isPendingFileReadiness(data)
+      ? "Diagnostics pending — LSP may still be warming; retry shortly"
+      : "Diagnostics unavailable";
+    return new Text(theme.fg("warning", label), 0, 0);
   }
   const trackedFiles = diagnosticScopeKind(data) === "tracked-files";
   if (section.status === "partial") {

package/src/tool/code_refactor_apply/guidance.ts

@@ -1,5 +1,6 @@
-export const toolDescription = "Apply one stored refactor plan by planId.";
+export const toolDescription =
+  "Apply one fresh stored refactor plan by planId after safety checks; mutates its files.";
 
-export const promptSnippet = "apply a fresh stored refactor plan";
+export const promptSnippet = "apply a stored refactor plan";
 
 export const promptGuidelines: string[] = [];

package/src/tool/code_refactor_plan/guidance.ts

@@ -1,5 +1,5 @@
 export const toolDescription =
-  "Preview one semantic rename or extraction and return a planId without mutating files.";
+  "Preview one semantic rename, extraction, import cleanup, or dead-code deletion and return a planId without mutating files.";
 
 export const promptSnippet = "preview a precise semantic refactor";