@mrclrchtr/supi-code-intelligence 4.10.0 → 5.0.0

package/src/substrate/lsp/lifecycle.ts

@@ -4,66 +4,49 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { acquireWorkspaceProviderHost } from "../workspace-provider-host.ts";
 import { LSP_STATE_CHANGE_EVENT, type LspAdapterState } from "./state.ts";
 
-const STATE_CHANGE_EVENT = new Event(LSP_STATE_CHANGE_EVENT);
-
-/** Poll interval (ms) for detecting server readiness transitions in the footer. */
-const READINESS_POLL_MS = 2_000;
-
 /** Acquire providers once per workspace and release them after the final Pi session ends. */
 export function registerLspSessionLifecycle(
   pi: ExtensionAPI,
   state: LspAdapterState,
   onStarted?: (ctx: ExtensionContext) => void | Promise<void>,
 ): void {
-  let readinessTimer: ReturnType<typeof setInterval> | null = null;
-  let lastFingerprint = "";
+  let disposeLifecycle: (() => void) | null = null;
+  let subscriptionGeneration = 0;
 
-  function fingerprint(): string {
-    const servers = state.controller?.workspaceRuntime?.getProjectServers();
-    if (!servers) return "";
-    let ready = 0;
-    let starting = 0;
-    let error = 0;
-    let unavailable = 0;
-    let openFiles = 0;
-    for (const s of servers) {
-      openFiles += s.openFiles.length;
-      if (s.status === "running" && s.ready) ready++;
-      else if (s.status === "running") starting++;
-      else if (s.status === "error") error++;
-      else unavailable++;
-    }
-    return `${ready}:${starting}:${error}:${unavailable}:${openFiles}`;
+  function dispatchStateChange(): void {
+    state.stateChanges.dispatchEvent(new Event(LSP_STATE_CHANGE_EVENT));
   }
 
-  function startReadinessPolling(): void {
-    stopReadinessPolling();
-    lastFingerprint = fingerprint();
-    readinessTimer = setInterval(() => {
-      if (state.controller?.kind !== "ready") return;
-      const current = fingerprint();
-      if (current === lastFingerprint) return;
-      lastFingerprint = current;
-      state.stateChanges.dispatchEvent(STATE_CHANGE_EVENT);
-    }, READINESS_POLL_MS);
-    readinessTimer.unref?.();
+  function stopLifecycleSubscription(): void {
+    subscriptionGeneration++;
+    disposeLifecycle?.();
+    disposeLifecycle = null;
   }
 
-  function stopReadinessPolling(): void {
-    if (readinessTimer) {
-      clearInterval(readinessTimer);
-      readinessTimer = null;
+  function startLifecycleSubscription(): void {
+    stopLifecycleSubscription();
+    const controller = state.controller;
+    if (!controller) {
+      dispatchStateChange();
+      return;
     }
-    lastFingerprint = "";
+    const generation = subscriptionGeneration;
+    let receivedInitialTransition = false;
+    disposeLifecycle = controller.subscribeLifecycle(() => {
+      if (generation !== subscriptionGeneration) return;
+      receivedInitialTransition = true;
+      dispatchStateChange();
+    });
+    if (!receivedInitialTransition) dispatchStateChange();
   }
 
   pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+    stopLifecycleSubscription();
     await state.providerLease?.release();
     state.providerLease = null;
     state.controller = null;
     state.lspActive = false;
     state.sentinelSnapshot = new Map();
-    stopReadinessPolling();
 
     const lease = await acquireWorkspaceProviderHost(ctx.cwd, {
       projectTrusted: ctx.isProjectTrusted(),
@@ -73,19 +56,16 @@ export function registerLspSessionLifecycle(
     state.lspActive = lease.lspController?.kind === "ready";
     state.sentinelSnapshot = lease.sentinelSnapshot;
     await onStarted?.(ctx);
-
-    // Dispatch initial server list so the footer shows starting servers immediately.
-    state.stateChanges.dispatchEvent(STATE_CHANGE_EVENT);
-    // Poll for readiness transitions (running → ready, errors, etc.).
-    startReadinessPolling();
+    startLifecycleSubscription();
   });
 
   pi.on("session_shutdown", async () => {
-    stopReadinessPolling();
+    stopLifecycleSubscription();
     await state.providerLease?.release();
     state.providerLease = null;
     state.controller = null;
     state.lspActive = false;
     state.sentinelSnapshot = new Map();
+    dispatchStateChange();
   });
 }

package/src/substrate/lsp/maintenance.ts

@@ -6,70 +6,244 @@
  * semantic tool queries.
  */
 
+import { statSync } from "node:fs";
 import * as nodePath from "node:path";
-import type { WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
+import {
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { DiagnosticEvidenceSummary } from "@mrclrchtr/supi-lsp/api";
 import {
   clearTsconfigCache,
   isLikelyStaleDiagnostic,
+  raceRequestControl,
   syncWorkspaceSentinelSnapshot,
+  type WorkspaceLspRuntime,
 } from "@mrclrchtr/supi-lsp/api";
+import { mergeDiagnosticEvidence } from "../../diagnostics/evidence.ts";
 
 /**
- * Run sentinel-sync, stale-module resync, prune, and diagnostic refresh
- * as a single maintenance pass. Call before explicit diagnostic queries
- * (code_health with refresh:true) or semantic tool readiness checks.
+ * Run sentinel-sync, diagnostic refresh, and stale-module resync as a single
+ * maintenance pass. Call before explicit diagnostic queries (code_health with
+ * refresh:true) or semantic tool readiness checks.
  */
 export async function refreshLspMaintenance(
   runtime: WorkspaceLspRuntime,
   cwd: string,
   sentinelSnapshot: Map<string, number>,
-): Promise<Map<string, number>> {
-  // Sentinel refresh: detect lockfile/tsconfig/d.ts changes from outside
-  // write/edit/code_refactor_apply.
-  const { snapshot, changes } = syncWorkspaceSentinelSnapshot(cwd, sentinelSnapshot);
+  control?: CodeRequestControl,
+): Promise<WorkspaceLspMaintenanceResult> {
+  const { snapshot } = synchronizeSentinels(runtime, cwd, sentinelSnapshot);
+  let diagnosticEvidence = emptyEvidence();
+  let failureReason: string | undefined;
 
-  if (changes.length > 0) {
-    clearTsconfigCache();
-    runtime.noteWorkspaceChanges(changes);
+  // Refresh before stale-module inspection. The refresh owns deleted-file
+  // classification; later snapshots must not erase its removed evidence.
+  try {
+    diagnosticEvidence = await runtime.refreshOpenDiagnostics(undefined, control);
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
+    failureReason = errorMessage(error);
+    diagnosticEvidence = readRuntimeEvidence(runtime);
+  }
+
+  try {
+    const staleResult = await resyncStaleModuleFiles(runtime, cwd, control);
+    diagnosticEvidence = mergeDiagnosticEvidence(diagnosticEvidence, staleResult.evidence, cwd);
+    if (staleResult.completed) failureReason = undefined;
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
+    // Keep evidence from the first refresh when stale inspection fails.
   }
 
-  // Stale-module resync: force-reopen files with "Cannot find module" errors
-  await resyncStaleModuleFiles(runtime, cwd);
+  return {
+    snapshot,
+    diagnosticEvidence,
+    ...(failureReason ? { failureReason } : {}),
+  };
+}
+
+/** Sentinel state and diagnostic evidence retained from one workspace pass. */
+export interface WorkspaceLspMaintenanceResult {
+  /** The next sentinel snapshot for the session-owned maintenance state. */
+  snapshot: Map<string, number>;
+  /** Evidence from every diagnostic refresh performed by this pass. */
+  diagnosticEvidence: DiagnosticEvidenceSummary;
+  /** Failure from the first workspace refresh, when no fresh pass completed. */
+  failureReason?: string;
+}
+
+/** Sentinel state and stale-file facts from one file-scoped pass. */
+export interface FileLspMaintenanceResult {
+  /** The next sentinel snapshot for the session-owned maintenance state. */
+  snapshot: Map<string, number>;
+  /** Number of stale files that matched the requested file. */
+  matchedStaleFileCount: number;
+}
+
+/** Refresh sentinel and stale-module state for one exact file without a workspace resync. */
+export async function refreshFileLspMaintenance(options: {
+  runtime: WorkspaceLspRuntime;
+  cwd: string;
+  sentinelSnapshot: Map<string, number>;
+  filePath: string;
+  control?: CodeRequestControl;
+}): Promise<FileLspMaintenanceResult> {
+  const { runtime, cwd, sentinelSnapshot, filePath, control } = options;
+  // A cancelled caller stops before any maintenance work starts.
+  throwIfCodeRequestInterrupted(control);
+  const { snapshot } = synchronizeSentinels(runtime, cwd, sentinelSnapshot);
+  const target = nodePath.resolve(filePath);
+  const stale = runtime
+    .getOutstandingDiagnostics(1)
+    .entries.some(
+      (entry) =>
+        nodePath.resolve(cwd, entry.file) === target &&
+        entry.diagnostics.some((diagnostic) => isLikelyStaleDiagnostic(diagnostic)),
+    );
 
-  // Two-pass prune/refresh for diagnostics
   runtime.pruneMissingFiles();
-  try {
-    await runtime.refreshOpenDiagnostics();
-  } catch {
-    /* best-effort */
+  if (stale) {
+    runtime.closeFile(target);
+    // Race the caller's cancellation so a client start during re-open does
+    // not outlive the caller; the underlying runtime keeps its own lifecycle.
+    await raceRequestControl(runtime.trackFile(target), control);
   }
   runtime.pruneMissingFiles();
+  throwIfCodeRequestInterrupted(control);
 
-  return snapshot;
+  return { snapshot, matchedStaleFileCount: stale ? 1 : 0 };
+}
+
+function synchronizeSentinels(
+  runtime: WorkspaceLspRuntime,
+  cwd: string,
+  sentinelSnapshot: Map<string, number>,
+) {
+  const state = syncWorkspaceSentinelSnapshot(cwd, sentinelSnapshot);
+  if (state.changes.length > 0) {
+    clearTsconfigCache();
+    runtime.noteWorkspaceChanges(state.changes);
+  }
+  return state;
 }
 
 /** Re-open files with stale module-resolution errors. */
-async function resyncStaleModuleFiles(runtime: WorkspaceLspRuntime, cwd: string): Promise<void> {
+async function resyncStaleModuleFiles(
+  runtime: WorkspaceLspRuntime,
+  cwd: string,
+  control?: CodeRequestControl,
+): Promise<{ evidence: DiagnosticEvidenceSummary; completed: boolean }> {
   const outstanding = runtime.getOutstandingDiagnostics(1);
   const staleFiles: string[] = [];
 
-  for (const entry of outstanding) {
+  for (const entry of outstanding.entries) {
     if (entry.diagnostics.some((d) => isLikelyStaleDiagnostic(d))) {
       staleFiles.push(entry.file);
     }
   }
 
-  if (staleFiles.length === 0) return;
+  if (staleFiles.length === 0) return { evidence: emptyEvidence(), completed: false };
 
+  const invalidated: Array<{
+    file: string;
+    status: "unconfirmed" | "failed" | "removed";
+  }> = staleFiles.map((file) => ({
+    file: nodePath.relative(cwd, nodePath.resolve(cwd, file)),
+    status: "unconfirmed",
+  }));
   for (const file of staleFiles) {
     const filePath = nodePath.resolve(cwd, file);
+    const relativeFile = nodePath.relative(cwd, filePath);
     runtime.closeFile(filePath);
-    await runtime.trackFile(filePath);
+    try {
+      if (!(await runtime.trackFile(filePath))) {
+        markUnavailable(invalidated, relativeFile, filePath);
+      }
+    } catch (error) {
+      if (isCodeRequestInterruption(error, control)) throw error;
+      markUnavailable(invalidated, relativeFile, filePath);
+    }
+  }
+
+  try {
+    return {
+      evidence: mergeDiagnosticEvidence(
+        {
+          requested: invalidated.length,
+          confirmed: 0,
+          unconfirmed: invalidated.length,
+          failed: 0,
+          removed: 0,
+          documents: invalidated,
+        },
+        await runtime.refreshOpenDiagnostics({ quietMs: 300, maxWaitMs: 2000 }, control),
+        cwd,
+      ),
+      completed: true,
+    };
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
+    return {
+      evidence: {
+        requested: invalidated.length,
+        confirmed: 0,
+        unconfirmed: invalidated.filter((document) => document.status === "unconfirmed").length,
+        failed: invalidated.filter((document) => document.status === "failed").length,
+        removed: invalidated.filter((document) => document.status === "removed").length,
+        documents: invalidated,
+      },
+      completed: false,
+    };
   }
+}
+
+function markUnavailable(
+  documents: Array<{ file: string; status: "unconfirmed" | "failed" | "removed" }>,
+  file: string,
+  filePath: string,
+): void {
+  const entry = documents.find((document) => document.file === file);
+  if (entry) entry.status = diagnosticFailureStatus(filePath);
+}
 
+function diagnosticFailureStatus(filePath: string): "failed" | "removed" {
   try {
-    await runtime.refreshOpenDiagnostics({ quietMs: 300, maxWaitMs: 2000 });
+    statSync(filePath);
+    return "failed";
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return "removed";
+    }
+    return "failed";
+  }
+}
+
+function readRuntimeEvidence(runtime: WorkspaceLspRuntime): DiagnosticEvidenceSummary {
+  try {
+    return runtime.getWorkspaceDiagnosticSummary().evidence;
   } catch {
-    /* best-effort */
+    return emptyEvidence();
   }
 }
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : "Diagnostic refresh failed.";
+}
+
+function emptyEvidence(): DiagnosticEvidenceSummary {
+  return {
+    requested: 0,
+    confirmed: 0,
+    unconfirmed: 0,
+    failed: 0,
+    removed: 0,
+    documents: [],
+  };
+}

package/src/substrate/lsp/state.ts

@@ -25,7 +25,7 @@ export interface LspAdapterState {
   lspActive: boolean;
   /** Snapshot of workspace sentinel files (package.json, tsconfig, lockfiles) for change detection. */
   sentinelSnapshot: Map<string, number>;
-  /** Fired when server statuses or readiness change — footer listens for re-renders. */
+  /** Fired for runtime lifecycle changes that require a footer render. */
   stateChanges: EventTarget;
 }
 
@@ -40,5 +40,5 @@ export function createLspAdapterState(): LspAdapterState {
   };
 }
 
-/** Event type dispatched on {@link LspAdapterState.stateChanges} when server statuses change. */
+/** Event type dispatched on {@link LspAdapterState.stateChanges} for LSP lifecycle changes. */
 export const LSP_STATE_CHANGE_EVENT = "server-status-changed" as const;

package/src/substrate/workspace-provider-host.ts

@@ -5,9 +5,11 @@ import { LspRuntimeController, scanWorkspaceSentinels } from "@mrclrchtr/supi-ls
 import { TreeSitterRuntimeController } from "@mrclrchtr/supi-tree-sitter/api";
 
 const HOSTS = Symbol.for("supi-code-intelligence/workspace-provider-hosts");
+const CLOSING_HOSTS = Symbol.for("supi-code-intelligence/closing-workspace-provider-hosts");
 const SHUTDOWN_GRACE_MS = 2_000;
 
 type HostRegistry = Map<string, WorkspaceProviderHost>;
+type ClosingHostRegistry = Map<string, Promise<void>>;
 
 /** One acquired reference to a process-shared Workspace provider host. */
 export interface WorkspaceProviderHostLease {
@@ -23,6 +25,12 @@ function registry(): HostRegistry {
   return global[HOSTS];
 }
 
+function closingRegistry(): ClosingHostRegistry {
+  const global = globalThis as typeof globalThis & { [CLOSING_HOSTS]?: ClosingHostRegistry };
+  global[CLOSING_HOSTS] ??= new Map();
+  return global[CLOSING_HOSTS];
+}
+
 function canonicalWorkspace(cwd: string): string {
   try {
     return realpathSync(cwd);
@@ -76,8 +84,16 @@ class WorkspaceProviderHost {
         released = true;
         this.#leases--;
         if (this.#leases === 0) {
-          registry().delete(this.cwd);
-          await this.#shutdown();
+          await Promise.resolve();
+          if (this.#leases !== 0) return;
+          const shutdown = this.#shutdown();
+          closingRegistry().set(this.cwd, shutdown);
+          try {
+            await shutdown;
+          } finally {
+            if (closingRegistry().get(this.cwd) === shutdown) closingRegistry().delete(this.cwd);
+            registry().delete(this.cwd);
+          }
         }
       },
     };
@@ -101,7 +117,7 @@ class WorkspaceProviderHost {
     this.#closed = true;
     await Promise.all([
       ...(this.#lsp ? [settleWithin(this.#lsp.shutdown())] : []),
-      ...(this.#tree ? [settleWithin(this.#tree.shutdown())] : []),
+      ...(this.#tree ? [this.#tree.shutdown()] : []),
     ]);
     this.#lsp = null;
     this.#tree = null;
@@ -114,6 +130,11 @@ export async function acquireWorkspaceProviderHost(
   options: { projectTrusted: boolean },
 ): Promise<WorkspaceProviderHostLease> {
   const workspace = canonicalWorkspace(cwd);
+  for (;;) {
+    const closing = closingRegistry().get(workspace);
+    if (!closing) break;
+    await closing.catch(() => undefined);
+  }
   const hosts = registry();
   let host = hosts.get(workspace);
   if (!host) {
@@ -126,4 +147,5 @@ export async function acquireWorkspaceProviderHost(
 /** Clear process-shared hosts between isolated tests. */
 export function resetWorkspaceProviderHostsForTests(): void {
   registry().clear();
+  closingRegistry().clear();
 }

package/src/tool/find/execute.ts

@@ -26,12 +26,18 @@ export async function executeFindTool(
     return searchErrorResult(`**Error:** ${outcome.message}`, {
       scope: Array.isArray(params?.scope) ? params.scope.join(", ") : null,
       nextQueries: ["Fix the search input and retry"],
+      message: outcome.message,
     });
   }
 
   const assembly = assembleFindWorkflowResult(outcome);
   return {
     content: renderFindResult(assembly),
-    details: { type: "search", data: assembly.details },
+    details: {
+      type: "search",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
   };
 }

package/src/tool/find/render.ts

@@ -38,9 +38,7 @@ function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMeta
   const { outcome } = assembly;
   if (outcome.data.kind !== "semantic") return "";
   const symbols = outcome.data.symbols;
-  if (symbols.length === 0) {
-    return `**Semantic search** — \`${outcome.query}\`\n\nNo semantic results found in \`${outcome.scopeLabel}\`.`;
-  }
+  if (symbols.length === 0) return renderEmptySemantic(assembly, evidence);
 
   const lines = [
     `**Semantic search** — \`${outcome.query}\` (${symbols.length} symbol${symbols.length === 1 ? "" : "s"} found)`,
@@ -55,3 +53,22 @@ function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMeta
   if (disclosure) lines.push(disclosure);
   return lines.join("\n");
 }
+
+function renderEmptySemantic(assembly: FindResultAssembly, evidence: EvidenceListMetadata): string {
+  const { outcome } = assembly;
+  const lines = [
+    `**Semantic search** — \`${outcome.query}\``,
+    "",
+    evidence.partialReason
+      ? `No LSP workspace-symbol results were collected in \`${outcome.scopeLabel}\`.`
+      : `No LSP workspace-symbol results found in \`${outcome.scopeLabel}\`.`,
+  ];
+  const disclosure = renderEvidenceListMetadataDisclosure(evidence);
+  if (disclosure) lines.push("", disclosure);
+  lines.push("", "Document-level semantic symbols can differ from the workspace index.");
+  const fileQuery = assembly.assembled.actions.find(
+    (action) => action.kind === "query" && action.instruction.startsWith("If you know the file"),
+  );
+  if (fileQuery?.kind === "query") lines.push(fileQuery.instruction);
+  return lines.join("\n");
+}

package/src/tool/find/tui.ts

@@ -1,39 +1,41 @@
-/**
- * TUI renderer for code_find — renderCall + renderResult.
- */
+/** TUI renderer for code_find. */
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { type ResultOptios, renderSimpleResult, type ToolResult } from "../../ui/tui/common.ts";
+import {
+  formatCallValue,
+  type ResultOptios,
+  renderSimpleResult,
+  type ToolRendererContext,
+  type ToolResult,
+} from "../../ui/tui/common.ts";
 import type { CodeFindToolParams } from "./execute.ts";
 
-/** ── renderCall ────────────────────────────────────────────────── */
-
-export function renderFindCall(args: unknown, theme: Theme, _context: unknown): Text {
-  const params = (args ?? {}) as CodeFindToolParams;
-  const mode = params.mode ?? "mode?";
+/** Render the compact code_find call header. */
+export function renderFindCall(
+  args: unknown,
+  theme: Theme,
+  _context: ToolRendererContext | undefined,
+): Text {
+  const params = (args ?? {}) as Partial<CodeFindToolParams>;
+  const mode = formatCallValue(params.mode, 20) ?? "mode?";
 
   let content = theme.fg("toolTitle", "code_find");
-
-  if (params.query) {
-    content += ` ${theme.fg("accent", JSON.stringify(params.query))}`;
-  }
-
+  const query = formatCallValue(params.query);
+  if (query) content += ` ${theme.fg("accent", JSON.stringify(query))}`;
   content += ` ${theme.fg("muted", mode)}`;
 
-  if (params.kind) {
-    content += theme.fg("dim", ` [${params.kind}]`);
-  }
+  const kind = formatCallValue(params.kind, 30);
+  if (kind) content += theme.fg("dim", ` [${kind}]`);
 
   return new Text(content, 0, 0);
 }
 
-/** ── renderResult ──────────────────────────────────────────────── */
-
+/** Render code_find progress, status, and structured result details. */
 export function renderFindResult(
   result: ToolResult,
   options: ResultOptios,
   theme: Theme,
-  _context: unknown,
+  context: ToolRendererContext | undefined,
 ): ReturnType<typeof renderSimpleResult> {
-  return renderSimpleResult(result, options, theme, "Searching…");
+  return renderSimpleResult(result, options, theme, "Searching…", context);
 }

package/src/tool/graph/execute.ts

@@ -4,6 +4,7 @@ import type { GraphWorkflowInput, RequestedGraphRelation } from "../../session/g
 import type { GraphTargetInput } from "../../session/target-input.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
 import { toWorkflowControl } from "../infra/workflow-control.ts";
+import { createToolDisplaySection } from "../result/display.ts";
 import { searchErrorResult } from "../result/errors.ts";
 import { assembleGraphResult } from "../result/graph.ts";
 import { renderGraphResult } from "./markdown.ts";
@@ -25,7 +26,7 @@ export async function executeGraphTool(
 
   if (outcome.kind === "unavailable") throw new Error(outcome.reason);
   if (outcome.kind === "invalid-input") {
-    return searchErrorResult(`**Error:** ${outcome.message}`);
+    return searchErrorResult(`**Error:** ${outcome.message}`, { message: outcome.message });
   }
   if (outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch") {
     const lines = [
@@ -45,7 +46,21 @@ export async function executeGraphTool(
         "Retry without `symbolKind`, use an observed provider kind, or choose a handle.",
       );
     }
-    return searchErrorResult(lines.join("\n"));
+    return searchErrorResult(lines.join("\n"), {
+      message:
+        outcome.kind === "kind-mismatch"
+          ? `No target matched provider kind ${outcome.requestedKind}.`
+          : "The target is ambiguous.",
+      displaySections: [
+        createToolDisplaySection({
+          key: "graph.candidates",
+          title: "Candidates",
+          items: outcome.candidates,
+          format: (candidate) =>
+            `${candidate.targetId} — ${candidate.name} (${candidate.kind ?? "unknown"}) at ${candidate.file}:${candidate.line}:${candidate.character}`,
+        }),
+      ],
+    });
   }
 
   const assembly = assembleGraphResult({
@@ -57,6 +72,11 @@ export async function executeGraphTool(
   });
   return {
     content: renderGraphResult(assembly),
-    details: { type: "search", data: assembly.details },
+    details: {
+      type: "search",
+      data: assembly.details,
+      status: "completed",
+      displaySections: assembly.displaySections,
+    },
   };
 }