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

package/extensions/plan/tools.ts

@@ -19,7 +19,8 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
-import { TODO_TOOL } from "../../lib/tool-names.ts";
+import { lastGoal } from "../../lib/goal-state.ts";
+import { GOAL_TOOL, TODO_TOOL } from "../../lib/tool-names.ts";
 import { lastTodos } from "../../lib/todo-state.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
@@ -34,13 +35,15 @@ import {
 	PLAN_OUTLINE,
 	extractPlanSteps,
 	planStepSummary,
+	verificationItem,
 	type PlanStep,
-	type PlanStepSummary,
 	type StepUpdate,
 } from "./steps.ts";
+import { basename } from "node:path";
+import { planTitle, type StoredPlan } from "./plans.ts";
 import { DEFAULT_TODO_MAX, mergeTodos, type TodoMerge } from "./todos.ts";
 import { reviewPlan } from "./review.ts";
-import { sanitizePlanText } from "./tui.ts";
+import { sanitizePlanText } from "./plan-text.ts";
 import type { EnterPlanModeDetails, ExitPlanModeDetails, SetPlanStepsDetails, WritePlanDetails } from "./types.ts";
 import { createPlanWebReview, type PlanWebReview } from "./web.ts";
 
@@ -116,20 +119,21 @@ function preview(plan: string): { body: string; more: number } {
 }
 
 /**
- * One sentence for `write_plan` when the step list is larger than approval can
- * track, so the model can shorten it instead of discovering the cap later.
+ * One sentence when a step is longer than the display cap. The text stays in the
+ * plan file either way; only the todo list and the approval listing shorten it.
  */
-function stepCapNote({ total, elided }: PlanStepSummary): string {
-	const notes: string[] = [];
-	if (total > MAX_STEPS) {
-		notes.push(`the plan has ${total} steps and only the first ${MAX_STEPS} can be seeded or ticked`);
-	}
-	if (elided > 0) {
-		notes.push(
-			`${elided} step${elided === 1 ? " is" : "s are"} longer than ${MAX_STEP_LENGTH} characters and will be shortened in the todo list`,
-		);
-	}
-	return notes.length > 0 ? ` Note: ${notes.join("; ")}.` : "";
+function stepElisionNote(elided: number): string {
+	if (elided === 0) return "";
+	const plural = elided === 1 ? " is" : "s are";
+	return ` Note: ${elided} step${plural} longer than ${MAX_STEP_LENGTH} characters and will be shortened in the todo list.`;
+}
+
+/**
+ * The diagnosis both cap refusals share: a step list longer than approval can
+ * track. Each caller appends the fix that is available from where it stands.
+ */
+function overCap(total: number): string {
+	return `The plan has ${total} top-level steps but approval tracks at most ${MAX_STEPS}.`;
 }
 
 /** "Step 2" or "Steps 1, 2" for a set of step numbers. */
@@ -171,11 +175,12 @@ async function seedTodos(
 	plan: string,
 ): Promise<{ steps: PlanStep[]; merged?: TodoMerge; error?: string }> {
 	const steps = extractPlanSteps(plan);
-	if (steps.length === 0) return { steps };
-	const merged = mergeTodos(lastTodos(ctx.sessionManager.getBranch()), steps, todoMaxItems(pi));
-	// Nothing new to write: every step is already in the list (or the list is
-	// full), so a whole-list rewrite would only churn the todo widget.
-	if (merged.added === 0) return { steps, merged };
+	const verification = verificationItem(plan);
+	if (steps.length === 0 && !verification) return { steps };
+	const merged = mergeTodos(lastTodos(ctx.sessionManager.getBranch()), steps, todoMaxItems(pi), verification);
+	// Nothing new to write: every step (and the verification item) is already in
+	// the list, or the list is full, so a rewrite would only churn the widget.
+	if (merged.added === 0 && merged.trailing !== "added") return { steps, merged };
 	const outcome = await ctx.executeTool(TODO_TOOL, { todos: merged.todos });
 	if (!outcome.isError) return { steps, merged };
 	// The nested call fails both when the tool is unavailable and when it rejects
@@ -185,6 +190,56 @@ async function seedTodos(
 	return { steps, merged, error: firstLine ? sanitizeLine(firstLine) : undefined };
 }
 
+/** What the goal offer did: `recorded` undefined when there was nothing to offer. */
+interface GoalOffer {
+	objective: string;
+	recorded?: boolean;
+	error?: string;
+}
+
+/**
+ * Offer to record the approved plan as the session goal — only when the session
+ * has no goal at all (an active or achieved one is the user's, never replaced) and
+ * the session can ask. The objective is the plan's own `# title`, or the file-name
+ * slug; recording runs through the goal tool, so validation and the widget stay
+ * goal's, and no model turn is spent.
+ */
+async function offerSessionGoal(ctx: ExtensionToolContext, plan: StoredPlan): Promise<GoalOffer> {
+	const objective = planObjective(plan);
+	if (!ctx.hasUI) return { objective };
+	// The branch already carries a goal: leave it alone, and say nothing.
+	if (lastGoal(ctx.sessionManager.getBranch()) !== null) return { objective };
+	const approved = await ctx.ui.confirm("Record this plan as the session goal?", objective);
+	if (!approved) return { objective };
+	const outcome = await ctx.executeTool(GOAL_TOOL, { objective });
+	if (!outcome.isError) return { objective, recorded: true };
+	const part = outcome.result?.content?.find((entry) => entry.type === "text");
+	const firstLine = part?.type === "text" ? part.text.split("\n", 1)[0] : undefined;
+	return { objective, recorded: false, error: firstLine ? sanitizeLine(firstLine) : undefined };
+}
+
+/** The plan's own title: its first `# heading`, else the file-name slug. */
+function planObjective(plan: StoredPlan): string {
+	const heading = /^ {0,3}#\s+(.+)$/m.exec(plan.content)?.[1];
+	const title = heading === undefined ? "" : sanitizeLine(heading).trim();
+	return title || planTitle(basename(plan.path));
+}
+
+/**
+ * One sentence about the plan's verification item, or "" when the plan has none
+ * (or it was already in the list). The item is a todo, not a plan step, so it is
+ * ticked in the list rather than in the file.
+ */
+function verificationNote(merged: TodoMerge | undefined): string {
+	if (merged?.trailing === "added") {
+		return "\nThe plan's verification section is the last todo item; tick it in the todo list, not in the file.";
+	}
+	if (merged?.trailing === "deferred") {
+		return "\nThe plan's verification section did not fit in the full todo list; keep it in mind.";
+	}
+	return "";
+}
+
 /** What the merge did, for the approval message; `steps` is the plan's step count. */
 function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
 	const total = steps.length;
@@ -287,7 +342,8 @@ export function registerTools(
 			"Save the plan you designed as a markdown file under .pi/plans (project root, or the agent directory outside a " +
 			"repository). Write the complete plan, not a summary, in this outline so it is consistent and scannable:\n\n" +
 			`${PLAN_OUTLINE}\n\n` +
-			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining.",
+			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining. " +
+			`A plan with more than ${MAX_STEPS} top-level steps in its Steps section is refused, so approval never drops steps it cannot track.`,
 		promptSnippet: "Save the designed plan as a markdown file under .pi/plans.",
 		promptGuidelines: [
 			"While plan mode is active, write the full plan with write_plan, then call exit_plan_mode with the returned path.",
@@ -308,6 +364,21 @@ export function registerTools(
 				};
 			}
 			const args = params as WritePlanArgs;
+			const summary = planStepSummary(args.content);
+			if (summary.total > MAX_STEPS) {
+				// Refuse before writing: a note after the fact arrives once the file exists and
+				// the review has listed every step, so the overflow is already lost.
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${overCap(summary.total)} Nothing was written; group the steps (one outcome each, sub-bullets for detail) and call write_plan again.`,
+						},
+					],
+					details: undefined,
+					isError: true,
+				};
+			}
 			try {
 				const file = await runtime.plans.write(ctx.cwd, {
 					title: args.title,
@@ -319,7 +390,7 @@ export function registerTools(
 					content: [
 						{
 							type: "text",
-							text: `Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepCapNote(planStepSummary(args.content))}`,
+							text: `Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}`,
 						},
 					],
 					details: { path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,
@@ -394,6 +465,27 @@ export function registerTools(
 				};
 			}
 
+			const total = planStepSummary(file.content).total;
+			if (total > MAX_STEPS) {
+				// A hand-edited or older plan file can still be over the cap; refuse it here
+				// too, so approval never seeds a list it cannot hold in full.
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${overCap(total)} It was not presented for approval; call write_plan with plan_path to group the steps, then exit_plan_mode again.`,
+						},
+					],
+					details: {
+						approved: false,
+						plan: file.content,
+						planPath: file.path,
+						relativePath: file.relativePath,
+					} satisfies ExitPlanModeDetails,
+					isError: true,
+				};
+			}
+
 			if (!ctx.hasUI) {
 				return {
 					content: [
@@ -464,6 +556,7 @@ export function registerTools(
 
 			runtime.disable(ctx);
 			const { steps, merged, error } = await seedTodos(pi, ctx, decision.plan.content);
+			const goal = await offerSessionGoal(ctx, decision.plan);
 			const listing =
 				steps.length > 0
 					? `\n\n${steps
@@ -478,6 +571,13 @@ export function registerTools(
 						: merged
 							? mergeSummary(merged, steps)
 							: ` Could not read the todo list. Record these steps with the todo tool before you start, and tick them off with ${SET_PLAN_STEPS_TOOL}.`;
+			const verification = verificationNote(merged);
+			const goalNote =
+				goal.recorded === undefined
+					? ""
+					: goal.recorded
+						? ` Recorded the session goal: ${goal.objective}.`
+						: ` Could not record the session goal: ${goal.error ?? "unknown error"}. Use the goal tool to set it.`;
 			const browserNote = decision.comments.length
 				? `\n\nThe user approved from the browser review with these comments:\n${feedbackSummary(decision.comments)}`
 				: "";
@@ -485,7 +585,7 @@ export function registerTools(
 				content: [
 					{
 						type: "text",
-						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${decision.plan.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${listing}`,
+						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${decision.plan.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${verification}${goalNote}${listing}`,
 					},
 				],
 				details: {

package/extensions/plan/tui.ts

@@ -1,10 +1,6 @@
 /**
  * Terminal rendering for the plan review screen.
  *
- * `sanitizePlanText` is exported so the transcript renderer (`tools.ts`) can
- * strip control characters from plan text with the same rules the review screen
- * uses.
- *
  * `PlanViewComponent` is the scrollable review screen `exit_plan_mode` opens
  * for approval. The plan body is rendered by Pi's own `Markdown` component with
  * the active Markdown theme, so headings, lists, code, links, and quotes match
@@ -30,7 +26,7 @@ import {
 	type TuiMouseEvent,
 	type TuiMouseEventResult,
 } from "@earendil-works/pi-tui";
-import { sanitizeLine, stripControlChars } from "../../lib/format.ts";
+import { sanitizeLine } from "../../lib/format.ts";
 import {
 	editorTheme,
 	screenHint,
@@ -45,8 +41,8 @@ import { titleRule } from "../../lib/tui/rules.ts";
 import { emptyState, checkbox } from "../../lib/tui/rows.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { planTitle, type StoredPlan } from "./plans.ts";
-import { changedSections, extractPlanSections } from "./steps.ts";
-import { stripFeedback } from "./feedback.ts";
+import { changedSections, sanitizePlanText, type SectionDigest } from "./plan-text.ts";
+import { extractPlanSections } from "./steps.ts";
 
 /** What the user chose from the read/review screen. */
 export type PlanViewAction = "approve" | "refine" | "keep" | "browser";
@@ -71,10 +67,10 @@ interface BodyCache {
 export interface PlanViewOptions {
 	plan: StoredPlan;
 	/**
-	 * The content the previous review of this plan showed, when there was one.
-	 * Used only to mark the sections that changed since then.
+	 * The section digests the previous review of this plan showed, when there was
+	 * one. Used only to mark the sections that changed since then.
 	 */
-	previous?: string;
+	baseline?: SectionDigest[];
 	theme: Theme;
 	/**
 	 * Called once when the screen closes. `refinement` carries the typed text
@@ -110,17 +106,6 @@ const PRIMARY_HINTS: ScreenHint[] = [
 const SCROLL_HINTS: ScreenHint[] = ["↑/↓ or k/j scroll", "space/b page", "g/G ends"];
 /** Section-jump hint, shown when the plan has more than one heading section. */
 const SECTION_HINTS: ScreenHint[] = ["n/p section"];
-/** Spaces a tab expands to; the terminal's own tab stops are not width-modelled. */
-const TAB_WIDTH = 4;
-
-/**
- * Replace control characters (including ESC and the C1 block) and expand tabs
- * so model-authored plan text cannot drive the terminal. Newlines are kept, so
- * callers can still render or split the text line by line.
- */
-export function sanitizePlanText(text: string): string {
-	return stripControlChars(text.replace(/\t/g, " ".repeat(TAB_WIDTH)));
-}
 
 /** A task checkbox in a list marker: `- [x] `, `1. [ ] `. */
 const TASK_MARKER = /^([-*+]|\d+[.)])(\s+)(\[([ xX])\])(\s*)$/;
@@ -210,13 +195,7 @@ export class PlanViewComponent implements Component {
 		const base = this.options.markdownTheme ?? getMarkdownTheme();
 		const theme = planMarkdownTheme(this.theme, base);
 		const current = sanitizePlanText(this.options.plan.content);
-		// Both sides of the diff get the same normalization: the baseline is stored
-		// raw, so sanitizing only `current` would report a tab as a change on every
-		// review.
-		const changed =
-			this.options.previous === undefined
-				? []
-				: changedSections(stripFeedback(sanitizePlanText(this.options.previous)), stripFeedback(current));
+		const changed = changedSections(this.options.baseline, current);
 		const chunks = extractPlanSections(current);
 		const lines: string[] = [];
 		const sections: SectionOffset[] = [];

package/extensions/plan/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { PlanAnnotation } from "./feedback.ts";
+import type { SectionDigest } from "./plan-text.ts";
 import type { StepUpdate } from "./steps.ts";
 
 /** Persisted (custom entry) plan-mode state. */
@@ -15,6 +16,14 @@ export interface PlanModeEntry {
 	removed?: string[];
 }
 
+/** Persisted (custom entry) review baseline for one plan. */
+export interface ReviewBaselineEntry {
+	/** Resolved path of the plan file the review showed. */
+	path: string;
+	/** One digest per heading section, in document order. */
+	sections: SectionDigest[];
+}
+
 /** Structured result carried in `enter_plan_mode`'s `details`. */
 export interface EnterPlanModeDetails {
 	/** Whether the user agreed to enter plan mode. */

package/extensions/plan/web-page.ts

@@ -16,6 +16,7 @@
 import {
 	brandLockup,
 	docHead,
+	SIDEBAR_COLLAPSE_MAX,
 	themeToggle,
 	WEB_BASE_CSS,
 	WEB_COMPONENTS_CSS,
@@ -90,7 +91,6 @@ ${WEB_COMPONENTS_CSS}
 .review-progress__fill{display:block;height:100%;width:0;background:var(--accent);transition:width var(--motion-fast) linear}
 /* Review panel: the plan's review facts, the section outline, then the keys. */
 .bf-app__body--single{grid-template-columns:minmax(0,1fr)}
-.bf-app__sidebar .bf-panel{flex:1 1 auto;min-height:0;min-width:0}
 .review-panel{display:flex;flex-direction:column;gap:var(--space-3);padding:var(--space-4) var(--space-4) var(--space-2)}
 .review-facts{display:flex;flex-direction:column;gap:var(--space-2);padding-bottom:var(--space-3);border-bottom:1px solid var(--border)}
 .review-fact{display:flex;align-items:center;justify-content:space-between;gap:var(--space-3);font-size:var(--fs-sm);color:var(--muted)}
@@ -172,7 +172,7 @@ ${WEB_COMPONENTS_CSS}
 .review-nav .lvl-2 a,.review-nav .lvl-3 a,.review-nav .lvl-4 a,.review-nav .lvl-5 a,.review-nav .lvl-6 a{padding-left:8px}
 .review-hints{display:none}
 }
-@media (max-width:860px){
+@media (max-width:${SIDEBAR_COLLAPSE_MAX}px){
 .bf-review{padding:var(--space-4) 18px 80px}
 .review-nav__title{display:none}
 }

package/extensions/plan/web.ts

@@ -25,7 +25,8 @@ import {
 	type PlanAnnotation,
 } from "./feedback.ts";
 import { planTitle, type PlanStore, type StoredPlan } from "./plans.ts";
-import { changedSections, extractPlanSections, extractPlanSteps } from "./steps.ts";
+import { changedSections, type SectionDigest } from "./plan-text.ts";
+import { extractPlanSections, extractPlanSteps } from "./steps.ts";
 import {
 	handleReviewRequest,
 	JSON_HEADERS,
@@ -59,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. */
@@ -166,31 +167,31 @@ 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);
+		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;
 
 		/**
-		 * Re-read the plan into `baseline` and return it. Named apart from the page
+		 * 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 refreshBaseline = async (): Promise<StoredPlan> => {
+		const refreshPageText = async (): Promise<StoredPlan> => {
 			const current = (await store.read(cwd, plan.path)) ?? plan;
-			baseline = stripFeedback(current.content);
+			pageText = stripFeedback(current.content);
 			return current;
 		};
 
 		const page = async (): Promise<ReviewPageData> => {
-			const stored = await refreshBaseline();
-			const current = baseline;
+			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 = options.previous === undefined ? [] : changedSections(stripFeedback(options.previous), current);
+			const changed = changedSections(options.baseline, current);
 			const outline = sections.flatMap((section, index) =>
 				section.title === ""
 					? []
@@ -236,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 {

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. */