feat(history): history selector TUI and command/shortcut wiring (slice 3/6)

docs/prompt-history.md

@@ -0,0 +1,61 @@
+# Prompt history
+
+Slice 1 of the prompt-history extension (#819 split) ships the storage layer only:
+a per-instance JSONL capture store, project identity, and the read/write
+primitives later slices build on. The selector UI, deletion/scope drains, and GC
+arrive in later slices of the chain.
+
+## Capture is opt-in
+
+Recording is **off by default**. Delivered prompts can contain secrets, and the
+deletion UI is not shipped yet, so nothing is stored unless you explicitly opt in:
+
+```bash
+GENTLE_PI_HISTORY_CAPTURE=1 pi
+```
+
+- Enabled by `1`, `true`, or `on` (case-insensitive). Unset, empty, or any other
+  value means **off** — the same switch is the disable path.
+- The check runs per prompt: unsetting the switch (or setting it to `0`) stops
+  new captures immediately, no pi restart needed.
+- With capture off the extension is inert: no registry entry, no files, and
+  prompts are never written.
+
+## Where the files live
+
+Everything sits under `~/.pi/agent/history/`:
+
+- `registry.json` — advisory map of project hash → cwd, used for display
+  labels.
+- `projects/<hash>/<instance>.jsonl` — one append-only capture file per pi
+  process.
+
+`<hash>` is the first 16 hex chars of the SHA-256 of the canonicalized project
+cwd; `<instance>` is a per-process UUID. Each line is one delivered prompt:
+
+```json
+{"v":1,"text":"the prompt as delivered","ts":1700000000000}
+```
+
+UI command-like prompts (`/name ...`) and empty lines are never stored. Later
+slices add the rebuildable `seed.jsonl`, scope drains/deletes, and GC.
+
+## Who can read them
+
+The store is plain JSONL on your local disk, not encrypted. Files are created by
+the pi process with default umask permissions (typically `0644` files inside
+`0755` directories), so any process running as your OS user can read them, and
+other local accounts can too wherever they can traverse your home directory.
+Treat the store as sensitive: it holds your prompts verbatim.
+
+## What disabling capture does
+
+Turning the switch off only stops **new** captures. Nothing is deleted: files
+already written — and the registry entry — stay on disk until you remove them or
+the deletion UI ships. To erase the store manually while capture is off (or pi
+is not running):
+
+```bash
+rm -rf ~/.pi/agent/history            # whole store
+rm -rf ~/.pi/agent/history/projects/<hash>   # one project (see registry.json)
+```

extensions/history/atomic-write.ts

@@ -0,0 +1,38 @@
+import path from "node:path";
+// SPDX-FileCopyrightText: 2026 ExoPro. Inspired by @jasonish/pi-prompt-history
+// SPDX-License-Identifier: MIT
+
+import fs from "node:fs";
+
+/**
+ * Shared atomic JSON writer (design §D3): serialize to a `.tmp` file in the
+ * SAME directory as the target, then renameSync it into place — a same-dir
+ * rename is atomic on POSIX/APFS, so readers see the old or the new file,
+ * never a partial write. Any error returns false and never throws.
+ *
+ * No fsync: both consumers treat lost writes as derived cache (a lost index
+ * rebuilds on the next open; a lost tombstone resurfaces a prompt the user
+ * can re-delete), so the per-write fsync cost is not justified — the crash
+ * window is documented, not fixed. The staging name is unique per write
+ * (`.tmp-<pid>-<ts>`, the same convention as the store.ts writers): the
+ * state dir is shared across concurrent pi instances, so a fixed
+ * `${filePath}.tmp` would let two writers clobber the same staging file
+ * (torn target JSON, spurious rename failures). A failed write unlinks its
+ * staging file, so orphaned `.tmp` files do not accumulate.
+ */
+export function writeJsonAtomic(filePath: string, value: unknown): boolean {
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(tmpPath, JSON.stringify(value), "utf8");
+    fs.renameSync(tmpPath, filePath);
+    return true;
+  } catch {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      // staging file never created or already renamed
+    }
+    return false;
+  }
+}

extensions/history/hide-prompts.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 ExoPro. Inspired by @jasonish/pi-prompt-history
+// SPDX-License-Identifier: MIT
+
+import fs from "node:fs";
+import path from "node:path";
+import { writeJsonAtomic } from "./atomic-write.ts";
+import { promptDedupKey } from "./selector-helpers.ts";
+
+/** Name of the tombstone file inside the injected state dir (spec C4). */
+const HIDE_FILE_NAME = "hidden.json";
+
+/**
+ * Shared recovery warning for a file that exists but cannot be trusted
+ * (spec C4, fail-closed READ half): toast-suitable, names hidden.json, and
+ * gives the user the explicit restore-or-delete choice.
+ */
+const RECOVERY_MESSAGE =
+  "The prompt-history hide list (hidden.json) is corrupt or unreadable. History is blocked until you restore the file or delete it (hidden prompts may then reappear).";
+
+/**
+ * Result of one tombstone write (spec C4): `written` on a successful atomic
+ * write, or an error object carrying a short, toast-suitable reason. Never
+ * throws.
+ */
+export type HideResult =
+  | { status: "written" }
+  | { status: "error"; message: string };
+
+/**
+ * Result of one tombstone read (spec C4): `trusted` keys when the file is
+ * missing or holds a valid array, or `untrusted` when the file exists but
+ * cannot be trusted. History reads FAIL CLOSED on `untrusted`: callers must
+ * block the drain instead of emptying the tombstone set, because hidden
+ * prompts may contain secrets an empty set would resurface.
+ */
+export type HiddenRead =
+  | { status: "trusted"; keys: Set<string> }
+  | {
+      status: "untrusted";
+      reason: "unreadable" | "corrupt" | "malformed";
+      message: string;
+    };
+
+/**
+ * Read the tombstone key set from `stateDir/hidden.json` — the READ half of
+ * the hide-file contract (spec C4). Fail-closed for history: a file that
+ * exists but is unreadable, corrupt, or wrong-shaped returns `untrusted`
+ * with the recovery warning so callers block the drain; it never degrades
+ * to an empty trusted set. A MISSING file — before any deletion — is the
+ * safe empty case and reads `trusted` with no keys. A valid array is
+ * trusted; junk items inside it are ignored, never trusted. Keys are
+ * `promptDedupKey` strings written by `hidePrompt`; the call never throws.
+ */
+export function readHiddenPrompts(stateDir: string): HiddenRead {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(path.join(stateDir, HIDE_FILE_NAME), "utf8");
+  } catch (error) {
+    const code = (error as { code?: unknown } | null | undefined)?.code;
+    if (code === "ENOENT") {
+      // Missing before any deletion: the safe empty tombstone set.
+      return { status: "trusted", keys: new Set<string>() };
+    }
+    return {
+      status: "untrusted",
+      reason: "unreadable",
+      message: RECOVERY_MESSAGE,
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { status: "untrusted", reason: "corrupt", message: RECOVERY_MESSAGE };
+  }
+  const keys = new Set<string>();
+  if (!Array.isArray(parsed)) {
+    return {
+      status: "untrusted",
+      reason: "malformed",
+      message: RECOVERY_MESSAGE,
+    };
+  }
+  for (const item of parsed) {
+    if (typeof item === "string" && item !== "") keys.add(item);
+  }
+  return { status: "trusted", keys };
+}
+
+/**
+ * Write the tombstone key for `text` into `stateDir/hidden.json` — the
+ * WRITE half of the hide-file contract (spec C4). The key is the shared
+ * `promptDedupKey` (byte-match normative with the merge filter — never a
+ * re-implementation); the set compacts on write and persists as a SORTED
+ * array via the shared atomic tmp+rename writer. An untrusted existing file
+ * is never silently reset (a clean rewrite would clear the blocked state
+ * one hide later): hidePrompt refuses with the recovery warning until the
+ * user restores or deletes the file. A missing file is the clean baseline;
+ * any write failure returns an error object for the delete-flow toast; the
+ * call never throws.
+ */
+export function hidePrompt(stateDir: string, text: string): HideResult {
+  const read = readHiddenPrompts(stateDir);
+  if (read.status === "untrusted") {
+    // Refuse without writing: never reset the untrusted state silently.
+    return { status: "error", message: read.message };
+  }
+  read.keys.add(promptDedupKey(text));
+  const written = writeJsonAtomic(
+    path.join(stateDir, HIDE_FILE_NAME),
+    [...read.keys].sort(),
+  );
+  return written
+    ? { status: "written" }
+    : {
+        status: "error",
+        message: "Could not write the hide file; the prompt may reappear.",
+      };
+}