@danypops/pi-lector 0.12.5 → 0.12.7

package/extension/src/client-diagnostics.ts

@@ -0,0 +1,46 @@
+import type { RetryingClientDiagnosticEvent } from "@danypops/vehicle-client/daemon-client";
+
+/**
+ * Formats one createRetryingClient diagnostic event as a single, compact line -- the same real
+ * RCA gap @danypops/vehicle-client's own onEvent hook was added to close: a scrubbed "connector
+ * unavailable" error at the tool-call boundary otherwise gives no way to tell, after the fact,
+ * whether it was a genuine fresh connect() failure, a circuit-breaker short-circuit (no connect
+ * attempted at all), or an in-flight operation's stale-connection retry. Never includes a stack
+ * trace -- name and message only, matching this house's other client-diagnostic channels
+ * (@danypops/vehicle-client-pi's own client-diagnostics.ts).
+ */
+/** Never risks Object's default `[object Object]` stringification for a non-Error, non-string throw. */
+function describeError(error: unknown): { name: string; message: string } {
+	if (error instanceof Error) return { name: error.name, message: error.message };
+	if (typeof error === "string") return { name: "string", message: error };
+	if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") return { name: typeof error, message: String(error) };
+	return { name: typeof error, message: "(unprintable value)" };
+}
+
+export function formatClientDiagnosticEvent(event: RetryingClientDiagnosticEvent): string {
+	const parts = [`[lector-client] ${event.type}`];
+	if (event.attempt !== undefined) parts.push(`attempt=${event.attempt}`);
+	if (event.consecutiveFailures !== undefined) parts.push(`consecutiveFailures=${event.consecutiveFailures}`);
+	if (event.operationId !== undefined) parts.push(`operationId=${event.operationId}`);
+	if (event.error !== undefined) {
+		const { name, message } = describeError(event.error);
+		parts.push(`error=${name}: ${message}`);
+	}
+	return parts.join(" ");
+}
+
+/**
+ * Logs a createRetryingClient diagnostic event to stderr, only when LECTOR_CLIENT_DIAG is set --
+ * zero cost and zero output for every session that never opts in, matching the env-gated
+ * convention @danypops/vehicle-client-pi's own VEHICLE_CLIENT_DIAG already established in this
+ * house. Never throws: onEvent's own contract requires it stay side-effect-light, and a broken
+ * local console (or a formatting bug) must not take down a real client call.
+ */
+export function logClientDiagnosticEvent(event: RetryingClientDiagnosticEvent): void {
+	if (!process.env.LECTOR_CLIENT_DIAG) return;
+	try {
+		console.error(formatClientDiagnosticEvent(event));
+	} catch {
+		// best-effort only -- see doc comment above.
+	}
+}

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

@@ -10,7 +10,13 @@ import { forgetWorkspaceId, lectorClient, type ResolvedWorkspace, workspaceForPr
  * 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[],
@@ -126,11 +132,11 @@ async function withCrossWorkspaceRestartRecovery<T>(
 
 export function createLectorCrossWorkspaceSearchOperations(): CrossWorkspaceSearchOperations {
 	return {
-		findSymbols(query, directories, timeoutMs) {
+		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 });
+				const { results } = await client.call("search.symbols", { query, workspaceIds, timeoutMs, ...(maxResults !== undefined ? { maxResults } : {}) });
 				return zipOutcomes(directories, workspaceIds, results);
 			});
 		},

package/extension/src/index.ts

@@ -1,3 +1,5 @@
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 import type {
 	CachedRepositoryPage,
@@ -44,6 +46,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 { classifyAutoPopulationRoot, 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 +92,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,
@@ -214,10 +216,23 @@ export default function (pi: ExtensionAPI) {
 	 * intentional fallback for a raw read/write of a file outside any git repo can register
 	 * exactly this as a "new workspace", and auto-populating it would attempt a full
 	 * filesystem-wide symbol-graph scan -- confirmed live as a real, previously-shipped bug.
+	 *
+	 * Also short-circuits a broad host directory (home directory, an XDG config/cache/data
+	 * root, a dotfile directory) the exact same way workspace.populateSymbolGraph's own
+	 * server-side gate would refuse it -- avoids the round trip (and the queue-behind-real-
+	 * projects ergonomics this caused live for ~/.pi/agent) entirely, using the identical
+	 * classification Lector itself uses so the two never drift. A readdir failure (permission,
+	 * race) is treated as "can't tell, don't block" -- the server-side gate is still authoritative.
 	 */
 	function startMonitoringRoot(root: string, ctx: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1]): void {
 		if (isFilesystemRoot(root)) return;
 		if (monitoringRoots.has(root)) return;
+		try {
+			const topLevelEntries = readdirSync(root);
+			if (classifyAutoPopulationRoot({ rootPath: root, homeDir: homedir(), topLevelEntries }) === "broad-non-project") return;
+		} catch {
+			// Can't read it here -- let the server-side gate be the authoritative answer.
+		}
 		monitoringRoots.add(root);
 		const thisGeneration = sessionGeneration;
 		void monitorWorkspaceCache(cacheOperations, {
@@ -279,9 +294,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 +1178,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 +1839,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,32 @@ 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";
+import { logClientDiagnosticEvent } from "./client-diagnostics.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>;
@@ -41,15 +45,19 @@ let connector: ClientConnector = () => connectLectorClient();
 const retryingClient: RetryingClient<LectorClient> = createRetryingClient(() => connector(), {
 	label: "Lector",
 	isStaleConnectionError: (error) => error instanceof LectorDaemonUnavailable || isLikelyStaleConnectionError(error),
+	// Purely observational, opt-in via LECTOR_CLIENT_DIAG -- see client-diagnostics.ts's own doc
+	// comment for the exact RCA gap this closes.
+	onEvent: logClientDiagnosticEvent,
 });
-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 +88,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 +130,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 +140,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 +152,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 +180,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 +200,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 +216,67 @@ 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 });
+}
+
+/** Raised by workspaceForAnnotationPath for a path that does not exist on disk at all -- a distinct, explicit failure the caller must handle, never silently guessed as "must be a file, take its dirname()." */
+export class AnnotationPathDoesNotExist extends Error {
+	constructor(readonly path: string) {
+		super(`"${path}" does not exist -- a symbol-annotation scope must be a real project directory or an existing source file`);
+		this.name = "AnnotationPathDoesNotExist";
+	}
+}
+
+/**
+ * For symbol-annotation's own `path` parameter, which genuinely means "which workspace does this
+ * belong to" and can honestly be either an existing project directory or one specific source
+ * file -- unlike workspaceForCodeIntelligencePath (files only, dirname() unconditional), a real
+ * project directory resolves via its own language markers, not its parent's. A genuinely
+ * nonexistent path throws AnnotationPathDoesNotExist rather than being silently treated as a file.
+ */
+export async function workspaceForAnnotationPath(path: string): Promise<ResolvedWorkspace> {
+	const request: WorkspaceResolutionRequest = { strategy: "code-intelligence-path-or-directory", path };
+	const key = requestCacheKey(request);
+	const cached = resolutionCache.get(key);
+	if (cached) return cached;
+	const client = await lectorClient();
+	const outcome = await client.callOnce("workspace.resolvePath", request);
+	if (!outcome.found) {
+		if (outcome.reason === "nonexistent-path") throw new AnnotationPathDoesNotExist(path);
+		throw new Error(`workspace.resolvePath unexpectedly reported not-found for code-intelligence-path-or-directory: ${path}`);
+	}
+	const resolved: ResolvedWorkspace = { workspaceId: outcome.workspaceId, root: outcome.root };
+	resolutionCache.set(key, resolved);
+	if (outcome.created) onNewWorkspace?.(outcome.root);
+	return resolved;
+}
+
+/**
+ * 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,30 +292,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 one root's cached workspaceId without retrying anything itself -- the batch sibling of
- * withWorkspace's own single-workspace `workspaceIdByRoot.delete(resolved.root)` 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.
+ * 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 {
-	workspaceIdByRoot.delete(root);
+	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/symbol-annotation/operations.ts

@@ -1,5 +1,5 @@
 import type { OperationInputs, OperationOutputs } from "@danypops/lector";
-import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "../lector-client.ts";
+import { lectorClient, withWorkspace, workspaceForAnnotationPath } from "../lector-client.ts";
 
 /** A bare symbol position an anchor is given as -- symbolNodeId and the anchor's baseline file hash are derived server-side, never supplied by the caller. */
 export interface AnnotationAnchorInput {
@@ -9,10 +9,12 @@ export interface AnnotationAnchorInput {
 }
 
 /**
- * Thin wrappers over Lector's annotation operations. Anchored to a workspace
- * via the first anchor's own path (workspaceForCodeIntelligencePath) --
- * every operation that needs a workspace already has at least one real
- * anchor position or an id whose workspace the caller already knows.
+ * Thin wrappers over Lector's annotation operations. Every operation resolves its workspace from
+ * its own `path` parameter via workspaceForAnnotationPath -- a real project directory or an
+ * existing source file, never dirname()'d unconditionally the way a plain code-intelligence
+ * path is. `path` here means "which workspace this call belongs to," not necessarily one of the
+ * operation's own anchors (create/refresh's anchors carry their own, separately-validated paths
+ * server-side).
  */
 export interface SymbolAnnotationOperations {
 	create(
@@ -46,7 +48,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 	return {
 		async create(path, subtype, title, body, anchors) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.createAnnotation", { workspaceId, subtype, title, body, anchors });
@@ -55,7 +57,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async get(path, id) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.call("workspace.getAnnotation", { workspaceId, id });
@@ -64,7 +66,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async list(path, options = {}) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.call("workspace.listAnnotations", {
@@ -79,7 +81,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async refresh(path, id, subtype, title, body, anchors) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.refreshAnnotation", { workspaceId, id, subtype, title, body, anchors });
@@ -88,7 +90,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async scrub(path, id) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.scrubAnnotation", { workspaceId, id });
@@ -97,7 +99,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async restore(path, id) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.restoreAnnotation", { workspaceId, id });
@@ -106,7 +108,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async contain(path, parentId, childId) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.containAnnotation", { workspaceId, parentId, childId });
@@ -115,7 +117,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async uncontain(path, parentId, childId) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.callOnce("workspace.uncontainAnnotation", { workspaceId, parentId, childId });
@@ -124,7 +126,7 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 		},
 		async tree(path, rootId, maxDepth) {
 			return withWorkspace(
-				() => workspaceForCodeIntelligencePath(path),
+				() => workspaceForAnnotationPath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
 					return client.call("workspace.annotationTree", { workspaceId, rootId, maxDepth });

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.5",
+	"version": "0.12.7",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -18,9 +18,9 @@
 		"typebox": "*"
 	},
 	"dependencies": {
-		"@danypops/vehicle-client": "^0.2.0",
+		"@danypops/vehicle-client": "^0.8.2",
 		"@danypops/lector": "^0.18.0",
-		"malevich-tui-components": "^0.19.0",
+		"malevich-tui-components": "^0.25.0",
 		"picomatch": "^4.0.5"
 	},
 	"devDependencies": {

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;
-}