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

package/extensions/wechat/qrcode.ts

@@ -2,20 +2,20 @@
  * Rendering a QR string as terminal lines.
  *
  * Uses the `qrcode` package only for the module matrix, then draws Unicode
- * half-blocks so two matrix rows share one terminal line. No ANSI is emitted;
- * the login screen decides colours, and the width is the matrix width plus a
- * quiet zone.
+ * half-blocks so two matrix rows share one terminal line. The package loads on
+ * the first QR, not when the extension registers: a session that never logs in
+ * pays nothing for it. No ANSI is emitted; the login screen decides colours, and
+ * the width is the matrix width plus a quiet zone.
  */
 
-import QRCode from "qrcode";
-
 interface QrMatrix {
 	size: number;
 	get(row: number, col: number): boolean;
 }
 
-/** Build the module matrix for `text`. */
-export function qrMatrix(text: string): QrMatrix {
+/** Build the module matrix for `text`, loading `qrcode` on first use. */
+export async function qrMatrix(text: string): Promise<QrMatrix> {
+	const { default: QRCode } = await import("qrcode");
 	const qr = QRCode.create(text, { errorCorrectionLevel: "M" });
 	return qr.modules as unknown as QrMatrix;
 }
@@ -25,9 +25,9 @@ export function qrMatrix(text: string): QrMatrix {
  * columns wide (half-block characters are single width), so a caller can test
  * `qrLines(text)[0].length` against the terminal width.
  */
-export function qrLines(text: string, options: { quiet?: number } = {}): string[] {
+export async function qrLines(text: string, options: { quiet?: number } = {}): Promise<string[]> {
 	const quiet = Math.max(0, options.quiet ?? 2);
-	const matrix = qrMatrix(text);
+	const matrix = await qrMatrix(text);
 	const size = matrix.size;
 	const isDark = (row: number, col: number): boolean =>
 		row >= 0 && col >= 0 && row < size && col < size && matrix.get(row, col);

package/extensions/wechat/slash.ts

@@ -21,6 +21,8 @@ export interface SlashPeerState {
 	status: "idle" | "queued" | "running";
 	queued: number;
 	runningMs?: number;
+	/** The title of a dialog waiting on the sender, when one is. */
+	prompt?: string;
 }
 
 /** The session controls an action may invoke; every one acts on the sender. */
@@ -152,6 +154,18 @@ export const SLASH_COMMANDS: readonly SlashCommand[] = [
 		kind: "action",
 		run: async (ctx) => {
 			const state = ctx.session.status();
+			// A waiting dialog is the whole status while it waits: the turn is blocked on
+			// it, so "working, 12s" would hide the one thing the peer can act on.
+			if (state.prompt !== undefined) {
+				await ctx.reply(
+					localized(
+						ctx.language,
+						`正在等你回答「${state.prompt}」，回复「取消」可跳过。`,
+						`Waiting for your answer: “${state.prompt}” — reply “cancel” to skip.`,
+					),
+				);
+				return;
+			}
 			if (state.status !== "running") {
 				await ctx.reply(
 					state.queued > 0

package/extensions/wechat/status-screen.ts

@@ -12,7 +12,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
 import { formatDuration, sanitizeLine } from "../../lib/format.ts";
-import { screenHint, type ScreenHint } from "../../lib/tui/chrome.ts";
+import { screenFooter, screenHint, type ScreenHint } from "../../lib/tui/chrome.ts";
 import { clip } from "../../lib/tui/columns.ts";
 import { formatRange, IdCursor, isCloseKey, navIntent } from "../../lib/tui/cursor.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
@@ -441,7 +441,7 @@ export class StatusScreenComponent implements Component {
 			...statusBody(view, theme, target, selection),
 		];
 		if (this.flash) lines.push("", clip(`  ${paint(theme, "meta", this.flash)}`, target));
-		lines.push("", screenHint(theme, target, this.hints(view)));
+		lines.push(...screenFooter(theme, target, screenHint(theme, target, this.hints(view))));
 		return lines;
 	}
 }

package/extensions/wechat/tools.ts

@@ -11,6 +11,7 @@ import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { failedResult, textResult } from "../../lib/tool-result.ts";
 import { callLine, errorLine, rejectionLine } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import type { Bridge } from "./bridge.ts";
@@ -39,17 +40,8 @@ function sendResult(sent: boolean, error?: string) {
 	const details = error === undefined ? { sent } : { sent, error };
 	const structuredContent: Record<string, JsonValue> = { sent };
 	if (error !== undefined) structuredContent.error = error;
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: sent ? "Sent to the WeChat owner." : `WeChat send failed: ${error ?? "unknown error"}`,
-			},
-		],
-		details,
-		structuredContent,
-		...(sent ? {} : { isError: true as const }),
-	};
+	const text = sent ? "Sent to the WeChat owner." : `WeChat send failed: ${error ?? "unknown error"}`;
+	return sent ? textResult(text, details, structuredContent) : failedResult(text, details, structuredContent);
 }
 
 export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {

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";