@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

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

@@ -3,17 +3,34 @@ 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. */
 
+/** Read source discovery counts from structured health details. */
+export function readSourceTrackingStatus(source: Record<string, unknown> | null): string | 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.skipped)} skipped, ${readArrayLength(source.unavailable)} unavailable, ${readNumber(source.deferred)} deferred`;
+}
+
 export function readRefreshStatus(data: Record<string, unknown> | null): string | null {
   const refresh = readRecord(data?.refresh);
   if (!refresh) return null;
@@ -41,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`
@@ -63,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;
 }
 
@@ -88,20 +121,25 @@ export function readCompactRefreshStatus(data: Record<string, unknown> | null):
   const refresh = readRecord(data?.refresh);
   if (!refresh || (refresh.kind !== "completed" && refresh.kind !== "failed")) return null;
 
+  const sourceTracking = formatSourceTracking(readRecord(refresh.sourceTracking));
   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 (
-      [staleRestart, processCrashRecovery]
+      [maintenanceScope, sourceTracking, staleRestart, processCrashRecovery, startupRetry]
         .filter((value): value is string => value !== null)
         .join("; ") || null
     );
   }
   const fileReadinessPending = isPendingFileReadiness(data);
   if (
+    !sourceTracking &&
     !processCrashRecovery &&
+    !startupRetry &&
     readNumber(refresh.restartedClients) === 0 &&
     !fileReadinessPending
   ) {
@@ -110,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 [staleRestart, processCrashRecovery, readiness]
+  return [
+    maintenanceScope,
+    sourceTracking,
+    staleRestart,
+    processCrashRecovery,
+    startupRetry,
+    readiness,
+  ]
     .filter((value): value is string => value !== null)
     .join("; ");
 }
@@ -122,16 +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, 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") {
@@ -169,15 +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, 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") {
@@ -191,16 +256,13 @@ function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   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 formatSourceTracking(source: Record<string, unknown> | null): string | null {
+  const status = readSourceTrackingStatus(source);
+  return status ? `source discovery ${status}` : null;
 }
 
-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 readArrayLength(value: unknown): number {
+  return Array.isArray(value) ? value.length : 0;
 }
 
 export function isPendingFileReadiness(data: Record<string, unknown> | null): boolean {
@@ -213,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;
@@ -246,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;
   }
@@ -269,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(

package/src/tool/code_health/tui.ts

@@ -3,7 +3,7 @@
  */
 
 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 {
   formatProjectServerRouteStatusCounts,
   type ProjectServerRouteStatusCounts,
@@ -29,7 +29,13 @@ import {
   readCompactRefreshStatus,
   readPreviousRefreshStatus,
   readRefreshStatus,
+  readSourceTrackingStatus,
 } from "./refresh-status.ts";
+import {
+  formatCompactDiagnosticEvidence,
+  formatDiagnosticEvidence,
+  withDiagnosticScope,
+} from "./scope.ts";
 import { formatSemanticHealthState, readSemanticHealthState } from "./semantic-state.ts";
 
 /** ── renderCall ────────────────────────────────────────────────── */
@@ -63,12 +69,16 @@ export function renderHealthResult(
   options: ResultOptios,
   theme: Theme,
   context: ToolRendererContext | undefined,
-): Container | Text {
+): Component {
   if (options.isPartial) return renderPartial("Gathering workspace health…", theme);
 
   const data =
     result.details?.type === "health" ? (result.details.data as Record<string, unknown>) : null;
-  const executionError = renderExecutionError(context, "code_health failed", theme);
+  const executionError = renderExecutionError(
+    result,
+    { isError: context?.isError, expanded: options.expanded, label: "code_health failed" },
+    theme,
+  );
   if (executionError) return executionError;
   const domainError = renderDomainError(result, theme);
   if (domainError) return renderDomainResult(result, options, theme, domainError);
@@ -135,7 +145,7 @@ function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme)
     formatSectionSummary(
       section,
       section.key === "diagnostics"
-        ? formatCompactDiagnosticEvidence(readDiagnosticEvidence(data))
+        ? formatCompactDiagnosticEvidence(readDiagnosticEvidence(data), diagnosticScopeKind(data))
         : null,
       theme,
       fileReadinessPending,
@@ -192,6 +202,8 @@ function buildStatusBar(data: Record<string, unknown> | null, theme: Theme): Tex
   const semanticStatus = readSemanticStatus(data);
   const structuralStatus = readString(data, "structuralStatus");
   const refreshStatus = readRefreshStatus(data);
+  const refresh = readRecord(data?.refresh);
+  const sourceTracking = readSourceTrackingStatus(readRecord(refresh?.sourceTracking));
 
   const lspColor = semanticStatus.startsWith("ready") ? "success" : "warning";
   const structuralColor = structuralStatus === "ready" ? "success" : "muted";
@@ -204,6 +216,7 @@ function buildStatusBar(data: Record<string, unknown> | null, theme: Theme): Tex
     lines.push(`Tree-sitter: ${theme.fg(structuralColor, structuralStatus)}`);
   }
   if (refreshStatus) lines.push(`Diagnostics: ${theme.fg("dim", refreshStatus)}`);
+  if (sourceTracking) lines.push(`Source discovery: ${theme.fg("dim", sourceTracking)}`);
 
   return new Text(lines.join("  "), 0, 0);
 }
@@ -226,36 +239,6 @@ function readDiagnosticEvidence(
   return readRecord(readRecord(data?.diagnosticObservation)?.evidence);
 }
 
-function formatCompactDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
-  if (!evidence) return null;
-  const counts = [
-    evidence.requested,
-    evidence.confirmed,
-    evidence.unconfirmed,
-    evidence.failed,
-    evidence.removed,
-  ];
-  if (!counts.every(isEvidenceCount)) return null;
-  return `req ${evidence.requested} · conf ${evidence.confirmed} · unconf ${evidence.unconfirmed} · failed ${evidence.failed} · removed ${evidence.removed}`;
-}
-
-function formatDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
-  if (!evidence) return null;
-  const counts = [
-    evidence.requested,
-    evidence.confirmed,
-    evidence.unconfirmed,
-    evidence.failed,
-    evidence.removed,
-  ];
-  if (!counts.every(isEvidenceCount)) return null;
-  return `${evidence.requested} requested, ${evidence.confirmed} confirmed, ${evidence.unconfirmed} unconfirmed, ${evidence.failed} failed, ${evidence.removed} removed`;
-}
-
-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;
 }
@@ -320,21 +303,29 @@ function buildDiagnosticSummary(data: Record<string, unknown> | null, theme: The
     const label = isPendingFileReadiness(data)
       ? "Diagnostics pending — LSP may still be warming; retry shortly"
       : "Diagnostics unavailable";
-    return new Text(theme.fg("warning", label), 0, 0);
+    return new Text(theme.fg("warning", withDiagnosticScope(label, data)), 0, 0);
   }
   const trackedFiles = diagnosticScopeKind(data) === "tracked-files";
   if (section.status === "partial") {
     const coverage = formatDiagnosticEvidence(readDiagnosticEvidence(data));
     const label = trackedFiles ? "Tracked-file diagnostics partial" : "Diagnostics partial";
-    return new Text(theme.fg("warning", coverage ? `${label} (${coverage})` : label), 0, 0);
+    const summary = coverage ? `${label} (${coverage})` : label;
+    return new Text(theme.fg("warning", withDiagnosticScope(summary, data)), 0, 0);
   }
   if (section.itemCount === 0) {
-    return new Text(theme.fg("success", diagnosticEmptySummary(data)), 0, 0);
+    return new Text(
+      theme.fg("success", withDiagnosticScope(diagnosticEmptySummary(data), data)),
+      0,
+      0,
+    );
   }
 
   const fileLabel = `${trackedFiles ? "tracked " : ""}${section.itemCount === 1 ? "file" : "files"}`;
   return new Text(
-    theme.fg("warning", theme.bold(`${section.itemCount} ${fileLabel} with issues`)),
+    theme.fg(
+      "warning",
+      theme.bold(withDiagnosticScope(`${section.itemCount} ${fileLabel} with issues`, data)),
+    ),
     0,
     0,
   );

package/src/tool/code_inspect/guidance.ts

@@ -1,6 +1,8 @@
 export const toolDescription =
-  "Inspect one exact point for syntax, the narrowest enclosing declaration, hover, definition, and nearby diagnostics. Use for point facts, not broad Orientation.";
+  "Inspect one source location for syntax, its enclosing declaration, hover information, definitions, and nearby diagnostics. Use it for point-local facts, not broad code context.";
 
-export const promptSnippet = "factual point inspection";
+export const promptSnippet = "inspect a source location";
 
-export const promptGuidelines: string[] = [];
+export const promptGuidelines = [
+  "Use code_inspect for diagnostics near a source location; use code_health for broader diagnostics or language-server status.",
+];

package/src/tool/code_inspect/tui.ts

@@ -40,5 +40,11 @@ export function renderInspectResult(
   theme: Theme,
   context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Inspecting…", context);
+  return renderSimpleResult(
+    result,
+    options,
+    theme,
+    { progress: "Inspecting…", failure: "code_inspect failed" },
+    context,
+  );
 }

package/src/tool/code_orientation/guidance.ts

@@ -1,9 +1,8 @@
 export const toolDescription =
-  "Orient around the workspace or one path, module, or target focus before surgical work. Omit focus for workspace Orientation. Workspace Orientation includes manifest and dependency inventories. For one-file work, use focused path Orientation. Directory focus may surface local instruction files.";
+  "Return observed workspace or focused code context to choose what source to inspect next. Omit `focus` for workspace context. A directory focus can surface local instruction files.";
 
-export const promptSnippet = "workspace/path/module/symbol Orientation";
+export const promptSnippet = "orient around workspace or code context";
 
 export const promptGuidelines = [
-  "Use code_orientation before broad file reading when you need direct workspace, package, directory, file, or symbol facts.",
-  "Use code_graph for relationships and code_health for provider or diagnostic state.",
+  "Use code_orientation before broad source reading when workspace or path context can narrow the files.",
 ];

package/src/tool/code_orientation/result.ts

@@ -1,5 +1,8 @@
 import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
-import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
+import {
+  type EvidenceListMetadata,
+  renderEvidenceListMetadataDisclosure,
+} from "../../analysis/evidence.ts";
 import type { ReadNextItem } from "../../analysis/read-next.ts";
 import type {
   OrientationCandidate,
@@ -15,6 +18,7 @@ import {
   type ResultSection,
   type ToolResultAssembly,
 } from "../result/assembly.ts";
+import { formatCandidateRow } from "../result/candidate-row.ts";
 import { createToolDisplaySection } from "../result/display.ts";
 import type {
   ContextDetails,
@@ -47,17 +51,17 @@ export interface OrientationResultAssembly {
 /** Build structured candidate rows for an unresolved Orientation target. */
 export function orientationCandidateDisplaySections(
   candidates: readonly OrientationCandidate[],
-  omittedCount = 0,
+  evidence: EvidenceListMetadata,
 ): readonly ToolDisplaySection[] {
   return [
     createToolDisplaySection({
       key: "orientation.candidates",
       title: "Candidates",
       items: candidates,
-      totalCount: candidates.length + omittedCount,
-      omittedCount,
-      format: (candidate) =>
-        `${candidate.rank}. ${candidate.name} (${candidate.kind ?? "unknown"}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`,
+      totalCount: evidence.totalCount,
+      omittedCount: evidence.omittedCount,
+      partialReason: evidence.partialReason,
+      format: (candidate) => formatCandidateRow(candidate, "rank-first"),
     }),
   ];
 }
@@ -215,13 +219,23 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
         `${candidate.rank}. **${candidate.name}** (\`${candidate.kind ?? "unknown"}\`) — \`${candidate.file}\`:${candidate.line}:${candidate.character} — \`${candidate.targetId}\``,
       );
     }
+    const evidence: EvidenceListMetadata = {
+      key: "orientation.candidates",
+      totalCount: outcome.totalCount,
+      shownCount: candidates.length,
+      omittedCount: outcome.omittedCount,
+      partialReason: outcome.partialReason,
+    };
+    const disclosure = renderEvidenceListMetadataDisclosure(evidence);
+    if (disclosure) lines.push("", disclosure);
     const nextQueries =
       outcome.kind === "kind-mismatch"
         ? ["Retry without symbolKind, use an observed provider kind, or focus one handle"]
         : ["Use one candidate handle as focus.target.handle"];
     const details = assembleOrientationDetails({
       confidence: "semantic",
-      omittedCount: outcome.omittedCount,
+      omittedCount: evidence.omittedCount ?? 0,
+      evidenceLists: [evidence],
       candidates,
       nextQueries,
     });
@@ -231,7 +245,8 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
         type: "context",
         data: details,
         status: "completed",
-        displaySections: orientationCandidateDisplaySections(candidates, outcome.omittedCount),
+        message: orientationSelectionMessage(outcome),
+        displaySections: orientationCandidateDisplaySections(candidates, evidence),
       },
     };
   }
@@ -246,3 +261,11 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
     },
   };
 }
+
+function orientationSelectionMessage(
+  outcome: Extract<OrientationOutcome, { kind: "disambiguation" | "kind-mismatch" }>,
+): string {
+  return outcome.kind === "kind-mismatch"
+    ? `No Orientation target matched provider kind ${outcome.requestedKind}.`
+    : "Multiple Orientation targets require one candidate.";
+}