@danypops/pi-lector 0.16.0 → 0.17.2

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

@@ -1,6 +1,7 @@
 import type {
 	CallHierarchyEntry,
 	Diagnostic,
+	DiagnosticContext,
 	DocumentSymbolEntry,
 	Hover,
 	IncomingCall,
@@ -153,8 +154,21 @@ export function formatDiagnosticsCall(args: { path?: unknown }, theme: LectorThe
 	return `${theme.fg("toolTitle", theme.bold(presentationTitle("diagnostics")))} ${theme.fg("accent", path)}`;
 }
 
-export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | undefined, expanded: boolean, theme: LectorTheme): string {
-	if (!diagnostics || diagnostics.length === 0) return theme.fg("success", "No diagnostics.");
+/** Describes project confidence separately from native diagnostics, optionally including setup actions. */
+export function describeDiagnosticContext(context: DiagnosticContext | undefined, expanded = true): string {
+	const lines = [`Project context: ${context?.confidence ?? "unknown"}`];
+	if (expanded) for (const finding of context?.setupFindings ?? []) lines.push(`setup ${finding.kind}: ${finding.action}`);
+	return lines.join("\n");
+}
+
+export function formatDiagnosticsResult(
+	diagnostics: readonly Diagnostic[] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+	context?: DiagnosticContext,
+): string {
+	const contextText = context ? `${describeDiagnosticContext(context, expanded)}\n` : "";
+	if (!diagnostics || diagnostics.length === 0) return contextText + theme.fg("success", "No diagnostics.");
 
 	const lines = [
 		theme.fg("muted", `${diagnostics.length} diagnostic${diagnostics.length === 1 ? "" : "s"}:`),
@@ -171,7 +185,7 @@ export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | und
 			moreLine: moreLine(theme),
 		}),
 	];
-	return lines.join("\n");
+	return contextText + lines.join("\n");
 }
 
 function formatPathCall(toolName: string, args: { path?: unknown }, theme: LectorTheme, qualifier = ""): string {

package/extension/src/index.ts

@@ -4,7 +4,6 @@ import { resolve } from "node:path";
 import type {
 	CachedRepositoryPage,
 	ContentHash,
-	Diagnostic,
 	DocumentSymbolEntry,
 	EditOutcome,
 	FindFilesResult,
@@ -53,6 +52,7 @@ import { formatApplyPatchCall, formatApplyPatchResult } from "./apply-patch/rend
 import { createLectorCodeIntelligenceOperations } from "./code-intelligence/operations.ts";
 import {
 	type CallHierarchyToolDetails,
+	describeDiagnosticContext,
 	formatCallHierarchyCall,
 	formatCallHierarchyResult,
 	formatCodeActionApplyCall,
@@ -324,8 +324,11 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	let cachingOverlay: CachingOverlay | undefined;
+	let disposeWorkspaceObserver: (() => void) | undefined;
 	pi.on("session_shutdown", (_event, ctx) => {
 		sessionGeneration++;
+		disposeWorkspaceObserver?.();
+		disposeWorkspaceObserver = undefined;
 		cacheStatesByRoot.clear();
 		monitoringRoots.clear();
 		lastInjectedSummary = undefined;
@@ -343,7 +346,11 @@ export default function (pi: ExtensionAPI) {
 		monitoringRoots.clear();
 		lastInjectedSummary = undefined;
 		uiContext = ctx;
-		setNewWorkspaceObserver((root) => startMonitoringRoot(root, ctx));
+		disposeWorkspaceObserver?.();
+		const observerGeneration = sessionGeneration;
+		disposeWorkspaceObserver = setNewWorkspaceObserver((root) => {
+			if (sessionGeneration === observerGeneration) startMonitoringRoot(root, ctx);
+		});
 		if (ctx.hasUI) {
 			// The persistent widget counterpart to the single-line "lector-cache" status above.
 			// Ownership is the Pi session, not cwd: one session may legitimately touch several roots.
@@ -437,7 +444,7 @@ export default function (pi: ExtensionAPI) {
 			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.",
+				"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. Returns workspace-relative paths, excluding dependency and escaped symlink targets; inspect a package through its separately registered workspace. Checks generation hashes against bounded current source snapshots; stale or unverified declarations are excluded and completeness is reduced. 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.",
@@ -771,7 +778,8 @@ export default function (pi: ExtensionAPI) {
 		registerLectorTool({
 			name: "diagnostics",
 			label: "Diagnostics",
-			description: "List every error and warning a language server currently knows about for one file, as of its last analysis.",
+			description:
+				"List native errors and warnings with bounded project-context confidence, separate setup findings, synchronized source hash and reported document versions. Server readiness is not compiler verification; unreported configuration stays unknown.",
 			promptSnippet: "List current errors/warnings for one file",
 			promptGuidelines: ["Use diagnostics after an edit to check for new type errors in one specific file, instead of running a full project build."],
 			parameters: Type.Object({ path: Type.String({ description: "Absolute or cwd-relative path to the file" }) }),
@@ -782,7 +790,10 @@ export default function (pi: ExtensionAPI) {
 					details.diagnostics.length === 0
 						? "No diagnostics."
 						: details.diagnostics.map((d) => `${d.severity} ${d.range.path}:${d.range.start.line}:${d.range.start.character} -- ${d.message}`).join("\n");
-				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
+				return {
+					content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${describeDiagnosticContext(details.context)}\n${text}` }],
+					details,
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -798,9 +809,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "diagnostics failed"), 0, 0);
 				}
-				const details = result.details as { diagnostics?: readonly Diagnostic[]; provenance?: IntelligenceProvenance } | undefined;
+				const details = result.details as OperationOutputs["workspace.diagnostics"] | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(renderIntelligenceSource(formatDiagnosticsResult(details?.diagnostics, expanded, theme), details?.provenance, theme));
+				text.setText(renderIntelligenceSource(formatDiagnosticsResult(details?.diagnostics, expanded, theme, details?.context), details?.provenance, theme));
 				return text;
 			},
 		});

package/extension/src/lector-client.ts

@@ -61,8 +61,13 @@ const retryingClient: RetryingClient<LectorClient> = createRetryingClient(() =>
  */
 let onNewWorkspace: ((root: string) => void) | undefined;
 
-export function setNewWorkspaceObserver(observer: ((root: string) => void) | undefined): void {
-	onNewWorkspace = observer;
+/** Registers a workspace observer and returns an idempotent disposer that preserves later registrations. */
+export function setNewWorkspaceObserver(observer: ((root: string) => void) | undefined): () => void {
+	const registration = observer ? (root: string) => observer(root) : undefined;
+	onNewWorkspace = registration;
+	return () => {
+		if (onNewWorkspace === registration) onNewWorkspace = undefined;
+	};
 }
 
 export interface RetryingLectorClient {

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

@@ -1,14 +1,18 @@
-import type { MutationHistoryEntry } from "@danypops/lector";
+import type { MutationHistoryEntry, MutationTransactionLookupOutcome } from "@danypops/lector";
 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 }[];
-}
+export type MutationTransactionRevertOutcome =
+	| {
+			readonly status: "reverted";
+			readonly transactionId: string;
+			readonly reverted: readonly { readonly path: string; readonly newHash: string | null }[];
+	  }
+	| { readonly status: "stale"; readonly transactionId: string; readonly stalePaths: readonly string[] }
+	| Extract<MutationTransactionLookupOutcome, { readonly status: "evicted" | "wrong-workspace" | "unknown" }>;
 
 /** 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"];
@@ -32,24 +36,14 @@ async function listResolvedHistory(
 	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 path = toWorkspaceRelativePath(root, absolutePath);
+	const page = await 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);
+	return page.entries;
 }
 
 export function createMutationHistoryOperations(): MutationHistoryOperations {
@@ -84,13 +78,23 @@ export function createMutationHistoryOperations(): MutationHistoryOperations {
 		revertTransaction(absolutePath, transactionId, call) {
 			return withWorkspace(
 				() => workspaceForPath(absolutePath),
-				({ workspaceId }) =>
-					invokeLectorVehicleOperation<MutationTransactionRevertOutcome>(
+				async ({ workspaceId }) => {
+					const lookup = await invokeLectorVehicleOperation<MutationTransactionLookupOutcome>(
+						"workspace.mutationTransaction",
+						{ workspaceId, transactionId },
+						MUTATION_HISTORY_READ_PERMISSIONS,
+						call,
+					);
+					if (lookup.status === "stale") return { status: "stale", transactionId, stalePaths: lookup.stalePaths };
+					if (lookup.status !== "ready") return lookup;
+					const reverted = await invokeLectorVehicleOperation<Omit<Extract<MutationTransactionRevertOutcome, { status: "reverted" }>, "status">>(
 						"workspace.revertMutationTransaction",
 						{ workspaceId, transactionId },
 						MUTATION_HISTORY_WRITE_PERMISSIONS,
 						call,
-					),
+					);
+					return { status: "reverted", ...reverted };
+				},
 			);
 		},
 	};

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

@@ -12,9 +12,23 @@ export function formatMutationHistoryList(entries: readonly MutationHistoryEntry
 }
 
 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");
+	switch (outcome.status) {
+		case "reverted":
+			return [
+				`${originalTransactionId} reverted atomically; revert recorded as transaction ${outcome.transactionId}`,
+				...outcome.reverted.map((entry) => `${entry.path} -> ${entry.newHash ?? "(deleted)"}`),
+			].join("\n");
+		case "stale":
+			return `${originalTransactionId} is stale at ${outcome.stalePaths.length} path(s); no files were reverted\n${outcome.stalePaths.join("\n")}`;
+		case "evicted":
+			return `${originalTransactionId} cannot be reverted because its bounded process-local history was evicted`;
+		case "wrong-workspace":
+			return `${originalTransactionId} belongs to a different registered workspace; use a path from that workspace`;
+		case "unknown":
+			return `${originalTransactionId} is unknown; mutation history is process-local and is lost after daemon restart`;
+		default: {
+			const exhaustive: never = outcome;
+			return exhaustive;
+		}
+	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.16.0",
+	"version": "0.17.2",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -22,7 +22,7 @@
 		"@danypops/vehicle-client-pi": "^0.45.0"
 	},
 	"dependencies": {
-		"@danypops/lector": "^0.22.0",
+		"@danypops/lector": "^0.23.1",
 		"@danypops/vehicle-client": "^0.10.8",
 		"@danypops/vehicle-core": "^0.19.1",
 		"malevich-tui-components": "^0.32.1",