@danypops/pi-lector 0.13.9 → 0.13.11

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

@@ -1,5 +1,9 @@
 import type { JobSnapshot, OperationInputs, OperationOutputs, PopulateSymbolGraphResult, SymbolEdgeKind, SymbolNode } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath, workspaceForPathOrDirectory } from "../lector-client.ts";
+import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
+
+const CODE_ACTION_PREVIEW_PERMISSIONS = ["workspace:read"];
+const CODE_ACTION_APPLY_PERMISSIONS = ["workspace:write"];
 
 /**
  * Thin wrappers over Lector's code-intelligence operations: goToDefinition,
@@ -34,9 +38,50 @@ export interface CodeIntelligenceOperations {
 	hover(path: string, line: number, character: number): Promise<OperationOutputs["workspace.hover"]>;
 	documentSymbols(path: string): Promise<OperationOutputs["workspace.documentSymbols"]>;
 	diagnostics(path: string): Promise<OperationOutputs["workspace.diagnostics"]>;
+	previewCodeActions(
+		path: string,
+		input: Omit<OperationInputs["workspace.previewCodeActions"], "workspaceId" | "path">,
+		call: LectorVehicleCall,
+	): Promise<OperationOutputs["workspace.previewCodeActions"]>;
+	applyCodeAction(
+		path: string,
+		previewId: OperationInputs["workspace.applyCodeAction"]["previewId"],
+		call: LectorVehicleCall,
+	): Promise<OperationOutputs["workspace.applyCodeAction"]>;
+	diagnosticDelta(
+		path: string,
+		source: OperationInputs["workspace.diagnosticDelta"]["source"],
+		bounds?: Omit<OperationInputs["workspace.diagnosticDelta"], "workspaceId" | "source">,
+	): Promise<OperationOutputs["workspace.diagnosticDelta"]>;
 	prepareCallHierarchy(path: string, line: number, character: number): Promise<OperationOutputs["workspace.prepareCallHierarchy"]>;
 	incomingCalls(path: string, line: number, character: number): Promise<OperationOutputs["workspace.incomingCalls"]>;
 	outgoingCalls(path: string, line: number, character: number): Promise<OperationOutputs["workspace.outgoingCalls"]>;
+	prepareTypeHierarchy(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.prepareTypeHierarchy"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.prepareTypeHierarchy"]>;
+	supertypes(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.supertypes"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.supertypes"]>;
+	subtypes(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.subtypes"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.subtypes"]>;
+	impactAnalysis(
+		path: string,
+		source: OperationInputs["workspace.impactAnalysis"]["source"],
+		bounds: Pick<
+			OperationInputs["workspace.impactAnalysis"],
+			"maxDepth" | "maxNodes" | "maxEdges" | "maxBytes" | "deadlineMs" | "coverage" | "autoPopulate" | "maxFiles" | "maxSymbolsPerFile"
+		>,
+	): Promise<OperationOutputs["workspace.impactAnalysis"]>;
 	/**
 	 * Not exposed as a standalone Pi tool -- every workspace auto-populates on first touch via
 	 * monitorWorkspaceCache (workspace-cache/operations.ts). Kept here as an internal capability
@@ -46,7 +91,14 @@ export interface CodeIntelligenceOperations {
 	populateSymbolGraph(path: string, maxFiles: number, maxSymbolsPerFile: number, waitMs?: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	/** Not exposed as a standalone Pi tool -- see populateSymbolGraph. */
 	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
-	reachableFrom(path: string, line: number, character: number, maxDepth: number, kind?: SymbolEdgeKind): Promise<readonly SymbolNode[]>;
+	reachableFrom(
+		path: string,
+		line: number,
+		character: number,
+		maxDepth: number,
+		kind?: SymbolEdgeKind,
+		autoPopulation?: Pick<OperationInputs["workspace.reachableFrom"], "autoPopulate" | "maxFiles" | "maxSymbolsPerFile">,
+	): Promise<readonly SymbolNode[]>;
 	/** 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"]>;
@@ -120,6 +172,36 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 				},
 			);
 		},
+		async previewCodeActions(path, input, call) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<OperationOutputs["workspace.previewCodeActions"]>(
+						"workspace.previewCodeActions",
+						{ workspaceId, path, ...input },
+						CODE_ACTION_PREVIEW_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async applyCodeAction(path, previewId, call) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<OperationOutputs["workspace.applyCodeAction"]>(
+						"workspace.applyCodeAction",
+						{ workspaceId, previewId },
+						CODE_ACTION_APPLY_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async diagnosticDelta(path, source, bounds) {
+			return withWorkspace(
+				() => workspaceForPathOrDirectory(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.diagnosticDelta", { workspaceId, source, ...bounds }),
+			);
+		},
 		async prepareCallHierarchy(path, line, character) {
 			return withWorkspace(
 				() => workspaceForCodeIntelligencePath(path),
@@ -147,6 +229,30 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 				},
 			);
 		},
+		async prepareTypeHierarchy(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.prepareTypeHierarchy", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async supertypes(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.supertypes", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async subtypes(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.subtypes", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async impactAnalysis(path, source, bounds) {
+			return withWorkspace(
+				() => workspaceForPathOrDirectory(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.impactAnalysis", { workspaceId, source, ...bounds }),
+			);
+		},
 		async populateSymbolGraph(path, maxFiles, maxSymbolsPerFile, waitMs = 500) {
 			return withWorkspace(
 				() => workspaceForPathOrDirectory(path),
@@ -167,12 +273,12 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 			const { job } = await client.call("job.status", { jobId });
 			return job;
 		},
-		async reachableFrom(path, line, character, maxDepth, kind) {
+		async reachableFrom(path, line, character, maxDepth, kind, autoPopulation) {
 			return withWorkspace(
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { symbols } = await client.call("workspace.reachableFrom", { workspaceId, path, line, character, maxDepth, kind });
+					const { symbols } = await client.call("workspace.reachableFrom", { workspaceId, path, line, character, maxDepth, kind, ...autoPopulation });
 					return symbols;
 				},
 			);

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

@@ -5,6 +5,7 @@ import type {
 	Hover,
 	IncomingCall,
 	IntelligenceProvenance,
+	OperationOutputs,
 	OutgoingCall,
 	SymbolNode,
 	WorkspaceLocation,
@@ -27,6 +28,7 @@ const DEFAULT_VISIBLE_LOCATIONS = 8;
 const DEFAULT_VISIBLE_SYMBOLS = 12;
 const DEFAULT_VISIBLE_DIAGNOSTICS = 12;
 const DEFAULT_VISIBLE_CALLS = 12;
+const DEFAULT_VISIBLE_CHANGES = 12;
 
 const DIAGNOSTIC_SEVERITY_COLOR: Record<Diagnostic["severity"], ThemeColor> = {
 	error: "error",
@@ -171,6 +173,123 @@ export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | und
 	return lines.join("\n");
 }
 
+function formatPathCall(toolName: string, args: { path?: unknown }, theme: LectorTheme, qualifier = ""): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	return `${theme.fg("toolTitle", theme.bold(toolName))}${qualifier ? ` ${theme.fg("muted", qualifier)}` : ""} ${theme.fg("accent", path)}`;
+}
+
+export function formatCodeActionPreviewCall(
+	args: { path?: unknown; startLine?: unknown; startCharacter?: unknown; endLine?: unknown; endCharacter?: unknown },
+	theme: LectorTheme,
+): string {
+	const range = `${typeof args.startLine === "number" ? args.startLine : "?"}:${typeof args.startCharacter === "number" ? args.startCharacter : "?"}-${typeof args.endLine === "number" ? args.endLine : "?"}:${typeof args.endCharacter === "number" ? args.endCharacter : "?"}`;
+	return formatPathCall("code_action_preview", args, theme, range);
+}
+
+export function formatCodeActionPreviewResult(
+	result: OperationOutputs["workspace.previewCodeActions"] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.actions.length === 0) return theme.fg("dim", "No code actions.");
+	return [
+		theme.fg("muted", `${result.actions.length} code action${result.actions.length === 1 ? "" : "s"}:`),
+		...renderTruncatedList({
+			items: result.actions,
+			expanded,
+			visibleCount: DEFAULT_VISIBLE_CHANGES,
+			formatItem: (action) => {
+				const state = action.disabledReason
+					? theme.fg("warning", `disabled: ${action.disabledReason}`)
+					: action.preferred
+						? theme.fg("success", "preferred")
+						: "";
+				const paths = action.affectedPaths.length > 0 ? action.affectedPaths.join(", ") : "command only";
+				return `  ${theme.bold(action.title)}${action.kind ? ` (${action.kind})` : ""} -- ${paths}${state ? ` -- ${state}` : ""}`;
+			},
+			moreLine: moreLine(theme),
+			truncationWarning: result.truncated || result.deadlineReached ? theme.fg("warning", "results truncated by the requested bounds") : undefined,
+		}),
+	].join("\n");
+}
+
+export function formatCodeActionApplyCall(args: { path?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("code_action_apply", args, theme);
+}
+
+export function formatCodeActionApplyResult(result: OperationOutputs["workspace.applyCodeAction"] | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No code-action result.");
+	const lines = result.touchedPaths.map((path) => `  ${path}`);
+	if (result.transactionId) lines.push(theme.fg("muted", `transaction ${result.transactionId}`));
+	if (result.pendingCommand) lines.push(theme.fg("warning", `pending command ${result.pendingCommand.command}`));
+	return lines.length > 0 ? lines.join("\n") : theme.fg("dim", "Code action made no file changes.");
+}
+
+export function formatDiagnosticDeltaCall(args: { path?: unknown; source?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("diagnostic_delta", args, theme, typeof args.source === "string" ? args.source : "");
+}
+
+export function formatDiagnosticDeltaResult(result: OperationOutputs["workspace.diagnosticDelta"] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No diagnostic delta.");
+	const changes = [
+		...result.introduced.map((diagnostic) => ({ label: "introduced", diagnostic })),
+		...result.resolved.map((diagnostic) => ({ label: "resolved", diagnostic })),
+		...result.changed.map(({ after }) => ({ label: "changed", diagnostic: after })),
+	];
+	if (changes.length === 0) return theme.fg("success", "No diagnostic changes.");
+	return renderTruncatedList({
+		items: changes,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CHANGES,
+		formatItem: ({ label, diagnostic }) =>
+			`${theme.fg(label === "introduced" ? "error" : label === "resolved" ? "success" : "warning", label)} ${formatLocation(theme, diagnostic.range.path, diagnostic.range.start.line, diagnostic.range.start.character)} -- ${diagnostic.message}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "results truncated by maxResults/maxBytes") : undefined,
+	}).join("\n");
+}
+
+export function formatTypeHierarchyCall(args: { direction?: unknown; path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return `${formatPositionalCall("type_hierarchy", args, theme)} ${theme.fg("muted", typeof args.direction === "string" ? args.direction : "")}`;
+}
+
+export function formatTypeHierarchyResult(
+	result: OperationOutputs["workspace.prepareTypeHierarchy"] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.items.length === 0) return theme.fg("dim", "No type-hierarchy items found.");
+	return renderTruncatedList({
+		items: result.items,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CALLS,
+		formatItem: (item) => `  ${formatCallHierarchyEntry(item, theme)}${item.detail ? theme.fg("dim", ` -- ${item.detail}`) : ""}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "results truncated by the requested bounds") : undefined,
+	}).join("\n");
+}
+
+export function formatImpactAnalysisCall(args: { path?: unknown; source?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("impact_analysis", args, theme, typeof args.source === "string" ? args.source : "");
+}
+
+export function formatImpactAnalysisResult(result: OperationOutputs["workspace.impactAnalysis"] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No impact-analysis result.");
+	const impacts = [
+		...result.changedSymbols.map(({ symbol, side }) => ({ label: `changed ${side}`, symbol })),
+		...result.impactedSymbols.map(({ symbol, depth }) => ({ label: `impact depth=${depth}`, symbol })),
+		...result.relatedTests.map(({ symbol, evidence }) => ({ label: `test ${evidence.kind}`, symbol })),
+	];
+	if (impacts.length === 0) return theme.fg("dim", "No changed symbols resolved.");
+	return renderTruncatedList({
+		items: impacts,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CHANGES,
+		formatItem: ({ label, symbol }) => `${theme.fg("muted", label)} ${formatCallHierarchyEntry(symbol, theme)}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated || result.deadlineReached ? theme.fg("warning", "analysis truncated by the requested bounds") : undefined,
+	}).join("\n");
+}
+
 function formatCallHierarchyEntry(entry: { kind: string; name: string; location: WorkspaceLocation }, theme: LectorTheme): string {
 	const kind = theme.fg(colorForKind(entry.kind), entry.kind);
 	const name = theme.fg("text", theme.bold(entry.name));

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

@@ -83,6 +83,9 @@ export function formatSearchTextAcrossProjectsResult(
 		lines.push(formatOutcomeHeader(entry, theme));
 		const { outcome } = entry;
 		if (outcome.status !== "ready") continue;
+		if (outcome.result.provenance) {
+			lines.push(theme.fg("dim", `  lexical via ${outcome.result.provenance.backend} (${outcome.result.provenance.indexState})`));
+		}
 		if (outcome.result.matches.length === 0) {
 			lines.push(theme.fg("dim", "  no matches"));
 			continue;

package/extension/src/editor/editor-state.ts

@@ -4,6 +4,26 @@ export type EditorMode = "normal" | "insert" | "command";
 
 export type EditorAction = { kind: "save" } | { kind: "save-and-quit" } | { kind: "quit" } | { kind: "hover" };
 
+export interface EditorSourcePosition {
+	/** One-based line number. */
+	readonly line: number;
+	/** One-based UTF-16 code-unit position within the line. */
+	readonly character: number;
+}
+
+export type EditorPositionErrorCode = "line-out-of-range" | "character-out-of-range";
+
+/** Reports why a requested source position cannot identify a cursor location in the current buffer. */
+export class EditorPositionError extends Error {
+	constructor(
+		readonly code: EditorPositionErrorCode,
+		message: string,
+	) {
+		super(`${code}: ${message}`);
+		this.name = "EditorPositionError";
+	}
+}
+
 const BACKSPACE_KEYS = new Set(["\x7f", "\b"]);
 
 /**
@@ -27,8 +47,25 @@ export class EditorState {
 	private insertPendingJ = false;
 	private yankedLine: string | undefined;
 
-	constructor(content: string) {
+	constructor(content: string, initialPosition?: EditorSourcePosition) {
 		this.buffer = new LiveBuffer(content);
+		if (initialPosition) this.moveToInitialPosition(initialPosition);
+	}
+
+	private moveToInitialPosition(position: EditorSourcePosition): void {
+		if (!Number.isSafeInteger(position.line) || position.line < 1 || position.line > this.buffer.lineCount) {
+			throw new EditorPositionError("line-out-of-range", `Line ${position.line} is outside this ${this.buffer.lineCount}-line buffer`);
+		}
+		const lineLength = this.buffer.lineText(position.line).length;
+		const maxCharacter = Math.max(lineLength, 1);
+		if (!Number.isSafeInteger(position.character) || position.character < 1 || position.character > maxCharacter) {
+			throw new EditorPositionError(
+				"character-out-of-range",
+				`Character ${position.character} is outside line ${position.line}'s ${lineLength} UTF-16 code units`,
+			);
+		}
+		this.cursorLine = position.line;
+		this.cursorCharacter = position.character;
 	}
 
 	get currentLineText(): string {

package/extension/src/editor/index.ts

@@ -29,7 +29,14 @@
  */
 
 export type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
-export { type EditorAction, type EditorMode, EditorState } from "./editor-state.ts";
+export {
+	type EditorAction,
+	type EditorMode,
+	EditorPositionError,
+	type EditorPositionErrorCode,
+	type EditorSourcePosition,
+	EditorState,
+} from "./editor-state.ts";
 export type { EditorTheme } from "./editor-theme.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
@@ -44,4 +51,5 @@ export {
 	type EditorHoverRequest,
 	ModalEditorComponent,
 	type ModalEditorHost,
+	type ModalEditorOptions,
 } from "./modal-editor-component.ts";

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

@@ -4,7 +4,7 @@ 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";
-import type { EditorAction } from "./editor-state.ts";
+import type { EditorAction, EditorSourcePosition } from "./editor-state.ts";
 import { EditorState } from "./editor-state.ts";
 import type { EditorTheme } from "./editor-theme.ts";
 
@@ -26,6 +26,11 @@ export type EditorHoverOutcome =
 	| { readonly kind: "ready"; readonly hover?: { readonly contents: string } }
 	| { readonly kind: "stale-active-buffer"; readonly bufferHash: ContentHash };
 
+export interface ModalEditorOptions {
+	/** Positions the cursor using one-based UTF-16 coordinates and scrolls it into the first viewport. */
+	readonly initialPosition?: EditorSourcePosition;
+}
+
 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. */
@@ -65,13 +70,14 @@ export class ModalEditorComponent implements Component {
 	private statusMessage = "";
 	private highlightCache: { text: string; spans: readonly HighlightSpan[] } | undefined;
 
-	constructor(tui: TUI, theme: EditorTheme, host: ModalEditorHost, content: string, done: () => void) {
+	constructor(tui: TUI, theme: EditorTheme, host: ModalEditorHost, content: string, done: () => void, options: ModalEditorOptions = {}) {
 		this.tui = tui;
 		this.theme = theme;
 		this.host = host;
 		this.done = done;
 		this.extension = extname(host.filePath);
-		this.state = new EditorState(content);
+		this.state = new EditorState(content, options.initialPosition);
+		this.scrollToKeepCursorVisible();
 		this.refreshHighlightsSafely();
 	}
 

package/extension/src/git/operations.ts

@@ -1,4 +1,4 @@
-import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationOutputs } from "@danypops/lector";
+import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationInputs, OperationOutputs } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForDirectory } from "../lector-client.ts";
 import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
 
@@ -6,6 +6,8 @@ type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"
 type GitWorktreeAddResult = OperationOutputs["workspace.gitWorktreeAdd"];
 type GitWorktreeRemoveResult = OperationOutputs["workspace.gitWorktreeRemove"];
 type GitGrepResult = OperationOutputs["workspace.gitGrep"];
+type GitHistoryGrepResult = OperationOutputs["workspace.gitGrepHistory"];
+type GitHistoryGrepBounds = Omit<OperationInputs["workspace.gitGrepHistory"], "workspaceId" | "pattern" | "pathspecs">;
 type GitListFilesResult = OperationOutputs["workspace.gitListFiles"];
 
 /** Matches GIT_READ_PERMISSIONS' own declared value server-side (git/operation-registration.ts). */
@@ -42,6 +44,14 @@ export interface GitOperations {
 		maxBytes: number,
 		call: LectorVehicleCall,
 	): Promise<GitGrepResult>;
+	/** Bounded extended-regex search across commit trees reachable from every ref, with deterministic topological paging and exact-match deduplication. */
+	grepHistory(
+		directory: string,
+		pattern: string,
+		pathspecs: readonly string[] | undefined,
+		bounds: GitHistoryGrepBounds,
+		call: LectorVehicleCall,
+	): Promise<GitHistoryGrepResult>;
 	/** Every file path in `ref`'s own tree, no checkout -- pathspecs narrows the listing (prefix-based, not glob-based like grep's). */
 	listFiles(directory: string, ref: string, pathspecs: readonly string[] | undefined, maxResults: number, call: LectorVehicleCall): Promise<GitListFilesResult>;
 	/** True iff ancestorRef is a real ancestor of (or the exact same commit as) ref -- the backport/reachability check "was this fix ported to this branch" actually needs. */
@@ -139,6 +149,18 @@ export function createLectorGitOperations(): GitOperations {
 					),
 			);
 		},
+		async grepHistory(directory, pattern, pathspecs, bounds, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitHistoryGrepResult>(
+						"workspace.gitGrepHistory",
+						{ workspaceId, pattern, pathspecs, ...bounds },
+						GIT_READ_PERMISSIONS,
+						call,
+					),
+			);
+		},
 		async listFiles(directory, ref, pathspecs, maxResults, call) {
 			return withWorkspace(
 				() => workspaceForDirectory(directory),

package/extension/src/git/rendering.ts

@@ -11,12 +11,24 @@ const DEFAULT_VISIBLE_FILES = 20;
 const DEFAULT_VISIBLE_COMMITS = 10;
 const DEFAULT_VISIBLE_DIFF_LINES = 60;
 
-export type GitAction = "status" | "log" | "diff" | "compare-symbol" | "worktree-add" | "worktree-remove" | "show" | "grep-ref" | "ls-ref" | "is-ancestor";
+export type GitAction =
+	| "status"
+	| "log"
+	| "diff"
+	| "compare-symbol"
+	| "worktree-add"
+	| "worktree-remove"
+	| "show"
+	| "grep-ref"
+	| "grep-history"
+	| "ls-ref"
+	| "is-ancestor";
 
 type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
 type GitWorktreeAddResult = OperationOutputs["workspace.gitWorktreeAdd"];
 type GitWorktreeRemoveResult = OperationOutputs["workspace.gitWorktreeRemove"];
 type GitGrepResult = OperationOutputs["workspace.gitGrep"];
+type GitHistoryGrepResult = OperationOutputs["workspace.gitGrepHistory"];
 type GitListFilesResult = OperationOutputs["workspace.gitListFiles"];
 
 export interface GitToolDetails {
@@ -29,6 +41,7 @@ export interface GitToolDetails {
 	readonly worktreeRemove?: GitWorktreeRemoveResult;
 	readonly showFile?: { readonly ref: string; readonly path: string; readonly content: string | undefined };
 	readonly grep?: GitGrepResult;
+	readonly historyGrep?: GitHistoryGrepResult;
 	readonly listFiles?: GitListFilesResult;
 	readonly isAncestor?: { readonly ancestorRef: string; readonly ref: string; readonly result: boolean };
 }
@@ -61,10 +74,10 @@ export function formatGitCall(
 		const ref = typeof args.ref === "string" ? args.ref : "";
 		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)} ${ancestorRef} -> ${ref}`;
 	}
-	if (action === "grep-ref") {
-		const ref = typeof args.ref === "string" ? args.ref : "";
+	if (action === "grep-ref" || action === "grep-history") {
+		const ref = action === "grep-ref" && typeof args.ref === "string" ? `${args.ref} ` : "";
 		const pattern = typeof args.pattern === "string" ? args.pattern : "";
-		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)} ${ref} "${pattern}"`;
+		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)} ${ref}"${pattern}"`;
 	}
 	if (action === "show") {
 		const ref = typeof args.ref === "string" ? args.ref : "";
@@ -105,6 +118,30 @@ function formatGitGrepResult(result: GitGrepResult | undefined, expanded: boolea
 	return lines.join("\n");
 }
 
+function formatGitHistoryGrepResult(result: GitHistoryGrepResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.matches.length === 0) {
+		if (result?.deadlineReached) return theme.fg("warning", "No matches before the deadline.");
+		return theme.fg("dim", "No historical matches.");
+	}
+	const lines = renderTruncatedList({
+		items: result.matches,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_FILES,
+		formatItem: (match) => {
+			const occurrences = match.occurrences > 1 ? ` (${match.occurrences} commits)` : "";
+			return `${theme.fg("muted", match.commit.slice(0, 8))} ${theme.fg("accent", `${match.path}:${match.line}`)}:${match.text}${occurrences}`;
+		},
+		moreLine: moreLine(theme),
+		truncationWarning: result.deadlineReached
+			? theme.fg("warning", "(deadline reached)")
+			: result.truncated
+				? theme.fg("warning", "(bounded by maxMatches/maxBytes)")
+				: undefined,
+	});
+	if (result.nextCommitOffset !== undefined) lines.push(theme.fg("muted", `next commit offset: ${result.nextCommitOffset}`));
+	return lines.join("\n");
+}
+
 function formatGitListFilesResult(result: GitListFilesResult | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!result || result.paths.length === 0) return theme.fg("dim", "No files.");
 	const lines = renderTruncatedList({
@@ -133,6 +170,7 @@ export function formatGitResult(details: GitToolDetails | undefined, expanded: b
 	if (details.action === "worktree-remove") return formatGitWorktreeRemoveResult(details.worktreeRemove, theme);
 	if (details.action === "show") return formatGitShowFileResult(details.showFile, theme);
 	if (details.action === "grep-ref") return formatGitGrepResult(details.grep, expanded, theme);
+	if (details.action === "grep-history") return formatGitHistoryGrepResult(details.historyGrep, expanded, theme);
 	if (details.action === "ls-ref") return formatGitListFilesResult(details.listFiles, expanded, theme);
 	if (details.action === "is-ancestor") return formatGitIsAncestorResult(details.isAncestor, theme);
 	return formatGitDiffResult(details.result, expanded, theme);

package/extension/src/index.ts

@@ -31,7 +31,7 @@ import type {
 	WorkspaceLocation,
 	WorkspaceMapResult,
 } from "@danypops/lector";
-import { DEFAULT_EXTERNAL_SEARCH_MAX_RESULTS, PACKAGE_ECOSYSTEMS } from "@danypops/lector";
+import { codeActionPreviewId, DEFAULT_EXTERNAL_SEARCH_MAX_RESULTS, PACKAGE_ECOSYSTEMS } from "@danypops/lector";
 import {
 	type AgentToolResult,
 	createEditToolDefinition,
@@ -56,6 +56,12 @@ import {
 	type CallHierarchyToolDetails,
 	formatCallHierarchyCall,
 	formatCallHierarchyResult,
+	formatCodeActionApplyCall,
+	formatCodeActionApplyResult,
+	formatCodeActionPreviewCall,
+	formatCodeActionPreviewResult,
+	formatDiagnosticDeltaCall,
+	formatDiagnosticDeltaResult,
 	formatDiagnosticsCall,
 	formatDiagnosticsResult,
 	formatDocumentSymbolsCall,
@@ -68,8 +74,12 @@ import {
 	formatGoToImplementationResult,
 	formatHoverCall,
 	formatHoverResult,
+	formatImpactAnalysisCall,
+	formatImpactAnalysisResult,
 	formatReachableFromCall,
 	formatReachableFromResult,
+	formatTypeHierarchyCall,
+	formatTypeHierarchyResult,
 	formatWorkspaceMapCall,
 	formatWorkspaceMapResult,
 } from "./code-intelligence/rendering.ts";
@@ -774,6 +784,186 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		registerLectorTool({
+			name: "code_action_preview",
+			label: "Code Action Preview",
+			description:
+				"Request bounded language-server code actions for one range. Returns opaque preview ids, affected files, exact edits, provenance, and truncation status. This operation is read-only; use code_action_apply separately to mutate files.",
+			promptSnippet: "Preview bounded language-server fixes for one range",
+			promptGuidelines: ["Preview first, inspect every affected path/edit, then pass exactly one returned previewId to code_action_apply."],
+			parameters: Type.Object({
+				path: Type.String({ description: "Absolute or cwd-relative file path" }),
+				startLine: Type.Number({ description: "1-indexed range start line" }),
+				startCharacter: Type.Number({ description: "1-indexed range start character" }),
+				endLine: Type.Number({ description: "1-indexed range end line" }),
+				endCharacter: Type.Number({ description: "1-indexed range end character" }),
+				only: Type.Optional(Type.Array(Type.String(), { maxItems: 20, description: "Code-action kinds such as quickfix" })),
+				includeCommandActions: Type.Optional(Type.Boolean({ description: "Include command-only actions in preview; guarded apply still denies them" })),
+				maxActions: Type.Number({ description: "Maximum actions" }),
+				maxEdits: Type.Number({ description: "Maximum edits per action" }),
+				maxFiles: Type.Number({ description: "Maximum affected files per action" }),
+				maxBytes: Type.Number({ description: "Maximum response JSON bytes" }),
+				deadlineMs: Type.Number({ description: "Wall-clock deadline in milliseconds" }),
+			}),
+			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<OperationOutputs["workspace.previewCodeActions"]>> {
+				const path = resolve(cwd, params.path);
+				const vehicleCall: LectorVehicleCall = { toolName: "code_action_preview", toolCallId, signal, context: ctx };
+				const result = await codeIntelligenceOperations.previewCodeActions(
+					path,
+					{
+						range: {
+							start: { line: params.startLine, character: params.startCharacter },
+							end: { line: params.endLine, character: params.endCharacter },
+						},
+						...(params.only ? { only: params.only } : {}),
+						...(params.includeCommandActions !== undefined ? { includeCommandActions: params.includeCommandActions } : {}),
+						maxActions: params.maxActions,
+						maxEdits: params.maxEdits,
+						maxFiles: params.maxFiles,
+						maxBytes: params.maxBytes,
+						deadlineMs: params.deadlineMs,
+					},
+					vehicleCall,
+				);
+				const text = result.actions
+					.map((action) => `${action.id} ${action.kind ?? "action"} ${action.title} -- ${action.affectedPaths.join(", ") || "command only"}`)
+					.join("\n");
+				return { content: [{ type: "text", text: text || "No code actions." }], details: result };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatCodeActionPreviewCall(args, theme));
+				return text;
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Finding code actions..."), 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 || "code_action_preview failed"), 0, 0);
+				}
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatCodeActionPreviewResult(result.details, expanded, theme));
+				return text;
+			},
+		});
+
+		registerLectorTool({
+			name: "code_action_apply",
+			label: "Apply Code Action",
+			description:
+				"Apply one previously previewed language-server WorkspaceEdit atomically with workspace containment, document-version and content-hash guards. Returns a transaction id for exact transaction-aware revert. Command-only actions are denied.",
+			promptSnippet: "Atomically apply one previewed language-server edit",
+			promptGuidelines: ["Use only after inspecting code_action_preview; retain transactionId for diagnostic_delta and revert."],
+			parameters: Type.Object({
+				path: Type.String({ description: "The same file path used to obtain the preview" }),
+				previewId: Type.String({ description: "Opaque id returned by code_action_preview" }),
+			}),
+			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<OperationOutputs["workspace.applyCodeAction"]>> {
+				const vehicleCall: LectorVehicleCall = { toolName: "code_action_apply", toolCallId, signal, context: ctx };
+				const result = await codeIntelligenceOperations.applyCodeAction(resolve(cwd, params.path), codeActionPreviewId(params.previewId), vehicleCall);
+				const text = [
+					...result.touchedPaths,
+					...(result.transactionId ? [`transaction ${result.transactionId}`] : []),
+					...(result.pendingCommand ? [`pending command ${result.pendingCommand.command}`] : []),
+				].join("\n");
+				return { content: [{ type: "text", text: text || "Code action made no file changes." }], details: result };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatCodeActionApplyCall(args, theme));
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Applying code action..."), 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 || "code_action_apply failed"), 0, 0);
+				}
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatCodeActionApplyResult(result.details, theme));
+				return text;
+			},
+		});
+
+		registerLectorTool({
+			name: "diagnostic_delta",
+			label: "Diagnostic Delta",
+			description:
+				"Return only diagnostics introduced, resolved, or changed by one atomic mutation transaction or git-ref diff across its bounded affected-file cone, with completeness and provenance. Transaction results include the exact safe revert operation.",
+			promptSnippet: "Inspect diagnostic changes caused by a transaction or git diff",
+			promptGuidelines: [
+				"Use source=transaction with the id returned by an atomic mutation, or source=git with a baseline ref; unchanged diagnostics are omitted.",
+			],
+			parameters: Type.Object({
+				path: Type.String({ description: "Project directory or a path inside it" }),
+				source: Type.String({ description: "transaction | git" }),
+				sourceId: Type.String({ description: "Mutation transaction id or git baseline ref" }),
+				maxResults: Type.Optional(Type.Number({ description: "Maximum results per delta class" })),
+				maxBytes: Type.Optional(Type.Number({ description: "Maximum response JSON bytes" })),
+				maxDepth: Type.Optional(Type.Number({ description: "Git source: maximum impact depth" })),
+				maxNodes: Type.Optional(Type.Number({ description: "Git source: maximum graph nodes" })),
+				maxEdges: Type.Optional(Type.Number({ description: "Git source: maximum graph edges" })),
+				deadlineMs: Type.Optional(Type.Number({ description: "Git source: wall-clock deadline" })),
+				maxFiles: Type.Optional(Type.Number({ description: "Git source: maximum graph files" })),
+				maxSymbolsPerFile: Type.Optional(Type.Number({ description: "Git source: maximum declarations per file" })),
+				autoPopulate: Type.Optional(Type.Boolean({ description: "Git source: populate a missing/stale graph" })),
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<OperationOutputs["workspace.diagnosticDelta"]>> {
+				const source =
+					params.source === "transaction"
+						? ({ kind: "transaction", transactionId: params.sourceId } as const)
+						: params.source === "git"
+							? ({ kind: "git", ref: params.sourceId } as const)
+							: undefined;
+				if (!source) throw new TypeError("diagnostic_delta source must be transaction or git");
+				const result = await codeIntelligenceOperations.diagnosticDelta(resolve(cwd, params.path), source, {
+					maxResults: params.maxResults,
+					maxBytes: params.maxBytes,
+					maxDepth: params.maxDepth,
+					maxNodes: params.maxNodes,
+					maxEdges: params.maxEdges,
+					deadlineMs: params.deadlineMs,
+					maxFiles: params.maxFiles,
+					maxSymbolsPerFile: params.maxSymbolsPerFile,
+					autoPopulate: params.autoPopulate,
+				});
+				const text = [
+					...result.introduced.map(
+						(diagnostic) => `introduced ${diagnostic.severity} ${diagnostic.range.path}:${diagnostic.range.start.line} -- ${diagnostic.message}`,
+					),
+					...result.resolved.map(
+						(diagnostic) => `resolved ${diagnostic.severity} ${diagnostic.range.path}:${diagnostic.range.start.line} -- ${diagnostic.message}`,
+					),
+					...result.changed.map(({ before, after }) => `changed ${after.range.path}:${after.range.start.line} -- ${before.message} -> ${after.message}`),
+				].join("\n");
+				return { content: [{ type: "text", text: text || "No diagnostic changes." }], details: result };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatDiagnosticDeltaCall(args, theme));
+				return text;
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Comparing diagnostics..."), 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 || "diagnostic_delta failed"), 0, 0);
+				}
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatDiagnosticDeltaResult(result.details, expanded, theme));
+				return text;
+			},
+		});
+
 		registerLectorTool({
 			name: "call_hierarchy",
 			label: "Call Hierarchy",
@@ -840,6 +1030,137 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		registerLectorTool({
+			name: "type_hierarchy",
+			label: "Type Hierarchy",
+			description:
+				"Resolve a type at an exact file position, or list its direct supertypes or subtypes. ACTIONS: prepare, supertypes, subtypes. Capability-unavailable is reported distinctly from an empty hierarchy.",
+			promptSnippet: "Resolve a type hierarchy at an exact position",
+			promptGuidelines: ["Use supertypes/subtypes instead of grepping for extends or implements; the language server resolves semantic relationships."],
+			parameters: Type.Object({
+				direction: Type.String({ description: "prepare | supertypes | subtypes" }),
+				...positionParameters,
+				maxResults: Type.Optional(Type.Number({ description: "Maximum hierarchy items (default 1000)" })),
+				maxBytes: Type.Optional(Type.Number({ description: "Maximum JSON bytes (default 1 MiB)" })),
+				deadlineMs: Type.Optional(Type.Number({ description: "Wall-clock deadline in milliseconds (default 10000, maximum 120000)" })),
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<OperationOutputs["workspace.prepareTypeHierarchy"]>> {
+				const path = resolve(cwd, params.path);
+				const bounds = { maxResults: params.maxResults, maxBytes: params.maxBytes, deadlineMs: params.deadlineMs };
+				const result =
+					params.direction === "prepare"
+						? await codeIntelligenceOperations.prepareTypeHierarchy(path, params.line, params.character, bounds)
+						: params.direction === "supertypes"
+							? await codeIntelligenceOperations.supertypes(path, params.line, params.character, bounds)
+							: params.direction === "subtypes"
+								? await codeIntelligenceOperations.subtypes(path, params.line, params.character, bounds)
+								: undefined;
+				if (!result) throw new Error(`unknown type_hierarchy direction: ${String(params.direction)}`);
+				const text =
+					result.items.length === 0
+						? "No type-hierarchy items found."
+						: result.items.map((item) => `${item.kind} ${item.name} -- ${item.location.path}:${item.location.line}:${item.location.character}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(result.provenance)}\n${text}` }], details: result };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatTypeHierarchyCall(args, theme));
+				return text;
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Resolving type hierarchy..."), 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 || "type_hierarchy failed"), 0, 0);
+				}
+				const details = result.details;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(renderIntelligenceSource(formatTypeHierarchyResult(details, expanded, theme), details.provenance, theme));
+				return text;
+			},
+		});
+
+		registerLectorTool({
+			name: "impact_analysis",
+			label: "Impact Analysis",
+			description:
+				"Map a git diff or mutation transaction to changed declarations, semantic callers/references, package boundaries, diagnostics, and related tests. Associations preserve semantic-edge versus filename-heuristic evidence.",
+			promptSnippet: "Find symbols and tests affected by a change",
+			promptGuidelines: [
+				"Use after a mutation or against a git ref to choose targeted verification from explicit evidence rather than filename guesses alone.",
+			],
+			parameters: Type.Object({
+				path: Type.String({ description: "Project directory or a path inside it" }),
+				source: Type.String({ description: "git | mutation" }),
+				ref: Type.Optional(Type.String({ description: "Git ref for source=git" })),
+				transactionId: Type.Optional(Type.String({ description: "Mutation transaction id for source=mutation" })),
+				maxDepth: Type.Number({ description: "Maximum reverse-graph hops" }),
+				maxNodes: Type.Number({ description: "Maximum graph nodes" }),
+				maxEdges: Type.Number({ description: "Maximum graph edges" }),
+				maxBytes: Type.Number({ description: "Maximum response JSON bytes" }),
+				deadlineMs: Type.Number({ description: "Wall-clock deadline in milliseconds" }),
+				maxFiles: Type.Number({ description: "Maximum source files for graph freshness/population" }),
+				maxSymbolsPerFile: Type.Number({ description: "Maximum declarations per source file" }),
+				autoPopulate: Type.Optional(Type.Boolean({ description: "Populate once when no complete graph exists" })),
+				coverage: Type.Optional(
+					Type.Array(
+						Type.Object({
+							testPath: Type.String(),
+							coveredPaths: Type.Array(Type.String(), { maxItems: 1000 }),
+						}),
+						{ maxItems: 1000, description: "Optional test-to-covered-source evidence" },
+					),
+				),
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<OperationOutputs["workspace.impactAnalysis"]>> {
+				const source =
+					params.source === "git"
+						? ({ kind: "git", ...(params.ref !== undefined ? { ref: params.ref } : {}) } as const)
+						: params.source === "mutation" && params.transactionId
+							? ({ kind: "mutation", transactionId: params.transactionId } as const)
+							: undefined;
+				if (!source) throw new TypeError("impact_analysis requires source=git or source=mutation with transactionId");
+				const result = await codeIntelligenceOperations.impactAnalysis(resolve(cwd, params.path), source, {
+					maxDepth: params.maxDepth,
+					maxNodes: params.maxNodes,
+					maxEdges: params.maxEdges,
+					maxBytes: params.maxBytes,
+					deadlineMs: params.deadlineMs,
+					maxFiles: params.maxFiles,
+					maxSymbolsPerFile: params.maxSymbolsPerFile,
+					...(params.autoPopulate !== undefined ? { autoPopulate: params.autoPopulate } : {}),
+					...(params.coverage !== undefined ? { coverage: params.coverage } : {}),
+				});
+				const text = [
+					...result.changedSymbols.map(({ symbol, side }) => `changed ${side} ${symbol.kind} ${symbol.name} -- ${symbol.location.path}`),
+					...result.impactedSymbols.map(({ symbol, depth }) => `impact depth=${depth} ${symbol.kind} ${symbol.name} -- ${symbol.location.path}`),
+					...result.relatedTests.map(({ symbol, evidence }) => `test ${evidence.kind} -- ${symbol.location.path}`),
+				].join("\n");
+				return { content: [{ type: "text", text: text || "No changed symbols resolved." }], details: result };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatImpactAnalysisCall(args, theme));
+				return text;
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Analyzing impact..."), 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 || "impact_analysis failed"), 0, 0);
+				}
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatImpactAnalysisResult(result.details, expanded, theme));
+				return text;
+			},
+		});
+
 		registerLectorTool({
 			name: "reference_based_rename",
 			label: "Reference-Based Rename",
@@ -1012,6 +1333,9 @@ export default function (pi: ExtensionAPI) {
 				childId: Type.Optional(Type.String({ description: "The contained annotation's id -- required for contain/uncontain" })),
 				rootId: Type.Optional(Type.String({ description: "The subtree's root annotation id -- required for tree" })),
 				maxDepth: Type.Optional(Type.Number({ description: "Maximum containment hops from rootId to include -- required for tree" })),
+				autoPopulate: Type.Optional(Type.Boolean({ description: "For create/refresh: populate a genuinely not-cached graph once before resolving anchors" })),
+				maxFiles: Type.Optional(Type.Number({ description: "For create/refresh autoPopulate: explicit maximum files to scan" })),
+				maxSymbolsPerFile: Type.Optional(Type.Number({ description: "For create/refresh autoPopulate: explicit maximum declarations per file" })),
 			}),
 			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<SymbolAnnotationToolDetails>> {
 				const path = resolve(cwd, params.path);
@@ -1034,6 +1358,11 @@ export default function (pi: ExtensionAPI) {
 						params.body,
 						resolveAnchorInputs(params.anchors),
 						vehicleCall,
+						{
+							...(params.autoPopulate !== undefined ? { autoPopulate: params.autoPopulate } : {}),
+							...(params.maxFiles !== undefined ? { maxFiles: params.maxFiles } : {}),
+							...(params.maxSymbolsPerFile !== undefined ? { maxSymbolsPerFile: params.maxSymbolsPerFile } : {}),
+						},
 					);
 					details.annotation = annotation;
 					text = formatAnnotationDetail(annotation);
@@ -1063,6 +1392,11 @@ export default function (pi: ExtensionAPI) {
 						params.body,
 						resolveAnchorInputs(params.anchors),
 						vehicleCall,
+						{
+							...(params.autoPopulate !== undefined ? { autoPopulate: params.autoPopulate } : {}),
+							...(params.maxFiles !== undefined ? { maxFiles: params.maxFiles } : {}),
+							...(params.maxSymbolsPerFile !== undefined ? { maxSymbolsPerFile: params.maxSymbolsPerFile } : {}),
+						},
 					);
 					details.annotation = annotation;
 					text = annotation ? formatAnnotationDetail(annotation) : `no annotation "${params.id}"`;
@@ -1169,10 +1503,17 @@ export default function (pi: ExtensionAPI) {
 						description: "Restrict to one edge kind; omit for any kind",
 					}),
 				),
+				autoPopulate: Type.Optional(Type.Boolean({ description: "Populate a genuinely not-cached graph once before traversing" })),
+				maxFiles: Type.Optional(Type.Number({ description: "For autoPopulate: explicit maximum files to scan" })),
+				maxSymbolsPerFile: Type.Optional(Type.Number({ description: "For autoPopulate: explicit maximum declarations per file" })),
 			}),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const symbols = await codeIntelligenceOperations.reachableFrom(path, params.line, params.character, params.maxDepth, params.kind);
+				const symbols = await codeIntelligenceOperations.reachableFrom(path, params.line, params.character, params.maxDepth, params.kind, {
+					...(params.autoPopulate !== undefined ? { autoPopulate: params.autoPopulate } : {}),
+					...(params.maxFiles !== undefined ? { maxFiles: params.maxFiles } : {}),
+					...(params.maxSymbolsPerFile !== undefined ? { maxSymbolsPerFile: params.maxSymbolsPerFile } : {}),
+				});
 				const text =
 					symbols.length === 0
 						? "Nothing reachable at this position."
@@ -1354,18 +1695,20 @@ export default function (pi: ExtensionAPI) {
 			name: "git",
 			label: "Git",
 			description:
-				"Working tree status, recent commit log, unified diff, one symbol's own declaration diff across two versions, ref-scoped blob/text/ancestry queries with no checkout, and a real disposable checkout at another ref, for a real git repository, in one tool. Fails clearly if `directory` is not inside a git repository. ACTIONS: status (working tree state, ahead/behind tracking), log (recent commits, bounded by maxCount), diff (unified diff against `ref`, defaulting to HEAD, bounded by maxBytes), compare-symbol (a named symbol's own declaration text diffed between fromRef and toRef, or fromRef and the current working tree when toRef is omitted -- tree-sitter syntactic tier only, TypeScript/JavaScript files only, no project-aware cross-reference resolution), show (a path's exact blob content at `ref`, no checkout), grep-ref (text search across `ref`'s own tree, no checkout -- the ref-scoped equivalent of search_code), ls-ref (every file path in `ref`'s own tree, no checkout), is-ancestor (is `ancestorRef` a real ancestor of, or the same commit as, `ref` -- the backport/reachability check \"was this fix ported to this branch\" actually needs), worktree-add (materializes `ref` as a real, read-only project via a detached git worktree and returns its own `directory` -- pass that straight to find_symbols/search_code/this tool itself for full semantic queries against another branch/commit, not just text), worktree-remove (releases and deletes a worktree-add-created checkout -- `directory` is that checkout's own returned directory, not the source repo's).",
+				"Working tree status, recent commit log, unified diff, one symbol's own declaration diff across two versions, ref-scoped blob/text/ancestry queries with no checkout, and a real disposable checkout at another ref, for a real git repository, in one tool. Fails clearly if `directory` is not inside a git repository. ACTIONS: status (working tree state, ahead/behind tracking), log (recent commits, bounded by maxCount), diff (unified diff against `ref`, defaulting to HEAD, bounded by maxBytes), compare-symbol (a named symbol's own declaration text diffed between fromRef and toRef, or fromRef and the current working tree when toRef is omitted -- tree-sitter syntactic tier only, TypeScript/JavaScript files only, no project-aware cross-reference resolution), show (a path's exact blob content at `ref`, no checkout), grep-ref (text search across `ref`'s own tree, no checkout -- the ref-scoped equivalent of search_code), grep-history (bounded extended-regex search across commit trees reachable from all refs, with topological paging and commit provenance), ls-ref (every file path in `ref`'s own tree, no checkout), is-ancestor (is `ancestorRef` a real ancestor of, or the same commit as, `ref` -- the backport/reachability check \"was this fix ported to this branch\" actually needs), worktree-add (materializes `ref` as a real, read-only project via a detached git worktree and returns its own `directory` -- pass that straight to find_symbols/search_code/this tool itself for full semantic queries against another branch/commit, not just text), worktree-remove (releases and deletes a worktree-add-created checkout -- `directory` is that checkout's own returned directory, not the source repo's).",
 			promptSnippet:
 				"Show a repository's status, log, diff, one symbol's diff across versions, a ref-scoped blob/text/ancestry query, or a real checkout at another ref",
 			promptGuidelines: [
-				"maxCount is required for action=log; maxBytes is required for action=diff/compare-symbol/grep-ref -- every bounded query needs its bound stated explicitly, never defaulted silently.",
+				"maxCount is required for action=log; maxBytes is required for action=diff/compare-symbol/grep-ref/grep-history -- every bounded query needs its bound stated explicitly, never defaulted silently.",
 				"path, symbol, and fromRef are required for action=compare-symbol; toRef is optional and means 'the current working tree' when omitted.",
 				"ref is required for action=worktree-add. A repeated worktree-add for the same (directory, ref) reuses the existing checkout unless forceRefresh is set -- use that when ref is a branch that may have moved.",
 				"action=worktree-remove's directory is worktree-add's own returned directory, never the source repo's -- always call it once done with a worktree to reclaim disk.",
-				"ref and path are required for action=show; ref and pattern (maxMatches, maxBytes) are required for action=grep-ref; ref (maxResults) is required for action=ls-ref; ancestorRef and ref are required for action=is-ancestor. None of the four checks anything out -- prefer them over worktree-add/find_symbols for a quick existence/text/ancestry answer.",
+				"ref and path are required for action=show; ref and pattern (maxMatches, maxBytes) are required for action=grep-ref; pattern, commitOffset, maxCommits, maxMatches, maxBytes, and deadlineMs are required for action=grep-history; ref (maxResults) is required for action=ls-ref; ancestorRef and ref are required for action=is-ancestor. These actions inspect Git objects directly with no checkout.",
 			],
 			parameters: Type.Object({
-				action: Type.String({ description: "status | log | diff | compare-symbol | show | grep-ref | ls-ref | is-ancestor | worktree-add | worktree-remove" }),
+				action: Type.String({
+					description: "status | log | diff | compare-symbol | show | grep-ref | grep-history | ls-ref | is-ancestor | worktree-add | worktree-remove",
+				}),
 				directory: Type.String({ description: "Directory inside the repository to check, absolute or relative to the current working directory" }),
 				maxCount: Type.Optional(Type.Number({ description: "Maximum number of commits to return, most recent first -- required for action=log" })),
 				ref: Type.Optional(
@@ -1376,7 +1719,9 @@ export default function (pi: ExtensionAPI) {
 				),
 				maxBytes: Type.Optional(
 					Type.Number({
-						description: "Maximum diff/comparison/grep output size in bytes before truncating -- required for action=diff/compare-symbol/grep-ref",
+						minimum: 1,
+						maximum: 8 * 1024 * 1024,
+						description: "Maximum diff/comparison/grep output size in bytes before truncating -- required for action=diff/compare-symbol/grep-ref/grep-history",
 					}),
 				),
 				path: Type.Optional(
@@ -1392,14 +1737,24 @@ export default function (pi: ExtensionAPI) {
 						description: "action=worktree-add only: recreate an already-reused worktree at ref's current tip instead of returning the existing one",
 					}),
 				),
-				pattern: Type.Optional(Type.String({ description: "Text pattern to search for -- required for action=grep-ref" })),
+				pattern: Type.Optional(
+					Type.String({ maxLength: 4096, description: "Pattern to search for -- required for grep-ref; an extended regular expression for grep-history" }),
+				),
 				pathspecs: Type.Optional(
-					Type.Array(Type.String(), {
+					Type.Array(Type.String({ minLength: 1, maxLength: 1024 }), {
+						maxItems: 64,
 						description:
-							'Narrows action=grep-ref (glob-based, e.g. "*.go") or action=ls-ref (prefix-based, e.g. "pkg/dpll"); omitted searches/lists the whole tree',
+							'Narrows action=grep-ref/grep-history (glob-based, e.g. "*.go") or action=ls-ref (prefix-based, e.g. "pkg/dpll"); omitted searches/lists the whole tree',
 					}),
 				),
-				maxMatches: Type.Optional(Type.Number({ description: "Maximum grep matches to return -- required for action=grep-ref" })),
+				maxMatches: Type.Optional(
+					Type.Number({ minimum: 1, maximum: 10_000, description: "Maximum grep matches to return -- required for action=grep-ref/grep-history" }),
+				),
+				commitOffset: Type.Optional(
+					Type.Number({ minimum: 0, maximum: 1_000_000, description: "Number of topologically ordered commits to skip -- required for action=grep-history" }),
+				),
+				maxCommits: Type.Optional(Type.Number({ minimum: 1, maximum: 512, description: "Maximum commit trees to search -- required for action=grep-history" })),
+				deadlineMs: Type.Optional(Type.Number({ minimum: 1, maximum: 120_000, description: "Wall-clock budget -- required for action=grep-history" })),
 				maxResults: Type.Optional(Type.Number({ description: "Maximum file paths to return -- required for action=ls-ref" })),
 				ancestorRef: Type.Optional(Type.String({ description: "The candidate ancestor ref -- required for action=is-ancestor" })),
 			}),
@@ -1456,6 +1811,32 @@ export default function (pi: ExtensionAPI) {
 					const details: GitToolDetails = { action: "grep-ref", grep };
 					return { content: [{ type: "text", text: JSON.stringify(grep) }], details };
 				}
+				if (params.action === "grep-history") {
+					if (!params.pattern) throw new Error("git action=grep-history requires pattern");
+					if (
+						params.commitOffset === undefined ||
+						params.maxCommits === undefined ||
+						params.maxMatches === undefined ||
+						params.maxBytes === undefined ||
+						params.deadlineMs === undefined
+					)
+						throw new Error("git action=grep-history requires commitOffset, maxCommits, maxMatches, maxBytes, and deadlineMs");
+					const historyGrep = await gitOperations.grepHistory(
+						directory,
+						params.pattern,
+						params.pathspecs,
+						{
+							commitOffset: params.commitOffset,
+							maxCommits: params.maxCommits,
+							maxMatches: params.maxMatches,
+							maxBytes: params.maxBytes,
+							deadlineMs: params.deadlineMs,
+						},
+						vehicleCall,
+					);
+					const details: GitToolDetails = { action: "grep-history", historyGrep };
+					return { content: [{ type: "text", text: JSON.stringify(historyGrep) }], details };
+				}
 				if (params.action === "ls-ref") {
 					if (!params.ref) throw new Error("git action=ls-ref requires ref");
 					if (params.maxResults === undefined) throw new Error("git action=ls-ref requires maxResults");
@@ -1497,7 +1878,7 @@ export default function (pi: ExtensionAPI) {
 			name: "search_code",
 			label: "Search Code",
 			description:
-				"Multi-file text/regex search scoped to a real project directory, backed by ripgrep -- respects .gitignore, skips node_modules/.git/build output. Bounded by maxMatches and maxBytes; results are cached.",
+				"Multi-file text/regex search scoped to a real project directory. Uses a bounded resident FFF index when ready and explicit ripgrep loading/stale/degraded fallback otherwise; respects ignore rules and skips generated dependency output. Bounded by maxMatches and maxBytes; results include lexical provenance.",
 			promptSnippet: "Search a project's files for a pattern",
 			parameters: Type.Object({
 				directory: Type.String({ description: "Directory inside the project to search, absolute or relative to the current working directory" }),
@@ -1508,8 +1889,10 @@ export default function (pi: ExtensionAPI) {
 			async execute(_toolCallId, params) {
 				const directory = resolve(cwd, params.directory);
 				const result = await searchOperations.search(params.query, directory, params.maxMatches, params.maxBytes);
-				const text =
+				const matches =
 					result.matches.length === 0 ? "No matches found." : result.matches.map((m) => `${m.path}:${m.lineNumber}: ${m.line.replace(/\n$/, "")}`).join("\n");
+				const source = result.provenance ? `lexical via ${result.provenance.backend} (${result.provenance.indexState})\n` : "";
+				const text = `${source}${matches}`;
 				return { content: [{ type: "text", text }], details: { result } };
 			},
 			renderCall(args, theme, context) {
@@ -2114,7 +2497,7 @@ export default function (pi: ExtensionAPI) {
 			name: "search_code_across_projects",
 			label: "Search Code Across Projects",
 			description:
-				"Fans out a ripgrep-backed text/regex search across several explicitly-named project directories at once and reports one outcome per project. Directories are required and explicit -- never every project this daemon happens to have registered, which can include unrelated projects from other concurrent sessions. Each directory resolves to its OWN nearest project root (package.json/tsconfig.json/go.mod/Cargo.toml/...), not the outer repo's git root -- sibling packages under one monorepo stay distinct scopes rather than collapsing into one. A result's collapsedWith lists any other requested directories that genuinely did resolve to the same workspace; empty means it got its own.",
+				"Fans out bounded indexed lexical text/regex search with explicit ripgrep fallback provenance across several explicitly-named project directories at once and reports one outcome per project. Directories are required and explicit -- never every project this daemon happens to have registered, which can include unrelated projects from other concurrent sessions. Each directory resolves to its OWN nearest project root (package.json/tsconfig.json/go.mod/Cargo.toml/...), not the outer repo's git root -- sibling packages under one monorepo stay distinct scopes rather than collapsing into one. A result's collapsedWith lists any other requested directories that genuinely did resolve to the same workspace; empty means it got its own.",
 			promptSnippet: "Search for a pattern across several projects at once",
 			parameters: Type.Object({
 				directories: Type.Array(Type.String(), { description: "Project directories to search, each absolute or relative to the current working directory" }),

package/extension/src/search/rendering.ts

@@ -12,7 +12,9 @@ export function formatSearchCall(args: { directory?: unknown; query?: unknown },
 }
 
 export function formatSearchResult(result: TextSearchResult | undefined, expanded: boolean, theme: LectorTheme): string {
-	if (!result || result.matches.length === 0) return theme.fg("dim", "No matches found.");
+	if (!result) return theme.fg("dim", "No matches found.");
+	const provenance = result.provenance ? theme.fg("dim", `lexical via ${result.provenance.backend} (${result.provenance.indexState})`) : undefined;
+	if (result.matches.length === 0) return [provenance, theme.fg("dim", "No matches found.")].filter((line) => line !== undefined).join("\n");
 	const lines = renderTruncatedList({
 		items: result.matches,
 		expanded,
@@ -22,5 +24,5 @@ export function formatSearchResult(result: TextSearchResult | undefined, expande
 		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,
 	});
-	return lines.join("\n");
+	return [provenance, ...lines].filter((line) => line !== undefined).join("\n");
 }

package/extension/src/symbol-annotation/operations.ts

@@ -13,6 +13,8 @@ export interface AnnotationAnchorInput {
 	readonly character: number;
 }
 
+export type AnnotationAutoPopulationOptions = Pick<OperationInputs["workspace.createAnnotation"], "autoPopulate" | "maxFiles" | "maxSymbolsPerFile">;
+
 /**
  * Thin wrappers over Lector's annotation operations. Every operation resolves its workspace from
  * its own `path` parameter via workspaceForAnnotationPath -- a real project directory or an
@@ -29,6 +31,7 @@ export interface SymbolAnnotationOperations {
 		body: string,
 		anchors: readonly AnnotationAnchorInput[],
 		call: LectorVehicleCall,
+		autoPopulation?: AnnotationAutoPopulationOptions,
 	): Promise<OperationOutputs["workspace.createAnnotation"]>;
 	get(path: string, id: string, call: LectorVehicleCall): Promise<OperationOutputs["workspace.getAnnotation"]>;
 	list(
@@ -44,6 +47,7 @@ export interface SymbolAnnotationOperations {
 		body: string,
 		anchors: readonly AnnotationAnchorInput[],
 		call: LectorVehicleCall,
+		autoPopulation?: AnnotationAutoPopulationOptions,
 	): Promise<OperationOutputs["workspace.refreshAnnotation"]>;
 	scrub(path: string, id: string, call: LectorVehicleCall): Promise<OperationOutputs["workspace.scrubAnnotation"]>;
 	restore(path: string, id: string, call: LectorVehicleCall): Promise<OperationOutputs["workspace.restoreAnnotation"]>;
@@ -54,13 +58,13 @@ export interface SymbolAnnotationOperations {
 
 export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperations {
 	return {
-		async create(path, subtype, title, body, anchors, call) {
+		async create(path, subtype, title, body, anchors, call, autoPopulation) {
 			return withWorkspace(
 				() => workspaceForAnnotationPath(path),
 				({ workspaceId }) =>
 					invokeLectorVehicleOperation<OperationOutputs["workspace.createAnnotation"]>(
 						"workspace.createAnnotation",
-						{ workspaceId, subtype, title, body, anchors },
+						{ workspaceId, subtype, title, body, anchors, ...autoPopulation },
 						ANNOTATION_WRITE_PERMISSIONS,
 						call,
 					),
@@ -90,13 +94,13 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 					),
 			);
 		},
-		async refresh(path, id, subtype, title, body, anchors, call) {
+		async refresh(path, id, subtype, title, body, anchors, call, autoPopulation) {
 			return withWorkspace(
 				() => workspaceForAnnotationPath(path),
 				({ workspaceId }) =>
 					invokeLectorVehicleOperation<OperationOutputs["workspace.refreshAnnotation"]>(
 						"workspace.refreshAnnotation",
-						{ workspaceId, id, subtype, title, body, anchors },
+						{ workspaceId, id, subtype, title, body, anchors, ...autoPopulation },
 						ANNOTATION_WRITE_PERMISSIONS,
 						call,
 					),

package/extension/src/vehicle-client.ts

@@ -29,9 +29,11 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 type VehicleClientConnector = () => Promise<VehicleClient>;
 
-function connectLectorVehicleClient(): Promise<VehicleClient> {
+async function connectLectorVehicleClient(): Promise<VehicleClient> {
 	const { host, port, token } = resolveLectorDaemonConnection();
-	return Promise.resolve(new RemoteVehicleClient({ baseUrl: `http://${host}:${port}`, token }));
+	const client = new RemoteVehicleClient({ baseUrl: `http://${host}:${port}`, token });
+	await client.negotiate({ minimumVersion: 1, maximumVersion: 1, requiredCapabilities: [], optionalCapabilities: [] });
+	return client;
 }
 
 function resolveLectorVehicleIdentity() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.13.9",
+	"version": "0.13.11",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -22,9 +22,9 @@
 		"@danypops/vehicle-client-pi": "^0.45.0"
 	},
 	"dependencies": {
-		"@danypops/lector": "^0.20.0",
-		"@danypops/vehicle-client": "^0.10.3",
-		"@danypops/vehicle-core": "^0.17.1",
+		"@danypops/lector": "^0.20.4",
+		"@danypops/vehicle-client": "^0.10.8",
+		"@danypops/vehicle-core": "^0.19.1",
 		"malevich-tui-components": "^0.32.1",
 		"picomatch": "^4.0.5"
 	},