@danypops/pi-lector 0.3.0 → 0.5.0

package/extension/src/index.ts

@@ -1,5 +1,6 @@
 import { resolve } from "node:path";
 import type {
+	CachedRepositoryPage,
 	ContentHash,
 	Diagnostic,
 	DocumentSymbolEntry,
@@ -10,6 +11,8 @@ import type {
 	JobSnapshot,
 	LineEdit,
 	LineEditOutcome,
+	MutationHistoryEntry,
+	OperationOutputs,
 	PackageSourceOperationResult,
 	PopulateSymbolGraphResult,
 	RepoFetchResult,
@@ -66,14 +69,20 @@ 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 { createLectorLineEditOperations } from "./line-edit-operations.ts";
 import { formatLineEditCall, formatLineEditResult } from "./line-edit-rendering.ts";
+import { createMutationHistoryOperations } from "./mutation-history-operations.ts";
 import { nearestGitRoot } from "./nearest-workspace-root.ts";
 import { createLectorPackageSourceOperations } from "./package-source-operations.ts";
 import { formatPackageSourceCall, formatPackageSourceResult } from "./package-source-rendering.ts";
 import { createLectorReadOperations } from "./read-operations.ts";
+import { createReferenceBasedRenameOperations } from "./reference-based-rename-operations.ts";
+import { createRenameOperations } from "./rename-operations.ts";
+import { createRepoCacheEvictOperations } from "./repo-cache-evict-operations.ts";
+import { createRepoCacheListOperations } from "./repo-cache-list-operations.ts";
+import { formatRepoCacheCall, formatRepoCacheEvictResult, formatRepoCacheListResult, formatRepoFetchResult } from "./repo-cache-rendering.ts";
 import { createLectorRepoFetchOperations } from "./repo-fetch-operations.ts";
-import { formatRepoFetchCall, formatRepoFetchResult } from "./repo-fetch-rendering.ts";
 import { createLectorSearchOperations } from "./search-operations.ts";
 import { formatSearchCall, formatSearchResult } from "./search-rendering.ts";
 import { type AnnotationAnchorInput, createLectorSymbolAnnotationOperations } from "./symbol-annotation-operations.ts";
@@ -115,63 +124,115 @@ function renderIntelligenceSource(body: string, provenance: IntelligenceProvenan
  */
 export default function (pi: ExtensionAPI) {
 	const cacheOperations = createWorkspaceCacheOperations();
-	let cacheRun = 0;
-	let cacheState: CachePresentationState | undefined;
-	let lastInjectedCacheState: string | undefined;
+	// One generation counter shared by every root's monitor loop, not per-root -- a new session
+	// (or shutdown) invalidates every previous session's in-flight monitor regardless of which
+	// root it tracked, and there is exactly one "current session" at a time.
+	let sessionGeneration = 0;
+	// Every workspace root actually touched so far this session, not just one fixed cwd root --
+	// populated by setNewWorkspaceObserver below, the real "first touch" trigger.
+	const cacheStatesByRoot = new Map<string, CachePresentationState>();
+	// Roots already monitored this session -- guards against starting the SAME root's monitor
+	// twice: session_start's own direct kick-off for the cwd root itself calls
+	// cacheOperations.status(), which registers that root via workspace.registerPath, which fires
+	// setNewWorkspaceObserver for it a moment later -- without this guard that would start a
+	// second, redundant concurrent monitor loop for the exact same root.
+	const monitoringRoots = new Set<string>();
+	let lastInjectedSummary: string | undefined;
+	let uiContext: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1] | undefined;
+
+	function combinedSummary(): string {
+		const states = [...cacheStatesByRoot.values()];
+		if (states.length === 0) return "";
+		const [only] = states;
+		if (states.length === 1 && only) return describeCacheState(only);
+		const counts = new Map<string, number>();
+		for (const state of states) counts.set(state.status, (counts.get(state.status) ?? 0) + 1);
+		return [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(", ");
+	}
+
+	function refreshStatusBar(): void {
+		if (!uiContext) return;
+		const summary = combinedSummary();
+		if (!summary) {
+			uiContext.ui.setStatus("lector-cache", undefined);
+			return;
+		}
+		const states = [...cacheStatesByRoot.values()];
+		const worst = states.some((state) => state.status === "not-cached" || state.status === "caching")
+			? "warning"
+			: states.every((state) => state.status === "cached")
+				? "success"
+				: "accent";
+		uiContext.ui.setStatus("lector-cache", uiContext.ui.theme.fg(worst, `Lector: ${summary}`));
+	}
+
+	/** Starts (or restarts, on a stale generation) monitoring one workspace root's cache lifecycle -- shared by session_start's own cwd root and every later root a tool call first touches. */
+	function startMonitoringRoot(root: string, ctx: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1]): void {
+		if (monitoringRoots.has(root)) return;
+		monitoringRoots.add(root);
+		const thisGeneration = sessionGeneration;
+		void monitorWorkspaceCache(cacheOperations, {
+			directory: root,
+			maxFiles: 500,
+			maxSymbolsPerFile: 100,
+			pollIntervalMs: 1_000,
+			maxPolls: 300,
+			shouldContinue: () => sessionGeneration === thisGeneration,
+			onState: (state) => {
+				if (sessionGeneration !== thisGeneration) return;
+				cacheStatesByRoot.set(root, state);
+				if (state.status === "finished-caching") {
+					if (ctx.hasUI) ctx.ui.notify(`Lector finished caching ${root}`, "info");
+					return;
+				}
+				refreshStatusBar();
+			},
+		}).catch((error: unknown) => {
+			if (sessionGeneration !== thisGeneration) return;
+			const message = error instanceof Error ? error.message : String(error);
+			cacheStatesByRoot.delete(root);
+			refreshStatusBar();
+			if (ctx.hasUI) ctx.ui.notify(`Lector cache failed for ${root}: ${message}`, "error");
+		});
+	}
 
 	pi.on("before_agent_start", () => {
-		if (!cacheState) return;
-		const description = describeCacheState(cacheState);
-		if (description === lastInjectedCacheState) return;
-		lastInjectedCacheState = description;
+		const summary = combinedSummary();
+		if (!summary || summary === lastInjectedSummary) return;
+		lastInjectedSummary = summary;
+		const messages = [...cacheStatesByRoot.entries()]
+			.filter(([, state]) => state.status !== "cached")
+			.map(([root, state]) => `${root}: ${cacheContextMessage(state)}`);
+		if (messages.length === 0) return;
 		return {
 			message: {
 				customType: "lector-cache-status",
-				content: cacheContextMessage(cacheState),
+				content: messages.join("\n"),
 				display: false,
 			},
 		};
 	});
 
 	pi.on("session_shutdown", (_event, ctx) => {
-		cacheRun++;
-		cacheState = undefined;
-		lastInjectedCacheState = undefined;
+		sessionGeneration++;
+		cacheStatesByRoot.clear();
+		monitoringRoots.clear();
+		lastInjectedSummary = undefined;
+		uiContext = undefined;
 		ctx.ui.setStatus("lector-cache", undefined);
 	});
 
 	pi.on("session_start", (_event, ctx) => {
 		const { cwd } = ctx;
+		sessionGeneration++;
+		cacheStatesByRoot.clear();
+		monitoringRoots.clear();
+		lastInjectedSummary = undefined;
+		uiContext = ctx;
+		setNewWorkspaceObserver((root) => startMonitoringRoot(root, ctx));
 		const projectRoot = nearestGitRoot(cwd);
-		const thisRun = ++cacheRun;
-		cacheState = undefined;
-		lastInjectedCacheState = undefined;
-		if (projectRoot) {
-			void monitorWorkspaceCache(cacheOperations, {
-				directory: projectRoot,
-				maxFiles: 500,
-				maxSymbolsPerFile: 100,
-				pollIntervalMs: 1_000,
-				maxPolls: 300,
-				shouldContinue: () => cacheRun === thisRun,
-				onState: (state) => {
-					cacheState = state;
-					if (state.status === "finished-caching") {
-						if (ctx.hasUI) ctx.ui.notify(`Lector finished caching ${projectRoot}`, "info");
-						return;
-					}
-					const color = state.status === "cached" ? "success" : state.status === "caching" ? "accent" : "warning";
-					ctx.ui.setStatus("lector-cache", ctx.ui.theme.fg(color, `Lector: ${describeCacheState(state)}`));
-				},
-			}).catch((error: unknown) => {
-				if (cacheRun !== thisRun) return;
-				const message = error instanceof Error ? error.message : String(error);
-				ctx.ui.setStatus("lector-cache", ctx.ui.theme.fg("error", "Lector: cache error"));
-				if (ctx.hasUI) ctx.ui.notify(`Lector cache failed: ${message}`, "error");
-			});
-		} else {
-			ctx.ui.setStatus("lector-cache", undefined);
-		}
+		if (projectRoot) startMonitoringRoot(projectRoot, ctx);
+		else ctx.ui.setStatus("lector-cache", undefined);
 
 		pi.registerTool(createReadToolDefinition(cwd, { operations: createLectorReadOperations() }));
 		pi.registerTool(createWriteToolDefinition(cwd, { operations: createLectorWriteOperations() }));
@@ -241,6 +302,8 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const codeIntelligenceOperations = createLectorCodeIntelligenceOperations();
+		const referenceBasedRenameOperations = createReferenceBasedRenameOperations();
+		const renameOperations = createRenameOperations();
 		const positionParameters = {
 			path: Type.String({ description: "Absolute or cwd-relative path to the file" }),
 			line: Type.Number({ description: "1-indexed line number" }),
@@ -622,6 +685,125 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		pi.registerTool({
+			name: "reference_based_rename",
+			label: "Reference-Based Rename",
+			description:
+				"Move/rename a file and rewrite every static import/export specifier the workspace's own populated symbol graph knows references it -- atomically, rolled back entirely on any failure. Non-LSP: uses find_references + a real parse of import/export declarations, not a language server's own rename. Refuses outright (touches nothing) unless the workspace's symbol graph is fully populated and current for the given bounds -- a partial rename that silently misses a reference is worse than refusing (Sourcegraph's CodeScaleBench finding). Does not follow dynamic import(expr)/require(expr) or any plain string reference to the file -- always check the returned caveats.",
+			promptSnippet: "Move a file and update every import that references it",
+			promptGuidelines: [
+				"Run populate_symbol_graph for this workspace first if cache_status/has_warm_index doesn't already show a fully cached (never partial) graph -- reference_based_rename refuses outright otherwise.",
+				"Always read the returned caveats: this never rewrites a dynamic import(expr)/require(expr) or a plain string reference to the old path, even if one exists.",
+			],
+			parameters: Type.Object({
+				fromPath: Type.String({ description: "Absolute or cwd-relative path to the file to move" }),
+				toPath: Type.String({ description: "Absolute or cwd-relative path for its new location" }),
+				maxFiles: Type.Number({ description: "Maximum number of source files the workspace's symbol graph must have scanned" }),
+				maxSymbolsPerFile: Type.Number({ description: "Maximum number of declarations per file the workspace's symbol graph must have processed" }),
+			}),
+			async execute(_toolCallId, params) {
+				const fromPath = resolve(cwd, params.fromPath);
+				const toPath = resolve(cwd, params.toPath);
+				const outcome = await referenceBasedRenameOperations.rename(fromPath, toPath, params.maxFiles, params.maxSymbolsPerFile);
+				const lines = [
+					`moved to ${outcome.movedTo}`,
+					outcome.filesUpdated.length === 0
+						? "no other files referenced it"
+						: `updated imports in ${outcome.filesUpdated.length} file(s): ${outcome.filesUpdated.join(", ")}`,
+					...outcome.caveats.map((caveat) => `caveat: ${caveat}`),
+				];
+				return { content: [{ type: "text", text: lines.join("\n") }], details: { outcome } };
+			},
+			renderCall(args, theme, context) {
+				const fromPath = typeof args.fromPath === "string" ? args.fromPath : "";
+				const toPath = typeof args.toPath === "string" ? args.toPath : "";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(
+					`${theme.fg("toolTitle", theme.bold("reference_based_rename"))} ${theme.fg("accent", fromPath)} ${theme.fg("dim", "->")} ${theme.fg("accent", toPath)}`,
+				);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Renaming..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "reference_based_rename failed"), 0, 0);
+				}
+				const details = result.details as { outcome?: { movedTo: string; filesUpdated: readonly string[] } } | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(
+					details?.outcome
+						? `${theme.fg("success", "moved")} ${theme.fg("accent", details.outcome.movedTo)} ${theme.fg("dim", `(${details.outcome.filesUpdated.length} import(s) updated)`)}`
+						: theme.fg("success", "rename complete"),
+				);
+				return text;
+			},
+		});
+
+		interface RenameToolDetails {
+			prepared?: OperationOutputs["workspace.prepareRename"];
+			applied?: OperationOutputs["workspace.rename"];
+		}
+
+		pi.registerTool({
+			name: "rename",
+			label: "Rename",
+			description:
+				"LSP-driven rename via the negotiated language server's own textDocument/prepareRename and textDocument/rename -- the semantic sibling of reference_based_rename, cross-file and identity-aware (resolves through re-exports/aliasing, not just static import specifiers), but only where the workspace's language server actually implements rename. prepare checks whether the symbol at a position can be renamed at all before committing; apply requests the rename and applies the server's own WorkspaceEdit atomically across every file it touches, rolled back entirely on any failure. Actions: prepare, apply.",
+			promptSnippet: "Rename a symbol everywhere it's used, via the language server",
+			promptGuidelines: [
+				"Call prepare first when unsure a position is renameable -- a null range means nothing to rename there, not an error.",
+				"apply fails outright if the negotiated server never advertised rename support -- reference_based_rename is the non-LSP fallback for that case.",
+			],
+			parameters: Type.Object({
+				action: Type.String({ description: "prepare | apply" }),
+				...positionParameters,
+				newName: Type.Optional(Type.String({ description: "Required for apply" })),
+			}),
+			async execute(_toolCallId, params): Promise<{ content: [{ type: "text"; text: string }]; details: RenameToolDetails }> {
+				const path = resolve(cwd, params.path);
+				if (params.action === "prepare") {
+					const prepared = await renameOperations.prepareRename(path, params.line, params.character);
+					const text = prepared.range
+						? `renameable${prepared.range.placeholder ? `: "${prepared.range.placeholder}"` : ""}`
+						: "nothing renameable at this position";
+					return { content: [{ type: "text", text }], details: { prepared } };
+				}
+				if (params.action === "apply") {
+					if (!params.newName) throw new Error("rename apply requires newName");
+					const applied = await renameOperations.rename(path, params.line, params.character, params.newName);
+					const text = `renamed to "${params.newName}" -- updated ${applied.touchedPaths.length} file(s): ${applied.touchedPaths.join(", ")}`;
+					return { content: [{ type: "text", text }], details: { applied } };
+				}
+				throw new Error(`unknown rename action "${params.action}" -- expected prepare or apply`);
+			},
+			renderCall(args, theme, context) {
+				const action = typeof args.action === "string" ? args.action : "";
+				const path = typeof args.path === "string" ? args.path : "";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(`${theme.fg("toolTitle", theme.bold("rename"))} ${theme.fg("dim", action)} ${theme.fg("accent", path)}`);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Renaming..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "rename failed"), 0, 0);
+				}
+				const text = result.content
+					.filter((block) => block.type === "text")
+					.map((block) => block.text)
+					.join("\n");
+				return new Text(theme.fg("success", text), 0, 0);
+			},
+		});
+
 		const symbolAnnotationOperations = createLectorSymbolAnnotationOperations();
 		function resolveAnchorInputs(anchors: readonly { path: string; line: number; character: number }[]): AnnotationAnchorInput[] {
 			return anchors.map((anchor) => ({ path: resolve(cwd, anchor.path), line: anchor.line, character: anchor.character }));
@@ -1165,6 +1347,67 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		type MutationHistoryToolDetails =
+			| { readonly action: "list"; readonly entries: readonly MutationHistoryEntry[] }
+			| { readonly action: "revert"; readonly reverted: { readonly path: string; readonly newHash: string | null } };
+
+		const mutationHistoryOperations = createMutationHistoryOperations();
+		pi.registerTool({
+			name: "mutation_history",
+			label: "Mutation History",
+			description:
+				"List or revert a file's recorded edit history. Every successful edit/line_edit/apply_patch is recorded (newest first, bounded, not durable across a daemon restart). Reverting restores the file to its exact content immediately before that entry's own mutation, guarded the same way every Lector write is -- refuses if the file changed since, rather than silently clobbering a newer change. A revert is itself a real, further-revertible mutation -- reverting a revert works.",
+			promptSnippet: "List or revert a file's recorded edit history",
+			promptGuidelines: [
+				"list first to find the entry id you want, then revert -- an id from a different file's history, or one already evicted by the bounded history, fails closed rather than guessing.",
+			],
+			parameters: Type.Object({
+				action: Type.Union([Type.Literal("list"), Type.Literal("revert")]),
+				path: Type.String({ description: "Absolute or workspace-relative path to the file" }),
+				maxResults: Type.Optional(Type.Number({ description: "Required for action=list -- maximum entries to return, newest first" })),
+				entryId: Type.Optional(Type.String({ description: "Required for action=revert -- an id returned by a prior action=list" })),
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<MutationHistoryToolDetails>> {
+				const absolutePath = resolve(cwd, params.path);
+				if (params.action === "list") {
+					if (params.maxResults === undefined) throw new Error("mutation_history action=list requires maxResults");
+					const entries = await mutationHistoryOperations.list(absolutePath, params.maxResults);
+					const text =
+						entries.length === 0
+							? "no recorded mutation history for this path"
+							: entries.map((entry) => `${entry.id}  ${new Date(entry.timestamp).toISOString()}  ${entry.operation}`).join("\n");
+					return { content: [{ type: "text", text }], details: { action: "list", entries } };
+				}
+				if (params.entryId === undefined) throw new Error("mutation_history action=revert requires entryId");
+				const reverted = await mutationHistoryOperations.revert(absolutePath, params.entryId);
+				return {
+					content: [{ type: "text", text: `${reverted.path} reverted -> ${reverted.newHash ?? "(deleted)"}` }],
+					details: { action: "revert", reverted },
+				};
+			},
+			renderCall(args, theme, context) {
+				const action = typeof args.action === "string" ? args.action : "";
+				const path = typeof args.path === "string" ? args.path : "";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(`${theme.fg("toolTitle", theme.bold("mutation_history"))} ${theme.fg("accent", action)} ${theme.fg("dim", path)}`);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Working on mutation history..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "mutation_history failed"), 0, 0);
+				}
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				const textBlock = result.content.find((block) => block.type === "text");
+				text.setText(theme.fg("success", textBlock && "text" in textBlock ? textBlock.text : "done"));
+				return text;
+			},
+		});
+
 		const packageSourceOperations = createLectorPackageSourceOperations();
 		pi.registerTool({
 			name: "package_source",
@@ -1204,40 +1447,75 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		type RepoCacheToolDetails =
+			| { readonly action: "fetch"; readonly result: RepoFetchResult & { workspaceId: string } }
+			| { readonly action: "list"; readonly page: CachedRepositoryPage }
+			| { readonly action: "evict"; readonly result: { evicted: boolean } };
+
 		const repoFetchOperations = createLectorRepoFetchOperations();
+		const repoCacheListOperations = createRepoCacheListOperations();
+		const repoCacheEvictOperations = createRepoCacheEvictOperations();
 		pi.registerTool({
-			name: "repo_fetch",
-			label: "Repo Fetch",
+			name: "repo_cache",
+			label: "Repo Cache",
 			description:
-				"Shallow-clones an external repository into a disk-bounded cache and registers it as a read-only project -- every other tool (search_code, find_symbols, go_to_definition, ...) then works on it unchanged. Explicit owner/repo[@ref] only, no discovery/search -- use web_fetch to find candidates first.",
-			promptSnippet: "Fetch an external open-source repo to search or analyze",
+				"Fetch, list/query, or evict entries in Lector's external-repo cache. action=fetch shallow-clones an external repository into a disk-bounded cache and registers it as a read-only project -- every other tool (search_code, find_symbols, go_to_definition, ...) then works on it unchanged; explicit owner/repo[@ref] only, no discovery/search (use web_fetch to find candidates first); forceRefresh reclones even when an unexpired cache entry already exists, for a caller that has already positively confirmed the remote moved. action=list queries the cache -- no network call, no mutation -- filtering by any combination of host/owner/repo/ref (exact match) and text (case-insensitive substring), bounded and paginated via cursor; each entry reports whether it's currently a registered workspace or just present on disk. action=evict removes one cache entry from disk by its exact host/owner/repo/ref identity; refuses with a clear error if it is still a currently-registered workspace.",
+			promptSnippet: "Fetch, list, or evict entries in the external-repo cache",
 			parameters: Type.Object({
-				owner: Type.String({ description: "Repository owner or organization" }),
-				repo: Type.String({ description: "Repository name" }),
-				ref: Type.Optional(Type.String({ description: "Branch, tag, or commit to fetch; defaults to the repository's default branch" })),
-				host: Type.Optional(Type.String({ description: "Git host; defaults to github.com" })),
+				action: Type.Union([Type.Literal("fetch"), Type.Literal("list"), Type.Literal("evict")]),
+				owner: Type.Optional(Type.String({ description: "Required for action=fetch/evict -- repository owner or organization" })),
+				repo: Type.Optional(Type.String({ description: "Required for action=fetch/evict -- repository name" })),
+				ref: Type.Optional(
+					Type.String({
+						description:
+							"fetch/evict: branch, tag, or commit; defaults to the repository's default branch. list: matches either the requested or the resolved ref",
+					}),
+				),
+				host: Type.Optional(Type.String({ description: "Git host; defaults to github.com for fetch/evict, unfiltered for list" })),
+				forceRefresh: Type.Optional(Type.Boolean({ description: "action=fetch only -- reclone even if an unexpired cache entry already exists" })),
+				text: Type.Optional(Type.String({ description: "action=list only -- case-insensitive substring match across host/owner/repo/refs" })),
+				maxResults: Type.Optional(Type.Number({ description: "Required for action=list -- maximum entries to return in this page" })),
+				cursor: Type.Optional(Type.String({ description: "action=list only -- opaque cursor from a prior call's nextCursor, to fetch the next page" })),
 			}),
-			async execute(_toolCallId, params) {
-				const result = await repoFetchOperations.fetch(params.host ?? "github.com", params.owner, params.repo, params.ref ?? null);
-				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { result } };
+			async execute(_toolCallId, params): Promise<AgentToolResult<RepoCacheToolDetails>> {
+				if (params.action === "fetch") {
+					if (!params.owner || !params.repo) throw new Error("repo_cache action=fetch requires owner and repo");
+					const result = await repoFetchOperations.fetch(params.host ?? "github.com", params.owner, params.repo, params.ref ?? null, params.forceRefresh);
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "fetch", result } };
+				}
+				if (params.action === "evict") {
+					if (!params.owner || !params.repo) throw new Error("repo_cache action=evict requires owner and repo");
+					const result = await repoCacheEvictOperations.evict(params.host ?? "github.com", params.owner, params.repo, params.ref ?? null);
+					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "evict", result } };
+				}
+				if (params.maxResults === undefined) throw new Error("repo_cache action=list requires maxResults");
+				const page = await repoCacheListOperations.list(
+					{ text: params.text, host: params.host, owner: params.owner, repo: params.repo, ref: params.ref },
+					params.maxResults,
+					params.cursor,
+				);
+				return { content: [{ type: "text", text: JSON.stringify(page) }], details: { action: "list", page } };
 			},
 			renderCall(args, theme, context) {
+				const action = args.action === "list" || args.action === "evict" ? args.action : "fetch";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatRepoFetchCall(args, theme));
+				text.setText(formatRepoCacheCall(action, args, theme));
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Fetching repository..."), 0, 0);
+				if (isPartial) return new Text(theme.fg("warning", "Working on repo cache..."), 0, 0);
 				if (context.isError) {
 					const errorText = result.content
 						.filter((block) => block.type === "text")
 						.map((block) => block.text)
 						.join("\n");
-					return new Text(theme.fg("error", errorText || "repo_fetch failed"), 0, 0);
+					return new Text(theme.fg("error", errorText || "repo_cache failed"), 0, 0);
 				}
-				const details = result.details as { result?: RepoFetchResult & { workspaceId: string } } | undefined;
+				const details = result.details as RepoCacheToolDetails | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatRepoFetchResult(details?.result, theme));
+				if (details?.action === "list") text.setText(formatRepoCacheListResult(details.page, theme));
+				else if (details?.action === "evict") text.setText(formatRepoCacheEvictResult(details.result, theme));
+				else text.setText(formatRepoFetchResult(details?.action === "fetch" ? details.result : undefined, theme));
 				return text;
 			},
 		});

package/extension/src/lector-client.ts

@@ -39,6 +39,19 @@ let connector: ClientConnector = () => connectLectorClient();
 const retryingClient: RetryingClient<LectorClient> = createRetryingClient(() => connector(), { label: "Lector" });
 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
+ * 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.
+ */
+let onNewWorkspace: ((root: string) => void) | undefined;
+
+export function setNewWorkspaceObserver(observer: ((root: string) => void) | undefined): void {
+	onNewWorkspace = observer;
+}
+
 export interface RetryingLectorClient {
 	call<Name extends OperationName>(operation: Name, input: OperationInputs[Name]): Promise<OperationOutputs[Name]>;
 }
@@ -64,6 +77,7 @@ async function workspaceForRoot(root: string): Promise<ResolvedWorkspace> {
 	const client = await lectorClient();
 	const { workspaceId } = await client.call("workspace.registerPath", { path: root });
 	workspaceIdByRoot.set(root, workspaceId);
+	onNewWorkspace?.(root);
 	return { workspaceId, root };
 }
 

package/extension/src/mutation-history-operations.ts

@@ -0,0 +1,34 @@
+import type { MutationHistoryEntry } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForPath } from "./lector-client.ts";
+import { toWorkspaceRelativePath } from "./workspace-relative-path.ts";
+
+/** Thin wrapper over Lector's mutation history: every successful edit is recorded, and any entry can be reverted -- guarded the same way every other Lector write is. */
+export interface MutationHistoryOperations {
+	list(absolutePath: string, maxResults: number): Promise<readonly MutationHistoryEntry[]>;
+	revert(absolutePath: string, entryId: string): Promise<{ path: string; newHash: string | null }>;
+}
+
+export function createMutationHistoryOperations(): MutationHistoryOperations {
+	return {
+		list(absolutePath, maxResults) {
+			return withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const path = toWorkspaceRelativePath(root, absolutePath);
+					const { entries } = await client.call("workspace.mutationHistory", { workspaceId, path, maxResults });
+					return entries;
+				},
+			);
+		},
+		revert(absolutePath, entryId) {
+			return withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.revertMutation", { workspaceId, entryId });
+				},
+			);
+		},
+	};
+}

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

@@ -0,0 +1,26 @@
+import type { OperationOutputs } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "./lector-client.ts";
+
+/**
+ * Thin wrapper over Lector's non-LSP reference-based rename: moves a file and rewrites every
+ * static import/export specifier the workspace's own populated symbol graph knows references it.
+ * `fromPath` resolves its own workspace (workspaceForCodeIntelligencePath -- this spawns a real
+ * language server), matching every other code-intelligence operation's convention.
+ */
+export interface ReferenceBasedRenameOperations {
+	rename(fromPath: string, toPath: string, maxFiles: number, maxSymbolsPerFile: number): Promise<OperationOutputs["workspace.referenceBasedRename"]>;
+}
+
+export function createReferenceBasedRenameOperations(): ReferenceBasedRenameOperations {
+	return {
+		async rename(fromPath, toPath, maxFiles, maxSymbolsPerFile) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(fromPath),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.referenceBasedRename", { workspaceId, fromPath, toPath, maxFiles, maxSymbolsPerFile });
+				},
+			);
+		},
+	};
+}

package/extension/src/rename-operations.ts

@@ -0,0 +1,36 @@
+import type { OperationOutputs } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "./lector-client.ts";
+
+/**
+ * Thin wrappers over Lector's LSP-driven prepareRename/rename -- position-based (path + 1-indexed
+ * line + character), matching every other code-intelligence operation's convention. `path`
+ * resolves its own workspace per call (workspaceForCodeIntelligencePath -- spawns a real
+ * language server).
+ */
+export interface RenameOperations {
+	prepareRename(path: string, line: number, character: number): Promise<OperationOutputs["workspace.prepareRename"]>;
+	rename(path: string, line: number, character: number, newName: string): Promise<OperationOutputs["workspace.rename"]>;
+}
+
+export function createRenameOperations(): RenameOperations {
+	return {
+		async prepareRename(path, line, character) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.prepareRename", { workspaceId, path, line, character });
+				},
+			);
+		},
+		async rename(path, line, character, newName) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.rename", { workspaceId, path, line, character, newName });
+				},
+			);
+		},
+	};
+}

package/extension/src/repo-cache-evict-operations.ts

@@ -0,0 +1,19 @@
+import { lectorClient } from "./lector-client.ts";
+
+/**
+ * Thin wrapper over repo.evictCache -- no `directory`/workspaceForDirectory resolution (matching
+ * repo-fetch-operations.ts and repo-cache-list-operations.ts: this targets the daemon-wide fetch
+ * cache, not a workspace-scoped concept).
+ */
+export interface RepoCacheEvictOperations {
+	evict(host: string, owner: string, repo: string, ref: string | null): Promise<{ evicted: boolean }>;
+}
+
+export function createRepoCacheEvictOperations(): RepoCacheEvictOperations {
+	return {
+		async evict(host, owner, repo, ref) {
+			const client = await lectorClient();
+			return client.call("repo.evictCache", { host, owner, repo, ref });
+		},
+	};
+}

package/extension/src/repo-cache-list-operations.ts

@@ -0,0 +1,24 @@
+import type { CachedRepositoryPage } from "@danypops/lector";
+import { lectorClient } from "./lector-client.ts";
+
+/**
+ * Thin wrapper over repo.listCache -- no network, no cache mutation, no `directory`/
+ * workspaceForDirectory resolution (matching repo-fetch-operations.ts: this queries the
+ * daemon-wide fetch cache, not a workspace-scoped concept).
+ */
+export interface RepoCacheListOperations {
+	list(
+		filters: { text?: string; host?: string; owner?: string; repo?: string; ref?: string },
+		maxResults: number,
+		cursor?: string,
+	): Promise<CachedRepositoryPage>;
+}
+
+export function createRepoCacheListOperations(): RepoCacheListOperations {
+	return {
+		async list(filters, maxResults, cursor) {
+			const client = await lectorClient();
+			return client.call("repo.listCache", { ...filters, maxResults, cursor });
+		},
+	};
+}

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

@@ -0,0 +1,42 @@
+import type { CachedRepositoryPage, RepoFetchResult } from "@danypops/lector";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+type RepoCacheAction = "fetch" | "list" | "evict";
+
+export function formatRepoCacheCall(
+	action: RepoCacheAction,
+	args: { owner?: unknown; repo?: unknown; ref?: unknown; host?: unknown; text?: unknown },
+	theme: LectorTheme,
+): string {
+	const label = theme.fg("toolTitle", theme.bold("repo_cache"));
+	if (action === "list") {
+		const filter = typeof args.text === "string" && args.text.length > 0 ? args.text : typeof args.repo === "string" ? args.repo : "";
+		return `${label} ${theme.fg("accent", "list")}${filter ? ` ${theme.fg("dim", filter)}` : ""}`;
+	}
+	const host = typeof args.host === "string" && args.host.length > 0 ? args.host : "github.com";
+	const owner = typeof args.owner === "string" ? args.owner : "";
+	const repo = typeof args.repo === "string" ? args.repo : "";
+	const ref = typeof args.ref === "string" ? `@${args.ref}` : "";
+	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", `${host}/${owner}/${repo}${ref}`)}`;
+}
+
+export function formatRepoFetchResult(result: (RepoFetchResult & { workspaceId: string }) | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	const lines = [
+		`${theme.fg("accent", result.workspaceId)} ${result.fromCache ? theme.fg("dim", "(from cache)") : theme.fg("toolTitle", "(fetched)")} -- ${result.path}`,
+	];
+	if (result.refFallbackOccurred) {
+		lines.push(theme.fg("warning", `requested ref not found; fell back to the default branch (resolved: ${result.resolvedRef})`));
+	}
+	return lines.join("\n");
+}
+
+export function formatRepoCacheListResult(page: CachedRepositoryPage | undefined, theme: LectorTheme): string {
+	const count = page?.entries.length ?? 0;
+	return count === 0 ? theme.fg("dim", "no cached repositories") : theme.fg("success", `${count} cached repositor${count === 1 ? "y" : "ies"}`);
+}
+
+export function formatRepoCacheEvictResult(result: { evicted: boolean } | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No result.");
+	return result.evicted ? theme.fg("success", "evicted") : theme.fg("dim", "nothing cached for that reference");
+}

package/extension/src/repo-fetch-operations.ts

@@ -7,14 +7,14 @@ import { lectorClient } from "./lector-client.ts";
  * creates a new registered workspace from a fetched external repo.
  */
 export interface RepoFetchOperations {
-	fetch(host: string, owner: string, repo: string, ref: string | null): Promise<RepoFetchResult & { workspaceId: string }>;
+	fetch(host: string, owner: string, repo: string, ref: string | null, forceRefresh?: boolean): Promise<RepoFetchResult & { workspaceId: string }>;
 }
 
 export function createLectorRepoFetchOperations(): RepoFetchOperations {
 	return {
-		async fetch(host, owner, repo, ref) {
+		async fetch(host, owner, repo, ref, forceRefresh) {
 			const client = await lectorClient();
-			return client.call("repo.fetch", { host, owner, repo, ref });
+			return client.call("repo.fetch", { host, owner, repo, ref, forceRefresh });
 		},
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -19,7 +19,7 @@
 	},
 	"dependencies": {
 		"@danypops/daemon-kit": "^0.22.1",
-		"@danypops/lector": "^0.3.0"
+		"@danypops/lector": "^0.6.0"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.81.1",

package/extension/src/repo-fetch-rendering.ts

@@ -1,21 +0,0 @@
-import type { RepoFetchResult } from "@danypops/lector";
-import type { LectorTheme } from "./lector-tui-theme.ts";
-
-export function formatRepoFetchCall(args: { owner?: unknown; repo?: unknown; ref?: unknown; host?: unknown }, theme: LectorTheme): string {
-	const host = typeof args.host === "string" && args.host.length > 0 ? args.host : "github.com";
-	const owner = typeof args.owner === "string" ? args.owner : "";
-	const repo = typeof args.repo === "string" ? args.repo : "";
-	const ref = typeof args.ref === "string" ? `@${args.ref}` : "";
-	return `${theme.fg("toolTitle", theme.bold("repo_fetch"))} ${theme.fg("accent", `${host}/${owner}/${repo}${ref}`)}`;
-}
-
-export function formatRepoFetchResult(result: (RepoFetchResult & { workspaceId: string }) | undefined, theme: LectorTheme): string {
-	if (!result) return theme.fg("dim", "No result.");
-	const lines = [
-		`${theme.fg("accent", result.workspaceId)} ${result.fromCache ? theme.fg("dim", "(from cache)") : theme.fg("toolTitle", "(fetched)")} -- ${result.path}`,
-	];
-	if (result.refFallbackOccurred) {
-		lines.push(theme.fg("warning", `requested ref not found; fell back to the default branch (resolved: ${result.resolvedRef})`));
-	}
-	return lines.join("\n");
-}