@danypops/pi-lector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Popsuevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# pi-lector
+
+Pi host adapter for Lector: overrides `read`, `write`, and `edit` with a
+daemon-backed, hash-guarded filesystem. Requires a running Lector daemon
+(`lector serve`) — no auto-spawn.
+
+`populate_symbol_graph` submits bounded background work and waits briefly. If the
+graph is still loading, it returns a job id immediately; `job_status` polls that id
+later without forcing the agent into a blocking or blind polling loop.
+
+When a session starts inside a Git repository, pi-lector checks a durable, bounded
+source-content manifest without blocking startup. The footer reports not cached,
+caching, or cached; completion also emits a one-shot notification. Session shutdown
+stops polling, and the agent receives each state transition once in its context.

package/extension/src/code-intelligence-hints.ts

@@ -0,0 +1,38 @@
+import type { Diagnostic, DocumentSymbolEntry } from "@danypops/lector";
+
+/** Only "error"/"warning" ever surface -- an "info"/"hint" on every keystroke would make the hint noisier than the edit it's attached to. */
+function isNoteworthy(diagnostic: Diagnostic): boolean {
+	return diagnostic.severity === "error" || diagnostic.severity === "warning";
+}
+
+/**
+ * A one-line note appended after edit/write on an LSP-supported file with a
+ * warm index already available -- mirrors pi-lsp-lite's real precedent of
+ * surfacing diagnostics inline with the edit result, so a caught type error
+ * doesn't wait for a separate diagnostics call to be noticed. Undefined
+ * when there is nothing noteworthy to say.
+ */
+export function buildPostEditDiagnosticsHint(diagnostics: readonly Diagnostic[]): string | undefined {
+	const noteworthy = diagnostics.filter(isNoteworthy);
+	if (noteworthy.length === 0) return undefined;
+	const errorCount = noteworthy.filter((d) => d.severity === "error").length;
+	const warningCount = noteworthy.length - errorCount;
+	const parts: string[] = [];
+	if (errorCount > 0) parts.push(`${errorCount} error${errorCount === 1 ? "" : "s"}`);
+	if (warningCount > 0) parts.push(`${warningCount} warning${warningCount === 1 ? "" : "s"}`);
+	return `Lector: ${parts.join(", ")} on this file (see the diagnostics tool for detail).`;
+}
+
+/** Below this, a read already shows the whole structure at a glance -- a hint would just be noise. */
+const MIN_SYMBOLS_FOR_HINT = 8;
+
+/**
+ * A one-line note appended after reading a large, LSP-supported file with a
+ * warm index already available -- nudges toward document_symbols/
+ * find_references/go_to_definition instead of re-reading the whole file for
+ * a targeted question next time.
+ */
+export function buildPostReadStructureHint(symbols: readonly DocumentSymbolEntry[]): string | undefined {
+	if (symbols.length < MIN_SYMBOLS_FOR_HINT) return undefined;
+	return `Lector: this file has ${symbols.length} top-level symbols -- document_symbols/find_references/go_to_definition can target one directly instead of rereading the whole file.`;
+}

package/extension/src/code-intelligence-operations.ts

@@ -0,0 +1,178 @@
+import type {
+	CallHierarchyEntry,
+	Diagnostic,
+	DocumentSymbolEntry,
+	Hover,
+	IncomingCall,
+	JobSnapshot,
+	OutgoingCall,
+	PopulateSymbolGraphResult,
+	SymbolEdgeKind,
+	SymbolNode,
+	WorkspaceLocation,
+} from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "./lector-client.ts";
+
+/**
+ * Thin wrappers over Lector's code-intelligence operations: goToDefinition,
+ * findReferences, hover, documentSymbols. Position-based (path + 1-indexed
+ * line + character), not symbol-name-based:
+ * an agent already has an exact position from a prior read or find_symbols
+ * call, so these compose directly off that rather than requiring a second,
+ * ambiguity-prone "which occurrence of this name" lookup.
+ *
+ * `path` resolves its own workspace per call (workspaceForCodeIntelligencePath,
+ * falling back to the file's own containing directory, never the filesystem
+ * root -- every one of these operations spawns a real language server,
+ * unlike read/write/edit) -- never a value captured once at session start.
+ */
+export interface CodeIntelligenceOperations {
+	goToDefinition(path: string, line: number, character: number): Promise<readonly WorkspaceLocation[]>;
+	goToImplementation(path: string, line: number, character: number): Promise<readonly WorkspaceLocation[]>;
+	findReferences(path: string, line: number, character: number, includeDeclaration: boolean): Promise<readonly WorkspaceLocation[]>;
+	hover(path: string, line: number, character: number): Promise<Hover | undefined>;
+	documentSymbols(path: string): Promise<readonly DocumentSymbolEntry[]>;
+	diagnostics(path: string): Promise<readonly Diagnostic[]>;
+	prepareCallHierarchy(path: string, line: number, character: number): Promise<readonly CallHierarchyEntry[]>;
+	incomingCalls(path: string, line: number, character: number): Promise<readonly IncomingCall[]>;
+	outgoingCalls(path: string, line: number, character: number): Promise<readonly OutgoingCall[]>;
+	populateSymbolGraph(path: string, maxFiles: number, maxSymbolsPerFile: number, waitMs?: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
+	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
+	reachableFrom(path: string, line: number, character: number, maxDepth: number, kind?: SymbolEdgeKind): Promise<readonly SymbolNode[]>;
+	/** Never spawns a symbol index -- safe to call opportunistically (e.g. before deciding whether to enrich a result). */
+	hasWarmIndex(path: string): Promise<boolean>;
+}
+
+export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperations {
+	return {
+		async goToDefinition(path, line, character) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { locations } = await client.call("workspace.goToDefinition", { workspaceId, path, line, character });
+					return locations;
+				},
+			);
+		},
+		async goToImplementation(path, line, character) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { locations } = await client.call("workspace.goToImplementation", { workspaceId, path, line, character });
+					return locations;
+				},
+			);
+		},
+		async findReferences(path, line, character, includeDeclaration) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { locations } = await client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
+					return locations;
+				},
+			);
+		},
+		async hover(path, line, character) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { hover } = await client.call("workspace.hover", { workspaceId, path, line, character });
+					return hover;
+				},
+			);
+		},
+		async documentSymbols(path) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { symbols } = await client.call("workspace.documentSymbols", { workspaceId, path });
+					return symbols;
+				},
+			);
+		},
+		async diagnostics(path) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { diagnostics } = await client.call("workspace.diagnostics", { workspaceId, path });
+					return diagnostics;
+				},
+			);
+		},
+		async prepareCallHierarchy(path, line, character) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { items } = await client.call("workspace.prepareCallHierarchy", { workspaceId, path, line, character });
+					return items;
+				},
+			);
+		},
+		async incomingCalls(path, line, character) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { calls } = await client.call("workspace.incomingCalls", { workspaceId, path, line, character });
+					return calls;
+				},
+			);
+		},
+		async outgoingCalls(path, line, character) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { calls } = await client.call("workspace.outgoingCalls", { workspaceId, path, line, character });
+					return calls;
+				},
+			);
+		},
+		async populateSymbolGraph(path, maxFiles, maxSymbolsPerFile, waitMs = 500) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { job } = await client.call("job.submit", {
+						operation: "workspace.populateSymbolGraph",
+						input: { workspaceId, maxFiles, maxSymbolsPerFile },
+						waitMs,
+					});
+					return job;
+				},
+			);
+		},
+		async jobStatus(jobId) {
+			const client = await lectorClient();
+			const { job } = await client.call("job.status", { jobId });
+			return job;
+		},
+		async reachableFrom(path, line, character, maxDepth, kind) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { symbols } = await client.call("workspace.reachableFrom", { workspaceId, path, line, character, maxDepth, kind });
+					return symbols;
+				},
+			);
+		},
+		async hasWarmIndex(path) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { warm } = await client.call("workspace.hasWarmIndex", { workspaceId });
+					return warm;
+				},
+			);
+		},
+	};
+}

package/extension/src/code-intelligence-rendering.ts

@@ -0,0 +1,237 @@
+import type {
+	CallHierarchyEntry,
+	Diagnostic,
+	DocumentSymbolEntry,
+	Hover,
+	IncomingCall,
+	JobSnapshot,
+	OutgoingCall,
+	PopulateSymbolGraphResult,
+	SymbolNode,
+	WorkspaceLocation,
+} from "@danypops/lector";
+import { keyHint, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import { colorForKind, formatLocation, type LectorTheme } from "./lector-tui-theme.ts";
+
+/**
+ * Custom TUI rendering for the code-intelligence tools: go_to_definition,
+ * find_references, hover, document_symbols. None of these have a built-in
+ * pi-coding-agent equivalent to inherit
+ * rendering from, exactly like find_symbols -- same theme.fg/theme.bold/
+ * keyHint approach, sharing find_symbols' own kind-coloring and location
+ * formatting via lector-tui-theme.ts rather than redefining it four times.
+ */
+
+const DEFAULT_VISIBLE_LOCATIONS = 8;
+const DEFAULT_VISIBLE_SYMBOLS = 12;
+const DEFAULT_VISIBLE_DIAGNOSTICS = 12;
+const DEFAULT_VISIBLE_CALLS = 12;
+
+const DIAGNOSTIC_SEVERITY_COLOR: Record<Diagnostic["severity"], ThemeColor> = {
+	error: "error",
+	warning: "warning",
+	information: "muted",
+	hint: "dim",
+};
+
+function formatPositionalCall(toolName: string, args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	const line = typeof args.line === "number" ? args.line : "?";
+	const character = typeof args.character === "number" ? args.character : "?";
+	return `${theme.fg("toolTitle", theme.bold(toolName))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
+}
+
+function formatLocationList(locations: readonly WorkspaceLocation[] | undefined, emptyMessage: string, expanded: boolean, theme: LectorTheme): string {
+	if (!locations || locations.length === 0) return theme.fg("dim", emptyMessage);
+
+	const displayCount = expanded ? locations.length : Math.min(locations.length, DEFAULT_VISIBLE_LOCATIONS);
+	const lines = [theme.fg("muted", `${locations.length} location${locations.length === 1 ? "" : "s"}:`)];
+	for (const location of locations.slice(0, displayCount)) {
+		lines.push(`  ${formatLocation(theme, location.path, location.line, location.character)}`);
+	}
+	const remaining = locations.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}
+
+export function formatGoToDefinitionCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return formatPositionalCall("go_to_definition", args, theme);
+}
+
+export function formatGoToDefinitionResult(locations: readonly WorkspaceLocation[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	return formatLocationList(locations, "No definition found.", expanded, theme);
+}
+
+export function formatGoToImplementationCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return formatPositionalCall("go_to_implementation", args, theme);
+}
+
+export function formatGoToImplementationResult(locations: readonly WorkspaceLocation[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	return formatLocationList(locations, "No implementation found.", expanded, theme);
+}
+
+export function formatFindReferencesCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return formatPositionalCall("find_references", args, theme);
+}
+
+export function formatFindReferencesResult(locations: readonly WorkspaceLocation[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	return formatLocationList(locations, "No references found.", expanded, theme);
+}
+
+export function formatHoverCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return formatPositionalCall("hover", args, theme);
+}
+
+const HOVER_COLLAPSED_LINE_COUNT = 6;
+
+export function formatHoverResult(hover: Hover | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!hover) return theme.fg("dim", "No hover information available.");
+	const lines = hover.contents.split("\n");
+	if (expanded || lines.length <= HOVER_COLLAPSED_LINE_COUNT) return hover.contents;
+	const remaining = lines.length - HOVER_COLLAPSED_LINE_COUNT;
+	return `${lines.slice(0, HOVER_COLLAPSED_LINE_COUNT).join("\n")}\n${theme.fg("dim", `... ${remaining} more line${remaining === 1 ? "" : "s"} (${keyHint("app.tools.expand", "to expand")})`)}`;
+}
+
+export function formatDocumentSymbolsCall(args: { path?: unknown }, theme: LectorTheme): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	return `${theme.fg("toolTitle", theme.bold("document_symbols"))} ${theme.fg("accent", path)}`;
+}
+
+/** Flattens a hierarchical DocumentSymbolEntry[] into (depth, entry) pairs, depth-first, for bounded rendering. */
+function flattenSymbols(entries: readonly DocumentSymbolEntry[], depth = 0): Array<{ depth: number; entry: DocumentSymbolEntry }> {
+	const flattened: Array<{ depth: number; entry: DocumentSymbolEntry }> = [];
+	for (const entry of entries) {
+		flattened.push({ depth, entry });
+		if (entry.children) flattened.push(...flattenSymbols(entry.children, depth + 1));
+	}
+	return flattened;
+}
+
+export function formatDocumentSymbolsResult(symbols: readonly DocumentSymbolEntry[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!symbols || symbols.length === 0) return theme.fg("dim", "No symbols found.");
+
+	const flattened = flattenSymbols(symbols);
+	const kindColumnWidth = Math.max(...flattened.map(({ entry }) => entry.kind.length));
+	const displayCount = expanded ? flattened.length : Math.min(flattened.length, DEFAULT_VISIBLE_SYMBOLS);
+	const lines = [theme.fg("muted", `${flattened.length} symbol${flattened.length === 1 ? "" : "s"}:`)];
+
+	for (const { depth, entry } of flattened.slice(0, displayCount)) {
+		const indent = "  ".repeat(depth + 1);
+		const kind = theme.fg(colorForKind(entry.kind), entry.kind.padEnd(kindColumnWidth));
+		const name = theme.fg("text", theme.bold(entry.name));
+		const location = formatLocation(theme, entry.range.path, entry.selectionRange.start.line, entry.selectionRange.start.character);
+		lines.push(`${indent}${kind}  ${name}  ${location}`);
+	}
+
+	const remaining = flattened.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}
+
+export function formatDiagnosticsCall(args: { path?: unknown }, theme: LectorTheme): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	return `${theme.fg("toolTitle", theme.bold("diagnostics"))} ${theme.fg("accent", path)}`;
+}
+
+export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!diagnostics || diagnostics.length === 0) return theme.fg("success", "No diagnostics.");
+
+	const displayCount = expanded ? diagnostics.length : Math.min(diagnostics.length, DEFAULT_VISIBLE_DIAGNOSTICS);
+	const lines = [theme.fg("muted", `${diagnostics.length} diagnostic${diagnostics.length === 1 ? "" : "s"}:`)];
+
+	for (const diagnostic of diagnostics.slice(0, displayCount)) {
+		const severity = theme.fg(DIAGNOSTIC_SEVERITY_COLOR[diagnostic.severity] ?? "muted", theme.bold(diagnostic.severity));
+		const location = formatLocation(theme, diagnostic.range.path, diagnostic.range.start.line, diagnostic.range.start.character);
+		const origin = diagnostic.source ? theme.fg("dim", ` (${diagnostic.source}${diagnostic.code !== undefined ? ` ${diagnostic.code}` : ""})`) : "";
+		lines.push(`  ${severity} ${location} -- ${diagnostic.message}${origin}`);
+	}
+
+	const remaining = diagnostics.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}
+
+function formatCallHierarchyEntry(entry: { kind: string; name: string; location: WorkspaceLocation }, theme: LectorTheme): string {
+	const kind = theme.fg(colorForKind(entry.kind), entry.kind);
+	const name = theme.fg("text", theme.bold(entry.name));
+	const location = formatLocation(theme, entry.location.path, entry.location.line, entry.location.character);
+	return `${kind} ${name} -- ${location}`;
+}
+
+export function formatPrepareCallHierarchyCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return formatPositionalCall("prepare_call_hierarchy", args, theme);
+}
+
+export function formatPrepareCallHierarchyResult(items: readonly CallHierarchyEntry[] | undefined, theme: LectorTheme): string {
+	if (!items || items.length === 0) return theme.fg("dim", "No call-hierarchy root at this position.");
+	return items.map((item) => formatCallHierarchyEntry(item, theme)).join("\n");
+}
+
+export function formatIncomingCallsCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return formatPositionalCall("incoming_calls", args, theme);
+}
+
+export function formatIncomingCallsResult(calls: readonly IncomingCall[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!calls || calls.length === 0) return theme.fg("dim", "No incoming calls found.");
+
+	const displayCount = expanded ? calls.length : Math.min(calls.length, DEFAULT_VISIBLE_CALLS);
+	const lines = [theme.fg("muted", `${calls.length} caller${calls.length === 1 ? "" : "s"}:`)];
+	for (const call of calls.slice(0, displayCount)) lines.push(`  ${formatCallHierarchyEntry(call.from, theme)}`);
+
+	const remaining = calls.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}
+
+export function formatOutgoingCallsCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return formatPositionalCall("outgoing_calls", args, theme);
+}
+
+export function formatOutgoingCallsResult(calls: readonly OutgoingCall[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!calls || calls.length === 0) return theme.fg("dim", "No outgoing calls found.");
+
+	const displayCount = expanded ? calls.length : Math.min(calls.length, DEFAULT_VISIBLE_CALLS);
+	const lines = [theme.fg("muted", `${calls.length} callee${calls.length === 1 ? "" : "s"}:`)];
+	for (const call of calls.slice(0, displayCount)) lines.push(`  ${formatCallHierarchyEntry(call.to, theme)}`);
+
+	const remaining = calls.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}
+
+export function formatPopulateSymbolGraphCall(args: { path?: unknown; maxFiles?: unknown; maxSymbolsPerFile?: unknown }, theme: LectorTheme): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	return `${theme.fg("toolTitle", theme.bold("populate_symbol_graph"))} ${theme.fg("accent", path)}`;
+}
+
+export function describePopulateSymbolGraphJob(job: JobSnapshot<PopulateSymbolGraphResult>): string {
+	if (job.status === "queued") return `Source workspace is registered; symbol graph is queued and still loading (job ${job.id}). Poll job_status.`;
+	if (job.status === "running") return `Source workspace is registered; symbol graph is still loading (job ${job.id}). Poll job_status.`;
+	if (job.status === "failed") return `Job ${job.id} failed [${job.error.code}] -- ${job.error.message}`;
+	const result = job.result;
+	return `Job ${job.id} cached ${result.filesProcessed} file${result.filesProcessed === 1 ? "" : "s"}, ${result.symbolsProcessed} symbol${result.symbolsProcessed === 1 ? "" : "s"}, ${result.nodesAdded} node${result.nodesAdded === 1 ? "" : "s"}, ${result.edgesAdded} edge${result.edgesAdded === 1 ? "" : "s"}`;
+}
+
+export function formatPopulateSymbolGraphResult(job: JobSnapshot<PopulateSymbolGraphResult> | undefined, theme: LectorTheme): string {
+	if (!job) return theme.fg("dim", "No job result.");
+	const color = job.status === "failed" ? "error" : job.status === "succeeded" ? "muted" : "warning";
+	return theme.fg(color, describePopulateSymbolGraphJob(job));
+}
+
+export function formatReachableFromCall(args: { path?: unknown; line?: unknown; character?: unknown; maxDepth?: unknown }, theme: LectorTheme): string {
+	const base = formatPositionalCall("reachable_from", args, theme);
+	const maxDepth = typeof args.maxDepth === "number" ? args.maxDepth : "?";
+	return `${base} ${theme.fg("dim", `(depth ${maxDepth})`)}`;
+}
+
+export function formatReachableFromResult(symbols: readonly SymbolNode[] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!symbols || symbols.length === 0) return theme.fg("dim", "Nothing reachable at this position (has the graph been populated for this workspace?).");
+
+	const displayCount = expanded ? symbols.length : Math.min(symbols.length, DEFAULT_VISIBLE_CALLS);
+	const lines = [theme.fg("muted", `${symbols.length} reachable symbol${symbols.length === 1 ? "" : "s"}:`)];
+	for (const symbol of symbols.slice(0, displayCount)) lines.push(`  ${formatCallHierarchyEntry(symbol, theme)}`);
+
+	const remaining = symbols.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	return lines.join("\n");
+}

package/extension/src/cross-workspace-search-operations.ts

@@ -0,0 +1,47 @@
+import type { TextSearchResult, WorkspaceQueryOutcome, WorkspaceSymbol } from "@danypops/lector";
+import { lectorClient, workspaceForDirectory } from "./lector-client.ts";
+
+/**
+ * Fans out across explicitly-named directories only -- never the daemon's own "every registered
+ * workspace" default. Lector's daemon is a shared, system-wide service: leaving workspaceIds
+ * unset would search every project any other concurrent Pi session has ever registered against
+ * it, not just this session's own (confirmed live, not assumed -- a real fetched jittor workspace
+ * from an unrelated session showed up in an early test of this exact feature). `directories` is
+ * required, same "no implicit fallback" convention as find_symbols/search_code.
+ */
+export interface CrossWorkspaceSearchOperations {
+	findSymbols(
+		query: string,
+		directories: readonly string[],
+		timeoutMs?: number,
+	): Promise<readonly WorkspaceQueryOutcome<{ symbols: readonly WorkspaceSymbol[] }>[]>;
+	searchText(
+		query: string,
+		directories: readonly string[],
+		maxMatches: number,
+		maxBytes: number,
+		timeoutMs?: number,
+	): Promise<readonly WorkspaceQueryOutcome<TextSearchResult>[]>;
+}
+
+async function resolveWorkspaceIds(directories: readonly string[]): Promise<readonly string[]> {
+	const resolved = await Promise.all(directories.map((directory) => workspaceForDirectory(directory)));
+	return resolved.map((r) => r.workspaceId);
+}
+
+export function createLectorCrossWorkspaceSearchOperations(): CrossWorkspaceSearchOperations {
+	return {
+		async findSymbols(query, directories, timeoutMs) {
+			const workspaceIds = await resolveWorkspaceIds(directories);
+			const client = await lectorClient();
+			const { results } = await client.call("search.symbols", { query, workspaceIds, timeoutMs });
+			return results;
+		},
+		async searchText(query, directories, maxMatches, maxBytes, timeoutMs) {
+			const workspaceIds = await resolveWorkspaceIds(directories);
+			const client = await lectorClient();
+			const { results } = await client.call("search.text", { query, maxMatches, maxBytes, workspaceIds, timeoutMs });
+			return results;
+		},
+	};
+}

package/extension/src/cross-workspace-search-rendering.ts

@@ -0,0 +1,66 @@
+import type { TextSearchResult, WorkspaceQueryOutcome, WorkspaceSymbol } from "@danypops/lector";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+const DEFAULT_VISIBLE_PER_WORKSPACE = 10;
+
+export function formatCrossWorkspaceCall(args: { directories?: unknown; query?: unknown }, theme: LectorTheme): string {
+	const directories = Array.isArray(args.directories) ? args.directories.filter((d): d is string => typeof d === "string") : [];
+	const query = typeof args.query === "string" ? args.query : "";
+	return `${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", `across ${directories.length} project(s)`)}`;
+}
+
+function formatOutcomeHeader(outcome: WorkspaceQueryOutcome<unknown>, theme: LectorTheme): string {
+	if (outcome.status === "ready") return theme.fg("accent", outcome.workspaceId);
+	if (outcome.status === "loading") return `${theme.fg("warning", outcome.workspaceId)} ${theme.fg("warning", `-- still loading: ${outcome.message}`)}`;
+	return `${theme.fg("error", outcome.workspaceId)} ${theme.fg("error", `-- ${outcome.message}`)}`;
+}
+
+export function formatFindSymbolsAcrossProjectsResult(
+	results: readonly WorkspaceQueryOutcome<{ symbols: readonly WorkspaceSymbol[] }>[] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!results || results.length === 0) return theme.fg("dim", "No projects to search.");
+	const lines: string[] = [];
+	for (const outcome of results) {
+		lines.push(formatOutcomeHeader(outcome, theme));
+		if (outcome.status !== "ready") continue;
+		if (outcome.result.symbols.length === 0) {
+			lines.push(theme.fg("dim", "  no symbols matched"));
+			continue;
+		}
+		const displayCount = expanded ? outcome.result.symbols.length : Math.min(DEFAULT_VISIBLE_PER_WORKSPACE, outcome.result.symbols.length);
+		for (const symbol of outcome.result.symbols.slice(0, displayCount)) {
+			lines.push(`  ${symbol.kind} ${symbol.name} -- ${symbol.location.path}:${symbol.location.line}:${symbol.location.character}`);
+		}
+		const remaining = outcome.result.symbols.length - displayCount;
+		if (remaining > 0) lines.push(theme.fg("dim", `  ... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	}
+	return lines.join("\n");
+}
+
+export function formatSearchTextAcrossProjectsResult(
+	results: readonly WorkspaceQueryOutcome<TextSearchResult>[] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!results || results.length === 0) return theme.fg("dim", "No projects to search.");
+	const lines: string[] = [];
+	for (const outcome of results) {
+		lines.push(formatOutcomeHeader(outcome, theme));
+		if (outcome.status !== "ready") continue;
+		if (outcome.result.matches.length === 0) {
+			lines.push(theme.fg("dim", "  no matches"));
+			continue;
+		}
+		const displayCount = expanded ? outcome.result.matches.length : Math.min(DEFAULT_VISIBLE_PER_WORKSPACE, outcome.result.matches.length);
+		for (const match of outcome.result.matches.slice(0, displayCount)) {
+			lines.push(`  ${match.path}:${match.lineNumber}: ${match.line.replace(/\n$/, "")}`);
+		}
+		const remaining = outcome.result.matches.length - displayCount;
+		if (remaining > 0) lines.push(theme.fg("dim", `  ... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+		if (outcome.result.truncated) lines.push(theme.fg("warning", "  (this workspace's search was itself truncated by maxMatches/maxBytes)"));
+	}
+	return lines.join("\n");
+}