feat(history): read, ordering, deduplication, and project/global query APIs (slice 2/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.",
+      };
+}

extensions/history/index.ts

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 ExoPro. Inspired by @jasonish/pi-prompt-history
+// SPDX-License-Identifier: MIT
+
+// Prompt-history extension entry (slice 1): identity constants, the
+// per-instance writer lifecycle, and the before_agent_start capture
+// handler. Selector UI, shortcut/command, scope drains, legacy migration
+// and seed bootstrap, and GC arrive in later slices.
+//
+// Capture is OPT-IN while the deletion/privacy behavior is unshipped:
+// nothing is recorded unless GENTLE_PI_HISTORY_CAPTURE=1|true|on. With the
+// switch off the handler is a no-op — no registry entry, no files, and
+// prompts are never written. Unsetting the switch only stops NEW captures;
+// files already written stay on disk (docs/prompt-history.md).
+
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  appendSessionCapture,
+  ensureRegistryEntry,
+  openSessionWriter,
+  type SessionWriterState,
+} from "./store.ts";
+
+// v2 multi-concurrency store root (design: tmp/multi-concurrency-design.md).
+const PI_HISTORY_ROOT = join(homedir(), ".pi", "agent", "history");
+
+export interface HistoryDeps {
+  env?: NodeJS.ProcessEnv;
+  root?: string;
+  cwd?: string;
+  instanceId?: string;
+  now?: () => number;
+}
+
+/**
+ * Strict opt-in: capture stays off unless GENTLE_PI_HISTORY_CAPTURE is
+ * explicitly 1, true, or on (case-insensitive). The same switch is the
+ * disable path — unsetting it stops new captures; files already on disk
+ * are left untouched until the deletion tooling lands.
+ */
+export function captureEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env.GENTLE_PI_HISTORY_CAPTURE?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "on";
+}
+
+export default function promptHistoryExtension(
+  pi: ExtensionAPI,
+  deps: HistoryDeps = {},
+): void {
+  const env = deps.env ?? process.env;
+  const root = deps.root ?? PI_HISTORY_ROOT;
+  const cwd = deps.cwd ?? process.cwd();
+  const instanceId = deps.instanceId ?? randomUUID();
+  const now = deps.now ?? Date.now;
+  let writerState: SessionWriterState | null = null;
+
+  /**
+   * One-time init per extension load: register the project in the advisory
+   * registry, then open this instance's exclusive capture file. Legacy
+   * migration and seed bootstrap join this init order in a later slice.
+   */
+  const getWriter = (): SessionWriterState => {
+    if (!writerState) {
+      try {
+        ensureRegistryEntry(root, cwd);
+      } catch {
+        // registry is advisory
+      }
+      writerState = openSessionWriter(root, cwd, instanceId);
+    }
+    return writerState;
+  };
+
+  // Persist every delivered user prompt (write-through, append-only JSONL),
+  // but only for opted-in sessions — see captureEnabled(). The local
+  // ExtensionAPI stub types handler args as unknown; narrow here.
+  pi.on("before_agent_start", (...args: unknown[]) => {
+    if (!captureEnabled(env)) return;
+    try {
+      const event = args[0] as { prompt?: string } | undefined;
+      appendSessionCapture(getWriter(), event?.prompt ?? "", now());
+    } catch {
+      // A capture failure must never break the agent loop or unregister
+      // the handler - swallow and keep the next prompt capturable.
+    }
+  });
+}