@danypops/pi-lector 0.13.6 → 0.13.9

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

@@ -50,6 +50,18 @@ 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(ownerId?: string): CodeIntelligenceOperations {
@@ -184,5 +196,14 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 				},
 			);
 		},
+		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/explorer-component.ts

@@ -9,7 +9,14 @@ import type { EditorTheme } from "./editor-theme.ts";
 import type { ExplorerDiff, ExplorerEntry } from "./explorer-diff.ts";
 import { diffExplorerLines, formatExplorerLine, parseExplorerLine } from "./explorer-diff.ts";
 
-export type ExplorerResult = { kind: "quit" } | { kind: "open-file"; absolutePath: string };
+/** Restores one Workspace's directory and active entry when its Explorer becomes visible again. */
+export interface ExplorerViewState {
+	readonly relativePath: string;
+	readonly selectedEntryName?: string;
+}
+
+/** Reports why the Explorer closed plus its latest restorable location when the host supports view-state persistence. */
+export type ExplorerResult = { kind: "quit"; viewState?: ExplorerViewState } | { kind: "open-file"; absolutePath: string; viewState?: ExplorerViewState };
 
 /** Joins a directory-relative name onto `directory` ("" means the resolved root itself). */
 export function joinExplorerPath(directory: string, name: string): string {
@@ -51,12 +58,19 @@ export class ExplorerComponent implements Component {
 	private statusMessage = "";
 	private confirming: PendingConfirmation | undefined;
 
-	constructor(tui: TUI, theme: EditorTheme, session: DirectoryExplorerSession, initialRelativePath: string, done: (result: ExplorerResult) => void) {
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		session: DirectoryExplorerSession,
+		initialRelativePath: string,
+		done: (result: ExplorerResult) => void,
+		initialSelectedEntryName?: string,
+	) {
 		this.tui = tui;
 		this.theme = theme;
 		this.session = session;
 		this.done = done;
-		this.pending = this.loadDirectory(initialRelativePath).catch((error: unknown) => this.reportError(error));
+		this.pending = this.loadDirectory(initialRelativePath, initialSelectedEntryName).catch((error: unknown) => this.reportError(error));
 	}
 
 	private pending: Promise<void> = Promise.resolve();
@@ -111,13 +125,20 @@ export class ExplorerComponent implements Component {
 		this.tui.requestRender();
 	}
 
-	private async loadDirectory(relativePath: string): Promise<void> {
+	private async loadDirectory(relativePath: string, selectedEntryName?: string): Promise<void> {
 		const listing = await this.session.listDirectory(relativePath);
 		this.currentPath = relativePath;
 		this.nextId = 1;
 		this.entries = listing.entries.map((entry) => ({ id: this.nextId++, name: entry.name, kind: entry.kind }));
 		const text = this.entries.length > 0 ? this.entries.map((entry) => formatExplorerLine(entry)).join("\n") : "";
 		this.state = new EditorState(text);
+		const selectedIndex = selectedEntryName === undefined ? -1 : this.entries.findIndex((entry) => entry.name === selectedEntryName);
+		const selectedEntry = selectedIndex >= 0 ? this.entries[selectedIndex] : undefined;
+		if (selectedEntry) {
+			this.state.cursorLine = selectedIndex + 1;
+			this.state.cursorCharacter = `${selectedEntry.id} `.length + 1;
+			this.scrollToKeepCursorVisible();
+		}
 		this.confirming = undefined;
 		this.statusMessage = "";
 		this.tui.requestRender();
@@ -133,12 +154,17 @@ export class ExplorerComponent implements Component {
 			await this.loadDirectory(joinExplorerPath(this.currentPath, entry.name));
 			return;
 		}
-		this.done({ kind: "open-file", absolutePath: join(this.session.root, joinExplorerPath(this.currentPath, entry.name)) });
+		this.done({
+			kind: "open-file",
+			absolutePath: join(this.session.root, joinExplorerPath(this.currentPath, entry.name)),
+			viewState: { relativePath: this.currentPath, selectedEntryName: entry.name },
+		});
 	}
 
 	private async navigateToParent(): Promise<void> {
 		if (this.currentPath === "") return; // already at the resolved root -- v1 never widens scope above it
-		await this.loadDirectory(parentExplorerPath(this.currentPath));
+		const childName = posix.basename(this.currentPath);
+		await this.loadDirectory(parentExplorerPath(this.currentPath), childName);
 	}
 
 	private async performAction(action: EditorAction): Promise<void> {
@@ -149,14 +175,14 @@ export class ExplorerComponent implements Component {
 				this.state.dirty = false;
 				if (diffs.length === 0) {
 					this.statusMessage = "no changes";
-					if (action.kind === "save-and-quit") this.done({ kind: "quit" });
+					if (action.kind === "save-and-quit") this.done({ kind: "quit", viewState: this.viewState() });
 					return;
 				}
 				this.confirming = { diffs, andQuit: action.kind === "save-and-quit" };
 				return;
 			}
 			case "quit":
-				this.done({ kind: "quit" });
+				this.done({ kind: "quit", viewState: this.viewState() });
 				return;
 			case "hover":
 				this.statusMessage = "hover is not applicable in the file explorer";
@@ -186,13 +212,19 @@ export class ExplorerComponent implements Component {
 			return;
 		}
 		if (andQuit) {
-			this.done({ kind: "quit" });
+			this.done({ kind: "quit", viewState: this.viewState() });
 			return;
 		}
 		await this.loadDirectory(this.currentPath);
 		this.statusMessage = "applied";
 	}
 
+	private viewState(): ExplorerViewState {
+		const parsed = parseExplorerLine(this.state.currentLineText);
+		const entry = !parsed || parsed.id === null ? undefined : this.entries.find((candidate) => candidate.id === parsed.id);
+		return entry ? { relativePath: this.currentPath, selectedEntryName: entry.name } : { relativePath: this.currentPath };
+	}
+
 	private scrollToKeepCursorVisible(): void {
 		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
 		if (this.state.cursorLine < this.scrollTop) this.scrollTop = this.state.cursorLine;

package/extension/src/editor/explorer-flow.ts

@@ -1,10 +1,10 @@
-import { dirname, relative } from "node:path";
+import { basename, dirname, relative } from "node:path";
 import type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
-import type { ExplorerResult } from "./explorer-component.ts";
+import type { ExplorerResult, ExplorerViewState } from "./explorer-component.ts";
 
 export interface ExplorerFlowHost {
-	/** Shows the explorer at `relativePath` (root-relative, "" for the resolved root) and resolves once the user quits or opens a file. */
-	showExplorer(session: DirectoryExplorerSession, relativePath: string): Promise<ExplorerResult>;
+	/** Shows the explorer at `relativePath` (root-relative, "" for the resolved root), optionally revealing one active entry, and resolves once the user quits or opens a file. */
+	showExplorer(session: DirectoryExplorerSession, relativePath: string, selectedEntryName?: string): Promise<ExplorerResult>;
 	/** Shows the real file editor for `absolutePath` and resolves once the user quits it. */
 	showEditor(absolutePath: string): Promise<void>;
 }
@@ -14,14 +14,21 @@ export interface ExplorerFlowHost {
  * the explorer -- at the directory the opened file lives in, not the resolved root -- once that
  * editor quits, rather than closing the whole session after the first file opened.
  */
-export async function runExplorerFlow(session: DirectoryExplorerSession, host: ExplorerFlowHost): Promise<void> {
-	let relativePath = "";
+export async function runExplorerFlow(
+	session: DirectoryExplorerSession,
+	host: ExplorerFlowHost,
+	initialViewState: ExplorerViewState = { relativePath: "" },
+): Promise<ExplorerViewState> {
+	let viewState = initialViewState;
 	for (;;) {
-		const result = await host.showExplorer(session, relativePath);
-		if (result.kind === "quit") return;
+		const result = await host.showExplorer(session, viewState.relativePath, viewState.selectedEntryName);
+		if (result.kind === "quit") return result.viewState ?? viewState;
 
 		await host.showEditor(result.absolutePath);
 		// path.relative(root, root) is "" directly, matching ExplorerComponent's own root-relative convention -- no "." case to normalize.
-		relativePath = relative(session.root, dirname(result.absolutePath));
+		viewState = result.viewState ?? {
+			relativePath: relative(session.root, dirname(result.absolutePath)),
+			selectedEntryName: basename(result.absolutePath),
+		};
 	}
 }

package/extension/src/editor/index.ts

@@ -31,11 +31,17 @@
 export type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
 export { type EditorAction, type EditorMode, EditorState } from "./editor-state.ts";
 export type { EditorTheme } from "./editor-theme.ts";
-export { ExplorerComponent, type ExplorerResult, joinExplorerPath } from "./explorer-component.ts";
+export { ExplorerComponent, type ExplorerResult, type ExplorerViewState, joinExplorerPath } from "./explorer-component.ts";
 // runExplorerFlow is pure orchestration over the two interfaces above (browse, open a file into
 // the real editor, return to the explorer at that file's own directory once it quits) -- exported
 // for the same reason ExplorerComponent/DirectoryExplorerSession are: any real host can drive this
 // 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,
@@ -96,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,
@@ -407,6 +409,74 @@ export default function (pi: ExtensionAPI) {
 
 		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;
 
 		async function openFileInEditor(commandCtx: ExtensionCommandContext, absolutePath: string): Promise<void> {
@@ -426,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);
@@ -1145,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) {
@@ -1622,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();
 		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);
@@ -1651,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) {
@@ -1714,17 +1797,22 @@ export default function (pi: ExtensionAPI) {
 			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" })),
@@ -1757,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) {

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.13.6",
+	"version": "0.13.9",
 	"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",