@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/extensions/rewind/README.md

@@ -2,16 +2,20 @@
 
 Snapshot the working tree at the start of each task and return to an earlier
 prompt from a menu — restoring the **code**, the **conversation**, or **both**.
-A snapshot is a git commit kept under `refs/pi/rewind/<id>`; restoring one
-rewrites the working tree **without touching the real index or moving HEAD**, so
-commits, branches, staged state, and the reflog are untouched. Conversation
-rewind uses Pi's session tree, so the branch you leave is not erased.
+`/review` uses the same snapshot to show the latest turn's changes and revert one
+file or the whole turn. A snapshot is a git commit kept under
+`refs/pi/rewind/<id>`; restoring one rewrites the working tree **without
+touching the real index or moving HEAD**, so commits, branches, staged state, and
+the reflog are untouched. Conversation rewind uses Pi's session tree, so the
+branch you leave is not erased.
 
 This is the `rewind` extension entrypoint; it is one of two sibling git
 extensions in this package (`worktree` is the other).
 
 <img src="../../assets/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and the focused prompt's snapshot detail" width="100%">
 
+<img src="../../assets/review.png" alt="The /review screen: changed files with M, A, and D marks, line counts, and the focused file's detail" width="100%">
+
 ```
 pi --extension ./extensions/rewind   # load this extension alone
 pi -e .                              # load the whole @gavin-hu/my-pi-agent package
@@ -22,6 +26,17 @@ pi install ./                        # install the package
 
 - Takes **one automatic snapshot per user prompt**, before the prompt's first
   mutating tool call. A read-only prompt snapshots nothing.
+- `/review` compares the working tree with the snapshot taken before the latest
+  prompt on the active branch. The file list carries `M`/`A`/`D`/`R` and line
+  counts; `Enter` opens a scrollable patch, `Space` selects files, `r` reverts
+  the selection (or the focused file when nothing is selected), and `R` reverts
+  every changed path. A modified text file's diff offers `h`, which opens a hunk
+  checklist; the chosen hunks revert as one reverse patch with its own
+  pre-restore safety snapshot. A rename is one `R` row, so reverting it restores
+  the old path and removes the new one together. A selected batch is one restore
+  and one pre-restore safety snapshot, not one per file. When the working tree
+  matches HEAD, the screen says the changes are already committed and a revert
+  leaves the commits in place.
 - `/rewind` lists **every user prompt on the active branch** (newest first), each
   marked `⬥` when a code snapshot was captured for it.
 - Picking a point asks what to restore: **Code and conversation**,
@@ -31,9 +46,10 @@ pi install ./                        # install the package
   - When code moves, a second step asks **Restore what?** — **Everything (N
     files)** or **Choose paths…**. The checklist lists every changed path
     grouped by directory (`M` modified, `D` deleted since the snapshot, `A`
-    created after it), with all of them selected, so `Enter` twice reproduces a
-    whole-tree restore. `Space` toggles a file or a directory, `a`/`n` select
-    all/none, and the confirm that follows previews only the chosen subset.
+    created after it, `R` renamed), with all of them selected, so `Enter` twice
+    reproduces a whole-tree restore. `Space` toggles a file or a directory,
+    `a`/`n` select all/none, and the confirm that follows previews only the
+    chosen subset.
   - *Conversation* moves the session tree back to that prompt and puts the
     prompt text back in the editor; the abandoned branch stays in the session.
 - Shows a `↺ N` status chip counting the prompts on the active branch — the
@@ -52,6 +68,7 @@ the main checkout; `list`/matching filter to the current root by default.
 | Command | What it does |
 |---|---|
 | `/rewind` | Open the timeline; pick a prompt, then a restore scope, then (for code) the paths. |
+| `/review` | Review the latest prompt's changes; open a diff, select files with `Space`, revert the selection or all files, or revert chosen hunks with `h`. |
 
 The path checklist is its own `ctx.ui.custom` screen: `Space` toggles the focused
 row, `a`/`n` select all or none, `Enter` returns the selection, and `Esc` cancels
@@ -63,13 +80,22 @@ The scope choice and the confirmation (with a diff preview) run after the screen
 closes. The path checklist is the same grammar: `Space` toggles, `a`/`n` select
 all or none, `Enter` restores the selection, `Esc` cancels the rewind.
 
+The review list is keyboard-driven too: `↑`/`↓` or `j`/`k` move, `PgUp`/`PgDn` and
+`Home`/`End` jump, `Space` toggles the focused file, `a`/`n` select all or none,
+`Enter` opens the focused file's diff, `r` reverts the selection (or the focused
+file when nothing is selected), `R` reverts every changed path, and `Esc` closes.
+In the diff, `j`/`k`, the arrows, `PgUp`/`PgDn`, and `g`/`G` scroll, `r` reverts
+the file, and `Esc` goes back. A modified text file's diff offers `h` for the
+hunk checklist: `Space` toggles, `a`/`n` select all or none, `Enter` reverts the
+chosen hunks, and `Esc` cancels back to the diff.
+
 ## Behaviour by mode
 
 | Mode | Behaviour |
 |---|---|
-| Interactive TUI | Full selectable timeline component, then the scope choice, the path checklist, and the confirmation. |
-| RPC (`hasUI`) | Timeline falls back to `ui.select`; scope choice and confirmation use forwarded dialogs. |
-| `print` / `json` | No picker: the prompt list is printed. |
+| Interactive TUI | Full selectable timeline, then the scope choice, the path checklist, and the confirmation. `/review` mounts the changed-file list, the per-file diff, and the hunk checklist. |
+| RPC (`hasUI`) | Timeline falls back to `ui.select`; scope choice and confirmation use forwarded dialogs. `/review` prints the changed-path list. |
+| `print` / `json` | No picker: the prompt list is printed. `/review` prints the changed-path list. |
 
 ## Configuration
 
@@ -94,15 +120,19 @@ The `rewind` section of the shared `bytefly.json` (global document, then
 | Key | Meaning |
 |---|---|
 | `autoSnapshots` | Take one automatic snapshot per prompt. Default `true`. |
-| `max` | Snapshot refs kept per root before the oldest are pruned on save. |
+| `max` | Snapshot refs kept per root; automatic and pre-restore safety snapshots both count. |
 | `includeUntracked` | Capture untracked, non-ignored files. |
 | `safetySnapshot` | Save the current state before a code restore. |
-| `autoPrune` | Delete the oldest refs beyond `max` after saving. |
+| `autoPrune` | Delete the oldest refs beyond `max` after an automatic snapshot. |
 | `showStatus` | Draw the `↺ N` status chip. |
 | `watch` | Extra tool names to treat as mutating. |
 | `ignore` | Tool names never to snapshot; this package's own tools are always excluded. |
 | `refNamespace` | Ref namespace for stored snapshots. |
 
+A restore's safety snapshot is not pruned immediately, so the snapshot it
+restored from stays available for a follow-up restore; the next automatic
+snapshot applies the cap.
+
 ## How snapshots are stored
 
 Each snapshot is a commit under `refs/pi/rewind/<id>` whose body carries a
@@ -126,6 +156,19 @@ commit. These refs are not branches and are not touched by `git push --all`.
 - **The path checklist is TUI-only.** RPC, `print`, and `json` modes restore the
   whole tree; there is no typed path syntax, because a list of exact paths is what
   the checklist is for and a glob would need its own validation and preview.
+- **Hunk selection covers modified text files.** Added, deleted, renamed, and
+  binary files, and a change with no textual hunks (a mode-only change), revert
+  whole; the diff offers `h` only when it has hunks to show.
+- **`/review` follows the latest prompt with a snapshot.** A read-only prompt
+  after it does not change the target, and a turn whose snapshot failed has no
+  review of its own. Actions are TUI-only; other modes print the changed list.
+- **`/review` refuses while plan mode is on.** Plan mode is read-only, so approve
+  the plan before reverting its changes.
+- **`/review` labels committed changes only when the working tree is clean.**
+  `currentTree === HEAD^{tree}` means every reviewed difference is in commits;
+  the confirm then says the commit stays. A dirty tree with some commits since
+  the snapshot is unlabelled and keeps the generic "HEAD and the index are
+  untouched" wording.
 
 ## Non-goals
 
@@ -140,8 +183,8 @@ commit. These refs are not branches and are not touched by `git push --all`.
 
 | Integration point | Value |
 |---|---|
-| Model-facing tools | None. `/rewind` is user-driven; automatic snapshots cover the start of every task. |
-| Commands | `/rewind` (`pi.registerCommand`). |
+| Model-facing tools | None. `/rewind` and `/review` are user-driven; automatic snapshots cover the start of every task. |
+| Commands | `/rewind` and `/review` (`pi.registerCommand`). |
 | Events | `session_start` (reset run state, status, stale-index sweep), `session_tree` (status refresh after tree navigation), `before_agent_start` (record the prompt — absent on a run a custom message starts — and resolve the run's snapshot decision), `tool_call` (take the run's snapshot before the first mutating call), `session_shutdown` (release indexes, clear status). |
 | State storage | Git refs `refs/pi/rewind/<id>` with metadata in the commit body. No tool-result `details` and no `pi.appendEntry`. |
 | Lifecycle | Index paths are created lazily and released in `session_shutdown`; status chip is set on start/tree/snapshot and cleared on shutdown. |
@@ -194,6 +237,31 @@ commit. These refs are not branches and are not touched by `git push --all`.
   records its `root`; listing and matching filter to the current root and
   restoring another worktree's snapshot is refused. The effective root follows
   `PI_WORKTREE_ROOT` when set.
+- **Review is derived, not stored.** `/review` uses the same
+  `buildRewindPoints` pairing as `/rewind`, calls `planRestore`, and fetches a
+  patch only when a file is opened. A revert is the existing subset restore, so
+  the safety snapshot and the working-tree-only rewrite are the ones `/rewind`
+  already guarantees. A selected batch is one subset restore, which is why it
+  takes one safety snapshot; the list carries the selection across a diff/back
+  round without persisting it.
+- **A rename is one entry, not two.** `parseNameStatus` keeps git's `R` line as
+  `{ path: destination, from: source }`, and `entryPaths` is the one helper that
+  names both sides. The restore filters the full diff in memory rather than
+  narrowing it with a pathspec, because git detects a rename only when both
+  paths are in scope; a pathspec would turn the row into an addition and lose
+  the side that has to be recreated. The row's patch and line counts stay a
+  delete plus a create, so the pane and the counts describe the same two
+  operations a revert performs. A rename whose two names resolve to one file (a
+  case-only rename on a case-insensitive filesystem) skips the destination
+  delete, because the checkout has already renamed that file.
+- **A hunk revert is a reverse patch, not a checkout.** `patch.ts` splits one
+  file's diff into its header and hunks; `buildHunkPatch` rebuilds only the chosen
+  ones, and `git apply --reverse` writes them to the working tree without
+  `--index`/`--cached`, so the real index and HEAD stay untouched. The patch goes
+  through a private temp directory because `pi.exec` has no stdin, and git checks
+  every hunk before writing, so a file edited after its diff was read fails
+  atomically. The revert takes the same pre-restore safety snapshot as a file
+  revert.
 - **Identity is fixed for internal commits.** `commit-tree` runs with
   `-c user.name=pi -c user.email=pi@localhost`, so snapshots work without committer
   identity configured and never depend on the user's git config.
@@ -202,23 +270,28 @@ commit. These refs are not branches and are not touched by `git push --all`.
 
 | File | Responsibility |
 |---|---|
-| `index.ts` | Registrar: wire the runtime, the command, and the run-state module to Pi's events (`registerRewind`). |
+| `index.ts` | Registrar: wire the runtime, the commands, and the run-state module to Pi's events (`registerRewind`). |
 | `types.ts` | `Snapshot`, `SnapshotReason`, `RestoreSummary`. |
 | `config.ts` | Config defaults and merge/normalize over `lib/config.ts`. |
-| `git.ts` | Single git entry point: rewind plumbing, the shared read helpers rewind consumes, and the production `RunGit`. |
+| `git.ts` | Single git entry point: rewind plumbing, the shared read helpers rewind consumes (name status, stat, patch, and `--numstat`), the reverse apply a hunk revert uses, and the production `RunGit`. |
 | `snapshot.ts` | Create a snapshot (tree from a temporary index → commit → ref). |
 | `snapshot-run.ts` | Per-run automatic-snapshot state: one snapshot per prompt, with a synchronous guard. |
-| `restore.ts` | Plan and apply a working-tree rewind, whole or for a chosen subset of paths. |
-| `paths.ts` | Pure: the changed-path list from `git diff --name-status`, its directory grouping, the change marks, and the restore counts. |
-| `path-picker.ts` | The checklist screen a partial restore opens: grouped paths, toggles, and the selection it returns. |
+| `restore.ts` | Plan and apply a working-tree rewind, whole or for a chosen subset of paths, recreating a rename's source and removing its destination. |
+| `paths.ts` | Pure: the changed-path list from `git diff --name-status` (a rename is one paired entry), its directory grouping, the change marks, the `--numstat` counts, and the restore counts. |
+| `checklist.ts` | The shared multi-select checklist screen: the cursor, `Space`/`a`/`n`/`Enter`, the height math, and the dock frame. The three checklists below supply only their rows and their words. |
+| `path-picker.ts` | The partial restore's checklist, a `ChecklistScreen` over grouped paths: directory toggles, the change marks, and the selection it returns. |
+| `patch.ts` | Pure: split a single-file unified diff into its header and hunks, and rebuild a patch from chosen hunks. |
+| `hunk-picker.ts` | The hunk checklist a modified file's diff opens, a `ChecklistScreen` over the hunks: previews, the indices it returns, and its own row budget. |
 | `store.ts` | Versioned metadata encoding and ref-backed listing/pruning. |
 | `policy.ts` | Which tool calls are worth a snapshot. |
 | `temp-index.ts` | Per-process `GIT_INDEX_FILE` paths: create, release, and sweep stale files. |
 | `status.ts` | The `↺ N` status chip. |
 | `queue.ts` | The serialized git operation queue for staging calls (`GIT_INDEX_FILE`). |
-| `runtime.ts` | Root/config caches and the snapshot/list/plan/restore operations. |
+| `runtime.ts` | Root/config caches and the snapshot/list/plan/patch/numstat/restore/hunk-revert operations. |
 | `timeline.ts` | Pure: prompts on the branch, paired with their snapshots. |
 | `rewind.ts` | Scope choice, the path step, confirmation, and applying code + conversation rewind. |
+| `review.ts` | The `/review` orchestration: the latest snapshot, the list/diff loop, the hunk step, confirmations, and the reverts. |
+| `review-tui.ts` | The changed-file list (a `ChecklistScreen`) and the scrollable per-file diff, which offers the hunk checklist. |
 | `rewind-tui.ts` | The selectable, width-safe timeline component, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
-| `commands.ts` | The `/rewind` command. |
-| `format.ts` | Model-facing and transcript text (pure). |
+| `commands.ts` | The `/rewind` and `/review` commands. |
+| `format.ts` | Pure rewind and review text, including diff bounding and the hunk prompt. |

package/extensions/rewind/checklist.ts

@@ -0,0 +1,185 @@
+/**
+ * The shared multi-select checklist screen.
+ *
+ * `/rewind`'s partial restore, `/review`'s changed-file list, and `/review`'s
+ * hunk step are one screen: a docked list where Space toggles the focused row,
+ * `a` and `n` fill or clear the selection, Enter returns it, and the summary
+ * names how much is chosen. The frame, the cursor arithmetic, the wheel, and the
+ * height math come from the `lib/tui/` kit; this base owns the selection and the
+ * keys, and a subclass supplies the rows, the row line, the detail block, the
+ * summary text, and the hints.
+ *
+ * Value-only: the cursor and the selection live on the instance.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { detailBlockRows, dockListFrame, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
+import { emptyState } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+
+/** Rows the checklist shows when the terminal height is unknown. */
+const SCREEN_DEFAULT_ITEMS = 12;
+/** Header, summary, blanks, and footer rows around the list. */
+const SCREEN_CHROME_ROWS = 6;
+
+export interface ChecklistOptions {
+	/** The header rule's label. */
+	title: string;
+	theme: Theme;
+	/** Ask the host to repaint. */
+	requestRender(): void;
+	/** The terminal height source, for the visible-row count. */
+	viewportRows?: ViewportRowsSource;
+	/** The empty-list line; omit when an empty list is never shown. */
+	emptyLabel?: string;
+}
+
+export abstract class ChecklistScreen<T> implements Component {
+	/** Focus by row index: a checklist's rows are fixed for the life of the screen. */
+	protected readonly cursor: ListCursor;
+	/** Chosen row keys, in the order they were selected. */
+	protected readonly chosen = new Set<string>();
+	private seeded = false;
+
+	constructor(protected readonly options: ChecklistOptions) {
+		this.cursor = new ListCursor(options.requestRender);
+	}
+
+	/** The rows to show, in screen order. */
+	protected abstract rows(): readonly T[];
+	/** A row's stable key, which is what the selection holds. */
+	protected abstract keyOf(row: T): string;
+	/** One list line for `row`. */
+	protected abstract rowLine(row: T, width: number, selected: boolean): string;
+	/** The summary line's text, without its indent or paint role. */
+	protected abstract summaryText(): string;
+	/** The footer hint row. */
+	protected abstract hint(width: number): string;
+	/** Enter, with the chosen keys in selection order. */
+	protected abstract onEnter(selection: string[]): void;
+	/** Esc or q. */
+	protected abstract onCancel(): void;
+	/** The focus block under the list, painted and clipped; empty for none. */
+	protected detailLines(_width: number): string[] {
+		return [];
+	}
+	/** The keys selected on the first render. */
+	protected initialSelection(): readonly string[] {
+		return this.rows().map((row) => this.keyOf(row));
+	}
+	/** The keys `a` selects; defaults to every row. */
+	protected selectableKeys(): readonly string[] {
+		return this.rows().map((row) => this.keyOf(row));
+	}
+	/** Rows the detail block costs, for the visible-row count. */
+	protected detailRows(detail: readonly string[]): number {
+		return detailBlockRows(detail);
+	}
+	/** A verb other than navigation, toggle, all, none, and enter. */
+	protected verb?(data: string): void;
+
+	/** The row under the cursor. */
+	protected get focused(): T | undefined {
+		return this.rows()[this.cursor.selected];
+	}
+
+	/** Paint through the theme. */
+	protected get theme(): Theme {
+		return this.options.theme;
+	}
+
+	/** Space on the focused row. */
+	protected toggle(row: T): void {
+		const key = this.keyOf(row);
+		if (this.chosen.has(key)) this.chosen.delete(key);
+		else this.chosen.add(key);
+	}
+
+	handleInput(data: string): void {
+		this.seed();
+		if (isCloseKey(data)) {
+			this.onCancel();
+			return;
+		}
+		if (navigateList(data, this.cursor, this.rows().length)) return;
+		if (data === " ") {
+			const row = this.focused;
+			if (row !== undefined) this.toggle(row);
+			this.options.requestRender();
+			return;
+		}
+		if (data === "a") {
+			for (const key of this.selectableKeys()) this.chosen.add(key);
+			this.options.requestRender();
+			return;
+		}
+		if (data === "n") {
+			this.chosen.clear();
+			this.options.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.enter)) {
+			this.onEnter([...this.chosen]);
+			return;
+		}
+		this.verb?.(data);
+	}
+
+	/** Wheel scrolling in fullscreen moves the cursor; regular mode leaves the wheel to the terminal. */
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		return scrollList(event, this.cursor, this.rows().length);
+	}
+
+	dispose(): void {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		this.seed();
+		const w = Math.max(1, width);
+		const header = titleRule(this.theme, w, this.options.title);
+		const rows = this.rows();
+		if (rows.length === 0 && this.options.emptyLabel !== undefined) {
+			return dockListFrame({
+				header,
+				body: emptyState(this.theme, w, { label: this.options.emptyLabel }),
+				hint: this.hint(w),
+			});
+		}
+
+		const detail = this.detailLines(w);
+		this.cursor.visible = fitRows(
+			this.options.viewportRows,
+			rows.length,
+			SCREEN_CHROME_ROWS + this.detailRows(detail),
+			SCREEN_DEFAULT_ITEMS,
+		);
+		const { start, end } = this.cursor.window(rows.length);
+		const body: string[] = [];
+		for (let index = start; index < end; index++) {
+			body.push(this.rowLine(rows[index], w, index === this.cursor.selected));
+		}
+
+		return dockListFrame({
+			header,
+			summary: clip(`  ${paint(this.theme, "meta", this.summaryText())}`, w),
+			body,
+			range: this.cursor.clipped(rows.length)
+				? formatRange(this.theme, w, { start, end, total: rows.length })
+				: undefined,
+			detail: detail.length > 0 ? detail : undefined,
+			hint: this.hint(w),
+		});
+	}
+
+	/** Fill the selection on the first interaction, after the subclass is built. */
+	private seed(): void {
+		if (this.seeded) return;
+		this.seeded = true;
+		for (const key of this.initialSelection()) this.chosen.add(key);
+	}
+}

package/extensions/rewind/commands.ts

@@ -10,6 +10,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import { formatRewindListText, formatRewindRow } from "./format.ts";
+import { openReview } from "./review.ts";
 import { rewindTo } from "./rewind.ts";
 import type { RewindRuntime } from "./runtime.ts";
 import { RewindListComponent } from "./rewind-tui.ts";
@@ -71,4 +72,11 @@ export function registerCommands(pi: ExtensionAPI, runtime: RewindRuntime): void
 			await openRewind(pi, runtime, ctx);
 		},
 	});
+
+	pi.registerCommand("review", {
+		description: "Review the latest turn's changes and revert a file or the whole turn",
+		handler: async (_args, ctx) => {
+			await openReview(pi, runtime, ctx);
+		},
+	});
 }

package/extensions/rewind/config.ts

@@ -6,18 +6,18 @@
  * malformed documents are ignored, and every value is clamped to a safe range.
  */
 
-import { clampInteger, cleanString, loadConfigSection } from "../../lib/config.ts";
+import { clampInteger, cleanString, loadConfigSection, stringList } from "../../lib/config.ts";
 
 export interface RewindConfig {
 	/** Take one automatic snapshot per user prompt. Default: true. */
 	autoSnapshots: boolean;
-	/** Ref count kept per root before the oldest are pruned on save. */
+	/** Ref count kept per root; automatic and pre-restore safety snapshots both count. */
 	max: number;
 	/** Include untracked, non-ignored files in a snapshot. Default: true. */
 	includeUntracked: boolean;
 	/** Snapshot the current state before a restore, so a rewind is undoable. */
 	safetySnapshot: boolean;
-	/** Prune oldest refs beyond `max` after saving. */
+	/** Prune the oldest refs beyond `max` after an automatic snapshot. */
 	autoPrune: boolean;
 	/** Show a `↺ N` status chip while the session runs. */
 	showStatus: boolean;
@@ -41,14 +41,6 @@ export const DEFAULT_CONFIG: RewindConfig = {
 	refNamespace: "refs/pi/rewind",
 };
 
-/** Keep only trimmed, non-empty strings from an untrusted array. */
-function stringList(value: unknown, fallback: string[]): string[] {
-	if (!Array.isArray(value)) return fallback;
-	return value
-		.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
-		.map((item) => item.trim());
-}
-
 /** Normalize one merged config object over the running base. */
 export function normalizeConfig(raw: Record<string, unknown> | undefined, base: RewindConfig): RewindConfig {
 	if (!raw) return base;