@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

package/src/tool/find/execute.ts

@@ -26,12 +26,18 @@ export async function executeFindTool(
     return searchErrorResult(`**Error:** ${outcome.message}`, {
       scope: Array.isArray(params?.scope) ? params.scope.join(", ") : null,
       nextQueries: ["Fix the search input and retry"],
+      message: outcome.message,
     });
   }
 
   const assembly = assembleFindWorkflowResult(outcome);
   return {
     content: renderFindResult(assembly),
-    details: { type: "search", data: assembly.details },
+    details: {
+      type: "search",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
   };
 }

package/src/tool/find/render.ts

@@ -38,9 +38,7 @@ function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMeta
   const { outcome } = assembly;
   if (outcome.data.kind !== "semantic") return "";
   const symbols = outcome.data.symbols;
-  if (symbols.length === 0) {
-    return `**Semantic search** — \`${outcome.query}\`\n\nNo semantic results found in \`${outcome.scopeLabel}\`.`;
-  }
+  if (symbols.length === 0) return renderEmptySemantic(assembly, evidence);
 
   const lines = [
     `**Semantic search** — \`${outcome.query}\` (${symbols.length} symbol${symbols.length === 1 ? "" : "s"} found)`,
@@ -55,3 +53,22 @@ function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMeta
   if (disclosure) lines.push(disclosure);
   return lines.join("\n");
 }
+
+function renderEmptySemantic(assembly: FindResultAssembly, evidence: EvidenceListMetadata): string {
+  const { outcome } = assembly;
+  const lines = [
+    `**Semantic search** — \`${outcome.query}\``,
+    "",
+    evidence.partialReason
+      ? `No LSP workspace-symbol results were collected in \`${outcome.scopeLabel}\`.`
+      : `No LSP workspace-symbol results found in \`${outcome.scopeLabel}\`.`,
+  ];
+  const disclosure = renderEvidenceListMetadataDisclosure(evidence);
+  if (disclosure) lines.push("", disclosure);
+  lines.push("", "Document-level semantic symbols can differ from the workspace index.");
+  const fileQuery = assembly.assembled.actions.find(
+    (action) => action.kind === "query" && action.instruction.startsWith("If you know the file"),
+  );
+  if (fileQuery?.kind === "query") lines.push(fileQuery.instruction);
+  return lines.join("\n");
+}

package/src/tool/find/tui.ts

@@ -1,39 +1,41 @@
-/**
- * TUI renderer for code_find — renderCall + renderResult.
- */
+/** TUI renderer for code_find. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { type ResultOptios, renderSimpleResult, type ToolResult } from "../../ui/tui/common.ts";
+import {
+  formatCallValue,
+  type ResultOptios,
+  renderSimpleResult,
+  type ToolRendererContext,
+  type ToolResult,
+} from "../../ui/tui/common.ts";
 import type { CodeFindToolParams } from "./execute.ts";
 
-/** ── renderCall ────────────────────────────────────────────────── */
-
-export function renderFindCall(args: unknown, theme: Theme, _context: unknown): Text {
-  const params = (args ?? {}) as CodeFindToolParams;
-  const mode = params.mode ?? "mode?";
+/** Render the compact code_find call header. */
+export function renderFindCall(
+  args: unknown,
+  theme: Theme,
+  _context: ToolRendererContext | undefined,
+): Text {
+  const params = (args ?? {}) as Partial<CodeFindToolParams>;
+  const mode = formatCallValue(params.mode, 20) ?? "mode?";
 
   let content = theme.fg("toolTitle", "code_find");
-
-  if (params.query) {
-    content += ` ${theme.fg("accent", JSON.stringify(params.query))}`;
-  }
-
+  const query = formatCallValue(params.query);
+  if (query) content += ` ${theme.fg("accent", JSON.stringify(query))}`;
   content += ` ${theme.fg("muted", mode)}`;
 
-  if (params.kind) {
-    content += theme.fg("dim", ` [${params.kind}]`);
-  }
+  const kind = formatCallValue(params.kind, 30);
+  if (kind) content += theme.fg("dim", ` [${kind}]`);
 
   return new Text(content, 0, 0);
 }
 
-/** ── renderResult ──────────────────────────────────────────────── */
-
+/** Render code_find progress, status, and structured result details. */
 export function renderFindResult(
   result: ToolResult,
   options: ResultOptios,
   theme: Theme,
-  _context: unknown,
+  context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Searching…");
+  return renderSimpleResult(result, options, theme, "Searching…", context);
 }

package/src/tool/graph/execute.ts

@@ -4,6 +4,7 @@ import type { GraphWorkflowInput, RequestedGraphRelation } from "../../session/g
 import type { GraphTargetInput } from "../../session/target-input.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
 import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { createToolDisplaySection } from "../result/display.ts";
 import { searchErrorResult } from "../result/errors.ts";
 import { assembleGraphResult } from "../result/graph.ts";
 import { renderGraphResult } from "./markdown.ts";
@@ -25,7 +26,7 @@ export async function executeGraphTool(
 
   if (outcome.kind === "unavailable") throw new Error(outcome.reason);
   if (outcome.kind === "invalid-input") {
-    return searchErrorResult(`**Error:** ${outcome.message}`);
+    return searchErrorResult(`**Error:** ${outcome.message}`, { message: outcome.message });
   }
   if (outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch") {
     const lines = [
@@ -45,7 +46,21 @@ export async function executeGraphTool(
         "Retry without `symbolKind`, use an observed provider kind, or choose a handle.",
       );
     }
-    return searchErrorResult(lines.join("\n"));
+    return searchErrorResult(lines.join("\n"), {
+      message:
+        outcome.kind === "kind-mismatch"
+          ? `No target matched provider kind ${outcome.requestedKind}.`
+          : "The target is ambiguous.",
+      displaySections: [
+        createToolDisplaySection({
+          key: "graph.candidates",
+          title: "Candidates",
+          items: outcome.candidates,
+          format: (candidate) =>
+            `${candidate.targetId} — ${candidate.name} (${candidate.kind ?? "unknown"}) at ${candidate.file}:${candidate.line}:${candidate.character}`,
+        }),
+      ],
+    });
   }
 
   const assembly = assembleGraphResult({
@@ -57,6 +72,11 @@ export async function executeGraphTool(
   });
   return {
     content: renderGraphResult(assembly),
-    details: { type: "search", data: assembly.details },
+    details: {
+      type: "search",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
   };
 }

package/src/tool/graph/tui.ts

@@ -1,73 +1,76 @@
-/**
- * TUI renderer for code_graph — renderCall + renderResult.
- *
- * Dual-surface rendering: chrome built from details, markdown body
- * available as a collapsible detail view.
- */
-
+/** TUI renderer for code_graph. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import {
   buildSimpleCompact,
   buildSimpleHeader,
   type EvidenceEntry,
+  formatCallPath,
+  formatCallValue,
   type ResultOptios,
+  renderDomainError,
+  renderDomainResult,
   renderEvidenceLines,
+  renderExecutionError,
   renderMarkdownDetail,
   renderPartial,
   renderStructuredDetailBody,
+  renderToolDisplaySections,
+  renderTruncationDisclosure,
+  type ToolRendererContext,
   type ToolResult,
 } from "../../ui/tui/common.ts";
 import type { CodeGraphToolParams, GraphRelation } from "./execute.ts";
 
-/** ── renderCall ────────────────────────────────────────────────── */
-
-export function renderGraphCall(args: unknown, theme: Theme, _context: unknown): Text {
-  const params = (args ?? {}) as CodeGraphToolParams;
-  const relations = params.relations ?? ["references"];
+/** Render the compact code_graph call header. */
+export function renderGraphCall(
+  args: unknown,
+  theme: Theme,
+  _context: ToolRendererContext | undefined,
+): Text {
+  const params = (args ?? {}) as Partial<CodeGraphToolParams>;
+  const relations: GraphRelation[] = Array.isArray(params.relations)
+    ? (params.relations as GraphRelation[])
+    : ["references"];
   const relationLabel = formatRelations(relations);
 
   let content = theme.fg("toolTitle", "code_graph");
+  if (relationLabel) content += ` ${theme.fg("accent", relationLabel)}`;
 
-  if (relationLabel) {
-    content += ` ${theme.fg("accent", relationLabel)}`;
-  }
-
-  const target = formatTarget(params);
-  if (target) {
-    content += ` ${theme.fg("muted", target)}`;
-  }
+  const target = formatTarget(params.target);
+  if (target) content += ` ${theme.fg("muted", target)}`;
 
   return new Text(content, 0, 0);
 }
 
-/** ── renderResult ──────────────────────────────────────────────── */
-
+/** Render code_graph progress, status, and structured result details. */
 export function renderGraphResult(
   result: ToolResult,
   options: ResultOptios,
   theme: Theme,
-  _context: unknown,
+  context: ToolRendererContext | undefined,
 ): Container | Text {
-  if (options.isPartial) {
-    return renderPartial("Collecting relations…", theme);
-  }
+  if (options.isPartial) return renderPartial("Collecting relations…", theme);
 
-  const container = new Container();
   const details =
     result.details?.type === "search" ? (result.details.data as Record<string, unknown>) : null;
-
-  if (result.isError) {
-    container.addChild(new Text(theme.fg("error", "code_graph failed"), 0, 0));
-    return container;
-  }
+  const executionError = renderExecutionError(context, "code_graph failed", theme);
+  if (executionError) return executionError;
+  const domainError = renderDomainError(result, theme);
+  if (domainError) return renderDomainResult(result, options, theme, domainError);
 
   if (!options.expanded) {
-    container.addChild(buildSimpleCompact(details ?? undefined, theme));
+    const compact = buildSimpleCompact(details ?? undefined, theme);
+    const truncation = renderTruncationDisclosure(result, theme);
+    if (!truncation) return compact;
+    const container = new Container();
+    container.addChild(compact);
+    container.addChild(new Spacer(1));
+    container.addChild(truncation);
     return container;
   }
 
-  // Expanded view
+  const container = new Container();
   const header = buildSimpleHeader(details ?? undefined, theme);
   if (header) container.addChild(header);
 
@@ -77,28 +80,38 @@ export function renderGraphResult(
     renderEvidenceLines(container, evidenceLists, theme);
   }
 
+  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);
+  }
   renderMarkdownDetail(container, result, theme);
-
   return container;
 }
 
-/** ── Helpers ───────────────────────────────────────────────────── */
-
-function formatRelations(relations: GraphRelation[]): string {
+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}`;
 }
 
-function formatTarget(params: CodeGraphToolParams): string {
-  if ("symbol" in params.target) return `of ${params.target.symbol.query}`;
-  if ("anchor" in params.target) {
-    const point = params.target.anchor;
-    const file = point.file.split("/").pop() ?? point.file;
-    return `at ${file}:${point.line}`;
+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);
+    return query ? `of ${query}` : "";
+  }
+  if (record.anchor && typeof record.anchor === "object") {
+    const anchor = record.anchor as Record<string, unknown>;
+    const file = formatCallPath(anchor.file);
+    const line = typeof anchor.line === "number" ? `:${anchor.line}` : "";
+    return file ? `at ${file}${line}` : "";
   }
-  if ("handle" in params.target) return `of ${params.target.handle}`;
-  return "";
+  const handle = formatCallValue(record.handle);
+  return handle ? `of ${handle}` : "";
 }

package/src/tool/health/execute.ts

@@ -21,12 +21,17 @@ export async function executeHealthTool(
   const outcome = await ctx.session.health(params as HealthWorkflowInput, toWorkflowControl(ctx));
   if (outcome.kind === "unavailable") throw new Error(outcome.reason);
   if (outcome.kind === "invalid-input") {
-    return healthErrorResult(`**Error:** ${outcome.message}`, "invalid input");
+    return healthErrorResult(`**Error:** ${outcome.message}`, outcome.message);
   }
 
   const assembly = assembleHealthResult(outcome.data);
   return {
     content: renderHealthResult(assembly, ctx.cwd),
-    details: { type: "health", data: assembly.details },
+    details: {
+      type: "health",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
   };
 }

package/src/tool/health/markdown.ts

@@ -51,16 +51,24 @@ function renderRefreshStatus(
 
   switch (data.refresh.kind) {
     case "completed":
-      lines.push(`**Diagnostic refresh**: ${completedRefreshText(data.refresh)}.`);
-      lines.push(`**Stale assessment**: ${staleAssessmentText(data.refresh)}.`);
+      lines.push(
+        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh))}`,
+      );
+      lines.push(`**Stale assessment**: ${asSentence(staleAssessmentText(data.refresh))}`);
       lines.push("");
       return;
-    case "failed":
-      lines.push(`**Diagnostic refresh**: failed — ${data.refresh.reason}`);
+    case "failed": {
+      const evidence = data.refresh.diagnosticEvidence
+        ? `; ${formatDiagnosticEvidence(data.refresh.diagnosticEvidence)}`
+        : "";
+      lines.push(
+        `**${refreshAttemptLabel(data.refresh)}**: failed — ${data.refresh.reason}${evidence}`,
+      );
       lines.push("");
       return;
+    }
     case "not-attempted":
-      lines.push(`**Diagnostic refresh**: not attempted — ${data.refresh.reason}`);
+      lines.push(`**Diagnostic refresh attempt**: not started — ${data.refresh.reason}`);
       if (data.refresh.lastAttempt) renderLastAttempt(lines, data.refresh.lastAttempt, cwd);
       lines.push("");
       return;
@@ -69,7 +77,7 @@ function renderRefreshStatus(
         renderLastAttempt(lines, data.refresh.lastAttempt, cwd);
       } else {
         lines.push(
-          "**Diagnostic refresh**: not attempted this session. Use `refresh: true` to try one.",
+          "**Diagnostic refresh attempt**: not requested this session. Use `refresh: true` to try one.",
         );
       }
       lines.push("");
@@ -79,10 +87,19 @@ function renderRefreshStatus(
 function completedRefreshText(
   attempt: Extract<HealthRefreshAttempt, { kind: "completed" }>,
 ): string {
-  if (attempt.attemptedActiveClients === 0 && attempt.restartedClients === 0) {
-    return "completed no-op — no active clients were targeted";
-  }
-  return `completed — ${attempt.attemptedActiveClients} active client${plural(attempt.attemptedActiveClients)} targeted, ${attempt.restartedClients} restarted`;
+  const base =
+    attempt.attemptedActiveClients === 0 && attempt.restartedClients === 0
+      ? "completed no-op — no active clients were targeted"
+      : `completed — ${attempt.attemptedActiveClients} active client${plural(attempt.attemptedActiveClients)} targeted, ${attempt.restartedClients} restarted`;
+  return attempt.operationScope === "workspace-runtime"
+    ? `${base}; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
+    : base;
+}
+
+function refreshAttemptLabel(attempt: Pick<HealthRefreshAttempt, "operationScope">): string {
+  return attempt.operationScope === "file-runtime"
+    ? "File LSP maintenance attempt"
+    : "Diagnostic refresh attempt";
 }
 
 function staleAssessmentText(
@@ -90,6 +107,9 @@ function staleAssessmentText(
 ): string {
   if (attempt.staleAssessment.warning) return attempt.staleAssessment.warning;
   const matches = `${attempt.staleAssessment.matchedFileCount} file${plural(attempt.staleAssessment.matchedFileCount)} match the stale-module heuristic`;
+  if (attempt.staleAssessment.scope === "file") {
+    return `${matches} in the requested file; workspace clustering was not assessed`;
+  }
   return attempt.staleAssessment.suspected
     ? `${matches}; a clustered stale-module pattern is suspected`
     : `${matches}; no clustered stale-module pattern is suspected`;
@@ -97,12 +117,19 @@ function staleAssessmentText(
 
 function renderLastAttempt(lines: string[], attempt: HealthRefreshAttempt, cwd: string): void {
   const outcome =
-    attempt.kind === "completed" ? completedRefreshText(attempt) : `failed — ${attempt.reason}`;
+    attempt.kind === "completed"
+      ? completedRefreshText(attempt)
+      : `failed — ${attempt.reason}${attempt.diagnosticEvidence ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}` : ""}`;
+  const label = refreshAttemptLabel(attempt);
   lines.push(
-    `**Last diagnostic refresh attempt**: ${outcome}, started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: workspace runtime.`,
+    `**Last ${label.toLowerCase()}**: ${asSentence(outcome)} Started ${formatElapsed(Date.now() - attempt.attemptedAt)}; requested ${formatDiagnosticScope(attempt.requestedDiagnosticScope, cwd)}; operation scope: ${refreshOperationScopeText(attempt)}.`,
   );
 }
 
+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`;
@@ -143,6 +170,7 @@ function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string
     lines.push("Diagnostics were not requested.");
   } else {
     lines.push(`**Evidence scope**: ${formatDiagnosticScope(observation.scope, cwd)}.`);
+    lines.push(`**Evidence coverage**: ${formatDiagnosticEvidence(observation.evidence)}.`);
     lines.push("");
     renderDiagnosticObservation(lines, data, cwd);
   }
@@ -150,15 +178,25 @@ function renderDiagnosticsSection(lines: string[], data: HealthData, cwd: string
   lines.push("");
 }
 
+function formatDiagnosticEvidence(evidence: {
+  requested: number;
+  confirmed: number;
+  unconfirmed: number;
+  failed: number;
+  removed: number;
+}): string {
+  return `${evidence.requested} requested, ${evidence.confirmed} confirmed, ${evidence.unconfirmed} unconfirmed, ${evidence.failed} failed, ${evidence.removed} removed`;
+}
+
 function renderDiagnosticObservation(lines: string[], data: HealthData, cwd: string): void {
   const observation = data.diagnostics;
   if (observation.kind === "not-requested") return;
   if (observation.kind === "unavailable") {
-    lines.push(`Diagnostics unavailable — ${observation.reason}.`);
+    lines.push(`Diagnostics unavailable — ${asSentence(observation.reason)}`);
     return;
   }
   if (observation.kind === "partial") {
-    lines.push(`Diagnostics partially collected — ${observation.reason}.`);
+    lines.push(`Diagnostics partially collected — ${asSentence(observation.reason)}`);
     if (observation.entries.length > 0) {
       lines.push("");
       lines.push("Partial results:");
@@ -173,6 +211,10 @@ function renderDiagnosticObservation(lines: string[], data: HealthData, cwd: str
   renderDiagnosticEntries(lines, data, cwd);
 }
 
+function asSentence(text: string): string {
+  return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+
 function emptyDiagnosticText(scope: HealthDiagnosticScope, cwd: string): string {
   if (scope.kind === "file") {
     return `No errors or warnings found for \`${makeRelative(cwd, scope.path)}\`.`;

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

@@ -0,0 +1,105 @@
+/** Render current and retained health refresh status for the TUI. */
+
+export function readRefreshStatus(data: Record<string, unknown> | null): string | null {
+  const refresh = readRecord(data?.refresh);
+  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 "not-attempted":
+      return `refresh attempt not started${formatLastRefreshSuffix(refresh)}`;
+    case "not-requested":
+      return `refresh not requested${formatLastRefreshSuffix(refresh)}`;
+    default:
+      return null;
+  }
+}
+
+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")) {
+    return null;
+  }
+  const attempt = readRecord(refresh.lastAttempt);
+  if (!attempt) return null;
+  const evidence = formatCompactDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  if (attempt.kind === "failed") {
+    return `last ${refreshAttemptLabel(attempt)} failed${evidence ? ` (${evidence})` : ""}`;
+  }
+  if (attempt.kind === "completed") {
+    return `last ${refreshAttemptLabel(attempt)} completed${evidence ? ` (${evidence})` : ""}`;
+  }
+  return null;
+}
+
+function refreshAttemptLabel(attempt: Record<string, unknown>): string {
+  return attempt.operationScope === "file-runtime" ? "file maintenance attempt" : "refresh attempt";
+}
+
+function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
+  const attempt = readRecord(refresh.lastAttempt);
+  if (!attempt) return "";
+  const evidence = formatDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  if (attempt.kind === "failed") {
+    const reason = typeof attempt.reason === "string" ? `: ${attempt.reason}` : "";
+    return `; last ${refreshAttemptLabel(attempt)} failed${reason}${evidence ? `; ${evidence}` : ""}`;
+  }
+  if (attempt.kind === "completed") {
+    return `; last ${refreshAttemptLabel(attempt)} completed${evidence ? `; ${evidence}` : ""}`;
+  }
+  return "";
+}
+
+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`;
+}
+
+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;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function readNumber(value: unknown): number {
+  return typeof value === "number" ? value : 0;
+}