@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

package/src/session/health-workflow.ts

@@ -4,6 +4,7 @@ import type { CapabilityState } from "@mrclrchtr/supi-code-runtime/api";
 import { isCodeRequestInterruption } from "@mrclrchtr/supi-code-runtime/api";
 import type {
   LspRuntimeController,
+  SemanticReadinessResult,
   WorkspaceDiagnosticReport,
   WorkspaceLspRuntime,
   WorkspaceLspRuntimeState,
@@ -21,6 +22,7 @@ import { describeStructuralState } from "../analysis/health/recovery.ts";
 import { collectServers } from "../analysis/health/signals.ts";
 import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
 import { resolveScope } from "../analysis/search/paths.ts";
+import type { LspMaintenanceState } from "../substrate/lsp/source-tracking.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
 import { collectHealthRefreshAttempt } from "./health-refresh.ts";
 import type {
@@ -45,8 +47,10 @@ export interface HealthWorkflowDeps {
   readonly lspController: LspRuntimeController | null;
   readonly lastRefreshAttempt: HealthRefreshAttempt | null;
   readonly trackRefreshAttempt: (attempt: HealthRefreshAttempt) => void;
-  /** Workspace sentinel snapshot for change detection. */
-  readonly sentinelSnapshot: Map<string, number>;
+  /** Typed sentinel, source-baseline, and created-source queue state. */
+  readonly maintenanceState: LspMaintenanceState;
+  /** Commit maintenance state only after a health attempt completes. */
+  readonly updateMaintenanceState: (state: LspMaintenanceState) => void;
 }
 
 /** Collect health facts without rendering a public result. */
@@ -77,7 +81,6 @@ export async function runHealthWorkflow(
   const diagnosticsScope = diagnosticScope(scopeFilter);
   const refreshCollection = await collectRefreshState({
     refreshRequested: request.refresh === true,
-    diagnosticsRequested: included.includes("diagnostics"),
     runtime,
     lspState,
     diagnosticsScope,
@@ -91,6 +94,7 @@ export async function runHealthWorkflow(
     scopeFilter,
     lspState,
     capabilityState: capabilityStates.semantic,
+    refreshReadiness: refreshCollection.fileReadiness,
     control,
   });
   const semanticReady = semanticState?.kind === "ready";
@@ -143,6 +147,8 @@ interface SemanticHealthStateOptions {
   requested: boolean;
   /** Whether this call requests file-routed evidence rather than passive inventory. */
   fileReadinessRequested: boolean;
+  /** Readiness observed by the explicit refresh phase, when one ran. */
+  refreshReadiness?: SemanticReadinessResult;
   runtime: WorkspaceLspRuntime | null;
   scopeFilter: string | null;
   lspState: WorkspaceLspRuntimeState;
@@ -154,12 +160,17 @@ async function establishSemanticHealthState(
   options: SemanticHealthStateOptions,
 ): Promise<SemanticHealthState | null> {
   if (!options.requested) return null;
-  if (options.fileReadinessRequested && options.runtime && isScopedFile(options.scopeFilter)) {
-    const readiness = await options.runtime.waitUntilReadyForFile(
-      options.scopeFilter,
-      undefined,
-      options.control,
-    );
+  if (options.fileReadinessRequested && isScopedFile(options.scopeFilter)) {
+    const readiness =
+      options.refreshReadiness ??
+      (options.runtime
+        ? await options.runtime.waitUntilReadyForFile(
+            options.scopeFilter,
+            undefined,
+            options.control,
+          )
+        : null);
+    if (!readiness) return deriveNonReadySemanticState(options.lspState, options.capabilityState);
     if (readiness.kind === "ready") return { kind: "ready" };
     if (readiness.kind === "timeout") {
       return { kind: "pending", reason: SEMANTIC_READINESS_TIMEOUT_REASON };
@@ -223,12 +234,12 @@ function collectCapabilityWarnings(
 
 interface HealthRefreshStateCollection {
   readonly attempt: HealthRefreshState;
+  readonly fileReadiness?: SemanticReadinessResult;
   readonly diagnosticReport?: WorkspaceDiagnosticReport;
 }
 
 interface RefreshStateOptions {
   readonly refreshRequested: boolean;
-  readonly diagnosticsRequested: boolean;
   readonly runtime: WorkspaceLspRuntime | null;
   readonly lspState: WorkspaceLspRuntimeState;
   readonly diagnosticsScope: HealthDiagnosticScope;
@@ -240,16 +251,7 @@ interface RefreshStateOptions {
 async function collectRefreshState(
   options: RefreshStateOptions,
 ): Promise<HealthRefreshStateCollection> {
-  const { deps, diagnosticsRequested, diagnosticsScope, lspState, runtime } = options;
-  if (!diagnosticsRequested) {
-    return {
-      attempt: {
-        kind: "not-requested",
-        reason: "Diagnostics were not requested.",
-        lastAttempt: deps.lastRefreshAttempt,
-      },
-    };
-  }
+  const { deps, diagnosticsScope, lspState, runtime } = options;
   if (!options.refreshRequested) {
     return {
       attempt: {
@@ -282,7 +284,7 @@ async function collectRefreshState(
       diagnosticsScope,
       attemptedAt,
       cwd: options.deps.cwd,
-      sentinelSnapshot: options.deps.sentinelSnapshot,
+      maintenanceState: options.deps.maintenanceState,
       control: options.control,
       reportRecoveryProgress: () =>
         reportProgress(options.control, {
@@ -291,8 +293,12 @@ async function collectRefreshState(
           message: "Refreshing diagnostics and recovery state",
         }),
     });
+    deps.updateMaintenanceState(attempt.maintenanceState);
     deps.trackRefreshAttempt(attempt.attempt);
-    return attempt;
+    return {
+      ...attempt,
+      ...(attempt.fileReadiness ? { fileReadiness: attempt.fileReadiness } : {}),
+    };
   } catch (error) {
     // Cancellation must propagate; a cancelled caller no longer awaits a
     // recorded failed attempt or the refresh data it would carry.

package/src/session/orientation-types.ts

@@ -5,6 +5,7 @@ import type { EvidenceListMetadata } from "../analysis/evidence.ts";
 import type { InstructionFilesMetadata } from "../analysis/instruction-files.ts";
 import type { CodeProvider } from "../analysis/provider.ts";
 import type { ReadNextItem } from "../analysis/read-next.ts";
+import type { TargetCandidateCompleteness } from "../analysis/target/types.ts";
 import type { OrientationTargetInput, TargetSymbolKind } from "./target-input.ts";
 import type { AnchorKind, TargetStoreEntry } from "./target-store.ts";
 
@@ -118,16 +119,14 @@ export interface OrientationResultData {
 
 export type OrientationWorkflowOutcome =
   | { readonly kind: "completed"; readonly data: OrientationResultData }
-  | {
+  | ({
       readonly kind: "disambiguation";
       readonly candidates: readonly OrientationCandidate[];
-      readonly omittedCount: number;
-    }
-  | {
+    } & TargetCandidateCompleteness)
+  | ({
       readonly kind: "kind-mismatch";
       readonly requestedKind: TargetSymbolKind;
       readonly candidates: readonly OrientationCandidate[];
-      readonly omittedCount: number;
-    }
+    } & TargetCandidateCompleteness)
   | { readonly kind: "invalid-input"; readonly message: string }
   | { readonly kind: "unavailable"; readonly reason: string };

package/src/session/orientation-workflow.ts

@@ -131,10 +131,18 @@ async function orientTarget(options: {
       ? {
           kind: "kind-mismatch",
           requestedKind: target.requestedKind,
-          omittedCount: target.omittedCount,
           candidates,
+          totalCount: target.totalCount,
+          omittedCount: target.omittedCount,
+          partialReason: target.partialReason,
         }
-      : { kind: "disambiguation", omittedCount: target.omittedCount, candidates };
+      : {
+          kind: "disambiguation",
+          candidates,
+          totalCount: target.totalCount,
+          omittedCount: target.omittedCount,
+          partialReason: target.partialReason,
+        };
   }
   if (target.kind !== "resolved") return target;
   throwIfAborted(control);

package/src/session/session.ts

@@ -20,6 +20,10 @@ import { realpathSync } from "node:fs";
 import * as path from "node:path";
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { LspRuntimeController } from "@mrclrchtr/supi-lsp/api";
+import {
+  createLspMaintenanceState,
+  type LspMaintenanceState,
+} from "../substrate/lsp/source-tracking.ts";
 import { type CapabilityAdapter, WorkspaceCapabilityAdapter } from "./capability-adapter.ts";
 import type { FindWorkflowInput, FindWorkflowOutcome } from "./find-types.ts";
 import { runFindWorkflow } from "./find-workflow.ts";
@@ -162,8 +166,8 @@ export class WorkspaceCodeIntelligenceSession {
    */
   #lspController: LspRuntimeController | null = null;
 
-  /** Workspace sentinel snapshot for change detection across explicit queries. */
-  #sentinelSnapshot: Map<string, number> = new Map();
+  /** Typed sentinel, source-baseline, and created-source queue state. */
+  #maintenanceState: LspMaintenanceState = createLspMaintenanceState();
 
   /** Whether the project owning this session is trusted for config loading. */
   #projectTrusted = false;
@@ -196,7 +200,7 @@ export class WorkspaceCodeIntelligenceSession {
    * Called by the extension entry point after LSP initialization.
    */
   seedSentinelSnapshot(snapshot: Map<string, number>): void {
-    this.#sentinelSnapshot = snapshot;
+    this.#maintenanceState = createLspMaintenanceState(snapshot);
   }
 
   /** Restore overview state from the active session branch. */
@@ -283,7 +287,10 @@ export class WorkspaceCodeIntelligenceSession {
         trackRefreshAttempt: (attempt) => {
           this.#lastHealthRefreshAttempt = attempt;
         },
-        sentinelSnapshot: this.#sentinelSnapshot,
+        maintenanceState: this.#maintenanceState,
+        updateMaintenanceState: (state) => {
+          this.#maintenanceState = state;
+        },
       },
       control,
     );
@@ -429,7 +436,7 @@ export class WorkspaceCodeIntelligenceSession {
     this.#workflowTargets.clear();
     this.#surfacedInstructionDirs.clear();
     this.#nativeInstructionPaths.clear();
-    this.#sentinelSnapshot.clear();
+    this.#maintenanceState = createLspMaintenanceState();
     this.#lspController = null;
     this.#projectTrusted = false;
   }

package/src/session/target-workflow.ts

@@ -19,6 +19,7 @@ import { resolveSymbolTarget } from "../analysis/target/symbol.ts";
 import type {
   ResolvedTargetData,
   ResolvedTargetGroupData,
+  TargetCandidateCompleteness,
   TargetOutcome,
 } from "../analysis/target/types.ts";
 import type { CapabilityAdapter } from "./capability-adapter.ts";
@@ -59,17 +60,15 @@ export type TargetWorkflowOutcome =
       omittedCount: number;
       unknownNestingCount: number;
     }
-  | {
+  | ({
       kind: "disambiguation";
       candidates: ReadonlyArray<TargetWorkflowCandidate>;
-      omittedCount: number;
-    }
-  | {
+    } & TargetCandidateCompleteness)
+  | ({
       kind: "kind-mismatch";
       requestedKind: TargetSymbolKind;
       candidates: ReadonlyArray<TargetWorkflowCandidate>;
-      omittedCount: number;
-    }
+    } & TargetCandidateCompleteness)
   | { kind: "invalid-input"; message: string }
   | { kind: "unavailable"; reason: string };
 
@@ -318,12 +317,16 @@ function toWorkflowOutcome(
         kind: "kind-mismatch",
         requestedKind: outcome.requestedKind,
         candidates,
+        totalCount: outcome.totalCount,
         omittedCount: outcome.omittedCount,
+        partialReason: outcome.partialReason,
       }
     : {
         kind: "disambiguation",
         candidates,
+        totalCount: outcome.totalCount,
         omittedCount: outcome.omittedCount,
+        partialReason: outcome.partialReason,
       };
 }
 

package/src/substrate/lsp/maintenance.ts

@@ -13,7 +13,6 @@ import {
   isCodeRequestInterruption,
   throwIfCodeRequestInterrupted,
 } from "@mrclrchtr/supi-code-runtime/api";
-import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
 import { uriToFile } from "@mrclrchtr/supi-core/path";
 import type { DiagnosticEvidenceSummary } from "@mrclrchtr/supi-lsp/api";
 import {
@@ -27,6 +26,12 @@ import {
   type WorkspaceLspRuntime,
 } from "@mrclrchtr/supi-lsp/api";
 import { mergeDiagnosticEvidence } from "../../diagnostics/evidence.ts";
+import {
+  type LspMaintenanceState,
+  type SourceTrackingReport,
+  trackCreatedSources,
+  withSentinelSnapshot,
+} from "./source-tracking.ts";
 
 /** Options shared by the workspace and file-scoped maintenance passes. */
 export interface LspMaintenanceOptions {
@@ -36,11 +41,7 @@ export interface LspMaintenanceOptions {
    * tracks created files inside this prefix; null disables the scope bound.
    */
   scope?: string | null;
-  /**
-   * Track files created since the last refresh so the following refresh pull
-   * includes them. Only the workspace-runtime path sets this; the snapshot is
-   * still widened on file-scoped passes so later diffs stay correct.
-   */
+  /** Track source additions only for a broad tracked-file refresh. */
   trackSources?: boolean;
 }
 
@@ -52,10 +53,11 @@ export interface LspMaintenanceOptions {
 export async function refreshLspMaintenance(
   runtime: WorkspaceLspRuntime,
   cwd: string,
-  sentinelSnapshot: Map<string, number>,
+  maintenanceState: LspMaintenanceState,
   options: LspMaintenanceOptions = {},
 ): Promise<WorkspaceLspMaintenanceResult> {
-  const { snapshot } = await synchronizeSentinels(runtime, sentinelSnapshot, options);
+  const synchronized = await synchronizeSentinels(runtime, cwd, maintenanceState, options);
+  const { snapshot, nextState, sourceTracking } = synchronized;
   let diagnosticEvidence = emptyEvidence();
   let failureReason: string | undefined;
 
@@ -80,15 +82,21 @@ export async function refreshLspMaintenance(
 
   return {
     snapshot,
+    maintenanceState: nextState,
     diagnosticEvidence,
+    ...(sourceTracking ? { sourceTracking } : {}),
     ...(failureReason ? { failureReason } : {}),
   };
 }
 
 /** Sentinel state and diagnostic evidence retained from one workspace pass. */
 export interface WorkspaceLspMaintenanceResult {
+  /** The next typed maintenance state for the session. */
+  maintenanceState: LspMaintenanceState;
   /** The next sentinel snapshot for the session-owned maintenance state. */
   snapshot: Map<string, number>;
+  /** Source discovery and bounded tracking facts for broad refreshes. */
+  sourceTracking?: SourceTrackingReport;
   /** Evidence from every diagnostic refresh performed by this pass. */
   diagnosticEvidence: DiagnosticEvidenceSummary;
   /** Failure from the first workspace refresh, when no fresh pass completed. */
@@ -97,6 +105,8 @@ export interface WorkspaceLspMaintenanceResult {
 
 /** Sentinel state and stale-file facts from one file-scoped pass. */
 export interface FileLspMaintenanceResult {
+  /** The next typed maintenance state for the session. */
+  maintenanceState: LspMaintenanceState;
   /** The next sentinel snapshot for the session-owned maintenance state. */
   snapshot: Map<string, number>;
   /** Number of stale files that matched the requested file. */
@@ -107,14 +117,14 @@ export interface FileLspMaintenanceResult {
 export async function refreshFileLspMaintenance(options: {
   runtime: WorkspaceLspRuntime;
   cwd: string;
-  sentinelSnapshot: Map<string, number>;
+  maintenanceState: LspMaintenanceState;
   filePath: string;
   control?: CodeRequestControl;
 }): Promise<FileLspMaintenanceResult> {
-  const { runtime, cwd, sentinelSnapshot, filePath, control } = options;
+  const { runtime, cwd, maintenanceState, filePath, control } = options;
   // A cancelled caller stops before any maintenance work starts.
   throwIfCodeRequestInterrupted(control);
-  const { snapshot } = await synchronizeSentinels(runtime, sentinelSnapshot);
+  const { snapshot, nextState } = await synchronizeSentinels(runtime, cwd, maintenanceState);
   const target = nodePath.resolve(filePath);
   const stale = confirmedOutstandingDiagnostics(runtime, cwd).some(
     (entry) =>
@@ -132,38 +142,51 @@ export async function refreshFileLspMaintenance(options: {
   runtime.pruneMissingFiles();
   throwIfCodeRequestInterrupted(control);
 
-  return { snapshot, matchedStaleFileCount: stale ? 1 : 0 };
+  return {
+    snapshot,
+    maintenanceState: nextState,
+    matchedStaleFileCount: stale ? 1 : 0,
+  };
 }
 
 /**
- * Sync the widened workspace snapshot, forward sentinel changes, and track
- * source files newly created since the last pass.
+ * Sync sentinel state and, only for broad refreshes, process source additions.
  *
- * The snapshot is widened to every regular file on every pass so later diffs
- * see genuine creations. Only sentinel-file events are forwarded as workspace
- * changes (config semantics unchanged); created source files are tracked only
- * on the workspace-runtime path and only once the snapshot was primed by an
- * earlier pass — the first pass establishes the baseline and cannot tell a
- * just-created file from a long-existing one.
+ * Sentinel state and source state use separate baselines. A complete source
+ * inventory establishes the first baseline without treating existing files as
+ * created. Limited inventories leave the previous source state unchanged.
  */
 async function synchronizeSentinels(
   runtime: WorkspaceLspRuntime,
-  sentinelSnapshot: Map<string, number>,
+  cwd: string,
+  maintenanceState: LspMaintenanceState,
   options: LspMaintenanceOptions = {},
-) {
-  const primed = sentinelSnapshot.size > 0;
-  const state = runtime.syncWorkspaceSentinelSnapshot(sentinelSnapshot, {
-    includeSourceFiles: true,
-  });
-
+): Promise<{
+  snapshot: Map<string, number>;
+  nextState: LspMaintenanceState;
+  sourceTracking?: SourceTrackingReport;
+}> {
+  const state = runtime.syncWorkspaceSentinelSnapshot(maintenanceState.sentinelSnapshot);
   invalidateChangedProjectConfigs(state.changes);
   if (state.changes.length > 0) runtime.noteWorkspaceChanges(state.changes);
 
-  if (options.trackSources && primed) {
-    await trackCreatedSourceFiles(runtime, state.sourceChanges, options.scope);
+  const nextSentinelState = withSentinelSnapshot(maintenanceState, state.snapshot);
+  if (!options.trackSources) {
+    return { snapshot: state.snapshot, nextState: nextSentinelState };
   }
 
-  return state;
+  const sourceResult = await trackCreatedSources({
+    runtime,
+    cwd,
+    state: nextSentinelState,
+    scope: options.scope,
+    control: options.control,
+  });
+  return {
+    snapshot: state.snapshot,
+    nextState: sourceResult.state,
+    sourceTracking: sourceResult.report,
+  };
 }
 
 /** Invalidate cached tsconfig scope parses only for config files that changed. */
@@ -181,23 +204,6 @@ function invalidateChangedProjectConfigs(changes: readonly FileEvent[]): void {
   }
 }
 
-/** Track source files newly created since the last pass, within the scope bound. */
-async function trackCreatedSourceFiles(
-  runtime: WorkspaceLspRuntime,
-  sourceChanges: readonly FileEvent[],
-  scope: string | null | undefined,
-): Promise<void> {
-  for (const change of sourceChanges) {
-    if (change.type !== FileChangeType.Created) continue;
-    const filePath = uriToFile(change.uri);
-    if (scope && !isWithinOrEqual(scope, filePath)) continue;
-    if (!runtime.isSupportedSourceFile(filePath)) continue;
-    // Best-effort: a file no client can serve stays untracked and is
-    // simply absent from evidence until a later explicit request.
-    await runtime.trackFile(filePath);
-  }
-}
-
 /** Return only diagnostics whose document evidence is confirmed. */
 function confirmedOutstandingDiagnostics(runtime: WorkspaceLspRuntime, cwd: string) {
   const outstanding = runtime.getOutstandingDiagnostics(1);