@danypops/pi-lector 0.1.0

package/extension/src/lector-client.ts

@@ -0,0 +1,175 @@
+import { dirname, parse } from "node:path";
+import {
+	connectLectorClient,
+	type LectorClient,
+	type OperationInputs,
+	type OperationName,
+	type OperationOutputs,
+	remoteErrorIs,
+	type WorkspaceId,
+} from "@danypops/lector";
+import { nearestGitRoot } from "./nearest-workspace-root.ts";
+
+/**
+ * Lazily connects to a running Lector daemon and caches, per project root,
+ * the workspaceId that root registers under. Never auto-spawns the daemon:
+ * a clear "start it with `lector serve`" error is preferable to guessing
+ * at a lifecycle the user didn't ask for. A failed connection attempt is
+ * not cached, so the very next tool call retries once the daemon is
+ * actually running.
+ *
+ * The daemon binds a new random port on every restart. A client resolved
+ * once and cached for the rest of the session would otherwise point at a
+ * dead port after any later restart -- lectorClient()'s returned .call()
+ * detects that on the failing call itself (not just the first connection
+ * attempt) and retries once against a freshly re-resolved client, matching
+ * the pattern already proven in this house's papyrusClient()/callService().
+ */
+
+type ClientConnector = () => Promise<LectorClient>;
+
+let connector: ClientConnector = () => connectLectorClient();
+let cachedClient: Promise<LectorClient> | undefined;
+const workspaceIdByRoot = new Map<string, WorkspaceId>();
+
+async function resolveClient(): Promise<LectorClient> {
+	if (!cachedClient) {
+		cachedClient = connector().catch((error: unknown) => {
+			cachedClient = undefined;
+			throw error;
+		});
+	}
+	return cachedClient;
+}
+
+/**
+ * True when `error` means the connection itself is bad (the daemon
+ * restarted on a new port since this client was cached, or died outright)
+ * -- worth invalidating the cache and retrying once. False for a genuine
+ * domain-level rejection (e.g. UnknownWorkspace), which a retry cannot fix
+ * and would only mask.
+ */
+function isStaleConnectionError(error: unknown): boolean {
+	if (error instanceof TypeError) return true; // fetch()'s own connection-refused/DNS-failure shape
+	if (!(error instanceof Error)) return false;
+	if (error.name === "AbortError" || error.name === "TimeoutError") return true;
+	return /fetch failed|unable to connect|network|socket|ECONNRESET|ECONNREFUSED|connection refused/i.test(error.message);
+}
+
+export interface RetryingLectorClient {
+	call<Name extends OperationName>(operation: Name, input: OperationInputs[Name]): Promise<OperationOutputs[Name]>;
+}
+
+export async function lectorClient(): Promise<RetryingLectorClient> {
+	return {
+		async call(operation, input) {
+			for (let attempt = 0; attempt < 2; attempt++) {
+				const client = await resolveClient();
+				try {
+					return await client.call(operation, input);
+				} catch (error) {
+					cachedClient = undefined;
+					if (attempt === 1 || !isStaleConnectionError(error)) throw error;
+				}
+			}
+			throw new Error("Lector daemon client retry exhausted");
+		},
+	};
+}
+
+export interface ResolvedWorkspace {
+	workspaceId: WorkspaceId;
+	/** The registered root the target path is relative to -- a git root or the filesystem root, never a fixed session cwd. */
+	root: string;
+}
+
+async function workspaceForRoot(root: string): Promise<ResolvedWorkspace> {
+	const cached = workspaceIdByRoot.get(root);
+	if (cached) return { workspaceId: cached, root };
+	const client = await lectorClient();
+	const { workspaceId } = await client.call("workspace.registerPath", { path: root });
+	workspaceIdByRoot.set(root, workspaceId);
+	return { workspaceId, root };
+}
+
+/**
+ * Resolve (and cache) the Lector workspace for whatever project actually
+ * contains this absolute FILE path -- never a session's original cwd.
+ * Files under the same repo share one cached workspace+id; a path under a
+ * different repo (or outside any repo entirely) gets its own, registered
+ * on demand via workspace.registerPath. This is what makes read/write/edit
+ * work for *any* absolute path in one session, exactly like Pi's built-in
+ * tools always have -- not just paths under wherever the session started.
+ *
+ * Falls back to the filesystem root when no enclosing git repo exists:
+ * unlike workspaceForDirectory, any absolute path is fair game here (a
+ * dotfile in $HOME, a /tmp scratch file), so there is no smaller sensible
+ * boundary to prefer over "the whole filesystem" -- this is what pi's own
+ * built-in read/write/edit already allow.
+ */
+export function workspaceForPath(absolutePath: string): Promise<ResolvedWorkspace> {
+	const directory = dirname(absolutePath);
+	const root = nearestGitRoot(directory) ?? parse(directory).root;
+	return workspaceForRoot(root);
+}
+
+/**
+ * Same resolution, starting from a directory (e.g. a symbol query's cwd)
+ * rather than a file's own path -- but falls back to the directory itself,
+ * never the filesystem root, when no enclosing git repo exists. Widening a
+ * find_symbols query's scope to the entire filesystem just because a
+ * project isn't a git repo would be both wrong (nothing meaningful to find
+ * outside the project) and unbounded (scanning the whole disk).
+ */
+export function workspaceForDirectory(directory: string): Promise<ResolvedWorkspace> {
+	const root = nearestGitRoot(directory) ?? directory;
+	return workspaceForRoot(root);
+}
+
+/**
+ * For any operation that spawns a real language server (find_symbols,
+ * goToDefinition, documentSymbols, diagnostics, ...) -- never workspaceForPath,
+ * whose filesystem-root fallback would point a real server at scanning the
+ * whole disk. Falls back to the file's own containing directory instead,
+ * same bound as workspaceForDirectory.
+ */
+export function workspaceForCodeIntelligencePath(absolutePath: string): Promise<ResolvedWorkspace> {
+	return workspaceForDirectory(dirname(absolutePath));
+}
+
+/**
+ * Resolves a workspace via `resolve`, then calls `perform` with it. A daemon
+ * restart wipes its in-memory workspace registry (workspace ids are not
+ * persisted across restarts by design), but this module's own workspaceId
+ * cache does not know that on its own -- a call through a stale cached id
+ * fails with UnknownWorkspace even though the underlying files on disk
+ * never changed. On exactly that failure, the stale cache entry is dropped
+ * and the whole flow (resolve, then perform) retries once against a
+ * freshly re-registered workspace -- re-registering the same root always
+ * yields the same workspaceId (deriveWorkspaceId is a deterministic hash
+ * of the path), so this is a safe, idempotent recovery, not a guess.
+ */
+export async function withWorkspace<T>(resolve: () => Promise<ResolvedWorkspace>, perform: (resolved: ResolvedWorkspace) => Promise<T>): Promise<T> {
+	for (let attempt = 0; attempt < 2; attempt++) {
+		const resolved = await resolve();
+		try {
+			return await perform(resolved);
+		} catch (error) {
+			if (attempt === 1 || !remoteErrorIs(error, "UnknownWorkspace")) throw error;
+			workspaceIdByRoot.delete(resolved.root);
+		}
+	}
+	throw new Error("Lector workspace resolution retry exhausted");
+}
+
+export function setLectorClientConnectorForTests(value: ClientConnector): void {
+	cachedClient = undefined;
+	workspaceIdByRoot.clear();
+	connector = value;
+}
+
+export function resetLectorClientForTests(): void {
+	cachedClient = undefined;
+	workspaceIdByRoot.clear();
+	connector = () => connectLectorClient();
+}

package/extension/src/lector-tui-theme.ts

@@ -0,0 +1,35 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/**
+ * The minimal slice of pi-coding-agent's real Theme class every Lector-tool
+ * rendering module in this package actually uses -- not the full class
+ * (15+ methods, private fields). Narrower, and a plain pass-through object
+ * satisfies it directly in tests with no cast, since Theme's real fg/bold
+ * already structurally match. Shared across find_symbols, document_symbols,
+ * go_to_definition, find_references, and hover's rendering so each doesn't
+ * redeclare the same interface.
+ */
+export interface LectorTheme {
+	fg(color: ThemeColor, text: string): string;
+	bold(text: string): string;
+}
+
+/** Maps a symbol/declaration kind to the closest semantic syntax-highlighting color already in the theme palette. */
+const KIND_COLOR: Record<string, ThemeColor> = {
+	function: "syntaxFunction",
+	method: "syntaxFunction",
+	class: "syntaxType",
+	interface: "syntaxType",
+	"type-alias": "syntaxType",
+	enum: "syntaxType",
+	variable: "syntaxVariable",
+};
+
+export function colorForKind(kind: string): ThemeColor {
+	return KIND_COLOR[kind] ?? "muted";
+}
+
+/** `path:line:character`, dimmed -- the one consistent way every Lector tool renders a file position. */
+export function formatLocation(theme: LectorTheme, path: string, line: number, character: number): string {
+	return theme.fg("dim", `${path}:${line}:${character}`);
+}

package/extension/src/nearest-workspace-root.ts

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+
+/**
+ * The nearest enclosing git repository root starting from (and including)
+ * a given directory, or undefined if none is found (e.g. /tmp scratch
+ * files, dotfiles outside any repo). Callers choose their own fallback --
+ * see lector-client.ts's workspaceForPath (falls back to the filesystem
+ * root: any absolute path is fair game for read/write/edit, exactly as
+ * Pi's built-in tools already allow) vs. workspaceForDirectory (falls back
+ * to the directory itself: widening a symbol-search scope all the way to
+ * the entire filesystem when a project isn't a git repo would be absurd).
+ *
+ * This -- not a Pi session's original cwd -- is Lector's real workspace
+ * granularity. A session routinely touches many unrelated repos, sibling
+ * projects, and scratch paths in one run; pi's built-in read/write/edit
+ * tools have never restricted which absolute path can be touched, and
+ * Lector must not either. (Real, shipped bug this fixes: read/write/edit
+ * hard-locked to whatever directory the session happened to start in,
+ * refusing every legitimate path outside it with a "Lector-registered
+ * workspace root" error -- discovered live, in a separate session, working
+ * against a completely different, unrelated repository.)
+ */
+export function nearestGitRoot(startDirectory: string): string | undefined {
+	let dir = startDirectory;
+	const fsRoot = parse(dir).root;
+	while (dir !== fsRoot) {
+		if (existsSync(join(dir, ".git"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) break; // defensive: dirname must be strictly ascending
+		dir = parent;
+	}
+	return existsSync(join(fsRoot, ".git")) ? fsRoot : undefined;
+}

package/extension/src/read-operations.ts

@@ -0,0 +1,73 @@
+import { constants } from "node:fs";
+import { access as fsAccess, readFile as fsReadFile } from "node:fs/promises";
+import type { ReadOperations } from "@earendil-works/pi-coding-agent";
+import { lectorClient, withWorkspace, workspaceForPath } from "./lector-client.ts";
+import { toWorkspaceRelativePath } from "./workspace-relative-path.ts";
+
+/**
+ * Lector's core domain (RawRead/ExpectedHashEdit) is deliberately text-only
+ * for now -- binary content is an open design question. Images are the one
+ * case pi's built-in read tool must still handle correctly, so they read
+ * directly from the local filesystem, bypassing Lector entirely, rather
+ * than corrupting binary bytes through a text round-trip. Extension-based,
+ * not content-sniffed: good enough to match pi's own defaultReadOperations
+ * behavior for the common case without depending on pi-coding-agent's
+ * internal detector.
+ */
+const IMAGE_MIME_TYPES_BY_EXTENSION: Record<string, string> = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".bmp": "image/bmp",
+};
+
+function imageMimeTypeFor(absolutePath: string): string | undefined {
+	const dot = absolutePath.lastIndexOf(".");
+	if (dot === -1) return undefined;
+	return IMAGE_MIME_TYPES_BY_EXTENSION[absolutePath.slice(dot).toLowerCase()];
+}
+
+/**
+ * ReadOperations backed by a running Lector daemon for text; images bypass
+ * Lector (see above). The workspace for each call is resolved from the
+ * absolute path being read, not a fixed cwd -- see workspaceForPath.
+ */
+export function createLectorReadOperations(): ReadOperations {
+	return {
+		async readFile(absolutePath) {
+			if (imageMimeTypeFor(absolutePath)) return fsReadFile(absolutePath);
+
+			return withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, absolutePath);
+					const { content } = await client.call("workspace.rawRead", { workspaceId, path: relativePath });
+					return Buffer.from(content, "utf-8");
+				},
+			);
+		},
+
+		async access(absolutePath) {
+			if (imageMimeTypeFor(absolutePath)) {
+				await fsAccess(absolutePath, constants.R_OK);
+				return;
+			}
+
+			// workspace.rawRead itself rejects a missing entry (WorkspaceEntryNotFound) -- exactly
+			// the "not accessible" signal pi's read/edit tools expect access() to throw for.
+			await withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, absolutePath);
+					await client.call("workspace.rawRead", { workspaceId, path: relativePath });
+				},
+			);
+		},
+
+		detectImageMimeType: (absolutePath) => Promise.resolve(imageMimeTypeFor(absolutePath)),
+	};
+}

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

@@ -0,0 +1,20 @@
+import type { RepoFetchResult } from "@danypops/lector";
+import { lectorClient } from "./lector-client.ts";
+
+/**
+ * Thin wrapper over repo.fetch. No `directory`/workspaceForDirectory resolution here -- unlike
+ * every other tool in this extension, this one doesn't target an existing local directory, it
+ * creates a new registered workspace from a fetched external repo.
+ */
+export interface RepoFetchOperations {
+	fetch(host: string, owner: string, repo: string, ref: string | null): Promise<RepoFetchResult & { workspaceId: string }>;
+}
+
+export function createLectorRepoFetchOperations(): RepoFetchOperations {
+	return {
+		async fetch(host, owner, repo, ref) {
+			const client = await lectorClient();
+			return client.call("repo.fetch", { host, owner, repo, ref });
+		},
+	};
+}

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

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

package/extension/src/search-operations.ts

@@ -0,0 +1,24 @@
+import type { TextSearchResult } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+
+/**
+ * Thin wrapper over workspace.searchText. `directory` is required, same convention as
+ * find_symbols/git operations -- no implicit "whatever the session's cwd is" fallback.
+ */
+export interface SearchOperations {
+	search(query: string, directory: string, maxMatches: number, maxBytes: number): Promise<TextSearchResult>;
+}
+
+export function createLectorSearchOperations(): SearchOperations {
+	return {
+		async search(query, directory, maxMatches, maxBytes) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.searchText", { workspaceId, query, maxMatches, maxBytes });
+				},
+			);
+		},
+	};
+}

package/extension/src/search-rendering.ts

@@ -0,0 +1,21 @@
+import type { TextSearchResult } from "@danypops/lector";
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+const DEFAULT_VISIBLE_MATCHES = 20;
+
+export function formatSearchCall(args: { directory?: unknown; query?: unknown }, theme: LectorTheme): string {
+	const directory = typeof args.directory === "string" ? args.directory : "";
+	const query = typeof args.query === "string" ? args.query : "";
+	return `${theme.fg("toolTitle", theme.bold("search_code"))} ${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", directory)}`;
+}
+
+export function formatSearchResult(result: TextSearchResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.matches.length === 0) return theme.fg("dim", "No matches found.");
+	const displayCount = expanded ? result.matches.length : Math.min(DEFAULT_VISIBLE_MATCHES, result.matches.length);
+	const lines = result.matches.slice(0, displayCount).map((match) => `${theme.fg("accent", match.path)}:${match.lineNumber}: ${match.line.replace(/\n$/, "")}`);
+	const remaining = result.matches.length - displayCount;
+	if (remaining > 0) lines.push(theme.fg("dim", `... ${remaining} more (${keyHint("app.tools.expand", "to expand")})`));
+	if (result.truncated) lines.push(theme.fg("warning", "(search itself was truncated by maxMatches/maxBytes -- results are incomplete)"));
+	return lines.join("\n");
+}

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

@@ -0,0 +1,97 @@
+import type { JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
+
+export interface WorkspaceCacheOperations {
+	status(directory: string, maxFiles: number, maxSymbolsPerFile: number): Promise<WorkspaceCacheStatus>;
+	submit(directory: string, maxFiles: number, maxSymbolsPerFile: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
+	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
+}
+
+export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
+	return {
+		status(directory, maxFiles, maxSymbolsPerFile) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.cacheStatus", { workspaceId, maxFiles, maxSymbolsPerFile });
+				},
+			);
+		},
+		submit(directory, maxFiles, maxSymbolsPerFile) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					const { job } = await client.call("job.submit", {
+						operation: "workspace.populateSymbolGraph",
+						input: { workspaceId, maxFiles, maxSymbolsPerFile },
+						waitMs: 0,
+					});
+					return job;
+				},
+			);
+		},
+		async jobStatus(jobId) {
+			const client = await lectorClient();
+			const { job } = await client.call("job.status", { jobId });
+			return job;
+		},
+	};
+}
+
+export type CachePresentationState =
+	| { readonly status: "not-cached"; readonly reason: string }
+	| { readonly status: "caching"; readonly jobId: string }
+	| { readonly status: "finished-caching"; readonly job: JobSnapshot<PopulateSymbolGraphResult> & { readonly status: "succeeded" } }
+	| { readonly status: "cached" };
+
+export interface MonitorWorkspaceCacheOptions {
+	readonly directory: string;
+	readonly maxFiles: number;
+	readonly maxSymbolsPerFile: number;
+	readonly pollIntervalMs: number;
+	readonly maxPolls: number;
+	readonly shouldContinue: () => boolean;
+	readonly onState: (state: CachePresentationState) => void;
+	readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/** Drives one bounded session cache lifecycle; Pi event handlers only render its states. */
+export async function monitorWorkspaceCache(operations: WorkspaceCacheOperations, options: MonitorWorkspaceCacheOptions): Promise<void> {
+	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+	const initial = await operations.status(options.directory, options.maxFiles, options.maxSymbolsPerFile);
+	if (!options.shouldContinue()) return;
+	if (initial.status === "cached") {
+		options.onState({ status: "cached" });
+		return;
+	}
+
+	let jobId: string;
+	if (initial.status === "caching") {
+		jobId = initial.jobId;
+	} else {
+		options.onState({ status: "not-cached", reason: initial.reason });
+		const submitted = await operations.submit(options.directory, options.maxFiles, options.maxSymbolsPerFile);
+		if (submitted.status === "failed") throw new Error(`${submitted.error.code}: ${submitted.error.message}`);
+		if (submitted.status === "succeeded") {
+			options.onState({ status: "finished-caching", job: submitted });
+			options.onState({ status: "cached" });
+			return;
+		}
+		jobId = submitted.id;
+	}
+	options.onState({ status: "caching", jobId });
+
+	for (let poll = 0; poll < options.maxPolls && options.shouldContinue(); poll++) {
+		await sleep(options.pollIntervalMs);
+		if (!options.shouldContinue()) return;
+		const job = await operations.jobStatus(jobId);
+		if (job.status === "failed") throw new Error(`${job.error.code}: ${job.error.message}`);
+		if (job.status === "succeeded") {
+			options.onState({ status: "finished-caching", job });
+			options.onState({ status: "cached" });
+			return;
+		}
+	}
+}

package/extension/src/workspace-relative-path.ts

@@ -0,0 +1,17 @@
+import { relative } from "node:path";
+
+/**
+ * Convert an absolute path pi's tools pass to Lector's workspace-relative
+ * form. The workspace root *is* the tool's cwd (registered via
+ * workspace.registerPath), so this is a plain node:path relative() --
+ * LocalFilesystemWorkspace independently rejects anything that still
+ * escapes its own root, but failing fast here gives a clearer error at the
+ * Pi-tool boundary instead of a generic PathEscapesWorkspaceRoot later.
+ */
+export function toWorkspaceRelativePath(cwd: string, absolutePath: string): string {
+	const rel = relative(cwd, absolutePath);
+	if (rel.startsWith("..")) {
+		throw new Error(`path "${absolutePath}" is outside the Lector-registered workspace root "${cwd}"`);
+	}
+	return rel;
+}

package/extension/src/write-operations.ts

@@ -0,0 +1,61 @@
+import { type ContentHash, remoteErrorIs } from "@danypops/lector";
+import type { WriteOperations } from "@earendil-works/pi-coding-agent";
+import { lectorClient, withWorkspace, workspaceForPath } from "./lector-client.ts";
+import { toWorkspaceRelativePath } from "./workspace-relative-path.ts";
+
+const MAX_STALE_HASH_RETRIES = 3;
+
+/**
+ * WriteOperations backed by Lector's hash-guarded exactEdit. The workspace
+ * for each call is resolved from the absolute path being written, not a
+ * fixed cwd -- see workspaceForPath.
+ *
+ * pi's write tool is unconditional overwrite by its own documented contract
+ * ("Creates the file if it doesn't exist, overwrites if it does"), so unlike
+ * edit, a stale hash here does not mean the model's intent is now wrong --
+ * it means a concurrent external change landed between our read and our
+ * write, and the model still wants its content to be exactly what it asked
+ * for. Retried transparently (bounded) by re-observing the current hash and
+ * retrying, rather than surfacing StaleExpectedHash to a caller whose tool
+ * contract never mentioned hashes at all.
+ */
+export function createLectorWriteOperations(): WriteOperations {
+	async function currentHash(client: Awaited<ReturnType<typeof lectorClient>>, workspaceId: string, relativePath: string): Promise<ContentHash | null> {
+		try {
+			const current = await client.call("workspace.rawRead", { workspaceId, path: relativePath });
+			return current.hash;
+		} catch {
+			return null; // no existing entry -- exactEdit's create semantics
+		}
+	}
+
+	return {
+		async writeFile(absolutePath, content) {
+			await withWorkspace(
+				() => workspaceForPath(absolutePath),
+				async ({ workspaceId, root }) => {
+					const client = await lectorClient();
+					const relativePath = toWorkspaceRelativePath(root, absolutePath);
+
+					let expectedHash = await currentHash(client, workspaceId, relativePath);
+
+					for (let attempt = 0; attempt < MAX_STALE_HASH_RETRIES; attempt++) {
+						try {
+							await client.call("workspace.exactEdit", { workspaceId, path: relativePath, expectedHash, content });
+							return;
+						} catch (error) {
+							if (!remoteErrorIs(error, "StaleExpectedHash") || attempt === MAX_STALE_HASH_RETRIES - 1) throw error;
+							expectedHash = await currentHash(client, workspaceId, relativePath);
+						}
+					}
+				},
+			);
+		},
+
+		async mkdir() {
+			// LocalFilesystemWorkspace's writeEntry already creates parent directories
+			// (mkdir(dirname(absolute), { recursive: true })) as part of every write --
+			// there is nothing left for this hook to do.
+		},
+	};
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@danypops/pi-lector",
+	"version": "0.1.0",
+	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
+	"license": "MIT",
+	"type": "module",
+	"keywords": ["pi-package"],
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"pi": {
+		"extensions": ["extension/src/index.ts"]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"dependencies": {
+		"@danypops/lector": "^0.1.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "^0.81.1",
+		"@earendil-works/pi-coding-agent": "^0.81.1",
+		"@earendil-works/pi-tui": "^0.81.1",
+		"bun-types": "latest",
+		"typebox": "^1.3.6",
+		"typescript": "^5.7.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DanyPops/lector.git",
+		"directory": "packages/pi-lector"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": ["extension", "README.md", "LICENSE"]
+}