@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/extensions/wechat/{inbound.ts → transport/inbound.ts}

@@ -8,12 +8,12 @@
  */
 
 import type { ImageContent } from "@earendil-works/pi-ai";
-import type { BotCredentials, InboundItem } from "./types.ts";
+import type { BotCredentials, InboundItem } from "../types.ts";
 import type { WechatClient } from "./client.ts";
-import type { PeerItem } from "./peer-worker.ts";
-import { messageOf } from "./errors.ts";
+import type { PeerItem } from "../peer/peer-worker.ts";
+import { messageOf } from "../errors.ts";
 import { decodeMediaKey, decryptEcb, saveMedia, sniffImageMime } from "./media.ts";
-import { notice } from "./notices.ts";
+import { notice } from "../text/notices.ts";
 
 /** What the inbound side needs from the bridge; every value is read at call time. */
 export interface InboundDeps {
@@ -84,7 +84,7 @@ export function createInboundAdmission(deps: InboundDeps): InboundAdmission {
 					images.push({
 						type: "image",
 						data: Buffer.from(plain).toString("base64"),
-						mimeType: sniffImageMime(plain),
+						mimeType: sniffImageMime(plain) ?? "image/jpeg",
 					});
 				}
 			} catch (error) {

package/extensions/wechat/{media.ts → transport/media.ts}

@@ -10,8 +10,8 @@
 import { createCipheriv, createDecipheriv } from "node:crypto";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { stripControlChars } from "../../lib/format.ts";
-import type { CDNMedia } from "./types.ts";
+import { stripControlChars } from "../../../lib/format.ts";
+import type { CDNMedia } from "../types.ts";
 
 /** Decode a Weixin media AES key from 32 hex chars or base64 to 16 bytes. */
 export function decodeMediaKey(value: string): Buffer {
@@ -38,8 +38,14 @@ export function aesEcbPaddedSize(plaintextSize: number): number {
 	return Math.ceil((plaintextSize + 1) / 16) * 16;
 }
 
-/** Sniff a common image MIME from magic bytes; defaults to `image/jpeg`. */
-export function sniffImageMime(bytes: Uint8Array): string {
+/**
+ * The MIME a common image's magic bytes name, or `undefined` when they name none.
+ *
+ * `undefined` is what an outbound image send refuses on; the inbound attach path
+ * decides its own fallback, because a peer's photo is worth passing on even when
+ * the header is unfamiliar.
+ */
+export function sniffImageMime(bytes: Uint8Array): string | undefined {
 	if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
 		return "image/png";
 	}
@@ -60,7 +66,7 @@ export function sniffImageMime(bytes: Uint8Array): string {
 	) {
 		return "image/webp";
 	}
-	return "image/jpeg";
+	return undefined;
 }
 
 /** Strip control characters and path separators, cap length, and never empty. */

package/extensions/wechat/transport/outbound.ts

@@ -0,0 +1,142 @@
+/**
+ * Outbound media: encrypt one local file and deliver it as a Weixin attachment.
+ *
+ * The flow mirrors the reference client: read the plaintext, compute its size and
+ * MD5, generate a 16-byte AES key and a file key, request the CDN upload target,
+ * upload the AES-128-ECB ciphertext, then send the item whose media reference
+ * carries the returned download parameter. The upload is one body; the item is a
+ * `type: 4` file or a `type: 2` image, and an image must sniff as one.
+ *
+ * Everything is injected, so it is tested with a fake client and a temp file.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { rejectionOf, type WechatClient } from "./client.ts";
+import { aesEcbPaddedSize, encryptEcb, sanitizeFileName, sniffImageMime, uploadUrlOf } from "./media.ts";
+import type { BotCredentials, CDNMedia } from "../types.ts";
+
+/** `UploadMediaType.FILE` from the protocol. */
+export const UPLOAD_MEDIA_TYPE_FILE = 3;
+
+/** `UploadMediaType.IMAGE` from the protocol. */
+export const UPLOAD_MEDIA_TYPE_IMAGE = 1;
+
+export interface SendLocalFileArgs {
+	client: WechatClient;
+	account: BotCredentials;
+	cdnBaseUrl: string;
+	/** Files larger than this are refused. */
+	maxBytes: number;
+	to: string;
+	contextToken?: string;
+	filePath: string;
+	/** Display name; defaults to the file's base name, sanitized. */
+	fileName?: string;
+	signal?: AbortSignal;
+	/** Random bytes for the AES key and file key; defaults to `crypto.randomBytes`. */
+	random?: (size: number) => Buffer;
+}
+
+/** One encrypted upload, with what both item shapes need to describe it. */
+interface Uploaded {
+	plain: Buffer;
+	/** Plaintext size in bytes, the `len` of a file item. */
+	rawsize: number;
+	/** Padded ciphertext size, the `mid_size` of an image item. */
+	filesize: number;
+	media: CDNMedia;
+	/** The AES key as 32 hex characters, which an image item names itself. */
+	aeskey: string;
+}
+
+/** Encrypt and upload one local file's bytes; `undefined` when it is empty or too big. */
+async function uploadLocal(args: SendLocalFileArgs, mediaType: number, plain: Buffer): Promise<Uploaded | undefined> {
+	if (plain.length === 0 || plain.length > args.maxBytes) return undefined;
+
+	const random = args.random ?? randomBytes;
+	const aesKey = random(16);
+	const filekey = random(16).toString("hex");
+	const rawsize = plain.length;
+	const rawfilemd5 = createHash("md5").update(plain).digest("hex");
+	const filesize = aesEcbPaddedSize(rawsize);
+	const aeskey = aesKey.toString("hex");
+
+	const upload = await args.client.getUploadUrl(
+		args.account,
+		{ filekey, mediaType, toUserId: args.to, rawsize, rawfilemd5, filesize, aeskey },
+		args.signal,
+	);
+
+	const downloadParam = await args.client.uploadCdn(
+		uploadUrlOf(upload, args.cdnBaseUrl, filekey),
+		encryptEcb(plain, aesKey),
+		args.signal,
+	);
+
+	// The reference encodes the hex key string as base64 (not the raw 16 bytes);
+	// the download decoder accepts either.
+	const media: CDNMedia = {
+		encrypt_query_param: downloadParam,
+		aes_key: Buffer.from(aeskey).toString("base64"),
+		encrypt_type: 1,
+	};
+	return { plain, rawsize, filesize, media, aeskey };
+}
+
+/**
+ * Upload and send a local file. Returns true when the message was accepted.
+ * Any failure (unreadable file, size cap, upload rejection) returns false rather
+ * than throwing, so the caller can fall back.
+ */
+export async function sendLocalFile(args: SendLocalFileArgs): Promise<boolean> {
+	try {
+		const uploaded = await uploadLocal(args, UPLOAD_MEDIA_TYPE_FILE, readFileSync(args.filePath));
+		if (!uploaded) return false;
+		const response = await args.client.sendFileMessage(
+			args.account,
+			{
+				to: args.to,
+				fileName: sanitizeFileName(args.fileName ?? basename(args.filePath)),
+				len: String(uploaded.rawsize),
+				media: uploaded.media,
+				contextToken: args.contextToken,
+			},
+			args.signal,
+		);
+		return rejectionOf(response) === undefined;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Upload and send a local image as a picture, not a document.
+ *
+ * A file whose bytes sniff as no image is refused before the upload, so this path
+ * cannot become a general file sender. Everything else matches
+ * {@link sendLocalFile}: false on any failure, for the caller to fall back on.
+ */
+export async function sendLocalImage(args: SendLocalFileArgs): Promise<boolean> {
+	try {
+		const plain = readFileSync(args.filePath);
+		if (sniffImageMime(plain) === undefined) return false;
+		const uploaded = await uploadLocal(args, UPLOAD_MEDIA_TYPE_IMAGE, plain);
+		if (!uploaded) return false;
+		const response = await args.client.sendImageMessage(
+			args.account,
+			{
+				to: args.to,
+				media: uploaded.media,
+				midSize: uploaded.filesize,
+				aeskey: uploaded.aeskey,
+				contextToken: args.contextToken,
+			},
+			args.signal,
+		);
+		return rejectionOf(response) === undefined;
+	} catch {
+		return false;
+	}
+}

package/extensions/wechat/{poll.ts → transport/poll.ts}

@@ -8,10 +8,10 @@
  * stops the loop.
  */
 
-import type { BotCredentials, WeixinMessage } from "./types.ts";
+import type { BotCredentials, WeixinMessage } from "../types.ts";
 import { isSessionExpired, rejectionOf, type WechatClient } from "./client.ts";
-import { messageOf } from "./errors.ts";
-import { defaultTimer } from "./timer.ts";
+import { messageOf } from "../errors.ts";
+import { defaultTimer } from "../timer.ts";
 
 const BACKOFF_MS = 2000;
 /** Poll watchdog when the server has not told us its long-poll hold yet. */

package/extensions/wechat/types.ts

@@ -6,7 +6,7 @@
  * the persisted credentials, cursor, and peer state.
  */
 
-import type { PeerLanguage } from "./format.ts";
+import type { PeerLanguage } from "./text/format.ts";
 
 /** One content item inside a message (`type` 1 = text). */
 export interface MessageItem {
@@ -68,6 +68,15 @@ export interface WeixinMessage {
 	message_id?: number;
 	from_user_id?: string;
 	to_user_id?: string;
+	/**
+	 * A group message's room, declared by the protocol as "when applicable".
+	 *
+	 * Nothing routes on it: the bridge keys a conversation by sender. The poll
+	 * probe prints it so a probe can tell whether rooms are delivered at all.
+	 */
+	group_id?: string;
+	/** The conversation the message belongs to, when the protocol supplies one. */
+	session_id?: string;
 	message_type?: number;
 	message_state?: number;
 	item_list?: MessageItem[];

package/extensions/wechat/{login-screen.ts → view/login-screen.ts}

@@ -8,10 +8,10 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, visibleWidth } from "@earendil-works/pi-tui";
-import { screenFooter, screenHint } from "../../lib/tui/chrome.ts";
-import { clip } from "../../lib/tui/columns.ts";
-import { isCloseKey } from "../../lib/tui/cursor.ts";
-import { titleRule } from "../../lib/tui/rules.ts";
+import { screenFooter, screenHint } from "../../../lib/tui/chrome.ts";
+import { clip } from "../../../lib/tui/columns.ts";
+import { isCloseKey } from "../../../lib/tui/cursor.ts";
+import { titleRule } from "../../../lib/tui/rules.ts";
 
 export interface LoginViewState {
 	/** Raw `get_qrcode_status` value, or `wait` before the first poll. */

package/extensions/wechat/{status-screen.ts → view/status-screen.ts}

@@ -11,17 +11,17 @@
 
 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 { 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";
-import { keyValueRow, listRow } from "../../lib/tui/rows.ts";
-import { titleRule } from "../../lib/tui/rules.ts";
-import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
-import type { BridgeStatus } from "./bridge.ts";
-import { peerLabel } from "./format.ts";
-import type { BotCredentials } from "./types.ts";
+import { formatDuration, sanitizeLine } from "../../../lib/format.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";
+import { keyValueRow, listRow } from "../../../lib/tui/rows.ts";
+import { titleRule } from "../../../lib/tui/rules.ts";
+import { paint, type TuiRole } from "../../../lib/tui/tokens.ts";
+import type { BridgeStatus } from "../bridge.ts";
+import { peerLabel } from "../text/format.ts";
+import type { BotCredentials } from "../types.ts";
 
 /** User-facing connection word; the internal `BridgeState` stays running/stopped. */
 export type StatusConnection = "open" | "expired" | "paused" | "closed";
@@ -48,8 +48,8 @@ export interface StatusView {
 	refusedPeers: string[];
 	mediaDropped: number;
 	promptPending: boolean;
-	/** The waiting prompt's peer, title, and start time. */
-	prompt?: { peer: string; title: string; startedAt: number };
+	/** Every waiting prompt, one per peer that was asked something. */
+	prompts: Array<{ peer: string; title: string; startedAt: number }>;
 	/** The clock the view was built with, for the prompt age. */
 	now?: number;
 }
@@ -96,13 +96,11 @@ export function statusView(
 		refusedPeers: status?.refusedPeers ?? [],
 		mediaDropped: status?.mediaDropped ?? 0,
 		promptPending: status?.promptPending ?? false,
-		prompt: status?.prompt
-			? {
-					peer: sanitizeLine(peerLabel(status.prompt.peer)),
-					title: sanitizeLine(status.prompt.title),
-					startedAt: status.prompt.startedAt,
-				}
-			: undefined,
+		prompts: (status?.prompts ?? []).map((prompt) => ({
+			peer: sanitizeLine(peerLabel(prompt.peer)),
+			title: sanitizeLine(prompt.title),
+			startedAt: prompt.startedAt,
+		})),
 		now,
 	};
 }
@@ -186,9 +184,12 @@ export function statusBody(view: StatusView, theme: Theme, width: number, select
 		lines.push(row(theme, target, "Queued", String(view.queued), "meta"));
 		if (view.refused > 0) lines.push(row(theme, target, "Refused", refusedValue(view), "meta"));
 		if (view.mediaDropped > 0) lines.push(row(theme, target, "Media", `${view.mediaDropped} dropped`, "meta"));
-		if (view.prompt) {
-			const age = formatDuration(Math.max(0, (view.now ?? Date.now()) - view.prompt.startedAt));
-			lines.push(row(theme, target, "Prompt", `${view.prompt.peer} · ${view.prompt.title} · ${age}`, "accent"));
+		if (view.prompts.length > 0) {
+			// One line per peer: with two turns running, two prompts can wait at once.
+			for (const prompt of view.prompts) {
+				const age = formatDuration(Math.max(0, (view.now ?? Date.now()) - prompt.startedAt));
+				lines.push(row(theme, target, "Prompt", `${prompt.peer} · ${prompt.title} · ${age}`, "accent"));
+			}
 		} else if (view.promptPending) {
 			lines.push(row(theme, target, "Prompt", "waiting for a reply", "accent"));
 		}
@@ -257,7 +258,8 @@ export interface StatusActions {
 	/** Start a fresh conversation for the peer; returns the line to flash. */
 	reset(peer: string): string;
 	/** Withdraw the waiting prompt; returns the line to flash. */
-	cancelPrompt(): string;
+	/** Withdraw the focused peer's waiting prompt. */
+	cancelPrompt(peer: string): string;
 	/** Pause or resume polling; async because it settles the poll loop first. */
 	togglePause(): string | Promise<string>;
 }
@@ -360,11 +362,14 @@ export class StatusScreenComponent implements Component {
 			return;
 		}
 		if (data === "c" || data === "C") {
-			if (!view.prompt) {
+			// Cancel the focused peer's own prompt: with two turns running, the other
+			// peer's question is not this operator's to withdraw.
+			const waiting = peer ? view.prompts.find((entry) => entry.peer === peer.label) : undefined;
+			if (!peer || !waiting) {
 				this.setFlash("No prompt waiting.");
 				return;
 			}
-			this.setFlash(this.options.actions?.cancelPrompt() ?? "Prompt cancel is unavailable.");
+			this.setFlash(this.options.actions?.cancelPrompt(peer.id ?? peer.label) ?? "Prompt cancel is unavailable.");
 			return;
 		}
 		if (data === "s" || data === "S" || data === "d" || data === "D" || data === "h" || data === "H") {

package/extensions/worktree/commands.ts

@@ -16,6 +16,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { messageOf } from "../../lib/errors.ts";
+import { planModeRefusal } from "../../lib/plan-entry.ts";
 import { isPlanModeEnabled } from "../../lib/plan-state.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import {
@@ -24,7 +25,7 @@ import {
 	formatWorktreeStatus,
 	isWorktreeCancelled,
 	pruneWorktrees,
-	worktreeLabel,
+	enteredWorktree,
 	worktreeSnapshot,
 } from "./lifecycle.ts";
 import { type WorktreeAction, WorktreeListComponent } from "./screen.ts";
@@ -46,36 +47,42 @@ 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");
+	ctx.ui.notify(planModeRefusal("changing worktrees"), "warning");
 	return true;
 }
 
-async function runEnter(pi: ExtensionAPI, ctx: ExtensionContext, name: string | undefined): Promise<void> {
-	if (refuseInPlanMode(ctx)) return;
+/**
+ * Run one lifecycle verb and report it the way a command does.
+ *
+ * Enter and exit differ in what they call and in the sentence a success prints, never in
+ * how a refusal is reported: a cancellation is the choice the user just made and reads as
+ * info, and everything else is a failure that names the verb that failed.
+ */
+async function reportLifecycle(ctx: ExtensionContext, verb: string, run: () => Promise<string>): Promise<void> {
 	try {
-		const { state } = await enterWorktree(pi, ctx, { name });
-		ctx.ui.notify(`Entered worktree ${worktreeLabel(state)}\n${state.path}`, "info");
+		ctx.ui.notify(await run(), "info");
 	} catch (error) {
 		if (isWorktreeCancelled(error)) {
 			ctx.ui.notify(messageOf(error), "info");
 			return;
 		}
-		ctx.ui.notify(`Enter failed: ${messageOf(error)}`, "error");
+		ctx.ui.notify(`${verb} failed: ${messageOf(error)}`, "error");
 	}
 }
 
+async function runEnter(pi: ExtensionAPI, ctx: ExtensionContext, name: string | undefined): Promise<void> {
+	if (refuseInPlanMode(ctx)) return;
+	// The path on its own line: a command's answer is read without a tool result beside it,
+	// and "which directory am I in now" is the question entering answers.
+	await reportLifecycle(ctx, "Enter", async () => {
+		const { state } = await enterWorktree(pi, ctx, { name });
+		return `${enteredWorktree(state)}\n${state.path}`;
+	});
+}
+
 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");
-	}
+	await reportLifecycle(ctx, "Exit", async () => (await exitWorktree(pi, ctx, {})).output);
 }
 
 async function runPrune(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {

package/extensions/worktree/exit.ts

@@ -36,13 +36,17 @@ export interface ExitOptions {
  * must not fail because the default branch could not be read.
  */
 async function describeHandoff(pi: ExtensionAPI, state: WorktreeState, recorded: number): Promise<Handoff> {
-	if (!state.branch) return { branch: null, base: null, ahead: recorded, merged: false };
+	// `recorded` is the count `inspectWork` took against the commit the worktree was created
+	// at, read while the directory was still there; without that commit there is no fork
+	// point, and the count is unknown rather than zero.
+	const commits = state.baseCommit ? recorded : undefined;
+	if (!state.branch) return { branch: null, base: null, ahead: recorded, commits, merged: false };
 	try {
 		// `origin/HEAD` names the merge target when the repository has a remote; a
 		// local-only repository has none, and the main checkout's own branch is the
 		// branch a merge would actually land on.
 		const base = (await defaultBranch(pi, state.repoRoot)) ?? (await currentBranch(pi, state.repoRoot)) ?? null;
-		if (!base) return { branch: state.branch, base: null, ahead: recorded, merged: false };
+		if (!base) return { branch: state.branch, base: null, ahead: recorded, commits, merged: false };
 		// Count against the resolved base branch, not the commit recorded at entry:
 		// a worktree branch rebased onto a newer local branch would otherwise report
 		// every commit the base gained since, as its own.
@@ -55,15 +59,17 @@ async function describeHandoff(pi: ExtensionAPI, state: WorktreeState, recorded:
 			: (await refExists(pi, root, `origin/${base}`))
 				? `origin/${base}`
 				: null;
-		if (!ref) return { branch: state.branch, base: null, ahead: recorded, merged: false };
+		if (!ref) return { branch: state.branch, base: null, ahead: recorded, commits, merged: false };
+		const ahead = await commitsAheadOf(pi, root, state.branch, ref);
 		return {
 			branch: state.branch,
 			base,
-			ahead: await commitsAheadOf(pi, root, state.branch, ref),
-			merged: await isBranchMerged(pi, root, state.branch, ref),
+			ahead,
+			commits,
+			merged: ahead === 0 && commits !== 0 && (await isBranchMerged(pi, root, state.branch, ref)),
 		};
 	} catch {
-		return { branch: state.branch, base: null, ahead: recorded, merged: false };
+		return { branch: state.branch, base: null, ahead: recorded, commits, merged: false };
 	}
 }
 

package/extensions/worktree/git.ts

@@ -171,7 +171,19 @@ export async function worktreeExists(pi: ExtensionAPI, dir: string): Promise<boo
 		.some((line) => line.startsWith("worktree ") && realPathOfNearest(line.slice("worktree ".length).trim()) === want);
 }
 
-/** Whether a local branch exists. */
+/**
+ * `rev-list --count` for one range, e.g. `main..HEAD`; 0 when git cannot answer.
+ *
+ * The three counts below are the same command with a different range, and a caller that
+ * reads a count as "no work here" must not have a failed read look like zero work.
+ */
+async function revListCount(pi: ExtensionAPI, dir: string, range: string): Promise<number> {
+	const result = await git(pi, ["rev-list", "--count", range], dir);
+	if (result.code !== 0) return 0;
+	const count = Number.parseInt(result.stdout.trim(), 10);
+	return Number.isFinite(count) ? count : 0;
+}
+
 /**
  * Count of commits on `branch` that `base` does not contain.
  *
@@ -179,10 +191,7 @@ export async function worktreeExists(pi: ExtensionAPI, dir: string): Promise<boo
  * after the worktree may already be gone while its branch refs outlive it.
  */
 export async function commitsAheadOf(pi: ExtensionAPI, dir: string, branch: string, base: string): Promise<number> {
-	const result = await git(pi, ["rev-list", "--count", `${base}..${branch}`], dir);
-	if (result.code !== 0) return 0;
-	const count = Number.parseInt(result.stdout.trim(), 10);
-	return Number.isFinite(count) ? count : 0;
+	return revListCount(pi, dir, `${base}..${branch}`);
 }
 
 /** Whether `ref` resolves here: a branch, a remote-tracking ref, or a tag. */
@@ -190,6 +199,7 @@ export async function refExists(pi: ExtensionAPI, dir: string, ref: string): Pro
 	return (await revParse(createExecRunner(pi), dir, ref)) !== undefined;
 }
 
+/** Whether a local branch exists. */
 export async function branchExists(pi: ExtensionAPI, repoRoot: string, branch: string): Promise<boolean> {
 	const result = await git(pi, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], repoRoot);
 	return result.code === 0;
@@ -257,18 +267,12 @@ export async function statusEntries(pi: ExtensionAPI, dir: string): Promise<stri
 
 /** Count of commits reachable from HEAD but not from `base`. */
 export async function commitsAhead(pi: ExtensionAPI, dir: string, base: string): Promise<number> {
-	const result = await git(pi, ["rev-list", "--count", `${base}..HEAD`], dir);
-	if (result.code !== 0) return 0;
-	const count = Number.parseInt(result.stdout.trim(), 10);
-	return Number.isFinite(count) ? count : 0;
+	return revListCount(pi, dir, `${base}..HEAD`);
 }
 
 /** Count of commits reachable from `base` but not from HEAD. */
 export async function commitsBehind(pi: ExtensionAPI, dir: string, base: string): Promise<number> {
-	const result = await git(pi, ["rev-list", "--count", `HEAD..${base}`], dir);
-	if (result.code !== 0) return 0;
-	const count = Number.parseInt(result.stdout.trim(), 10);
-	return Number.isFinite(count) ? count : 0;
+	return revListCount(pi, dir, `HEAD..${base}`);
 }
 
 /** Whether `branch` is fully contained in `ref` (already merged). */
@@ -283,7 +287,11 @@ export async function mergeBase(pi: ExtensionAPI, dir: string, ref: string): Pro
 	return result.code === 0 ? result.stdout.trim() || undefined : undefined;
 }
 
-export type CheckoutCheck = { ok: true } | { ok: false; reason: "gone" | "unsafe" | "unverified"; detail: string };
+/** Why a checkout is unusable, as `checkCheckout` reports it. */
+export type CheckoutRefusal = { ok: false; reason: "gone" | "unsafe" | "unverified"; detail: string };
+
+/** The verdict on a recorded worktree: usable, or the refusal that says why not. */
+export type CheckoutCheck = { ok: true } | CheckoutRefusal;
 
 /**
  * Verify a directory is a usable, separate checkout before restoring it.