@saifymatteo/pi-extensions 0.0.0-stage → 0.1.0

package/packages/pi-session-retention/README.md

@@ -0,0 +1,62 @@
+# pi-session-retention
+
+From the monorepo root:
+
+```sh
+pi -e ./packages/pi-session-retention
+```
+
+**Warning:** this uses existing personal Pi resources and settings unless isolated as described in the root README. Existing retention approval/state is reused: startup may automatically move sessions and permanently purge expired Trash without a new approval. Back up conversations before loading. Do not load two copies of this extension at once.
+
+Node.js >=24 for development; Pi loads the TypeScript extension. Host coding-agent/TUI packages are peers. Store locations and destructive behavior are unchanged. `PI_CODING_AGENT_DIR` selects the agent home (default `~/.pi/agent`); `PI_CODING_AGENT_SESSION_DIR` and explicit session-directory overrides narrow the scope. See the operational notes below and [NOTICE.md](NOTICE.md) for provenance.
+
+## Packaged tests and limitations
+
+Run `node --test packages/pi-session-retention/test/*.test.mjs` from the repository root after its dev dependencies are available. Tests use temporary fixtures or pure helpers, never the real session store. Interactive terminal behavior and OS process discovery still need manual exercise in an isolated agent home. Requires working `ps` on Unix or PowerShell/CIM on Windows and a filesystem supporting exclusive hard-link publication. No network/model requests are made by retention. Trash searches read stored conversation text; local Trash is not encryption or secure erasure.
+
+The original operational README is included under `src/README.md`. Its `bun`-based check commands and deployment statement describe the private workspace this extension was developed in, not this repository; use the repository-root checks above for verification.
+
+## Original operational documentation
+
+# Session retention
+
+Moves inactive session families out of Pi's searchable session store. No search index, scheduler, model calls, or added dependencies.
+
+## Use
+
+- `/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-cleanup` advertises `[preview|pause]` and offers both arguments through command completion.
+
+The footer shows maintenance phases: scanning, approval, process checks, moving sessions and purging expired Trash. Trash loading and restoration also show status. The status clears on completion, cancellation or failure; it does not leave an idle indicator.
+
+Interactive startup checks at most once per 24 hours, including after session switches/reloads. Print, JSON and RPC modes never run maintenance. There is no OS scheduler: expired Trash remains until the next successful cleanup.
+
+## Rules
+
+A family consists of a session and every descendant linked by `parentSession`, including descendants in another project. Its activity clock is the newest filesystem modification time or header timestamp among its members. Only families strictly more than 30 days inactive qualify. Named sessions use the same rule. The current session protects its entire family.
+
+Trashed families receive another 30 days before permanent deletion. Restoring a family preserves its JSONL contents and original paths, updates file modification times to give the whole family a fresh 30-day grace period, and never overwrites existing files.
+
+Default scope is every project under the agent's normal `sessions` store. A custom session directory reported by the session manager is treated as its own store; the extension does not sweep unrelated custom locations. Trash is a sibling `.trash/<store-name>-<path-hash>` directory **outside** the live store, not `sessions/.trash`. Approval, pause state, daily timestamp and maintenance lock live there too, not in this repository.
+
+Startup reads bounded session headers and file metadata, not every transcript. A cleanup batch revalidates the family graph once, rather than rescanning the entire store for each family. Only explicit Trash searches read conversation text from trashed files. Normal session discovery no longer needs to read those files. This does not erase copies exported elsewhere or memories already retained by external integrations.
+
+## 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.
+- 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.
+
+## Development checks
+
+This copy lives in the [pi-extensions](https://github.com/saifymatteo/pi-extensions) repository. Run its checks from the repository root: `node --test packages/pi-session-retention/test/*.test.mjs` (temporary fixtures and pure helpers; the real session store is never touched) and `npm run smoke` for an isolated host load. Interactive terminal behavior and OS process discovery still need manual exercise in an isolated agent home.
+
+Requires working `ps` on Unix or PowerShell/CIM on Windows and a filesystem supporting exclusive hard-link publication. No network or model requests are made by retention. Trash searches read stored conversation text; local Trash is not encryption or secure erasure.

package/packages/pi-session-retention/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@saifymatteo/pi-session-retention",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "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/packages/pi-session-retention/src/README.md

@@ -0,0 +1,42 @@
+# Session retention
+
+Moves inactive session families out of Pi's searchable session store. No search index, scheduler, model calls, or added dependencies.
+
+## Use
+
+- `/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-cleanup` advertises `[preview|pause]` and offers both arguments through command completion.
+
+The footer shows maintenance phases: scanning, approval, process checks, moving sessions and purging expired Trash. Trash loading and restoration also show status. The status clears on completion, cancellation or failure; it does not leave an idle indicator.
+
+Interactive startup checks at most once per 24 hours, including after session switches/reloads. Print, JSON and RPC modes never run maintenance. There is no OS scheduler: expired Trash remains until the next successful cleanup.
+
+## Rules
+
+A family consists of a session and every descendant linked by `parentSession`, including descendants in another project. Its activity clock is the newest filesystem modification time or header timestamp among its members. Only families strictly more than 30 days inactive qualify. Named sessions use the same rule. The current session protects its entire family.
+
+Trashed families receive another 30 days before permanent deletion. Restoring a family preserves its JSONL contents and original paths, updates file modification times to give the whole family a fresh 30-day grace period, and never overwrites existing files.
+
+Default scope is every project under the agent's normal `sessions` store. A custom session directory reported by the session manager is treated as its own store; the extension does not sweep unrelated custom locations. Trash is a sibling `.trash/<store-name>-<path-hash>` directory **outside** the live store, not `sessions/.trash`. Approval, pause state, daily timestamp and maintenance lock live there too, not in this repository.
+
+Startup reads bounded session headers and file metadata, not every transcript. A cleanup batch revalidates the family graph once, rather than rescanning the entire store for each family. Only explicit Trash searches read conversation text from trashed files. Normal session discovery no longer needs to read those files. This does not erase copies exported elsewhere or memories already retained by external integrations.
+
+## 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.
+- 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.
+
+## Development checks
+
+This copy lives in the [pi-extensions](https://github.com/saifymatteo/pi-extensions) repository. Run its checks from the repository root: `node --test packages/pi-session-retention/test/*.test.mjs` (temporary fixtures and pure helpers; the real session store is never touched) and `npm run smoke` for an isolated host load. Interactive terminal behavior and OS process discovery still need manual exercise in an isolated agent home.
+
+Requires working `ps` on Unix or PowerShell/CIM on Windows and a filesystem supporting exclusive hard-link publication. No network or model requests are made by retention. Trash searches read stored conversation text; local Trash is not encryption or secure erasure.

package/packages/pi-session-retention/src/core.ts

@@ -0,0 +1,333 @@
+import { constants } from 'node:fs'
+import { copyFile, link, lstat, mkdir, open, readdir, rename, rmdir, unlink, utimes } from 'node:fs/promises'
+import { isAbsolute, join, parse, relative, resolve, sep } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+export const RETENTION_MS = 30 * 24 * 60 * 60 * 1000
+const HEADER_BYTES = 64 * 1024
+const MANIFEST_BYTES = 1024 * 1024
+export type Family = { id: string; paths: string[]; latestActivity: number; protected: boolean; reasons: string[] }
+export type ScanResult = { families: Family[]; candidates: Family[]; issues: string[]; aborted: boolean }
+// Adapter must hold its cross-process lock for the entire awaited operation, and
+// discover active sessions itself. A guard is required, and only true permits work.
+export type Guard = (operation: 'trash' | 'restore' | 'purge', paths: readonly string[]) => Promise<boolean>
+export type MutationOptions = { now?: number; guard: Guard }
+export type Manifest = { version: 1; id: string; trashedAt: number; ready: boolean; files: { original: string; stored: string }[] }
+export type TrashBatch = { manifest: Manifest; missing: string[] }
+export const pathKey = (path: string) => process.platform === 'win32' ? resolve(path).toLowerCase() : resolve(path)
+const inside = (root: string, path: string) => { const r = relative(root, path); return r !== '' && !isAbsolute(r) && r !== '..' && !r.startsWith(`..${sep}`) }
+const time = (now = Date.now()) => { if (!Number.isFinite(now) || now < 0) throw new Error('Invalid clock'); return now }
+const message = (error: unknown) => error instanceof Error ? error.message : String(error)
+const absent = (error: unknown) => (error as NodeJS.ErrnoException).code === 'ENOENT'
+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) {
+  const absolute = resolve(path)
+  const root = parse(absolute).root
+  let cursor = root
+  const parts = absolute.slice(root.length).split(sep).filter(Boolean)
+  for (let i = 0; i < parts.length; i++) {
+    cursor = join(cursor, parts[i])
+    try {
+      const s = await lstat(cursor)
+      if (s.isSymbolicLink() || (i < parts.length - 1 && !s.isDirectory())) throw new Error(`Unsafe path: ${cursor}`)
+    } catch (error) { if (missing && absent(error)) return; throw error }
+  }
+}
+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) {
+  await safePath(path)
+  const s = await lstat(path)
+  if (!s.isFile()) throw new Error(`Not a regular file: ${path}`)
+  return s
+}
+async function header(path: string) {
+  const before = await regular(path)
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+  try {
+    const s = await handle.stat()
+    if (!s.isFile() || before.ino !== s.ino || before.dev !== s.dev) throw new Error(`Changed file: ${path}`)
+    const buffer = Buffer.alloc(HEADER_BYTES)
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0)
+    const end = buffer.subarray(0, bytesRead).indexOf(10)
+    if (end < 0 && (s.size >= HEADER_BYTES || bytesRead < s.size)) throw new Error('Session header exceeds limit')
+    const h = JSON.parse(buffer.subarray(0, end < 0 ? bytesRead : end).toString('utf8'))
+    const stamp = typeof h.timestamp === 'string' ? Date.parse(h.timestamp) : NaN
+    if (h.type !== 'session' || typeof h.id !== 'string' || !h.id.trim() || !Number.isFinite(stamp) ||
+      (h.parentSession != null && (typeof h.parentSession !== 'string' || !isAbsolute(h.parentSession)))) throw new Error(`Invalid session header: ${path}`)
+    return { parent: h.parentSession == null ? undefined : resolve(h.parentSession), activity: Math.max(s.mtimeMs, stamp) }
+  } finally { await handle.close() }
+}
+
+export class RetentionStore {
+  readonly root: string
+  readonly trashRoot: string
+  constructor(root: string, trashRoot: string) {
+    this.root = resolve(root)
+    this.trashRoot = resolve(trashRoot)
+    if (pathKey(this.root) === pathKey(this.trashRoot) || inside(this.root, this.trashRoot) || inside(this.trashRoot, this.root)) throw new Error('Session and trash roots must be disjoint')
+  }
+  private async roots() {
+    await safePath(this.root)
+    if (!(await lstat(this.root)).isDirectory()) throw new Error('Session root is not a directory')
+    await safePath(this.trashRoot, true)
+    if (await exists(this.trashRoot) && !(await lstat(this.trashRoot)).isDirectory()) throw new Error('Trash root is not a directory')
+  }
+  private async allow(options: MutationOptions, operation: Parameters<Guard>[0], paths: string[]) {
+    if (typeof options?.guard !== 'function' || await options.guard(operation, paths) !== true) throw new Error('Mutation guard refused')
+    await this.roots()
+  }
+
+  async scan(options: { now?: number; protectedPaths?: readonly string[] } = {}): Promise<ScanResult> {
+    const now = time(options.now)
+    await this.roots()
+    const nodes = new Map<string, Awaited<ReturnType<typeof header>>>()
+    const issues: string[] = []
+    const walk = async (dir: string) => {
+      try {
+        await safePath(dir)
+        for (const item of await readdir(dir, { withFileTypes: true })) {
+          const path = join(dir, item.name)
+          if (item.isSymbolicLink()) { issues.push(`Symlink skipped; completeness unknown: ${path}`); continue }
+          if (item.isDirectory()) await walk(path)
+          else if (item.name.endsWith('.jsonl')) {
+            try { nodes.set(path, await header(path)) } catch (error) { issues.push(`${path}: ${message(error)}`) }
+          }
+        }
+      } catch (error) { issues.push(`${dir}: ${message(error)}`) }
+    }
+    await walk(this.root)
+    const neighbors = new Map([...nodes.keys()].map(path => [path, new Set<string>()]))
+    const byKey = new Map([...nodes.keys()].map(path => [pathKey(path), path]))
+    const invalid = new Map<string, string>()
+    for (const [path, node] of nodes) {
+      if (!node.parent) continue
+      const parent = byKey.get(pathKey(node.parent))
+      if (!inside(this.root, node.parent) || !parent) invalid.set(path, 'Missing or outside-root parent')
+      else { neighbors.get(path)!.add(parent); neighbors.get(parent)!.add(path) }
+    }
+    const protectedPaths = new Set((options.protectedPaths ?? []).map(pathKey))
+    const seen = new Set<string>()
+    const families: Family[] = []
+    for (const start of nodes.keys()) {
+      if (seen.has(start)) continue
+      const paths: string[] = [], queue = [start]
+      while (queue.length) {
+        const path = queue.pop()!
+        if (seen.has(path)) continue
+        seen.add(path); paths.push(path)
+        queue.push(...neighbors.get(path)!)
+      }
+      paths.sort()
+      const reasons = new Set<string>()
+      for (const path of paths) {
+        if (invalid.has(path)) reasons.add(invalid.get(path)!)
+        if (protectedPaths.has(pathKey(path))) reasons.add('Active/protected session')
+      }
+      // A connected parent graph is a tree iff it has exactly one parentless root.
+      if (paths.filter(path => !nodes.get(path)!.parent).length !== 1) reasons.add('Cycle or incomplete tree')
+      families.push({ id: paths[0], paths, latestActivity: paths.reduce((latest, path) => Math.max(latest, nodes.get(path)!.activity), -Infinity), protected: reasons.size > 0, reasons: [...reasons] })
+    }
+    // An unreadable header could refer to ANY known family. Never guess completeness.
+    return { families, candidates: issues.length ? [] : families.filter(f => !f.protected && now - f.latestActivity > RETENTION_MS), issues, aborted: issues.length > 0 }
+  }
+
+  private batchPath(id: string) {
+    if (!uuid.test(id)) throw new Error('Invalid batch id')
+    return join(this.trashRoot, id)
+  }
+  private original(path: string) {
+    if (typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\\') || path.split('/').some(p => !p || p === '.' || p === '..' || p.includes(':')) || !path.endsWith('.jsonl')) throw new Error('Invalid original path')
+    const absolute = resolve(this.root, ...path.split('/'))
+    if (!inside(this.root, absolute)) throw new Error('Original path escapes root')
+    return absolute
+  }
+  private async load(id: string): Promise<TrashBatch> {
+    await this.roots()
+    const dir = this.batchPath(id)
+    const path = join(dir, 'manifest.json')
+    const stat = await regular(path)
+    if (stat.size > MANIFEST_BYTES) throw new Error('Manifest too large')
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+    let m: Manifest
+    try { m = JSON.parse(await handle.readFile('utf8')) } finally { await handle.close() }
+    if (!m || m.version !== 1 || m.id !== id || !Number.isFinite(m.trashedAt) || m.trashedAt < 0 || typeof m.ready !== 'boolean' || !Array.isArray(m.files) || !m.files.length) throw new Error('Invalid manifest')
+    const originals = new Set<string>(), stored = new Set<string>(), missing: string[] = []
+    for (const [i, file] of m.files.entries()) {
+      if (!file || file.stored !== `${i}.jsonl`) throw new Error('Invalid stored path')
+      const original = this.original(file.original)
+      if (originals.has(pathKey(original))) throw new Error('Duplicate original path')
+      originals.add(pathKey(original)); stored.add(file.stored)
+      await safePath(original, true)
+      const target = join(dir, file.stored)
+      if (!await exists(target)) missing.push(file.stored)
+      else await regular(target)
+    }
+    // Never recursively remove a directory described by an untrusted manifest.
+    for (const name of await readdir(dir)) {
+      if (name === 'manifest.json' || stored.has(name)) continue
+      if (/^manifest\.[0-9a-f-]+\.tmp$/.test(name) || [...stored].some(file => name === `${file}.staging`)) {
+        await regular(join(dir, name))
+        missing.push(name) // Crash debris forbids automatic purge, but not recovery.
+      } else throw new Error(`Unexpected batch entry: ${name}`)
+    }
+    return { manifest: m, missing }
+  }
+  async listTrash(): Promise<{ batches: TrashBatch[]; issues: string[] }> {
+    await this.roots()
+    const batches: TrashBatch[] = [], issues: string[] = []
+    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
+      try {
+        if (!item.isDirectory() || item.isSymbolicLink()) throw new Error('Not a batch directory')
+        batches.push(await this.load(item.name))
+      } catch (error) { issues.push(`${item.name}: ${message(error)}`) }
+    }
+    return { batches, issues }
+  }
+  // Atomic metadata replacement keeps the previous recoverable journal on crash.
+  // Only metadata is renamed; session files are NEVER rename-overwritten.
+  private async journal(manifest: Manifest, create = false) {
+    const dir = this.batchPath(manifest.id), path = join(dir, 'manifest.json')
+    await safePath(path, create)
+    if (create) {
+      const handle = await open(path, 'wx')
+      try { await handle.writeFile(JSON.stringify(manifest)); await handle.sync() } finally { await handle.close() }
+      return
+    }
+    await regular(path)
+    const temp = join(dir, `manifest.${randomUUID()}.tmp`)
+    const handle = await open(temp, 'wx')
+    try { await handle.writeFile(JSON.stringify(manifest)); await handle.sync() } finally { await handle.close() }
+    await regular(path)
+    await rename(temp, path)
+  }
+  // Stage and sync the copy before exclusive hard-link publication on the target
+  // filesystem. Even a crash mid-copy cannot expose a truncated recoverable file.
+  // A crash after publication may leave BOTH copies: restore refuses that collision.
+  private async move(source: string, target: string) {
+    const before = await regular(source)
+    await safePath(target, true)
+    const staging = `${target}.staging`
+    await copyFile(source, staging, constants.COPYFILE_EXCL)
+    const handle = await open(staging, constants.O_RDWR | (constants.O_NOFOLLOW ?? 0))
+    try { await handle.sync() } finally { await handle.close() }
+    await link(staging, target) // fails rather than overwriting any existing entry
+    await unlink(staging)
+    const after = await regular(source)
+    if (before.ino !== after.ino || before.dev !== after.dev || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('Source changed during move; both copies retained')
+    await unlink(source)
+  }
+  async trashFamily(family: Family, options: MutationOptions): Promise<Manifest> {
+    return (await this.trashFamilies([family], options))[0]
+  }
+  async trashFamilies(families: Family[], options: MutationOptions): Promise<Manifest[]> {
+    const now = time(options?.now)
+    await this.allow(options, 'trash', families.flatMap(f => f.paths))
+    // Revalidate the entire plan once under the adapter's exclusive lock, not
+    // once per family (which would reread O(n²) headers during the first cleanup).
+    const scan = await this.scan({ now })
+    const candidates = new Map(scan.candidates.map(f => [f.id, f]))
+    const seen = new Set<string>()
+    for (const family of families) {
+      const current = candidates.get(family.id)
+      if (!current || family.protected || seen.has(family.id) || current.paths.length !== family.paths.length || !current.paths.every((p, i) => p === family.paths[i])) throw new Error('Family is no longer a safe candidate')
+      seen.add(family.id)
+    }
+    const manifests: Manifest[] = []
+    for (const family of families) manifests.push(await this.trashValidated(family, { ...options, now }))
+    return manifests
+  }
+  private async trashValidated(current: Family, options: MutationOptions): Promise<Manifest> {
+    for (const path of current.paths) {
+      if (time(options.now) - (await header(path)).activity <= RETENTION_MS) throw new Error('Family activity changed; no longer a safe candidate')
+    }
+    const manifest: Manifest = { version: 1, id: randomUUID(), trashedAt: time(options.now), ready: false, files: current.paths.map((path, i) => ({ original: relative(this.root, path).split(sep).join('/'), stored: `${i}.jsonl` })) }
+    for (const file of manifest.files) this.original(file.original)
+    if (Buffer.byteLength(JSON.stringify(manifest)) > MANIFEST_BYTES) throw new Error('Manifest too large')
+    await mkdir(this.trashRoot, { recursive: true })
+    await safePath(this.trashRoot)
+    await mkdir(this.batchPath(manifest.id))
+    await this.journal(manifest, true)
+    for (const file of manifest.files) {
+      await this.allow(options, 'trash', current.paths)
+      const source = this.original(file.original)
+      if (time(options.now) - (await header(source)).activity <= RETENTION_MS) throw new Error('Family activity changed; incomplete journal retained')
+      await this.move(source, join(this.batchPath(manifest.id), file.stored))
+    }
+    await this.allow(options, 'trash', current.paths)
+    manifest.ready = true
+    await this.journal(manifest)
+    return manifest
+  }
+  async restoreFamily(id: string, options: MutationOptions): Promise<{ restored: string[] }> {
+    const now = time(options?.now)
+    const { manifest } = await this.load(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.
+    for (const file of manifest.files) {
+      const source = join(this.batchPath(id), file.stored), target = this.original(file.original)
+      if (await exists(source) && await exists(target)) throw new Error(`Restore collision: ${target}`)
+      if (!await exists(source) && !await exists(target)) throw new Error(`Missing both copies: ${target}`)
+      if (await exists(target)) await regular(target)
+    }
+    manifest.ready = false
+    await this.journal(manifest)
+    const restored: string[] = []
+    for (const file of manifest.files) {
+      const source = join(this.batchPath(id), file.stored), target = this.original(file.original)
+      await this.allow(options, 'restore', paths)
+      await safePath(target, true)
+      if (await exists(source)) {
+        await mkdir(resolve(target, '..'), { recursive: true })
+        await this.move(source, target)
+        restored.push(target)
+      }
+      await regular(target)
+      await utimes(target, new Date(now), new Date(now))
+    }
+    await this.allow(options, 'restore', paths)
+    await this.removeJournal(id)
+    return { restored }
+  }
+  private async removeJournal(id: string) {
+    const dir = this.batchPath(id)
+    await regular(join(dir, 'manifest.json'))
+    const names = await readdir(dir)
+    if (names.length !== 1 || names[0] !== 'manifest.json') throw new Error('Batch still contains files or crash debris; journal retained')
+    await unlink(join(dir, 'manifest.json'))
+    await rmdir(dir)
+  }
+  async purgeExpired(options: MutationOptions): Promise<{ purged: string[]; issues: string[] }> {
+    const now = time(options?.now)
+    await this.allow(options, 'purge', [])
+    const { batches, issues } = await this.listTrash()
+    const purged: string[] = []
+    for (const batch of batches) {
+      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)
+        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)
+        manifest.ready = false // A partial purge must never automatically continue.
+        await this.journal(manifest)
+        for (const file of manifest.files) {
+          await this.allow(options, 'purge', paths)
+          const path = join(this.batchPath(id), file.stored)
+          await regular(path)
+          await unlink(path)
+        }
+        await this.removeJournal(id)
+        purged.push(id)
+      } catch (error) { issues.push(`${id}: ${message(error)}`) }
+    }
+    return { purged, issues }
+  }
+}

package/packages/pi-session-retention/src/dialog.ts

@@ -0,0 +1,118 @@
+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 { dialogRows, wheelAsArrows } from "./lib/dialog.ts";
+
+export type TrashChoice = { value: string; label: string; description: string; search: string };
+
+export class SessionTrashDialog implements Component, Focusable {
+	private input = new Input({ prompt: "" });
+	private list!: SelectList;
+	private filtered: TrashChoice[] = [];
+	private viewport = 5;
+
+	constructor(
+		private tui: TUI,
+		private theme: Theme,
+		private keybindings: KeybindingsManager,
+		private choices: TrashChoice[],
+		query: string,
+		private done: (id: string | undefined) => void,
+	) {
+		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; }
+
+	private filter(): void {
+		const query = this.input.getValue().toLowerCase();
+		this.filtered = this.choices.filter((choice) => choice.search.toLowerCase().includes(query));
+		this.buildList();
+	}
+
+	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"),
+		});
+		if (selected !== undefined) this.list.setSelectedIndex(Math.max(0, this.filtered.findIndex((choice) => choice.value === selected)));
+	}
+
+	handleMouse(event: TuiMouseEvent) { return wheelAsArrows(event, (key) => this.handleInput(key)); }
+
+	handleInput(data: string): void {
+		const kb = this.keybindings;
+		if (kb.matches(data, "tui.select.cancel") || matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.done(undefined);
+			return;
+		}
+		if (kb.matches(data, "tui.select.confirm")) {
+			const selected = this.list.getSelectedItem();
+			if (selected) this.done(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 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);
+			}
+		} else {
+			const previous = this.input.getValue();
+			this.input.handleInput(data);
+			if (previous !== this.input.getValue()) this.filter();
+		}
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	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 (viewport !== this.viewport) {
+			this.viewport = viewport;
+			this.buildList(this.list.getSelectedItem()?.value);
+		}
+		// 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)),
+		].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 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"));
+		lines.push(border(`┗${"━".repeat(inner)}┛`));
+		return lines;
+	}
+
+	invalidate(): void {
+		this.input.invalidate();
+		this.list.invalidate();
+	}
+}