@danypops/pi-lector 0.12.14 → 0.13.0

package/extension/src/bounded-poll.ts

@@ -0,0 +1,19 @@
+/**
+ * Idempotent start/stop wrapper over setInterval -- a second start() is a no-op rather than a
+ * competing timer, and stop() is safe to call even if never started. Same shape as pi-papyrus's,
+ * pi-pipes', pi-packed's, and pi-tickets' own BoundedPoll.
+ */
+export class BoundedPoll {
+	private timer: ReturnType<typeof setInterval> | undefined;
+
+	start(intervalMs: number, tick: () => void): void {
+		if (this.timer) return;
+		this.timer = setInterval(tick, intervalMs);
+	}
+
+	stop(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = undefined;
+	}
+}

package/extension/src/git/operations.ts

@@ -5,6 +5,8 @@ import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle
 type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"];
 type GitWorktreeAddResult = OperationOutputs["workspace.gitWorktreeAdd"];
 type GitWorktreeRemoveResult = OperationOutputs["workspace.gitWorktreeRemove"];
+type GitGrepResult = OperationOutputs["workspace.gitGrep"];
+type GitListFilesResult = OperationOutputs["workspace.gitListFiles"];
 
 /** Matches GIT_READ_PERMISSIONS' own declared value server-side (git/operation-registration.ts). */
 const GIT_READ_PERMISSIONS = ["workspace:read"];
@@ -28,6 +30,22 @@ export interface GitOperations {
 	log(directory: string, maxCount: number, call: LectorVehicleCall): Promise<readonly GitLogEntry[]>;
 	diff(directory: string, ref: string | undefined, maxBytes: number, call: LectorVehicleCall): Promise<GitDiffResult>;
 	compareSymbol(directory: string, path: string, symbolName: string, fromRef: string, toRef: string | undefined, maxBytes: number): Promise<SymbolComparison>;
+	/** A path's exact blob content at `ref`, without checking anything out -- Tier 1's own showFile, undefined content meaning the path did not exist there. */
+	showFile(directory: string, ref: string, path: string, call: LectorVehicleCall): Promise<string | undefined>;
+	/** Text search across `ref`'s own tree, no checkout -- the ref-scoped equivalent of search_code. pathspecs narrows the search (glob-based, e.g. "*.go"). */
+	grep(
+		directory: string,
+		ref: string,
+		pattern: string,
+		pathspecs: readonly string[] | undefined,
+		maxMatches: number,
+		maxBytes: number,
+		call: LectorVehicleCall,
+	): Promise<GitGrepResult>;
+	/** 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. */
+	isAncestor(directory: string, ancestorRef: string, ref: string, call: LectorVehicleCall): Promise<boolean>;
 	/**
 	 * Materializes a real, disposable, read-only project at `ref` via a detached git worktree.
 	 * The returned `path` is a real directory every other pi-lector tool already accepts as its
@@ -95,5 +113,52 @@ export function createLectorGitOperations(): GitOperations {
 					invokeLectorVehicleOperation<GitWorktreeRemoveResult>("workspace.gitWorktreeRemove", { workspaceId }, GIT_WORKTREE_WRITE_PERMISSIONS, call),
 			);
 		},
+		async showFile(directory, ref, path, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const { content } = await invokeLectorVehicleOperation<{ content: string | undefined }>(
+						"workspace.gitShowFile",
+						{ workspaceId, ref, path },
+						GIT_READ_PERMISSIONS,
+						call,
+					);
+					return content;
+				},
+			);
+		},
+		async grep(directory, ref, pattern, pathspecs, maxMatches, maxBytes, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitGrepResult>(
+						"workspace.gitGrep",
+						{ workspaceId, ref, pattern, pathspecs, maxMatches, maxBytes },
+						GIT_READ_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async listFiles(directory, ref, pathspecs, maxResults, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitListFilesResult>("workspace.gitListFiles", { workspaceId, ref, pathspecs, maxResults }, GIT_READ_PERMISSIONS, call),
+			);
+		},
+		async isAncestor(directory, ancestorRef, ref, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				async ({ workspaceId }) => {
+					const { isAncestor } = await invokeLectorVehicleOperation<{ isAncestor: boolean }>(
+						"workspace.gitIsAncestor",
+						{ workspaceId, ancestorRef, ref },
+						GIT_READ_PERMISSIONS,
+						call,
+					);
+					return isAncestor;
+				},
+			);
+		},
 	};
 }

package/extension/src/git/rendering.ts

@@ -11,11 +11,13 @@ 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";
+export type GitAction = "status" | "log" | "diff" | "compare-symbol" | "worktree-add" | "worktree-remove" | "show" | "grep-ref" | "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 GitListFilesResult = OperationOutputs["workspace.gitListFiles"];
 
 export interface GitToolDetails {
 	readonly action: GitAction;
@@ -25,10 +27,24 @@ export interface GitToolDetails {
 	readonly comparison?: SymbolComparison;
 	readonly worktreeAdd?: GitWorktreeAddResult;
 	readonly worktreeRemove?: GitWorktreeRemoveResult;
+	readonly showFile?: { readonly ref: string; readonly path: string; readonly content: string | undefined };
+	readonly grep?: GitGrepResult;
+	readonly listFiles?: GitListFilesResult;
+	readonly isAncestor?: { readonly ancestorRef: string; readonly ref: string; readonly result: boolean };
 }
 
 export function formatGitCall(
-	args: { action?: unknown; directory?: unknown; ref?: unknown; path?: unknown; symbol?: unknown; fromRef?: unknown; toRef?: unknown },
+	args: {
+		action?: unknown;
+		directory?: unknown;
+		ref?: unknown;
+		path?: unknown;
+		symbol?: unknown;
+		fromRef?: unknown;
+		toRef?: unknown;
+		pattern?: unknown;
+		ancestorRef?: unknown;
+	},
 	theme: LectorTheme,
 ): string {
 	const action = typeof args.action === "string" ? args.action : "";
@@ -40,6 +56,21 @@ export function formatGitCall(
 		const toRef = typeof args.toRef === "string" ? ` -> ${args.toRef}` : "";
 		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", `${directory}/${path}`)} (${symbol}) ${fromRef}${toRef}`;
 	}
+	if (action === "is-ancestor") {
+		const ancestorRef = typeof args.ancestorRef === "string" ? args.ancestorRef : "";
+		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 : "";
+		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}"`;
+	}
+	if (action === "show") {
+		const ref = typeof args.ref === "string" ? args.ref : "";
+		const path = typeof args.path === "string" ? args.path : "";
+		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", `${directory}/${path}`)} @ ${ref}`;
+	}
 	const ref = typeof args.ref === "string" ? ` ${args.ref}` : "";
 	return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)}${ref}`;
 }
@@ -55,6 +86,44 @@ function formatGitWorktreeRemoveResult(result: GitWorktreeRemoveResult | undefin
 	return theme.fg("accent", "worktree removed");
 }
 
+function formatGitShowFileResult(details: GitToolDetails["showFile"], theme: LectorTheme): string {
+	if (!details) return theme.fg("dim", "No result.");
+	if (details.content === undefined) return theme.fg("dim", `"${details.path}" does not exist at ${details.ref}`);
+	return details.content;
+}
+
+function formatGitGrepResult(result: GitGrepResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result || result.matches.length === 0) return theme.fg("dim", "No matches.");
+	const lines = renderTruncatedList({
+		items: result.matches,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_FILES,
+		formatItem: (match) => `${theme.fg("accent", `${match.path}:${match.line}`)}:${match.text}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "(also bounded by maxMatches/maxBytes)") : undefined,
+	});
+	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({
+		items: result.paths,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_FILES,
+		formatItem: (path) => path,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "(bounded by maxResults)") : undefined,
+	});
+	return lines.join("\n");
+}
+
+function formatGitIsAncestorResult(details: GitToolDetails["isAncestor"], theme: LectorTheme): string {
+	if (!details) return theme.fg("dim", "No result.");
+	const verb = details.result ? "is" : "is not";
+	return theme.fg("accent", `${details.ancestorRef} ${verb} an ancestor of ${details.ref}`);
+}
+
 export function formatGitResult(details: GitToolDetails | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!details) return theme.fg("dim", "No result.");
 	if (details.action === "status") return formatGitStatusResult(details.summary, expanded, theme);
@@ -62,6 +131,10 @@ export function formatGitResult(details: GitToolDetails | undefined, expanded: b
 	if (details.action === "compare-symbol") return formatCompareSymbolResult(details.comparison, expanded, theme);
 	if (details.action === "worktree-add") return formatGitWorktreeAddResult(details.worktreeAdd, theme);
 	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 === "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

@@ -129,6 +129,7 @@ import { formatSearchCall, formatSearchResult } from "./search/rendering.ts";
 import { type AnnotationAnchorInput, createLectorSymbolAnnotationOperations } from "./symbol-annotation/operations.ts";
 import { formatAnnotationDetail, formatAnnotationListSummary, formatAnnotationSummary } from "./symbol-annotation/rendering.ts";
 import type { LectorVehicleCall } from "./vehicle-client.ts";
+import { CachingOverlay } from "./workspace-cache/caching-overlay.ts";
 import {
 	type CachePresentationState,
 	cacheContextMessage,
@@ -278,6 +279,7 @@ export default function (pi: ExtensionAPI) {
 		};
 	});
 
+	let cachingOverlay: CachingOverlay | undefined;
 	pi.on("session_shutdown", (_event, ctx) => {
 		sessionGeneration++;
 		cacheStatesByRoot.clear();
@@ -285,6 +287,7 @@ export default function (pi: ExtensionAPI) {
 		lastInjectedSummary = undefined;
 		uiContext = undefined;
 		ctx.ui.setStatus("lector-cache", undefined);
+		cachingOverlay?.dispose();
 	});
 
 	pi.on("session_start", (_event, ctx) => {
@@ -295,6 +298,14 @@ export default function (pi: ExtensionAPI) {
 		lastInjectedSummary = undefined;
 		uiContext = ctx;
 		setNewWorkspaceObserver((root) => startMonitoringRoot(root, ctx));
+		if (ctx.hasUI) {
+			// The persistent widget counterpart to the single-line "lector-cache" status above --
+			// enumerates EVERY workspace currently caching, not just this session's own cwd root.
+			cachingOverlay ??= new CachingOverlay();
+			cachingOverlay.setUI(ctx.ui);
+			void cachingOverlay.refresh();
+			cachingOverlay.startPolling();
+		}
 		const thisGeneration = sessionGeneration;
 		void nearestGitWorkspaceRoot(cwd)
 			.then((projectRoot) => {
@@ -1246,25 +1257,34 @@ 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, 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), 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, or a real checkout at another ref",
+				"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).",
+			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 -- 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 -- 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.",
 			],
 			parameters: Type.Object({
-				action: Type.String({ description: "status | log | diff | compare-symbol | worktree-add | worktree-remove" }),
+				action: Type.String({ description: "status | log | diff | compare-symbol | show | grep-ref | 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(
-					Type.String({ description: "Ref to diff against (defaults to HEAD) for action=diff, or to check out for action=worktree-add (required)" }),
+					Type.String({
+						description:
+							"Ref to diff against (defaults to HEAD) for action=diff, or to check out/query for action=worktree-add/show/grep-ref/ls-ref/is-ancestor (required for those)",
+					}),
 				),
 				maxBytes: Type.Optional(
-					Type.Number({ description: "Maximum diff/comparison size in bytes before truncating -- required for action=diff/compare-symbol" }),
+					Type.Number({
+						description: "Maximum diff/comparison/grep output size in bytes before truncating -- required for action=diff/compare-symbol/grep-ref",
+					}),
+				),
+				path: Type.Optional(
+					Type.String({ description: "File path (relative to directory) containing the symbol, or to read -- required for action=compare-symbol/show" }),
 				),
-				path: Type.Optional(Type.String({ description: "File path (relative to directory) containing the symbol -- required for action=compare-symbol" })),
 				symbol: Type.Optional(Type.String({ description: "Exact symbol name to compare -- required for action=compare-symbol" })),
 				fromRef: Type.Optional(Type.String({ description: "Git ref for the 'before' version -- required for action=compare-symbol" })),
 				toRef: Type.Optional(
@@ -1275,6 +1295,16 @@ 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" })),
+				pathspecs: Type.Optional(
+					Type.Array(Type.String(), {
+						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',
+					}),
+				),
+				maxMatches: Type.Optional(Type.Number({ description: "Maximum grep matches to return -- required for action=grep-ref" })),
+				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" })),
 			}),
 			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<GitToolDetails>> {
 				const directory = resolve(cwd, params.directory);
@@ -1316,6 +1346,32 @@ export default function (pi: ExtensionAPI) {
 					const details: GitToolDetails = { action: "worktree-remove", worktreeRemove };
 					return { content: [{ type: "text", text: JSON.stringify(worktreeRemove) }], details };
 				}
+				if (params.action === "show") {
+					if (!params.ref || !params.path) throw new Error("git action=show requires ref and path");
+					const content = await gitOperations.showFile(directory, params.ref, params.path, vehicleCall);
+					const details: GitToolDetails = { action: "show", showFile: { ref: params.ref, path: params.path, content } };
+					return { content: [{ type: "text", text: content ?? `"${params.path}" does not exist at ${params.ref}` }], details };
+				}
+				if (params.action === "grep-ref") {
+					if (!params.ref || !params.pattern) throw new Error("git action=grep-ref requires ref and pattern");
+					if (params.maxMatches === undefined || params.maxBytes === undefined) throw new Error("git action=grep-ref requires maxMatches and maxBytes");
+					const grep = await gitOperations.grep(directory, params.ref, params.pattern, params.pathspecs, params.maxMatches, params.maxBytes, vehicleCall);
+					const details: GitToolDetails = { action: "grep-ref", grep };
+					return { content: [{ type: "text", text: JSON.stringify(grep) }], 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");
+					const listFiles = await gitOperations.listFiles(directory, params.ref, params.pathspecs, params.maxResults, vehicleCall);
+					const details: GitToolDetails = { action: "ls-ref", listFiles };
+					return { content: [{ type: "text", text: JSON.stringify(listFiles) }], details };
+				}
+				if (params.action === "is-ancestor") {
+					if (!params.ancestorRef || !params.ref) throw new Error("git action=is-ancestor requires ancestorRef and ref");
+					const result = await gitOperations.isAncestor(directory, params.ancestorRef, params.ref, vehicleCall);
+					const details: GitToolDetails = { action: "is-ancestor", isAncestor: { ancestorRef: params.ancestorRef, ref: params.ref, result } };
+					return { content: [{ type: "text", text: JSON.stringify({ isAncestor: result }) }], details };
+				}
 				throw new Error(`unknown git action: ${String(params.action)}`);
 			},
 			renderCall(args, theme, context) {

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

@@ -0,0 +1,124 @@
+/**
+ * Persistent above-editor widget for currently-active symbol-graph caching jobs -- mirrors
+ * pi-papyrus's own TaskOverlay/NoteOverlay, pi-pipes' own JobsOverlay, and pi-packed's own
+ * DoctorOverlay: factory-form ctx.ui.setWidget registration, requestRender on refresh, hides the
+ * widget entirely (setWidget(key, undefined)) rather than an empty box once nothing is caching.
+ *
+ * workspace.activeCachingJobs enumerates every workspace with a currently active (queued/
+ * running) population job -- see packages/lector/src/service/symbol-graph/cache-query-handlers.ts.
+ */
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { AutoRotatingWindow } from "malevich-tui-components";
+import { BoundedPoll } from "../bounded-poll.js";
+import { lectorClient, type RetryingLectorClient } from "../lector-client.js";
+import { buildCachingWidgetProjection, type CachingWidgetProjection, LECTOR_CACHING_WIDGET_VISIBLE_ROWS, renderCachingWidgetLines } from "./caching-widget.js";
+
+const WIDGET_KEY = "pi-lector-caching";
+
+/** Matches pi-papyrus's/pi-pipes' own 15-20s cadence -- workspace.activeCachingJobs is a cheap in-memory read. */
+export const CACHING_WIDGET_POLL_INTERVAL_MS = 15_000;
+
+/** How often the widget's own auto-rotating overflow page advances. */
+export const CACHING_WIDGET_ROTATION_INTERVAL_MS = 6_000;
+
+const EMPTY_PROJECTION: CachingWidgetProjection = { rows: [], total: 0 };
+
+export class CachingOverlay {
+	private uiCtx: ExtensionUIContext | undefined;
+	private registered = false;
+	private tui: TUI | undefined;
+	private projection: CachingWidgetProjection = EMPTY_PROJECTION;
+	private readonly poll = new BoundedPoll();
+	/** Repaint-only ticker (no data refetch) so the widget's own auto-rotating page visibly
+	 * advances even when nothing else has changed. */
+	private readonly rotationPoll = new BoundedPoll();
+	private readonly rotation = new AutoRotatingWindow({
+		totalRows: 0,
+		pageSize: LECTOR_CACHING_WIDGET_VISIBLE_ROWS,
+		intervalMs: CACHING_WIDGET_ROTATION_INTERVAL_MS,
+	});
+
+	constructor(private readonly connect: () => Promise<RetryingLectorClient> = lectorClient) {}
+
+	setUI(ctx: ExtensionUIContext): void {
+		if (ctx !== this.uiCtx) {
+			this.uiCtx = ctx;
+			this.registered = false;
+			this.tui = undefined;
+		}
+	}
+
+	/** Never throws: called from a poll timer and from session_start, neither of which should turn
+	 * a best-effort status widget into a crashed extension host over a daemon that isn't running
+	 * yet or a rendering bug. */
+	async refresh(): Promise<void> {
+		try {
+			const client = await this.connect();
+			const result = await client.call("workspace.activeCachingJobs", {});
+			this.projection = buildCachingWidgetProjection(result.jobs);
+		} catch {
+			this.projection = EMPTY_PROJECTION;
+		}
+		try {
+			this.render();
+		} catch {
+			// A rendering bug must not crash the extension host over a best-effort status widget.
+		}
+	}
+
+	private render(): void {
+		if (!this.uiCtx) return;
+
+		if (this.projection.total === 0) {
+			if (this.registered) {
+				this.uiCtx.setWidget(WIDGET_KEY, undefined);
+				this.registered = false;
+				this.tui = undefined;
+				this.rotationPoll.stop();
+			}
+			return;
+		}
+
+		if (!this.registered) {
+			this.uiCtx.setWidget(
+				WIDGET_KEY,
+				(tui: TUI, theme: Theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => renderCachingWidgetLines(theme, this.projection, width, this.rotation),
+						invalidate: () => {
+							// Theme changed -- force re-registration, matching every other overlay in this ecosystem.
+							this.registered = false;
+							this.tui = undefined;
+						},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
+			this.registered = true;
+			this.rotationPoll.start(CACHING_WIDGET_ROTATION_INTERVAL_MS, () => this.tui?.requestRender());
+		} else {
+			this.tui?.requestRender();
+		}
+	}
+
+	startPolling(intervalMs: number = CACHING_WIDGET_POLL_INTERVAL_MS): void {
+		this.poll.start(intervalMs, () => {
+			void this.refresh();
+		});
+	}
+
+	stopPolling(): void {
+		this.poll.stop();
+	}
+
+	dispose(): void {
+		this.stopPolling();
+		this.rotationPoll.stop();
+		this.uiCtx?.setWidget(WIDGET_KEY, undefined);
+		this.registered = false;
+		this.tui = undefined;
+		this.uiCtx = undefined;
+	}
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Pure projection/render pair for the Caching widget -- mirrors pi-papyrus's own task-widget.ts /
+ * pi-pipes' own jobs-widget.ts / pi-packed's own doctor-widget.ts split: the daemon's
+ * workspace.activeCachingJobs result in, a bounded intermediate shape out, no I/O, no TUI, fully
+ * unit-testable without a real daemon or terminal. See caching-overlay.ts for the stateful
+ * ctx.ui.setWidget-registered class that drives these from a live poll.
+ */
+import { vehicleWidgetTitle } from "@danypops/vehicle-client-pi/widget-header";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { type AutoRotatingWindow, renderCardRow, type TextMeasure } from "malevich-tui-components";
+
+const measure: TextMeasure = { visibleWidth, truncateToWidth, wrapTextWithAnsi };
+
+/** The daemon's own manifest name (see packages/lector/src/service.ts's `new VehicleRegistry({ name: "lector" })`). */
+const VEHICLE_NAME = "lector";
+
+/** Visible rows per page before the auto-rotating overflow hint pages to the next. */
+export const LECTOR_CACHING_WIDGET_VISIBLE_ROWS = 5;
+
+export interface CachingWidgetRow {
+	workspaceId: string;
+	status: "queued" | "running" | "waiting-for-resources";
+}
+
+export interface CachingWidgetProjection {
+	rows: CachingWidgetRow[];
+	total: number;
+}
+
+export function buildCachingWidgetProjection(jobs: readonly CachingWidgetRow[]): CachingWidgetProjection {
+	return { rows: [...jobs], total: jobs.length };
+}
+
+function cachingRowLine(theme: { fg(color: string, text: string): string }, row: CachingWidgetRow, width: number): string {
+	const glyph =
+		row.status === "waiting-for-resources"
+			? theme.fg("warning", "\u23f8")
+			: row.status === "queued"
+				? theme.fg("muted", "\u2022")
+				: theme.fg("accent", "\u25b6");
+	return truncateToWidth(`${glyph} ${row.workspaceId}`, width, "\u2026");
+}
+
+/** "Lector · Caching · <N>", plus a "page/total ⟳" suffix once genuinely paging. */
+function cachingCardLabel(projection: CachingWidgetProjection, rotation?: AutoRotatingWindow): string {
+	const base = vehicleWidgetTitle(VEHICLE_NAME, "Caching", `${projection.total}`);
+	return rotation?.isPaging ? `${base} \u00b7 ${rotation.pageIndex + 1}/${rotation.pageCount} \u27f3` : base;
+}
+
+/** Renders the widget as a single bordered card -- `[]` (hide the whole widget) when nothing is
+ * currently caching, matching every other overlay's own "hide when nothing to show" convention. */
+export function renderCachingWidgetLines(
+	theme: { fg(color: string, text: string): string },
+	projection: CachingWidgetProjection,
+	width: number,
+	rotation?: AutoRotatingWindow,
+): string[] {
+	if (projection.total === 0) return [];
+	rotation?.setTotalRows(projection.rows.length);
+	const { start, end } = rotation?.currentPageBounds() ?? { start: 0, end: projection.rows.length };
+	const visibleRows = projection.rows.slice(start, end);
+
+	return renderCardRow(
+		[
+			{
+				label: cachingCardLabel(projection, rotation),
+				render: (innerWidth: number) => visibleRows.map((row) => cachingRowLine(theme, row, innerWidth)),
+			},
+		],
+		width,
+		{ measure, frameStyle: (s) => theme.fg("borderMuted", s) },
+	);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.12.14",
+	"version": "0.13.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -22,10 +22,10 @@
 		"@danypops/vehicle-client-pi": "^0.43.0"
 	},
 	"dependencies": {
+		"@danypops/lector": "workspace:*",
 		"@danypops/vehicle-client": "^0.10.3",
 		"@danypops/vehicle-core": "^0.17.1",
-		"@danypops/lector": "^0.19.3",
-		"malevich-tui-components": "^0.25.0",
+		"malevich-tui-components": "^0.32.1",
 		"picomatch": "^4.0.5"
 	},
 	"devDependencies": {