@danypops/pi-lector 0.13.5 → 0.13.7

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

@@ -50,9 +50,21 @@ export interface CodeIntelligenceOperations {
 	/** Never spawns a symbol index -- safe to call opportunistically (e.g. before deciding whether to enrich a result). */
 	hasWarmIndex(path: string): Promise<boolean>;
 	workspaceMap(path: string, maxNodes: number, maxEdges: number, maxEntries: number, maxBytes: number): Promise<OperationOutputs["workspace.map"]>;
+	localizeContext(
+		path: string,
+		query: string,
+		options?: {
+			seedSymbols?: readonly string[];
+			seedLocations?: readonly { path: string; line: number; character?: number }[];
+			maxSymbols?: number;
+			maxBytes?: number;
+			maxDepth?: number;
+			deadlineMs?: number;
+		},
+	): Promise<OperationOutputs["workspace.localizeContext"]>;
 }
 
-export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperations {
+export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIntelligenceOperations {
 	return {
 		async goToDefinition(path, line, character) {
 			return withWorkspace(
@@ -144,6 +156,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 						operation: "workspace.populateSymbolGraph",
 						input: { workspaceId, maxFiles, maxSymbolsPerFile },
 						waitMs,
+						...(ownerId ? { ownerId } : {}),
 					});
 					return job;
 				},
@@ -183,5 +196,14 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				},
 			);
 		},
+		async localizeContext(path, query, options = {}) {
+			return withWorkspace(
+				() => workspaceForPathOrDirectory(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.localizeContext", { workspaceId, query, ...options });
+				},
+			);
+		},
 	};
 }

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

@@ -92,7 +92,8 @@ export function formatSearchTextAcrossProjectsResult(
 				items: outcome.result.matches,
 				expanded,
 				visibleCount: DEFAULT_VISIBLE_PER_WORKSPACE,
-				formatItem: (match) => `  ${match.path}:${match.lineNumber}: ${match.line.replace(/\n$/, "")}`,
+				formatItem: (match) =>
+					`  ${match.path}:${match.lineNumber}: ${match.line.replace(/\n$/, "")}${match.lineTruncated ? theme.fg("warning", " (line truncated)") : ""}`,
 				moreLine: (hidden) => theme.fg("dim", `  ... ${hidden} more (${keyHint("app.tools.expand", "to expand")})`),
 				truncationWarning: outcome.result.truncated
 					? theme.fg("warning", "  (this workspace's search was itself truncated by maxMatches/maxBytes)")

package/extension/src/editor/index.ts

@@ -38,4 +38,10 @@ export { ExplorerComponent, type ExplorerResult, joinExplorerPath } from "./expl
 // exact, already-tested loop without re-deriving it, instead of only this package's own Pi
 // extension entry point being able to.
 export { type ExplorerFlowHost, runExplorerFlow } from "./explorer-flow.ts";
-export { ModalEditorComponent, type ModalEditorHost } from "./modal-editor-component.ts";
+export {
+	type EditorBufferSnapshot,
+	type EditorHoverOutcome,
+	type EditorHoverRequest,
+	ModalEditorComponent,
+	type ModalEditorHost,
+} from "./modal-editor-component.ts";

package/extension/src/editor/modal-editor-component.ts

@@ -1,6 +1,6 @@
 import { extname } from "node:path";
-import type { HighlightSpan } from "@danypops/lector";
-import { highlightSpans } from "@danypops/lector";
+import type { ContentHash, HighlightSpan } from "@danypops/lector";
+import { contentHashOf, highlightSpans } from "@danypops/lector";
 import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
@@ -10,12 +10,30 @@ import type { EditorTheme } from "./editor-theme.ts";
 
 export type { EditorTheme } from "./editor-theme.ts";
 
+export interface EditorBufferSnapshot {
+	readonly text: string;
+	readonly hash: ContentHash;
+	readonly dirty: boolean;
+}
+
+export interface EditorHoverRequest {
+	readonly line: number;
+	readonly character: number;
+	readonly buffer: EditorBufferSnapshot;
+}
+
+export type EditorHoverOutcome =
+	| { readonly kind: "ready"; readonly hover?: { readonly contents: string } }
+	| { readonly kind: "stale-active-buffer"; readonly bufferHash: ContentHash };
+
 export interface ModalEditorHost {
 	filePath: string;
 	/** Saves the buffer's current text through Lector's hash-guarded write. Throws (surfaced as a status message, not a crash) on a genuinely concurrent external change. */
 	save(text: string): Promise<void>;
-	/** Real hover info from Lector's existing code-intelligence operation, or undefined when there is none at this position. */
+	/** Resolves hover against the saved file for hosts that do not expose active-buffer semantics. */
 	hover(line: number, character: number): Promise<{ contents: string } | undefined>;
+	/** Resolves hover against the supplied active-buffer snapshot or reports that semantic evidence is stale. */
+	hoverSnapshot?(request: EditorHoverRequest): Promise<EditorHoverOutcome>;
 }
 
 const CAPTURE_COLOR: Record<string, ThemeColor> = {
@@ -111,9 +129,29 @@ export class ModalEditorComponent implements Component {
 				this.done();
 				return;
 			case "hover": {
-				const hover = await this.host.hover(this.state.cursorLine, this.state.cursorCharacter);
-				const firstLine = hover?.contents.split("\n")[0];
-				this.statusMessage = firstLine ?? "no hover info at this position";
+				const text = this.state.buffer.text;
+				const request = {
+					line: this.state.cursorLine,
+					character: this.state.cursorCharacter,
+					buffer: { text, hash: contentHashOf(text), dirty: this.state.dirty },
+				};
+				const outcome = this.host.hoverSnapshot
+					? await this.host.hoverSnapshot(request)
+					: { kind: "ready" as const, hover: await this.host.hover(request.line, request.character) };
+				switch (outcome.kind) {
+					case "ready": {
+						const firstLine = outcome.hover?.contents.split("\n")[0];
+						this.statusMessage = firstLine ?? "no hover info at this position";
+						break;
+					}
+					case "stale-active-buffer":
+						this.statusMessage = "stale active buffer: save or discard changes before semantic queries";
+						break;
+					default: {
+						const exhaustive: never = outcome;
+						throw new Error(`Unhandled hover outcome: ${JSON.stringify(exhaustive)}`);
+					}
+				}
 				break;
 			}
 			default: {

package/extension/src/index.ts

@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 import type {
 	CachedRepositoryPage,
 	ContentHash,
+	ContextBundleResult,
 	Diagnostic,
 	DocumentSymbolEntry,
 	EditOutcome,
@@ -38,10 +39,11 @@ import {
 	createWriteToolDefinition,
 	type ExtensionAPI,
 	type ExtensionCommandContext,
+	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { renderBoundedTable, type TextMeasure } from "malevich-tui-components";
-import { Type } from "typebox";
+import { type TSchema, 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 };
@@ -95,7 +97,8 @@ import { formatGitCall, formatGitResult, type GitToolDetails } from "./git/rende
 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 { createMutationHistoryOperations, type MutationTransactionRevertOutcome } from "./mutation-history/operations.ts";
+import { formatMutationHistoryList, formatMutationTransactionRevert } from "./mutation-history/rendering.ts";
 import { createLectorPackageSourceOperations, type PackageSourceListPage } from "./package-source/operations.ts";
 import {
 	buildPackageSourceListTableRows,
@@ -128,6 +131,7 @@ import { createLectorSearchOperations } from "./search/operations.ts";
 import { formatSearchCall, formatSearchResult } from "./search/rendering.ts";
 import { type AnnotationAnchorInput, createLectorSymbolAnnotationOperations } from "./symbol-annotation/operations.ts";
 import { formatAnnotationDetail, formatAnnotationListSummary, formatAnnotationSummary } from "./symbol-annotation/rendering.ts";
+import { boundLectorToolText } from "./tool-output-bounds.ts";
 import type { LectorVehicleCall } from "./vehicle-client.ts";
 import { CachingOverlay } from "./workspace-cache/caching-overlay.ts";
 import {
@@ -168,7 +172,23 @@ function renderIntelligenceSource(body: string, provenance: IntelligenceProvenan
  * "start it with `lector serve`" error if none is reachable.
  */
 export default function (pi: ExtensionAPI) {
-	const cacheOperations = createWorkspaceCacheOperations();
+	let cacheOperations = createWorkspaceCacheOperations();
+	// Registration is the ownership boundary: every custom Lector tool enters this set
+	// automatically, so future tools cannot silently bypass the final model-content cap.
+	// Built-in-compatible read/write/edit stay on Pi's own definitions and truncation path.
+	const customToolNames = new Set<string>();
+	function registerLectorTool<TParams extends TSchema, TDetails = unknown, TState = unknown>(tool: ToolDefinition<TParams, TDetails, TState>): void {
+		customToolNames.add(tool.name);
+		pi.registerTool(tool);
+	}
+	pi.on("tool_result", (event) => {
+		if (!customToolNames.has(event.toolName)) return;
+		const textBlocks = event.content.filter((block): block is Extract<(typeof event.content)[number], { type: "text" }> => block.type === "text");
+		if (textBlocks.length === 0) return;
+		const bounded = boundLectorToolText(textBlocks.map((block) => block.text).join("\n"));
+		if (!bounded.truncation) return;
+		return { content: [{ type: "text", text: bounded.text }, ...event.content.filter((block) => block.type !== "text")] };
+	});
 	// 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.
@@ -292,6 +312,8 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_start", (_event, ctx) => {
 		const { cwd } = ctx;
+		const ownerId = ctx.sessionManager.getSessionId();
+		cacheOperations = createWorkspaceCacheOperations(ownerId);
 		sessionGeneration++;
 		cacheStatesByRoot.clear();
 		monitoringRoots.clear();
@@ -299,9 +321,9 @@ export default function (pi: ExtensionAPI) {
 		uiContext = ctx;
 		setNewWorkspaceObserver((root) => startMonitoringRoot(root, ctx));
 		if (ctx.hasUI) {
-			// The persistent widget counterpart to the single-line "lector-cache" status above --
-			// enumerates EVERY workspace currently caching, not just this session's own cwd root.
-			cachingOverlay ??= new CachingOverlay();
+			// The persistent widget counterpart to the single-line "lector-cache" status above.
+			// Ownership is the Pi session, not cwd: one session may legitimately touch several roots.
+			cachingOverlay = new CachingOverlay(undefined, ownerId);
 			cachingOverlay.setUI(ctx.ui);
 			void cachingOverlay.refresh();
 			cachingOverlay.startPolling();
@@ -323,7 +345,7 @@ export default function (pi: ExtensionAPI) {
 		pi.registerTool(createEditToolDefinition(cwd, { operations: createLectorEditOperations() }));
 
 		const findSymbolsOperations = createLectorFindSymbolsOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "find_symbols",
 			label: "Find Symbols",
 			description:
@@ -385,7 +407,75 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		const codeIntelligenceOperations = createLectorCodeIntelligenceOperations();
+		const codeIntelligenceOperations = createLectorCodeIntelligenceOperations(ownerId);
+
+		registerLectorTool({
+			name: "localize_context",
+			label: "Localize Context",
+			description:
+				"Localize a natural-language coding task to a bounded, ranked set of workspace symbols. Combines lexical source matches with the persisted call/reference/containment graph, returns compact signatures and explicit score reasons, and reports incomplete or unavailable graph coverage. The daemon does not invoke an LLM. `directory` selects the project explicitly.",
+			promptSnippet: "Localize a coding task to ranked symbols and compact graph-backed context",
+			promptGuidelines: [
+				"Use localize_context near the start of an unfamiliar implementation or debugging task to get a bounded candidate set before reading files one by one.",
+				"Treat every reason as provenance for a retrieval signal, not proof of semantic dataflow; inspect completeness before relying on graph omissions.",
+			],
+			parameters: Type.Object({
+				query: Type.String({ description: "Natural-language coding task or issue text" }),
+				directory: Type.String({ description: "Directory of the project to localize, absolute or relative to the current working directory" }),
+				seedSymbols: Type.Optional(Type.Array(Type.String(), { description: "Optional exact symbol names that anchor graph expansion", maxItems: 100 })),
+				seedLocations: Type.Optional(
+					Type.Array(
+						Type.Object({
+							path: Type.String(),
+							line: Type.Number({ description: "1-indexed line" }),
+							character: Type.Optional(Type.Number({ description: "Optional 1-indexed declaration character" })),
+						}),
+						{ description: "Optional declaration locations that anchor graph expansion", maxItems: 100 },
+					),
+				),
+				maxSymbols: Type.Optional(Type.Number({ description: "Maximum candidates returned (default 20, maximum 500)" })),
+				maxBytes: Type.Optional(Type.Number({ description: "Maximum serialized candidate bytes (default 30000, maximum 2 MiB)" })),
+				maxDepth: Type.Optional(Type.Number({ description: "Maximum call/reference/containment expansion depth (default 2, maximum 5)" })),
+				deadlineMs: Type.Optional(Type.Number({ description: "Wall-clock budget in milliseconds (default 5000, maximum 30000)" })),
+			}),
+			async execute(_toolCallId, params) {
+				const directory = resolve(cwd, params.directory);
+				const result = await codeIntelligenceOperations.localizeContext(directory, params.query, {
+					...(params.seedSymbols ? { seedSymbols: params.seedSymbols } : {}),
+					...(params.seedLocations ? { seedLocations: params.seedLocations.map((seed) => ({ ...seed, path: resolve(cwd, seed.path) })) } : {}),
+					...(params.maxSymbols !== undefined ? { maxSymbols: params.maxSymbols } : {}),
+					...(params.maxBytes !== undefined ? { maxBytes: params.maxBytes } : {}),
+					...(params.maxDepth !== undefined ? { maxDepth: params.maxDepth } : {}),
+					...(params.deadlineMs !== undefined ? { deadlineMs: params.deadlineMs } : {}),
+				});
+				const completeness = `lexical=${result.completeness.lexical}, graph=${result.completeness.graph}${result.completeness.deadlineReached ? ", deadline reached" : ""}${result.truncated ? ", truncated" : ""}`;
+				const text =
+					result.candidates.length === 0
+						? `No localization candidates.\nCompleteness: ${completeness}`
+						: `Primary candidates\n\n${result.candidates
+								.map(
+									(candidate, index) =>
+										`${index + 1}. ${candidate.name}\n   ${candidate.path}:${candidate.line}:${candidate.character}\n   ${candidate.signature ?? candidate.kind}\n   Reasons:\n${candidate.reasons.map((reason) => `   - ${reason.detail} (+${reason.score})`).join("\n")}`,
+								)
+								.join("\n\n")}\n\nCompleteness: ${completeness}`;
+				return { content: [{ type: "text", text }], details: result };
+			},
+			renderCall(args, theme) {
+				return new Text(theme.fg("toolTitle", `localize ${typeof args.query === "string" ? args.query : "context"}`), 0, 0);
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Localizing..."), 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 || "localize_context failed"), 0, 0);
+				}
+				const details = result.details as ContextBundleResult | undefined;
+				return new Text(details ? `${details.candidates.length} candidates · graph ${details.completeness.graph}` : "Localization complete", 0, 0);
+			},
+		});
 
 		const editorOverlayOptions = { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "center" } } as const;
 
@@ -406,6 +496,11 @@ export default function (pi: ExtensionAPI) {
 						const result = await codeIntelligenceOperations.hover(absolutePath, line, character);
 						return result.hover;
 					},
+					hoverSnapshot: async (request) => {
+						if (request.buffer.dirty) return { kind: "stale-active-buffer", bufferHash: request.buffer.hash };
+						const result = await codeIntelligenceOperations.hover(absolutePath, request.line, request.character);
+						return { kind: "ready", hover: result.hover };
+					},
 				};
 				return new ModalEditorComponent(tui, theme, host, session.content, () => done(undefined));
 			}, editorOverlayOptions);
@@ -451,7 +546,7 @@ export default function (pi: ExtensionAPI) {
 			character: Type.Number({ description: "1-indexed character offset within the line" }),
 		};
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "go_to_definition",
 			label: "Go to Definition",
 			description: "Find where the symbol at an exact file position is actually declared, across files, through re-exports and aliasing.",
@@ -485,7 +580,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "go_to_implementation",
 			label: "Go to Implementation",
 			description:
@@ -523,7 +618,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "find_references",
 			label: "Find References",
 			description: "Find every project-wide usage of the symbol at an exact file position.",
@@ -568,7 +663,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "hover",
 			label: "Hover",
 			description: "Get type and documentation information for the symbol at an exact file position.",
@@ -608,7 +703,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "document_symbols",
 			label: "Document Symbols",
 			description: "List every symbol declared in one file, hierarchically -- an outline of its classes, functions, and their members.",
@@ -642,7 +737,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "diagnostics",
 			label: "Diagnostics",
 			description: "List every error and warning a language server currently knows about for one file, as of its last analysis.",
@@ -679,7 +774,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "call_hierarchy",
 			label: "Call Hierarchy",
 			description:
@@ -745,7 +840,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "reference_based_rename",
 			label: "Reference-Based Rename",
 			description:
@@ -808,7 +903,7 @@ export default function (pi: ExtensionAPI) {
 			applied?: OperationOutputs["workspace.rename"];
 		}
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "rename",
 			label: "Rename",
 			description:
@@ -877,7 +972,7 @@ export default function (pi: ExtensionAPI) {
 			uncontained?: boolean;
 		}
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "symbol_annotations",
 			label: "Symbol Annotations",
 			description:
@@ -1056,7 +1151,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "reachable_from",
 			label: "Reachable From",
 			description:
@@ -1105,7 +1200,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "workspace_map",
 			label: "Workspace Map",
 			description:
@@ -1125,14 +1220,16 @@ export default function (pi: ExtensionAPI) {
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
 				const result = await codeIntelligenceOperations.workspaceMap(path, params.maxNodes, params.maxEdges, params.maxEntries, params.maxBytes);
-				const text =
+				const coverage = `Candidate coverage: languages=${result.candidateSelection.representedLanguages.join(",") || "none"}; scopes=${result.candidateSelection.representedScopes.join(",") || "none"}${result.candidateSelection.omittedScopes.length > 0 ? `; omitted=${result.candidateSelection.omittedScopes.join(",")}` : ""}; strategy=${result.candidateSelection.strategy}.`;
+				const text = `${
 					result.entries.length === 0
 						? "No ranked symbols (the workspace's symbol graph may still be populating in the background -- retry shortly)."
 						: result.entries
 								.map(
 									(entry) => `${entry.kind} ${entry.name} -- ${entry.path}:${entry.line}:${entry.character}${entry.signature ? ` -- ${entry.signature}` : ""}`,
 								)
-								.join("\n");
+								.join("\n")
+				}\n${coverage}`;
 				return { content: [{ type: "text", text }], details: { result } };
 			},
 			renderCall(args, theme, context) {
@@ -1162,7 +1259,7 @@ export default function (pi: ExtensionAPI) {
 			readonly job?: JobSnapshot<PopulateSymbolGraphResult>;
 		}
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "workspace_cache",
 			label: "Workspace Cache",
 			description:
@@ -1253,7 +1350,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const gitOperations = createLectorGitOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "git",
 			label: "Git",
 			description:
@@ -1396,7 +1493,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const searchOperations = createLectorSearchOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "search_code",
 			label: "Search Code",
 			description:
@@ -1437,7 +1534,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const findFilesOperations = createLectorFindFilesOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "find_files",
 			label: "Find Files",
 			description:
@@ -1483,7 +1580,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const lineEditOperations = createLectorLineEditOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "line_edit",
 			label: "Line Edit",
 			description:
@@ -1554,7 +1651,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const applyPatchOperations = createLectorApplyPatchOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "apply_patch",
 			label: "Apply Patch",
 			description:
@@ -1602,23 +1699,25 @@ 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 } };
+			| { readonly action: "revert"; readonly reverted: { readonly path: string; readonly newHash: string | null } }
+			| { readonly action: "revert-transaction"; readonly reverted: MutationTransactionRevertOutcome };
 
 		const mutationHistoryOperations = createMutationHistoryOperations();
-		pi.registerTool({
+		registerLectorTool({
 			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",
+				"List a file's recorded edit history, revert a standalone entry, or atomically revert every file in a rename/multi-file transaction. Every successful edit/line_edit/apply_patch is recorded (newest first, bounded, not durable across a daemon restart). Reverts are hash-guarded and further-revertible. A transaction member is never reverted alone: use action=revert-transaction with its transactionId.",
+			promptSnippet: "List or safely revert standalone or transaction-grouped 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.",
+				"list first. Use action=revert only for a standalone entry; if list reports a transactionId, use action=revert-transaction so every member is restored atomically.",
 			],
 			parameters: Type.Object({
-				action: Type.Union([Type.Literal("list"), Type.Literal("revert")]),
-				path: Type.String({ description: "Absolute or workspace-relative path to the file" }),
+				action: Type.Union([Type.Literal("list"), Type.Literal("revert"), Type.Literal("revert-transaction")]),
+				path: Type.String({ description: "Absolute or workspace-relative path used to resolve the owning workspace" }),
 				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" })),
+				entryId: Type.Optional(Type.String({ description: "Required for action=revert -- a standalone entry id returned by list" })),
+				transactionId: Type.Optional(Type.String({ description: "Required for action=revert-transaction -- a transaction id returned by list" })),
 			}),
 			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<MutationHistoryToolDetails>> {
 				const absolutePath = resolve(cwd, params.path);
@@ -1631,17 +1730,21 @@ export default function (pi: ExtensionAPI) {
 				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, vehicleCall);
-					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, vehicleCall);
+					return { content: [{ type: "text", text: formatMutationHistoryList(entries) }], details: { action: "list", entries } };
+				}
+				if (params.action === "revert") {
+					if (params.entryId === undefined) throw new Error("mutation_history action=revert requires entryId");
+					const reverted = await mutationHistoryOperations.revert(absolutePath, params.entryId, vehicleCall);
+					return {
+						content: [{ type: "text", text: `${reverted.path} reverted -> ${reverted.newHash ?? "(deleted)"}` }],
+						details: { action: "revert", reverted },
+					};
+				}
+				if (params.transactionId === undefined) throw new Error("mutation_history action=revert-transaction requires transactionId");
+				const reverted = await mutationHistoryOperations.revertTransaction(absolutePath, params.transactionId, vehicleCall);
 				return {
-					content: [{ type: "text", text: `${reverted.path} reverted -> ${reverted.newHash ?? "(deleted)"}` }],
-					details: { action: "revert", reverted },
+					content: [{ type: "text", text: formatMutationTransactionRevert(params.transactionId, reverted) }],
+					details: { action: "revert-transaction", reverted },
 				};
 			},
 			renderCall(args, theme, context) {
@@ -1690,21 +1793,26 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		const packageSourceOperations = createLectorPackageSourceOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "package_source",
 			label: "Package Source",
 			description:
-				"Resolve, list, remove, or clean bookkeeping for installed npm packages resolved to verified exact repository source. action=resolve uses the project's lockfile, bounded registry metadata, and an exact Git ref/commit; registers verified source as a read-only workspace for the other Lector tools. action=list reports every package coordinate already resolved this way -- no re-resolution, no network. action=remove drops one bookkeeping entry by its exact ecosystem/name/resolvedVersion; refuses if it is still a currently-registered workspace. action=clean removes every non-in-use entry, optionally scoped to one ecosystem. Neither remove nor clean deletes the underlying repo_cache disk entry -- use repo_cache(action=evict) for that, since a monorepo can share one checkout across several package coordinates.",
+				"Resolve, list, remove, or clean bookkeeping for installed packages (npm, pypi, ...) resolved to verified exact repository source. action=resolve uses the project's own lockfile-family, bounded registry metadata, and an exact Git ref/commit (or, for an editable/direct-VCS/local install, the already-known source directly, no registry lookup needed); registers verified source as a read-only workspace for the other Lector tools. action=list reports every package coordinate already resolved this way -- no re-resolution, no network. action=remove drops one bookkeeping entry by its exact ecosystem/name/resolvedVersion; refuses if it is still a currently-registered workspace. action=clean removes every non-in-use entry, optionally scoped to one ecosystem. Neither remove nor clean deletes the underlying repo_cache disk entry -- use repo_cache(action=evict) for that, since a monorepo can share one checkout across several package coordinates.",
 			promptSnippet: "Resolve, list, remove, or clean verified package source bookkeeping",
 			parameters: Type.Object({
 				action: Type.Optional(Type.Union([Type.Literal("resolve"), Type.Literal("list"), Type.Literal("remove"), Type.Literal("clean")])),
-				directory: Type.Optional(Type.String({ description: "Required for action=resolve -- project directory containing the npm-family lockfile" })),
+				directory: Type.Optional(Type.String({ description: "Required for action=resolve -- project directory containing the package's own lockfile-family" })),
 				name: Type.Optional(Type.String({ description: "Required for action=resolve/remove -- installed package name, including scope when present" })),
 				version: Type.Optional(
 					Type.String({ description: "action=resolve only -- exact installed version; required when the lockfile contains several versions" }),
 				),
-				registry: Type.Optional(Type.String({ description: "npm registry URL; defaults to the public npm registry" })),
-				ecosystem: Type.Optional(Type.String({ description: "Required for action=remove; optional filter for action=list/clean" })),
+				registry: Type.Optional(Type.String({ description: "Registry URL; defaults to the ecosystem's own public registry (npm registry / pypi.org)" })),
+				ecosystem: Type.Optional(
+					Type.String({
+						description:
+							"npm/pypi/cargo/go/maven/conan/vcpkg/nuget/swiftpm -- action=resolve defaults to npm; required for action=remove; optional filter for action=list/clean",
+					}),
+				),
 				resolvedVersion: Type.Optional(Type.String({ description: "Required for action=remove -- the exact resolved version to remove" })),
 				text: Type.Optional(Type.String({ description: "action=list only -- case-insensitive substring match across ecosystem/name/resolvedVersion" })),
 				maxResults: Type.Optional(Type.Number({ description: "Required for action=list -- maximum entries to return in this page" })),
@@ -1737,7 +1845,13 @@ export default function (pi: ExtensionAPI) {
 				}
 				if (!params.directory || !params.name) throw new Error("package_source action=resolve requires directory and name");
 				const directory = resolve(cwd, params.directory);
-				const result = await packageSourceOperations.resolve(directory, params.name, params.version ?? null, params.registry ?? null);
+				const result = await packageSourceOperations.resolve(
+					directory,
+					params.name,
+					params.version ?? null,
+					params.registry ?? null,
+					optionalPackageEcosystem(params.ecosystem),
+				);
 				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "resolve", result } };
 			},
 			renderCall(args, theme, context) {
@@ -1796,7 +1910,7 @@ export default function (pi: ExtensionAPI) {
 		const repoFetchOperations = createLectorRepoFetchOperations();
 		const repoCacheListOperations = createRepoCacheListOperations();
 		const repoCacheEvictOperations = createRepoCacheEvictOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "repo_cache",
 			label: "Repo Cache",
 			description:
@@ -1899,7 +2013,7 @@ export default function (pi: ExtensionAPI) {
 			| { readonly action: "sourcegraph_code"; readonly result: { candidates: readonly SourcegraphCodeCandidate[] } };
 
 		const externalSearchOperations = createExternalSearchOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "external_search",
 			label: "External Search",
 			description:
@@ -1956,7 +2070,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const crossWorkspaceSearchOperations = createLectorCrossWorkspaceSearchOperations();
-		pi.registerTool({
+		registerLectorTool({
 			name: "find_symbols_across_projects",
 			label: "Find Symbols Across Projects",
 			description:
@@ -1996,7 +2110,7 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
-		pi.registerTool({
+		registerLectorTool({
 			name: "search_code_across_projects",
 			label: "Search Code Across Projects",
 			description:

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

@@ -3,6 +3,13 @@ import { withWorkspace, workspaceForPath } from "../lector-client.ts";
 import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
 import { toWorkspaceRelativePath } from "../workspace-relative-path.ts";
 
+const MAX_INTERNAL_HISTORY_LOOKUP_RESULTS = 2_000;
+
+export interface MutationTransactionRevertOutcome {
+	readonly transactionId: string;
+	readonly reverted: readonly { readonly path: string; readonly newHash: string | null }[];
+}
+
 /** Match MUTATION_HISTORY_READ_PERMISSIONS/MUTATION_HISTORY_WRITE_PERMISSIONS' own declared values server-side (mutation-history/operation-registration.ts). */
 const MUTATION_HISTORY_READ_PERMISSIONS = ["workspace:read"];
 const MUTATION_HISTORY_WRITE_PERMISSIONS = ["workspace:write"];
@@ -15,32 +22,72 @@ const MUTATION_HISTORY_WRITE_PERMISSIONS = ["workspace:write"];
 export interface MutationHistoryOperations {
 	list(absolutePath: string, maxResults: number, call: LectorVehicleCall): Promise<readonly MutationHistoryEntry[]>;
 	revert(absolutePath: string, entryId: string, call: LectorVehicleCall): Promise<{ path: string; newHash: string | null }>;
+	revertTransaction(absolutePath: string, transactionId: string, call: LectorVehicleCall): Promise<MutationTransactionRevertOutcome>;
+}
+
+async function listResolvedHistory(
+	workspaceId: string,
+	root: string,
+	absolutePath: string,
+	maxResults: number,
+	call: LectorVehicleCall,
+): Promise<readonly MutationHistoryEntry[]> {
+	const relativePath = toWorkspaceRelativePath(root, absolutePath);
+	// Single-file edits historically record the caller's workspace-relative path, while LSP
+	// WorkspaceEdits record canonical absolute paths. Query both identities until the daemon's
+	// stored-history migration can normalize old entries, then deduplicate by immutable entry id.
+	const paths = relativePath === absolutePath ? [absolutePath] : [relativePath, absolutePath];
+	const pages = await Promise.all(
+		paths.map((path) =>
+			invokeLectorVehicleOperation<{ entries: readonly MutationHistoryEntry[] }>(
+				"workspace.mutationHistory",
+				{ workspaceId, path, maxResults },
+				MUTATION_HISTORY_READ_PERMISSIONS,
+				call,
+			),
+		),
+	);
+	const byId = new Map<string, MutationHistoryEntry>();
+	for (const page of pages) for (const entry of page.entries) byId.set(entry.id, entry);
+	return [...byId.values()].sort((a, b) => b.timestamp - a.timestamp).slice(0, maxResults);
 }
 
 export function createMutationHistoryOperations(): MutationHistoryOperations {
 	return {
 		list(absolutePath, maxResults, call) {
+			return withWorkspace(
+				() => workspaceForPath(absolutePath),
+				({ workspaceId, root }) => listResolvedHistory(workspaceId, root, absolutePath, maxResults, call),
+			);
+		},
+		revert(absolutePath, entryId, call) {
 			return withWorkspace(
 				() => workspaceForPath(absolutePath),
 				async ({ workspaceId, root }) => {
-					const path = toWorkspaceRelativePath(root, absolutePath);
-					const { entries } = await invokeLectorVehicleOperation<{ entries: readonly MutationHistoryEntry[] }>(
-						"workspace.mutationHistory",
-						{ workspaceId, path, maxResults },
-						MUTATION_HISTORY_READ_PERMISSIONS,
+					const entries = await listResolvedHistory(workspaceId, root, absolutePath, MAX_INTERNAL_HISTORY_LOOKUP_RESULTS, call);
+					const target = entries.find((entry) => entry.id === entryId);
+					if (!target) throw new Error(`mutation history entry "${entryId}" is not recorded for "${absolutePath}" -- list that path again before reverting`);
+					if (target.transactionId !== null) {
+						throw new Error(
+							`mutation history entry "${entryId}" belongs to multi-file transaction "${target.transactionId}" -- refusing a partial revert; use action=revert-transaction with transactionId`,
+						);
+					}
+					return invokeLectorVehicleOperation<{ path: string; newHash: string | null }>(
+						"workspace.revertMutation",
+						{ workspaceId, entryId },
+						MUTATION_HISTORY_WRITE_PERMISSIONS,
 						call,
 					);
-					return entries;
 				},
 			);
 		},
-		revert(absolutePath, entryId, call) {
+		revertTransaction(absolutePath, transactionId, call) {
 			return withWorkspace(
 				() => workspaceForPath(absolutePath),
 				({ workspaceId }) =>
-					invokeLectorVehicleOperation<{ path: string; newHash: string | null }>(
-						"workspace.revertMutation",
-						{ workspaceId, entryId },
+					invokeLectorVehicleOperation<MutationTransactionRevertOutcome>(
+						"workspace.revertMutationTransaction",
+						{ workspaceId, transactionId },
 						MUTATION_HISTORY_WRITE_PERMISSIONS,
 						call,
 					),

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

@@ -0,0 +1,20 @@
+import type { MutationHistoryEntry } from "@danypops/lector";
+import type { MutationTransactionRevertOutcome } from "./operations.ts";
+
+export function formatMutationHistoryList(entries: readonly MutationHistoryEntry[]): string {
+	if (entries.length === 0) return "no recorded mutation history for this path";
+	return entries
+		.map((entry) => {
+			const grouping = entry.transactionId === null ? "standalone mutation" : `transaction ${entry.transactionId}`;
+			return `${entry.id}  ${new Date(entry.timestamp).toISOString()}  ${entry.operation}  ${grouping}`;
+		})
+		.join("\n");
+}
+
+export function formatMutationTransactionRevert(originalTransactionId: string, outcome: MutationTransactionRevertOutcome): string {
+	const lines = [
+		`${originalTransactionId} reverted atomically; revert recorded as transaction ${outcome.transactionId}`,
+		...outcome.reverted.map((entry) => `${entry.path} -> ${entry.newHash ?? "(deleted)"}`),
+	];
+	return lines.join("\n");
+}

package/extension/src/package-source/operations.ts

@@ -7,7 +7,13 @@ export interface PackageSourceListPage {
 }
 
 export interface PackageSourceOperations {
-	resolve(directory: string, name: string, requestedVersion: string | null, registry: string | null): Promise<PackageSourceOperationResult>;
+	resolve(
+		directory: string,
+		name: string,
+		requestedVersion: string | null,
+		registry: string | null,
+		ecosystem?: PackageEcosystem,
+	): Promise<PackageSourceOperationResult>;
 	list(options: { ecosystem?: PackageEcosystem; text?: string; maxResults: number; cursor?: string }): Promise<PackageSourceListPage>;
 	remove(ecosystem: PackageEcosystem, registry: string | null, name: string, resolvedVersion: string): Promise<{ removed: boolean }>;
 	clean(ecosystem: PackageEcosystem | undefined): Promise<{ removed: number; skipped: number }>;
@@ -15,12 +21,12 @@ export interface PackageSourceOperations {
 
 export function createLectorPackageSourceOperations(): PackageSourceOperations {
 	return {
-		async resolve(directory, name, requestedVersion, registry) {
+		async resolve(directory, name, requestedVersion, registry, ecosystem = "npm") {
 			const client = await lectorClient();
 			return client.callOnce("package.resolveSource", {
 				request: {
 					projectRoot: directory,
-					coordinate: { ecosystem: "npm", registry, name, requestedVersion },
+					coordinate: { ecosystem, registry, name, requestedVersion },
 				},
 				bounds: DEFAULT_PACKAGE_SOURCE_BOUNDS,
 			});

package/extension/src/search/rendering.ts

@@ -17,7 +17,8 @@ export function formatSearchResult(result: TextSearchResult | undefined, expande
 		items: result.matches,
 		expanded,
 		visibleCount: DEFAULT_VISIBLE_MATCHES,
-		formatItem: (match) => `${theme.fg("accent", match.path)}:${match.lineNumber}: ${match.line.replace(/\n$/, "")}`,
+		formatItem: (match) =>
+			`${theme.fg("accent", match.path)}:${match.lineNumber}: ${match.line.replace(/\n$/, "")}${match.lineTruncated ? theme.fg("warning", " (line truncated)") : ""}`,
 		moreLine: (hidden) => theme.fg("dim", `... ${hidden} more (${keyHint("app.tools.expand", "to expand")})`),
 		truncationWarning: result.truncated ? theme.fg("warning", "(search itself was truncated by maxMatches/maxBytes -- results are incomplete)") : undefined,
 	});

package/extension/src/tool-output-bounds.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from "@earendil-works/pi-coding-agent";
+
+export interface BoundedLectorToolText {
+	readonly text: string;
+	readonly truncation: TruncationResult | undefined;
+}
+
+function noticeFor(truncation: TruncationResult): string {
+	return (
+		`[Lector tool output truncated: ${truncation.totalLines} lines total, ${formatSize(truncation.totalBytes)} total; ` +
+		`showing ${truncation.outputLines} lines and ${formatSize(truncation.outputBytes)}. Refine the query or lower its scope.]`
+	);
+}
+
+/**
+ * Applies Pi's process-level custom-tool output contract independently of Lector's domain bounds.
+ * Domain maxBytes values intentionally describe DTO payload fields, not the final serialized tool
+ * message; this final guard accounts for separators, provenance, JSON framing, and caller-selected
+ * bounds before content enters model context.
+ */
+export function boundLectorToolText(text: string): BoundedLectorToolText {
+	const initial = truncateHead(text);
+	if (!initial.truncated) return { text, truncation: undefined };
+
+	let bounded = initial;
+	for (let attempt = 0; attempt < 3; attempt++) {
+		const notice = noticeFor(bounded);
+		const noticeBytes = Buffer.byteLength(`\n\n${notice}`, "utf8");
+		bounded = truncateHead(text, {
+			maxLines: Math.max(1, DEFAULT_MAX_LINES - 2),
+			maxBytes: Math.max(1, DEFAULT_MAX_BYTES - noticeBytes),
+		});
+	}
+	const notice = noticeFor(bounded);
+	return { text: bounded.content ? `${bounded.content}\n\n${notice}` : notice, truncation: bounded };
+}

package/extension/src/workspace-cache/caching-overlay.ts

@@ -4,8 +4,8 @@
  * DoctorOverlay: factory-form ctx.ui.setWidget registration, requestRender on refresh, hides the
  * widget entirely (setWidget(key, undefined)) rather than an empty box once nothing is caching.
  *
- * workspace.activeCachingJobs enumerates every workspace with a currently active (queued/
- * running) population job -- see packages/lector/src/service/symbol-graph/cache-query-handlers.ts.
+ * workspace.activeCachingJobs is filtered by the owning Pi session, while its omitted-owner
+ * daemon contract remains available for global administration -- see cache-query-handlers.ts.
  */
 import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { TUI } from "@earendil-works/pi-tui";
@@ -39,7 +39,10 @@ export class CachingOverlay {
 		intervalMs: CACHING_WIDGET_ROTATION_INTERVAL_MS,
 	});
 
-	constructor(private readonly connect: () => Promise<RetryingLectorClient> = lectorClient) {}
+	constructor(
+		private readonly connect: () => Promise<RetryingLectorClient> = lectorClient,
+		private readonly ownerId?: string,
+	) {}
 
 	setUI(ctx: ExtensionUIContext): void {
 		if (ctx !== this.uiCtx) {
@@ -55,7 +58,7 @@ export class CachingOverlay {
 	async refresh(): Promise<void> {
 		try {
 			const client = await this.connect();
-			const result = await client.call("workspace.activeCachingJobs", {});
+			const result = await client.call("workspace.activeCachingJobs", this.ownerId ? { ownerId: this.ownerId } : {});
 			this.projection = buildCachingWidgetProjection(result.jobs);
 		} catch {
 			this.projection = EMPTY_PROJECTION;

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

@@ -39,7 +39,7 @@ export interface WorkspaceCacheOperations {
 	watchJob?(jobId: string, onJob: (job: JobSnapshot<PopulateSymbolGraphResult>) => void): Promise<JobWatchOutcome>;
 }
 
-export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
+export function createWorkspaceCacheOperations(ownerId?: string): WorkspaceCacheOperations {
 	return {
 		status(directory, maxFiles, maxSymbolsPerFile) {
 			return withWorkspace(
@@ -59,6 +59,7 @@ export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
 						operation: "workspace.populateSymbolGraph",
 						input: { workspaceId, maxFiles, maxSymbolsPerFile, retryTimeBudgetMs },
 						waitMs,
+						...(ownerId ? { ownerId } : {}),
 					});
 					return job;
 				},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.13.5",
+	"version": "0.13.7",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -22,17 +22,19 @@
 		"@danypops/vehicle-client-pi": "^0.45.0"
 	},
 	"dependencies": {
-		"@danypops/lector": "^0.19.9",
+		"@danypops/lector": "^0.20.0",
 		"@danypops/vehicle-client": "^0.10.3",
 		"@danypops/vehicle-core": "^0.17.1",
 		"malevich-tui-components": "^0.32.1",
 		"picomatch": "^4.0.5"
 	},
 	"devDependencies": {
-		"@danypops/vehicle-client-pi": "^0.45.0",
-		"@danypops/vehicle-conformance": "^0.4.0",
+		"@danypops/pi-eval-harness": "^0.1.0",
 		"@danypops/pi-extension-harness": "^0.2.0",
+		"@danypops/pi-process-harness": "^0.1.3",
 		"@danypops/pi-tui-harness": "^0.0.1",
+		"@danypops/vehicle-client-pi": "^0.45.0",
+		"@danypops/vehicle-conformance": "^0.4.0",
 		"@earendil-works/pi-ai": "^0.81.1",
 		"@earendil-works/pi-coding-agent": "^0.81.1",
 		"@earendil-works/pi-tui": "^0.81.1",