@danypops/pi-lector 0.9.4 → 0.9.6

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

@@ -1,5 +1,5 @@
 import type { SymbolSearchResult, TextSearchResult, WorkspaceQueryOutcome } from "@danypops/lector";
-import { lectorClient, workspaceForDirectory } from "./lector-client.ts";
+import { lectorClient, workspaceForProjectDirectory } from "./lector-client.ts";
 
 /**
  * Fans out across explicitly-named directories only -- never the daemon's own "every registered
@@ -10,34 +10,79 @@ import { lectorClient, workspaceForDirectory } from "./lector-client.ts";
  * 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<SymbolSearchResult>[]>;
+	findSymbols(query: string, directories: readonly string[], timeoutMs?: number): Promise<readonly CrossWorkspaceOutcome<SymbolSearchResult>[]>;
 	searchText(
 		query: string,
 		directories: readonly string[],
 		maxMatches: number,
 		maxBytes: number,
 		timeoutMs?: number,
-	): Promise<readonly WorkspaceQueryOutcome<TextSearchResult>[]>;
+	): Promise<readonly CrossWorkspaceOutcome<TextSearchResult>[]>;
+}
+
+/**
+ * One caller-supplied directory's own outcome, labeled back by that literal directory (never
+ * just a workspaceId hash) so a caller can tell which of their own inputs a result belongs to.
+ * `collapsedWith` lists any OTHER requested directories that resolved to this same workspaceId --
+ * empty when this directory got its own distinct scope, as it should for a real monorepo
+ * subproject. A caller must be able to tell "two of my inputs turned out to be one workspace"
+ * apart from "these are genuinely two separate results" -- silently duplicating one payload
+ * under two different-looking entries is exactly the bug this exists to prevent.
+ */
+export interface CrossWorkspaceOutcome<T> {
+	readonly directory: string;
+	readonly workspaceId: string;
+	readonly collapsedWith: readonly string[];
+	readonly outcome: WorkspaceQueryOutcome<T>;
 }
 
 async function resolveWorkspaceIds(directories: readonly string[]): Promise<readonly string[]> {
-	const resolved = await Promise.all(directories.map((directory) => workspaceForDirectory(directory)));
+	const resolved = await Promise.all(directories.map((directory) => workspaceForProjectDirectory(directory)));
 	return resolved.map((r) => r.workspaceId);
 }
 
+/**
+ * Zips the daemon's own outcomes back onto the literal directories that produced them, and
+ * computes collapsedWith. The daemon's search.symbols/search.text handlers map workspaceIds to
+ * results 1:1, in order, with no deduplication of their own (confirmed by reading service.ts's
+ * crossFindSymbols/crossSearchText: `targets.map(...)` over the exact `workspaceIds` array
+ * given) -- so a length mismatch here means that contract broke, not a normal runtime condition
+ * to paper over with an unsafe cast.
+ */
+function zipOutcomes<T>(
+	directories: readonly string[],
+	workspaceIds: readonly string[],
+	outcomes: readonly WorkspaceQueryOutcome<T>[],
+): readonly CrossWorkspaceOutcome<T>[] {
+	if (outcomes.length !== directories.length) {
+		throw new Error(
+			`Lector's search fan-out returned ${outcomes.length} outcome(s) for ${directories.length} requested directories -- expected exactly one outcome per directory, in order`,
+		);
+	}
+	return directories.map((directory, index) => {
+		const workspaceId = workspaceIds[index];
+		const outcome = outcomes[index];
+		if (workspaceId === undefined || outcome === undefined) {
+			throw new Error(`Lector's search fan-out is missing a workspaceId/outcome for directory "${directory}"`);
+		}
+		const collapsedWith = directories.filter((_, otherIndex) => otherIndex !== index && workspaceIds[otherIndex] === workspaceId);
+		return { directory, workspaceId, collapsedWith, outcome };
+	});
+}
+
 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;
+			return zipOutcomes(directories, workspaceIds, 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;
+			return zipOutcomes(directories, workspaceIds, results);
 		},
 	};
 }

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

@@ -1,6 +1,7 @@
-import type { SymbolSearchResult, TextSearchResult, WorkspaceQueryOutcome } from "@danypops/lector";
+import type { SymbolSearchResult, TextSearchResult } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
+import type { CrossWorkspaceOutcome } from "./cross-workspace-search-operations.ts";
 import { describeFindSymbolSources } from "./find-symbols-rendering.ts";
 import type { LectorTheme } from "./lector-tui-theme.ts";
 
@@ -12,21 +13,31 @@ export function formatCrossWorkspaceCall(args: { directories?: unknown; 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}`)}`;
+function formatOutcomeHeader(entry: CrossWorkspaceOutcome<unknown>, theme: LectorTheme): string {
+	const { outcome } = entry;
+	const label = theme.fg("accent", entry.directory);
+	const lines: string[] = [];
+	if (outcome.status === "ready") lines.push(label);
+	else if (outcome.status === "loading") lines.push(`${label} ${theme.fg("warning", `-- still loading: ${outcome.message}`)}`);
+	else lines.push(`${label} ${theme.fg("error", `-- ${outcome.message}`)}`);
+	// Surfaced explicitly, never silently -- two distinct inputs resolving to one workspace means
+	// one of their own result payloads below is a real duplicate of the other's, not two independent answers.
+	if (entry.collapsedWith.length > 0) {
+		lines.push(theme.fg("warning", `  resolved to the same workspace as: ${entry.collapsedWith.join(", ")}`));
+	}
+	return lines.join("\n");
 }
 
 export function formatFindSymbolsAcrossProjectsResult(
-	results: readonly WorkspaceQueryOutcome<SymbolSearchResult>[] | undefined,
+	results: readonly CrossWorkspaceOutcome<SymbolSearchResult>[] | 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));
+	for (const entry of results) {
+		lines.push(formatOutcomeHeader(entry, theme));
+		const { outcome } = entry;
 		if (outcome.status !== "ready") continue;
 		lines.push(
 			theme.fg("muted", `  ${outcome.result.provenance.fidelity} via ${outcome.result.provenance.backend}${outcome.result.truncated ? " (truncated)" : ""}`),
@@ -50,14 +61,15 @@ export function formatFindSymbolsAcrossProjectsResult(
 }
 
 export function formatSearchTextAcrossProjectsResult(
-	results: readonly WorkspaceQueryOutcome<TextSearchResult>[] | undefined,
+	results: readonly CrossWorkspaceOutcome<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));
+	for (const entry of results) {
+		lines.push(formatOutcomeHeader(entry, theme));
+		const { outcome } = entry;
 		if (outcome.status !== "ready") continue;
 		if (outcome.result.matches.length === 0) {
 			lines.push(theme.fg("dim", "  no matches"));

package/extension/src/index.ts

@@ -9,6 +9,7 @@ import type {
 	GithubRepoSearchResult,
 	Hover,
 	IntelligenceProvenance,
+	JobSnapshot,
 	LineEdit,
 	LineEditOutcome,
 	MutationHistoryEntry,
@@ -16,15 +17,16 @@ import type {
 	OperationOutputs,
 	PackageEcosystem,
 	PackageSourceOperationResult,
+	PopulateSymbolGraphResult,
 	RepoFetchResult,
 	SourcegraphCodeCandidate,
 	SymbolAnnotation,
 	SymbolNode,
 	SymbolSearchResult,
 	TextSearchResult,
+	WorkspaceCacheStatus,
 	WorkspaceLocation,
 	WorkspaceMapResult,
-	WorkspaceQueryOutcome,
 } from "@danypops/lector";
 import { DEFAULT_EXTERNAL_SEARCH_MAX_RESULTS, PACKAGE_ECOSYSTEMS } from "@danypops/lector";
 import {
@@ -65,7 +67,7 @@ import {
 	formatWorkspaceMapCall,
 	formatWorkspaceMapResult,
 } from "./code-intelligence-rendering.ts";
-import { createLectorCrossWorkspaceSearchOperations } from "./cross-workspace-search-operations.ts";
+import { type CrossWorkspaceOutcome, createLectorCrossWorkspaceSearchOperations } from "./cross-workspace-search-operations.ts";
 import { formatCrossWorkspaceCall, formatFindSymbolsAcrossProjectsResult, formatSearchTextAcrossProjectsResult } from "./cross-workspace-search-rendering.ts";
 import { createLectorEditOperations } from "./edit-operations.ts";
 import { createExternalSearchOperations } from "./external-search-operations.ts";
@@ -125,6 +127,7 @@ import {
 	describeCacheState,
 	monitorWorkspaceCache,
 } from "./workspace-cache-operations.ts";
+import { formatJobSnapshotResult, formatWorkspaceCacheCall, formatWorkspaceCacheStatusResult } from "./workspace-cache-rendering.ts";
 import { createLectorWriteOperations } from "./write-operations.ts";
 
 function describeIntelligenceSource(provenance: IntelligenceProvenance): string {
@@ -650,7 +653,7 @@ export default function (pi: ExtensionAPI) {
 				"Move/rename a file and rewrite every static import/export specifier the workspace's own populated symbol graph knows references it -- atomically, rolled back entirely on any failure. Non-LSP: uses find_references + a real parse of import/export declarations, not a language server's own rename. Refuses outright (touches nothing) unless the workspace's symbol graph is fully populated and current for the given bounds -- a partial rename that silently misses a reference is worse than refusing (Sourcegraph's CodeScaleBench finding). Does not follow dynamic import(expr)/require(expr) or any plain string reference to the file -- always check the returned caveats.",
 			promptSnippet: "Move a file and update every import that references it",
 			promptGuidelines: [
-				"The workspace's symbol graph auto-populates in the background (default bounds: 500 files, 100 symbols/file) the first time this workspace is touched. If this refuses because the graph isn't populated at the requested maxFiles/maxSymbolsPerFile, run `lector workspace populate-symbol-graph <path> --max-files <n> --max-symbols-per-file <n>` via bash for a larger scan, then retry.",
+				"The workspace's symbol graph auto-populates in the background (default bounds: 500 files, 100 symbols/file) the first time this workspace is touched. If this refuses because the graph isn't populated at the requested maxFiles/maxSymbolsPerFile, use workspace_cache(action=populate, maxFiles, maxSymbolsPerFile) for a larger scan, then retry -- no need to shell out to the CLI.",
 				"Always read the returned caveats: this never rewrites a dynamic import(expr)/require(expr) or a plain string reference to the old path, even if one exists.",
 			],
 			parameters: Type.Object({
@@ -779,10 +782,11 @@ export default function (pi: ExtensionAPI) {
 			name: "symbol_annotations",
 			label: "Symbol Annotations",
 			description:
-				'Agent-authored narrative content anchored to one or more symbols in the workspace\'s persisted graph -- e.g. a "user story dataflow" note spanning every symbol touched end-to-end. Every anchor must resolve to a real, currently-known symbol (the workspace\'s symbol graph auto-populates in the background on first touch). get/list/tree live-check staleness against the current graph/workspace on every call and persist a correction before returning, so a returned status never disagrees with reality -- a stale annotation must be refreshed (re-authored and re-anchored) or scrubbed (soft-deleted, restorable) by an explicit decision; Lector never rewrites the narrative itself. contain/uncontain build a reusable, nestable structure on top of plain annotations: a container (e.g. a "data flow") can contain other annotations -- including per-symbol notes shared by more than one container (DRY reuse) or another container one level deeper (nested data flows) -- without duplicating their content. tree reads a whole bounded subtree in one call. Actions: create, get, list, refresh, scrub, restore, contain, uncontain, tree.',
+				'Agent-authored narrative content anchored to one or more symbols in the workspace\'s persisted graph -- e.g. a "user story dataflow" note spanning every symbol touched end-to-end. Every anchor must resolve to a real, currently-known symbol (the workspace\'s symbol graph auto-populates in the background on first touch, bounded to the first 500 files/100 symbols each -- use workspace_cache(action=populate) with larger bounds for a symbol outside that). get/list/tree live-check staleness against the current graph/workspace on every call and persist a correction before returning, so a returned status never disagrees with reality -- a stale annotation must be refreshed (re-authored and re-anchored) or scrubbed (soft-deleted, restorable) by an explicit decision; Lector never rewrites the narrative itself. contain/uncontain build a reusable, nestable structure on top of plain annotations: a container (e.g. a "data flow") can contain other annotations -- including per-symbol notes shared by more than one container (DRY reuse) or another container one level deeper (nested data flows) -- without duplicating their content. tree reads a whole bounded subtree in one call. Actions: create, get, list, refresh, scrub, restore, contain, uncontain, tree.',
 			promptSnippet: "Attach, read, or invalidate narrative annotations on the symbol graph",
 			promptGuidelines: [
 				"Resolve real anchor positions first (find_symbols/document_symbols/go_to_definition) -- an anchor position must match the workspace's own symbol graph's recorded position for that symbol, not just any occurrence of its name.",
+				"UnknownAnnotationAnchor on a real, existing symbol usually means the graph's default 500-file auto-scan never reached that file -- check workspace_cache(action=status) and populate with larger bounds before assuming the position itself is wrong.",
 				"A stale annotation's body may no longer describe the code accurately -- read it, decide whether to refresh (re-author) or scrub (remove), never trust it as-is.",
 				"Prefer reusing an existing per-symbol annotation as a shared child of several containers over re-authoring the same explanation in each -- that reuse is the reason contain/uncontain exist.",
 				"contain/uncontain are idempotent (containing an already-contained child, or uncontaining an already-absent relationship, is a no-op, not an error) and reject a cycle up front rather than accepting one.",
@@ -944,10 +948,11 @@ export default function (pi: ExtensionAPI) {
 			name: "reachable_from",
 			label: "Reachable From",
 			description:
-				"Every symbol reachable from an exact file position by following the workspace's persisted call graph up to maxDepth hops -- transitive callers/reachability that would otherwise require chaining many find_references/call_hierarchy calls by hand. The workspace's symbol graph auto-populates in the background the first time this workspace is touched; if it's still building, this returns an empty result rather than an error -- wait a moment and retry.",
+				"Every symbol reachable from an exact file position by following the workspace's persisted call graph up to maxDepth hops -- transitive callers/reachability that would otherwise require chaining many find_references/call_hierarchy calls by hand. The workspace's symbol graph auto-populates in the background the first time this workspace is touched, bounded to the first 500 files/100 symbols each; if the position you need falls outside that, this returns an empty result rather than an error -- use workspace_cache(action=populate) with larger bounds, not just a retry.",
 			promptSnippet: "Find symbols reachable from a position, up to N hops, via the persisted graph",
 			promptGuidelines: [
 				"Use reachable_from for multi-hop questions (does A eventually call C through B); use call_hierarchy (direction=incoming/outgoing) for a single direct hop live against the language server.",
+				"An empty result on a real, existing symbol usually means the graph's default 500-file auto-scan never reached that file, not that nothing is reachable -- check with workspace_cache(action=status) and populate with larger bounds if so.",
 			],
 			parameters: Type.Object({
 				...positionParameters,
@@ -992,11 +997,11 @@ export default function (pi: ExtensionAPI) {
 			name: "workspace_map",
 			label: "Workspace Map",
 			description:
-				"A ranked, budget-bounded summary of the workspace's most structurally central symbols (aider-repomap-shaped) -- signature-only, highest-ranked first by PageRank over the populated call/reference graph, not full file dumps. Use when orienting in an unfamiliar or large codebase instead of reading many files one by one. The workspace's symbol graph auto-populates in the background the first time this workspace is touched; if it's still building, this returns empty rather than an error -- wait a moment and retry.",
+				"A ranked, budget-bounded summary of the workspace's most structurally central symbols (aider-repomap-shaped) -- signature-only, highest-ranked first by PageRank over the populated call/reference graph, not full file dumps. Use when orienting in an unfamiliar or large codebase instead of reading many files one by one. The workspace's symbol graph auto-populates in the background the first time this workspace is touched, bounded to the first 500 files/100 symbols each; a workspace bigger than that needs workspace_cache(action=populate) with larger bounds for full coverage.",
 			promptSnippet: "Get a ranked, signature-only overview of the workspace's most central symbols",
 			promptGuidelines: [
 				"Prefer this over reading many files to get oriented in a large or unfamiliar codebase -- it surfaces the most-referenced symbols first, not an arbitrary file order.",
-				"A budget-truncated result means real symbols were left out, not that the workspace only has this many -- raise maxEntries/maxBytes for more.",
+				"A budget-truncated result means real symbols were left out, not that the workspace only has this many -- raise maxEntries/maxBytes for more. An empty result instead means the graph itself never covered this workspace -- check workspace_cache(action=status).",
 			],
 			parameters: Type.Object({
 				path: Type.String({ description: "Absolute or cwd-relative path used to resolve which workspace to map" }),
@@ -1039,6 +1044,80 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		interface WorkspaceCacheToolDetails {
+			readonly action: "status" | "populate" | "job_status";
+			readonly status?: WorkspaceCacheStatus;
+			readonly job?: JobSnapshot<PopulateSymbolGraphResult>;
+		}
+
+		pi.registerTool({
+			name: "workspace_cache",
+			label: "Workspace Cache",
+			description:
+				"Checks or drives population of the workspace's persisted symbol graph -- the store reachable_from, symbol_annotations (anchor resolution), reference_based_rename, and workspace_map all read from, separate from the live language-server index find_symbols/hover/go_to_definition use. action=status reports not-cached/caching/partial/cached for the given bounds, without starting any work. action=populate explicitly requests a scan (optionally larger than the default 500-file/100-symbol auto-scan every workspace gets on first touch) and waits up to waitMs for it to finish, returning a job snapshot either way. action=job_status polls a job returned by populate that didn't finish within its own wait.",
+			promptSnippet: "Check or force-populate the workspace's persisted symbol graph",
+			promptGuidelines: [
+				"Use action=populate with a larger maxFiles/maxSymbolsPerFile before relying on reachable_from/symbol_annotations/reference_based_rename against a workspace bigger than the default 500-file auto-scan -- their own errors (empty results, UnknownAnnotationAnchor, ReferenceBasedRenameRequiresFreshGraph) usually mean the graph never reached the files you need, not that population is simply still catching up.",
+				"action=populate returns immediately once its own waitMs elapses even if the job is still running -- check the returned job's status and poll with action=job_status (the same jobId) rather than assuming a non-succeeded result means failure.",
+			],
+			parameters: Type.Object({
+				action: Type.Union([Type.Literal("status"), Type.Literal("populate"), Type.Literal("job_status")]),
+				directory: Type.Optional(
+					Type.String({ description: "Required for action=status/populate -- absolute or cwd-relative path used to resolve the workspace" }),
+				),
+				maxFiles: Type.Optional(
+					Type.Number({ description: "action=status/populate only -- defaults to 500, the same bound the automatic first-touch scan uses" }),
+				),
+				maxSymbolsPerFile: Type.Optional(
+					Type.Number({ description: "action=status/populate only -- defaults to 100, the same bound the automatic first-touch scan uses" }),
+				),
+				waitMs: Type.Optional(
+					Type.Number({
+						description:
+							"action=populate only -- how long to wait for the job to finish before returning its current snapshot; defaults to 3000, capped by the daemon at 30000",
+					}),
+				),
+				jobId: Type.Optional(Type.String({ description: "Required for action=job_status -- a jobId returned by a prior action=populate call" })),
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<WorkspaceCacheToolDetails>> {
+				if (params.action === "job_status") {
+					if (!params.jobId) throw new Error("workspace_cache action=job_status requires jobId");
+					const job = await codeIntelligenceOperations.jobStatus(params.jobId);
+					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "job_status", job } };
+				}
+				if (!params.directory) throw new Error(`workspace_cache action=${params.action} requires directory`);
+				const directory = resolve(cwd, params.directory);
+				const maxFiles = params.maxFiles ?? 500;
+				const maxSymbolsPerFile = params.maxSymbolsPerFile ?? 100;
+				if (params.action === "status") {
+					const status = await cacheOperations.status(directory, maxFiles, maxSymbolsPerFile);
+					return { content: [{ type: "text", text: JSON.stringify(status) }], details: { action: "status", status } };
+				}
+				const job = await codeIntelligenceOperations.populateSymbolGraph(directory, maxFiles, maxSymbolsPerFile, params.waitMs ?? 3_000);
+				return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "populate", job } };
+			},
+			renderCall(args, theme, context) {
+				const action = args.action === "populate" || args.action === "job_status" ? args.action : "status";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatWorkspaceCacheCall(action, args, theme));
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Checking workspace cache..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "workspace_cache failed"), 0, 0);
+				}
+				const details = result.details as WorkspaceCacheToolDetails | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(details?.action === "status" ? formatWorkspaceCacheStatusResult(details.status, theme) : formatJobSnapshotResult(details?.job, theme));
+				return text;
+			},
+		});
+
 		const gitOperations = createLectorGitOperations();
 		pi.registerTool({
 			name: "git",
@@ -1645,7 +1724,7 @@ export default function (pi: ExtensionAPI) {
 			name: "find_symbols_across_projects",
 			label: "Find Symbols Across Projects",
 			description:
-				"Fans out a symbol-name search across several explicitly-named project directories at once (e.g. several fetched repos, or a handful of related local projects) and reports one outcome per project -- ready with real results, loading (a project's language server is still cold-starting; retry shortly), or error. Directories are required and explicit -- never every project this daemon happens to have registered, which can include unrelated projects from other concurrent sessions.",
+				"Fans out a symbol-name search across several explicitly-named project directories at once (e.g. several fetched repos, or a handful of related local projects) and reports one outcome per project -- ready with real results, loading (a project's language server is still cold-starting; retry shortly), or error. Directories are required and explicit -- never every project this daemon happens to have registered, which can include unrelated projects from other concurrent sessions. Each directory resolves to its OWN nearest project root (package.json/tsconfig.json/go.mod/Cargo.toml/...), not the outer repo's git root -- sibling packages under one monorepo stay distinct scopes rather than collapsing into one. A result's collapsedWith lists any other requested directories that genuinely did resolve to the same workspace; empty means it got its own.",
 			promptSnippet: "Search for a symbol name across several projects at once",
 			parameters: Type.Object({
 				directories: Type.Array(Type.String(), { description: "Project directories to search, each absolute or relative to the current working directory" }),
@@ -1671,7 +1750,7 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "find_symbols_across_projects failed"), 0, 0);
 				}
-				const details = result.details as { results?: readonly WorkspaceQueryOutcome<SymbolSearchResult>[] } | undefined;
+				const details = result.details as { results?: readonly CrossWorkspaceOutcome<SymbolSearchResult>[] } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(formatFindSymbolsAcrossProjectsResult(details?.results, expanded, theme));
 				return text;
@@ -1682,7 +1761,7 @@ export default function (pi: ExtensionAPI) {
 			name: "search_code_across_projects",
 			label: "Search Code Across Projects",
 			description:
-				"Fans out a ripgrep-backed text/regex search across several explicitly-named project directories at once and reports one outcome per project. Directories are required and explicit -- never every project this daemon happens to have registered, which can include unrelated projects from other concurrent sessions.",
+				"Fans out a ripgrep-backed text/regex search across several explicitly-named project directories at once and reports one outcome per project. Directories are required and explicit -- never every project this daemon happens to have registered, which can include unrelated projects from other concurrent sessions. Each directory resolves to its OWN nearest project root (package.json/tsconfig.json/go.mod/Cargo.toml/...), not the outer repo's git root -- sibling packages under one monorepo stay distinct scopes rather than collapsing into one. A result's collapsedWith lists any other requested directories that genuinely did resolve to the same workspace; empty means it got its own.",
 			promptSnippet: "Search for a pattern across several projects at once",
 			parameters: Type.Object({
 				directories: Type.Array(Type.String(), { description: "Project directories to search, each absolute or relative to the current working directory" }),
@@ -1710,7 +1789,7 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "search_code_across_projects failed"), 0, 0);
 				}
-				const details = result.details as { results?: readonly WorkspaceQueryOutcome<TextSearchResult>[] } | undefined;
+				const details = result.details as { results?: readonly CrossWorkspaceOutcome<TextSearchResult>[] } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(formatSearchTextAcrossProjectsResult(details?.results, expanded, theme));
 				return text;

package/extension/src/lector-client.ts

@@ -3,6 +3,7 @@ import { dirname, extname, parse } from "node:path";
 import {
 	connectLectorClient,
 	descriptorForExtension,
+	LANGUAGE_SERVER_DESCRIPTORS,
 	type LectorClient,
 	type OperationInputs,
 	type OperationName,
@@ -142,6 +143,30 @@ export function workspaceForCodeIntelligencePath(absolutePath: string): Promise<
 	return workspaceForRoot(root);
 }
 
+/** Every known language's own rootMarkers, deduplicated -- see workspaceForProjectDirectory. */
+const ALL_PROJECT_ROOT_MARKERS: readonly string[] = [...new Set(LANGUAGE_SERVER_DESCRIPTORS.flatMap((descriptor) => descriptor.rootMarkers))];
+
+/**
+ * Resolves a caller-supplied directory to its OWN nearest project root -- never the outer repo's
+ * git root -- so distinct sibling packages under one monorepo stay distinct workspaces. Unlike
+ * workspaceForDirectory (used by find_symbols/read/write, where one canonical workspaceId per
+ * repo is exactly the point), this is for a tool whose entire premise is comparing *different*
+ * scopes (find_symbols_across_projects, search_code_across_projects): collapsing two sibling
+ * packages into the same workspaceId there silently duplicates one package's own results under
+ * the other's name, with no error at all -- confirmed live against this monorepo
+ * (packages/lector and packages/pi-lector both resolved to the same workspaceId).
+ *
+ * Unlike workspaceForCodeIntelligencePath, there is no single file (and therefore no known
+ * extension) to pick one specific language's markers from -- a caller-supplied directory could
+ * be any language, so this checks the union of every known language's rootMarkers. Falls back to
+ * the nearest git root, then the directory itself, exactly as nearestProjectRoot already does
+ * internally (it appends ".git" to whatever marker list it's given).
+ */
+export function workspaceForProjectDirectory(directory: string): Promise<ResolvedWorkspace> {
+	const root = nearestProjectRoot(directory, ALL_PROJECT_ROOT_MARKERS) ?? directory;
+	return workspaceForRoot(root);
+}
+
 /**
  * For an operation whose `path` genuinely means "the project/workspace itself"
  * (populateSymbolGraph, workspaceMap, hasWarmIndex) rather than one specific file

package/extension/src/workspace-cache-rendering.ts

@@ -0,0 +1,45 @@
+import type { JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+type WorkspaceCacheAction = "status" | "populate" | "job_status";
+
+export function formatWorkspaceCacheCall(
+	action: WorkspaceCacheAction,
+	args: { directory?: unknown; maxFiles?: unknown; maxSymbolsPerFile?: unknown; jobId?: unknown },
+	theme: LectorTheme,
+): string {
+	const label = theme.fg("toolTitle", theme.bold("workspace_cache"));
+	if (action === "job_status") {
+		const jobId = typeof args.jobId === "string" ? args.jobId : "";
+		return `${label} ${theme.fg("accent", "job_status")} ${theme.fg("dim", jobId)}`;
+	}
+	const directory = typeof args.directory === "string" ? args.directory : "";
+	const maxFiles = typeof args.maxFiles === "number" ? String(args.maxFiles) : "default";
+	const maxSymbolsPerFile = typeof args.maxSymbolsPerFile === "number" ? String(args.maxSymbolsPerFile) : "default";
+	const bounds =
+		action === "populate" && (typeof args.maxFiles === "number" || typeof args.maxSymbolsPerFile === "number")
+			? theme.fg("dim", ` (maxFiles=${maxFiles}, maxSymbolsPerFile=${maxSymbolsPerFile})`)
+			: "";
+	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", directory)}${bounds}`;
+}
+
+function formatResultCounts(result: PopulateSymbolGraphResult): string {
+	const failed = result.filesFailed > 0 ? `, ${result.filesFailed} failed` : "";
+	return `${result.filesProcessed}/${result.filesAttempted} files${failed}, ${result.symbolsProcessed} symbols, ${result.nodesAdded} nodes, ${result.edgesAdded} edges`;
+}
+
+export function formatWorkspaceCacheStatusResult(status: WorkspaceCacheStatus | undefined, theme: LectorTheme): string {
+	if (!status) return theme.fg("dim", "No result.");
+	if (status.status === "not-cached") return theme.fg("warning", `not cached (${status.reason})`);
+	if (status.status === "caching") return theme.fg("accent", `caching (job ${status.jobId})`);
+	if (status.status === "partial") return theme.fg("warning", `partial -- ${formatResultCounts(status.generation.result)}`);
+	return theme.fg("success", `cached -- ${formatResultCounts(status.generation.result)}`);
+}
+
+export function formatJobSnapshotResult(job: JobSnapshot<PopulateSymbolGraphResult> | undefined, theme: LectorTheme): string {
+	if (!job) return theme.fg("dim", "No result.");
+	if (job.status === "queued") return theme.fg("dim", `queued (job ${job.id})`);
+	if (job.status === "running") return theme.fg("accent", `running (job ${job.id})`);
+	if (job.status === "failed") return theme.fg("error", `failed (job ${job.id}): ${job.error.code}: ${job.error.message}`);
+	return theme.fg("success", `succeeded (job ${job.id}) -- ${formatResultCounts(job.result)}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.9.4",
+	"version": "0.9.6",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",