@gavin-hu/my-pi-agent 0.11.2 → 0.11.3

package/extensions/wechat/README.md

@@ -61,7 +61,9 @@ How the `send_wechat` call and its result look in the transcript — the call li
   can drive the agent; `allowedPeers` opts in others. An entry matches either id
   form (`alice` or `alice@im.wechat`), and a refused sender is named in
   `/wechat status` and in one terminal notice, so the id to allowlist can be
-  copied from either.
+  copied from either. `a` on the control screen or `/wechat allow [peer]` writes
+  one entry into the project config; the running bridge picks it up on the next
+  `/reload` or restart, and the confirmation names the file.
 - **Session-bound** — the bridge runs while an account is stored and the Pi
   process is alive; it starts on `session_start`, and `/wechat logout` clears the
   account and stops it. The peer sessions outlive it on disk.
@@ -74,8 +76,11 @@ How the `send_wechat` call and its result look in the transcript — the call li
 | `/wechat login` | QR login; on scan, stores credentials, replaces a running poller, and starts the bridge. |
 | `/wechat new` | Start a fresh *host* session. Peer conversations are independent and survive it; they use an inbound `/new`. |
 | `/wechat status` | The same control screen as a bare `/wechat` (the one-line summary while a peer turn runs). |
+| `/wechat doctor` | Print a read-only health report: connection and token age, last poll and hold, lock holder, per-peer session/queue, recent failures. |
 | `/wechat stop <peer>` | Stop that peer's running turn; reports when nothing was running. |
 | `/wechat reset <peer>` | Start a fresh conversation for that peer; refused while its turn runs. |
+| `/wechat history <peer> [n]` | Print that peer's recent messages (default 10, max 20); read-only, and works without a live session. |
+| `/wechat allow [peer]` | Add a refused sender to `wechat.allowedPeers` in the project `.pi/bytefly.json`, after a confirmation that names the file. Without an argument it offers the refused senders. |
 | `/wechat logout` | Confirm, then clear credentials, drop the bridge, and stop polling. |
 | `/wechat help` | List the subcommands with a line each. |
 
@@ -98,10 +103,15 @@ one-step recovery.
 
 In the TUI, `/wechat` opens a control screen with the account, connection
 state, owner, per-peer conversation rows (what each peer is doing, how long, and
-what is queued behind it), activity counters, and any pending remote prompt. Keys: `l` log in
-or reconnect, `n` start a new session, `o` log out, `r` refresh, and Esc closes.
-The subcommands above are shortcuts for the same actions and the only route
-outside the TUI; an unknown subcommand reports the valid ones.
+what is queued behind it), activity counters, and the waiting remote prompt
+(peer, question, and age).
+`j`/`k` (or the arrows) move the focus over peer rows; `s` stops the focused
+peer's turn and `d` starts a fresh conversation for it, both in place; `h` closes
+the screen and prints that peer's history; `a` closes it and offers the refused
+senders to allow; `c` withdraws the waiting prompt. `l` logs in or reconnects,
+`n` starts a new session, `o` logs out, `r` refreshes, and Esc closes. The
+subcommands above are shortcuts for the same actions and the only route outside
+the TUI; an unknown subcommand reports the valid ones.
 
 A peer turn runs in its own session, but it still owns the bridge, so a `/wechat`
 command typed at the terminal declines while one is running: `status` prints the
@@ -304,6 +314,9 @@ never touches the stored cursor.
 
 ## Troubleshooting
 
+- **First, run `/wechat doctor`.** It prints the connection, token age, last
+  poll, poller lock, per-peer queue/session age, and the last failure, which
+  answers most "why is the bot quiet?" questions in one screen.
 - **`Another Pi session is already polling this WeChat account.`** — one runtime
   owns the account at a time, tracked by `<agent-dir>/wechat/poller.lock`.
   Quit the other `pi` process. A lock left by a process that already exited is
@@ -382,7 +395,7 @@ sessions are in-process).
 
 | Integration point | Detail |
 |---|---|
-| Command | `pi.registerCommand("wechat", …)` — `login`, `new`, `status`, `stop <peer>`, `reset <peer>`, `logout`, `help`; bare `/wechat` opens the control screen. |
+| Command | `pi.registerCommand("wechat", …)` — `login`, `new`, `status`, `doctor`, `stop <peer>`, `reset <peer>`, `history <peer> [n]`, `allow [peer]`, `logout`, `help`; bare `/wechat` opens the control screen. |
 | Tools | `send_wechat` — owner-only proactive text; registered at factory time with `exposure: "direct"`, `executionMode: "sequential"`, `openWorldHint: true`. |
 | Events | `session_start` (record the live context, auto-start the bridge when an account exists); `session_shutdown` (idempotent stop). No host run events: peer turns are not the host session's runs. |
 | Sessions | `openPeerSession` creates one SDK `AgentSession` per peer (`createAgentSession`, `SessionManager.continueRecent` under `<agent-dir>/wechat/sessions/<peer>/`), inheriting the host's model and thinking level. `DefaultResourceLoader` standard discovery minus this bridge (`withoutWechatExtensions`), so a peer session cannot start a second poller, plus a short channel contract appended to the system prompt so the model knows it is answering in a phone chat window. When `peers[<id>].tools` is set, only those names stay active. |
@@ -483,7 +496,7 @@ status, which is what the old start/stop guidance used to do.
 | `login.ts` | QR login state machine. |
 | `qrcode.ts` | QR matrix → Unicode half-block terminal lines. |
 | `login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`), drawn from the `lib/tui/` kit (`titleRule`, `clip`, `isCloseKey`). |
-| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`) and the pure one-line/body renderers, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `paint`). |
+| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`): live facts, a focusable peer list with stop/reset/history keys, and the pure one-line/body renderers, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `listRow`, `paint`, `IdCursor`). |
 | `config.ts` | The `wechat` section of `bytefly.json` loading and normalization. |
 | `credentials.ts` | `credentials.json` (`0600`, every stored account and the active one). |
 | `state.ts` | `state.json` (cursor, owner, per-peer tokens, recent message ids). |
@@ -497,6 +510,7 @@ status, which is what the old start/stop guidance used to do.
 | `remote-ui.ts` | The peer session's UI context: dialogs and notices bound to that peer, the `askHuman` marker that delivers the file/text preface, and the `remotePrompts` switch. |
 | `slash.ts` | Inbound slash commands: the built-in registry (`/new`, `/stop`, `/status`, `/history`, `/help`), the session controls an action may invoke, and the pure parse/lookup/expand helpers. |
 | `history.ts` | Read-only `/history`: opens the peer's newest session, formats the last user/assistant messages, and never writes. |
+| `doctor.ts` | The plain-text `/wechat doctor` report: connection/token age, poll, lock, peer sessions, recent failures, and config. |
 | `types.ts` | Wire and domain types. |
 
 ## Testing

package/extensions/wechat/bridge.ts

@@ -25,7 +25,11 @@ import { messageOf } from "./errors.ts";
 import { parseInbound, peerKey, peerLabel, peerLanguage, sanitizeInbound, type PeerLanguage } from "./format.ts";
 import { notice } from "./notices.ts";
 import { createPresence } from "./presence.ts";
-import { createWechatInteractionChannel, type WechatInteractionChannel } from "./interaction.ts";
+import {
+	createWechatInteractionChannel,
+	type PendingPromptInfo,
+	type WechatInteractionChannel,
+} from "./interaction.ts";
 import { defaultSleep, defaultTimer, type ArmTimer } from "./timer.ts";
 import { createPeerWorker, type PeerState, type PeerWorker } from "./peer-worker.ts";
 import type { PeerSession } from "./peer-session.ts";
@@ -95,6 +99,8 @@ export interface BridgeDeps {
 	notify?: (message: string, kind?: "info" | "warning" | "error") => void;
 	/** Called whenever the bridge's connection state changes, for a status chip. */
 	onStateChange?: (state: BridgeState) => void;
+	/** Read the poller lock, for the doctor. */
+	loadLock?: () => { pid: number; at: number } | undefined;
 }
 
 export interface BridgeStatus {
@@ -114,6 +120,22 @@ export interface BridgeStatus {
 	mediaDropped: number;
 	/** Whether a remote dialog prompt is waiting for an answer. */
 	promptPending: boolean;
+	/** The waiting prompt's peer, kind, title, and age. */
+	prompt?: PendingPromptInfo;
+	/** When this connection opened. */
+	startedAt?: number;
+	/** When the last poll settled, successful or not. */
+	lastPollAt?: number;
+	/** The last poll failure, cleared by a successful poll. */
+	lastPollError?: string;
+	/** The last outbound send failure, cleared by a successful send. */
+	lastSendError?: string;
+	/** The long-poll hold currently in use (server hint or configured). */
+	pollHoldMs?: number;
+	/** The stored account's login time. */
+	tokenCreatedAt?: number;
+	/** The poller lock on disk, for the doctor. */
+	lock?: { pid: number; at: number };
 }
 
 export interface SendResult {
@@ -144,6 +166,11 @@ export function createBridge(deps: BridgeDeps): Bridge {
 	const armTimer = deps.armTimer ?? defaultTimer;
 	let running = false;
 	let expired = false;
+	let startedAt: number | undefined;
+	let lastPollAt: number | undefined;
+	let lastPollError: string | undefined;
+	let lastSendError: string | undefined;
+	let pollHoldMs: number | undefined;
 	let abort: AbortController | undefined;
 	let loopPromise: Promise<void> | undefined;
 	let client: WechatClient | undefined;
@@ -204,6 +231,12 @@ export function createBridge(deps: BridgeDeps): Bridge {
 		notify,
 		onExpired: handleExpired,
 		forgetToken,
+		onSendError: (message) => {
+			lastSendError = message;
+		},
+		onSent: () => {
+			lastSendError = undefined;
+		},
 	});
 
 	/** Run a slash action out-of-band and reply to the sender; never starts a turn. */
@@ -420,6 +453,12 @@ export function createBridge(deps: BridgeDeps): Bridge {
 		refreshLock: deps.refreshLock,
 		isRunning: () => running,
 		pollTimeout,
+		now: deps.now,
+		onPoll: (result) => {
+			lastPollAt = result.at;
+			lastPollError = result.error;
+			if (result.holdMs !== undefined) pollHoldMs = result.holdMs;
+		},
 	});
 
 	/**
@@ -438,6 +477,10 @@ export function createBridge(deps: BridgeDeps): Bridge {
 		budget.reset();
 		admission.reset();
 		inbound.reset();
+		lastPollAt = undefined;
+		lastPollError = undefined;
+		lastSendError = undefined;
+		pollHoldMs = undefined;
 	}
 
 	function releaseSafe(): void {
@@ -482,6 +525,7 @@ export function createBridge(deps: BridgeDeps): Bridge {
 			running = true;
 			expired = false;
 			resetEphemeral();
+			startedAt = deps.now();
 			// One worker per connection: it owns the per-peer queues and sessions, so
 			// a login (or a reconnect after an expiry) starts from a clean slate while
 			// each peer's history stays on disk.
@@ -573,6 +617,14 @@ export function createBridge(deps: BridgeDeps): Bridge {
 				refusedPeers: [...refusedPeers],
 				mediaDropped: inbound.dropped(),
 				promptPending: interaction.hasPending(),
+				prompt: interaction.pendingInfo(),
+				startedAt,
+				lastPollAt,
+				lastPollError,
+				lastSendError,
+				pollHoldMs: pollHoldMs ?? deps.config.pollHoldMs,
+				tokenCreatedAt: account?.createdAt,
+				lock: deps.loadLock?.(),
 			};
 		},
 

package/extensions/wechat/commands.ts

@@ -1,5 +1,5 @@
 /**
- * The `/wechat` command: `login`, `new`, `status`, `logout`, `help`.
+ * The `/wechat` command: `login`, `new`, `status`, `logout`, `allow`, `help`.
  *
  * The command is the operator's single entry point. `/wechat` (or `/wechat
  * status`) opens the control screen, where every action is a key; the verb
@@ -11,11 +11,20 @@
  * declines while a WeChat peer turn is running.
  */
 
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	CONFIG_DIR_NAME,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { writeConfigValue } from "../../lib/config.ts";
+import { sanitizeLine } from "../../lib/format.ts";
 import { supportsCustomUI } from "../../lib/interaction.ts";
-import type { Bridge } from "./bridge.ts";
+import { isAllowedPeer, type Bridge } from "./bridge.ts";
 import type { WechatClient } from "./client.ts";
 import type { WechatConfig } from "./config.ts";
+import { doctorReport } from "./doctor.ts";
 import { peerLabel, peerKey } from "./format.ts";
 import { waitForLogin, type LoginOutcome } from "./login.ts";
 import { defaultSleep } from "./timer.ts";
@@ -31,6 +40,8 @@ export interface CommandDeps {
 	createLoginClient: (cwd: string) => WechatClient;
 	saveAccount: (account: BotCredentials) => void;
 	primaryAccount: () => BotCredentials | undefined;
+	/** Read a peer's recent messages for `/wechat history`; read-only. */
+	readHistory: (peer: string, count: number) => Promise<string>;
 	logout: () => void;
 	now: () => number;
 }
@@ -50,8 +61,11 @@ export const WECHAT_COMMANDS = [
 	{ verb: "login", description: "Log in by QR; on a scan, store the account and start the bridge" },
 	{ verb: "new", description: "Start a fresh host session (peer conversations are independent)" },
 	{ verb: "status", description: "Open the control screen (a one-line summary outside the TUI)" },
+	{ verb: "doctor", description: "Print a health report: token age, last poll, lock, peers, failures" },
 	{ verb: "stop", description: "Stop one peer's running turn: /wechat stop <peer>" },
 	{ verb: "reset", description: "Start a fresh conversation for one peer: /wechat reset <peer>" },
+	{ verb: "history", description: "Print one peer's recent messages: /wechat history <peer> [n]" },
+	{ verb: "allow", description: "Allow a refused sender in the project config: /wechat allow [peer]" },
 	{ verb: "logout", description: "Clear the stored account and stop the bridge" },
 	{ verb: "help", description: "List these commands" },
 ] as const satisfies readonly WechatCommand[];
@@ -98,6 +112,72 @@ function busyWithPeerTurn(ctx: ExtensionContext, deps: CommandDeps, verb: string
 	return true;
 }
 
+/** Print the read-only health report, in the TUI, over RPC, or in a script. */
+async function runDoctor(ctx: ExtensionContext, deps: CommandDeps): Promise<void> {
+	ctx.ui.notify(
+		doctorReport({
+			status: deps.getBridge()?.status(),
+			account: deps.primaryAccount(),
+			config: deps.loadConfig(ctx.cwd),
+			now: deps.now(),
+		}),
+	);
+}
+
+/** Add a refused sender to the project config after the operator confirms. */
+async function runAllow(ctx: ExtensionContext, deps: CommandDeps, peerArg?: string): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify("WeChat allow needs a confirmation dialog, which this mode has no UI for.", "warning");
+		return;
+	}
+	const candidate = peerArg?.trim() || (await chooseRefused(ctx, deps));
+	if (!candidate) return;
+	const config = deps.loadConfig(ctx.cwd);
+	if (isAllowedPeer(candidate, undefined, config.allowedPeers)) {
+		ctx.ui.notify(`${sanitizeLine(peerLabel(candidate))} is already allowed.`);
+		return;
+	}
+	const relative = join(CONFIG_DIR_NAME, "bytefly.json");
+	const label = sanitizeLine(peerLabel(candidate));
+	const confirmed = await ctx.ui.confirm(`Allow ${label}?`, `Add this sender to wechat.allowedPeers in ${relative}?`);
+	if (!confirmed) return;
+	try {
+		writeConfigValue(join(ctx.cwd, relative), "wechat", "allowedPeers", [...config.allowedPeers, candidate]);
+		ctx.ui.notify(`Saved ${label} to ${relative}. Run /reload or restart Pi to apply.`);
+	} catch (error) {
+		ctx.ui.notify(`Could not save the allowlist: ${messageOf(error)}`, "error");
+	}
+}
+
+/** Pick one of the refused senders, or explain that there is nothing to allow. */
+async function chooseRefused(ctx: ExtensionContext, deps: CommandDeps): Promise<string | undefined> {
+	const refused = deps.getBridge()?.status().refusedPeers ?? [];
+	if (refused.length === 0) {
+		ctx.ui.notify("No refused sender to allow.", "warning");
+		return undefined;
+	}
+	return ctx.ui.select("Allow which sender?", refused);
+}
+
+/** Print one peer's recent messages; read-only, and works without a live session. */
+async function runHistory(ctx: ExtensionCommandContext, deps: CommandDeps, args: string): Promise<void> {
+	const [peer = "", countArg] = args.trim().split(/\s+/).filter(Boolean);
+	const bridge = deps.getBridge();
+	if (!peer) {
+		const known = bridge?.status().peerStates.map((entry) => peerLabel(entry.peer)) ?? [];
+		ctx.ui.notify(`Usage: /wechat history <peer> [n]. Known: ${known.join(", ") || "none yet"}.`, "warning");
+		return;
+	}
+	const requested = Number.parseInt(countArg ?? "", 10);
+	const count = Math.min(20, Math.max(1, Number.isFinite(requested) ? requested : 10));
+	try {
+		const text = await deps.readHistory(peer, count);
+		ctx.ui.notify(text || `No history yet for ${peerLabel(peer)}.`);
+	} catch (error) {
+		ctx.ui.notify(`WeChat history failed: ${messageOf(error)}`, "warning");
+	}
+}
+
 /**
  * React to a finished login. A confirmed scan stores the account and starts the
  * bridge immediately, so `/wechat login` is the only command needed to go
@@ -214,9 +294,37 @@ async function runPanel(ctx: ExtensionCommandContext, deps: CommandDeps): Promis
 				theme,
 				view,
 				onClose: done,
+				actions: {
+					stop: (peer) => {
+						const bridge = deps.getBridge();
+						if (!bridge) return "WeChat bridge is not running.";
+						return bridge.stop(peer) ? `Stopping ${peerLabel(peer)}.` : `${peerLabel(peer)} has no running turn.`;
+					},
+					reset: (peer) => {
+						const bridge = deps.getBridge();
+						if (!bridge) return "WeChat bridge is not running.";
+						return bridge.reset(peer)
+							? `Started a fresh conversation for ${peerLabel(peer)}.`
+							: `${peerLabel(peer)} is running; stop it before starting fresh.`;
+					},
+					cancelPrompt: () => {
+						const bridge = deps.getBridge();
+						if (!bridge?.status().promptPending) return "No prompt is waiting.";
+						bridge.channel().cancel();
+						return "Cancelled the waiting prompt.";
+					},
+				},
 				requestRender: () => tui.requestRender(),
 			}),
 	);
+	if (typeof action === "object" && action?.kind === "history") {
+		await runHistory(ctx, deps, action.peer);
+		return;
+	}
+	if (typeof action === "object" && action?.kind === "allow") {
+		await runAllow(ctx, deps);
+		return;
+	}
 	switch (action) {
 		case "login":
 		case "new":
@@ -296,6 +404,12 @@ async function dispatch(
 			return runNew(ctx, deps);
 		case "status":
 			return runPanel(ctx, deps);
+		case "doctor":
+			return runDoctor(ctx, deps);
+		case "history":
+			return runHistory(ctx, deps, peerArg);
+		case "allow":
+			return runAllow(ctx, deps, peerArg || undefined);
 		case "stop":
 			return runPeerAction(ctx, deps, "stop", peerArg);
 		case "reset":
@@ -311,7 +425,7 @@ async function dispatch(
 export function registerCommands(pi: ExtensionAPI, deps: CommandDeps): void {
 	pi.registerCommand("wechat", {
 		description:
-			"WeChat bridge. /wechat opens the control screen (login | new | status | stop | reset | logout | help)",
+			"WeChat bridge. /wechat opens the control screen (login | new | status | doctor | stop | reset | history | allow | logout | help)",
 		getArgumentCompletions: completeSubcommand,
 		handler: async (args, ctx) => {
 			const [sub = "status", ...rest] = args.trim().split(/\s+/).filter(Boolean);

package/extensions/wechat/deliver.ts

@@ -49,6 +49,10 @@ export interface DeliveryDeps {
 	onExpired: () => void;
 	/** Drop a peer's cached reply token. */
 	forgetToken: (peer: string) => void;
+	/** The last send failure, for the doctor/status. */
+	onSendError?: (message: string) => void;
+	/** A message got through; clear the last failure. */
+	onSent?: () => void;
 }
 
 /** The bridge's outbound surface. */
@@ -137,9 +141,13 @@ export function createDeliverer(deps: DeliveryDeps): Deliverer {
 			if (failureNotified.has(target.peer)) return;
 			failureNotified.add(target.peer);
 			const partial = progress.total > 1 ? ` after ${progress.sent} of ${progress.total} parts were sent` : "";
+			deps.onSendError?.(messageOf(error));
 			deps.notify(`WeChat ${label} failed${partial}: ${messageOf(error)}`, "warning");
 		});
-		if (!failed && delivery.ok) failureNotified.delete(target.peer);
+		if (!failed && delivery.ok) {
+			failureNotified.delete(target.peer);
+			deps.onSent?.();
+		}
 		return delivery.ok;
 	}
 
@@ -169,7 +177,11 @@ export function createDeliverer(deps: DeliveryDeps): Deliverer {
 			});
 			// `sendLocalFile` reports only success, and the caller may fall back to text;
 			// without this line the operator would never know the attachment was dropped.
-			if (!sent && !signal?.aborted) deps.notify(`WeChat file delivery failed for ${fileName}.`, "warning");
+			if (!sent && !signal?.aborted) {
+				deps.onSendError?.(`file delivery failed: ${fileName}`);
+				deps.notify(`WeChat file delivery failed for ${fileName}.`, "warning");
+			}
+			if (sent) deps.onSent?.();
 			return sent;
 		},
 
@@ -178,11 +190,13 @@ export function createDeliverer(deps: DeliveryDeps): Deliverer {
 			const delivery = await deliverText(owner, contextToken, text, signal, (error, progress) => {
 				deps.forgetToken(owner);
 				const partial = progress.total > 1 ? ` after ${progress.sent} of ${progress.total} parts were sent` : "";
+				deps.onSendError?.(messageOf(error));
 				failure = `${messageOf(error)}${partial}`;
 			});
 			if (delivery.expired) return { ok: false, error: "WeChat session expired." };
 			if (delivery.empty) return { ok: false, error: "Nothing to send after formatting." };
 			if (!delivery.ok) return { ok: false, error: failure ?? "WeChat send failed." };
+			deps.onSent?.();
 			return { ok: true };
 		},
 

package/extensions/wechat/doctor.ts

@@ -0,0 +1,121 @@
+/**
+ * The plain-text health report behind `/wechat doctor`.
+ *
+ * It answers the operator's first question — why is the bot quiet or slow? — from
+ * facts the bridge already has: the connection, the token's age, the last poll,
+ * the poller lock, per-peer sessions, and the last send/poll failure. Pure, so
+ * the wording and the age math are unit-tested without a bridge.
+ */
+
+import { formatDuration } from "../../lib/format.ts";
+import type { BridgeStatus } from "./bridge.ts";
+import type { WechatConfig } from "./config.ts";
+import type { BotCredentials } from "./types.ts";
+import { peerLabel } from "./format.ts";
+
+export interface DoctorInput {
+	/** Undefined when the bridge has never been built in this runtime. */
+	status?: BridgeStatus;
+	account?: BotCredentials;
+	config: WechatConfig;
+	now: number;
+}
+
+const LABEL = 11;
+
+/** One `Label      value` line. */
+function row(label: string, value: string): string {
+	return `${label.padEnd(LABEL)}${value}`;
+}
+
+/** `3.2s` since `at`, or a placeholder. */
+function age(now: number, at: number | undefined): string {
+	return at === undefined ? "unknown" : `${formatDuration(Math.max(0, now - at))} ago`;
+}
+
+function connection(status: BridgeStatus | undefined, account: BotCredentials | undefined, now: number): string {
+	if (!status?.open) {
+		return status?.expired ? "expired · run /wechat login" : "closed";
+	}
+	const owner = status.owner ? peerLabel(status.owner) : "unclaimed";
+	const token = account ? `${formatDuration(Math.max(0, now - account.createdAt))} old` : "unknown age";
+	return `open · owner ${owner} · token ${token}`;
+}
+
+function poll(status: BridgeStatus | undefined, now: number): string {
+	if (!status) return "not started";
+	const last =
+		status.lastPollAt === undefined
+			? "no poll yet"
+			: `last ${formatDuration(Math.max(0, now - status.lastPollAt))} ago`;
+	const hold = status.pollHoldMs === undefined ? "server hold" : `hold ${formatDuration(status.pollHoldMs)}`;
+	const error = status.lastPollError ? ` · error: ${status.lastPollError}` : "";
+	return `${last} · ${hold}${error}`;
+}
+
+function lockLine(status: BridgeStatus | undefined, now: number): string {
+	const lock = status?.lock;
+	if (!lock) return status?.open ? "not held" : "not running";
+	return `pid ${lock.pid} · ${age(now, lock.at)}`;
+}
+
+function peers(status: BridgeStatus | undefined): string[] {
+	if (!status || status.peerStates.length === 0) return [row("Peers", "none")];
+	const running = status.peerStates.filter((entry) => entry.state.status === "running").length;
+	const lines = [row("Peers", `${status.peerStates.length} · ${running} running · ${status.queued} queued`)];
+	for (const entry of status.peerStates) {
+		const state = entry.state;
+		const what =
+			state.status === "running"
+				? `running ${formatDuration(state.runningMs ?? 0)}`
+				: state.status === "queued"
+					? `queued ${state.queued}`
+					: "idle";
+		const session = state.sessionAgeMs === undefined ? "" : ` · session ${formatDuration(state.sessionAgeMs)}`;
+		lines.push(row(`  ${peerLabel(entry.peer)}`, `${what}${session}`));
+	}
+	return lines;
+}
+
+function recent(status: BridgeStatus | undefined): string {
+	const errors = [
+		status?.lastSendError ? `send: ${status.lastSendError}` : undefined,
+		status?.lastPollError ? `poll: ${status.lastPollError}` : undefined,
+	].filter((entry): entry is string => entry !== undefined);
+	return row("Recent", errors.length > 0 ? errors.join(" · ") : "no recent failure");
+}
+
+function media(status: BridgeStatus | undefined): string {
+	const dropped = status?.mediaDropped ?? 0;
+	const refused = status?.refused ?? 0;
+	const names = status?.refusedPeers.join(", ");
+	return row(
+		"Media",
+		`${dropped} dropped · ${refused} refused${names ? ` (${names})` : ""} · ${status?.promptPending ? "prompt waiting" : "no prompt"}`,
+	);
+}
+
+function configLine(config: WechatConfig): string {
+	const overrides = Object.keys(config.peers).length;
+	const limits = config.maxTurnsPerHour > 0 ? `${config.maxTurnsPerHour} turns/h` : "no turn cap";
+	return row(
+		"Config",
+		`typing ${config.typingIndicator ? "on" : "off"} · prompts ${config.remotePrompts ? "on" : "off"} · ` +
+			`${config.allowedPeers.length} allowed · ${overrides} peer override(s) · ${limits}`,
+	);
+}
+
+/** The doctor report, one line per fact. */
+export function doctorReport(input: DoctorInput): string {
+	const { status, account, config, now } = input;
+	return [
+		"wechat — health",
+		row("Connection", connection(status, account, now)),
+		row("Poll", poll(status, now)),
+		row("Lock", lockLine(status, now)),
+		...peers(status),
+		recent(status),
+		media(status),
+		configLine(config),
+	].join("\n");
+}

package/extensions/wechat/index.ts

@@ -23,7 +23,7 @@ import { registerCommands, type CommandDeps } from "./commands.ts";
 import { messageOf } from "./errors.ts";
 import { loadWechatConfig } from "./config.ts";
 import { clearCredentials, primaryAccount, saveAccount, wechatDir } from "./credentials.ts";
-import { acquireLock, lockPath, refreshLock, releaseLock } from "./lock.ts";
+import { acquireLock, lockPath, readLock, refreshLock, releaseLock } from "./lock.ts";
 import { openPeerSession, type PeerSession, type PeerSessionOptions } from "./peer-session.ts";
 import { createPeerUIContext } from "./remote-ui.ts";
 import { peerKey } from "./format.ts";
@@ -127,6 +127,7 @@ export default function wechat(pi: ExtensionAPI, deps: WechatDeps = {}): void {
 			acquireLock: () => acquireLock(lockPath(), lockDeps()),
 			refreshLock: () => refreshLock(lockPath(), lockDeps()),
 			releaseLock: () => releaseLock(lockPath(), process.pid),
+			loadLock: () => readLock(lockPath()),
 			notify: (message, kind) => {
 				ctxRef?.ui.notify(message, kind);
 			},
@@ -180,6 +181,8 @@ export default function wechat(pi: ExtensionAPI, deps: WechatDeps = {}): void {
 		},
 		saveAccount,
 		primaryAccount,
+		readHistory: (peer, count) =>
+			readPeerHistory(ctxRef?.cwd ?? process.cwd(), join(wechatDir(), "sessions"), peer, count),
 		logout: () => {
 			clearCredentials();
 			// The account is the on/off switch: without one there is nothing to report,

package/extensions/wechat/interaction.ts

@@ -38,6 +38,8 @@ export interface WechatInteractionDeps {
 	language: () => PeerLanguage;
 	/** Arm a cancellable one-shot timer. Defaults to a real, unref'd `setTimeout`. */
 	armTimer?: ArmTimer;
+	/** Clock for the prompt's start time; defaults to `Date.now`. */
+	now?: () => number;
 }
 
 export interface WechatInteractionChannel extends InteractionChannel {
@@ -45,13 +47,27 @@ export interface WechatInteractionChannel extends InteractionChannel {
 	handleInbound(peer: string, text: string): boolean;
 	/** Whether a prompt is currently waiting for a reply. */
 	hasPending(): boolean;
+	/** The waiting prompt, for the control screen; undefined when none waits. */
+	pendingInfo(): PendingPromptInfo | undefined;
+	/** Withdraw the waiting prompt: tell the peer and resolve it cancelled. */
+	cancel(): void;
 	/** Drop any pending prompt (turn settled or the bridge stopped). */
 	reset(): void;
 }
 
+/** The waiting prompt, as the control screen reads it. */
+export interface PendingPromptInfo {
+	peer: string;
+	kind: InteractionRequest["kind"];
+	title: string;
+	/** When the prompt was registered, in epoch milliseconds. */
+	startedAt: number;
+}
+
 interface Pending {
 	request: InteractionRequest;
 	peer: string;
+	startedAt: number;
 	resolve: (answer: InteractionAnswer) => void;
 	signal?: AbortSignal;
 	onAbort: () => void;
@@ -61,6 +77,7 @@ interface Pending {
 
 export function createWechatInteractionChannel(deps: WechatInteractionDeps): WechatInteractionChannel {
 	const arm = deps.armTimer ?? defaultTimer;
+	const now = deps.now ?? Date.now;
 	let pending: Pending | undefined;
 	/**
 	 * Free text captured from a `select` "Other" reply, per peer: the immediately
@@ -88,6 +105,26 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 			return pending !== undefined;
 		},
 
+		pendingInfo(): PendingPromptInfo | undefined {
+			const current = pending;
+			return current === undefined
+				? undefined
+				: {
+						peer: current.peer,
+						kind: current.request.kind,
+						title: current.request.title,
+						startedAt: current.startedAt,
+					};
+		},
+
+		cancel(): void {
+			if (!pending) return;
+			// The peer saw the prompt; one line says it was withdrawn. `reset` is the
+			// silent cleanup path and deliberately does not send this.
+			void deps.send(notice("timeout", deps.language()));
+			settle({ kind: "cancelled" });
+		},
+
 		async post(text: string, signal?: AbortSignal): Promise<void> {
 			await deps.send(text, signal);
 		},
@@ -117,7 +154,7 @@ export function createWechatInteractionChannel(deps: WechatInteractionDeps): Wec
 			const cancelTimers: Array<() => void> = [];
 			const answer = new Promise<InteractionAnswer>((resolve) => {
 				const onAbort = () => settle({ kind: "cancelled" });
-				pending = { request, peer, resolve, signal, onAbort, cancelTimers };
+				pending = { request, peer, startedAt: now(), resolve, signal, onAbort, cancelTimers };
 				signal?.addEventListener("abort", onAbort, { once: true });
 				// An ignored question must not freeze the session: nudge once, then
 				// cancel so the model gets a clean answer instead of a hang.

package/extensions/wechat/lock.ts

@@ -48,10 +48,19 @@ function parseLock(text: string): LockInfo | undefined {
 	}
 }
 
+/** The raw lock record, or undefined when the file is missing or corrupt. */
+export function readLock(path: string): LockInfo | undefined {
+	try {
+		if (!existsSync(path)) return undefined;
+		return parseLock(readFileSync(path, "utf-8"));
+	} catch {
+		return undefined;
+	}
+}
+
 /** True when the existing lock blocks a new owner. */
 export function isLocked(path: string, deps: LockDeps): boolean {
-	if (!existsSync(path)) return false;
-	const info = parseLock(readFileSync(path, "utf-8"));
+	const info = readLock(path);
 	if (!info) return false;
 	if (info.pid === deps.pid) return false;
 	const stale = deps.now() - info.at > (deps.staleMs ?? DEFAULT_STALE_MS);

package/extensions/wechat/peer-worker.ts

@@ -75,6 +75,8 @@ export interface PeerState {
 	queued: number;
 	/** How long the running turn has been going, in milliseconds. */
 	runningMs?: number;
+	/** How long the peer's session has been open, when one is open. */
+	sessionAgeMs?: number;
 }
 
 export interface PeerSnapshot {
@@ -110,6 +112,8 @@ interface PeerEntry {
 	/** Monotonic start time of the running turn, for `runningMs`. */
 	startedAt?: number;
 	session?: PeerSession;
+	/** When the current session opened, for the doctor's session age. */
+	sessionSince?: number;
 	opening?: Promise<PeerSession>;
 	disposeTimer?: () => void;
 }
@@ -164,15 +168,18 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 	function stateOf(peer: string): PeerState {
 		const target = peers.get(peer);
 		if (!target) return { status: "idle", queued: 0 };
+		const sessionAge =
+			target.sessionSince === undefined ? undefined : { sessionAgeMs: Math.max(0, now() - target.sessionSince) };
 		if (target.running) {
 			return {
 				status: "running",
 				queued: target.queue.length + target.merged,
 				runningMs: target.startedAt === undefined ? 0 : now() - target.startedAt,
+				...sessionAge,
 			};
 		}
 		const queued = target.queue.length + target.merged;
-		return { status: queued > 0 ? "queued" : "idle", queued };
+		return { status: queued > 0 ? "queued" : "idle", queued, ...sessionAge };
 	}
 
 	/** Drop the peer's session and queue. */
@@ -182,6 +189,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 		cancelIdleSweep(target);
 		target.session?.dispose();
 		target.session = undefined;
+		target.sessionSince = undefined;
 		target.opening = undefined;
 	}
 
@@ -212,6 +220,7 @@ export function createPeerWorker(deps: PeerWorkerDeps): PeerWorker {
 						throw new Error("The WeChat bridge closed while opening the session.");
 					}
 					target.session = opened;
+					target.sessionSince = now();
 					return opened;
 				})
 				.finally(() => {

package/extensions/wechat/poll.ts

@@ -45,6 +45,9 @@ export interface PollDeps {
 	onMessages: (messages: WeixinMessage[]) => void;
 	refreshLock: () => void;
 	isRunning: () => boolean;
+	now: () => number;
+	/** Report the last poll attempt, for the doctor/status. */
+	onPoll?: (result: { at: number; error?: string; holdMs?: number }) => void;
 	pollTimeout: (serverHintMs: number | undefined) => number;
 }
 
@@ -82,6 +85,10 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 				} catch (error) {
 					if (signal.aborted || !deps.isRunning()) break;
 					if (watchdog.signal.aborted) {
+						deps.onPoll?.({
+							at: deps.now(),
+							error: `timed out after ${Math.round(watchdogMs / 1000)}s`,
+						});
 						// A wedged request, not a server answer: retry at once with the same
 						// cursor, so nothing is skipped, and say so once.
 						if (!timeoutNotified) {
@@ -90,6 +97,7 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 						}
 						continue;
 					}
+					deps.onPoll?.({ at: deps.now(), error: messageOf(error) });
 					deps.notify(`WeChat poll failed: ${messageOf(error)}`, "warning");
 					try {
 						await deps.sleep(BACKOFF_MS, signal);
@@ -112,6 +120,7 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 					if (!rejectedNotified) {
 						rejectedNotified = true;
 						const code = (response.ret ?? 0) !== 0 ? response.ret : (response.errcode ?? 0);
+						deps.onPoll?.({ at: deps.now(), error: `rejected ret ${code}` });
 						deps.notify(`WeChat poll rejected (ret ${code}); retrying.`, "warning");
 					}
 					try {
@@ -130,6 +139,7 @@ export function createPollLoop(deps: PollDeps): PollLoop {
 				}
 				deps.onMessages(response.msgs);
 				deps.refreshLock();
+				deps.onPoll?.({ at: deps.now(), holdMs: serverHint ?? deps.holdMs() });
 			}
 		},
 	};

package/extensions/wechat/status-screen.ts

@@ -3,19 +3,20 @@
  *
  * `connectionOf`, `statusView`, `statusLine`, and `statusBody` are pure, so the
  * wording, fields, and width safety are unit-tested; `StatusScreenComponent` is
- * the TUI mounted by `runPanel`. It is the control hub: every operator action
- * (login, new session, logout) is a key here, so the user never has to remember
- * a subcommand. It shows the live connection state and closes with an action so
- * the command can run it after the screen is gone and input focus is free.
+ * the TUI mounted by `runPanel`. It is the control hub: the global keys (login,
+ * new session, logout) close the screen and dispatch, while a focused peer row
+ * can be stopped, reset, or opened in `/wechat history` without leaving the
+ * screen.
  */
 
 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 { clip } from "../../lib/tui/columns.ts";
-import { isCloseKey } from "../../lib/tui/cursor.ts";
+import { formatRange, IdCursor, isCloseKey, navIntent } from "../../lib/tui/cursor.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { keyValueRow } from "../../lib/tui/rows.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";
@@ -25,8 +26,11 @@ import type { BotCredentials } from "./types.ts";
 /** User-facing connection word; the internal `BridgeState` stays running/stopped. */
 export type StatusConnection = "open" | "expired" | "closed";
 
-/** What the status screen closed with: an action to dispatch, or `close`. */
-export type StatusAction = "close" | "login" | "new" | "logout";
+/**
+ * What the status screen closed with: a global action, a peer history request,
+ * or `close`.
+ */
+export type StatusAction = "close" | "login" | "new" | "logout" | { kind: "history"; peer: string } | { kind: "allow" };
 
 /** The facts the status screen and the one-line summary render. */
 export interface StatusView {
@@ -44,17 +48,23 @@ 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 };
+	/** The clock the view was built with, for the prompt age. */
+	now?: number;
 }
 
 /** One peer's line in the control screen. */
 export interface PeerRow {
+	/** The raw peer id, so an action targets the right person; falls back to `label`. */
+	id?: string;
 	label: string;
 	status: "idle" | "queued" | "running";
 	queued: number;
 	runningMs?: number;
 }
 
-/** How many peer rows the screen lists before summarising the rest. */
+/** How many peer rows the screen lists before scrolling. */
 const MAX_PEER_ROWS = 5;
 
 /** The connection word for a bridge status, or `closed` when there is none. */
@@ -63,7 +73,11 @@ export function connectionOf(status: BridgeStatus | undefined): StatusConnection
 }
 
 /** Build the view from the stored account and the live bridge status. */
-export function statusView(account: BotCredentials | undefined, status: BridgeStatus | undefined): StatusView {
+export function statusView(
+	account: BotCredentials | undefined,
+	status: BridgeStatus | undefined,
+	now: number = Date.now(),
+): StatusView {
 	return {
 		bridge: status !== undefined,
 		account: account ? peerLabel(account.ilinkUserId) : undefined,
@@ -72,6 +86,7 @@ export function statusView(account: BotCredentials | undefined, status: BridgeSt
 		peers: status?.peerCount ?? 0,
 		queued: status?.queued ?? 0,
 		peerRows: (status?.peerStates ?? []).map((entry) => ({
+			id: entry.peer,
 			label: peerLabel(entry.peer),
 			status: entry.state.status,
 			queued: entry.state.queued,
@@ -81,6 +96,14 @@ export function statusView(account: BotCredentials | undefined, status: BridgeSt
 		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,
+		now,
 	};
 }
 
@@ -140,8 +163,14 @@ function connectionRole(connection: StatusConnection): TuiRole {
 	}
 }
 
+/** The peer focus passed into the body: which row is selected and which slice shows. */
+export interface PeerSelection {
+	selectedId?: string;
+	window?: { start: number; end: number };
+}
+
 /** Rows for the status screen body, each fitted to `width`. */
-export function statusBody(view: StatusView, theme: Theme, width: number): string[] {
+export function statusBody(view: StatusView, theme: Theme, width: number, selection?: PeerSelection): string[] {
 	const target = Math.max(1, width);
 	const lines = [
 		row(theme, target, "Account", view.account ?? "not logged in", view.account ? "label" : "meta"),
@@ -153,8 +182,13 @@ export function statusBody(view: StatusView, theme: Theme, width: number): strin
 		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.promptPending) lines.push(row(theme, target, "Prompt", "waiting for a reply", "accent"));
-		lines.push(...peerLines(view.peerRows, theme, target));
+		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"));
+		} else if (view.promptPending) {
+			lines.push(row(theme, target, "Prompt", "waiting for a reply", "accent"));
+		}
+		lines.push(...peerLines(view.peerRows, theme, target, selection));
 	}
 	if (view.connection === "expired") {
 		lines.push("");
@@ -179,47 +213,98 @@ function peerValue(row: PeerRow): string {
 	return "idle";
 }
 
-/** One indented line per peer, capped, so the screen stays compact. */
-function peerLines(rows: PeerRow[], theme: Theme, width: number): string[] {
+/** One selectable line per peer, with a range row when the list is scrolled. */
+function peerLines(rows: PeerRow[], theme: Theme, width: number, selection?: PeerSelection): string[] {
 	if (rows.length === 0) return [];
-	const shown = rows.slice(0, MAX_PEER_ROWS);
-	const lines = [""];
-	for (const [index, entry] of shown.entries()) {
-		const value = peerValue(entry);
+	const start = selection?.window?.start ?? 0;
+	const end = selection?.window?.end ?? Math.min(rows.length, MAX_PEER_ROWS);
+	const shown = rows.slice(start, end);
+	const lines = ["", clip(`  ${paint(theme, "meta", "Conversations")}`, width)];
+	for (const entry of shown) {
+		const selected = selection?.selectedId !== undefined && (entry.id ?? entry.label) === selection.selectedId;
 		const role: TuiRole = entry.status === "running" ? "accent" : entry.status === "queued" ? "warn" : "meta";
-		lines.push(row(theme, width, index === 0 ? "Conversations" : "", value, role));
+		lines.push(
+			listRow(theme, width, {
+				indent: 2,
+				selected,
+				label: entry.label,
+				trailing: peerValue(entry),
+				trailingRole: role,
+			}),
+		);
 	}
-	if (rows.length > shown.length) {
+	if (selection?.window !== undefined) {
+		if (start > 0 || end < rows.length) {
+			lines.push(formatRange(theme, width, { start, end, total: rows.length }));
+		}
+	} else if (rows.length > shown.length) {
 		lines.push(clip(`  ${paint(theme, "meta", `+${rows.length - shown.length} more`)}`, width));
 	}
 	return lines;
 }
 
+/** The peer actions the screen can run without closing. */
+export interface StatusActions {
+	/** Stop the peer's running turn; returns the line to flash. */
+	stop(peer: string): string;
+	/** 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;
+}
+
 export interface StatusScreenOptions {
 	theme: Theme;
 	/** Live view, re-read on every render so `r` shows the current state. */
 	view: () => StatusView;
 	/** Called once when the screen closes, with the chosen action. */
 	onClose: (action: StatusAction) => void;
+	/** In-place peer actions; absent makes `s`/`d` explain that they are unavailable. */
+	actions?: StatusActions;
 	/** Repaint after a state change. */
 	requestRender: () => void;
 }
 
 /** The `/wechat` control screen: live connection facts plus every action. */
 export class StatusScreenComponent implements Component {
+	private readonly cursor = new IdCursor();
+	private flash: string | undefined;
+
 	constructor(private readonly options: StatusScreenOptions) {}
 
-	private hints(): ScreenHint[] {
-		return [
-			"Esc close",
+	/**
+	 * The focused peer, or undefined when the list is empty. Not named `focused`:
+	 * the host duck-types focusables with `"focused" in component` and writes a
+	 * boolean there, which would shadow the method.
+	 */
+	private focusedPeer(view: StatusView): PeerRow | undefined {
+		const rows = view.peerRows;
+		if (rows.length === 0) return undefined;
+		return rows[this.cursor.indexOf(rows, (row) => row.id ?? row.label)];
+	}
+
+	private setFlash(message: string | undefined): void {
+		this.flash = message;
+		this.options.requestRender();
+	}
+
+	private hints(view: StatusView): ScreenHint[] {
+		const hints: ScreenHint[] = ["Esc close"];
+		if (view.peerRows.length > 0) {
+			hints.push("j/k move", { text: "s stop", color: "accent" }, { text: "d reset", color: "warning" }, "h history");
+		}
+		hints.push(
 			{ text: "l login", color: "accent" },
 			{ text: "n new", color: "accent" },
 			{ text: "o logout", color: "error" },
 			"r refresh",
-		];
+		);
+		return hints;
 	}
 
 	handleInput(data: string): void {
+		const view = this.options.view();
+		const peer = this.focusedPeer(view);
 		if (isCloseKey(data)) {
 			this.options.onClose("close");
 			return;
@@ -236,21 +321,97 @@ export class StatusScreenComponent implements Component {
 			this.options.onClose("logout");
 			return;
 		}
-		if (data === "r" || data === "R") this.options.requestRender();
+		if (data === "r" || data === "R") {
+			this.setFlash(undefined);
+			return;
+		}
+		if (data === "a" || data === "A") {
+			this.options.onClose({ kind: "allow" });
+			return;
+		}
+		if (data === "c" || data === "C") {
+			if (!view.prompt) {
+				this.setFlash("No prompt waiting.");
+				return;
+			}
+			this.setFlash(this.options.actions?.cancelPrompt() ?? "Prompt cancel is unavailable.");
+			return;
+		}
+		if (data === "s" || data === "S" || data === "d" || data === "D" || data === "h" || data === "H") {
+			if (!peer) {
+				this.setFlash("No peer conversation yet.");
+				return;
+			}
+			const id = peer.id ?? peer.label;
+			if (data === "h" || data === "H") {
+				this.options.onClose({ kind: "history", peer: id });
+				return;
+			}
+			const actions = this.options.actions;
+			if (!actions) {
+				this.setFlash("Peer actions are unavailable here.");
+				return;
+			}
+			this.setFlash(data === "s" || data === "S" ? actions.stop(id) : actions.reset(id));
+			return;
+		}
+		const rows = view.peerRows;
+		const index = this.cursor.indexOf(rows, (row) => row.id ?? row.label);
+		switch (navIntent(data)) {
+			case "up":
+				this.select(index - 1, view);
+				return;
+			case "down":
+				this.select(index + 1, view);
+				return;
+			case "pageUp":
+				this.select(index - this.cursor.visible, view);
+				return;
+			case "pageDown":
+				this.select(index + this.cursor.visible, view);
+				return;
+			case "home":
+				this.select(0, view);
+				return;
+			case "end":
+				this.select(rows.length - 1, view);
+				return;
+		}
 	}
 
-	/** Stateless: every value is read live from `view()` on render. */
+	/** Focus the row at `index` and repaint when it moves. */
+	private select(index: number, view: StatusView): void {
+		const rows = view.peerRows;
+		if (rows.length === 0) return;
+		this.cursor.select(rows, (row) => row.id ?? row.label, index);
+		this.options.requestRender();
+	}
+
+	/** The cursor is plain state and the view is live, so there is nothing to invalidate. */
 	invalidate(): void {}
 
 	render(width: number): string[] {
 		const target = Math.max(1, width);
 		const theme = this.options.theme;
-		return [
+		const view = this.options.view();
+		const rows = view.peerRows;
+		this.cursor.visible = Math.min(MAX_PEER_ROWS, Math.max(1, rows.length));
+		this.cursor.clamp(rows, (row) => row.id ?? row.label);
+		const peer = this.focusedPeer(view);
+		if (rows.length > 0) this.cursor.ensureVisible(this.cursor.indexOf(rows, (row) => row.id ?? row.label));
+		const start = this.cursor.scroll;
+		const end = Math.min(rows.length, start + this.cursor.visible);
+		const selection: PeerSelection | undefined =
+			rows.length === 0
+				? undefined
+				: { selectedId: peer ? (peer.id ?? peer.label) : undefined, window: { start, end } };
+		const lines = [
 			titleRule(theme, target, `wechat${SEPARATORS.item}control`),
 			"",
-			...statusBody(this.options.view(), theme, target),
-			"",
-			screenHint(theme, target, this.hints()),
+			...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)));
+		return lines;
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, memory, wechat, and bytefly.",
   "keywords": [
     "pi-package",