@gavin-hu/my-pi-agent 0.15.1 → 0.17.0

package/extensions/worktree/README.md

@@ -20,6 +20,31 @@ How the `list_worktrees` call and its result look in the transcript — the call
 
 <img src="../../assets/tools/list_worktrees.png" alt="The list_worktrees tool's call and result, drawn by the generic fallback" width="100%">
 
+## The `/worktree` screen
+
+<img src="../../assets/worktree.png" alt="The /worktree screen: a Worktrees title rule with a `4 worktrees · 1 dirty · 1 ahead` summary, the current dark-mode row carrying its ahead count, a dirty row, a merged row, and a stale-locked row, the focused row's path and base with the Not isolated gap under it, and the key hints" width="100%">
+
+`/worktree` on its own opens a list screen: one row per managed worktree with its
+state (current, dirty, ahead, behind, merged, locked, last used), the active
+worktree's base and isolation gaps under the focused row, and a detail pane for
+the selected one. Outside a terminal — print, RPC, JSON — the same facts print as
+text instead, which is also what the model's `list_worktrees` reads.
+
+| Key | |
+|---|---|
+| `j` / `k`, arrows | move |
+| `g` / `G` | first / last row |
+| Enter, `l` | open the selected worktree's detail |
+| `e` | enter the selected worktree |
+| `x` | exit the active worktree |
+| `p` | prune eligible worktrees in place |
+| Esc, `q` | close |
+
+`e` and `x` close the screen before they act, because an exit asks through the
+normal prompt and a prompt cannot open inside a mounted screen. `p` never asks,
+so it prunes without closing and reports the result in the footer. In plan mode
+the screen still opens and every verb refuses with a notice.
+
 ## What it does
 
 - `enter_worktree` creates `<repo>/.pi/worktrees/<name>` on branch
@@ -50,18 +75,21 @@ How the `list_worktrees` call and its result look in the transcript — the call
 
 | | |
 |---|---|
-| `/worktree` | status + list managed worktrees |
+| `/worktree` | the list screen: managed worktrees, the active one, and its gaps |
 | `/worktree enter [name]` | enter a worktree (a name may be a PR/MR reference) |
-| `/worktree exit [--keep\|--remove]` | exit a worktree |
+| `/worktree exit` | exit a worktree |
 | `/worktree prune` | remove clean, unused, old managed worktrees |
 | `--worktree <name>` | enter at session start |
 
-`--remove` forces removal without prompting and may discard uncommitted
-changes; a branch that still holds work is kept. Declining a confirmation
-(entering an outside path, exiting a worktree with work) is reported as normal
-feedback, not an error.
+Exit asks whether to keep or remove, and `worktree.onExit` answers without
+asking: a clean worktree this session created is removed, one holding work or
+entered by path asks, and only a worktree with no work loses its branch. There
+are no flags to disagree with either. Declining a confirmation (entering an
+outside path, exiting a worktree with work) is reported as normal feedback, not
+an error. An argument a subcommand does not take prints the usage line instead of
+being ignored.
 
-`/worktree status` (and `list_worktrees`) reports the active worktree, any
+`list_worktrees` (and a headless `/worktree`) reports the active worktree, any
 override that is not re-rooted, what isolation does not cover, and the managed
 worktrees:
 
@@ -261,7 +289,7 @@ use, falling back to directory mtime for a worktree with no record.
 | Registration | The default export calls `registerWorktree`: root-tool overrides, the `--worktree` flag, lifecycle listeners, model tools, and the `/worktree` command. Nothing long-lived starts at load. |
 | Tools | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees` via `registerTool`. All `executionMode: "sequential"`. Annotations: `enter_worktree` destructive + open-world; `exit_worktree`/`prune_worktrees` destructive; `list_worktrees` read-only. No `outputSchema`; structured state is returned in tool-result `details` — `exit_worktree` carries `{ state, removed, handoff }`, where `handoff` is `{ branch, base, ahead, merged }`. |
 | Built-in overrides | `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` are re-registered under the same names with `defaultActive: false`; each spreads the built-in definition and replaces only `execute`. `skipOverrides` is applied at load time. `powershell` is deliberately not overridden: it cannot be re-rooted without a guard, so the `tool_call` handler refuses it (see `guard.blockPowershell`). |
-| Commands | `/worktree` via `registerCommand`, with argument completions for the subcommands and exit flags. |
+| Commands | `/worktree` via `registerCommand`, with argument completions for `enter`, `exit`, and `prune`. The bare command mounts `screen.ts` in a terminal and prints the status text otherwise; `enter`/`exit`/`prune` refuse while plan mode is read-only. |
 | Flags | `--worktree` via `registerFlag`. |
 | Events | `session_start` (bind inherited env, restore or refuse recorded state, read the flag), `session_shutdown` (release the lock, clear status), `before_agent_start` (set the prompt cwd and worktree section), `tool_call` (guard file tools and `bash`, refuse `powershell`, and count a command it lets through unverified). |
 | State | The binding is a custom session entry (`worktree`) written with `pi.appendEntry` and rebuilt from `ctx.sessionManager.getBranch()` on `session_start`. `.pi/worktrees/index.json` is a disposable managed-record cache, reconciled against `git worktree list`. Child processes inherit `PI_WORKTREE_*` env. |
@@ -291,6 +319,11 @@ use, falling back to directory mtime for a worktree with no record.
   provenance and usage in a disposable index. A *Binding* is this session's
   active root, a session entry that drives `getRoot()` and is replayable on the
   branch.
+- **One snapshot, two surfaces.** `worktreeSnapshot` reads the active binding, the
+gaps, and every managed worktree once; `formatWorktreeStatus` renders it as text
+and `screen.ts` renders the same rows as the list. A tool result and the screen
+that disagree about a worktree would be a second source of truth, so there is
+one read and two renderings.
 - **Mutable root in one place.** Pi loads one extension factory per runtime, so
   `runtime.ts` owns the single active worktree, the config cache, and the
   process-environment hook; lifecycle, tools, and commands stay stateless
@@ -327,12 +360,13 @@ use, falling back to directory mtime for a worktree with no record.
 | `enter.ts` / `exit.ts` / `prune.ts` | The lifecycle phases |
 | `handoff.ts` | The `Handoff:` block an exit leaves: the branch's lead, whether the base contains it, and the merge or PR command. |
 | `tools.ts` / `commands.ts` | Model tools / slash commands |
+| `screen.ts` | The `/worktree` list screen: rows, keys, detail pane, and verbs |
 | `root-tools.ts` | Load-time built-in overrides bound to the active root |
 | `git.ts` | Git plumbing (shared runner + read helpers) |
 | `guard.ts` | Path, shell, and git-redirect isolation checks, plus the `powershell` refusal |
 | `gaps.ts` | The isolation gaps a session carries, and how they read (pure) |
 | `include.ts` | `.worktreeinclude` matcher and copy |
-| `config.ts` / `state.ts` / `status.ts` | Config, session entry shape, status text |
+| `config.ts` / `state.ts` / `status.ts` | Config, session entry shape, status text and the shared snapshot |
 | `registry.ts` | Disposable managed-worktree index + derived status |
 
 ## Testing
@@ -344,6 +378,8 @@ bun run test:watch
 ```
 
 The suite covers the pure logic (`include.ts` gitignore matcher, `guard.ts` path
-and command checks, `parsePrReference`) and drives the extension end-to-end
-against real temporary git repositories through a mocked `pi` API: enter/exit,
-isolation guards, borrowed worktrees, prune, and inactive-override reporting.
+and command checks, `parsePrReference`), drives the `/worktree` screen against a
+snapshot (`ui.test.ts`: rows, marks, verbs, and width bounds), and drives the
+extension end-to-end against real temporary git repositories through a mocked
+`pi` API: enter/exit, isolation guards, borrowed worktrees, prune, and
+inactive-override reporting.

package/extensions/worktree/commands.ts

@@ -1,22 +1,33 @@
 /**
  * Slash commands for the worktree extension.
  *
- * One `/worktree` command keeps the surface small and discoverable:
- *   /worktree                     status + list managed worktrees
- *   /worktree enter [name]        create or enter a worktree (name may be a PR/MR ref)
- *   /worktree exit [--keep|--remove]
+ * One `/worktree` command keeps the surface small: the bare command is the
+ * worktree screen (the status text when the session is not a terminal), and three
+ * verbs do the lifecycle.
+ *
+ *   /worktree                     the worktree screen
+ *   /worktree enter [name]        create or re-enter a worktree (name may be a PR/MR ref)
+ *   /worktree exit                leave; worktree.onExit and the prompt decide the fate
  *   /worktree prune               remove clean, unused, old managed worktrees
+ *
+ * There are no flags: the exit prompt already offers keep or remove and the
+ * config sets the default, so a flag could only disagree with one of the two.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "../../lib/errors.ts";
+import { isPlanModeEnabled } from "../../lib/plan-state.ts";
+import { withRailsSuppressed } from "../../lib/rails.ts";
 import {
 	enterWorktree,
 	exitWorktree,
+	formatWorktreeStatus,
 	isWorktreeCancelled,
 	pruneWorktrees,
 	worktreeLabel,
-	worktreeStatus,
+	worktreeSnapshot,
 } from "./lifecycle.ts";
+import { type WorktreeAction, WorktreeListComponent } from "./screen.ts";
 
 interface Completion {
 	value: string;
@@ -25,83 +36,116 @@ interface Completion {
 }
 
 const SUBCOMMANDS: Completion[] = [
-	{ value: "status", label: "status", description: "Show the current worktree and list managed worktrees" },
 	{ value: "enter", label: "enter", description: "Create or enter a worktree: enter [name]" },
-	{ value: "exit", label: "exit", description: "Return to the main checkout: exit [--keep|--remove]" },
+	{ value: "exit", label: "exit", description: "Return to the main checkout" },
 	{ value: "prune", label: "prune", description: "Remove clean, unused managed worktrees older than pruneAfterDays" },
 ];
 
-const EXIT_FLAGS: Completion[] = [
-	{ value: "--keep", label: "--keep", description: "Keep the worktree on exit" },
-	{
-		value: "--remove",
-		label: "--remove",
-		description: "Force removal without prompting (may discard uncommitted changes)",
-	},
-];
+const USAGE = "Usage: /worktree [enter [name]|exit|prune]";
+
+/** Refuse a lifecycle change while plan mode is read-only, as `/check` does. */
+function refuseInPlanMode(ctx: ExtensionContext): boolean {
+	if (!isPlanModeEnabled(ctx.sessionManager.getBranch())) return false;
+	ctx.ui.notify("Plan mode is read-only. Approve the plan before changing worktrees.", "warning");
+	return true;
+}
+
+async function runEnter(pi: ExtensionAPI, ctx: ExtensionContext, name: string | undefined): Promise<void> {
+	if (refuseInPlanMode(ctx)) return;
+	try {
+		const { state } = await enterWorktree(pi, ctx, { name });
+		ctx.ui.notify(`Entered worktree ${worktreeLabel(state)}\n${state.path}`, "info");
+	} catch (error) {
+		if (isWorktreeCancelled(error)) {
+			ctx.ui.notify(messageOf(error), "info");
+			return;
+		}
+		ctx.ui.notify(`Enter failed: ${messageOf(error)}`, "error");
+	}
+}
+
+async function runExit(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+	if (refuseInPlanMode(ctx)) return;
+	try {
+		const result = await exitWorktree(pi, ctx, {});
+		ctx.ui.notify(result.output, "info");
+	} catch (error) {
+		if (isWorktreeCancelled(error)) {
+			ctx.ui.notify(messageOf(error), "info");
+			return;
+		}
+		ctx.ui.notify(`Exit failed: ${messageOf(error)}`, "error");
+	}
+}
 
-const USAGE = "Usage: /worktree [status|enter [name]|exit [--keep|--remove]|prune]";
+async function runPrune(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+	if (refuseInPlanMode(ctx)) return;
+	ctx.ui.notify(await pruneWorktrees(pi, ctx), "info");
+}
+
+/** The bare command: the list screen in a terminal, the status text elsewhere. */
+async function showWorktrees(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+	const snapshot = await worktreeSnapshot(pi, ctx);
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(formatWorktreeStatus(snapshot), "info");
+		return;
+	}
+	// The screen closes before an enter or exit runs: both change the session
+	// binding, and `exitWorktree` asks through `ctx.ui.select`, which cannot nest
+	// inside a mounted screen. Prune runs in place, so its verb stays on the screen.
+	const action = await withRailsSuppressed(pi, () =>
+		ctx.ui.custom<WorktreeAction | undefined>((tui, theme, _keybindings, done) => {
+			return new WorktreeListComponent({
+				snapshot,
+				theme,
+				requestRender: () => tui.requestRender(),
+				onDone: (next) => done(next),
+				reload: () => worktreeSnapshot(pi, ctx),
+				prune: () => pruneWorktrees(pi, ctx),
+				readOnly: isPlanModeEnabled(ctx.sessionManager.getBranch()),
+				viewportRowsSource: () => tui.terminal?.rows,
+			});
+		}),
+	);
+	if (!action) return;
+	if (action.kind === "exit") await runExit(pi, ctx);
+	else await runEnter(pi, ctx, action.name);
+}
 
 export function registerCommands(pi: ExtensionAPI): void {
 	pi.registerCommand("worktree", {
-		description: "Manage git worktrees: /worktree [status|enter|exit|prune]",
+		description: "Manage git worktrees: the worktree screen, or enter, exit, and prune",
 		getArgumentCompletions: (prefix) => {
-			const [action = "", argument, ...rest] = prefix.trimStart().split(/\s+/);
-			if (rest.length > 0) return null;
+			const text = prefix.trimStart();
+			if (text.includes(" ")) return null;
+			const items = SUBCOMMANDS.filter((item) => item.value.startsWith(text));
+			return items.length > 0 ? items.map((item) => ({ ...item, value: `${item.value} ` })) : null;
+		},
+		handler: async (args, ctx) => {
+			const [sub = "", ...rest] = args.trim().split(/\s+/).filter(Boolean);
 
-			if (argument === undefined) {
-				const items = SUBCOMMANDS.filter((item) => item.value.startsWith(action));
-				return items.length > 0 ? items.map((item) => ({ ...item, value: `${item.value} ` })) : null;
+			if (sub === "") {
+				await showWorktrees(pi, ctx);
+				return;
 			}
-
-			if (action === "exit") {
-				const flags = EXIT_FLAGS.filter((item) => item.value.startsWith(argument));
-				return flags.length > 0 ? flags : null;
+			// Only `enter` takes an argument. Anything else is a typo, and a typo that
+			// is silently ignored is how a command does something the user did not ask for.
+			const allowed = sub === "enter" ? 1 : 0;
+			if (rest.length > allowed) {
+				ctx.ui.notify(`Unexpected argument "${rest[allowed]}".\n${USAGE}`, "error");
+				return;
 			}
 
-			return null;
-		},
-		handler: async (args, ctx) => {
-			const [sub = "status", ...rest] = args.trim().split(/\s+/).filter(Boolean);
-
 			switch (sub) {
-				case "status":
-					ctx.ui.notify(await worktreeStatus(pi, ctx), "info");
+				case "enter":
+					await runEnter(pi, ctx, rest[0]);
 					return;
-
-				case "enter": {
-					try {
-						const { state } = await enterWorktree(pi, ctx, { name: rest[0] });
-						ctx.ui.notify(`Entered worktree ${worktreeLabel(state)}\n${state.path}`, "info");
-					} catch (error) {
-						if (isWorktreeCancelled(error)) {
-							ctx.ui.notify(error.message, "info");
-							return;
-						}
-						ctx.ui.notify(`Enter failed: ${error instanceof Error ? error.message : String(error)}`, "error");
-					}
-					return;
-				}
-
-				case "exit": {
-					const remove = rest.includes("--remove") ? true : rest.includes("--keep") ? false : undefined;
-					try {
-						const result = await exitWorktree(pi, ctx, { remove });
-						ctx.ui.notify(result.output, "info");
-					} catch (error) {
-						if (isWorktreeCancelled(error)) {
-							ctx.ui.notify(error.message, "info");
-							return;
-						}
-						ctx.ui.notify(`Exit failed: ${error instanceof Error ? error.message : String(error)}`, "error");
-					}
+				case "exit":
+					await runExit(pi, ctx);
 					return;
-				}
-
 				case "prune":
-					ctx.ui.notify(await pruneWorktrees(pi, ctx), "info");
+					await runPrune(pi, ctx);
 					return;
-
 				default:
 					ctx.ui.notify(`Unknown worktree subcommand "${sub}".\n${USAGE}`, "error");
 			}

package/extensions/worktree/enter.ts

@@ -110,7 +110,7 @@ export async function enterWorktree(
 	}
 	if (current) {
 		throw new Error(
-			`Already working in a worktree (${worktreeLabel(current)}). Call exit_worktree before entering another.`,
+			`Already working in a worktree (${worktreeLabel(current)}). Run /worktree exit, or call exit_worktree, before entering another.`,
 		);
 	}
 

package/extensions/worktree/exit.ts

@@ -16,6 +16,7 @@ import {
 	lockWorktree,
 	refExists,
 	unlockWorktree,
+	worktreePath,
 	worktreeRemove,
 } from "./git.ts";
 import { handoffLines, type Handoff } from "./handoff.ts";
@@ -163,7 +164,16 @@ export async function exitWorktree(
 		}
 	} else {
 		lines.push(`Kept worktree ${state.path}`);
-		if (state.branch) lines.push(`Re-enter with enter_worktree (path: ${state.path})`);
+		if (state.branch) {
+			// Name entry only reaches a managed worktree; a path the user pointed at is
+			// re-entered through the tool.
+			const label = worktreeLabel(state);
+			lines.push(
+				worktreePath(state.repoRoot, config, label) === state.path
+					? `Re-enter with /worktree enter ${label}`
+					: `Re-enter with enter_worktree (path: ${state.path}); /worktree enter only manages ${config.dir}`,
+			);
+		}
 		touchRecord(state.repoRoot, config, state.path);
 	}
 

package/extensions/worktree/lifecycle.ts

@@ -11,4 +11,12 @@ export { enterWorktree, type EnterOptions } from "./enter.ts";
 export { exitWorktree, type ExitOptions } from "./exit.ts";
 export { pruneWorktrees } from "./prune.ts";
 export { findInactiveOverrides } from "./root-tools.ts";
-export { refusalMessage, stateSummary, worktreeFacts, worktreeLabel, worktreeStatus } from "./status.ts";
+export {
+	formatWorktreeStatus,
+	refusalMessage,
+	stateSummary,
+	worktreeFacts,
+	worktreeLabel,
+	worktreeSnapshot,
+	worktreeStatus,
+} from "./status.ts";

package/extensions/worktree/screen.ts

@@ -0,0 +1,263 @@
+/**
+ * The `/worktree` list screen: one row per managed worktree, the active one
+ * marked, with a detail pane and three verbs.
+ *
+ * The frame, navigation, y/N confirmation, and pane come from the shared
+ * `DockListScreen`, so this module owns only the worktree vocabulary. Rows come
+ * from the same `worktreeSnapshot` the text status renders, so the screen and the
+ * `list_worktrees` tool cannot disagree about a worktree.
+ *
+ * Every verb but `p` closes the screen and hands the action back to the command:
+ * entering and exiting change the session binding and `exitWorktree` asks through
+ * `ctx.ui.select`, which cannot nest inside a mount. `p` never prompts, so it
+ * runs in place and refreshes the rows.
+ */
+
+import { basename } from "node:path";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "../../lib/errors.ts";
+import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { DockListScreen, type DetailContents } from "../../lib/tui/dock-screen.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
+import { statusRow } from "../../lib/tui/rows.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
+import { gapLines } from "./gaps.ts";
+import { handoffLines } from "./handoff.ts";
+import type { CheckoutStatus } from "./registry.ts";
+import { relativeDay, statusMarks, type WorktreeSnapshot, worktreeLabel } from "./status.ts";
+
+/** What a verb asks the command to do once the screen is gone. */
+export type WorktreeAction = { kind: "enter"; name: string } | { kind: "exit" };
+
+/** One row: a managed worktree, or the active one when this session does not manage it. */
+export interface WorktreeRow {
+	/** Canonical path, and the row's stable id. */
+	path: string;
+	/** Basename of the path: the name `enter` takes back. */
+	name: string;
+	branch: string | undefined;
+	/** Whether this row is the session's active worktree. */
+	current: boolean;
+	/** What git says about it; absent for a worktree entered by path. */
+	status: CheckoutStatus | undefined;
+}
+
+/** The rows for a snapshot, in git's order, with the active worktree always present. */
+export function worktreeRows(snapshot: WorktreeSnapshot): WorktreeRow[] {
+	const rows: WorktreeRow[] = snapshot.managed.map((item) => ({
+		path: item.entry.path,
+		name: basename(item.entry.path),
+		branch: item.entry.branch,
+		current: snapshot.active?.path === item.entry.path,
+		status: item.status,
+	}));
+	const active = snapshot.active;
+	// A worktree entered by path is not in the managed list, but a reader looking
+	// for "where am I" must still see it.
+	if (active && !rows.some((row) => row.path === active.path)) {
+		rows.unshift({
+			path: active.path,
+			name: worktreeLabel(active),
+			branch: active.branch,
+			current: true,
+			status: undefined,
+		});
+	}
+	return rows;
+}
+
+/** The glyph and its role: a missing checkout is the error, dirty work the warning. */
+function rowGlyph(status: CheckoutStatus | undefined): { char: string; role: TuiRole } {
+	if (!status) return { char: GLYPHS.worktree, role: "info" };
+	if (status.state === "missing") return { char: GLYPHS.cross, role: "bad" };
+	if (status.state === "dirty") return { char: GLYPHS.warn, role: "warn" };
+	if (status.merged) return { char: GLYPHS.check, role: "ok" };
+	return { char: GLYPHS.branch, role: "info" };
+}
+
+/** The row's right-hand text: its marks, or `clean` when it has none. */
+function rowMarks(row: WorktreeRow): string {
+	const marks = row.status ? statusMarks(row.status, row.current) : ["current"];
+	if (marks.length === 0) marks.push("clean");
+	return marks.join("  ");
+}
+
+export interface WorktreeScreenOptions {
+	/** The rows to open with; the command has already read them. */
+	snapshot: WorktreeSnapshot;
+	theme: Theme;
+	requestRender(): void;
+	/** Close the screen; `undefined` when the user only closed it. */
+	onDone(action: WorktreeAction | undefined): void;
+	/** Read the rows again after a verb changed them. */
+	reload(): Promise<WorktreeSnapshot>;
+	/** Run a prune in place and return its report. */
+	prune(): Promise<string>;
+	/** Plan mode: the screen still shows the list, but no verb may change it. */
+	readOnly: boolean;
+	viewportRowsSource?: ViewportRowsSource;
+}
+
+/** The `/worktree` screen. */
+export class WorktreeListComponent extends DockListScreen<WorktreeRow> {
+	private view: WorktreeSnapshot;
+	private pruning = false;
+
+	constructor(private readonly deps: WorktreeScreenOptions) {
+		super({
+			theme: deps.theme,
+			title: "Worktrees",
+			detailTitle: "Worktree",
+			emptyList: "No managed worktrees. /worktree enter <name> creates one.",
+			emptyDetail: "Nothing recorded for this worktree.",
+			requestRender: deps.requestRender,
+			onClose: () => deps.onDone(undefined),
+			viewportRowsSource: deps.viewportRowsSource,
+		});
+		this.view = deps.snapshot;
+	}
+
+	protected rows(): readonly WorktreeRow[] {
+		return worktreeRows(this.view);
+	}
+
+	protected idOf(row: WorktreeRow): string {
+		return row.path;
+	}
+
+	protected rowLine(row: WorktreeRow, width: number, selected: boolean): string {
+		const glyph = rowGlyph(row.status);
+		return statusRow(this.theme, width, {
+			selected,
+			glyph: glyph.char,
+			glyphRole: glyph.role,
+			label: row.name,
+			labelRole: selected ? "accent" : "label",
+			trailing: rowMarks(row),
+			trailingRole: row.current ? "accent" : "faint",
+		});
+	}
+
+	protected detailBlock(row: WorktreeRow): string[] {
+		const lines = [`${row.path}  ${row.branch ?? "(detached)"}`];
+		const active = this.view.active;
+		// The gaps are the same rules `/worktree` status and `doctor` report: a gap
+		// the user cannot see is a gap they cannot weigh.
+		if (row.current && active) {
+			lines.push(`base: ${active.baseRef} (${active.baseRefMode})    main: ${active.repoRoot}`);
+			if (this.view.gaps.length > 0) lines.push("Not isolated:", ...gapLines(this.view.gaps));
+		}
+		return lines;
+	}
+
+	protected summaryCells(rows: readonly WorktreeRow[]): string[] {
+		const cells = [paint(this.theme, "meta", `${rows.length} worktree${rows.length === 1 ? "" : "s"}`)];
+		const dirty = rows.filter((row) => row.status?.state === "dirty").length;
+		if (dirty > 0) cells.push(paint(this.theme, "warn", `${dirty} dirty`));
+		const ahead = rows.filter((row) => (row.status?.ahead ?? 0) > 0).length;
+		if (ahead > 0) cells.push(paint(this.theme, "accent", `${ahead} ahead`));
+		const inactive = this.view.inactiveOverrides;
+		if (inactive.length > 0) cells.push(paint(this.theme, "warn", `not isolated: ${inactive.join(", ")}`));
+		return cells;
+	}
+
+	protected listHints(): ScreenHint[] {
+		return [
+			"Esc close",
+			"↑/↓ or j/k select",
+			{ text: "Enter or l detail", color: "accent" },
+			{ text: "e enter", color: "accent" },
+			{ text: "x exit", color: "warning" },
+			{ text: "p prune", color: "warning" },
+		];
+	}
+
+	protected detailHints(): ScreenHint[] {
+		return ["Esc back", "↑/↓ scroll", "g/G ends"];
+	}
+
+	protected detailFor(row: WorktreeRow): DetailContents {
+		const lines = [`path    ${row.path}`, `branch  ${row.branch ?? "(detached)"}`];
+		const status = row.status;
+		if (!status) {
+			lines.push("state   entered by path; this session does not manage it");
+		} else {
+			if (status.head) lines.push(`head    ${status.head.slice(0, 7)}`);
+			const bits = [status.state === "dirty" ? `dirty (${status.changed} changed)` : "clean"];
+			if (status.ahead > 0) bits.push(`${status.ahead} ahead`);
+			if (status.behind > 0) bits.push(`${status.behind} behind`);
+			if (status.merged) bits.push("merged");
+			lines.push(`state   ${bits.join(", ")}`);
+			if (status.locked) {
+				lines.push(`lock    ${status.staleLock ? "stale (owner is gone)" : "held by a live session"}`);
+			}
+			if (status.lastUsedAt) lines.push(`used    ${relativeDay(status.lastUsedAt)}`);
+			// The handoff is read, not performed: a merge lands in the main checkout.
+			if (status.ahead > 0 && row.branch) {
+				lines.push(
+					"",
+					...handoffLines({
+						branch: row.branch,
+						base: this.view.baseBranch ?? null,
+						ahead: status.ahead,
+						merged: status.merged,
+					}),
+				);
+			}
+		}
+		return { title: row.name, lines, subtitle: row.branch ?? row.path };
+	}
+
+	protected handleVerb(key: string, row: WorktreeRow | undefined): void {
+		if (key !== "e" && key !== "x" && key !== "p") return;
+		if (this.deps.readOnly) {
+			this.notify("Plan mode is read-only. Approve the plan before changing worktrees.");
+			return;
+		}
+		if (key === "e") {
+			if (!row) {
+				this.notify("No worktree to enter.");
+				return;
+			}
+			if (row.current) {
+				this.notify(`${row.name} is already the current worktree.`);
+				return;
+			}
+			if (this.view.active) {
+				this.notify(`Still in ${worktreeLabel(this.view.active)}; press x to exit first.`);
+				return;
+			}
+			this.deps.onDone({ kind: "enter", name: row.name });
+			return;
+		}
+		if (key === "x") {
+			if (!this.view.active) {
+				this.notify("Not in a worktree.");
+				return;
+			}
+			this.deps.onDone({ kind: "exit" });
+			return;
+		}
+		if (this.pruning) {
+			this.notify("A prune is already running.");
+			return;
+		}
+		this.pruning = true;
+		this.notify("Pruning…");
+		void this.pruneInPlace();
+	}
+
+	/** Prune is the one verb that never prompts, so it runs without closing the screen. */
+	private async pruneInPlace(): Promise<void> {
+		try {
+			const report = await this.deps.prune();
+			this.view = await this.deps.reload();
+			this.resort();
+			this.notify(report.split("\n")[0] ?? "Pruned.");
+		} catch (error) {
+			this.notify(`Prune failed: ${messageOf(error)}`);
+		} finally {
+			this.pruning = false;
+		}
+	}
+}