@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/extensions/rewind/path-picker.ts

@@ -0,0 +1,198 @@
+/**
+ * The path checklist a partial rewind opens: every changed path, grouped by
+ * directory, each one togglable.
+ *
+ * The screen is the timeline's sibling — same dock frame, same cursor, same
+ * width-safe row grammar — so a partial restore reads as one more step in
+ * `/rewind` rather than a second product. Rows are selected by default, which
+ * makes `Enter` here reproduce the whole-tree restore exactly.
+ *
+ * The component owns only the selection: paths in, a chosen subset out through
+ * `onClose`, and the restore itself stays behind the confirmation that follows.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
+import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { checkbox, listRow } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { baseName, expandGroup, groupPaths, SELECTION_MARKS, type ChangedPath, type PathGroup } from "./paths.ts";
+
+export interface PathPickerOptions {
+	/** The changed paths the snapshot differs on. */
+	paths: readonly ChangedPath[];
+	theme: Theme;
+	/** Called once when the screen closes: the selected paths, or undefined when cancelled. */
+	onClose: (paths?: string[]) => void;
+	requestRender: () => void;
+	viewportRows?: ViewportRowsSource;
+}
+
+/** Rows the screen 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;
+
+/** One rendered row: a directory header or a file under one. */
+type Row = { kind: "group"; group: PathGroup } | { kind: "file"; path: ChangedPath; dir: string };
+
+/** The checklist of changed paths. */
+export class PathPickerComponent implements Component {
+	private readonly cursor: ListCursor;
+	private readonly groups: PathGroup[];
+	private readonly rows: Row[];
+	private readonly chosen = new Set<string>();
+
+	constructor(private readonly options: PathPickerOptions) {
+		this.cursor = new ListCursor(options.requestRender);
+		this.groups = groupPaths(options.paths);
+		// Every path starts selected, so confirming without touching anything means
+		// "restore it all" — the behavior `/rewind` had before the checklist existed.
+		for (const group of this.groups) for (const path of expandGroup(group)) this.chosen.add(path);
+		this.rows = this.groups.flatMap((group): Row[] => [
+			{ kind: "group", group },
+			...group.paths.map((path): Row => ({ kind: "file", path, dir: group.dir })),
+		]);
+	}
+
+	/** Whether every file under `group` is selected. */
+	private groupOn(group: PathGroup): boolean {
+		return group.paths.every((path) => this.chosen.has(path.path));
+	}
+
+	/** Toggle every file under `group` to `on`. */
+	private setGroup(group: PathGroup, on: boolean): void {
+		for (const path of expandGroup(group)) {
+			if (on) this.chosen.add(path);
+			else this.chosen.delete(path);
+		}
+	}
+
+	/** Apply a key press. Exposed for the tests that drive the screen directly. */
+	handleInput(data: string): void {
+		if (isCloseKey(data)) {
+			this.options.onClose(undefined);
+			return;
+		}
+		if (navigateList(data, this.cursor, this.rows.length)) return;
+		if (data === " ") {
+			const row = this.rows[this.cursor.selected];
+			if (row?.kind === "group") this.setGroup(row.group, !this.groupOn(row.group));
+			else if (row) {
+				if (this.chosen.has(row.path.path)) this.chosen.delete(row.path.path);
+				else this.chosen.add(row.path.path);
+			}
+			this.options.requestRender();
+			return;
+		}
+		if (data === "a") {
+			for (const path of this.options.paths) this.chosen.add(path.path);
+			this.options.requestRender();
+			return;
+		}
+		if (data === "n") {
+			this.chosen.clear();
+			this.options.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.enter)) this.options.onClose([...this.chosen]);
+	}
+
+	/** 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 {}
+
+	// The shared dock frame, like every other list screen.
+	render(width: number): string[] {
+		const w = Math.max(1, width);
+		const header = titleRule(this.theme, w, "Restore paths");
+		const cursor = this.cursor;
+		cursor.visible = fitRows(this.options.viewportRows, this.rows.length, SCREEN_CHROME_ROWS, SCREEN_DEFAULT_ITEMS);
+		const { start, end } = cursor.window(this.rows.length);
+
+		const body: string[] = [];
+		for (let i = start; i < end; i++) body.push(this.rowLine(w, this.rows[i], i === cursor.selected));
+
+		const total = this.options.paths.length;
+		const selected = this.chosen.size;
+		return dockListFrame({
+			header,
+			summary: clip(
+				`  ${paint(this.theme, "meta", `${selected} of ${total} selected${SEPARATORS.item}Space toggles a file or a directory`)}`,
+				w,
+			),
+			body,
+			range: cursor.clipped(this.rows.length)
+				? formatRange(this.theme, w, { start, end, total: this.rows.length })
+				: undefined,
+			detail: this.detail(w),
+			hint: this.hint(w),
+		});
+	}
+
+	private get theme(): Theme {
+		return this.options.theme;
+	}
+
+	/** One row: a directory header with its count, or a file with its change mark. */
+	private rowLine(width: number, row: Row, selected: boolean): string {
+		const tone = selected ? "accent" : row.kind === "group" ? "meta" : "label";
+		if (row.kind === "group") {
+			const count = row.group.paths.length;
+			return listRow(this.theme, width, {
+				selected,
+				leading: checkbox(this.theme, this.groupOn(row.group)),
+				label: `${row.group.dir === "" ? "./" : `${row.group.dir}/`}`,
+				labelRole: tone,
+				trailing: `${count} file${count === 1 ? "" : "s"}`,
+				trailingRole: "meta",
+			});
+		}
+		return listRow(this.theme, width, {
+			selected,
+			indent: 2,
+			// The header already carries the directory's checkbox, so the file rows
+			// keep the column with a blank rather than repeating it.
+			leading: " ",
+			label: baseName(row.path.path),
+			labelRole: tone,
+			trailing: SELECTION_MARKS[row.path.change],
+			trailingRole: row.path.change === "added" ? "warn" : "meta",
+		});
+	}
+
+	/** What the focused row will do, in words. */
+	private detail(width: number): string[] | undefined {
+		const row = this.rows[this.cursor.selected];
+		if (!row) return undefined;
+		const text =
+			row.kind === "group"
+				? `Space selects or clears all ${row.group.paths.length} file${row.group.paths.length === 1 ? "" : "s"} in this directory.`
+				: row.path.change === "added"
+					? "A — created after the snapshot; restoring removes it."
+					: row.path.change === "deleted"
+						? "D — deleted since the snapshot; restoring brings it back."
+						: "M — modified since the snapshot; restoring rewrites it.";
+		return [clip(`  ${paint(this.theme, "meta", text)}`, width)];
+	}
+
+	/** The key-hint row, with the primary action in the accent role. */
+	private hint(width: number): string {
+		return screenHint(this.theme, width, [
+			"Esc cancel",
+			{ text: "Enter restore", color: "accent" },
+			"Space toggle",
+			"a all",
+			"n none",
+		]);
+	}
+}

package/extensions/rewind/paths.ts

@@ -0,0 +1,128 @@
+/**
+ * The changed paths a rewind can restore, and how the picker groups them.
+ *
+ * `git diff --name-status <snapshot> <working tree>` is the one source of truth:
+ * the preview, the checklist, and the apply step all read this list, so they
+ * cannot disagree about what changed. Pure: parsing, grouping, marks, and the
+ * counts `RestoreSummary` reports.
+ *
+ * A rename arrives as `R100\told\tnew`. It is expanded into two entries — the old
+ * path as deleted and the new one as added — because that is exactly what the
+ * restore does to each: selecting the old path brings it back, selecting the new
+ * one removes it. Both rows appear in the checklist rather than one opaque one.
+ */
+
+/** What a restore does to one path. */
+export type PathChange = "modified" | "deleted" | "added";
+
+/** One path the snapshot differs on, and how. */
+export interface ChangedPath {
+	/** Repository-relative path, as git reports it. */
+	path: string;
+	change: PathChange;
+}
+
+/** The trailing mark for each change in the checklist. */
+export const SELECTION_MARKS: Readonly<Record<PathChange, string>> = {
+	modified: "M",
+	deleted: "D",
+	added: "A",
+};
+
+/** One directory's files, for the checklist's grouping. */
+export interface PathGroup {
+	/** Directory relative to the root; `""` for files at the root. */
+	dir: string;
+	/** The group's files, sorted by path. */
+	paths: ChangedPath[];
+}
+
+/** The status letter → change kind, for the single-path statuses. */
+function changeOf(letter: string): PathChange | undefined {
+	switch (letter) {
+		case "M":
+		case "T": // a type change (file ↔ symlink) rewrites the path
+			return "modified";
+		case "D":
+			return "deleted";
+		case "A":
+			return "added";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Parse `git diff --name-status` output. A rename expands to both of its paths
+ * (as described in the module comment) and a copy to its destination only — the
+ * source is untouched, so it is not a changed path. An unknown status letter is
+ * skipped rather than guessed at.
+ */
+export function parseNameStatus(stdout: string): ChangedPath[] {
+	const changed: ChangedPath[] = [];
+	for (const line of stdout.split("\n")) {
+		if (line.trim() === "") continue;
+		const [status, first, second] = line.split("\t");
+		if (!status || !first) continue;
+		const letter = status[0] ?? "";
+		if (letter === "R" || letter === "C") {
+			if (!second) continue;
+			if (letter === "R") changed.push({ path: first, change: "deleted" });
+			changed.push({ path: second, change: "added" });
+			continue;
+		}
+		const kind = changeOf(letter);
+		if (kind) changed.push({ path: first, change: kind });
+	}
+	return changed;
+}
+
+/** The directory part of a path, or `""` for the root. */
+function dirOf(path: string): string {
+	const slash = path.lastIndexOf("/");
+	return slash === -1 ? "" : path.slice(0, slash);
+}
+
+/** The file name within its directory. */
+export function baseName(path: string): string {
+	const slash = path.lastIndexOf("/");
+	return slash === -1 ? path : path.slice(slash + 1);
+}
+
+/**
+ * Group changed paths by directory: the root first, then directories in
+ * lexicographic order, files sorted inside each group. A stable order is what
+ * makes the checklist's cursor predictable and the golden renders testable.
+ */
+export function groupPaths(paths: readonly ChangedPath[]): PathGroup[] {
+	const groups = new Map<string, ChangedPath[]>();
+	for (const entry of paths) {
+		const dir = dirOf(entry.path);
+		const group = groups.get(dir);
+		if (group) group.push(entry);
+		else groups.set(dir, [entry]);
+	}
+	return [...groups.entries()]
+		.map(([dir, entries]) => ({ dir, paths: [...entries].sort((a, b) => a.path.localeCompare(b.path)) }))
+		.sort((a, b) => (a.dir === "" ? -1 : b.dir === "" ? 1 : a.dir.localeCompare(b.dir)));
+}
+
+/** The paths a directory toggle selects. */
+export function expandGroup(group: PathGroup): string[] {
+	return group.paths.map((entry) => entry.path);
+}
+
+/**
+ * The counts the plan and the summary report: `changed` is modified plus deleted
+ * (files rewritten from the snapshot), and `removed` is the paths created after
+ * it, which the restore deletes.
+ */
+export function summarize(paths: readonly ChangedPath[]): { changed: number; removed: number } {
+	let changed = 0;
+	let removed = 0;
+	for (const entry of paths) {
+		if (entry.change === "added") removed++;
+		else changed++;
+	}
+	return { changed, removed };
+}

package/extensions/rewind/restore.ts

@@ -1,24 +1,31 @@
 /**
  * Rewind: restore the working tree and index to a snapshot without moving HEAD.
  *
- * `read-tree --reset -u` brings tracked files back to the snapshot (restoring
- * modifications and deletions and removing paths the snapshot never had). Files
- * created after the snapshot and never tracked are then deleted explicitly,
- * because `read-tree` leaves untracked files alone. HEAD, branches, and reflogs
- * are untouched.
+ * The whole-tree restore runs `read-tree --reset -u` against the snapshot, which
+ * brings tracked files back (restoring modifications and deletions and removing
+ * paths the snapshot never had). Files created after the snapshot and never
+ * tracked are then deleted explicitly, because `read-tree` leaves untracked files
+ * alone. HEAD, branches, and reflogs are untouched.
+ *
+ * A **partial** restore takes the same shape over a subset: `read-tree` accepts no
+ * pathspec, so the selected paths are checked out of the snapshot instead, and
+ * only the selected additions are deleted. Everything else is left exactly as it
+ * is, and the same temporary index is used, so the real index stays untouched
+ * either way.
  */
 
 import { lstatSync, rmSync } from "node:fs";
 import { resolve, sep } from "node:path";
 import {
-	addedPaths,
 	busyGitState,
-	changedCount,
 	diffStat,
+	nameStatus,
 	readTreeReset,
+	restorePaths,
 	treeFromWorkingTree,
 	type RunGit,
 } from "./git.ts";
+import { summarize, type ChangedPath } from "./paths.ts";
 import type { Snapshot, RestoreSummary } from "./types.ts";
 
 export interface RestoreDeps {
@@ -32,6 +39,8 @@ export interface RestoreInput {
 	indexFile: string;
 	/** Snapshot to restore. */
 	target: Snapshot;
+	/** Restore only these paths; omitted means the whole tree. */
+	paths?: readonly string[];
 }
 
 export interface RestorePlan {
@@ -41,6 +50,8 @@ export interface RestorePlan {
 	changed: number;
 	/** Paths created since the snapshot that the restore removes. */
 	removed: number;
+	/** Every changed path, with how the restore treats it. */
+	paths: ChangedPath[];
 }
 
 export type PlanResult = { ok: true; plan: RestorePlan } | { ok: false; reason: string };
@@ -51,26 +62,32 @@ export async function planRestore(deps: RestoreDeps, input: RestoreInput): Promi
 	if (busy) {
 		return { ok: false, reason: `a git ${busy} is in progress; finish or abort it before restoring.` };
 	}
-	const { cur, added, changed } = await previewRestore(deps, input);
-	const diff = await diffStat(deps.runGit, input.root, input.target.commit, cur);
-	return { ok: true, plan: { diff, changed, removed: added.length } };
+	const cur = await stagedTree(deps, input);
+	const paths = await changedPaths(deps, input, cur);
+	const diff = await diffStat(deps.runGit, input.root, input.target.commit, cur, selectionOf(paths));
+	return { ok: true, plan: { diff, ...summarize(paths), paths } };
+}
+
+/** The selection narrowed to paths the plan actually found, or undefined for all. */
+function selectionOf(paths: readonly ChangedPath[]): string[] | undefined {
+	return paths.length > 0 ? paths.map((entry) => entry.path) : undefined;
 }
 
 /**
- * Stage the working tree into the temporary index and compare it against the
- * snapshot. `cur` is the staged commit, `added` the paths created since the
- * snapshot, and `changed` the tracked files modified or deleted.
+ * Stage the working tree into the temporary index, so previews compare
+ * tree-to-tree: untracked files captured in the snapshot are not mistaken for
+ * deletions against the real index.
  */
-async function previewRestore(
-	deps: RestoreDeps,
-	input: RestoreInput,
-): Promise<{ cur: string; added: string[]; changed: number }> {
-	// Compare tree-to-tree, so untracked files captured in the snapshot are not
-	// mistaken for deletions against the real index.
-	const cur = await treeFromWorkingTree(deps.runGit, input.root, input.indexFile, input.target.includeUntracked);
-	const added = await addedPaths(deps.runGit, input.root, input.target.commit, cur);
-	const changed = await changedCount(deps.runGit, input.root, input.target.commit, cur, "MD");
-	return { cur, added, changed };
+async function stagedTree(deps: RestoreDeps, input: RestoreInput): Promise<string> {
+	return treeFromWorkingTree(deps.runGit, input.root, input.indexFile, input.target.includeUntracked);
+}
+
+/** Every changed path, narrowed to the caller's selection when one is given. */
+async function changedPaths(deps: RestoreDeps, input: RestoreInput, cur: string): Promise<ChangedPath[]> {
+	const all = await nameStatus(deps.runGit, input.root, input.target.commit, cur);
+	if (!input.paths) return all;
+	const selected = new Set(input.paths);
+	return all.filter((entry) => selected.has(entry.path));
 }
 
 /** Delete a path under `root`, refusing to escape it or remove a directory. */
@@ -85,12 +102,36 @@ function deleteFile(root: string, relative: string): void {
 	}
 }
 
-/** Apply the restore. Recomputes the removal set immediately before mutating. */
+/**
+ * Apply the restore. Recomputes the changed set immediately before mutating, so a
+ * file edited while the confirmation was open is still handled correctly.
+ */
 export async function applyRestore(deps: RestoreDeps, input: RestoreInput): Promise<RestoreSummary> {
-	const { added, changed } = await previewRestore(deps, input);
+	const cur = await stagedTree(deps, input);
+	const paths = await changedPaths(deps, input, cur);
+	const { changed, removed } = summarize(paths);
+	const rewritten = paths.filter((entry) => entry.change !== "added").map((entry) => entry.path);
+	const created = paths.filter((entry) => entry.change === "added").map((entry) => entry.path);
+
+	if (input.paths) {
+		await restorePaths(deps.runGit, input.root, input.target.commit, input.indexFile, rewritten);
+	} else {
+		// The whole tree in one call: this also removes files the snapshot lacks,
+		// which a pathspec checkout of every changed path would not.
+		await readTreeReset(deps.runGit, input.root, input.target.commit, input.indexFile);
+	}
+	for (const path of created) deleteFile(input.root, path);
 
-	await readTreeReset(deps.runGit, input.root, input.target.commit, input.indexFile);
-	for (const path of added) deleteFile(input.root, path);
+	// A subset notice says "2 of 5 files", so it needs the whole diff's size; the
+	// all-path query is already in hand when nothing was narrowed.
+	const of = input.paths ? (await nameStatus(deps.runGit, input.root, input.target.commit, cur)).length : paths.length;
 
-	return { id: input.target.id, commit: input.target.commit, root: input.root, changed, removed: added.length };
+	return {
+		id: input.target.id,
+		commit: input.target.commit,
+		root: input.root,
+		changed,
+		removed,
+		...(input.paths ? { of } : {}),
+	};
 }

package/extensions/rewind/rewind.ts

@@ -9,7 +9,11 @@
  */
 
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { withRailsSuppressed } from "../../lib/rails.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatChangeSummary, formatRestoreText, previewDiffText } from "./format.ts";
+import { PathPickerComponent } from "./path-picker.ts";
+import type { ChangedPath } from "./paths.ts";
 import type { RewindRuntime } from "./runtime.ts";
 import { rewindScopes, type RewindPoint, type RewindScope } from "./timeline.ts";
 
@@ -47,19 +51,67 @@ async function chooseScope(
 }
 
 /** Build the combined confirm body, including the diff preview when code moves. */
-function confirmBody(scope: RewindScope, changeSummary: string | undefined, diff: string | undefined): string {
+function confirmBody(
+	scope: RewindScope,
+	changeSummary: string | undefined,
+	diff: string | undefined,
+	subset?: { selected: number; total: number },
+): string {
 	const lines = [scopeDescription(scope)];
+	if (subset) lines.push(`Restoring ${subset.selected} of ${subset.total} changed files.`);
 	if (changeSummary) lines.push(`${changeSummary} since the snapshot. HEAD is untouched.`);
 	if (diff) lines.push("", previewDiffText(diff));
 	if (scope !== "code") lines.push("", "This prompt returns to the editor so you can edit and resubmit.");
 	return lines.join("\n");
 }
 
+/** What the path step decided: the whole tree, a chosen subset, or nothing. */
+export type PathChoice = { kind: "all" } | { kind: "some"; paths: string[] } | { kind: "cancel" };
+
+/** The two answers the path step offers before the checklist opens. */
+const ALL_LABEL = (count: number): string => `Everything (${count} file${count === 1 ? "" : "s"})`;
+const SOME_LABEL = "Choose paths…";
+
+/**
+ * Ask which paths to restore. The checklist needs a list only a TUI can mount, so
+ * every other mode keeps the whole-tree restore rather than inventing a typed
+ * syntax with its own parser and preview.
+ */
+export async function choosePaths(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	paths: readonly ChangedPath[],
+): Promise<PathChoice> {
+	if (ctx.mode !== "tui" || paths.length === 0) return { kind: "all" };
+
+	const choice = await ctx.ui.select("Restore what?", [ALL_LABEL(paths.length), SOME_LABEL]);
+	if (choice === undefined) return { kind: "cancel" };
+	if (choice !== SOME_LABEL) return { kind: "all" };
+
+	const selected = await withRailsSuppressed(pi, () =>
+		ctx.ui.custom<string[] | undefined>(
+			(tui, theme, _keybindings, done) =>
+				new PathPickerComponent({
+					paths,
+					theme,
+					onClose: (subset) => done(subset),
+					requestRender: () => tui.requestRender(),
+					viewportRows: () => tui.terminal?.rows,
+				}),
+		),
+	);
+	if (!selected) return { kind: "cancel" };
+	// An empty checklist is a choice, not a cancel: it restores no files and still
+	// moves the conversation, which is what the confirm describes.
+	return { kind: "some", paths: selected };
+}
+
 /**
  * Rewind to `point` with the chosen scope. Interactive only: callers guard on
  * `ctx.hasUI`. Returns true when something was applied.
  */
 export async function rewindTo(
+	pi: ExtensionAPI,
 	runtime: RewindRuntime,
 	ctx: ExtensionCommandContext,
 	root: string | undefined,
@@ -81,6 +133,9 @@ export async function rewindTo(
 	}
 
 	let plan;
+	/** The subset to restore, when the path step narrowed the plan. */
+	let selection: string[] | undefined;
+	let total = 0;
 	if (snapshot && root) {
 		const result = await runtime.plan(root, snapshot);
 		if (!result.ok) {
@@ -88,12 +143,34 @@ export async function rewindTo(
 			return false;
 		}
 		plan = result.plan;
+		total = plan.paths.length;
+		if (plan.paths.length > 0) {
+			const choice = await choosePaths(pi, ctx, plan.paths);
+			if (choice.kind === "cancel") {
+				ctx.ui.notify("Rewind cancelled.", "info");
+				return false;
+			}
+			if (choice.kind === "some") {
+				selection = choice.paths;
+				const narrowed = await runtime.plan(root, snapshot, selection);
+				if (!narrowed.ok) {
+					ctx.ui.notify(narrowed.reason, "warning");
+					return false;
+				}
+				plan = narrowed.plan;
+			}
+		}
 	}
 
 	const label = point.summary || point.prompt || "this prompt";
 	const approved = await ctx.ui.confirm(
 		`Rewind to "${label}"?`,
-		confirmBody(scope, plan ? formatChangeSummary(plan.changed, plan.removed) : undefined, plan?.diff),
+		confirmBody(
+			scope,
+			plan ? formatChangeSummary(plan.changed, plan.removed) : undefined,
+			plan?.diff,
+			selection ? { selected: plan?.paths.length ?? 0, total } : undefined,
+		),
 	);
 	if (!approved) {
 		ctx.ui.notify("Rewind cancelled.", "info");
@@ -103,7 +180,7 @@ export async function rewindTo(
 	const notes: string[] = [];
 	if (snapshot && root) {
 		try {
-			const restored = await runtime.restore(ctx, root, snapshot, runtime.configFor(root));
+			const restored = await runtime.restore(ctx, root, snapshot, runtime.configFor(root), selection);
 			await runtime.setStatus(ctx);
 			notes.push(formatRestoreText(restored));
 		} catch (error) {

package/extensions/rewind/runtime.ts

@@ -33,8 +33,15 @@ export interface RewindRuntime {
 	/** Create and store a snapshot of the current working tree. */
 	snapshot(ctx: ExtensionContext, options: SnapshotOptions): Promise<Snapshot>;
 	list(root: string): Promise<Snapshot[]>;
-	plan(root: string, target: Snapshot): Promise<PlanResult>;
-	restore(ctx: ExtensionContext, root: string, target: Snapshot, config: RewindConfig): Promise<RestoreSummary>;
+	/** Preview a restore; `paths` narrows it to a subset of the changed paths. */
+	plan(root: string, target: Snapshot, paths?: readonly string[]): Promise<PlanResult>;
+	restore(
+		ctx: ExtensionContext,
+		root: string,
+		target: Snapshot,
+		config: RewindConfig,
+		paths?: readonly string[],
+	): Promise<RestoreSummary>;
 	/** Repaint the `↺ N` chip from the prompt count on the active branch (`/rewind` list size). */
 	setStatus(ctx: ExtensionContext): Promise<void>;
 	clearStatus(ctx: ExtensionContext): void;
@@ -110,10 +117,10 @@ export function createRuntime(pi: ExtensionAPI): RewindRuntime {
 	const list = (root: string): Promise<Snapshot[]> =>
 		listSnapshots(runGit, root, configFor(root).refNamespace, { root });
 
-	const plan = (root: string, target: Snapshot): Promise<PlanResult> =>
+	const plan = (root: string, target: Snapshot, paths?: readonly string[]): Promise<PlanResult> =>
 		queue.enqueue(async () => {
 			if (!belongsToRoot(target, root)) return { ok: false, reason: foreignRootReason(target, root) };
-			return planRestore({ runGit }, { root, indexFile: await indexStore.pathFor(root), target });
+			return planRestore({ runGit }, { root, indexFile: await indexStore.pathFor(root), target, paths });
 		});
 
 	const restore = (
@@ -121,11 +128,12 @@ export function createRuntime(pi: ExtensionAPI): RewindRuntime {
 		root: string,
 		target: Snapshot,
 		config: RewindConfig,
+		paths?: readonly string[],
 	): Promise<RestoreSummary> =>
 		queue.enqueue(async () => {
 			if (!belongsToRoot(target, root)) throw new Error(foreignRootReason(target, root));
 			const indexFile = await indexStore.pathFor(root);
-			const input: RestoreInput = { root, indexFile, target };
+			const input: RestoreInput = { root, indexFile, target, paths };
 			let safety: string | undefined;
 			if (config.safetySnapshot) {
 				const before = await createSnapshot(

package/extensions/rewind/snapshot-run.ts

@@ -15,8 +15,11 @@ import { createSnapshotPolicy, type SnapshotPolicy } from "./policy.ts";
 import type { RewindRuntime } from "./runtime.ts";
 
 export interface SnapshotRun {
-	/** Start a run for `prompt`: reset run state and resolve the snapshot decision. */
-	beginRun(prompt: string, ctx: ExtensionContext): Promise<void>;
+	/**
+	 * Start a run for `prompt` — `undefined` when a custom message started it: reset
+	 * run state and resolve the snapshot decision.
+	 */
+	beginRun(prompt: string | undefined, ctx: ExtensionContext): Promise<void>;
 	/** Take the run's single snapshot before the first mutating call, at most once. */
 	onToolCall(toolName: string, ctx: ExtensionContext): Promise<void>;
 	/** Drop run-scoped state (on session shutdown). */

package/extensions/rewind/types.ts

@@ -53,6 +53,8 @@ export interface RestoreSummary {
 	changed: number;
 	/** Files deleted because they were created after the snapshot. */
 	removed: number;
+	/** Paths the whole diff touched, present only when a subset was restored. */
+	of?: number;
 	/** Id of the pre-restore safety snapshot, when one was taken. */
 	safety?: string;
 }