@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

package/src/tool/code_graph/tui.ts

@@ -1,28 +1,34 @@
-/** TUI renderer for code_graph. */
+/** Human transcript renderer for code_graph. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { type Component, Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { renderCandidateSelection } from "../../ui/tui/candidate-selection.ts";
 import {
   buildSimpleCompact,
-  buildSimpleHeader,
   type EvidenceEntry,
   formatCallPath,
   formatCallValue,
   type ResultOptios,
+  readEvidenceEntries,
   renderDomainError,
-  renderDomainResult,
-  renderEvidenceLines,
   renderExecutionError,
   renderMarkdownDetail,
   renderPartial,
-  renderStructuredDetailBody,
   renderToolDisplaySections,
   renderTruncationDisclosure,
   type ToolRendererContext,
   type ToolResult,
 } from "../../ui/tui/common.ts";
+import {
+  MAX_TUI_DISPLAY_ITEMS,
+  readToolDisplaySections,
+  truncateDisplayText,
+} from "../result/display.ts";
+import type { ToolDisplaySection } from "../result/types.ts";
+import type { GraphFileGroup } from "./details.ts";
 import type { CodeGraphToolParams, GraphRelation } from "./execute.ts";
+import { compactGraphLabel, formatGraphEvidence, formatGraphRange } from "./format.ts";
 
-/** Render the compact code_graph call header. */
+/** Render the compact call header from the requested selector. */
 export function renderGraphCall(
   args: unknown,
   theme: Theme,
@@ -30,84 +36,240 @@ export function renderGraphCall(
 ): Text {
   const params = (args ?? {}) as Partial<CodeGraphToolParams>;
   const relations: GraphRelation[] = Array.isArray(params.relations)
-    ? (params.relations as GraphRelation[])
+    ? params.relations
     : ["references"];
-  const relationLabel = formatRelations(relations);
-
-  let content = theme.fg("toolTitle", "code_graph");
-  if (relationLabel) content += ` ${theme.fg("accent", relationLabel)}`;
-
+  const label = formatRelations(relations);
   const target = formatTarget(params.target);
-  if (target) content += ` ${theme.fg("muted", target)}`;
-
-  return new Text(content, 0, 0);
+  return new Text(
+    theme.fg("toolTitle", "code_graph") +
+      (label ? ` ${theme.fg("accent", label)}` : "") +
+      (target ? ` ${theme.fg("muted", target)}` : ""),
+    0,
+    0,
+  );
 }
 
-/** Render code_graph progress, status, and structured result details. */
+/** Render one structured body, with no duplicate agent Markdown. */
 export function renderGraphResult(
   result: ToolResult,
   options: ResultOptios,
   theme: Theme,
   context: ToolRendererContext | undefined,
-): Container | Text {
+): Component {
   if (options.isPartial) return renderPartial("Collecting relations…", theme);
-
-  const details =
-    result.details?.type === "search" ? (result.details.data as Record<string, unknown>) : null;
-  const executionError = renderExecutionError(context, "code_graph failed", theme);
+  const executionError = renderExecutionError(
+    result,
+    { isError: context?.isError, expanded: options.expanded, label: "code_graph failed" },
+    theme,
+  );
   if (executionError) return executionError;
+  const candidateSelection = renderCandidateSelection(result, options, theme, "graph.candidates");
+  if (candidateSelection) return candidateSelection;
   const domainError = renderDomainError(result, theme);
-  if (domainError) return renderDomainResult(result, options, theme, domainError);
+  if (domainError) return renderGraphDomainError(result, options.expanded, domainError, theme);
 
-  if (!options.expanded) {
-    const compact = buildSimpleCompact(details ?? undefined, theme);
-    const truncation = renderTruncationDisclosure(result, theme);
-    if (!truncation) return compact;
-    const container = new Container();
-    container.addChild(compact);
+  const data = asRecord(result.details?.data);
+  const container = new Container();
+  if (result.details?.type === "graph" && data) {
+    renderGraphBody(data, result, { container, expanded: options.expanded, theme });
+  } else {
+    // Older persisted results have only generic search details.
+    container.addChild(buildSimpleCompact(data ?? undefined, theme));
+    if (options.expanded)
+      renderToolDisplaySections(container, result.details?.displaySections, theme);
+  }
+  const truncation = renderTruncationDisclosure(result, theme);
+  if (truncation) {
     container.addChild(new Spacer(1));
     container.addChild(truncation);
-    return container;
   }
+  return container;
+}
 
-  const container = new Container();
-  const header = buildSimpleHeader(details ?? undefined, theme);
-  if (header) container.addChild(header);
+interface SectionView {
+  rel: string;
+  label: string;
+  unavailable: boolean;
+  message: string | null;
+  externalCount: number;
+  scope: Record<string, unknown> | null;
+  fileGroups: GraphFileGroup[];
+}
 
-  const evidenceLists = details?.evidenceLists as EvidenceEntry[] | undefined;
-  if (evidenceLists && evidenceLists.length > 0) {
+function renderGraphBody(
+  data: Record<string, unknown>,
+  result: ToolResult,
+  options: { container: Container; expanded: boolean; theme: Theme },
+): void {
+  const { container, expanded, theme } = options;
+  const target =
+    typeof data.targetName === "string" ? compactGraphLabel(data.targetName) : "Target";
+  const file = typeof data.targetFile === "string" ? truncateDisplayText(data.targetFile) : "";
+  container.addChild(new Text(theme.fg("accent", `${target}${file ? ` — ${file}` : ""}`), 0, 0));
+  const evidence = readEvidenceEntries(data.evidenceLists);
+  const displays = readToolDisplaySections(result.details?.displaySections);
+  const sections = readSections(data.sections);
+  const summaries: string[] = [];
+  for (const section of sections) {
+    const display = displays.find((entry) => entry.key === `graph.${section.rel}`);
+    const metadata = evidence.find((entry) => entry.key.startsWith(`${section.rel}.`));
+    const summary = sectionSummary(section, metadata, display);
+    if (!expanded) {
+      summaries.push(summary);
+      continue;
+    }
     container.addChild(new Spacer(1));
-    renderEvidenceLines(container, evidenceLists, theme);
+    container.addChild(
+      new Text(theme.fg(section.unavailable ? "warning" : "accent", summary), 0, 0),
+    );
+    renderRelationBody(container, { section, display, targetName: data.targetName }, theme);
   }
+  if (!expanded)
+    container.addChild(
+      new Text(theme.fg("muted", summaries.join(" · ") || "No graph sections"), 0, 0),
+    );
+}
 
-  renderToolDisplaySections(container, result.details?.displaySections, theme);
-  renderStructuredDetailBody(container, details ?? undefined, theme);
-  const truncation = renderTruncationDisclosure(result, theme);
-  if (truncation) {
-    container.addChild(new Spacer(1));
-    container.addChild(truncation);
+function renderRelationBody(
+  container: Container,
+  input: { section: SectionView; display: ToolDisplaySection | undefined; targetName: unknown },
+  theme: Theme,
+): void {
+  const { section, display, targetName } = input;
+  if (section.unavailable) {
+    if (section.message)
+      container.addChild(new Text(theme.fg("warning", truncateDisplayText(section.message)), 0, 0));
+    return;
+  }
+  const scope = scopeLabel(section.scope, targetName);
+  if (scope) container.addChild(new Text(theme.fg("dim", scope), 0, 0));
+  const rows = display?.lines ?? [];
+  let index = 0;
+  const groups =
+    section.fileGroups.reduce((sum, group) => sum + group.count, 0) === rows.length
+      ? section.fileGroups
+      : [];
+  for (const group of groups) {
+    if (index >= rows.length) break;
+    container.addChild(new Text(theme.fg("dim", group.file), 0, 0));
+    for (const row of rows.slice(index, index + group.count))
+      container.addChild(new Text(theme.fg("muted", `  ${row}`), 0, 0));
+    index += group.count;
   }
-  renderMarkdownDetail(container, result, theme);
+  // Older results contain full paths in each row and have no file groups.
+  for (const row of rows.slice(index)) container.addChild(new Text(theme.fg("muted", row), 0, 0));
+}
+
+function renderGraphDomainError(
+  result: ToolResult,
+  expanded: boolean,
+  domainError: Text,
+  theme: Theme,
+): Container | Text {
+  if (!expanded) return domainError;
+  const container = new Container();
+  container.addChild(domainError);
+  const displays = readToolDisplaySections(result.details?.displaySections);
+  renderToolDisplaySections(container, displays, theme);
+  if (displays.length === 0) renderMarkdownDetail(container, result, theme);
   return container;
 }
 
+function sectionSummary(
+  section: SectionView,
+  metadata: EvidenceEntry | undefined,
+  display: ToolDisplaySection | undefined,
+): string {
+  if (section.unavailable) return `${section.label}: unavailable`;
+  if (!metadata) return `${section.label}: evidence unavailable`;
+  // The display has its own bounded row count; the underlying evidence total is unchanged.
+  const shown = display
+    ? { ...metadata, shownCount: display.shownCount, omittedCount: display.omittedCount }
+    : metadata;
+  return `${section.label}: ${formatGraphEvidence(shown, section.rel === "callees" ? "call sites" : "locations", section.externalCount)}`;
+}
+
+function readSections(value: unknown): SectionView[] {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, 3).flatMap((item) => {
+    const section = asRecord(item);
+    if (
+      !section ||
+      typeof section.rel !== "string" ||
+      !["references", "callees", "implements"].includes(section.rel) ||
+      (section.source !== "structural" && section.source !== "semantic")
+    )
+      return [];
+    const rel = section.rel;
+    const source = section.source;
+    const depth =
+      rel === "callees" && (section.depth === "direct" || section.depth === "deep")
+        ? `, ${section.depth}`
+        : "";
+    return [
+      {
+        rel,
+        label: `${rel} (${source}${depth})`,
+        unavailable: section.status === "unavailable",
+        message: typeof section.message === "string" ? section.message : null,
+        externalCount: typeof section.externalCount === "number" ? section.externalCount : 0,
+        scope: asRecord(section.enclosingScope),
+        fileGroups: readFileGroups(section.fileGroups),
+      },
+    ];
+  });
+}
+
+function readFileGroups(value: unknown): GraphFileGroup[] {
+  if (!Array.isArray(value)) return [];
+  const groups: GraphFileGroup[] = [];
+  for (const entry of value.slice(0, MAX_TUI_DISPLAY_ITEMS)) {
+    const group = asRecord(entry);
+    if (
+      !group ||
+      typeof group.file !== "string" ||
+      typeof group.count !== "number" ||
+      !Number.isInteger(group.count) ||
+      group.count < 1 ||
+      group.count > MAX_TUI_DISPLAY_ITEMS
+    )
+      return [];
+    groups.push({ file: truncateDisplayText(group.file), count: group.count });
+  }
+  return groups;
+}
+
+function scopeLabel(scope: Record<string, unknown> | null, targetName: unknown): string | null {
+  if (!scope || typeof scope.startLine !== "number" || typeof scope.endLine !== "number")
+    return null;
+  const name =
+    typeof scope.name === "string" && scope.name !== targetName
+      ? `${compactGraphLabel(scope.name)} — `
+      : "";
+  const range = formatGraphRange({ startLine: scope.startLine, endLine: scope.endLine });
+  return `Scope: ${name}${range}; source expressions, not resolved symbols`;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
 function formatRelations(relations: readonly GraphRelation[]): string {
-  if (relations.length === 0) return "";
-  if (relations.length === 1) return `→ ${relations[0]}`;
-  if (relations.length <= 3) return `→ ${relations.join(", ")}`;
-  return `→ ${relations.slice(0, 2).join(", ")} +${relations.length - 2}`;
+  return relations.length ? `→ ${relations.slice(0, 3).join(", ")}` : "";
 }
 
 function formatTarget(target: unknown): string {
-  if (!target || typeof target !== "object") return "";
-  const record = target as Record<string, unknown>;
-
-  if (record.symbol && typeof record.symbol === "object") {
-    const query = formatCallValue((record.symbol as Record<string, unknown>).query);
+  const record = asRecord(target);
+  if (!record) return "";
+  const symbol = asRecord(record.symbol);
+  if (symbol) {
+    const query = formatCallValue(symbol.query);
     return query ? `of ${query}` : "";
   }
-  if (record.anchor && typeof record.anchor === "object") {
-    const anchor = record.anchor as Record<string, unknown>;
+  const anchor = asRecord(record.anchor);
+  if (anchor) {
     const file = formatCallPath(anchor.file);
     const line = typeof anchor.line === "number" ? `:${anchor.line}` : "";
     return file ? `at ${file}${line}` : "";

package/src/tool/code_health/guidance.ts

@@ -1,8 +1,6 @@
 export const toolDescription =
-  "Report live diagnostics as observations, language-server route status, and final semantic health state. Tracked-file snapshots do not prove workspace completeness; server inventory and route issue counts are workspace-wide. Server-only calls are passive.";
+  "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 = "live workspace health observations";
+export const promptSnippet = "check live diagnostics and language-server health";
 
-export const promptGuidelines = [
-  "Use code_health with refresh:true before relying on potentially stale diagnostics; explicit refresh can recover crashed routes with tracked files in scope.",
-];
+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,
@@ -15,7 +9,10 @@ import { makeRelative, renderFileScopeStatus } from "./file-scope-markdown.ts";
 import {
   formatProcessCrashRecovery,
   formatRefreshElapsed,
+  formatSourceTracking,
+  formatSourceTrackingDetails,
   formatStaleDiagnosticRestarts as formatStaleDiagnosticRestartsText,
+  formatStartupRetry,
   isFileReadinessPending,
 } from "./refresh-outcome.ts";
 import type {
@@ -51,72 +48,93 @@ 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))}`,
-      );
-      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}`,
-      );
-      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(
   attempt: Extract<HealthRefreshAttempt, { kind: "completed" }>,
   fileReadinessPending = attempt.fileReadiness === "pending",
+  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
       ? "completed no-op — no active clients were targeted"
       : `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 sourceTracking = formatSourceTracking(attempt.sourceTracking);
+  const outcome = [
+    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 = formatSourceTrackingDetails(attempt.sourceTracking);
+  if (sourceTracking) lines.push(`**Source discovery**: ${asSentence(sourceTracking)}`);
 }
 
 function refreshAttemptLabel(attempt: Pick<HealthRefreshAttempt, "operationScope">): string {
@@ -142,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)}.`,
   );
 }
 
@@ -150,20 +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 = 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}` : ""}${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,8 +1,11 @@
 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";
 
 /** Report whether a file health result is waiting for semantic readiness. */
 export function isFileReadinessPending(
@@ -64,6 +67,54 @@ 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 `${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. */
 export function formatRefreshElapsed(milliseconds: number): string {
   const seconds = Math.max(0, Math.round(milliseconds / 1_000));