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

package/extensions/plan/web.ts

@@ -15,11 +15,25 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { basename } from "node:path";
 import { openInBrowser } from "../../lib/browser.ts";
 import { fenceLanguage, highlightLines } from "../../lib/highlight.ts";
-import { codeBody, fenceInfo, planBlocks, planHeadings } from "./blocks.ts";
-import { parseFeedback, stripFeedback, type PlanAnnotation } from "./feedback.ts";
+import { codeBody, fenceInfo, planBlocks } from "./blocks.ts";
+import {
+	MAX_ANNOTATIONS,
+	MAX_COMMENT_LENGTH,
+	MAX_QUOTE_LENGTH,
+	parseFeedback,
+	stripFeedback,
+	type PlanAnnotation,
+} from "./feedback.ts";
 import { planTitle, type PlanStore, type StoredPlan } from "./plans.ts";
-import { changedSections, extractPlanSteps } from "./steps.ts";
-import { handleReviewRequest, type ReviewContext, type ServeResponse, type SaveResult } from "./web-router.ts";
+import { changedSections, type SectionDigest } from "./plan-text.ts";
+import { extractPlanSections, extractPlanSteps } from "./steps.ts";
+import {
+	handleReviewRequest,
+	JSON_HEADERS,
+	type ReviewContext,
+	type ServeResponse,
+	type SaveResult,
+} from "./web-router.ts";
 import type { ReviewPageData } from "./web-page.ts";
 
 /** How a browser review ended. */
@@ -46,8 +60,8 @@ export interface PlanReviewOptions {
 	signal?: AbortSignal;
 	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
 	canApprove?: boolean;
-	/** The content the previous review showed, so this page can mark changed sections. */
-	previous?: string;
+	/** The section digests the previous review showed, so this page can mark changed sections. */
+	baseline?: SectionDigest[];
 }
 
 /** Starts and tracks review sessions. */
@@ -64,6 +78,10 @@ export interface PlanWebReviewDeps {
 	token?: () => string;
 	/** Override the bind port; the default `0` lets the OS pick. */
 	port?: number;
+	/** Override the closed-tab grace; the default leaves a reload time to reconnect. */
+	dropGraceMs?: number;
+	/** Override the accepted body size; a test keeps it small. */
+	maxBodyBytes?: number;
 }
 
 /** Largest feedback body accepted, in bytes. */
@@ -71,21 +89,37 @@ const MAX_BODY_BYTES = 1024 * 1024;
 /** Grace period before an empty client set counts as a closed tab. */
 const DROP_GRACE_MS = 1500;
 
-function readBody(request: IncomingMessage): Promise<string | undefined> {
+/** A request body, or the fact that it was too large to read. */
+type BodyResult = { ok: true; body: string } | { ok: false };
+
+/**
+ * Read a request body, stopping at {@link MAX_BODY_BYTES}. An oversize body is
+ * reported rather than destroyed here, so the handler can still answer 413 over
+ * the open socket instead of the client seeing a dropped connection.
+ */
+function readBody(request: IncomingMessage, limit: number): Promise<BodyResult> {
 	return new Promise((resolve) => {
 		const chunks: Buffer[] = [];
 		let size = 0;
+		let done = false;
+		const settle = (result: BodyResult): void => {
+			if (done) return;
+			done = true;
+			resolve(result);
+		};
 		request.on("data", (chunk: Buffer) => {
+			if (done) return;
 			size += chunk.length;
-			if (size > MAX_BODY_BYTES) {
-				resolve(undefined);
-				request.destroy();
+			if (size > limit) {
+				chunks.length = 0;
+				request.pause();
+				settle({ ok: false });
 				return;
 			}
 			chunks.push(chunk);
 		});
-		request.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
-		request.on("error", () => resolve(undefined));
+		request.on("end", () => settle({ ok: true, body: Buffer.concat(chunks).toString("utf-8") }));
+		request.on("error", () => settle({ ok: false }));
 	});
 }
 
@@ -115,6 +149,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 	): Promise<PlanReviewSession | undefined> => {
 		const { signal } = options;
 		const canApprove = options.canApprove === true;
+		const maxBody = deps.maxBodyBytes ?? MAX_BODY_BYTES;
 		const token = (deps.token ?? (() => randomBytes(16).toString("hex")))();
 		let settled = false;
 		let resolveDone!: (result: PlanReviewResult) => void;
@@ -132,24 +167,47 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 
 		// The stripped plan the page last rendered; a save must anchor against a file
 		// that still matches it, or the comments land beside the wrong text.
-		let baseline = stripFeedback(plan.content);
-		// Section titles that differ from what the previous review showed. Feedback
-		// is stripped on both sides, so a comment never reads as an edit.
-		const changed =
-			options.previous === undefined ? new Set<string>() : changedSections(stripFeedback(options.previous), baseline);
+		let pageText = stripFeedback(plan.content);
 		let savedPlan: StoredPlan | undefined;
 		// Set by `onSaved`/`onCancel`; resolved once the HTTP response has flushed,
 		// so the caller cannot close the socket before the browser sees the reply.
 		let pendingResult: PlanReviewResult | undefined;
 
-		const page = async (): Promise<ReviewPageData> => {
+		/**
+		 * Re-read the plan into `pageText` and return it. Named apart from the page
+		 * build because it writes the state a later save validates against, so a `GET`
+		 * does not hide that write inside what looks like a read.
+		 */
+		const refreshPageText = async (): Promise<StoredPlan> => {
 			const current = (await store.read(cwd, plan.path)) ?? plan;
-			baseline = stripFeedback(current.content);
-			const blocks = planBlocks(baseline);
-			const headings = planHeadings(blocks);
+			pageText = stripFeedback(current.content);
+			return current;
+		};
+
+		const page = async (): Promise<ReviewPageData> => {
+			const stored = await refreshPageText();
+			const current = pageText;
+			const blocks = planBlocks(current);
+			const sections = extractPlanSections(current);
+			// Per-occurrence change flags, aligned with the sections list: the same shape
+			// the terminal review renders, so duplicate headings cannot both light up.
+			const changed = changedSections(options.baseline, current);
+			const outline = sections.flatMap((section, index) =>
+				section.title === ""
+					? []
+					: [
+							{
+								id: `s-${section.line}`,
+								line: section.line,
+								level: section.level,
+								text: section.title,
+								...(changed[index] ? { changed: true } : {}),
+							},
+						],
+			);
 			// The same step list approval seeds and set_plan_steps indexes, so the page's
 			// progress cannot disagree with the todo list.
-			const stepList = extractPlanSteps(baseline);
+			const stepList = extractPlanSteps(current);
 			// Highlight code blocks once, at the boundary: the client copies only the
 			// tok-* spans out of the server-escaped HTML.
 			const code: Record<string, string[]> = {};
@@ -161,21 +219,16 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			return {
 				// The document's own H1 reads better than the file-name slug, and the
 				// slug is still the fallback for a plan that starts with something else.
-				title: headings.find((heading) => heading.level === 1)?.text || planTitle(basename(current.path)),
+				title: sections.find((section) => section.level === 1)?.title || planTitle(basename(plan.path)),
 				blocks,
-				annotations: parseFeedback(current.content),
-				outline: headings.map((heading) => ({
-					id: `s-${heading.line}`,
-					line: heading.line,
-					level: heading.level,
-					text: heading.text,
-					...(changed.has(heading.text) ? { changed: true } : {}),
-				})),
+				annotations: parseFeedback(stored.content),
+				outline,
 				steps: {
 					done: stepList.filter((step) => step.status === "completed").length,
 					total: stepList.length,
 				},
 				code,
+				limits: { comments: MAX_ANNOTATIONS, comment: MAX_COMMENT_LENGTH, quote: MAX_QUOTE_LENGTH },
 				token,
 				canApprove,
 			};
@@ -184,7 +237,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		const save = async (annotations: PlanAnnotation[]): Promise<SaveResult> => {
 			const current = await store.read(cwd, plan.path);
 			if (!current) return { ok: false, status: 404, message: "The plan file is gone." };
-			if (stripFeedback(current.content) !== baseline) {
+			if (stripFeedback(current.content) !== pageText) {
 				return { ok: false, status: 409, message: "The plan changed on disk; reload the page and review again." };
 			}
 			try {
@@ -215,31 +268,34 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		// button and the abort signal are the deterministic paths.
 		const clients = new Set<ServerResponse>();
 		let hadClient = false;
+		const dropGrace = deps.dropGraceMs ?? DROP_GRACE_MS;
 		const scheduleDrop = (): void => {
 			if (clients.size > 0 || !hadClient || settled || dropTimer) return;
 			dropTimer = setTimeout(() => {
 				dropTimer = undefined;
 				if (clients.size === 0) finish({ status: "cancelled" });
-			}, DROP_GRACE_MS);
+			}, dropGrace);
 			(dropTimer as { unref?: () => void }).unref?.();
 		};
 
 		const server = createServer((request, response) => {
 			void (async () => {
 				const method = request.method ?? "GET";
-				const body = method.toUpperCase() === "POST" ? await readBody(request) : "";
-				if (body === undefined) {
-					response.writeHead(413, { "Content-Type": "application/json" });
+				const read =
+					method.toUpperCase() === "POST" ? await readBody(request, maxBody) : { ok: true as const, body: "" };
+				if (!read.ok) {
+					response.writeHead(413, { ...JSON_HEADERS, Connection: "close" });
 					response.end(JSON.stringify({ error: "The request body is too large." }));
 					return;
 				}
+				const body = read.body;
 				let result: ServeResponse;
 				try {
 					result = await handleReviewRequest(context, method, request.url ?? "/", request.headers, body);
 				} catch {
 					result = {
 						status: 500,
-						headers: { "Content-Type": "application/json" },
+						headers: { ...JSON_HEADERS },
 						body: JSON.stringify({ error: "Internal error" }),
 					};
 				}
@@ -264,16 +320,25 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 					return;
 				}
 				// A save or cancel only resolves the session after its response is on the
-				// wire; otherwise `close()` would force-close the socket mid-reply.
-				response.end(result.body ?? "", () => {
-					if (!pendingResult) return;
+				// wire; otherwise `close()` would force-close the socket mid-reply. The
+				// `close` path covers a client that walks away before the flush callback
+				// runs, so a settle cannot be lost with the socket.
+				const settlePending = (): void => {
 					const terminal = pendingResult;
+					if (!terminal) return;
 					pendingResult = undefined;
 					finish(terminal);
-				});
+				};
+				response.end(result.body ?? "", settlePending);
+				response.on("close", settlePending);
 			})();
 		});
 
+		// An accept-level error (EMFILE and friends) is emitted on the server, and an
+		// `error` event with no listener would take the host down mid-review. The
+		// review still ends through its own paths: cancel, abort, drop, or shutdown.
+		server.on("error", () => {});
+
 		const preferred = deps.port ?? ports.get(plan.path) ?? 0;
 		let port: number | undefined;
 		try {

package/extensions/question/README.md

@@ -131,7 +131,7 @@ None in v1 — the tool is either available (a UI exists) or not.
 |---|---|
 | Tool | `ask_user_question`; `exposure: "model-only"`, `defaultActive: false`, activated in `session_start` when `ctx.hasUI` is true. |
 | Execution | `executionMode: "sequential"`. |
-| Annotations | `readOnlyHint: true`, `openWorldHint: false`, `destructiveHint: false`. |
+| Annotations | `readOnlyHint: true`, `openWorldHint: false` (a read-only tool declares no `destructiveHint`). |
 | Output schema | None. Structured data is returned as tool-result `details` (not `structuredContent`). |
 | State storage | Tool-result `details` (`questions`, `answers`, `cancelled`, `unavailable`). No `pi.appendEntry`. |
 | Lifecycle | `session_start` only: add the tool to the active set when a UI exists. No `session_shutdown`. |

package/extensions/question/tools.ts

@@ -45,7 +45,7 @@ export function registerTools(pi: ExtensionAPI): void {
 		parameters: AskUserQuestionParams,
 		exposure: "model-only",
 		defaultActive: false,
-		annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: false },
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/extensions/rewind/README.md

@@ -28,6 +28,12 @@ pi install ./                        # install the package
   **Conversation only**, or **Code only**.
   - *Code* rewrites the working tree to the snapshot and is itself undoable
     (a `pre-restore` safety snapshot is taken first).
+  - 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.
   - *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
@@ -45,18 +51,23 @@ 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. |
+| `/rewind` | Open the timeline; pick a prompt, then a restore scope, then (for code) the paths. |
+
+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
+the rewind.
 
 The timeline is keyboard-driven: `↑`/`↓` or `j`/`k` move, `PgUp`/`PgDn`/`Home`/`End`
 jump, `Enter` chooses the focused prompt, the mouse wheel scrolls, `Esc` closes.
 The scope choice and the confirmation (with a diff preview) run after the screen
-closes.
+closes. The path checklist is the same grammar: `Space` toggles, `a`/`n` select
+all or none, `Enter` restores the selection, `Esc` cancels the rewind.
 
 ## Behaviour by mode
 
 | Mode | Behaviour |
 |---|---|
-| Interactive TUI | Full selectable timeline component; scope choice and confirmation follow after it closes. |
+| 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. |
 
@@ -110,9 +121,14 @@ A clean working tree still records a commit (so the metadata always travels with
 the snapshot); git reuses the identical tree object, so the only cost is a small
 commit. These refs are not branches and are not touched by `git push --all`.
 
+## Limitations
+
+- **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.
+
 ## Non-goals
 
-- No per-file or partial code rewind; a restore is all-or-nothing.
 - No capture of `.gitignore`d files.
 - No moving HEAD, committing, stashing, or pushing.
 - No non-git projects for code snapshots (conversation-only rewind still works
@@ -126,7 +142,7 @@ commit. These refs are not branches and are not touched by `git push --all`.
 |---|---|
 | Model-facing tools | None. `/rewind` is user-driven; automatic snapshots cover the start of every task. |
 | Commands | `/rewind` (`pi.registerCommand`). |
-| Events | `session_start` (reset run state, status, stale-index sweep), `session_tree` (status refresh after tree navigation), `before_agent_start` (capture the prompt 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). |
+| 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. |
 
@@ -136,7 +152,9 @@ commit. These refs are not branches and are not touched by `git push --all`.
   `before_agent_start` records the prompt summary and resolves the run's root,
   policy, and config, so the first mutating `tool_call` takes the snapshot with a
   fully synchronous guard. No `await` sits between that guard's check and its
-  claim, so parallel sibling calls cannot double-snapshot.
+  claim, so parallel sibling calls cannot double-snapshot. A run a custom message
+  starts (a wake) has no prompt to record; the snapshot it takes is otherwise the
+  same.
 - **The timeline comes from the session tree, not from git.** `/rewind` lists
   every user message on the active branch and pairs each with the snapshot whose
   recorded `entryId` matches, so read-only prompts appear too and the list
@@ -190,7 +208,9 @@ commit. These refs are not branches and are not touched by `git push --all`.
 | `git.ts` | Single git entry point: rewind plumbing, the shared read helpers rewind consumes, 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. |
+| `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. |
 | `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. |
@@ -198,7 +218,7 @@ commit. These refs are not branches and are not touched by `git push --all`.
 | `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. |
 | `timeline.ts` | Pure: prompts on the branch, paired with their snapshots. |
-| `rewind.ts` | Scope choice, confirmation, and applying code + conversation rewind. |
+| `rewind.ts` | Scope choice, the path step, confirmation, and applying code + conversation rewind. |
 | `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). |

package/extensions/rewind/commands.ts

@@ -61,7 +61,7 @@ async function openRewind(pi: ExtensionAPI, runtime: RewindRuntime, ctx: Extensi
 
 	const point = await withRailsSuppressed(pi, () => choosePoint(ctx, points));
 	if (!point) return;
-	await rewindTo(runtime, ctx, root, point);
+	await rewindTo(pi, runtime, ctx, root, point);
 }
 
 export function registerCommands(pi: ExtensionAPI, runtime: RewindRuntime): void {

package/extensions/rewind/format.ts

@@ -131,11 +131,11 @@ export function previewDiffText(diff: string, maxLines = DIFF_PREVIEW_LINES): st
 	return [...lines.slice(0, maxLines), `… ${lines.length - maxLines} more lines`].join("\n");
 }
 
-/** Restore confirmation text. */
+/** Restore confirmation text; a partial restore also names how much it covered. */
 export function formatRestoreText(summary: RestoreSummary): string {
-	const parts = [
-		`Restored snapshot #${summary.id}: ${summary.changed} file${summary.changed === 1 ? "" : "s"} changed`,
-	];
+	const scope = summary.of === undefined ? "" : ` of ${summary.of}`;
+	const files = `${summary.changed}${scope} file${summary.changed === 1 && summary.of === undefined ? "" : "s"}`;
+	const parts = [`Restored snapshot #${summary.id}: ${files} changed`];
 	if (summary.removed > 0) parts.push(`${summary.removed} removed`);
 	const line = `${parts.join(", ")}.`;
 	const safety = summary.safety ? ` A safety snapshot #${summary.safety} captures the pre-restore state.` : "";

package/extensions/rewind/git.ts

@@ -22,6 +22,7 @@ import {
 	runGitOrThrow as run,
 	type RunGit,
 } from "../../lib/git/index.ts";
+import { parseNameStatus, type ChangedPath } from "./paths.ts";
 
 // Re-export exactly the shared helpers this extension consumes, so rewind code
 // has one git import surface instead of reaching into `lib/git` directly.
@@ -128,33 +129,70 @@ export async function readTreeReset(runGit: RunGit, cwd: string, commit: string,
 	await run(runGit, ["read-tree", "--reset", "-u", commit], { cwd, env: { GIT_INDEX_FILE: indexFile } });
 }
 
-/** Paths added between two trees (present in `to`, absent from `from`). */
-export async function addedPaths(runGit: RunGit, cwd: string, from: string, to: string): Promise<string[]> {
-	const result = await runGit(["diff", "--no-color", "--name-only", "--diff-filter=A", from, to], { cwd });
-	if (result.code !== 0) return [];
-	return result.stdout.split("\n").filter((line) => line.trim().length > 0);
+/**
+ * A pathspec that matches `path` literally.
+ *
+ * The paths come from `git diff` output, so a file named `weird[1].txt` is a real
+ * possibility; without `:(literal)` git would read it as a glob and restore the
+ * wrong thing (or nothing).
+ */
+function literalPathspec(path: string): string {
+	return `:(literal)${path}`;
 }
 
-/** `git diff --stat` between two trees. */
-export async function diffStat(runGit: RunGit, cwd: string, from: string, to: string): Promise<string> {
-	const result = await runGit(["diff", "--no-color", "--stat", from, to, "--"], { cwd });
-	return result.code === 0 ? result.stdout.trim() : "";
+/**
+ * The changed paths between two trees, with how each changed.
+ *
+ * One call replaces the separate added-path and changed-count queries, so the
+ * preview, the checklist, and the apply step all read the same list.
+ */
+export async function nameStatus(
+	runGit: RunGit,
+	cwd: string,
+	from: string,
+	to: string,
+	paths?: readonly string[],
+): Promise<ChangedPath[]> {
+	const args = ["diff", "--no-color", "--name-status", from, to, "--"];
+	if (paths) args.push(...paths.map(literalPathspec));
+	const result = await runGit(args, { cwd });
+	return result.code === 0 ? parseNameStatus(result.stdout) : [];
 }
 
-/** Count of paths changed between two trees, optionally filtered by diff status. */
-export async function changedCount(
+/** `git diff --stat` between two trees, optionally limited to `paths`. */
+export async function diffStat(
 	runGit: RunGit,
 	cwd: string,
 	from: string,
 	to: string,
-	filter?: string,
-): Promise<number> {
-	const args = ["diff", "--no-color", "--name-only"];
-	if (filter) args.push(`--diff-filter=${filter}`);
-	args.push(from, to, "--");
+	paths?: readonly string[],
+): Promise<string> {
+	const args = ["diff", "--no-color", "--stat", from, to, "--"];
+	if (paths) args.push(...paths.map(literalPathspec));
 	const result = await runGit(args, { cwd });
-	if (result.code !== 0) return 0;
-	return result.stdout.split("\n").filter((line) => line.trim().length > 0).length;
+	return result.code === 0 ? result.stdout.trim() : "";
+}
+
+/**
+ * Rewrite the given paths in the working tree from `commit`.
+ *
+ * `read-tree --reset -u` takes no pathspec, so a partial restore checks the paths
+ * out of the snapshot instead. The index it writes is the temporary one, so the
+ * real index stays untouched exactly as the whole-tree reset leaves it. Callers
+ * pass only paths present in `commit`; an added path is deleted, not checked out.
+ */
+export async function restorePaths(
+	runGit: RunGit,
+	cwd: string,
+	commit: string,
+	indexFile: string,
+	paths: readonly string[],
+): Promise<void> {
+	if (paths.length === 0) return;
+	await run(runGit, ["checkout", commit, "--", ...paths.map(literalPathspec)], {
+		cwd,
+		env: { GIT_INDEX_FILE: indexFile },
+	});
 }
 
 /** Label of an in-progress git operation that a rewind must not clobber, if any. */

package/extensions/rewind/index.ts

@@ -36,12 +36,10 @@ export function registerRewind(pi: ExtensionAPI): void {
 		await runtime.setStatus(ctx);
 	});
 
-	// A new prompt begins a task: the run resolves its snapshot decision up
-	// front, so the `tool_call` guard can stay synchronous. A run started by a
-	// custom message (a wake) has no user prompt — `event.prompt` is undefined
-	// there despite its type — so `beginRun` accepts a missing prompt.
+	// A run started by a custom message (a wake) has no user prompt: only a user
+	// run carries one, and a newer host spells that as a union on `messageType`.
 	pi.on("before_agent_start", async (event, ctx) => {
-		await run.beginRun(event.prompt, ctx);
+		await run.beginRun("prompt" in event ? event.prompt : undefined, ctx);
 	});
 
 	pi.on("session_shutdown", (_event, ctx) => {