feat(history): tombstones, deletion, and privacy semantics (slice 5/6)

README.md

@@ -880,6 +880,7 @@ To opt out:
 | `docs/skill-style-guide.md`    | Normative style guide used by the packaged skill creation/improvement skills.                              |
 | `docs/native-authority-architecture.md` | Post-U8 ownership boundary, reproducible slimming metrics, Windows evidence, exact #191 seam, and the `review-integration/v1`→`v2` migration status, including the "compact-v2" naming disambiguation.     |
 | `docs/review-integration.md`   | Negotiated provider/consumer contract and the current Gentle Pi adoption boundary.                         |
+| `docs/prompt-history.md`       | Prompt-history slice 1: opt-in capture switch, storage layout, readers, and disable/removal semantics.      |
 
 ## Development
 

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/index.ts

@@ -4,20 +4,28 @@
 // Prompt-history extension entry (slice 3): the selector TUI, overlay glue,
 // and the shortcut/command wiring over the slice-1 writer, slice-2 drains,
 // and slice-4 init sequence (legacy migration + seed bootstrap run once
-// inside getWriter). Deletion (slice 5) and GC/compaction (slice 6) arrive
-// in later slices.
+// inside getWriter). Deletion (slice 5) is wired here; GC/compaction
+// (slice 6) arrives in a later slice.
+//
+// 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 { join } from "node:path";
 import { homedir } from "node:os";
 import {
   DynamicBorder,
   type ExtensionAPI,
-  type ShortcutContext,
+  type ExtensionCommandContext,
   type Theme,
 } from "@earendil-works/pi-coding-agent";
 import {
   appendSessionCapture,
   bootstrapProjectSeed,
+  deleteFromGlobal,
+  deleteFromProject,
   drainGlobal,
   drainProject,
   ensureRegistryEntry,
@@ -26,15 +34,18 @@ import {
   type SessionWriterState,
 } from "./store.ts";
 import { randomUUID } from "node:crypto";
+import { hidePrompt } from "./hide-prompts.ts";
 import {
   buildPromptRecords,
   filterPrompts,
   type PromptEntry,
   clampPreviewOffset,
   clampSelectedIndex,
+  deletionActionsFor,
   dedupePromptEntries,
   getVisiblePromptRecords,
   initialLoadedCount,
+  loadedCountAfterDelete,
   loadedCountForQuery,
   loadedCountForTarget,
   moveSelectedIndex,
@@ -292,6 +303,10 @@ class PromptHistorySelector extends Container implements Focusable {
       match: (d, _kb) => matchesKey(d, "end"),
       handler: () => this.jumpToLast(),
     },
+    {
+      match: (d, _kb) => matchesKey(d, "ctrl+shift+backspace"),
+      handler: () => this.deleteCurrent(),
+    },
     {
       match: (d, _kb) => matchesKey(d, "ctrl+shift+up"),
       handler: () => this.previewPageUp(),
@@ -364,7 +379,7 @@ class PromptHistorySelector extends Container implements Focusable {
       new FixedRowText(
         theme.fg(
           "dim",
-          "↑↓ move • PgUp/PgDn page • tab scope • enter select and quit • ctrl+shift+↑/↓ preview • esc cancel",
+          "↑↓ move • PgUp/PgDn page • tab scope • enter select and quit • ctrl+shift+↑/↓ preview • ctrl+shift+backspace delete • esc cancel",
         ),
         true /* centered */,
       ),
@@ -547,6 +562,54 @@ class PromptHistorySelector extends Container implements Focusable {
     this.applyFilter(this.searchInput.getValue());
   }
 
+  /** Delete the currently selected prompt from disk and refresh the list. */
+  private deleteCurrent(): void {
+    const selected = this.filteredRecords[this.selectedIndex];
+    if (!selected) return;
+
+    // C4 delete flows (design §F): the record's provenance decides the
+    // actions via the pure planner; module constants are used directly.
+    const actions = deletionActionsFor(selected.source ?? "editor");
+
+    if (actions.deleteFromEditorStore) {
+      // Store path: physically remove EVERY copy from the JSONL store
+      // (memory + file in one atomic rewrite).
+      const { removed } =
+        this.scope === "global"
+          ? deleteFromGlobal(PI_HISTORY_ROOT, selected.text)
+          : deleteFromProject(PI_HISTORY_ROOT, CURRENT_CWD, selected.text);
+      if (removed === 0) return;
+    }
+
+    // Tombstone ALWAYS: the session transcripts are immutable and would
+    // re-supply the deleted prompt on the next merge (hide-file suppresses
+    // the twin). Only the session path aborts on a hide error — the store
+    // row is already gone on the editor path, so the splice proceeds.
+    const hide = hidePrompt(PI_HISTORY_NAV_STATE_DIR, selected.text);
+    if (hide.status === "error") {
+      this.onNotify?.(hide.message, "error");
+      if (!actions.deleteFromEditorStore) {
+        return;
+      }
+    }
+    // Remove from the master records array so a subsequent filter doesn't
+    // bring it back.
+    const idx = this.records.indexOf(selected);
+    if (idx !== -1) {
+      this.records.splice(idx, 1);
+      // C4 delete backfill (design §B3): shrink the window with the splice,
+      // then pull the next unloaded row while any remain — genuine shrink
+      // only at exhaustion.
+      this.loadedCount = loadedCountAfterDelete(
+        this.loadedCount,
+        this.records.length,
+      );
+    }
+
+    // Re-apply current filter (rebuilds filteredRecords, list, preview).
+    this.applyFilter(this.searchInput.getValue());
+  }
+
   // -- Navigation ---------------------------------------------------------
 
   private moveUp(): void {
@@ -823,7 +886,7 @@ function createPromptHistorySelectorFactory(
 }
 
 async function runPromptHistorySelection(
-  ctx: ShortcutContext,
+  ctx: Pick<ExtensionCommandContext, "ui">,
   records: PromptRecord[],
 ): Promise<PromptRecord | null> {
   const historyGlobals: PiHistoryGlobals = globalThis as Record<
@@ -899,7 +962,7 @@ function drainForScope(scope: HistoryScope): string[] {
 }
 
 async function openHistorySelector(
-  ctx: Pick<ShortcutContext, "ui">,
+  ctx: Pick<ExtensionCommandContext, "ui">,
 ): Promise<void> {
   // Store-only drain (user-directed): both scopes read the store files
   // symmetrically — no live transcript merge (the one-time seed bootstrap
@@ -931,27 +994,89 @@ function recordsFromEntries(
   return buildPromptRecords(dedupePromptEntries(entries));
 }
 
-export default function promptHistoryExtension(pi: ExtensionAPI) {
-  // One writer per extension load; see getWriter() for the init order.
-  // Warm migrate/registry/seed OFF the first-prompt path: the scheduled
-  // init runs once, immediately after load. A prompt arriving earlier
-  // falls back to the synchronous lazy init in getWriter(), whose
-  // writerState guard makes whichever runs second a no-op — bootstrap
-  // work is never duplicated.
+
+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 ?? CURRENT_CWD;
+  const instanceId = deps.instanceId ?? INSTANCE_ID;
+  const now = deps.now ?? Date.now;
+  let writerState: SessionWriterState | null = null;
+
+  /**
+   * One-time init per extension load: migrate legacy stores, register the
+   * project, bootstrap the seed, then open this instance's exclusive file.
+   */
+  const getWriter = (): SessionWriterState => {
+    if (!writerState) {
+      try {
+        migrateLegacyStores(root, AGENT_DIR);
+      } catch {
+        // migration is best-effort; the gate keeps it one-shot
+      }
+      try {
+        ensureRegistryEntry(root, cwd);
+      } catch {
+        // registry is advisory
+      }
+      try {
+        bootstrapProjectSeed(
+          root,
+          cwd,
+          SESSIONS_ROOT,
+          500,
+          PI_HISTORY_NAV_STATE_DIR,
+        );
+      } catch {
+        // bootstrap is a rebuildable cache
+      }
+      writerState = openSessionWriter(root, cwd, instanceId);
+    }
+    return writerState;
+  };
+
+  // Warm migrate/registry/seed OFF the first-prompt path, but only for
+  // opted-in sessions: with capture disabled nothing may be written —
+  // no registry entry, no seed files, no store (docs/prompt-history.md).
   setImmediate(() => {
+    if (!captureEnabled(env)) return;
     try {
       getWriter();
     } catch {
       // init is best-effort; the lazy path retries on the next prompt
     }
   });
 
-  // Persist every delivered user prompt (write-through, append-only JSONL).
-  // The local ExtensionAPI stub types handler args as unknown; narrow here.
+  // 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 ?? "", Date.now());
+      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.

extensions/history/selector-helpers.ts

@@ -215,6 +215,46 @@ export function loadedCountForTarget(
   return next;
 }
 
+/**
+ * Delete backfill (spec C4's two steps verbatim, AC-L4-1..3): decrement the
+ * window against the splice-shrunk snapshot; while unloaded rows remain,
+ * backfill one row (clamped) so the next unloaded record slides into the
+ * deleted slot and the visible list length stays stable; at exhaustion the
+ * decrement is the genuine shrink. Written stepwise — NOT the algebraic
+ * min(L, T') shortcut — so the unit tests pin the contract, not an
+ * equivalence. Callers guarantee the deleted row sits inside the loaded
+ * prefix (idx < loadedCount by construction).
+ */
+export function loadedCountAfterDelete(
+  loadedCount: number,
+  totalCountAfterSplice: number,
+): number {
+  const decrement = loadedCount - 1;
+  if (decrement < totalCountAfterSplice) {
+    return Math.min(decrement + 1, totalCountAfterSplice);
+  }
+  return decrement;
+}
+
+/**
+ * Pure delete-flow planner (spec C4, design §F): maps a record's provenance
+ * to the two delete actions. "editor" deletes from the editor store on disk
+ * AND writes the tombstone (twin suppression — the session copy of the same
+ * text would otherwise resurface next open); "session" writes the tombstone
+ * only (session transcripts are NEVER written). Takes source as a plain
+ * parameter (no member reads — the T23 provenance pin keeps overlay
+ * consumers source-agnostic outside deleteCurrent); the only consumer is
+ * deleteCurrent in history/index.ts.
+ */
+export function deletionActionsFor(
+  source: PromptSource,
+): { deleteFromEditorStore: boolean; writeTombstone: boolean } {
+  if (source === "editor") {
+    return { deleteFromEditorStore: true, writeTombstone: true };
+  }
+  return { deleteFromEditorStore: false, writeTombstone: true };
+}
+
 export function getVisiblePromptRecords(
   records: PromptRecord[],
   selectedIndex: number,