@danypops/pi-lector 0.12.4 → 0.12.6

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

@@ -1,5 +1,5 @@
-import type { SymbolSearchResult, TextSearchResult, WorkspaceQueryOutcome } from "@danypops/lector";
-import { lectorClient, workspaceForProjectDirectory } from "../lector-client.ts";
+import { type SymbolSearchResult, type TextSearchResult, UnknownWorkspace, type WorkspaceQueryOutcome } from "@danypops/lector";
+import { forgetWorkspaceId, lectorClient, type ResolvedWorkspace, workspaceForProjectDirectory } from "../lector-client.ts";
 
 /**
  * Fans out across explicitly-named directories only -- never the daemon's own "every registered
@@ -10,7 +10,13 @@ import { lectorClient, workspaceForProjectDirectory } 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 CrossWorkspaceOutcome<SymbolSearchResult>[]>;
+	/** maxResults, when given, applies per project (see workspace.cacheStatus's own OperationInputs note on search.symbols) -- omitted falls back to the daemon's own conservative default, never an unbounded per-project search.symbols call fanned out across every requested directory at once. */
+	findSymbols(
+		query: string,
+		directories: readonly string[],
+		timeoutMs?: number,
+		maxResults?: number,
+	): Promise<readonly CrossWorkspaceOutcome<SymbolSearchResult>[]>;
 	searchText(
 		query: string,
 		directories: readonly string[],
@@ -36,18 +42,23 @@ export interface CrossWorkspaceOutcome<T> {
 	readonly outcome: WorkspaceQueryOutcome<T>;
 }
 
-async function resolveWorkspaceIds(directories: readonly string[]): Promise<readonly string[]> {
-	const resolved = await Promise.all(directories.map((directory) => workspaceForProjectDirectory(directory)));
-	return resolved.map((r) => r.workspaceId);
+function resolveWorkspaces(directories: readonly string[]): Promise<readonly ResolvedWorkspace[]> {
+	return Promise.all(directories.map((directory) => workspaceForProjectDirectory(directory)));
 }
 
 /**
  * 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.
+ * computes collapsedWith -- by workspaceId identity, never by array position. A real, reproduced
+ * live bug: the daemon's own response order can legitimately differ from the request's
+ * workspaceIds order (an immediate per-item error for an unregistered id is reported ahead of
+ * real results, for instance) -- a caller correlating positionally then hands one directory's
+ * result to a completely different directory. Every outcome already carries its own workspaceId;
+ * this groups outcomes by that id (preserving arrival order *within* one id's own group, since
+ * two directories can legitimately share one workspaceId -- a monorepo's unmarked siblings) and
+ * consumes exactly one outcome per requested (directory, workspaceId) pair in that group, in
+ * order. A missing, duplicated-beyond-what-was-asked, or wholly unrequested workspaceId in the
+ * response means the daemon's contract broke -- fails loud rather than silently mislabeling or
+ * dropping data.
  */
 function zipOutcomes<T>(
 	directories: readonly string[],
@@ -56,33 +67,86 @@ function zipOutcomes<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`,
+			`Lector's search fan-out returned ${outcomes.length} outcome(s) for ${directories.length} requested directories -- expected exactly one outcome per directory`,
 		);
 	}
-	return directories.map((directory, index) => {
+	const outcomesByWorkspaceId = new Map<string, WorkspaceQueryOutcome<T>[]>();
+	for (const outcome of outcomes) {
+		const bucket = outcomesByWorkspaceId.get(outcome.workspaceId);
+		if (bucket) bucket.push(outcome);
+		else outcomesByWorkspaceId.set(outcome.workspaceId, [outcome]);
+	}
+	const consumedByWorkspaceId = new Map<string, number>();
+	const results = 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}"`);
+		if (workspaceId === undefined) throw new Error(`Lector's search fan-out is missing a resolved workspaceId for directory "${directory}"`);
+		const consumed = consumedByWorkspaceId.get(workspaceId) ?? 0;
+		const outcome = outcomesByWorkspaceId.get(workspaceId)?.[consumed];
+		if (!outcome) {
+			throw new Error(
+				`Lector's search fan-out returned no outcome for workspace "${workspaceId}" (directory "${directory}") -- the daemon's response no longer corresponds to the request`,
+			);
 		}
+		consumedByWorkspaceId.set(workspaceId, consumed + 1);
 		const collapsedWith = directories.filter((_, otherIndex) => otherIndex !== index && workspaceIds[otherIndex] === workspaceId);
 		return { directory, workspaceId, collapsedWith, outcome };
 	});
+	const totalConsumed = [...consumedByWorkspaceId.values()].reduce((sum, count) => sum + count, 0);
+	if (totalConsumed !== outcomes.length) {
+		throw new Error(
+			"Lector's search fan-out returned an outcome for a workspace nobody asked for -- the daemon's response no longer corresponds to the request",
+		);
+	}
+	return results;
+}
+
+/** True exactly for the daemon's own "this workspaceId is not registered" outcome for this request's own workspaceId -- never a string-matched guess against an unrelated error. */
+function isUnknownWorkspaceOutcome<T>(outcome: WorkspaceQueryOutcome<T>, workspaceId: string): boolean {
+	return outcome.status === "error" && outcome.message === new UnknownWorkspace(workspaceId).message;
+}
+
+/**
+ * A daemon restart wipes its in-memory workspace registry, but this process's own workspaceId
+ * cache does not know that on its own -- a cross-workspace call through a stale cached id comes
+ * back with a real, correctly-correlated "no workspace registered" outcome for that one
+ * workspace, even though the underlying directory on disk never changed. On exactly that
+ * outcome, the stale cache entries are dropped and the whole fan-out (re-resolve every
+ * directory, then re-run) retries once -- the same bounded, idempotent recovery withWorkspace
+ * already gives single-workspace operations, extended to a batch. A genuine per-workspace error
+ * unrelated to registration (an unsupported language, a real internal failure) is never retried.
+ */
+async function withCrossWorkspaceRestartRecovery<T>(
+	directories: readonly string[],
+	perform: (resolved: readonly ResolvedWorkspace[]) => Promise<readonly CrossWorkspaceOutcome<T>[]>,
+): Promise<readonly CrossWorkspaceOutcome<T>[]> {
+	const resolved = await resolveWorkspaces(directories);
+	const outcomes = await perform(resolved);
+	const stale = outcomes.filter((entry) => isUnknownWorkspaceOutcome(entry.outcome, entry.workspaceId));
+	if (stale.length === 0) return outcomes;
+	for (const entry of stale) {
+		const match = resolved.find((candidate) => candidate.workspaceId === entry.workspaceId);
+		if (match) forgetWorkspaceId(match.root);
+	}
+	return perform(await resolveWorkspaces(directories));
 }
 
 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 zipOutcomes(directories, workspaceIds, results);
+		findSymbols(query, directories, timeoutMs, maxResults) {
+			return withCrossWorkspaceRestartRecovery(directories, async (resolved) => {
+				const workspaceIds = resolved.map((r) => r.workspaceId);
+				const client = await lectorClient();
+				const { results } = await client.call("search.symbols", { query, workspaceIds, timeoutMs, ...(maxResults !== undefined ? { maxResults } : {}) });
+				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 zipOutcomes(directories, workspaceIds, results);
+		searchText(query, directories, maxMatches, maxBytes, timeoutMs) {
+			return withCrossWorkspaceRestartRecovery(directories, async (resolved) => {
+				const workspaceIds = resolved.map((r) => r.workspaceId);
+				const client = await lectorClient();
+				const { results } = await client.call("search.text", { query, maxMatches, maxBytes, workspaceIds, timeoutMs });
+				return zipOutcomes(directories, workspaceIds, results);
+			});
 		},
 	};
 }

package/extension/src/index.ts

@@ -44,6 +44,7 @@ import { Type } from "typebox";
 /** Real ANSI-aware measurement for Table -- Malevich's own default is ASCII-only, unsafe against theme-styled cell/header text. */
 const tableMeasure: TextMeasure = { visibleWidth, truncateToWidth };
 
+import { isFilesystemRoot } from "@danypops/lector";
 import { createLectorApplyPatchOperations } from "./apply-patch/operations.ts";
 import { formatApplyPatchCall, formatApplyPatchResult } from "./apply-patch/rendering.ts";
 import { createLectorCodeIntelligenceOperations } from "./code-intelligence/operations.ts";
@@ -89,11 +90,10 @@ import { createLectorFindSymbolsOperations } from "./find-symbols/operations.ts"
 import { describeFindSymbolSources, formatFindSymbolsCall, formatFindSymbolsResult } from "./find-symbols/rendering.ts";
 import { createLectorGitOperations } from "./git/operations.ts";
 import { formatGitCall, formatGitResult, type GitToolDetails } from "./git/rendering.ts";
-import { setNewWorkspaceObserver } from "./lector-client.ts";
+import { nearestGitWorkspaceRoot, setNewWorkspaceObserver } from "./lector-client.ts";
 import { createLectorLineEditOperations } from "./line-edit/operations.ts";
 import { formatLineEditCall, formatLineEditResult } from "./line-edit/rendering.ts";
 import { createMutationHistoryOperations } from "./mutation-history/operations.ts";
-import { isFilesystemRoot, nearestGitRoot } from "./nearest-workspace-root.ts";
 import { createLectorPackageSourceOperations, type PackageSourceListPage } from "./package-source/operations.ts";
 import {
 	buildPackageSourceListTableRows,
@@ -279,9 +279,17 @@ export default function (pi: ExtensionAPI) {
 		lastInjectedSummary = undefined;
 		uiContext = ctx;
 		setNewWorkspaceObserver((root) => startMonitoringRoot(root, ctx));
-		const projectRoot = nearestGitRoot(cwd);
-		if (projectRoot) startMonitoringRoot(projectRoot, ctx);
-		else ctx.ui.setStatus("lector-cache", undefined);
+		const thisGeneration = sessionGeneration;
+		void nearestGitWorkspaceRoot(cwd)
+			.then((projectRoot) => {
+				if (sessionGeneration !== thisGeneration) return;
+				if (projectRoot) startMonitoringRoot(projectRoot, ctx);
+				else ctx.ui.setStatus("lector-cache", undefined);
+			})
+			.catch(() => {
+				// A daemon that isn't running yet is not a session_start failure -- the first real
+				// tool call surfaces that clearly instead.
+			});
 
 		pi.registerTool(createReadToolDefinition(cwd, { operations: createLectorReadOperations() }));
 		pi.registerTool(createWriteToolDefinition(cwd, { operations: createLectorWriteOperations() }));
@@ -1155,14 +1163,20 @@ export default function (pi: ExtensionAPI) {
 					if (!Number.isSafeInteger(waitMs) || waitMs < 1 || waitMs > 300_000)
 						throw new Error("workspace_cache action=wait waitMs must be an integer from 1 to 300000");
 					const pollIntervalMs = 5_000;
-					const completed = await waitForJobCompletion(cacheOperations, params.jobId, {
+					const outcome = await waitForJobCompletion(cacheOperations, params.jobId, {
 						pollIntervalMs,
 						maxPolls: Math.ceil(waitMs / pollIntervalMs),
 						shouldContinue: () => !signal?.aborted,
 						signal,
 					});
 					if (signal?.aborted) throw new DOMException("workspace cache wait canceled", "AbortError");
-					const job = completed ?? (await cacheOperations.jobStatus(params.jobId));
+					if (outcome.kind === "transport-failed") throw outcome.error instanceof Error ? outcome.error : new Error(String(outcome.error));
+					if (outcome.kind === "job-not-found") {
+						throw new Error(
+							`workspace cache job "${params.jobId}" is no longer known -- it expired, was evicted, or belonged to a previous daemon process; check workspace_cache action=status instead`,
+						);
+					}
+					const job = outcome.kind === "terminal" ? outcome.job : await cacheOperations.jobStatus(params.jobId);
 					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "wait", job } };
 				}
 				if (!params.directory) throw new Error(`workspace_cache action=${params.action} requires directory`);
@@ -1810,10 +1824,13 @@ export default function (pi: ExtensionAPI) {
 				directories: Type.Array(Type.String(), { description: "Project directories to search, each absolute or relative to the current working directory" }),
 				query: Type.String({ description: "Symbol name (or substring) to search for" }),
 				timeoutMs: Type.Optional(Type.Number({ description: "How long to wait per project before reporting it as still-loading; defaults to 3000" })),
+				maxResults: Type.Optional(
+					Type.Number({ description: "Maximum matches to return per project (not total across every project); defaults to a conservative per-project bound" }),
+				),
 			}),
 			async execute(_toolCallId, params) {
 				const directories = params.directories.map((directory) => resolve(cwd, directory));
-				const results = await crossWorkspaceSearchOperations.findSymbols(params.query, directories, params.timeoutMs);
+				const results = await crossWorkspaceSearchOperations.findSymbols(params.query, directories, params.timeoutMs, params.maxResults);
 				return { content: [{ type: "text", text: JSON.stringify(results) }], details: { results } };
 			},
 			renderCall(args, theme, context) {

package/extension/src/lector-client.ts

@@ -1,9 +1,6 @@
-import { existsSync, statSync } from "node:fs";
-import { dirname, extname, parse } from "node:path";
+import { dirname, extname } from "node:path";
 import {
 	connectLectorClient,
-	descriptorForExtension,
-	LANGUAGE_SERVER_DESCRIPTORS,
 	type LectorClient,
 	LectorDaemonUnavailable,
 	type OperationInputs,
@@ -11,25 +8,31 @@ import {
 	type OperationOutputs,
 	remoteErrorIs,
 	type WorkspaceId,
+	type WorkspaceResolutionRequest,
 } from "@danypops/lector";
 import { createRetryingClient, isLikelyStaleConnectionError, type RetryingClient } from "@danypops/vehicle-client/daemon-client";
-import { nearestGitRoot, nearestProjectRoot } from "./nearest-workspace-root.ts";
 
 /**
- * Lazily connects to a running Lector daemon and caches, per project root,
- * the workspaceId that root registers under. Never auto-spawns the daemon:
- * a clear "start it with `lector serve`" error is preferable to guessing
- * at a lifecycle the user didn't ask for. A failed connection attempt is
- * not cached, so the very next tool call retries once the daemon is
- * actually running.
+ * Lazily connects to a running Lector daemon and caches, per resolution request, the
+ * workspace it resolves to. Never auto-spawns the daemon: a clear "start it with `lector serve`"
+ * error is preferable to guessing at a lifecycle the user didn't ask for. A failed connection
+ * attempt is not cached, so the very next tool call retries once the daemon is actually running.
  *
- * The daemon binds a new random port on every restart. A client resolved
- * once and cached for the rest of the session would otherwise point at a
- * dead port after any later restart -- daemon-kit's createRetryingClient
- * detects that on the failing call itself (not just the first connection
- * attempt) and retries once against a freshly re-resolved client, the same
- * policy this file used to hand-roll and now shares with web-spider's
- * callWebSpider(), papyrus's callService(), and pi-packed's createNatives().
+ * The daemon binds a new random port on every restart. A client resolved once and cached for
+ * the rest of the session would otherwise point at a dead port after any later restart --
+ * daemon-kit's createRetryingClient detects that on the failing call itself (not just the first
+ * connection attempt) and retries once against a freshly re-resolved client, the same policy
+ * this file used to hand-roll and now shares with web-spider's callWebSpider(), papyrus's
+ * callService(), and pi-packed's createNatives().
+ *
+ * Workspace-root resolution itself (which file belongs to which project) is Lector's own
+ * server-side concern -- see @danypops/lector's workspace.resolvePath and its own
+ * resolveWorkspacePath. This module used to reimplement that same filesystem walk-up locally
+ * (nearestGitRoot/nearestProjectRoot/nearestDeclaredWorkspaceRoot); two real, previously-shipped
+ * bugs (a project's own root directory silently resolving to its parent, and two sibling
+ * monorepo packages in this very repo collapsing onto the same workspaceId) traced directly to
+ * that logic living in the wrong process. Every workspaceForXxx below is now a thin RPC wrapper
+ * over workspace.resolvePath.
  */
 
 type ClientConnector = () => Promise<LectorClient>;
@@ -42,14 +45,15 @@ const retryingClient: RetryingClient<LectorClient> = createRetryingClient(() =>
 	label: "Lector",
 	isStaleConnectionError: (error) => error instanceof LectorDaemonUnavailable || isLikelyStaleConnectionError(error),
 });
-const workspaceIdByRoot = new Map<string, WorkspaceId>();
 
 /**
- * Fires exactly once per distinct root, the moment it's first registered in this process --
- * never on a later call that reuses the cached workspaceId. The single choke point every
+ * Fires exactly once per distinct root, the moment the daemon itself first registers it --
+ * never on a later call that resolves an already-registered root. The single choke point every
  * resolver (workspaceForPath, workspaceForDirectory, workspaceForCodeIntelligencePath,
  * workspaceForPathOrDirectory) funnels through, so this is genuinely "the first time any tool
- * call resolves this workspace," not just the one cwd workspace at session start.
+ * call resolves this workspace," not just the one cwd workspace at session start. Driven by
+ * workspace.resolvePath's own authoritative `created` flag, not a local cache -- correct even
+ * when a different process registered the same root moments earlier.
  */
 let onNewWorkspace: ((root: string) => void) | undefined;
 
@@ -80,18 +84,41 @@ export async function lectorClient(): Promise<RetryingLectorClient> {
 
 export interface ResolvedWorkspace {
 	workspaceId: WorkspaceId;
-	/** The registered root the target path is relative to -- a git root or the filesystem root, never a fixed session cwd. */
+	/** The root workspace.resolvePath actually registered -- a git root, a language project root, or the filesystem root, never a fixed session cwd. */
 	root: string;
 }
 
-async function workspaceForRoot(root: string): Promise<ResolvedWorkspace> {
-	const cached = workspaceIdByRoot.get(root);
-	if (cached) return { workspaceId: cached, root };
+/**
+ * Caches by the exact resolution request, not by the discovered root (this process no longer
+ * discovers roots itself) -- a repeated call with the identical path+strategy avoids a network
+ * round trip; two different files under the same repo each pay one round trip the first time,
+ * same as workspace.registerPath's own idempotent registration would cost anyway. A daemon
+ * restart wipes its in-memory registry; withWorkspace's own UnknownWorkspace retry (unchanged
+ * below) evicts exactly the stale entry this cache produced, the same recovery it always gave.
+ */
+const resolutionCache = new Map<string, ResolvedWorkspace>();
+
+function requestCacheKey(request: WorkspaceResolutionRequest): string {
+	return JSON.stringify(request, Object.keys(request).sort());
+}
+
+async function resolveWorkspace(request: WorkspaceResolutionRequest): Promise<ResolvedWorkspace> {
+	const key = requestCacheKey(request);
+	const cached = resolutionCache.get(key);
+	if (cached) return cached;
 	const client = await lectorClient();
-	const { workspaceId } = await client.callOnce("workspace.registerPath", { path: root });
-	workspaceIdByRoot.set(root, workspaceId);
-	onNewWorkspace?.(root);
-	return { workspaceId, root };
+	const outcome = await client.callOnce("workspace.resolvePath", request);
+	if (!outcome.found) {
+		// Every strategy this function is used for (git-root/language-project-root with an
+		// explicit fallback, path-or-directory) always resolves to something server-side --
+		// declared-monorepo-root (the one strategy that can legitimately report not found) is
+		// never routed through this function, see resolveDeclaredMonorepoRoot below.
+		throw new Error(`workspace.resolvePath unexpectedly reported not-found for a fallback-guaranteed strategy: ${key}`);
+	}
+	const resolved: ResolvedWorkspace = { workspaceId: outcome.workspaceId, root: outcome.root };
+	resolutionCache.set(key, resolved);
+	if (outcome.created) onNewWorkspace?.(outcome.root);
+	return resolved;
 }
 
 /**
@@ -99,9 +126,8 @@ async function workspaceForRoot(root: string): Promise<ResolvedWorkspace> {
  * contains this absolute FILE path -- never a session's original cwd.
  * Files under the same repo share one cached workspace+id; a path under a
  * different repo (or outside any repo entirely) gets its own, registered
- * on demand via workspace.registerPath. This is what makes read/write/edit
- * work for *any* absolute path in one session, exactly like Pi's built-in
- * tools always have -- not just paths under wherever the session started.
+ * on demand. This is what makes read/write/edit work for *any* absolute
+ * path in one session, exactly like Pi's built-in tools always have.
  *
  * Falls back to the filesystem root when no enclosing git repo exists:
  * unlike workspaceForDirectory, any absolute path is fair game here (a
@@ -110,9 +136,7 @@ async function workspaceForRoot(root: string): Promise<ResolvedWorkspace> {
  * built-in read/write/edit already allow.
  */
 export function workspaceForPath(absolutePath: string): Promise<ResolvedWorkspace> {
-	const directory = dirname(absolutePath);
-	const root = nearestGitRoot(directory) ?? parse(directory).root;
-	return workspaceForRoot(root);
+	return resolveWorkspace({ strategy: "git-root", path: dirname(absolutePath), fallback: "filesystem-root" });
 }
 
 /**
@@ -124,8 +148,19 @@ export function workspaceForPath(absolutePath: string): Promise<ResolvedWorkspac
  * outside the project) and unbounded (scanning the whole disk).
  */
 export function workspaceForDirectory(directory: string): Promise<ResolvedWorkspace> {
-	const root = nearestGitRoot(directory) ?? directory;
-	return workspaceForRoot(root);
+	return resolveWorkspace({ strategy: "git-root", path: directory, fallback: "given-directory" });
+}
+
+/**
+ * Honest "does a real git repo exist here at all" -- unlike workspaceForDirectory, no fallback
+ * masks a non-project directory as its own root. Used by session_start to decide whether cwd
+ * looks like a real project worth auto-populating a cache for, never a bare scratch/home
+ * directory.
+ */
+export async function nearestGitWorkspaceRoot(directory: string): Promise<string | undefined> {
+	const client = await lectorClient();
+	const outcome = await client.call("workspace.resolvePath", { strategy: "git-root", path: directory });
+	return outcome.found ? outcome.root : undefined;
 }
 
 /**
@@ -141,15 +176,14 @@ export function workspaceForDirectory(directory: string): Promise<ResolvedWorksp
  * gets that subproject's rootUri instead of the whole repo's.
  */
 export function workspaceForCodeIntelligencePath(absolutePath: string): Promise<ResolvedWorkspace> {
-	const directory = dirname(absolutePath);
-	const descriptor = descriptorForExtension(extname(absolutePath));
-	const root = descriptor ? (nearestProjectRoot(directory, descriptor.rootMarkers) ?? directory) : (nearestGitRoot(directory) ?? directory);
-	return workspaceForRoot(root);
+	return resolveWorkspace({
+		strategy: "language-project-root",
+		path: dirname(absolutePath),
+		fallback: "given-directory",
+		extension: extname(absolutePath),
+	});
 }
 
-/** 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
@@ -162,13 +196,11 @@ const ALL_PROJECT_ROOT_MARKERS: readonly string[] = [...new Set(LANGUAGE_SERVER_
  *
  * 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).
+ * be any language, so the daemon checks the union of every known language's rootMarkers when no
+ * extension is given.
  */
 export function workspaceForProjectDirectory(directory: string): Promise<ResolvedWorkspace> {
-	const root = nearestProjectRoot(directory, ALL_PROJECT_ROOT_MARKERS) ?? directory;
-	return workspaceForRoot(root);
+	return resolveWorkspace({ strategy: "language-project-root", path: directory, fallback: "given-directory" });
 }
 
 /**
@@ -180,19 +212,35 @@ export function workspaceForProjectDirectory(directory: string): Promise<Resolve
  * dirname() strips its final segment, silently resolving to the *parent*
  * directory's own nearest git root instead -- for a project nested one level
  * under a broader already-registered workspace, this mixes in every sibling
- * project's own graph, with no error at all. Checks whether the path is
- * itself a real, existing directory first; only takes dirname() when it is
- * not (a file, or a not-yet-existing path).
+ * project's own graph, with no error at all. The daemon checks whether the
+ * path is itself a real, existing directory first; only takes dirname() when
+ * it is not (a file, or a not-yet-existing path).
  */
 export function workspaceForPathOrDirectory(path: string): Promise<ResolvedWorkspace> {
-	const isRealDirectory = existsSync(path) && statSync(path).isDirectory();
-	return workspaceForDirectory(isRealDirectory ? path : dirname(path));
+	return resolveWorkspace({ strategy: "path-or-directory", path });
+}
+
+/**
+ * The nearest ancestor of an already-resolved project root whose own package.json declares that
+ * project as a workspace member via npm/yarn/bun's "workspaces" field -- undefined (no
+ * directory-itself/filesystem-root fallback) when no such ancestor exists, a real and expected
+ * outcome for a plain single-package repo. Used only by reference-based-rename's own
+ * widen-and-retry: on ReferenceBasedRenameRequiresFreshGraph, retry once against the declared
+ * monorepo root instead of the narrower project the rename was first attempted against.
+ * Deliberately uncached (a rare retry path, not a hot loop).
+ */
+export async function workspaceForDeclaredMonorepoRoot(projectRoot: string): Promise<ResolvedWorkspace | undefined> {
+	const client = await lectorClient();
+	const outcome = await client.callOnce("workspace.resolvePath", { strategy: "declared-monorepo-root", path: projectRoot });
+	if (!outcome.found) return undefined;
+	if (outcome.created) onNewWorkspace?.(outcome.root);
+	return { workspaceId: outcome.workspaceId, root: outcome.root };
 }
 
 /**
  * Resolves a workspace via `resolve`, then calls `perform` with it. A daemon
  * restart wipes its in-memory workspace registry (workspace ids are not
- * persisted across restarts by design), but this module's own workspaceId
+ * persisted across restarts by design), but this module's own resolution
  * cache does not know that on its own -- a call through a stale cached id
  * fails with UnknownWorkspace even though the underlying files on disk
  * never changed. On exactly that failure, the stale cache entry is dropped
@@ -208,20 +256,34 @@ export async function withWorkspace<T>(resolve: () => Promise<ResolvedWorkspace>
 			return await perform(resolved);
 		} catch (error) {
 			if (attempt === 1 || !remoteErrorIs(error, "UnknownWorkspace")) throw error;
-			workspaceIdByRoot.delete(resolved.root);
+			forgetWorkspaceId(resolved.root);
 		}
 	}
 	throw new Error("Lector workspace resolution retry exhausted");
 }
 
+/**
+ * Drops every cache entry resolved to this root without retrying anything itself -- the batch
+ * sibling of withWorkspace's own single-workspace recovery, for a caller (cross-workspace
+ * search's fan-out) that resolves many roots at once and needs to evict only the specific ones a
+ * daemon restart actually invalidated, not the whole cache. A root can appear under more than one
+ * cache key (workspaceForPath and workspaceForDirectory can each independently resolve to the
+ * same root for related paths), so this scans by value, not a single key lookup.
+ */
+export function forgetWorkspaceId(root: string): void {
+	for (const [key, resolved] of resolutionCache) {
+		if (resolved.root === root) resolutionCache.delete(key);
+	}
+}
+
 export function setLectorClientConnectorForTests(value: ClientConnector): void {
 	retryingClient.reset();
-	workspaceIdByRoot.clear();
+	resolutionCache.clear();
 	connector = value;
 }
 
 export function resetLectorClientForTests(): void {
 	retryingClient.reset();
-	workspaceIdByRoot.clear();
+	resolutionCache.clear();
 	connector = () => connectLectorClient();
 }

package/extension/src/reference-based-rename/operations.ts

@@ -1,6 +1,5 @@
 import { type OperationOutputs, remoteErrorIs } from "@danypops/lector";
-import { lectorClient, type ResolvedWorkspace, withWorkspace, workspaceForCodeIntelligencePath, workspaceForProjectDirectory } from "../lector-client.ts";
-import { nearestDeclaredWorkspaceRoot } from "../nearest-workspace-root.ts";
+import { lectorClient, type ResolvedWorkspace, withWorkspace, workspaceForCodeIntelligencePath, workspaceForDeclaredMonorepoRoot } from "../lector-client.ts";
 
 /**
  * Thin wrapper over Lector's non-LSP reference-based rename: moves a file and rewrites every
@@ -31,10 +30,10 @@ export function createReferenceBasedRenameOperations(): ReferenceBasedRenameOper
 				return await withWorkspace(() => workspaceForCodeIntelligencePath(fromPath), performRename);
 			} catch (error) {
 				if (!remoteErrorIs(error, "ReferenceBasedRenameRequiresFreshGraph")) throw error;
-				const { root: narrowRoot } = await workspaceForCodeIntelligencePath(fromPath);
-				const declaredRoot = nearestDeclaredWorkspaceRoot(narrowRoot);
-				if (!declaredRoot) throw error;
-				return withWorkspace(() => workspaceForProjectDirectory(declaredRoot), performRename);
+				const narrow = await workspaceForCodeIntelligencePath(fromPath);
+				const declared = await workspaceForDeclaredMonorepoRoot(narrow.root);
+				if (!declared) throw error;
+				return withWorkspace(() => Promise.resolve(declared), performRename);
 			}
 		},
 	};

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

@@ -1,4 +1,11 @@
-import { type JobSnapshot, type PopulateSymbolGraphResult, resolveLectorDaemonConnection, type WorkspaceCacheStatus } from "@danypops/lector";
+import {
+	type CacheResultCounts,
+	type JobSnapshot,
+	type PopulateSymbolGraphResult,
+	remoteErrorIs,
+	resolveLectorDaemonConnection,
+	type WorkspaceCacheStatus,
+} from "@danypops/lector";
 import { connectPushChannel } from "@danypops/vehicle-client/daemon-client";
 import { lectorClient, withWorkspace, workspaceForProjectDirectory } from "../lector-client.ts";
 
@@ -79,7 +86,7 @@ export type CachePresentationState =
 	| { readonly status: "not-cached"; readonly reason: string }
 	| { readonly status: "caching"; readonly jobId: string }
 	| { readonly status: "finished-caching"; readonly job: JobSnapshot<PopulateSymbolGraphResult> & { readonly status: "succeeded" } }
-	| { readonly status: "partial"; readonly result: PopulateSymbolGraphResult }
+	| { readonly status: "partial"; readonly result: CacheResultCounts }
 	| { readonly status: "cached" };
 
 export function describeCacheState(state: CachePresentationState): string {
@@ -117,12 +124,27 @@ export interface WaitForJobCompletionOptions {
 	readonly sleep?: (ms: number) => Promise<void>;
 }
 
+/**
+ * Exhaustive outcome of waiting on one job -- every path monitorWorkspaceCache must reconcile
+ * against authoritative workspace.cacheStatus, distinct from a genuine terminal result:
+ * "job-not-found" (the id expired, was evicted, or survives from a since-restarted daemon),
+ * "timed-out" (the bounded poll budget was spent and the job is still non-terminal), and
+ * "transport-failed" (the daemon couldn't be reached at all) all mean "we no longer know this
+ * job's real state" -- never treated as if the job were still "caching" forever.
+ */
+export type JobCompletionOutcome =
+	| { readonly kind: "terminal"; readonly job: JobSnapshot<PopulateSymbolGraphResult> & { readonly status: "succeeded" | "failed" } }
+	| { readonly kind: "timed-out" }
+	| { readonly kind: "canceled" }
+	| { readonly kind: "job-not-found" }
+	| { readonly kind: "transport-failed"; readonly error: unknown };
+
 /** Waits on Vehicle push delivery and checks status on a bounded cadence when push is unavailable or disconnected. */
 export async function waitForJobCompletion(
 	operations: WorkspaceCacheOperations,
 	jobId: string,
 	options: WaitForJobCompletionOptions,
-): Promise<JobSnapshot<PopulateSymbolGraphResult> | undefined> {
+): Promise<JobCompletionOutcome> {
 	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
 	let pushedResolve: ((job: JobSnapshot<PopulateSymbolGraphResult>) => void) | undefined;
 	const pushed = new Promise<JobSnapshot<PopulateSymbolGraphResult>>((resolve) => {
@@ -135,17 +157,29 @@ export async function waitForJobCompletion(
 	});
 	const onAbort = () => resolveAbort();
 	options.signal?.addEventListener("abort", onAbort, { once: true });
+
+	async function checkStatus(): Promise<JobCompletionOutcome | undefined> {
+		try {
+			const current = await operations.jobStatus(jobId);
+			if (current.status === "succeeded" || current.status === "failed") return { kind: "terminal", job: current };
+			return undefined;
+		} catch (error) {
+			if (remoteErrorIs(error, "JobNotFound")) return { kind: "job-not-found" };
+			return { kind: "transport-failed", error };
+		}
+	}
+
 	try {
-		const outcome = await operations.watchJob?.(jobId, (job) => pushedResolve?.(job));
-		if (outcome?.status === "subscribed") watch = outcome.handle;
+		const subscription = await operations.watchJob?.(jobId, (job) => pushedResolve?.(job));
+		if (subscription?.status === "subscribed") watch = subscription.handle;
 		for (let poll = 0; poll < options.maxPolls && options.shouldContinue() && !options.signal?.aborted; poll++) {
-			const current = await operations.jobStatus(jobId);
-			if (current.status === "succeeded" || current.status === "failed") return current;
+			const checked = await checkStatus();
+			if (checked) return checked;
 			const next = await Promise.race([pushed, sleep(options.pollIntervalMs).then(() => undefined), aborted.then(() => undefined)]);
-			if (next?.status === "succeeded" || next?.status === "failed") return next;
+			if (next?.status === "succeeded" || next?.status === "failed") return { kind: "terminal", job: next };
 		}
-		if (options.shouldContinue() && !options.signal?.aborted) return operations.jobStatus(jobId);
-		return undefined;
+		if (!options.shouldContinue() || options.signal?.aborted) return { kind: "canceled" };
+		return (await checkStatus()) ?? { kind: "timed-out" };
 	} finally {
 		options.signal?.removeEventListener("abort", onAbort);
 		watch?.close();
@@ -186,12 +220,31 @@ export async function monitorWorkspaceCache(operations: WorkspaceCacheOperations
 	}
 	options.onState({ status: "caching", jobId });
 
-	const job = await waitForJobCompletion(operations, jobId, {
+	const outcome = await waitForJobCompletion(operations, jobId, {
 		pollIntervalMs: options.pollIntervalMs,
 		maxPolls: options.maxPolls,
 		shouldContinue: options.shouldContinue,
 		sleep,
 	});
-	if (job?.status === "failed") throw new Error(`${job.error.code}: ${job.error.message}`);
-	if (job?.status === "succeeded") reportCompleted(job);
+	if (outcome.kind === "canceled") return;
+	if (outcome.kind === "terminal") {
+		if (outcome.job.status === "failed") throw new Error(`${outcome.job.error.code}: ${outcome.job.error.message}`);
+		reportCompleted(outcome.job);
+		return;
+	}
+	// job-not-found, timed-out, and transport-failed all mean the same thing here: this specific
+	// watch no longer knows the job's real state. Never leave the last-reported "caching" message
+	// standing -- ask the daemon's own authoritative record what is actually true right now.
+	const reconciled = await operations.status(options.directory, options.maxFiles, options.maxSymbolsPerFile);
+	if (reconciled.status === "cached") {
+		options.onState({ status: "cached" });
+	} else if (reconciled.status === "partial") {
+		options.onState({ status: "partial", result: reconciled.generation.result });
+	} else if (reconciled.status === "not-cached") {
+		options.onState({ status: "not-cached", reason: reconciled.reason });
+	} else {
+		// Still genuinely caching or queued behind resource admission under a fresh check --
+		// an accurate report, not a stale one, even though the presented status string repeats.
+		options.onState({ status: "caching", jobId: reconciled.jobId });
+	}
 }

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

@@ -1,4 +1,4 @@
-import type { JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
+import type { CacheResultCounts, JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
 
 type WorkspaceCacheAction = "status" | "populate" | "wait" | "job_status";
@@ -23,7 +23,7 @@ export function formatWorkspaceCacheCall(
 	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", directory)}${bounds}`;
 }
 
-function formatResultCounts(result: PopulateSymbolGraphResult): string {
+function formatResultCounts(result: CacheResultCounts): 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`;
 }

package/package.json

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

package/extension/src/nearest-workspace-root.ts

@@ -1,130 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, parse, relative } from "node:path";
-import picomatch from "picomatch";
-
-/**
- * The bare filesystem root is never a legitimate discovered project root, even if it happens
- * to contain a marker file (a stray `git init /`, a leftover `package.json`) -- matches the
- * same convention already established elsewhere in this house (oculus/survey/rust_scanner.go's
- * findCrateRoot, oculus/locator/match.go's effectiveParent: reaching "/" during a walk-up means
- * "not found", never "found here"). Confirmed live: without this, a Lector daemon registered
- * "/" as a workspace and a background job attempted to symbol-graph the entire filesystem.
- * `exists` is injectable so a test can simulate "a marker exists at the filesystem root"
- * without ever touching the real one.
- */
-function walkUpForMarkers(startDirectory: string, markers: readonly string[], exists: (path: string) => boolean = existsSync): string | undefined {
-	let dir = startDirectory;
-	const fsRoot = parse(dir).root;
-	while (dir !== fsRoot) {
-		if (markers.some((marker) => exists(join(dir, marker)))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) break; // defensive: dirname must be strictly ascending
-		dir = parent;
-	}
-	return undefined;
-}
-
-/**
- * The nearest enclosing git repository root starting from (and including) a given directory,
- * or undefined if none is found (e.g. /tmp scratch files, dotfiles outside any repo, or the
- * walk reaching the filesystem root without a match). Callers choose their own fallback -- see
- * lector-client.ts's workspaceForPath (falls back to the filesystem root: any absolute path is
- * fair game for read/write/edit, exactly as Pi's built-in tools already allow) vs.
- * workspaceForDirectory (falls back to the directory itself: widening a symbol-search scope all
- * the way to the entire filesystem when a project isn't a git repo would be absurd).
- *
- * This -- not a Pi session's original cwd -- is Lector's real workspace granularity. A session
- * routinely touches many unrelated repos, sibling projects, and scratch paths in one run; Pi's
- * built-in read/write/edit tools have never restricted which absolute path can be touched, and
- * Lector must not either. (Real, shipped bug this fixes: read/write/edit hard-locked to
- * whatever directory the session happened to start in, refusing every legitimate path outside
- * it with a "Lector-registered workspace root" error -- discovered live, in a separate session,
- * working against a completely different, unrelated repository.)
- *
- * `exists` is injectable for tests -- see walkUpForMarkers.
- */
-/**
- * True for the bare filesystem root itself ("/" on Linux/macOS, "C:\\" on Windows) -- the one
- * path a caller must never treat as a real project to auto-index. workspaceForPath's own
- * intentional fallback for a raw read/write of a file outside any git repo can still produce
- * this value; callers that trigger background work (auto-population, cache monitoring) off a
- * newly-registered workspace must check this explicitly rather than assuming
- * nearestGitRoot/nearestProjectRoot are the only paths that can hand them a workspace root.
- */
-export function isFilesystemRoot(path: string): boolean {
-	return parse(path).root === path;
-}
-
-export function nearestGitRoot(startDirectory: string, exists: (path: string) => boolean = existsSync): string | undefined {
-	return walkUpForMarkers(startDirectory, [".git"], exists);
-}
-
-/**
- * Same nearest-enclosing-root walk as nearestGitRoot, but also checks a language's own root
- * markers (tsconfig.json, go.mod, Cargo.toml, ...) at each directory, nearest first -- so a
- * monorepo subproject with its own root marker resolves to itself, not the outer repo's .git.
- * Found via @arvoretech/pi-lsp comparison: without this, a file inside a monorepo subproject
- * misattributes its whole project to the repo root, handing the language server the wrong
- * rootUri (and, for TypeScript, the wrong tsconfig.json) even though a closer one exists.
- */
-export function nearestProjectRoot(startDirectory: string, rootMarkers: readonly string[], exists: (path: string) => boolean = existsSync): string | undefined {
-	return walkUpForMarkers(startDirectory, [...rootMarkers, ".git"], exists);
-}
-
-/** An npm/yarn/bun package.json's own "workspaces" field: either a bare glob array, or `{ packages: [...] }` (pnpm's own equivalent shape for the same field, embedded inside package.json rather than a separate pnpm-workspace.yaml). */
-interface WorkspacesManifest {
-	workspaces?: string[] | { packages?: string[] };
-}
-
-function readWorkspaceGlobs(packageJsonPath: string, readFile: (path: string) => string): string[] | undefined {
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(readFile(packageJsonPath));
-	} catch {
-		return undefined;
-	}
-	if (typeof parsed !== "object" || parsed === null) return undefined;
-	const { workspaces } = parsed as WorkspacesManifest;
-	const globs = Array.isArray(workspaces) ? workspaces : (workspaces?.packages ?? undefined);
-	return Array.isArray(globs) ? globs.filter((entry): entry is string => typeof entry === "string") : undefined;
-}
-
-/**
- * The nearest ancestor of a real project root (as found by nearestProjectRoot) whose own
- * package.json declares that project as a workspace member via npm/yarn/bun's "workspaces"
- * field -- never an arbitrary ancestor that merely happens to have its own marker file. Walks
- * upward past ancestors with no "workspaces" field (or one that doesn't actually match this
- * project's relative path) rather than stopping at the first package.json found, since an
- * intermediate directory can be a plain package with no workspaces declaration of its own.
- *
- * Mirrors how mature language tooling handles this same monorepo shape: TypeScript's tsserver
- * only widens a file's project scope to an ancestor "solution" tsconfig that explicitly lists
- * the nearer project in its own `references`, and rust-analyzer treats Cargo's `[workspace]`
- * `members` list as the authoritative multi-crate boundary rather than inferring one from
- * directory structure. This is the same idea applied to npm/yarn/bun's own declared
- * "workspaces" glob instead of a language-specific manifest.
- *
- * Returns undefined (no declared ancestor) for a plain single-package repo, or when no ancestor's
- * "workspaces" globs actually match this project -- callers must not treat an arbitrary git root
- * as an implicit stand-in.
- */
-export function nearestDeclaredWorkspaceRoot(
-	projectRoot: string,
-	exists: (path: string) => boolean = existsSync,
-	readFile: (path: string) => string = (path) => readFileSync(path, "utf8"),
-): string | undefined {
-	let dir = dirname(projectRoot);
-	const fsRoot = parse(dir).root;
-	while (dir !== fsRoot) {
-		const packageJsonPath = join(dir, "package.json");
-		if (exists(packageJsonPath)) {
-			const globs = readWorkspaceGlobs(packageJsonPath, readFile);
-			const relativePath = relative(dir, projectRoot);
-			if (globs?.some((glob) => picomatch(glob)(relativePath))) return dir;
-		}
-		const parent = dirname(dir);
-		if (parent === dir) break; // defensive: dirname must be strictly ascending
-		dir = parent;
-	}
-	return undefined;
-}