@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

package/src/analysis/health/server-status.ts

@@ -57,7 +57,7 @@ export function formatProjectServerStatusReason(
     case "process-crash-recovery-pending":
       return "process recovery in progress";
     case "process-crash-recovery-exhausted":
-      return "process recovery exhausted; reload required";
+      return "process recovery exhausted; try another explicit health refresh";
     default:
       return null;
   }

package/src/analysis/relations/callees.ts

@@ -11,6 +11,8 @@ export interface CalleesResult {
   enclosingScope: CalleeScope | null;
   callees: CalleeEntry[];
   confidence: "structural" | "unavailable";
+  /** Original provider reason when callee evidence is unavailable. */
+  message: string | null;
   depth: "direct" | "deep";
 }
 
@@ -30,7 +32,7 @@ export async function collectCallees(
   control?: CodeRequestControl,
 ): Promise<CalleesResult> {
   if (!deps.provider?.calleesAt) {
-    return unavailableCallees(targetName);
+    return unavailableCallees(targetName, "No structural callee provider", depth);
   }
 
   const depthOrOptions = control ? { depth, control } : depth;
@@ -40,8 +42,8 @@ export async function collectCallees(
     targetCharacter,
     depthOrOptions,
   );
-  if (result.kind !== "success" || !result.data) {
-    return unavailableCallees(targetName);
+  if (result.kind !== "success") {
+    return unavailableCallees(targetName, result.message, depth);
   }
 
   void maxResults;
@@ -53,9 +55,10 @@ export async function collectCallees(
   );
   const callees: CalleeEntry[] = result.data.callees.map((c) => ({
     name: c.name,
-    file: c.file ?? c.location ?? targetFile,
-    line: c.startLine ?? targetLine,
-    character: c.startCharacter ?? targetCharacter,
+    ...(c.displayName ? { displayName: c.displayName } : {}),
+    file: targetFile,
+    line: c.startLine,
+    character: c.startCharacter,
   }));
 
   return {
@@ -64,18 +67,24 @@ export async function collectCallees(
     enclosingScope,
     callees,
     confidence: "structural",
+    message: null,
     depth: result.data.depth ?? depth,
   };
 }
 
-function unavailableCallees(targetName: string | null): CalleesResult {
+function unavailableCallees(
+  targetName: string | null,
+  message: string,
+  depth: "direct" | "deep",
+): CalleesResult {
   return {
     kind: "callees",
     targetName: targetName ?? "symbol",
     enclosingScope: null,
     callees: [],
     confidence: "unavailable",
-    depth: "direct",
+    message,
+    depth,
   };
 }
 

package/src/analysis/relations/implementations.ts

@@ -73,8 +73,7 @@ export async function collectImplementations(
     implementations: project,
     externalCount: normalized.external.length,
     invalidLocationCount: normalized.invalidLocationCount,
-    partialReason:
-      normalized.partialReason ?? (result.kind === "partial" ? "provider-limited" : null),
+    partialReason: result.kind === "partial" ? "provider-limited" : normalized.partialReason,
     confidence: "semantic",
   };
 }

package/src/analysis/relations/references.ts

@@ -13,7 +13,7 @@ import {
 } from "./provider-locations.ts";
 import type { CallerEvidence, CallerReference, RelationsServiceDeps } from "./types.ts";
 
-export interface CallersResult {
+interface CallerEvidenceData {
   kind: "callers";
   targetName: string;
   references: CallerReference[];
@@ -22,9 +22,12 @@ export interface CallersResult {
   invalidLocationCount: number;
   partialReason: RelationLocationPartialReason | null;
   evidence: CallerEvidence;
-  confidence: "semantic" | "unavailable";
 }
 
+/** Reference evidence, or the provider reason that prevented collection. */
+export type CallersResult = CallerEvidenceData &
+  ({ confidence: "semantic" } | { confidence: "unavailable"; message: string });
+
 /**
  * Collect callers (references) for a target file/position using semantic provider.
  */
@@ -46,6 +49,7 @@ export async function collectCallers(
       partialReason: null,
       evidence: "semantic-references",
       confidence: "unavailable",
+      message: "No semantic references provider",
     };
   }
 
@@ -60,6 +64,7 @@ export async function collectCallers(
       partialReason: null,
       evidence: "semantic-references",
       confidence: "unavailable",
+      message: result.reason,
     };
   }
 
@@ -77,8 +82,7 @@ export async function collectCallers(
     references: inProject,
     externalCount: normalized.external.length,
     invalidLocationCount: normalized.invalidLocationCount,
-    partialReason:
-      normalized.partialReason ?? (result.kind === "partial" ? "provider-limited" : null),
+    partialReason: result.kind === "partial" ? "provider-limited" : normalized.partialReason,
     evidence: "semantic-references",
     confidence: "semantic",
   };

package/src/analysis/relations/types.ts

@@ -1,4 +1,4 @@
-import type { CodeRequestControl, SemanticProvider } from "@mrclrchtr/supi-code-runtime/api";
+import type { SemanticProvider, StructuralProvider } from "@mrclrchtr/supi-code-runtime/api";
 
 /**
  * Shared types for the relations analysis modules.
@@ -32,13 +32,15 @@ export interface CalleeScope {
 /** One direct structural callee entry from an enclosing-scope lookup. */
 export interface CalleeEntry {
   name: string;
+  /** Syntax-based preview only; the full name remains the grouping key. */
+  displayName?: string;
   file: string;
   line: number;
   character: number;
 }
 
-/** Consumer-facing display entry for structural calls (no character). */
-export type CallEntry = Omit<CalleeEntry, "character">;
+/** One structural call site with a 1-based UTF-16 coordinate. */
+export type CallEntry = CalleeEntry;
 
 /** One implementation entry from a semantic implementation lookup. */
 export interface ImplementationEntry {
@@ -54,32 +56,6 @@ export interface RelationsServiceDeps {
   provider: {
     references?: SemanticProvider["references"];
     implementation?: SemanticProvider["implementation"];
-    calleesAt?: (
-      file: string,
-      line: number,
-      character: number,
-      depthOrOptions?:
-        | "direct"
-        | "deep"
-        | { depth?: "direct" | "deep"; control?: CodeRequestControl },
-    ) => Promise<{
-      kind: string;
-      data?: {
-        enclosingScope?: {
-          name?: string;
-          startLine?: number;
-          endLine?: number;
-        };
-        callees: Array<{
-          name: string;
-          file?: string;
-          location?: string;
-          startLine?: number;
-          startCharacter?: number;
-        }>;
-        depth?: "direct" | "deep";
-      };
-      message?: string;
-    }>;
+    calleesAt?: StructuralProvider["calleesAt"];
   } | null;
 }

package/src/analysis/target/anchored.ts

@@ -191,7 +191,9 @@ async function candidatesFromSymbols(
 ): Promise<{
   kind: "disambiguation";
   candidates: DisambiguationCandidateData[];
+  totalCount: number;
   omittedCount: number;
+  partialReason: null;
 }> {
   const candidates = await Promise.all(
     matched.map(async (s, idx) => {
@@ -215,7 +217,13 @@ async function candidatesFromSymbols(
       } satisfies DisambiguationCandidateData;
     }),
   );
-  return { kind: "disambiguation", candidates, omittedCount: 0 };
+  return {
+    kind: "disambiguation",
+    candidates,
+    totalCount: candidates.length,
+    omittedCount: 0,
+    partialReason: null,
+  };
 }
 
 /** Layer 1: match the coordinate against LSP document symbols. Returns null to fall through. */

package/src/analysis/target/symbol.ts

@@ -18,7 +18,11 @@ import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
 import type { TargetSymbolKind } from "../../session/target-input.ts";
 import type { AnchorKind } from "../../session/target-store.ts";
 import { normalizePath } from "../search/paths.ts";
-import type { DisambiguationCandidateData, TargetOutcome } from "./types.ts";
+import type {
+  DisambiguationCandidateData,
+  TargetCandidateCompleteness,
+  TargetOutcome,
+} from "./types.ts";
 
 const MAX_CANDIDATES = 8; // default fallback when maxResults is not provided
 const NON_EXPORTED_KINDS = new Set(["Variable", "Field", "Property"]);
@@ -146,6 +150,7 @@ export async function resolveSymbolTarget(
       return buildCandidateOutcome({
         kind: "kind-mismatch",
         candidates: eligible,
+        ...candidateCompleteness(result, eligible.length),
         semantic,
         cwd,
         maxResults: options.maxResults,
@@ -155,6 +160,7 @@ export async function resolveSymbolTarget(
     }
     return resolveCandidates({
       candidates: exactKind,
+      ...candidateCompleteness(result, exactKind.length),
       semantic,
       cwd,
       maxResults: options.maxResults,
@@ -164,6 +170,7 @@ export async function resolveSymbolTarget(
 
   return resolveCandidates({
     candidates: eligible,
+    ...candidateCompleteness(result, eligible.length),
     semantic,
     cwd,
     maxResults: options?.maxResults,
@@ -179,19 +186,15 @@ function normalizeProviderKind(kind: string): string {
   return kind.replace(/[\s_-]/g, "").toLowerCase();
 }
 
-async function resolveCandidates(options: {
-  candidates: readonly CodeSymbol[];
-  semantic: SemanticSubstrate;
-  cwd: string;
-  maxResults?: number;
-  control?: CodeRequestControl;
-}): Promise<TargetOutcome> {
-  const { candidates, semantic, cwd, maxResults, control } = options;
+async function resolveCandidates(
+  options: CandidateOutcomeBase & Pick<TargetCandidateCompleteness, "totalCount" | "partialReason">,
+): Promise<TargetOutcome> {
+  const { candidates, semantic, cwd, maxResults, control, totalCount, partialReason } = options;
   const ranged = candidates.filter(
     (candidate) =>
       candidate.declarationAnchor.line > 0 || candidate.declarationAnchor.character > 0,
   );
-  if (ranged.length === 1) {
+  if (ranged.length === 1 && totalCount !== null) {
     return resolvedTarget(await refineResolvedSymbolAnchor(ranged[0], semantic, control));
   }
   return buildCandidateOutcome({
@@ -200,6 +203,8 @@ async function resolveCandidates(options: {
     semantic,
     cwd,
     maxResults,
+    totalCount,
+    partialReason,
     control,
   });
 }
@@ -230,13 +235,24 @@ interface CandidateOutcomeBase {
   semantic: SemanticSubstrate;
   cwd: string;
   maxResults?: number;
+  control?: CodeRequestControl;
+}
+
+function candidateCompleteness(
+  result: Exclude<CodeQueryResult<CodeSymbol[]>, { kind: "unavailable" }>,
+  totalCount: number,
+): Pick<TargetCandidateCompleteness, "totalCount" | "partialReason"> {
+  return result.kind === "partial"
+    ? { totalCount: null, partialReason: "provider-limited" }
+    : { totalCount, partialReason: null };
 }
 
 type CandidateOutcomeOptions = CandidateOutcomeBase &
+  Pick<TargetCandidateCompleteness, "totalCount" | "partialReason"> &
   (
     | { kind: "disambiguation"; requestedKind?: never }
     | { kind: "kind-mismatch"; requestedKind: TargetSymbolKind }
-  ) & { control?: CodeRequestControl };
+  );
 
 /**
  * Refine only bounded visible candidates to name anchors while retaining the
@@ -271,7 +287,9 @@ async function buildCandidateOutcome(
   );
   const common = {
     candidates: toDisambiguationCandidates(refined, options.cwd),
+    totalCount: options.totalCount,
     omittedCount: Math.max(0, options.candidates.length - cap),
+    partialReason: options.partialReason,
   };
   return options.kind === "kind-mismatch"
     ? {

package/src/analysis/target/types.ts

@@ -136,6 +136,16 @@ export interface DisambiguationCandidateData {
   anchorKind: AnchorKind;
 }
 
+/** Completeness metadata for a bounded candidate collection. */
+export interface TargetCandidateCompleteness {
+  /** Exact candidate total, or null when the provider returned partial data. */
+  totalCount: number | null;
+  /** Candidates returned by the provider but hidden by the target cap. */
+  omittedCount: number;
+  /** Why the provider cannot establish an exact candidate total. */
+  partialReason: "provider-limited" | null;
+}
+
 /**
  * Typed outcome of a resolution attempt.
  *
@@ -145,16 +155,14 @@ export interface DisambiguationCandidateData {
 export type TargetOutcome =
   | { kind: "resolved"; target: ResolvedTargetData }
   | { kind: "group"; group: ResolvedTargetGroupData }
-  | {
+  | ({
       kind: "disambiguation";
       candidates: DisambiguationCandidateData[];
-      omittedCount: number;
-    }
-  | {
+    } & TargetCandidateCompleteness)
+  | ({
       kind: "kind-mismatch";
       requestedKind: TargetSymbolKind;
       candidates: DisambiguationCandidateData[];
-      omittedCount: number;
-    }
+    } & TargetCandidateCompleteness)
   | { kind: "unavailable"; reason: string }
   | { kind: "error"; message: string };

package/src/api.ts

@@ -61,6 +61,8 @@ export type {
   CodeIntelResultDetails,
   ContextDetails,
   DisambiguationCandidate,
+  GraphDetails,
+  GraphSectionDetails,
   HealthDetails,
   HealthSectionDetails,
   InspectDetails,

package/src/session/graph/collect.ts

@@ -7,6 +7,7 @@ import {
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { CodeProvider } from "../../analysis/provider.ts";
 import {
+  readNextAround,
   readNextEnclosingScope,
   readNextTarget,
   readNextTopSites,
@@ -75,7 +76,7 @@ async function collectReferences(options: CollectRelationOptions): Promise<Graph
     },
   });
   if (result.confidence === "unavailable") {
-    return { kind: "unavailable", rel: "references", message: "References unavailable" };
+    return { kind: "unavailable", rel: "references", message: result.message };
   }
 
   const targetLine = options.position.line + 1;
@@ -132,7 +133,11 @@ async function collectCalleesRelation(options: CollectRelationOptions): Promise<
     options.requestControl,
   );
   if (result.confidence === "unavailable") {
-    return { kind: "unavailable", rel: "callees", message: "Callees unavailable" };
+    return {
+      kind: "unavailable",
+      rel: "callees",
+      message: `${result.message ?? "Callees unavailable"}\nUse code_inspect at the target position to check the scope.`,
+    };
   }
 
   const enclosingScope = result.enclosingScope ?? {
@@ -143,8 +148,10 @@ async function collectCalleesRelation(options: CollectRelationOptions): Promise<
   };
   const calls: CallEntry[] = result.callees.map((callee) => ({
     name: callee.name,
+    ...(callee.displayName ? { displayName: callee.displayName } : {}),
     file: callee.file,
     line: callee.line,
+    character: callee.character,
   }));
   return {
     kind: "ok",
@@ -192,6 +199,14 @@ async function collectImplementationsRelation(
       invalidLocationCount: result.invalidLocationCount,
       partialReason: result.partialReason,
     },
-    readNext: [],
+    readNext: result.implementations
+      .slice(0, Math.min(options.maxResults, 2))
+      .map((implementation) =>
+        readNextAround(
+          toDisplayPath(options.cwd, implementation.file),
+          implementation.line,
+          "inspect an implementation site",
+        ),
+      ),
   };
 }

package/src/session/health-refresh.ts

@@ -4,12 +4,15 @@ import {
 } from "@mrclrchtr/supi-code-runtime/api";
 import {
   emptyProcessCrashRecoveryReport,
+  emptyStartupRetryReport,
+  type SemanticReadinessResult,
   type WorkspaceDiagnosticReport,
   type WorkspaceLspRuntime,
 } from "@mrclrchtr/supi-lsp/api";
 import { recoverDiagnosticRuntime } from "../analysis/health/recovery.ts";
 import { mergeDiagnosticEvidence } from "../diagnostics/evidence.ts";
 import { refreshFileLspMaintenance, refreshLspMaintenance } from "../substrate/lsp/maintenance.ts";
+import type { LspMaintenanceState } from "../substrate/lsp/source-tracking.ts";
 import type {
   HealthDiagnosticScope,
   HealthFileReadiness,
@@ -21,13 +24,17 @@ interface HealthRefreshAttemptOptions {
   readonly diagnosticsScope: HealthDiagnosticScope;
   readonly attemptedAt: number;
   readonly cwd: string;
-  readonly sentinelSnapshot: Map<string, number>;
+  readonly maintenanceState: LspMaintenanceState;
   readonly control?: CodeRequestControl;
   readonly reportRecoveryProgress?: () => void;
 }
 
 export interface HealthRefreshCollection {
   readonly attempt: HealthRefreshAttempt;
+  /** File readiness observed by the same explicit refresh call. */
+  readonly fileReadiness?: SemanticReadinessResult;
+  /** Next typed maintenance state, committed only after the attempt returns. */
+  readonly maintenanceState: LspMaintenanceState;
   /** Final report from the runtime, retained only for the current workflow. */
   readonly diagnosticReport?: WorkspaceDiagnosticReport;
 }
@@ -49,19 +56,20 @@ async function collectFileRefreshAttempt(
   const maintenance = await refreshFileLspMaintenance({
     runtime: options.runtime,
     cwd: options.cwd,
-    sentinelSnapshot: options.sentinelSnapshot,
+    maintenanceState: options.maintenanceState,
     filePath: scope.path,
     control: options.control,
   });
-  updateSentinelSnapshot(options.sentinelSnapshot, maintenance.snapshot);
   const readiness = await options.runtime.waitUntilReadyForFile(
     scope.path,
-    undefined,
+    { retryFailedRoute: true },
     options.control,
   );
   const fileReadiness: HealthFileReadiness =
     readiness.kind === "ready" ? "ready" : readiness.kind === "timeout" ? "pending" : "unavailable";
   return {
+    fileReadiness: readiness,
+    maintenanceState: maintenance.maintenanceState,
     attempt: {
       kind: "completed",
       attemptedAt: options.attemptedAt,
@@ -72,6 +80,7 @@ async function collectFileRefreshAttempt(
       fileReadiness,
       restartedClients: 0,
       processCrashRecovery: readiness.processCrashRecovery ?? emptyProcessCrashRecoveryReport(),
+      startupRetry: readiness.startupRetry ?? emptyStartupRetryReport(),
       staleAssessment: {
         scope: "file",
         suspected: null,
@@ -90,16 +99,16 @@ async function collectWorkspaceRefreshAttempt(
   const maintenance = await refreshLspMaintenance(
     options.runtime,
     options.cwd,
-    options.sentinelSnapshot,
+    options.maintenanceState,
     {
       control: options.control,
       scope: workspaceScope?.filter ?? null,
       trackSources: workspaceScope !== null,
     },
   );
-  updateSentinelSnapshot(options.sentinelSnapshot, maintenance.snapshot);
   if (maintenance.failureReason) {
     return {
+      maintenanceState: maintenance.maintenanceState,
       attempt: {
         kind: "failed",
         attemptedAt: options.attemptedAt,
@@ -108,6 +117,8 @@ async function collectWorkspaceRefreshAttempt(
         operationScope: "workspace-runtime",
         diagnosticEvidence: maintenance.diagnosticEvidence,
         processCrashRecovery: emptyProcessCrashRecoveryReport(),
+        startupRetry: emptyStartupRetryReport(),
+        ...(maintenance.sourceTracking ? { sourceTracking: maintenance.sourceTracking } : {}),
         reason: maintenance.failureReason,
       },
     };
@@ -123,6 +134,7 @@ async function collectWorkspaceRefreshAttempt(
       // runtime then performs a fresh pass that includes the replacement.
       initialEvidence: maintenance.diagnosticEvidence,
       processCrashDemand: {
+        explicit: true,
         ...(workspaceScope?.filter ? { scopes: [workspaceScope.filter] } : {}),
       },
     });
@@ -133,6 +145,7 @@ async function collectWorkspaceRefreshAttempt(
     );
     if (recovery.refreshFailureReason) {
       return {
+        maintenanceState: maintenance.maintenanceState,
         attempt: {
           kind: "failed",
           attemptedAt: options.attemptedAt,
@@ -149,12 +162,15 @@ async function collectWorkspaceRefreshAttempt(
           },
           diagnosticEvidence,
           processCrashRecovery: recovery.processCrashRecovery,
+          startupRetry: recovery.startupRetry,
+          ...(maintenance.sourceTracking ? { sourceTracking: maintenance.sourceTracking } : {}),
           reason: recovery.refreshFailureReason,
         },
         diagnosticReport: recovery.diagnosticReport,
       };
     }
     return {
+      maintenanceState: maintenance.maintenanceState,
       attempt: {
         kind: "completed",
         attemptedAt: options.attemptedAt,
@@ -164,7 +180,9 @@ async function collectWorkspaceRefreshAttempt(
         attemptedActiveClients: recovery.attemptedClients,
         restartedClients: recovery.restartedClients,
         processCrashRecovery: recovery.processCrashRecovery,
+        startupRetry: recovery.startupRetry,
         diagnosticEvidence,
+        ...(maintenance.sourceTracking ? { sourceTracking: maintenance.sourceTracking } : {}),
         staleAssessment: {
           scope: "workspace",
           suspected: recovery.staleAssessment.suspected,
@@ -179,6 +197,7 @@ async function collectWorkspaceRefreshAttempt(
     // recorded failed attempt.
     if (isCodeRequestInterruption(error, options.control)) throw error;
     return {
+      maintenanceState: maintenance.maintenanceState,
       attempt: {
         kind: "failed",
         attemptedAt: options.attemptedAt,
@@ -187,17 +206,14 @@ async function collectWorkspaceRefreshAttempt(
         operationScope: "workspace-runtime",
         diagnosticEvidence: maintenance.diagnosticEvidence,
         processCrashRecovery: emptyProcessCrashRecoveryReport(),
+        startupRetry: emptyStartupRetryReport(),
+        ...(maintenance.sourceTracking ? { sourceTracking: maintenance.sourceTracking } : {}),
         reason: errorMessage(error),
       },
     };
   }
 }
 
-function updateSentinelSnapshot(target: Map<string, number>, next: Map<string, number>): void {
-  target.clear();
-  for (const [key, value] of next) target.set(key, value);
-}
-
 function errorMessage(error: unknown): string {
   return error instanceof Error && error.message ? error.message : "Diagnostic refresh failed.";
 }

package/src/session/health-types.ts

@@ -4,8 +4,10 @@ import type {
   ProcessCrashRecoveryReport,
   ProjectServerInfo,
   ProjectServerStatusReason,
+  StartupRetryReport,
 } from "@mrclrchtr/supi-lsp/api";
 import type { CapabilityWarningReport } from "../analysis/capability/capability-warnings.ts";
+import type { SourceTrackingReport } from "../substrate/lsp/source-tracking.ts";
 
 export type HealthSection = "diagnostics" | "servers";
 
@@ -62,7 +64,7 @@ export type HealthDiagnosticObservation =
       readonly scope: HealthDiagnosticScope;
       readonly entries: readonly HealthDiagnosticEntry[];
       readonly evidence: DiagnosticEvidenceSummary;
-      /** Tsconfig scope decision for the requested file (file scope only). */
+      /** Tsconfig scope decision for an applicable TypeScript or JavaScript file. */
       readonly scopeStatus?: FileScopeDecision;
     }
   | {
@@ -71,7 +73,7 @@ export type HealthDiagnosticObservation =
       readonly entries: readonly HealthDiagnosticEntry[];
       readonly evidence: DiagnosticEvidenceSummary;
       readonly reason: string;
-      /** Tsconfig scope decision for the requested file (file scope only). */
+      /** Tsconfig scope decision for an applicable TypeScript or JavaScript file. */
       readonly scopeStatus?: FileScopeDecision;
     }
   | {
@@ -80,7 +82,7 @@ export type HealthDiagnosticObservation =
       readonly entries: readonly HealthDiagnosticEntry[];
       readonly evidence: DiagnosticEvidenceSummary;
       readonly reason: string;
-      /** Tsconfig scope decision for the requested file (file scope only). */
+      /** Tsconfig scope decision for an applicable TypeScript or JavaScript file. */
       readonly scopeStatus?: FileScopeDecision;
     };
 
@@ -92,6 +94,7 @@ export interface HealthStaleAssessment {
   readonly warning: string | null;
 }
 
+/** Runtime scope of maintenance; it is not the diagnostic result scope. */
 export type HealthRefreshOperationScope = "file-runtime" | "workspace-runtime";
 
 /** Readiness result for a file-scoped maintenance attempt. */
@@ -113,10 +116,17 @@ interface CompletedHealthRefreshAttempt {
   readonly restartedClients: number;
   /** Separate outcome for process-crash route recovery. */
   readonly processCrashRecovery: ProcessCrashRecoveryReport;
+  /** Separate outcome for initial-start retries. */
+  readonly startupRetry?: StartupRetryReport;
   readonly staleAssessment: HealthStaleAssessment;
+  /**
+   * Source discovery and bounded tracking facts for broad refreshes. The
+   * report's skipped list describes automatic tracking policy, not capability.
+   */
+  readonly sourceTracking?: SourceTrackingReport;
 }
 
-/** A diagnostic refresh attempt against an explicit LSP runtime scope. */
+/** A diagnostic refresh attempt with separate maintenance and result scopes. */
 export type HealthRefreshAttempt =
   | (CompletedHealthRefreshAttempt & {
       readonly operationScope: "workspace-runtime";
@@ -144,6 +154,13 @@ export type HealthRefreshAttempt =
       readonly diagnosticEvidence?: DiagnosticEvidenceSummary;
       /** Process-crash outcome, when the recovery pass returned one. */
       readonly processCrashRecovery?: ProcessCrashRecoveryReport;
+      /** Initial-start retry outcome, when the recovery pass returned one. */
+      readonly startupRetry?: StartupRetryReport;
+      /**
+       * Source discovery and bounded tracking facts for broad refreshes. The
+       * report's skipped list describes automatic tracking policy, not capability.
+       */
+      readonly sourceTracking?: SourceTrackingReport;
       /** File readiness outcome, when a file-scoped attempt failed. */
       readonly fileReadiness?: HealthFileReadiness;
       readonly reason: string;