pi-cockpit 0.15.0 → 0.16.0

package/package.json

@@ -1,85 +1,85 @@
-{
-  "name": "pi-cockpit",
-  "version": "0.15.0",
-  "description": "Responsive Maestro operations sidebar, fallback status widgets, and footer for Pi.",
-  "type": "module",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "tui",
-    "teammate",
-    "todo"
-  ],
-  "license": "MIT",
-  "files": [
-    "src/",
-    "themes/",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node --test --experimental-transform-types tests/config.test.ts tests/public-events.test.ts tests/maestro-store.test.ts tests/split-pane.test.ts tests/editor-bottom.test.ts tests/sidebar-render.test.ts tests/sidebar-controller.test.ts tests/viewport-stability.test.ts tests/quiet-tools.test.ts tests/edit-guard.test.ts tests/agents-store.test.ts tests/endpoint-store.test.ts tests/session-ui-state.test.ts tests/session-tabs.test.ts tests/agent-bar.test.ts tests/supervision-store.test.ts tests/bash-bg-store.test.ts tests/bash-bg-widget.test.ts tests/bash-bg-overlay.test.ts tests/agent-overlay.test.ts tests/todo-store.test.ts tests/render.test.ts tests/agent-scroll.test.ts tests/session-bar.test.ts tests/session-detail.test.ts tests/footer.test.ts tests/extension-status.test.ts tests/input-routing.test.ts tests/integration-contract.test.ts tests/stack-widget.test.ts tests/zen-render.test.ts tests/zen-browse.test.ts tests/zen-sheet.test.ts tests/settings-view.test.ts tests/thinking-fold.test.ts tests/thinking-timer.test.ts tests/tick-policy.test.ts tests/ambient.test.ts tests/viewport.test.ts tests/theme-picker.test.ts tests/model-picker.test.ts tests/title-gen.test.ts tests/title-llm.test.ts tests/settings-registry.test.ts tests/settings-coordinator.test.ts tests/settings-locale.test.ts tests/tui-i18n.test.ts tests/settings-shell.test.ts tests/settings-cockpit-provider.test.ts tests/settings-cross-package.test.ts tests/ui-primitives.test.ts tests/settings-shell-secret.test.ts tests/settings-shell-listcrud.test.ts tests/capturing-overlay.test.ts tests/claude-editor.test.ts tests/fullscreen-controller.test.ts tests/transcript-selection.test.ts tests/terminal-cleanup.test.ts tests/terminal-capability.test.ts",
-    "typecheck": "tsc --noEmit",
-    "prepack": "node ../../scripts/bundle-settings-core.mjs",
-    "postpack": "node ../../scripts/bundle-settings-core.mjs --clean"
-  },
-  "pi": {
-    "extensions": [
-      "./src/extension/index.ts"
-    ],
-    "themes": [
-      "./themes"
-    ]
-  },
-  "dependencies": {
-    "pi-maestro-settings-core": "0.1.3",
-    "proper-lockfile": "4.1.2"
-  },
-  "bundledDependencies": [
-    "pi-maestro-settings-core"
-  ],
-  "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "pi-maestro-teammate": "^1.6.0",
-    "typebox": "*"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-agent-core": {
-      "optional": true
-    },
-    "@earendil-works/pi-ai": {
-      "optional": true
-    },
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
-    "@earendil-works/pi-tui": {
-      "optional": true
-    },
-    "pi-maestro-teammate": {
-      "optional": true
-    },
-    "typebox": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.83.0",
-    "@earendil-works/pi-ai": "0.83.0",
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@earendil-works/pi-tui": "0.83.0",
-    "@types/node": "^22.0.0",
-    "pi-maestro-teammate": "1.13.0",
-    "typebox": "1.3.7",
-    "typescript": "^5.5.0"
-  },
-  "main": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./v1/events": "./src/public/v1/events.ts",
-    "./src/*": "./src/*"
-  }
-}
+{
+  "name": "pi-cockpit",
+  "version": "0.16.0",
+  "description": "Responsive Maestro operations sidebar, fallback status widgets, and footer for Pi.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "tui",
+    "teammate",
+    "todo"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "themes/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test --experimental-transform-types tests/config.test.ts tests/public-events.test.ts tests/maestro-store.test.ts tests/split-pane.test.ts tests/editor-bottom.test.ts tests/sidebar-render.test.ts tests/sidebar-controller.test.ts tests/viewport-stability.test.ts tests/quiet-tools.test.ts tests/edit-guard.test.ts tests/agents-store.test.ts tests/endpoint-store.test.ts tests/session-ui-state.test.ts tests/session-tabs.test.ts tests/agent-bar.test.ts tests/supervision-store.test.ts tests/bash-bg-store.test.ts tests/bash-bg-widget.test.ts tests/bash-bg-overlay.test.ts tests/agent-overlay.test.ts tests/todo-store.test.ts tests/render.test.ts tests/agent-scroll.test.ts tests/session-bar.test.ts tests/session-detail.test.ts tests/footer.test.ts tests/extension-status.test.ts tests/input-routing.test.ts tests/input-history-store.test.ts tests/unified-editor.test.ts tests/integration-contract.test.ts tests/stack-widget.test.ts tests/zen-render.test.ts tests/zen-browse.test.ts tests/zen-sheet.test.ts tests/settings-view.test.ts tests/thinking-fold.test.ts tests/thinking-timer.test.ts tests/tick-policy.test.ts tests/ambient.test.ts tests/viewport.test.ts tests/theme-picker.test.ts tests/model-picker.test.ts tests/title-gen.test.ts tests/title-llm.test.ts tests/settings-registry.test.ts tests/settings-coordinator.test.ts tests/settings-locale.test.ts tests/tui-i18n.test.ts tests/settings-shell.test.ts tests/settings-cockpit-provider.test.ts tests/settings-cross-package.test.ts tests/ui-primitives.test.ts tests/settings-shell-secret.test.ts tests/settings-shell-listcrud.test.ts tests/capturing-overlay.test.ts tests/claude-editor.test.ts tests/fullscreen-controller.test.ts tests/transcript-selection.test.ts tests/terminal-cleanup.test.ts tests/terminal-capability.test.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "node ../../scripts/bundle-settings-core.mjs",
+    "postpack": "node ../../scripts/bundle-settings-core.mjs --clean"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension/index.ts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "dependencies": {
+    "pi-maestro-settings-core": "0.1.3",
+    "proper-lockfile": "4.1.2"
+  },
+  "bundledDependencies": [
+    "pi-maestro-settings-core"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "pi-maestro-teammate": "^1.6.0",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-agent-core": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "pi-maestro-teammate": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
+    "@types/node": "^22.0.0",
+    "pi-maestro-teammate": "1.13.0",
+    "typebox": "1.3.7",
+    "typescript": "^5.5.0"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./v1/events": "./src/public/v1/events.ts",
+    "./src/*": "./src/*"
+  }
+}

package/src/claude-editor.ts

@@ -1,6 +1,7 @@
 import { CustomEditor, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
-import { isKeyRelease, isKeyRepeat, matchesKey, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
+import { isKeyRelease, isKeyRepeat, matchesKey, getKeybindings, truncateToWidth, visibleWidth, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
 import { readAutocompleteState } from "./autocomplete-probe.ts";
+import { tuiT } from "./tui-i18n.ts";
 
 /** Invisible editor start marker consumed by the fullscreen controller (fullscreenInput only). */
 export const EDITOR_START_SENTINEL = "\u2063\u2064\u2063\u2064cockpit:editor:start";
@@ -9,6 +10,15 @@ export const EDITOR_END_SENTINEL = "\u2063\u2064\u2063\u2064cockpit:editor:end";
 
 export const DEFAULT_DOUBLE_ESCAPE_WINDOW_MS = 500;
 
+/** Cursor state when the user is typing rather than browsing history. */
+const NOT_BROWSING = -1;
+
+export interface CockpitEditorRouteTarget {
+  label: string;
+  sigil?: "@" | "#";
+  paint: (text: string) => string;
+}
+
 export interface CockpitClaudeEditorOptions {
 	/** Enable the double bare-Escape clear-input state machine. */
 	doubleEscapeClearInput: boolean;
@@ -22,6 +32,14 @@ export interface CockpitClaudeEditorOptions {
 	onError?: (error: unknown) => void;
 	/** Double-Escape window in ms (default 500). */
 	doubleEscapeWindowMs?: number;
+	/** Persistent prompt history, newest first. Read on every keystroke. */
+	getEntries?: () => readonly string[];
+	/** Called for every submitted prompt (including slash commands and `!` lines). */
+	record?: (text: string) => void;
+	/** Immutable route prefix painted inside the editor, never included in text. */
+	getRouteTarget?: () => CockpitEditorRouteTarget | undefined;
+	/** Called with the constructed editor so the host can push route updates. */
+	onEditor?: (editor: CockpitClaudeEditor) => void;
 }
 
 export interface DoubleEscapeDecision {
@@ -85,13 +103,18 @@ export class DoubleEscapeGate {
 }
 
 /**
- * Cockpit's CustomEditor: owns the double-Escape state machine and the editor
- * markers the fullscreen controller uses to split transcript / editor / chrome.
- * Installed at session start (reload-gated) via createCockpitClaudeEditorFactory.
+ * Cockpit's unified CustomEditor: owns the double-Escape state machine, the
+ * editor markers the fullscreen controller uses, the persistent ↑/↓ prompt
+ * history, and the input route-target prefix. Installed at session start
+ * (reload-gated) via createCockpitClaudeEditorFactory.
  */
 export class CockpitClaudeEditor extends CustomEditor {
 	private readonly editorOptions: CockpitClaudeEditorOptions;
 	private readonly doubleEscapeGate = new DoubleEscapeGate();
+	/** History browsing cursor: NOT_BROWSING while typing, else an index into getEntries(). */
+	private index = NOT_BROWSING;
+	/** What the user had typed before browsing started, restored on the way back down. */
+	private draft = "";
 
 	constructor(
 		tui: TUI,
@@ -102,17 +125,39 @@ export class CockpitClaudeEditor extends CustomEditor {
 		super(tui, theme, keybindings);
 		this.editorOptions = options;
 		if (options.doubleEscapeWindowMs !== undefined) this.doubleEscapeGate.windowMs = options.doubleEscapeWindowMs;
+		options.onEditor?.(this);
+	}
+
+	/** Submitted prompts go to the persistent store when enabled, else to the base in-memory history. */
+	override addToHistory(text: string): void {
+		if (this.editorOptions.record) this.editorOptions.record(text);
+		else super.addToHistory(text);
+	}
+
+	/** Programmatic writes (submit clears, `ui.setEditorText`) end history browsing. */
+	override setText(text: string): void {
+		this.index = NOT_BROWSING;
+		super.setText(text);
 	}
 
 	override render(width: number): string[] {
-		const lines = super.render(width);
-		if (!this.editorOptions.emitEditorMarkers) return lines;
-		return [EDITOR_START_SENTINEL, ...lines, EDITOR_END_SENTINEL];
+		const target = this.editorOptions.getRouteTarget?.();
+		const lines = target ? this.renderWithRouteTarget(width, target) : super.render(width);
+		const total = this.editorOptions.getEntries?.().length ?? 0;
+		const banner = this.browsing() && total > 0
+			? historyBanner(this.index + 1, total, width, this.getPaddingX(), this.borderColor)
+			: undefined;
+		if (!this.editorOptions.emitEditorMarkers) {
+			return banner ? [...lines, banner] : lines;
+		}
+		// The fullscreen controller treats everything between the sentinels as the
+		// editor region, so the banner must sit before the END marker to stay visible.
+		return [EDITOR_START_SENTINEL, ...lines, ...(banner ? [banner] : []), EDITOR_END_SENTINEL];
 	}
 
 	override handleInput(data: string): void {
-		const enabled = this.editorOptions.doubleEscapeClearInput;
 		if (this.isBareEscape(data)) {
+			const enabled = this.editorOptions.doubleEscapeClearInput;
 			if (enabled) {
 				const probe = readAutocompleteState(this);
 				const autocomplete: DoubleEscapeGateInput["autocomplete"] = probe.unknown
@@ -133,8 +178,30 @@ export class CockpitClaudeEditor extends CustomEditor {
 			super.handleInput(data);
 			return;
 		}
-		if (enabled) this.doubleEscapeGate.onAnyOtherInput();
+		if (this.editorOptions.doubleEscapeClearInput) this.doubleEscapeGate.onAnyOtherInput();
+		const keys = getKeybindings();
+		// History browsing only exists when persistent history is enabled; without
+		// getEntries, Up/Down keep their plain cursor-move meaning.
+		if (this.editorOptions.getEntries) {
+			if (keys.matches(data, "tui.editor.cursorUp") && this.canBrowseOlder()) {
+				this.step(1);
+				return;
+			}
+			if (keys.matches(data, "tui.editor.cursorDown") && this.canBrowseNewer()) {
+				this.step(-1);
+				return;
+			}
+		}
 		super.handleInput(data);
+		// Editing the recalled text means the user left history behind.
+		if (this.browsing() && this.getText() !== this.editorOptions.getEntries?.()[this.index]) {
+			this.index = NOT_BROWSING;
+		}
+	}
+
+	/** Repaint after a cross-extension input-target change. */
+	refreshRouteTarget(): void {
+		this.tui.requestRender();
 	}
 
 	private isBareEscape(data: string): boolean {
@@ -149,9 +216,90 @@ export class CockpitClaudeEditor extends CustomEditor {
 			this.editorOptions.onError?.(error);
 		}
 	}
+
+	private renderWithRouteTarget(width: number, target: CockpitEditorRouteTarget): string[] {
+		const paddingX = Math.min(this.getPaddingX(), Math.max(0, Math.floor((width - 1) / 2)));
+		const contentWidth = Math.max(1, width - paddingX * 2);
+		const layoutWidth = Math.max(1, contentWidth - (paddingX ? 0 : 1));
+		const token = truncateToWidth(`${target.sigil ?? "@"}${target.label}:`, Math.max(1, layoutWidth - 1), "…");
+		const injected = `${token}${visibleWidth(token) < layoutWidth ? " " : ""}`;
+
+		// Editor has no render-prefix API. Temporarily project the immutable target
+		// into its layout state so native wrapping and cursor placement stay correct,
+		// then restore the real editable state before returning.
+		const state = (this as unknown as EditorWithRenderState).state;
+		const originalLines = state.lines;
+		const originalCursorCol = state.cursorCol;
+		state.lines = [`${injected}${originalLines[0] ?? ""}`, ...originalLines.slice(1)];
+		if (state.cursorLine === 0) state.cursorCol += injected.length;
+		try {
+			const rendered = super.render(width);
+			const routeLine = rendered.findIndex((line) => line.includes(token));
+			if (routeLine >= 0) {
+				rendered[routeLine] = rendered[routeLine]!.replace(token, target.paint(token));
+			}
+			return rendered.map((line) => truncateToWidth(line, Math.max(1, width), ""));
+		} finally {
+			state.lines = originalLines;
+			state.cursorCol = originalCursorCol;
+		}
+	}
+
+	private browsing(): boolean {
+		return this.index > NOT_BROWSING;
+	}
+
+	/**
+	 * Mirrors the base editor's own gating: on the first line, and either already
+	 * browsing or with the cursor at the very start (which includes an empty editor) —
+	 * anywhere else Up is a plain cursor move.
+	 */
+	private canBrowseOlder(): boolean {
+		if (this.isShowingAutocomplete() || this.getCursor().line !== 0) return false;
+		return this.browsing() || this.getCursor().col === 0;
+	}
+
+	private canBrowseNewer(): boolean {
+		if (!this.browsing() || this.isShowingAutocomplete()) return false;
+		return this.getCursor().line === this.getLines().length - 1;
+	}
+
+	private step(delta: number): void {
+		const entries = this.editorOptions.getEntries?.() ?? [];
+		const next = this.index + delta;
+		if (next < NOT_BROWSING || next >= entries.length) return;
+		if (!this.browsing()) this.draft = this.getText();
+		// super.setText, so the index we are about to record survives.
+		super.setText(next === NOT_BROWSING ? this.draft : entries[next] ?? "");
+		this.index = next;
+	}
+}
+
+/** Compact history position label, indented to the editor's content. */
+export function historyBanner(
+	position: number,
+	total: number,
+	width: number,
+	paddingX: number,
+	paint: (value: string) => string,
+): string {
+	const indent = " ".repeat(Math.max(0, paddingX));
+	const inner = Math.max(1, width - indent.length * 2);
+	const label = tuiT("editor.historyBanner", { position, total });
+	return indent + paint(truncateToWidth(label, inner, "…"));
+}
+
+interface EditorRenderState {
+	lines: string[];
+	cursorLine: number;
+	cursorCol: number;
+}
+
+interface EditorWithRenderState {
+	state: EditorRenderState;
 }
 
-/** Build the editor factory Cockpit installs when a gated feature is on. */
+/** Build the editor factory Cockpit installs for its gated editor features. */
 export function createCockpitClaudeEditorFactory(options: CockpitClaudeEditorOptions) {
 	const factory = (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) =>
 		new CockpitClaudeEditor(tui, theme, keybindings, options);

package/src/config.ts

@@ -54,6 +54,7 @@ const isCurrencyMode = (v: unknown): v is CurrencyMode => v === "usd" || v === "
 		doubleEscapeClearInput: typeof o.doubleEscapeClearInput === "boolean" ? o.doubleEscapeClearInput : base.doubleEscapeClearInput,
 		fullscreenInput: typeof o.fullscreenInput === "boolean" ? o.fullscreenInput : base.fullscreenInput,
 		copyOnSelect: typeof o.copyOnSelect === "boolean" ? o.copyOnSelect : base.copyOnSelect,
+		historyEnabled: typeof o.historyEnabled === "boolean" ? o.historyEnabled : base.historyEnabled,
 		currency: isCurrencyMode(o.currency) ? o.currency : base.currency,
 		currencyRate: typeof o.currencyRate === "number" && Number.isFinite(o.currencyRate) && o.currencyRate > 0
 			? Math.min(100, Math.max(0.01, Math.round(o.currencyRate * 100) / 100))
@@ -141,6 +142,7 @@ export function mergeConfigDocument(raw: unknown, config: CockpitConfig): Record
 		doubleEscapeClearInput: config.doubleEscapeClearInput,
 		fullscreenInput: config.fullscreenInput,
 		copyOnSelect: config.copyOnSelect,
+		historyEnabled: config.historyEnabled,
 		currency: config.currency,
 		currencyRate: config.currencyRate,
 		icons,

package/src/editor/input-history-store.ts

@@ -0,0 +1,173 @@
+/**
+ * Per-workspace input history, owned by Cockpit's unified editor.
+ *
+ * The prompt history Pi's editor offers on up/down lives in memory only, so it is
+ * gone the moment the session ends. This store mirrors it to
+ * `~/.pi/workspaces/<workspace-id>/input-history.json`, keyed by working directory,
+ * so a brand new session picks up where the previous one left off.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+
+const FILE_NAME = "input-history.json";
+/** Matches the built-in editor's in-memory cap, so the list feels the same. */
+const DEFAULT_MAX_ENTRIES = 100;
+/** Session restore replays every past prompt; one debounce window collapses it into one write. */
+const DEFAULT_SAVE_DEBOUNCE_MS = 250;
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+
+/**
+ * Serializes every save across store instances so a fresh store's load() never
+ * races an older store's pending flush (reload/new/resume in the same process):
+ * the next load waits for the previous store's save to land before reading.
+ */
+let pendingWrites: Promise<void> = Promise.resolve();
+
+export interface InputHistoryStoreOptions {
+  rootDir?: string;
+  maxEntries?: number;
+  debounceMs?: number;
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * Stable per-workspace storage id, byte-identical to the historical
+ * pi-maestro-flow implementation so persisted history keeps resolving to the
+ * same file across the module move.
+ */
+export function workspaceStorageId(cwd: string): string {
+  const normalized = normalizeWorkspacePath(cwd);
+  const slug = basename(resolve(cwd))
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "workspace";
+  return `${slug}-${createHash("sha256").update(normalized).digest("hex").slice(0, 8)}`;
+}
+
+function normalizeWorkspacePath(cwd: string): string {
+  const normalized = resolve(cwd).replaceAll("\\", "/").replace(/\/$/, "");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+export class InputHistoryStore {
+  readonly filePath: string;
+  private readonly dir: string;
+  private readonly maxEntries: number;
+  private readonly debounceMs: number;
+  private readonly onError: ((error: unknown) => void) | undefined;
+  private entries: string[] = [];
+  private timer: NodeJS.Timeout | undefined;
+  private writes: Promise<void> = Promise.resolve();
+
+  constructor(cwd: string, options: InputHistoryStoreOptions = {}) {
+    const rootDir = options.rootDir ?? join(homedir(), ".pi", "workspaces");
+    this.dir = join(rootDir, workspaceStorageId(cwd));
+    this.filePath = join(this.dir, FILE_NAME);
+    this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+    this.debounceMs = Math.max(0, options.debounceMs ?? DEFAULT_SAVE_DEBOUNCE_MS);
+    this.onError = options.onError;
+  }
+
+  /** Newest first. */
+  list(): readonly string[] {
+    return this.entries;
+  }
+
+  async load(): Promise<readonly string[]> {
+    // Let any older store's pending save land first, so a session that starts
+    // right after a shutdown sees the previous session's last prompt.
+    await pendingWrites;
+    const disk = await this.readFromDisk();
+    // Entries recorded before the first load settled (an immediate submit right
+    // after startup) must survive: keep them ahead of the disk entries.
+    const known = new Set(this.entries);
+    this.entries = capped([...this.entries, ...disk.filter((value) => !known.has(value))], this.maxEntries);
+    return this.entries;
+  }
+
+  /** Move `text` to the front of the history and schedule a save. */
+  record(text: string): void {
+    const entry = text.trim();
+    if (!entry || this.entries[0] === entry) return;
+    this.entries = capped([entry, ...this.entries.filter((value) => value !== entry)], this.maxEntries);
+    this.schedule();
+  }
+
+  /** Run any pending save now and wait for every outstanding write. */
+  async flush(): Promise<void> {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+      this.enqueueSave();
+    }
+    await this.writes;
+  }
+
+  private schedule(): void {
+    if (this.timer) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.enqueueSave();
+    }, this.debounceMs);
+  }
+
+  private enqueueSave(): void {
+    const save = pendingWrites.then(() => this.save());
+    pendingWrites = save.catch(() => undefined);
+    this.writes = save.catch((error: unknown) => {
+      this.onError?.(error);
+    });
+  }
+
+  private async save(): Promise<void> {
+    // Another pi window in the same workspace may have written since we loaded;
+    // keep whatever it added instead of overwriting it.
+    const known = new Set(this.entries);
+    const disk = (await this.readFromDisk()).filter((value) => !known.has(value));
+    this.entries = capped([...this.entries, ...disk], this.maxEntries);
+    await mkdir(this.dir, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+    const temp = `${this.filePath}.${process.pid}.tmp`;
+    try {
+      const payload = JSON.stringify({ version: 1, entries: this.entries }, null, 2);
+      await writeFile(temp, payload, { mode: PRIVATE_FILE_MODE });
+      await rename(temp, this.filePath);
+    } catch (error) {
+      await rm(temp, { force: true });
+      throw error;
+    }
+  }
+
+  private async readFromDisk(): Promise<string[]> {
+    try {
+      return parseEntries(JSON.parse(await readFile(this.filePath, "utf8")) as unknown);
+    } catch (error) {
+      // No history yet is the normal first-run state, not a failure.
+      if ((error as NodeJS.ErrnoException | null)?.code === "ENOENT") return [];
+      this.onError?.(error);
+      return [];
+    }
+  }
+}
+
+function parseEntries(raw: unknown): string[] {
+  const list = (raw as { entries?: unknown } | null)?.entries;
+  if (!Array.isArray(list)) return [];
+  const seen = new Set<string>();
+  const entries: string[] = [];
+  for (const value of list) {
+    if (typeof value !== "string") continue;
+    const entry = value.trim();
+    if (!entry || seen.has(entry)) continue;
+    seen.add(entry);
+    entries.push(entry);
+  }
+  return entries;
+}
+
+function capped(entries: string[], maxEntries: number): string[] {
+  return entries.length > maxEntries ? entries.slice(0, maxEntries) : entries;
+}