gentle-pi 3.7.0 → 4.1.0

package/extensions/gentle-stats.ts

@@ -0,0 +1,101 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { USER_PI_HOME_ENV } from "../lib/gentle-shell-launcher.ts";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
+import { withOverlayRepaint } from "../lib/overlay-repaint.ts";
+import { createStatsLoader, currentSessionStats, type StatsLoader } from "../lib/stats-collector.ts";
+import { StatsView } from "../lib/stats-view.ts";
+
+// Gentle Stats: /gentle:stats opens a full-terminal panel over local Pi
+// session history (tokens, cost, models, activity). It only reads the
+// session files Pi already writes; nothing new is persisted.
+//
+// History spans two homes: the active one (Gentle Shell's isolated home) and
+// the user's regular Pi home, which the launcher records before isolating.
+// Launched without it (plain pi, or an older launcher), the conventional
+// ~/.pi/agent stands in. The loader reads an alias of the same root once and
+// counts a session copied into both homes once.
+
+export const STATS_COMMAND_NAME = "gentle:stats";
+
+/** Optional shortcut; there is no default key because the common alt+ keys are taken. */
+export function statsViewKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_STATS_VIEW_KEY?.trim();
+	return !value || value.toLowerCase() === "off" ? undefined : value;
+}
+
+/** The sessions roots /gentle:stats reads: the active home and the user's original Pi home. */
+export function statsSessionRoots(agentDir: string, env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string[] {
+	const userHome = env[USER_PI_HOME_ENV] || join(home, ".pi", "agent");
+	return [join(agentDir, "sessions"), join(userHome, "sessions")];
+}
+
+export interface GentleStatsDeps {
+	env?: NodeJS.ProcessEnv;
+	now?: () => number;
+	sessionsRoots?: () => readonly string[];
+	loader?: StatsLoader;
+}
+
+export default function gentleStats(pi: ExtensionAPI, deps: GentleStatsDeps = {}): void {
+	const env = deps.env ?? process.env;
+	const now = deps.now ?? (() => Date.now());
+	const sessionsRoots = deps.sessionsRoots ?? (() => statsSessionRoots(getAgentDir(), env));
+	// One loader per process keeps its per-file cache across openings.
+	const loader = deps.loader ?? createStatsLoader();
+	const overlays = new Set<StatsView>();
+
+	const openOverlay = async (ctx: ExtensionContext) => {
+		if (!ctx.hasUI) return;
+		if (ctx.mode !== "tui") {
+			ctx.ui.notify("The stats overlay requires TUI mode.", "warning");
+			return;
+		}
+		let view: StatsView | undefined;
+		await ctx.ui.custom<null>(
+			(tui, theme, _keybindings, done) => {
+				const close = withOverlayRepaint(tui, done);
+				view = new StatsView({
+					theme,
+					rows: () => Math.max(0, tui.terminal.rows),
+					cwd: ctx.sessionManager.getCwd(),
+					now,
+					load: () => loader.load(sessionsRoots()),
+					current: () => currentSessionStats(ctx.sessionManager.getEntries(), { sessionId: ctx.sessionManager.getSessionId() ?? "", now: now() }),
+					onClose: () => close(null),
+					requestRender: () => tui.requestRender(),
+				});
+				overlays.add(view);
+				// Open at once with a loading state; the scan repaints when it settles.
+				void view.load();
+				const interaction = createNativeFullscreenInteraction({
+					keyboardTarget: view,
+					requestRender: () => tui.requestRender(),
+				});
+				interaction.addChild(view);
+				return interaction;
+			},
+			{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", margin: 0, anchor: "center" } },
+		).finally(() => {
+			view?.dispose();
+			if (view) overlays.delete(view);
+		});
+	};
+
+	pi.registerCommand(STATS_COMMAND_NAME, {
+		description: "Show local Pi usage stats: activity heatmap, tokens, cost, models, and this session. r cycles the range, s the project scope.",
+		handler: async (_args, ctx) => openOverlay(ctx),
+	});
+	const viewKey = statsViewKey(env);
+	if (viewKey) {
+		pi.registerShortcut(viewKey as Parameters<ExtensionAPI["registerShortcut"]>[0], {
+			description: "Show local Pi usage stats",
+			handler: async (ctx) => openOverlay(ctx),
+		});
+	}
+	pi.on("session_shutdown", () => {
+		for (const view of overlays) { view.handleInput("q"); view.dispose(); }
+		overlays.clear();
+	});
+}

package/extensions/gentle-todo.ts

@@ -1,7 +1,9 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Text, type Component, type TUI } from "@earendil-works/pi-tui";
+import { ScrollView, Text, truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import { appendSystemPromptOnce } from "../lib/append-system-prompt.ts";
 import { NativePointerRegion } from "../lib/native-pointer-region.ts";
-import { sidebarPart } from "../lib/shell-sidebar.ts";
+import { panelHeaderRow } from "../lib/shell-card.ts";
+import { sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
 import { invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
 import {
 	applyTodo,
@@ -12,6 +14,7 @@ import {
 	TODO_DETAILS_KEY,
 	TODO_GLYPH,
 	TODO_TOOL_NAME,
+	todoCardTone,
 	todoPromptBlock,
 	todoSummary,
 	type TodoParams,
@@ -21,12 +24,16 @@ import {
 // Gentle Todo: the task list the model keeps while it works, drawn as a
 // Gentle Shell card above the editor. Three things keep it current that a
 // static tool description cannot: `write` replaces the whole list in one
-// call, every turn's system prompt carries the open tasks and the rules, and
+// call, each run's system prompt carries the open tasks and the rules, and
 // a list that goes untouched while tasks stay open is marked stale for both
-// the human and the model.
+// the human and the model. Long runs also receive one request-local reminder
+// after several tool-use turns, without waking the agent or changing tasks.
 
 const WIDGET_KEY = "gentle-todo";
+const STATUS_ENUM = ["pending", "in_progress", "blocked", "done", "dropped"];
 const COLLAPSE_KEY_DEFAULT = "ctrl+shift+t";
+const REMIND_AFTER_TOOL_TURNS = 4;
+const TODO_REMINDER = "The todo plan has not been reviewed during several tool-use turns. Check whether it still matches the work performed and update tasks where needed. Do not mark work done without verification.";
 const TOOL_PARAMETERS = {
 	type: "object",
 	additionalProperties: false,
@@ -43,15 +50,15 @@ const TOOL_PARAMETERS = {
 				properties: {
 					id: { type: "integer", description: "Existing task id to keep." },
 					title: { type: "string", description: "Short imperative title, e.g. 'Write the parser'." },
-					status: { type: "string", enum: ["pending", "in_progress", "done"], description: "Defaults to pending." },
-					note: { type: "string", description: "What is happening right now, shown while in_progress, e.g. 'writing tests'." },
+					status: { type: "string", enum: STATUS_ENUM, description: "Defaults to pending. blocked: open but waiting on something outside the list; dropped: will not be done, on purpose." },
+					note: { type: "string", description: "What is happening right now, shown while in_progress, e.g. 'writing tests'; required for blocked, naming what it waits for, e.g. 'waiting for an admin'." },
 				},
 			},
 		},
 		id: { type: "integer", description: "Task id for update." },
 		title: { type: "string", description: "Title for add, or a new title for update." },
-		status: { type: "string", enum: ["pending", "in_progress", "done"], description: "Status for add or update." },
-		note: { type: "string", description: "Note for add or update." },
+		status: { type: "string", enum: STATUS_ENUM, description: "Status for add or update." },
+		note: { type: "string", description: "Note for add or update; required for blocked." },
 	},
 } as const;
 
@@ -70,12 +77,18 @@ export function todoCollapseKey(env: NodeJS.ProcessEnv = process.env): string |
 interface TodoSession {
 	state: TodoState;
 	turn: number;
+	/** Separate from the existing run-based card freshness. */
+	toolTurnsSinceWrite: number;
+	reminded: boolean;
+	wroteThisTurn: boolean;
 	collapsed: boolean;
 	/** A finished list stays on screen for the turn it finished in, then clears. */
 	clearOnNextTurn: boolean;
 	ui: ExtensionContext["ui"] | undefined;
 	host: { requestRender(): void } | undefined;
 	tui: TUI | undefined;
+	/** Resolve the visible host when the key is pressed, not when it renders. */
+	scrollTodo?: (lines: number) => void;
 }
 
 function sessionKey(ctx: ExtensionContext): string {
@@ -91,7 +104,7 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		const key = sessionKey(ctx);
 		let current = sessions.get(key);
 		if (!current) {
-			current = { state: emptyTodo(), turn: 0, collapsed: false, clearOnNextTurn: false, ui: undefined, host: undefined, tui: undefined };
+			current = { state: emptyTodo(), turn: 0, toolTurnsSinceWrite: 0, reminded: false, wroteThisTurn: false, collapsed: false, clearOnNextTurn: false, ui: undefined, host: undefined, tui: undefined };
 			sessions.set(key, current);
 		}
 		return current;
@@ -103,18 +116,51 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		current.host?.requestRender();
 	};
 
-	const todoCard = (current: TodoSession, theme: Parameters<typeof renderTodoCard>[1], scrollable: boolean, spacer: boolean): Component & { dispose(): void } => {
+	const todoCard = (current: TodoSession, theme: Parameters<typeof renderTodoCard>[1], spacer: boolean): Component & { dispose(): void; digest(): string; scrollBy(lines: number): void } => {
 		let hovered = false;
+		let body: string[] = [];
+		let collapsed = current.collapsed;
+		// Widgets are measured as leaves, so native layout cannot assign this
+		// body a viewport. Use native scroll state and explicitly slice its lines
+		// while keeping the collapse header and card footer outside the viewport.
+		const scroll = new ScrollView({ render: () => body, invalidate() {} }, { follow: "none", overscroll: "contain" });
+		const scrollBy = (lines: number) => {
+			if (current.collapsed) return;
+			scroll.scrollBy(lines);
+			if (current.tui) invalidateSidebar(current.tui);
+			current.host?.requestRender();
+		};
+		// The row the rendered card draws its header on: 0 for the outlined
+		// frame, 1 below the float panel's top padding row.
+		let headerRow = 0;
 		const card: Component = {
 			render(width: number) {
+				const stale = staleTurns(current.state, current.turn);
+				headerRow = panelHeaderRow(theme, width, todoCardTone(stale));
 				const lines = renderTodoCard(current.state, theme, width, {
 					collapsed: current.collapsed,
-					staleTurns: staleTurns(current.state, current.turn),
+					staleTurns: stale,
 					collapseKey,
 					hovered,
-					...(scrollable ? { scrollable: true } : {}),
+					scrollable: true,
 				});
-				return spacer && lines.length > 0 ? [...lines, ""] : lines;
+				if (collapsed !== current.collapsed) {
+					collapsed = current.collapsed;
+					scroll.scrollToStart();
+				}
+				// At most one third of the screen, capped at 16 rows. Read height
+				// on every render so a mobile resize immediately releases chat space.
+				const terminalRows = current.tui?.terminal?.rows ?? 48;
+				const height = Math.min(16, Math.floor(terminalRows / 3));
+				const bodyStart = headerRow === 1 ? 3 : 1;
+				body = lines.slice(bodyStart, -1);
+				const overflow = !current.collapsed && lines.length + Number(spacer) > height;
+				const room = Math.max(1, height - bodyStart - 1 - Number(spacer) - Number(overflow));
+				scroll.updateLayout(body.length, current.collapsed ? body.length : room, () => current.host?.requestRender());
+				const visible = scroll.render(width).slice(scroll.scrollTop, scroll.scrollTop + scroll.viewportHeight);
+				const output = [...lines.slice(0, bodyStart), ...visible, ...lines.slice(-1)];
+				if (overflow) output.push(theme.fg("muted", truncateToWidth(`↑↓ ${scroll.scrollTop + 1}–${scroll.scrollTop + visible.length}/${body.length} · ctrl+shift+↑/↓`, width)));
+				return spacer && output.length > 0 ? [...output, ""] : output;
 			},
 			invalidate() {
 				hovered = false;
@@ -122,10 +168,10 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		};
 		const region = new NativePointerRegion(card, {
 			onHover(event) {
-				// The region spans the whole card, but only the header row (y===0)
-				// is the clickable control, so a move elsewhere in the card clears
-				// hover exactly like leaving the region entirely would.
-				const next = event.y === 0;
+				// The region spans the whole card, but only the header row is the
+				// clickable control, so a move elsewhere in the card clears hover
+				// exactly like leaving the region entirely would.
+				const next = event.y === headerRow;
 				if (next === hovered) return { handled: true };
 				hovered = next;
 				return { handled: true, render: true };
@@ -136,12 +182,21 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 				current.host?.requestRender();
 			},
 			onClick(event) {
-				if (event.button !== "left" || event.y !== 0) return undefined;
+				if (event.button !== "left" || event.y !== headerRow) return undefined;
 				toggle(current);
 				return { handled: true, render: true };
 			},
+			onWheel(event) {
+				if (current.collapsed || body.length <= scroll.viewportHeight) return undefined;
+				scrollBy(event.wheelDelta ?? 0);
+				return { handled: true, render: true };
+			},
 		});
 		return {
+			scrollBy,
+			// Sidebar caches must observe height-only resizes and local viewport
+			// changes, even when terminal width and task content stay the same.
+			digest: () => JSON.stringify([current.tui?.terminal?.rows, current.collapsed, current.turn, hovered, scroll.scrollTop]),
 			render: (width) => region.render(width),
 			handleMouse: (event) => region.handleMouse(event),
 			invalidate: () => region.invalidate(),
@@ -153,6 +208,7 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		if (current.tui) invalidateSidebar(current.tui);
 		if (!current.ui) return;
 		if (current.state.tasks.length === 0) {
+			current.scrollTodo = undefined;
 			current.ui.setWidget(WIDGET_KEY, undefined);
 			return;
 		}
@@ -160,7 +216,15 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		current.ui.setWidget(WIDGET_KEY, (tui, theme) => {
 			snapshot.host = tui;
 			snapshot.tui = tui;
-			return sidebarPart(tui, "todo", todoCard(snapshot, theme, false, true), todoCard(snapshot, theme, true, false));
+			const bottom = todoCard(snapshot, theme, true);
+			const rail = todoCard(snapshot, theme, false);
+			snapshot.scrollTodo = (lines) => {
+				// Cached rail lines do not re-render when a narrow→wide resize
+				// restores the sidebar. Select ownership from the live layout.
+				const state = tui.terminal ? sidebarState(tui) : undefined;
+				(state?.active && state.ownsHost?.() ? rail : bottom).scrollBy(lines);
+			};
+			return sidebarPart(tui, "todo", bottom, rail);
 		});
 	};
 
@@ -175,6 +239,8 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 			"Mark a task in_progress before starting it and done right after finishing it; keep exactly one task in_progress.",
 			"Prefer write with the complete list whenever the plan changes; keep ids of tasks that already exist.",
 			"Never mark a task done while tests fail or the work is partial; add a task for the blocker instead.",
+			"Mark a task blocked with a note naming what it waits for only when that is outside the list (a person, another team, an authorization); a prerequisite in the list is ordering, so keep the task pending. Return it to pending once the condition holds.",
+			"When the plan changes, mark tasks it made obsolete dropped, never done; dropped tasks no longer count as open.",
 		],
 		parameters: TOOL_PARAMETERS,
 		executionMode: "sequential",
@@ -192,6 +258,11 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 			if (!result.error) {
 				current.state = result.state;
 				current.clearOnNextTurn = false;
+				if (params.action !== "list") {
+					current.toolTurnsSinceWrite = 0;
+					current.reminded = false;
+					current.wroteThisTurn = true;
+				}
 				if (current.tui) invalidateSidebar(current.tui);
 			}
 			return {
@@ -210,6 +281,13 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		});
 	}
 
+	for (const [key, lines] of [["ctrl+shift+up", -3], ["ctrl+shift+down", 3]] as const) {
+		pi.registerShortcut(key, {
+			description: `Scroll the Todo list ${lines < 0 ? "up" : "down"}`,
+			handler: async (ctx) => session(ctx).scrollTodo?.(lines),
+		});
+	}
+
 	pi.on("session_start", (_event, ctx) => {
 		const current = session(ctx);
 		// A list that was already finished when the session was left is history,
@@ -217,6 +295,9 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		const replayed = replayTodo(ctx.sessionManager.getBranch());
 		current.state = replayed.tasks.length > 0 && todoSummary(replayed).open === 0 ? { ...replayed, tasks: [] } : replayed;
 		current.turn = ctx.sessionManager.getBranch().filter((entry) => (entry as { type?: string }).type === "message" && (entry as { message?: { role?: string } }).message?.role === "user").length;
+		current.toolTurnsSinceWrite = 0;
+		current.reminded = false;
+		current.wroteThisTurn = false;
 		current.ui = ctx.hasUI ? ctx.ui : undefined;
 		show(current);
 	});
@@ -236,7 +317,32 @@ export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = pr
 		}
 		const block = todoPromptBlock(current.state, staleTurns(current.state, current.turn));
 		if (!block) return undefined;
-		return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+		// gentle-shell#1485: pi-claude-bridge drops a handler-returned
+		// systemPrompt, so the open-tasks block goes through appendSystemPrompt.
+		appendSystemPromptOnce(event.systemPromptOptions, block);
+		return undefined;
+	});
+
+	pi.on("turn_end", (event, ctx) => {
+		const current = session(ctx);
+		// A turn containing a valid todo write is already reconciled. Failed
+		// writes and list reads deliberately do not refresh this counter.
+		if (!current.wroteThisTurn && event.message.role === "assistant" && event.message.content.some((part) => part.type === "toolCall")) {
+			current.toolTurnsSinceWrite += 1;
+		}
+		current.wroteThisTurn = false;
+	});
+
+	pi.on("context", (event, ctx) => {
+		const current = session(ctx);
+		if (current.reminded || current.toolTurnsSinceWrite < REMIND_AFTER_TOOL_TURNS) return undefined;
+		if (!current.state.tasks.some((task) => task.status === "pending" || task.status === "in_progress")) return undefined;
+		current.reminded = true;
+		// Context transforms are request-local: no transcript entry, UI
+		// notification, continuation or provider-specific wake is needed.
+		return {
+			messages: [...event.messages, { role: "custom" as const, customType: "gentle-todo-reminder", content: TODO_REMINDER, display: false, timestamp: Date.now() }],
+		};
 	});
 
 	pi.on("tool_execution_end", (event, ctx) => {

package/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;
+  }
+}

package/extensions/history/hide-prompts.ts

@@ -0,0 +1,183 @@
+// SPDX-FileCopyrightText: 2026 ExoPro. Inspired by @jasonish/pi-prompt-history
+// SPDX-License-Identifier: MIT
+
+import { createHash } from "node:crypto";
+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";
+
+/** Marks tombstone entries written in the exact (hashed) key format. */
+const TOMBSTONE_KEY_PREFIX = "sha256:";
+
+/**
+ * UI-level prompt identity: whitespace-collapsed, trimmed, case-insensitive,
+ * never truncated. The store's scope deletes sweep by this same identity,
+ * so a tombstone hides exactly the copies a delete removes.
+ */
+export function promptIdentity(text: string): string {
+  return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+/**
+ * Tombstone key for `text`: a SHA-256 of its full prompt identity. Exact —
+ * two prompts that merely share a prefix get different keys — and hashed,
+ * so hidden.json never holds the text of a deleted prompt.
+ */
+export function tombstoneKey(text: string): string {
+  return (
+    TOMBSTONE_KEY_PREFIX +
+    createHash("sha256").update(promptIdentity(text)).digest("hex")
+  );
+}
+
+/**
+ * Whether `text` is hidden by the tombstone set `keys`. Hashed keys match
+ * the exact prompt identity. Plaintext entries from the earlier prefix
+ * format (`promptDedupKey`: the first 120 normalized characters) stay
+ * honored as written, so upgrading never resurfaces a hidden prompt; only
+ * new deletions use the exact format.
+ */
+export function isPromptHidden(keys: ReadonlySet<string>, text: string): boolean {
+  if (keys.size === 0) return false;
+  return keys.has(tombstoneKey(text)) || keys.has(promptDedupKey(text));
+}
+
+/**
+ * Retention cap for hidden.json (slice-05 D5): the tombstone file is a
+ * rebuildable derived cache, not a retention guarantee, so it holds at
+ * most this many keys in recency order; hiding past the cap drops the
+ * OLDEST keys from the front.
+ */
+export const HIDE_FILE_MAX_ENTRIES = 1000;
+
+/**
+ * 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 the
+ * `tombstoneKey` hashes written by `hidePrompt`, or plaintext entries from
+ * the earlier prefix format (see `isPromptHidden`); the call never throws.
+ * A valid array's stored order is preserved (the recency order — oldest
+ * first — that `hidePrompt` maintains and caps).
+ */
+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
+ * `tombstoneKey` (byte-match normative with the drain and seed filters via
+ * `isPromptHidden` — never a re-implementation). The file array is RECENCY-ordered — oldest key
+ * first, newest key appended last — and re-hiding an existing key
+ * refreshes it to the end (delete + add, since Set.add on a present
+ * member keeps its old position). The file is capped at
+ * `HIDE_FILE_MAX_ENTRIES` (1000): after the append, keys drop from the
+ * FRONT until the file fits, so hidden.json stays a bounded cache — a
+ * dropped (oldest) prompt may reappear in the list and can be deleted
+ * again. Keys persist in that insertion order — NO sort — 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 };
+  }
+  // Recency order (slice-05 D5): the set iterates in stored file order
+  // (oldest first); delete+add refreshes a re-hidden key to the END.
+  const key = tombstoneKey(text);
+  read.keys.delete(key);
+  read.keys.add(key);
+  // Cap: drop the OLDEST keys from the front once over the limit.
+  const ordered = [...read.keys];
+  if (ordered.length > HIDE_FILE_MAX_ENTRIES) {
+    ordered.splice(0, ordered.length - HIDE_FILE_MAX_ENTRIES);
+  }
+  const written = writeJsonAtomic(
+    path.join(stateDir, HIDE_FILE_NAME),
+    ordered,
+  );
+  return written
+    ? { status: "written" }
+    : {
+        status: "error",
+        message: "Could not write the hide file; the prompt may reappear.",
+      };
+}