@mrclrchtr/supi-code-intelligence 4.10.0 → 5.0.0

package/src/analysis/target/anchored.ts

@@ -9,12 +9,14 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type {
-  CodeResult,
-  CodeSymbol,
-  NodeAtData,
-  SemanticProvider,
-  StructuralProvider,
+import {
+  type CodeRequestControl,
+  type CodeResult,
+  type CodeSymbol,
+  isCodeRequestInterruption,
+  type NodeAtData,
+  type SemanticProvider,
+  type StructuralProvider,
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { AnchorKind } from "../../session/target-store.ts";
 import type { AnchoredResolutionMetadata, AnchoredResolutionSource } from "../../types/index.ts";
@@ -217,17 +219,20 @@ async function candidatesFromSymbols(
 }
 
 /** Layer 1: match the coordinate against LSP document symbols. Returns null to fall through. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: layered anchored resolution keeps layer-1 symbol matching and identity resolution together.
 async function resolveFromSemantic(
   file: string,
   requested: Anchor,
   provider: AnchoredResolverProvider,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome | null> {
   if (!provider.documentSymbols) return null;
   let symbols: CodeSymbol[] = [];
   try {
     const result = await provider.documentSymbols(file);
     if (result.kind !== "unavailable") symbols = result.data;
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     symbols = [];
   }
   if (symbols.length === 0) return null;
@@ -241,7 +246,7 @@ async function resolveFromSemantic(
   }
 
   const structural = provider.nodeAt ? { nodeAt: provider.nodeAt } : undefined;
-  const resolveIdentity = createCodeSymbolIdentityResolver(file, symbols, structural);
+  const resolveIdentity = createCodeSymbolIdentityResolver(file, symbols, structural, control);
   if (exact.length === 1) {
     return resolvedFromSymbol(file, exact[0], {
       snapped: false,
@@ -268,12 +273,14 @@ async function resolveFromStructural(
   file: string,
   requested: Anchor,
   provider: AnchoredResolverProvider,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome | null> {
   if (!provider.nodeAt) return null;
   let nodeResult: CodeResult<NodeAtData> | null = null;
   try {
     nodeResult = await provider.nodeAt(file, requested.line, requested.character);
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     nodeResult = null;
   }
   if (nodeResult?.kind !== "success") return null;
@@ -351,11 +358,13 @@ async function resolveFromStructural(
  * This does not perform heuristic global text search and does not silently
  * treat declaration anchors as name anchors (ADR 0003).
  */
+// biome-ignore lint/complexity/useMaxParams: anchored resolution is a stable public resolver boundary with fixed positional fields.
 export async function resolveAnchoredSymbolTarget(
   file: string,
   line: number,
   character: number,
   provider: AnchoredResolverProvider | null,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome> {
   if (!fs.existsSync(file)) {
     return { kind: "error", message: `File not found: \`${file}\`` };
@@ -369,9 +378,9 @@ export async function resolveAnchoredSymbolTarget(
 
   const requested: Anchor = { line, character };
   if (provider) {
-    const semantic = await resolveFromSemantic(file, requested, provider);
+    const semantic = await resolveFromSemantic(file, requested, provider, control);
     if (semantic) return semantic;
-    const structural = await resolveFromStructural(file, requested, provider);
+    const structural = await resolveFromStructural(file, requested, provider, control);
     if (structural) return structural;
   }
 

package/src/analysis/target/file.ts

@@ -9,12 +9,14 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type {
-  DeclarationNesting,
-  DocumentCodeSymbol,
-  OutlineData,
-  SemanticProvider as SemanticSubstrate,
-  StructuralProvider as StructuralSubstrate,
+import {
+  type CodeRequestControl,
+  type DeclarationNesting,
+  type DocumentCodeSymbol,
+  isCodeRequestInterruption,
+  type OutlineData,
+  type SemanticProvider as SemanticSubstrate,
+  type StructuralProvider as StructuralSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
 import type { AnchorKind } from "../../session/target-store.ts";
 import { normalizePath } from "../search/paths.ts";
@@ -80,6 +82,7 @@ export async function resolveFileTargetGroup(
     semantic?: SemanticSubstrate;
     structural?: StructuralSubstrate;
   } = {},
+  control?: CodeRequestControl,
 ): Promise<
   | { kind: "resolved"; group: ResolvedTargetGroupData }
   | { kind: "invalid-input"; message: string }
@@ -90,8 +93,8 @@ export async function resolveFileTargetGroup(
   const resolvedFile = validation.file;
 
   const [semantic, structural] = await Promise.all([
-    discoverSemantic(resolvedFile, deps.semantic, deps.structural),
-    discoverStructural(resolvedFile, deps.structural),
+    discoverSemantic(resolvedFile, deps.semantic, deps.structural, control),
+    discoverStructural(resolvedFile, deps.structural, control),
   ]);
   if (!semantic.available && !structural.available) {
     const displayFile = path.relative(cwd, resolvedFile) || file;
@@ -148,6 +151,7 @@ async function discoverSemantic(
   file: string,
   semantic: SemanticSubstrate | undefined,
   structural: StructuralSubstrate | undefined,
+  control?: CodeRequestControl,
 ): Promise<DiscoveryResult> {
   if (!semantic) return { available: false, targets: [] };
   try {
@@ -158,12 +162,13 @@ async function discoverSemantic(
       targets: await Promise.all(
         result.data.map(async (symbol) => {
           const target = targetFromSymbol(file, symbol);
-          const refined = await refineTypeAliasIdentity(target, structural);
+          const refined = await refineTypeAliasIdentity(target, structural, control);
           return { ...refined, nesting: target.nesting };
         }),
       ),
     };
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     return { available: false, targets: [] };
   }
 }
@@ -196,13 +201,15 @@ function normalizeNesting(value: unknown): DeclarationNesting {
 async function discoverStructural(
   file: string,
   structural: StructuralSubstrate | undefined,
+  control?: CodeRequestControl,
 ): Promise<DiscoveryResult> {
   if (!structural) return { available: false, targets: [] };
   try {
     const result = await structural.outline(file);
     if (result.kind !== "success") return { available: false, targets: [] };
     return { available: true, targets: flattenOutline(file, result.data) };
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     return { available: false, targets: [] };
   }
 }

package/src/analysis/target/identity.ts

@@ -1,5 +1,10 @@
 import { resolve } from "node:path";
-import type { CodeSymbol, StructuralProvider } from "@mrclrchtr/supi-code-runtime/api";
+import {
+  type CodeRequestControl,
+  type CodeSymbol,
+  isCodeRequestInterruption,
+  type StructuralProvider,
+} from "@mrclrchtr/supi-code-runtime/api";
 import type { ResolvedTargetData, TargetOutcome } from "./types.ts";
 
 /**
@@ -45,6 +50,7 @@ export interface DeclarationOccurrenceIdentity extends DeclarationIdentityResult
 export async function resolveDeclarationIdentityKind(
   observation: DeclarationIdentityObservation,
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): Promise<DeclarationIdentityResult> {
   const identityKind = canonicalDeclarationKind(observation.providerKind);
   if (
@@ -69,7 +75,8 @@ export async function resolveDeclarationIdentityKind(
     return exactNameAnchor && isTypeAlias
       ? { identityKind: "type", structuralEvidence: true }
       : { identityKind, structuralEvidence: false };
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     return { identityKind, structuralEvidence: false };
   }
 }
@@ -82,6 +89,7 @@ export function createCodeSymbolIdentityResolver(
   file: string,
   allSymbols: readonly CodeSymbol[],
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): (symbol: CodeSymbol) => Promise<DeclarationOccurrenceIdentity> {
   const identities = new Map<CodeSymbol, Promise<DeclarationIdentityResult>>();
   const occurrences = new Map<CodeSymbol, Promise<DeclarationOccurrenceIdentity>>();
@@ -97,6 +105,7 @@ export function createCodeSymbolIdentityResolver(
         nameAnchor: symbol.nameAnchor ?? null,
       },
       structural,
+      control,
     );
     identities.set(symbol, identity);
     return identity;
@@ -147,6 +156,7 @@ function compareCodeSymbolDeclarations(left: CodeSymbol, right: CodeSymbol): num
 export async function refineTypeAliasIdentity(
   target: ResolvedTargetData,
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): Promise<ResolvedTargetData> {
   if (target.identityKind !== undefined) return target;
   const identity = await resolveDeclarationIdentityKind(
@@ -160,6 +170,7 @@ export async function refineTypeAliasIdentity(
           : null,
     },
     structural,
+    control,
   );
   return {
     ...target,
@@ -173,9 +184,13 @@ export async function refineTargetOutcomeIdentity(
   outcome: TargetOutcome,
   cwd: string,
   structural: Pick<StructuralProvider, "nodeAt"> | undefined,
+  control?: CodeRequestControl,
 ): Promise<TargetOutcome> {
   if (outcome.kind === "resolved") {
-    return { kind: "resolved", target: await refineTypeAliasIdentity(outcome.target, structural) };
+    return {
+      kind: "resolved",
+      target: await refineTypeAliasIdentity(outcome.target, structural, control),
+    };
   }
   if (outcome.kind !== "disambiguation" && outcome.kind !== "kind-mismatch") return outcome;
 
@@ -195,6 +210,7 @@ export async function refineTargetOutcomeIdentity(
               : null,
         },
         structural,
+        control,
       );
       return {
         candidate: {

package/src/analysis/target/symbol.ts

@@ -7,9 +7,11 @@
  */
 
 import * as path from "node:path";
-import type {
-  CodeSymbol,
-  SemanticProvider as SemanticSubstrate,
+import {
+  type CodeRequestControl,
+  type CodeSymbol,
+  isCodeRequestInterruption,
+  type SemanticProvider as SemanticSubstrate,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
 import type { TargetSymbolKind } from "../../session/target-input.ts";
@@ -59,6 +61,7 @@ function anchorOf(s: CodeSymbol): CodeSymbol["declarationAnchor"] {
 async function refineResolvedSymbolAnchor(
   workspaceSymbol: CodeSymbol,
   semantic: SemanticSubstrate,
+  control?: CodeRequestControl,
 ): Promise<CodeSymbol> {
   try {
     const result = await semantic.documentSymbols(workspaceSymbol.file);
@@ -84,7 +87,8 @@ async function refineResolvedSymbolAnchor(
     }
 
     return refined;
-  } catch {
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
     return workspaceSymbol;
   }
 }
@@ -107,6 +111,7 @@ export async function resolveSymbolTarget(
     kind?: TargetSymbolKind;
     exportedOnly?: boolean;
     maxResults?: number;
+    control?: CodeRequestControl;
   },
 ): Promise<TargetOutcome> {
   const result = await semantic.workspaceSymbols(symbol);
@@ -150,12 +155,25 @@ export async function resolveSymbolTarget(
         cwd,
         maxResults: options.maxResults,
         requestedKind,
+        control: options.control,
       });
     }
-    return resolveCandidates(exactKind, semantic, cwd, options.maxResults);
+    return resolveCandidates({
+      candidates: exactKind,
+      semantic,
+      cwd,
+      maxResults: options.maxResults,
+      control: options.control,
+    });
   }
 
-  return resolveCandidates(eligible, semantic, cwd, options?.maxResults);
+  return resolveCandidates({
+    candidates: eligible,
+    semantic,
+    cwd,
+    maxResults: options?.maxResults,
+    control: options?.control,
+  });
 }
 
 function providerKindMatches(reported: string, requested: TargetSymbolKind): boolean {
@@ -166,18 +184,20 @@ function normalizeProviderKind(kind: string): string {
   return kind.replace(/[\s_-]/g, "").toLowerCase();
 }
 
-async function resolveCandidates(
-  candidates: readonly CodeSymbol[],
-  semantic: SemanticSubstrate,
-  cwd: string,
-  maxResults?: number,
-): Promise<TargetOutcome> {
+async function resolveCandidates(options: {
+  candidates: readonly CodeSymbol[];
+  semantic: SemanticSubstrate;
+  cwd: string;
+  maxResults?: number;
+  control?: CodeRequestControl;
+}): Promise<TargetOutcome> {
+  const { candidates, semantic, cwd, maxResults, control } = options;
   const ranged = candidates.filter(
     (candidate) =>
       candidate.declarationAnchor.line > 0 || candidate.declarationAnchor.character > 0,
   );
   if (ranged.length === 1) {
-    return resolvedTarget(await refineResolvedSymbolAnchor(ranged[0], semantic));
+    return resolvedTarget(await refineResolvedSymbolAnchor(ranged[0], semantic, control));
   }
   return buildCandidateOutcome({
     kind: "disambiguation",
@@ -185,6 +205,7 @@ async function resolveCandidates(
     semantic,
     cwd,
     maxResults,
+    control,
   });
 }
 
@@ -220,7 +241,7 @@ type CandidateOutcomeOptions = CandidateOutcomeBase &
   (
     | { kind: "disambiguation"; requestedKind?: never }
     | { kind: "kind-mismatch"; requestedKind: TargetSymbolKind }
-  );
+  ) & { control?: CodeRequestControl };
 
 /**
  * Refine only bounded visible candidates to name anchors while retaining the
@@ -234,7 +255,7 @@ async function buildCandidateOutcome(
   const refined = await Promise.all(
     options.candidates
       .slice(0, cap)
-      .map((candidate) => refineResolvedSymbolAnchor(candidate, options.semantic)),
+      .map((candidate) => refineResolvedSymbolAnchor(candidate, options.semantic, options.control)),
   );
   const common = {
     candidates: toDisambiguationCandidates(refined, options.cwd),

package/src/api.ts

@@ -57,6 +57,7 @@ export type { TargetSymbolKind } from "./session/target-input.ts";
 // Code-intelligence-specific result types.
 export type {
   CodeIntelResult,
+  CodeIntelResultDetails,
   ContextDetails,
   DisambiguationCandidate,
   HealthDetails,
@@ -65,4 +66,7 @@ export type {
   OrientationSectionDetails,
   ResolveDetails,
   SearchDetails,
+  ToolDisplaySection,
+  ToolOutputTruncationDetails,
+  ToolResultStatus,
 } from "./types/index.ts";

package/src/diagnostics/evidence.ts

@@ -0,0 +1,51 @@
+import * as path from "node:path";
+import type {
+  DiagnosticEvidenceDocument,
+  DiagnosticEvidenceStatus,
+  DiagnosticEvidenceSummary,
+} from "@mrclrchtr/supi-lsp/api";
+
+/** Merge file-local diagnostic evidence without inventing coverage. */
+export function mergeDiagnosticEvidence(
+  previous: DiagnosticEvidenceSummary,
+  latest: DiagnosticEvidenceSummary,
+  cwd?: string,
+  policy: "latest" | "conservative" = "latest",
+): DiagnosticEvidenceSummary {
+  const byFile = new Map<string, DiagnosticEvidenceDocument>();
+  for (const document of [...previous.documents, ...latest.documents]) {
+    const file = cwd ? path.relative(cwd, path.resolve(cwd, document.file)) : document.file;
+    const next = { file, status: document.status };
+    const previousDocument = byFile.get(file);
+    if (
+      !previousDocument ||
+      policy === "latest" ||
+      evidenceStatusRank(next.status) > evidenceStatusRank(previousDocument.status)
+    ) {
+      byFile.set(file, next);
+    }
+  }
+  const documents = Array.from(byFile.values()).sort((a, b) => a.file.localeCompare(b.file));
+  const counts = {
+    requested: documents.length,
+    confirmed: 0,
+    unconfirmed: 0,
+    failed: 0,
+    removed: 0,
+  };
+  for (const document of documents) counts[document.status]++;
+  return { ...counts, documents };
+}
+
+function evidenceStatusRank(status: DiagnosticEvidenceStatus): number {
+  switch (status) {
+    case "confirmed":
+      return 1;
+    case "unconfirmed":
+      return 2;
+    case "failed":
+      return 3;
+    case "removed":
+      return 4;
+  }
+}

package/src/session/capability-adapter.ts

@@ -9,6 +9,7 @@
 
 import {
   type CapabilityState,
+  type CodeRequestControl,
   getDefaultWorkspaceRuntime,
   type SemanticProvider,
   type StructuralProvider,
@@ -67,7 +68,11 @@ export interface CapabilityAdapter {
    * the target workflow can decide whether to proceed, return a
    * timeout note, or return an unavailable result.
    */
-  ensureSemanticReadiness(cwd: string, scope: ReadinessScope): Promise<ReadinessOutcome>;
+  ensureSemanticReadiness(
+    cwd: string,
+    scope: ReadinessScope,
+    control?: CodeRequestControl,
+  ): Promise<ReadinessOutcome>;
 }
 
 // ── Production adapter ────────────────────────────────────────────────
@@ -107,8 +112,12 @@ export class WorkspaceCapabilityAdapter implements CapabilityAdapter {
     return null;
   }
 
-  async ensureSemanticReadiness(cwd: string, scope: ReadinessScope): Promise<ReadinessOutcome> {
-    const result = await ensureSemanticReadiness(cwd, scope);
+  async ensureSemanticReadiness(
+    cwd: string,
+    scope: ReadinessScope,
+    control?: CodeRequestControl,
+  ): Promise<ReadinessOutcome> {
+    const result = await ensureSemanticReadiness(cwd, scope, undefined, control);
     return result;
   }
 

package/src/session/find-workflow.ts

@@ -30,7 +30,8 @@ export async function runFindWorkflow(
   const scope = resolveScopeSet(request.scope ? [...request.scope] : undefined, deps.cwd);
   if (scope.kind === "error") return { kind: "invalid-input", message: scope.reason };
 
-  throwIfAborted(control);
+  if (mode === "ast") control?.signal?.throwIfAborted();
+  else throwIfAborted(control);
   reportProgress(control, {
     intent: "find",
     phase: mode,
@@ -69,9 +70,11 @@ async function runSemanticSearch(options: {
   control?: WorkflowControl;
 }): Promise<FindWorkflowOutcome> {
   const { query, scopePaths, scopeLabel, maxResults, deps, control } = options;
-  const readiness = await deps.capability.ensureSemanticReadiness(deps.cwd, {
-    kind: "workspace",
-  });
+  const readiness = await deps.capability.ensureSemanticReadiness(
+    deps.cwd,
+    { kind: "workspace" },
+    control,
+  );
   if (readiness.kind === "timeout") {
     return { kind: "unavailable", reason: "Semantic readiness timed out." };
   }
@@ -82,7 +85,10 @@ async function runSemanticSearch(options: {
   if (!provider?.workspaceSymbols) {
     return { kind: "unavailable", reason: "No semantic workspace-symbol provider is active." };
   }
-  const result = await provider.workspaceSymbols(query);
+  const result = await provider.workspaceSymbols(query, control);
+  // A cancellation that landed during the request must not publish symbols
+  // the caller no longer awaits.
+  throwIfAborted(control);
   if (result.kind === "unavailable") {
     return { kind: "unavailable", reason: result.reason };
   }
@@ -120,13 +126,17 @@ async function runAstSearch(options: {
   if (!provider) {
     return { kind: "unavailable", reason: "No structural provider is active." };
   }
-  throwIfAborted(control);
+  control?.signal?.throwIfAborted();
   const outcome = await getStructuredPatternMatches({
     params: { pattern: query, kind: input.kind },
     roots: scopePaths,
     cwd: deps.cwd,
     structural: provider,
-    control: { signal: control?.signal },
+    control: {
+      operationId: control?.operationId,
+      signal: control?.signal,
+      deadline: control?.deadline,
+    },
   });
   if (outcome.kind === "invalid-input") return outcome;
   if (outcome.kind === "unavailable") return outcome;

package/src/session/graph/collect.ts

@@ -1,5 +1,10 @@
 /** Presentation-neutral relation collection used by the session-owned graph workflow. */
 
+import {
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
 import type { CodeProvider } from "../../analysis/provider.ts";
 import {
   readNextEnclosingScope,
@@ -25,6 +30,7 @@ export interface CollectRelationOptions {
   semanticReadinessError: string | null;
   anchorKind: AnchorKind;
   calleeDepth?: "direct" | "deep";
+  requestControl?: CodeRequestControl;
 }
 
 /** Collect one evidence-backed graph relation without rendering it. */
@@ -46,6 +52,7 @@ export async function collectRelation(
         return collectImplementationsRelation(options);
     }
   } catch (error) {
+    if (isCodeRequestInterruption(error, options.requestControl)) throw error;
     return {
       kind: "unavailable",
       rel: relation,
@@ -61,7 +68,11 @@ async function collectReferences(options: CollectRelationOptions): Promise<Graph
 
   const result = await collectCallers(options.file, options.position, options.displayName, {
     cwd: options.cwd,
-    provider: { references: options.provider.references },
+    provider: {
+      references: async (file, position) =>
+        options.provider?.references(file, position, options.requestControl) ??
+        unavailableCodeQuery("References unavailable"),
+    },
   });
   if (result.confidence === "unavailable") {
     return { kind: "unavailable", rel: "references", message: "References unavailable" };
@@ -118,6 +129,7 @@ async function collectCalleesRelation(options: CollectRelationOptions): Promise<
     { cwd: options.cwd, provider: { calleesAt: options.provider.calleesAt } },
     undefined,
     options.calleeDepth ?? "direct",
+    options.requestControl,
   );
   if (result.confidence === "unavailable") {
     return { kind: "unavailable", rel: "callees", message: "Callees unavailable" };
@@ -161,7 +173,11 @@ async function collectImplementationsRelation(
 
   const result = await collectImplementations(options.file, options.position, options.displayName, {
     cwd: options.cwd,
-    provider: { implementation: options.provider.implementation },
+    provider: {
+      implementation: async (file, position) =>
+        options.provider?.implementation(file, position, options.requestControl) ??
+        unavailableCodeQuery("Implementations unavailable"),
+    },
   });
   if (result.confidence === "unavailable") {
     return { kind: "unavailable", rel: "implements", message: "Implementations unavailable" };

package/src/session/graph-workflow.ts

@@ -54,7 +54,9 @@ export async function runGraphWorkflow(
       maxResults: request.maxResults,
     },
     deps,
+    control,
   );
+  throwIfAborted(control);
   if (targetOutcome.kind === "target-group") {
     return {
       kind: "invalid-input",
@@ -64,12 +66,13 @@ export async function runGraphWorkflow(
   if (targetOutcome.kind !== "resolved") return targetOutcome;
 
   const entry = targetOutcome.entry;
-  const semanticReadinessError = await getSemanticReadinessError(
+  const semanticReadinessError = await getSemanticReadinessError({
     relations,
-    entry.file,
-    deps.capability,
-    deps.cwd,
-  );
+    file: entry.file,
+    capability: deps.capability,
+    cwd: deps.cwd,
+    control,
+  });
   const provider = deps.capability.getProvider(deps.cwd);
   const maxResults = request.maxResults ?? 8;
   const displayName =
@@ -94,9 +97,11 @@ export async function runGraphWorkflow(
         semanticReadinessError,
         anchorKind: entry.anchorKind,
         calleeDepth: request.calleeDepth,
+        requestControl: control,
       }),
     );
   }
+  throwIfAborted(control);
 
   if (sections.length > 0 && sections.every((section) => section.kind === "unavailable")) {
     return {
@@ -127,16 +132,18 @@ function normalizeRelations(
   return requested as readonly GraphRelationKind[];
 }
 
-async function getSemanticReadinessError(
-  relations: readonly GraphRelationKind[],
-  file: string,
-  capability: CapabilityAdapter,
-  cwd: string,
-): Promise<string | null> {
+async function getSemanticReadinessError(options: {
+  relations: readonly GraphRelationKind[];
+  file: string;
+  capability: CapabilityAdapter;
+  cwd: string;
+  control?: WorkflowControl;
+}): Promise<string | null> {
+  const { relations, file, capability, cwd, control } = options;
   if (!relations.some((relation) => relation === "references" || relation === "implements")) {
     return null;
   }
-  const readiness = await capability.ensureSemanticReadiness(cwd, { kind: "file", file });
+  const readiness = await capability.ensureSemanticReadiness(cwd, { kind: "file", file }, control);
   if (readiness.kind === "ready") return null;
   if (readiness.kind === "timeout") {
     return "Semantic readiness timed out. Retry shortly or inspect code_health.";