@saifymatteo/pi-session-retention 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.6]
+
+### Added
+
+- Preview trashed sessions in place with Enter, scroll read-only conversation excerpts, and switch between family members. Messages use Pi's themed Markdown rendering with highlighted code blocks and isolated formatting per excerpt. Ctrl+R requests a confirmed whole-family restore from either search or preview; Esc returns from preview without losing the search.
+- Support Page Up/Page Down and Home/End in Session Trash: page through search results and previews, and jump straight to the first or last family or to the preview's top and bottom.
+- Group Session Trash families under their originating project directories, matching session search: folder headers use the cached working directory when known, the selected family's folder stays fixed above the scrolling list, and filtering keeps only folders with matches.
+- Open Session Trash before transcript indexing finishes, enrich search in the background, and reuse guarded metadata caches for unchanged files. Closing the picker cancels indexing; stale or unsafe metadata falls back to filenames without weakening restore or purge validation.
+- Clean unrelated inactive session families while other Pi instances stay open, protecting registered open sessions and coordinating session changes across windows. Unregistered or unverifiable instances still defer maintenance.
+
+### Fixed
+
+- Wait for in-flight automatic cleanup when opening Session Trash or requesting explicit cleanup, instead of requiring a retry after reload; retain lock and shutdown safeguards.
+- Separate Trash preview UI from transcript text with fixed muted project metadata, ruled sections, message-body rails, and a fixed excerpt-status strip. Preserve blue/yellow bold role headers without a user-message background.
+- Accept OS pseudo-processes with PID 0, such as Windows System Idle Process, instead of incorrectly deferring session registration and cleanup previews.
+
+## [0.1.5]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.4]
+
+### Fixed
+
+- Schedule automatic maintenance outside the awaited session-start handler; defer launch while the agent is busy.
+- Offer `/session-cleanup` for first approval without interrupting startup, retaining store locking, protected sessions, and shutdown draining.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as an extension in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/README.md

@@ -31,7 +31,7 @@ Moves inactive session families out of Pi's searchable session store. No search
 - `/session-cleanup preview` — show counts, scope and example candidate families without moving or deleting sessions.
 - `/session-cleanup` — review the first cleanup and approve daily automatic maintenance. Later calls run maintenance immediately.
 - `/session-cleanup pause` — pause automatic maintenance; run `/session-cleanup` to review and enable it again.
-- `/session-trash [query]` — open a dialog styled like `session-finder.ts`, with a heavy border, padded rows, a `Search:` line and yellow selection, listing trashed families immediately. Type to filter by names, first user prompts, IDs or original paths; use ↑↓ and Enter to select, then confirm a whole-family restore. Esc cancels. An optional query prefills the filter; clearing it shows all families again.
+- `/session-trash [query]` — search trashed families by name, first user prompt, ID or original path. ↑↓ selects; Enter previews; Ctrl+R requests a confirmed whole-family restore from either view. In preview, `[ ]` switches members and ↑↓ / PgUp/PgDn scrolls. Esc returns to search or closes it. An optional query prefills the filter.
 
 `/session-cleanup` advertises `[preview|pause]` and offers both arguments through command completion.
 
@@ -51,13 +51,13 @@ Startup reads bounded session headers and file metadata, not every transcript. A
 
 ## Safety and recovery
 
-- Maintenance is serialized by an exclusive per-store lock. Process discovery must succeed, and maintenance defers when its inventory finds another recognized Pi CLI process, including idle windows. Successful inventories are reused for at most one second within a maintenance transaction to avoid starting PowerShell for every file. Session switches and forks in the current window are blocked until maintenance ends. It does not assume that excluding this window protects other windows. Close other Pi windows and run `/session-cleanup` to retry. Unrecognized custom SDK hosts and programs with renamed executables are outside this process detector's guarantee; do not run maintenance alongside them.
+- Maintenance protects every verified open session's whole family, including idle windows, while cleaning unrelated inactive families. All open instances must load the updated extension and share an agent home; reload/update or close any instance reported as unregistered. Shared registration and per-store locks serialize maintenance and block session switches/forks until it ends. Unrecognized SDK hosts and renamed executables remain outside process detection; do not run maintenance alongside them.
 - On `/reload`, session replacement or graceful shutdown, maintenance cancels pending approval/Trash dialogs, stops at the next safety boundary and waits for in-flight file work to finish before releasing its lock. The lock is never removed while its operation can still mutate files. Forced termination or a crash can still leave a stale lock; these are not automatically removed.
 - Each family has a recovery manifest written before any file moves. Incomplete operations remain recoverable in `/session-trash` and are never automatically purged. Keep the manifest with its files. If the process crashes leaving `.maintenance.lock`, close all Pi processes before removing that stale lock and retrying. A corrupt lock fails closed rather than being guessed away.
 - Symlink paths, invalid headers, unresolved parents, family cycles, changed files and corrupt/path-escaping manifests are rejected or protected. An unreadable session can defer cleanup because the complete family graph cannot be established safely. Restore collisions do not overwrite either copy.
 - Moving session files does not retroactively ingest them into external memory integrations. Such integrations retain their live in-memory state and flush outstanding writes at shutdown; they do not depend on reopening historical JSONL files for those writes. Earlier failed ingestion is not repaired by this extension.
 
-Keep other Pi windows closed during maintenance. Sampled OS process discovery and an extension-owned lock are conservative safeguards, not a native session lock honored by every external program. A new external process can race a cleanup; do not launch another Pi process while maintenance is running. Back up irreplaceable conversations before approving retention.
+Updated, registered Pi windows may stay open during maintenance. Sampled OS process discovery and extension-owned locks are not native session locks honored by every program: do not launch another Pi process while maintenance runs. Back up irreplaceable conversations before approving retention.
 
 ## Development checks
 

package/package.json

@@ -1,38 +1,39 @@
 {
-  "name": "@saifymatteo/pi-session-retention",
-  "version": "0.1.4",
-  "license": "AGPL-3.0-only",
-  "type": "module",
-  "keywords": [
-    "pi-package",
-    "pi-extension"
-  ],
-  "files": [
-    "src",
-    "README.md",
-    "NOTICE.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-session-retention/screenshot.png",
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
-  },
-  "engines": {
-    "node": ">=24"
-  },
-  "description": "Inspect and manage stored sessions; review deletion behavior before use.",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/saifymatteo/pi-extensions.git",
-    "directory": "packages/pi-session-retention"
-  }
+	"name": "@saifymatteo/pi-session-retention",
+	"version": "0.1.6",
+	"license": "AGPL-3.0-only",
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"pi-extension"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"NOTICE.md",
+		"LICENSE"
+	],
+	"pi": {
+		"image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-session-retention/screenshot.png",
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"engines": {
+		"node": ">=24"
+	},
+	"description": "Inspect and manage stored sessions; review deletion behavior before use.",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/saifymatteo/pi-extensions.git",
+		"directory": "packages/pi-session-retention"
+	}
 }

package/src/README.md

@@ -7,7 +7,7 @@ Moves inactive session families out of Pi's searchable session store. No search
 - `/session-cleanup preview` — show counts, scope and example candidate families without moving or deleting sessions.
 - `/session-cleanup` — review the first cleanup and approve daily automatic maintenance. Later calls run maintenance immediately.
 - `/session-cleanup pause` — pause automatic maintenance; run `/session-cleanup` to review and enable it again.
-- `/session-trash [query]` — open a dialog styled like `session-finder.ts`, with a heavy border, padded rows, a `Search:` line and yellow selection, listing trashed families immediately. Type to filter by names, first user prompts, IDs or original paths; use ↑↓ and Enter to select, then confirm a whole-family restore. Esc cancels. An optional query prefills the filter; clearing it shows all families again.
+- `/session-trash [query]` — search trashed families by name, first user prompt, ID or original path. ↑↓ selects; Enter previews; Ctrl+R requests a confirmed whole-family restore from either view. In preview, `[ ]` switches members and ↑↓ / PgUp/PgDn scrolls. Esc returns to search or closes it. An optional query prefills the filter.
 
 `/session-cleanup` advertises `[preview|pause]` and offers both arguments through command completion.
 
@@ -27,13 +27,13 @@ Startup reads bounded session headers and file metadata, not every transcript. A
 
 ## Safety and recovery
 
-- Maintenance is serialized by an exclusive per-store lock. Process discovery must succeed, and maintenance defers when its inventory finds another recognized Pi CLI process, including idle windows. Successful inventories are reused for at most one second within a maintenance transaction to avoid starting PowerShell for every file. Session switches and forks in the current window are blocked until maintenance ends. It does not assume that excluding this window protects other windows. Close other Pi windows and run `/session-cleanup` to retry. Unrecognized custom SDK hosts and programs with renamed executables are outside this process detector's guarantee; do not run maintenance alongside them.
+- Maintenance protects every verified open session's whole family, including idle windows, while cleaning unrelated inactive families. All open instances must load the updated extension and share an agent home; reload/update or close any instance reported as unregistered. Shared registration and per-store locks serialize maintenance and block session switches/forks until it ends. Unrecognized SDK hosts and renamed executables remain outside process detection; do not run maintenance alongside them.
 - On `/reload`, session replacement or graceful shutdown, maintenance cancels pending approval/Trash dialogs, stops at the next safety boundary and waits for in-flight file work to finish before releasing its lock. The lock is never removed while its operation can still mutate files. Forced termination or a crash can still leave a stale lock; these are not automatically removed.
 - Each family has a recovery manifest written before any file moves. Incomplete operations remain recoverable in `/session-trash` and are never automatically purged. Keep the manifest with its files. If the process crashes leaving `.maintenance.lock`, close all Pi processes before removing that stale lock and retrying. A corrupt lock fails closed rather than being guessed away.
 - Symlink paths, invalid headers, unresolved parents, family cycles, changed files and corrupt/path-escaping manifests are rejected or protected. An unreadable session can defer cleanup because the complete family graph cannot be established safely. Restore collisions do not overwrite either copy.
 - Moving session files does not retroactively ingest them into external memory integrations. Such integrations retain their live in-memory state and flush outstanding writes at shutdown; they do not depend on reopening historical JSONL files for those writes. Earlier failed ingestion is not repaired by this extension.
 
-Keep other Pi windows closed during maintenance. Sampled OS process discovery and an extension-owned lock are conservative safeguards, not a native session lock honored by every external program. A new external process can race a cleanup; do not launch another Pi process while maintenance is running. Back up irreplaceable conversations before approving retention.
+Updated, registered Pi windows may stay open during maintenance. Sampled OS process discovery and extension-owned locks are not native session locks honored by every program: do not launch another Pi process while maintenance runs. Back up irreplaceable conversations before approving retention.
 
 ## Development checks
 

package/src/core.ts

@@ -23,7 +23,7 @@ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 
 // Check every component, not just the leaf. Missing suffixes are allowed only
 // for creation; existing symlinks and non-directory ancestors are always errors.
-async function safePath(path: string, missing = false) {
+export async function safePath(path: string, missing = false) {
   const absolute = resolve(path)
   const root = parse(absolute).root
   let cursor = root
@@ -37,7 +37,7 @@ async function safePath(path: string, missing = false) {
   }
 }
 async function exists(path: string) { try { await lstat(path); return true } catch (error) { if (absent(error)) return false; throw error } }
-async function regular(path: string) {
+export async function regular(path: string) {
   await safePath(path)
   const s = await lstat(path)
   if (!s.isFile()) throw new Error(`Not a regular file: ${path}`)
@@ -144,7 +144,7 @@ export class RetentionStore {
     if (!inside(this.root, absolute)) throw new Error('Original path escapes root')
     return absolute
   }
-  private async load(id: string): Promise<TrashBatch> {
+  async getTrashBatch(id: string): Promise<TrashBatch> {
     await this.roots()
     const dir = this.batchPath(id)
     const path = join(dir, 'manifest.json')
@@ -181,10 +181,10 @@ export class RetentionStore {
     if (!await exists(this.trashRoot)) return { batches, issues }
     for (const item of await readdir(this.trashRoot, { withFileTypes: true })) {
       // Shared store metadata belongs to the adapter, not to a session family.
-      if (['settings.json', '.maintenance.lock'].includes(item.name) || /^settings-[0-9a-f-]+\.tmp$/.test(item.name)) continue
+      if (['settings.json', '.maintenance.lock', '.search-cache'].includes(item.name) || /^(?:settings-|\.lock-)[0-9a-f-]+\.tmp$/.test(item.name)) continue
       try {
         if (!item.isDirectory() || item.isSymbolicLink()) throw new Error('Not a batch directory')
-        batches.push(await this.load(item.name))
+        batches.push(await this.getTrashBatch(item.name))
       } catch (error) { issues.push(`${item.name}: ${message(error)}`) }
     }
     return { batches, issues }
@@ -266,7 +266,7 @@ export class RetentionStore {
   }
   async restoreFamily(id: string, options: MutationOptions): Promise<{ restored: string[] }> {
     const now = time(options?.now)
-    const { manifest } = await this.load(id)
+    const { manifest } = await this.getTrashBatch(id)
     const paths = manifest.files.flatMap(file => [this.original(file.original), join(this.batchPath(id), file.stored)])
     await this.allow(options, 'restore', paths)
     // Preflight the whole batch before moving anything, including incomplete ones.
@@ -312,7 +312,7 @@ export class RetentionStore {
       if (!batch.manifest.ready || batch.missing.length || now - batch.manifest.trashedAt <= RETENTION_MS) continue
       const id = batch.manifest.id
       try {
-        const { manifest, missing } = await this.load(id)
+        const { manifest, missing } = await this.getTrashBatch(id)
         if (!manifest.ready || missing.length || now - manifest.trashedAt <= RETENTION_MS) continue
         const paths = manifest.files.flatMap(file => [this.original(file.original), join(this.batchPath(id), file.stored)])
         await this.allow(options, 'purge', paths)

package/src/dialog.ts

@@ -1,14 +1,30 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Input, Key, matchesKey, SelectList, truncateToWidth, visibleWidth, type Component, type Focusable, type KeybindingsManager, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { posix, win32 } from "node:path";
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Input, Key, Markdown, matchesKey, ScrollView, sliceByColumn, Spacer, stripTerminalSequences, Text, truncateToWidth, visibleWidth, type Component, type Focusable, type KeybindingsManager, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import type { TrashPreview } from "./preview.ts";
 import { dialogRows, wheelAsArrows } from "./lib/dialog.ts";
 
-export type TrashChoice = { value: string; label: string; description: string; search: string };
+export type TrashChoice = { value: string; label: string; description: string; search: string; members?: number; group?: string; cwd?: string };
+export type TrashPreviewLoader = (id: string, memberIndex: number, signal: AbortSignal) => Promise<TrashPreview>;
+export type TrashIndexProgress = { completed: number; total: number; failed: number };
+type TrashRow = { kind: "folder"; label: string } | { kind: "family"; choice: TrashChoice };
 
 export class SessionTrashDialog implements Component, Focusable {
 	private input = new Input({ prompt: "" });
-	private list!: SelectList;
+	private rows: TrashRow[] = [];
+	private selectedValue?: string;
+	private selectedRow = 0;
+	private offset = 0;
 	private filtered: TrashChoice[] = [];
 	private viewport = 5;
+	private progress?: TrashIndexProgress;
+	private closed = false;
+	private hasFocus = false;
+	private preview?: { id: string; member: number; count: number; controller: AbortController };
+	private previewContent = new Container();
+	private previewValue: TrashPreview | string = "";
+	private previewScroll = new ScrollView(this.previewContent, { scrollbar: "hidden", overscroll: "contain" });
+	private previewTasks = new Set<Promise<void>>();
 
 	constructor(
 		private tui: TUI,
@@ -17,102 +33,324 @@ export class SessionTrashDialog implements Component, Focusable {
 		private choices: TrashChoice[],
 		query: string,
 		private done: (id: string | undefined) => void,
+		private loadPreview?: TrashPreviewLoader,
 	) {
 		this.input.handleInput(query); // Native text insertion leaves the cursor after the prefilled query.
 		this.filter();
 	}
 
-	get focused(): boolean { return this.input.focused; }
-	set focused(value: boolean) { this.input.focused = value; }
+	get focused(): boolean { return this.hasFocus; }
+	set focused(value: boolean) { this.hasFocus = value; this.input.focused = value && !this.preview; }
 
-	private filter(): void {
+	update(choices: TrashChoice[], progress?: TrashIndexProgress): void {
+		if (this.closed) return;
+		const selected = this.getSelectedItem()?.value;
+		this.choices = choices;
+		this.progress = progress;
+		this.filter(selected);
+		this.refresh();
+	}
+
+	private indexStatus(): string {
+		if (!this.progress) return "";
+		const { completed, total, failed } = this.progress;
+		if (completed < total) return `indexing ${completed}/${total}${failed ? ` · ${failed} unavailable` : ""}`;
+		return failed ? `search incomplete · ${failed} unavailable` : "";
+	}
+
+	private filter(selected?: string): void {
 		const query = this.input.getValue().toLowerCase();
 		this.filtered = this.choices.filter((choice) => choice.search.toLowerCase().includes(query));
-		this.buildList();
+		this.buildList(selected);
 	}
 
 	private buildList(selected?: string): void {
-		this.list = new SelectList(this.filtered, this.viewport, {
-			selectedPrefix: (text) => text,
-			selectedText: (text) => text.replace(/^→ /, "▶ "),
-			description: (text) => text,
-			scrollInfo: (text) => this.theme.fg("dim", text),
-			noMatch: () => this.theme.fg("muted", this.choices.length ? "No matching families" : "Trash empty"),
+		// Families grouped by their originating project directory, newest trash first
+		// (the caller pre-sorts). Folder labels prefer a cached real cwd over the
+		// encoded session-directory segment.
+		if (selected !== undefined) this.selectedValue = selected;
+		if (this.selectedValue && !this.filtered.some(choice => choice.value === this.selectedValue)) this.selectedValue = undefined;
+		this.selectedValue ??= this.filtered[0]?.value;
+		const labels = new Map<string, string>();
+		for (const choice of this.filtered) {
+			const key = choice.group || "";
+			if (!labels.has(key)) labels.set(key, choice.cwd || "");
+			else if (choice.cwd && !labels.get(key)) labels.set(key, choice.cwd);
+		}
+		const rows: TrashRow[] = [];
+		const seen = new Set<string>();
+		for (const choice of this.filtered) {
+			const key = choice.group || "";
+			if (!seen.has(key)) { seen.add(key); rows.push({ kind: "folder", label: labels.get(key) || key || "(no project)" }); }
+			rows.push({ kind: "family", choice });
+		}
+		this.rows = rows;
+		this.selectedRow = Math.max(0, rows.findIndex(row => row.kind === "family" && row.choice.value === this.selectedValue));
+		this.clampOffset();
+	}
+
+	getSelectedItem(): TrashChoice | undefined { return this.filtered.find(choice => choice.value === this.selectedValue); }
+
+	private activeFolderIndex(): number {
+		for (let i = Math.min(this.selectedRow, this.rows.length - 1); i >= 0; i--) {
+			if (this.rows[i]?.kind === "folder") return i;
+		}
+		return -1;
+	}
+
+	private clampOffset(): void {
+		this.offset = Math.max(0, Math.min(this.selectedRow - this.viewport + 1, Math.max(0, this.rows.length - this.viewport)));
+	}
+
+	private refresh(): void { this.input.invalidate(); this.tui.requestRender(); }
+
+	private setPreviewContent(value: TrashPreview | string = this.previewValue): void {
+		this.previewValue = value;
+		this.previewContent.clear();
+		if (typeof value === "string") {
+			this.previewContent.addChild(new Text(value, 0, 0));
+			return;
+		}
+		const markdownTheme = getMarkdownTheme();
+		const userOptions = { preserveOrderedListMarkers: true, preserveBackslashEscapes: true };
+		const section = (label: string) => this.previewContent.addChild({
+			render: (width: number) => {
+				const heading = truncateToWidth(`── ${label} `, width, "");
+				return [this.theme.fg("muted", markdownTheme.bold(heading) + "─".repeat(Math.max(0, width - visibleWidth(heading))))];
+			},
+			invalidate() {},
 		});
-		if (selected !== undefined) this.list.setSelectedIndex(Math.max(0, this.filtered.findIndex((choice) => choice.value === selected)));
+		const message = (role: "user" | "assistant", text: string) => {
+			const isUser = role === "user";
+			this.previewContent.addChild(new Text(this.theme.fg(isUser ? "mdLink" : "warning", markdownTheme.bold(isUser ? "You" : "Assistant")), 0, 0));
+			// Each excerpt retains its native Markdown cache and isolated code fences.
+			const body = new Markdown(text, 0, 0, markdownTheme, undefined, isUser ? userOptions : undefined);
+			const rail = {
+				children: [body],
+				render: (width: number) => {
+					const inset = width >= 4 ? 3 : 0;
+					const prefix = inset ? this.theme.fg("dim", "│") + "  " : "";
+					return body.render(Math.max(1, width - inset)).map(line => truncateToWidth(prefix + line, width, ""));
+				},
+				invalidate: () => body.invalidate(),
+			};
+			this.previewContent.addChild(rail);
+			this.previewContent.addChild(new Spacer(1));
+		};
+		section("FIRST REQUEST");
+		message("user", value.firstRequest || "No user text recorded");
+		section("RECENT MESSAGES");
+		for (const entry of value.recent) message(entry.role, entry.text);
+	}
+
+	private finish(id?: string): void {
+		this.dispose();
+		this.done(id);
+	}
+
+	private openPreview(id: string, member = 0): void {
+		const choice = this.choices.find(choice => choice.value === id);
+		if (!choice || this.closed) return;
+		this.preview?.controller.abort();
+		const count = choice.members ?? 1;
+		const state = { id, member: (member + count) % count, count, controller: new AbortController() };
+		this.preview = state;
+		this.input.focused = false;
+		this.setPreviewContent("Loading preview…");
+		this.previewScroll.scrollToStart();
+		this.refresh();
+		const current = () => !this.closed && this.preview === state && !state.controller.signal.aborted;
+		const task = Promise.resolve().then(async () => {
+			state.controller.signal.throwIfAborted();
+			if (!this.loadPreview) throw new Error("Preview unavailable");
+			return this.loadPreview(id, state.member, state.controller.signal);
+		}).then(value => {
+			if (!current()) return;
+			this.setPreviewContent(value);
+			this.refresh();
+		}, error => {
+			if (!current()) return;
+			const reason = stripTerminalSequences(String(error instanceof Error ? error.message : error)).replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 1000);
+			this.setPreviewContent(`Preview unavailable: ${reason}\n\nEsc returns to search. Ctrl+R can still request a freshly validated restore.`);
+			this.refresh();
+		}).catch(() => { /* The host may dispose its renderer during completion. */ });
+		this.previewTasks.add(task);
+		void task.then(() => this.previewTasks.delete(task));
 	}
 
 	handleMouse(event: TuiMouseEvent) { return wheelAsArrows(event, (key) => this.handleInput(key)); }
 
 	handleInput(data: string): void {
+		if (this.closed) return;
 		const kb = this.keybindings;
-		if (kb.matches(data, "tui.select.cancel") || matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
-			this.done(undefined);
+		if (matchesKey(data, Key.ctrl("c"))) { this.finish(); return; }
+		if (kb.matches(data, "tui.select.cancel") || matchesKey(data, Key.escape)) {
+			if (this.preview) {
+				this.preview.controller.abort();
+				this.preview = undefined;
+				this.input.focused = this.hasFocus;
+				this.refresh();
+			} else this.finish();
+			return;
+		}
+		if (matchesKey(data, Key.ctrl("r"))) {
+			const id = this.preview?.id ?? this.getSelectedItem()?.value;
+			if (id) this.finish(id);
+			return;
+		}
+		if (this.preview) {
+			if ((data === "[" || data === "]") && this.preview.count > 1) this.openPreview(this.preview.id, this.preview.member + (data === "[" ? -1 : 1));
+			else {
+				if (kb.matches(data, "tui.select.up")) this.previewScroll.scrollBy(-1);
+				if (kb.matches(data, "tui.select.down")) this.previewScroll.scrollBy(1);
+				if (kb.matches(data, "tui.select.pageUp")) this.previewScroll.scrollBy(-Math.max(1, this.previewScroll.viewportHeight));
+				if (kb.matches(data, "tui.select.pageDown")) this.previewScroll.scrollBy(Math.max(1, this.previewScroll.viewportHeight));
+				if (matchesKey(data, Key.home)) this.previewScroll.scrollToStart();
+				if (matchesKey(data, Key.end)) this.previewScroll.scrollToEnd();
+				this.refresh();
+			}
 			return;
 		}
 		if (kb.matches(data, "tui.select.confirm")) {
-			const selected = this.list.getSelectedItem();
-			if (selected) this.done(selected.value);
+			const selected = this.getSelectedItem();
+			if (selected) this.openPreview(selected.value);
 			return;
 		}
 		const up = kb.matches(data, "tui.select.up");
 		const down = kb.matches(data, "tui.select.down");
 		const pageUp = kb.matches(data, "tui.select.pageUp");
 		const pageDown = kb.matches(data, "tui.select.pageDown");
-		if (up || down || pageUp || pageDown) {
-			const index = this.filtered.findIndex((choice) => choice.value === this.list.getSelectedItem()?.value);
+		const home = matchesKey(data, Key.home);
+		const end = matchesKey(data, Key.end);
+		if (up || down || pageUp || pageDown || home || end) {
+			const index = this.filtered.findIndex((choice) => choice.value === this.selectedValue);
 			const count = this.filtered.length;
 			if (count) {
-				const next = pageUp || pageDown
-					? Math.max(0, Math.min(count - 1, index + (pageUp ? -this.viewport : this.viewport)))
-					: (index + (up ? -1 : 1) + count) % count;
-				this.list.setSelectedIndex(next);
+				const next = home ? 0 : end ? count - 1
+					: pageUp || pageDown
+						? Math.max(0, Math.min(count - 1, index + (pageUp ? -this.viewport : this.viewport)))
+						: (index + (up ? -1 : 1) + count) % count;
+				this.selectedValue = this.filtered[next]?.value;
+				this.buildList(this.selectedValue);
 			}
 		} else {
 			const previous = this.input.getValue();
 			this.input.handleInput(data);
 			if (previous !== this.input.getValue()) this.filter();
 		}
-		this.invalidate();
-		this.tui.requestRender();
+		this.refresh();
+	}
+
+	private renderPreview(width: number, height: number): string[] {
+		const state = this.preview!;
+		const rows = Math.max(1, Math.min(height, dialogRows(this.tui, 0)));
+		// Eight fixed chrome rows still need room for a readable first message.
+		const compact = width < 16 || rows < 12;
+		const bodyWidth = Math.max(1, compact ? width : width - 6);
+		const value = typeof this.previewValue === "string" ? undefined : this.previewValue;
+		const member = `Session ${state.member + 1}/${state.count}${state.count > 1 ? " · [ ] switch" : ""} · read-only`;
+		const notice = value ? `Preview only · ${value.truncated ? "Some content shortened" : "Current branch · Tools/thinking omitted"}` : "Read-only preview";
+		const footer = `↑↓ PgUp/PgDn Home/End scroll · Ctrl+R restore all ${state.count} · Esc back`;
+		const head = rows >= 3 ? [this.theme.fg("muted", member)] : [];
+		const tail = [...(rows >= 4 ? [this.theme.fg("muted", notice)] : []), ...(rows >= 2 ? [this.theme.fg("dim", footer)] : [])];
+		const capacity = Math.max(1, rows - (compact ? head.length + tail.length : 8));
+		const content = this.previewScroll.render(bodyWidth);
+		this.previewScroll.updateLayout(content.length, capacity, () => this.tui.requestRender());
+		const visible = content.slice(this.previewScroll.scrollTop, this.previewScroll.scrollTop + capacity);
+		if (compact) return [...head, ...visible, ...tail].map(line => truncateToWidth(line, width, ""));
+		while (visible.length < capacity) visible.push("");
+		const border = (text: string) => this.theme.fg("border", text);
+		const row = (text: string, color: "text" | "muted" | "dim" = "text") => {
+			const fitted = truncateToWidth(text, bodyWidth, "…");
+			return border("┃  ") + this.theme.fg(color, fitted + " ".repeat(Math.max(0, bodyWidth - visibleWidth(fitted)))) + border("  ┃");
+		};
+		const cwd = (value?.cwd || "").replace(/[\r\n\t]/g, " ");
+		const project = (/^[a-z]:[\\/]|^\\\\/i.test(cwd) ? win32 : posix).basename(cwd) || cwd || (value ? "Project not recorded" : "");
+		const projectWidth = bodyWidth - visibleWidth(` · ${member}`);
+		const metadata = project && projectWidth >= 6 ? `${truncateToWidth(project, projectWidth, "…")} · ${member}` : member;
+		const pathWidth = visibleWidth(cwd);
+		const path = pathWidth > bodyWidth ? `…${sliceByColumn(cwd, pathWidth - bodyWidth + 1, bodyWidth - 1, true)}` : cwd;
+		const label = (value?.name || this.choices.find(choice => choice.value === state.id)?.label || state.id).replace(/[\r\n\t]/g, " ");
+		const title = truncateToWidth(` Session Trash › ${label} `, width - 3, "…");
+		return [border(`┏${title}${"━".repeat(Math.max(0, width - 2 - visibleWidth(title)))}┓`), row(metadata, "muted"), row(path, "muted"), row(""), ...visible.map(line => row(line)), border(`┣${"━".repeat(width - 2)}┫`), row(notice, "muted"), row(footer, "dim"), border(`┗${"━".repeat(width - 2)}┛`)];
 	}
 
 	render(width: number): string[] {
 		const height = Math.max(1, this.tui.terminal.rows);
-		// Fixed lines: 2 borders, search, footer, list scroll info.
-		const viewport = dialogRows(this.tui, 5);
+		if (this.preview) return this.renderPreview(width, height);
+		// Fixed lines: 2 borders, search, active-folder header, footer, list scroll info.
+		const viewport = dialogRows(this.tui, 6);
 		if (viewport !== this.viewport) {
 			this.viewport = viewport;
-			this.buildList(this.list.getSelectedItem()?.value);
+			this.buildList(this.selectedValue);
 		}
 		// Below the frame's minimum size, keep the native input/cursor usable.
 		if (width < 16 || height < 8) return [
 			...this.input.render(Math.max(1, width)),
-			...this.list.render(Math.max(4, width)).map((line) => this.theme.fg(line.startsWith("▶ ") ? "warning" : "text", line)),
+			...(this.indexStatus() ? [this.indexStatus()] : []),
+			...this.windowLines(this.viewport).map((line) => this.theme.fg(line.startsWith("▶ ") ? "warning" : "text", line)),
 		].slice(0, height).map((line) => truncateToWidth(line, Math.max(0, width), ""));
 
 		// Match session-finder.ts: heavy border, two-cell padding and warning selection.
 		const border = (value: string) => this.theme.fg("border", value);
 		const inner = width - 2;
 		const bodyWidth = inner - 4;
-		const title = truncateToWidth(` Session Trash · ${this.filtered.length} results `, inner - 1, "…");
-		const row = (value: string, color: "text" | "warning" | "dim" = "text") => {
+		const progress = this.indexStatus();
+		const title = truncateToWidth(` Session Trash${progress ? ` · ${progress}` : ""} · ${this.filtered.length} results `, inner - 1, "…");
+		const row = (value: string, color: "text" | "warning" | "dim" | "muted" = "text") => {
 			const fitted = truncateToWidth(value, bodyWidth, "…");
 			const padded = `  ${fitted}${" ".repeat(Math.max(0, bodyWidth - visibleWidth(fitted)))}  `;
 			return border("┃") + this.theme.fg(color, padded) + border("┃");
 		};
 		const lines = [border(`┏${title}${"━".repeat(Math.max(0, inner - visibleWidth(title)))}┓`)];
 		for (const line of this.input.render(bodyWidth - 8)) lines.push(row(`Search: ${line}`, "warning"));
-		const items = this.list.render(bodyWidth);
-		while (items.length < viewport + 1) items.push("");
-		for (const item of items) lines.push(row(item, item.startsWith("▶ ") ? "warning" : "text"));
-		lines.push(row("↑↓ / PgUp/PgDn navigate · type to search · Enter restore · Esc close", "dim"));
+		// Match session-finder.ts: the selected family's folder stays fixed above the
+		// scrolling list, and inline folder headers skip the fixed copy. With no rows,
+		// render the empty-state text instead of folder chrome.
+		const folderIndex = this.activeFolderIndex();
+		if (!this.rows.length) {
+			const empty = this.indexStatus() ? `No matches yet — ${this.indexStatus()}` : this.choices.length ? "No matching families" : "Trash empty";
+			lines.push(row(this.theme.fg("muted", empty), "muted"));
+			for (let i = 1; i < this.viewport + 1; i++) lines.push(row(""));
+		} else {
+			const folder = folderIndex >= 0 && this.rows[folderIndex]?.kind === "folder" ? this.rows[folderIndex].label : "(no project)";
+			lines.push(row(this.theme.fg("dim", `▸ ${folder}`), "dim"));
+			for (const line of this.windowLines(this.viewport, folderIndex)) lines.push(row(line, line.startsWith("▶ ") ? "warning" : line.startsWith("▸ ") ? "dim" : "text"));
+		}
+		const info = this.rows.length > this.viewport ? `  (${Math.max(0, this.filtered.findIndex(choice => choice.value === this.selectedValue) + 1) || 1}/${this.filtered.length})` : "";
+		lines.push(row(this.theme.fg("dim", info), "dim"));
+		lines.push(row("↑↓ navigate · Home/End jump · type to search · Enter preview · Ctrl+R restore · Esc close", "dim"));
 		lines.push(border(`┗${"━".repeat(inner)}┛`));
 		return lines;
 	}
 
+	/** Windowed list rows: folder headers plus the selected family marker. */
+	private windowLines(count: number, skipFolderIndex = -1): string[] {
+		// Like session-finder: slice rows, drop the fixed folder copy, cap at `count`.
+		const window: string[] = [];
+		for (let i = this.offset; i < this.rows.length && window.length < count; i++) {
+			if (i === skipFolderIndex) continue;
+			const entry = this.rows[i];
+			window.push(entry.kind === "folder" ? `▸ ${entry.label}` : `${entry.choice.value === this.selectedValue ? "▶ " : "  "}${entry.choice.label}${entry.choice.description ? ` · ${entry.choice.description}` : ""}`);
+		}
+		while (window.length < count) window.push("");
+		return window;
+	}
+
+	dispose(): void {
+		this.closed = true;
+		this.preview?.controller.abort();
+		this.input.focused = false;
+	}
+
+	async drain(): Promise<void> {
+		this.dispose();
+		await Promise.all([...this.previewTasks]);
+	}
+
 	invalidate(): void {
 		this.input.invalidate();
-		this.list.invalidate();
+		this.setPreviewContent();
+		this.previewScroll.invalidate();
 	}
 }