@mrclrchtr/supi-code-intelligence 6.2.0 → 6.4.0

package/src/substrate/lsp/source-tracking.ts

@@ -0,0 +1,247 @@
+import { statSync } from "node:fs";
+import * as path from "node:path";
+import {
+  type CodeRequestControl,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
+import type {
+  BulkTrackFileOutcome,
+  WorkspaceLspRuntime,
+  WorkspaceSourceInventory,
+} from "@mrclrchtr/supi-lsp/api";
+import { isMissingFileError, MAX_BULK_TRACK_FILES } from "@mrclrchtr/supi-lsp/api";
+
+/** Typed session state for sentinel maintenance and automatic source tracking. */
+export interface LspMaintenanceState {
+  readonly sentinelSnapshot: Map<string, number>;
+  readonly sourceBaseline: ReadonlySet<string> | null;
+  readonly createdSourceQueue: readonly string[];
+}
+
+/** Source discovery and tracking facts from one broad diagnostic refresh. */
+export interface SourceTrackingReport {
+  readonly status: WorkspaceSourceInventory["status"];
+  readonly reason: WorkspaceSourceInventory["reason"];
+  readonly observedFileCount: number;
+  readonly discovered: readonly string[];
+  readonly tracked: readonly string[];
+  readonly unsupported: readonly string[];
+  readonly unavailable: readonly string[];
+  readonly deferred: number;
+}
+
+/** Create empty source state with an optional lifecycle-seeded sentinel snapshot. */
+export function createLspMaintenanceState(
+  sentinelSnapshot: Map<string, number> = new Map(),
+): LspMaintenanceState {
+  return {
+    sentinelSnapshot,
+    sourceBaseline: null,
+    createdSourceQueue: [],
+  };
+}
+
+/** Replace the sentinel portion of maintenance state without source state. */
+export function withSentinelSnapshot(
+  state: LspMaintenanceState,
+  sentinelSnapshot: Map<string, number>,
+): LspMaintenanceState {
+  return { ...state, sentinelSnapshot };
+}
+
+/** Discover source additions and process a bounded queue for one refresh. */
+export async function trackCreatedSources(options: {
+  readonly runtime: WorkspaceLspRuntime;
+  readonly cwd: string;
+  readonly state: LspMaintenanceState;
+  readonly scope?: string | null;
+  readonly control?: CodeRequestControl;
+}): Promise<{ state: LspMaintenanceState; report: SourceTrackingReport }> {
+  const inventory = await options.runtime.scanWorkspaceSources(options.control);
+  throwIfCodeRequestInterrupted(options.control);
+  if (inventory.status === "limited") {
+    return {
+      state: options.state,
+      report: createReport({
+        cwd: options.cwd,
+        inventory,
+        discovered: [],
+        tracked: [],
+        unsupported: [],
+        unavailable: [],
+        deferred: options.state.createdSourceQueue,
+        control: options.control,
+      }),
+    };
+  }
+
+  const discovered = discoverCreatedPaths(
+    options.state.sourceBaseline,
+    inventory.files,
+    options.control,
+  );
+  const queue = removeMissingPaths(
+    options.state.sourceBaseline === null
+      ? []
+      : deduplicatePaths([...options.state.createdSourceQueue, ...discovered], options.control),
+    options.control,
+  );
+  const selected = selectScopedPaths(queue, options.cwd, options.scope, options.control).slice(
+    0,
+    MAX_BULK_TRACK_FILES,
+  );
+  const batch =
+    selected.length === 0
+      ? { outcomes: [] as const }
+      : await options.runtime.bulkTrackFiles(selected, options.control);
+  const nextQueue = retainQueuePaths(queue, selected, batch.outcomes, options.control);
+  const nextState: LspMaintenanceState = {
+    sentinelSnapshot: options.state.sentinelSnapshot,
+    sourceBaseline: new Set(inventory.files),
+    createdSourceQueue: nextQueue,
+  };
+
+  const tracked = pathsForOutcome(batch.outcomes, "tracked");
+  const unsupported = pathsForOutcome(batch.outcomes, "unsupported");
+  const unavailable = pathsForOutcome(batch.outcomes, "unavailable");
+  return {
+    state: nextState,
+    report: createReport({
+      cwd: options.cwd,
+      inventory,
+      discovered,
+      tracked,
+      unsupported,
+      unavailable,
+      deferred: nextQueue,
+      control: options.control,
+    }),
+  };
+}
+
+function discoverCreatedPaths(
+  baseline: ReadonlySet<string> | null,
+  current: readonly string[],
+  control?: CodeRequestControl,
+): string[] {
+  if (baseline === null) return [];
+  const discovered: string[] = [];
+  for (const filePath of current) {
+    throwIfCodeRequestInterrupted(control);
+    if (!baseline.has(filePath)) discovered.push(filePath);
+  }
+  return discovered;
+}
+
+function selectScopedPaths(
+  queue: readonly string[],
+  cwd: string,
+  scope: string | null | undefined,
+  control?: CodeRequestControl,
+): string[] {
+  const resolvedScope = scope === null || scope === undefined ? null : path.resolve(cwd, scope);
+  const selected: string[] = [];
+  for (const filePath of queue) {
+    throwIfCodeRequestInterrupted(control);
+    if (resolvedScope === null || isWithinOrEqual(resolvedScope, filePath)) selected.push(filePath);
+  }
+  return selected;
+}
+
+function retainQueuePaths(
+  queue: readonly string[],
+  selected: readonly string[],
+  outcomes: readonly BulkTrackFileOutcome[],
+  control?: CodeRequestControl,
+): string[] {
+  const selectedSet = new Set(selected);
+  const outcomeByPath = new Map(outcomes.map((outcome) => [outcome.file, outcome] as const));
+  const unstarted: string[] = [];
+  const unavailable: string[] = [];
+
+  for (const filePath of queue) {
+    throwIfCodeRequestInterrupted(control);
+    if (!selectedSet.has(filePath)) {
+      unstarted.push(filePath);
+      continue;
+    }
+    const outcome = outcomeByPath.get(filePath);
+    if (!outcome) {
+      unstarted.push(filePath);
+    } else if (outcome.kind === "unavailable") {
+      unavailable.push(filePath);
+    }
+  }
+  return [...unstarted, ...unavailable];
+}
+
+function pathsForOutcome(
+  outcomes: readonly BulkTrackFileOutcome[],
+  kind: BulkTrackFileOutcome["kind"],
+): string[] {
+  return outcomes.filter((outcome) => outcome.kind === kind).map((outcome) => outcome.file);
+}
+
+function createReport(options: {
+  cwd: string;
+  inventory: WorkspaceSourceInventory;
+  discovered: readonly string[];
+  tracked: readonly string[];
+  unsupported: readonly string[];
+  unavailable: readonly string[];
+  deferred: readonly string[];
+  control?: CodeRequestControl;
+}): SourceTrackingReport {
+  return {
+    status: options.inventory.status,
+    reason: options.inventory.reason,
+    observedFileCount: options.inventory.observedFileCount,
+    discovered: displayPaths(options.cwd, options.discovered, options.control),
+    tracked: displayPaths(options.cwd, options.tracked, options.control),
+    unsupported: displayPaths(options.cwd, options.unsupported, options.control),
+    unavailable: displayPaths(options.cwd, options.unavailable, options.control),
+    deferred: options.deferred.length,
+  };
+}
+
+function displayPaths(
+  cwd: string,
+  filePaths: readonly string[],
+  control?: CodeRequestControl,
+): string[] {
+  const displayed: string[] = [];
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    const relativePath = path.relative(cwd, filePath);
+    displayed.push((relativePath || path.basename(filePath)).replaceAll(path.sep, "/"));
+  }
+  return displayed;
+}
+
+function deduplicatePaths(filePaths: readonly string[], control?: CodeRequestControl): string[] {
+  const unique = new Set<string>();
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    unique.add(filePath);
+  }
+  return [...unique];
+}
+
+function removeMissingPaths(filePaths: readonly string[], control?: CodeRequestControl): string[] {
+  const existing: string[] = [];
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    if (!isMissingFile(filePath)) existing.push(filePath);
+  }
+  return existing;
+}
+
+function isMissingFile(filePath: string): boolean {
+  try {
+    statSync(filePath);
+    return false;
+  } catch (error) {
+    return isMissingFileError(error);
+  }
+}

package/src/tool/code_find/guidance.ts

@@ -1,8 +1,8 @@
 export const toolDescription =
-  'Search source shape with mode:"ast" or LSP workspace symbols with mode:"semantic". Modes never silently fall back. Unscoped AST scans cover visible supported files, skipping hidden and generated/dependency directories.';
+  "Search code structure or workspace symbols for structural or semantic matches. It never silently falls back to another mode or to text search.";
 
-export const promptSnippet = "explicit structural or semantic code search";
+export const promptSnippet = "search code structure or workspace symbols";
 
 export const promptGuidelines = [
-  "Use code_find for structural or semantic search evidence; use PI grep for literal/regex source search and code_graph references for symbol-identity relationships.",
+  "Use code_find for structural or semantic search, grep for text search, and code_graph for symbol relationships.",
 ];

package/src/tool/code_graph/guidance.ts

@@ -1,6 +1,6 @@
 export const toolDescription =
-  "Collect references, structural callees, and implementations for one target. Callees match source shape, not symbol identity.";
+  "Find symbol references and implementations, and list calls from a target's enclosing scope. Callee results match source shape, not symbol identity.";
 
-export const promptSnippet = "provider-backed and structural relation evidence";
+export const promptSnippet = "trace code relationships";
 
 export const promptGuidelines: string[] = [];

package/src/tool/code_health/guidance.ts

@@ -1,8 +1,8 @@
 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. 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.",
+  "Use code_health with `refresh: true` before relying on diagnostics that can be stale.",
 ];

package/src/tool/code_health/markdown.ts

@@ -15,6 +15,7 @@ import { makeRelative, renderFileScopeStatus } from "./file-scope-markdown.ts";
 import {
   formatProcessCrashRecovery,
   formatRefreshElapsed,
+  formatSourceTracking,
   formatStaleDiagnosticRestarts as formatStaleDiagnosticRestartsText,
   isFileReadinessPending,
 } from "./refresh-outcome.ts";
@@ -57,8 +58,9 @@ function renderRefreshStatus(
     case "completed": {
       const fileReadinessPending = isFileReadinessPending(data.refresh, data.semanticState);
       lines.push(
-        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh, fileReadinessPending))}`,
+        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh, fileReadinessPending, false))}`,
       );
+      renderSourceTracking(lines, data.refresh);
       lines.push(`**Stale assessment**: ${asSentence(staleAssessmentText(data.refresh))}`);
       lines.push("");
       return;
@@ -74,6 +76,7 @@ function renderRefreshStatus(
       lines.push(
         `**${refreshAttemptLabel(data.refresh)}**: failed — ${data.refresh.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence}`,
       );
+      renderSourceTracking(lines, data.refresh);
       lines.push("");
       return;
     }
@@ -97,6 +100,7 @@ function renderRefreshStatus(
 function completedRefreshText(
   attempt: Extract<HealthRefreshAttempt, { kind: "completed" }>,
   fileReadinessPending = attempt.fileReadiness === "pending",
+  includeSourceTracking = true,
 ): string {
   const processCrashRecovery = formatProcessCrashRecovery(attempt.processCrashRecovery);
   const noOp =
@@ -110,15 +114,26 @@ function completedRefreshText(
       ? "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,
+  ].filter((value): value is string => value !== null);
   const withOutcome = outcome.length > 0 ? `${base}; ${outcome.join("; ")}` : base;
   return attempt.operationScope === "workspace-runtime"
     ? `${withOutcome}; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
     : withOutcome;
 }
 
+function renderSourceTracking(
+  lines: string[],
+  attempt: Pick<HealthRefreshAttempt, "sourceTracking">,
+): void {
+  const sourceTracking = formatSourceTracking(attempt.sourceTracking);
+  if (sourceTracking) lines.push(`**Source discovery**: ${asSentence(sourceTracking)}`);
+}
+
 function refreshAttemptLabel(attempt: Pick<HealthRefreshAttempt, "operationScope">): string {
   return attempt.operationScope === "file-runtime"
     ? "File LSP maintenance attempt"
@@ -160,10 +175,11 @@ function refreshAttemptOutcome(attempt: HealthRefreshAttempt): string {
     ? formatProcessCrashRecovery(attempt.processCrashRecovery)
     : null;
   const staleRestart = formatStaleDiagnosticRestarts(attempt);
+  const sourceTracking = formatSourceTracking(attempt.sourceTracking);
   const evidence = attempt.diagnosticEvidence
     ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
     : "";
-  return `failed — ${attempt.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence}`;
+  return `failed — ${attempt.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${sourceTracking ? `; ${sourceTracking}` : ""}${evidence}`;
 }
 
 function refreshOperationScopeText(attempt: HealthRefreshAttempt): string {

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

@@ -1,5 +1,9 @@
-import type { ProcessCrashRecoverySummary } from "@mrclrchtr/supi-lsp/api";
+import type {
+  ProcessCrashRecoveryEntry,
+  ProcessCrashRecoveryReport,
+} 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(
@@ -21,17 +25,54 @@ export function formatStaleDiagnosticRestarts(restartedClients: number): string
   return `stale diagnostic restarts: ${restartedClients} client${plural(restartedClients)} restarted`;
 }
 
-/** Format a non-empty process-crash route recovery outcome. */
-export function formatProcessCrashRecovery(
-  summary: ProcessCrashRecoverySummary | null | undefined,
+/** Format process-crash counts for the compact health view. */
+export function formatCompactProcessCrashRecovery(
+  report: ProcessCrashRecoveryReport | null | undefined,
 ): string | null {
   if (
-    !summary ||
-    (summary.attemptedRoutes === 0 && summary.recoveredRoutes === 0 && summary.failedRoutes === 0)
+    !report ||
+    (report.recoveredRoutes === 0 &&
+      report.skippedRoutes === 0 &&
+      report.failedRoutes === 0 &&
+      report.exhaustedRoutes === 0)
   ) {
     return null;
   }
-  return `process-crash recovery: ${summary.recoveredRoutes} route${plural(summary.recoveredRoutes)} recovered (${summary.attemptedRoutes} attempted, ${summary.failedRoutes} failed)`;
+  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 source discovery and bounded tracking counts separately from diagnostics. */
+export function formatSourceTracking(
+  report: SourceTrackingReport | null | undefined,
+): string | null {
+  if (!report) return null;
+  const inventory =
+    report.status === "complete" ? "complete" : `limited (${report.reason ?? "unknown reason"})`;
+  return `source discovery: ${inventory}; ${report.observedFileCount} source files observed, ${report.discovered.length} discovered, ${report.tracked.length} tracked, ${report.unsupported.length} unsupported, ${report.unavailable.length} unavailable, ${report.deferred} deferred`;
 }
 
 /** Format the age of a retained refresh attempt for a status line. */

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

@@ -1,5 +1,11 @@
-import type { ProcessCrashRecoverySummary } from "@mrclrchtr/supi-lsp/api";
 import {
+  MAX_PROCESS_CRASH_RECOVERY_ENTRIES,
+  type ProcessCrashRecoveryEntry,
+  type ProcessCrashRecoveryOutcome,
+  type ProcessCrashRecoveryReport,
+} from "@mrclrchtr/supi-lsp/api";
+import {
+  formatCompactProcessCrashRecovery,
   formatProcessCrashRecovery,
   formatStaleDiagnosticRestarts,
   isFileReadinessPending,
@@ -8,6 +14,14 @@ 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.unsupported)} unsupported, ${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;
@@ -82,19 +96,21 @@ export function readCompactRefreshStatus(data: Record<string, unknown> | null):
   const refresh = readRecord(data?.refresh);
   if (!refresh || (refresh.kind !== "completed" && refresh.kind !== "failed")) return null;
 
-  const processCrashRecovery = formatProcessCrashRecovery(
+  const sourceTracking = formatSourceTracking(readRecord(refresh.sourceTracking));
+  const processCrashRecovery = formatCompactProcessCrashRecovery(
     readProcessCrashRecovery(refresh.processCrashRecovery),
   );
   if (refresh.kind === "failed") {
     const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
     return (
-      [staleRestart, processCrashRecovery]
+      [sourceTracking, staleRestart, processCrashRecovery]
         .filter((value): value is string => value !== null)
         .join("; ") || null
     );
   }
   const fileReadinessPending = isPendingFileReadiness(data);
   if (
+    !sourceTracking &&
     !processCrashRecovery &&
     readNumber(refresh.restartedClients) === 0 &&
     !fileReadinessPending
@@ -104,7 +120,7 @@ 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 [sourceTracking, staleRestart, processCrashRecovery, readiness]
     .filter((value): value is string => value !== null)
     .join("; ");
 }
@@ -117,7 +133,8 @@ 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 = formatProcessCrashRecovery(
+  const sourceTracking = formatSourceTracking(readRecord(attempt.sourceTracking));
+  const processCrashRecovery = formatCompactProcessCrashRecovery(
     readProcessCrashRecovery(attempt.processCrashRecovery),
   );
   const staleRestart = formatStaleDiagnosticRestartsForRecord(attempt);
@@ -125,7 +142,7 @@ export function readPreviousRefreshStatus(data: Record<string, unknown> | null):
     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, sourceTracking, staleRestart, processCrashRecovery, evidence]
     .filter((value): value is string => value !== null)
     .join("; ");
   if (attempt.kind === "failed") {
@@ -164,6 +181,7 @@ function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   const attempt = readRecord(refresh.lastAttempt);
   if (!attempt) return "";
   const evidence = formatDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  const sourceTracking = formatSourceTracking(readRecord(attempt.sourceTracking));
   const staleRestart = formatStaleDiagnosticRestartsForRecord(attempt);
   const processCrashRecovery = formatProcessCrashRecovery(
     readProcessCrashRecovery(attempt.processCrashRecovery),
@@ -171,7 +189,7 @@ function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   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, sourceTracking, staleRestart, processCrashRecovery, evidence]
     .filter((value): value is string => value !== null)
     .join("; ");
   if (attempt.kind === "failed") {
@@ -185,6 +203,15 @@ function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   return "";
 }
 
+function formatSourceTracking(source: Record<string, unknown> | null): string | null {
+  const status = readSourceTrackingStatus(source);
+  return status ? `source discovery ${status}` : null;
+}
+
+function readArrayLength(value: unknown): number {
+  return Array.isArray(value) ? value.length : 0;
+}
+
 function formatCompactDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
   const counts = readEvidenceCounts(evidence);
   if (!counts) return null;
@@ -207,20 +234,60 @@ export function isPendingFileReadiness(data: Record<string, unknown> | null): bo
   return isFileReadinessPending(attempt, readSemanticHealthState(data?.semanticState));
 }
 
-function readProcessCrashRecovery(value: unknown): ProcessCrashRecoverySummary | null {
-  const summary = readRecord(value);
-  if (!summary) return null;
-  const attemptedRoutes = summary.attemptedRoutes;
-  const recoveredRoutes = summary.recoveredRoutes;
-  const failedRoutes = summary.failedRoutes;
+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(attemptedRoutes) ||
     !isEvidenceCount(recoveredRoutes) ||
-    !isEvidenceCount(failedRoutes)
+    !isEvidenceCount(skippedRoutes) ||
+    !isEvidenceCount(failedRoutes) ||
+    !isEvidenceCount(exhaustedRoutes) ||
+    !isEvidenceCount(omittedEntries) ||
+    !Array.isArray(report.entries) ||
+    report.entries.length > MAX_PROCESS_CRASH_RECOVERY_ENTRIES
   ) {
     return null;
   }
-  return { attemptedRoutes, recoveredRoutes, failedRoutes };
+  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 {

package/src/tool/code_health/tui.ts

@@ -29,6 +29,7 @@ import {
   readCompactRefreshStatus,
   readPreviousRefreshStatus,
   readRefreshStatus,
+  readSourceTrackingStatus,
 } from "./refresh-status.ts";
 import { formatSemanticHealthState, readSemanticHealthState } from "./semantic-state.ts";
 
@@ -192,6 +193,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 +207,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);
 }

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_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.",
 ];