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

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,13 @@ 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 pause` | Stop polling new messages; running turns may finish and reply. The poller lock is released, so another runtime may take the account. |
+| `/wechat resume` | Reacquire the lock and poll again; reports when another runtime already holds it. |
+| `/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 +105,23 @@ 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; `p` pauses or resumes
+polling. `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.
+
+Pause is per runtime and keeps the account and peer sessions: a running turn
+may finish and reply, a waiting prompt is withdrawn with the timeout notice,
+and the poller lock is released so another runtime can take over. Resume
+reacquires the lock and reports when another runtime holds it. `/reload` or a
+restart builds a new bridge and resumes polling, so pause is a temporary mute,
+not a persistent switch.
 
 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 +324,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,16 +405,16 @@ 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`, `pause`, `resume`, `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. |
 | Turn ownership | `peer-worker.ts`: a serial queue per peer, `session.prompt()`/`session.abort()`, `getLastAssistantText()` for the answer, and one idle sweep per session. `concurrency` defaults to 1 so a forwarded dialog has one owner. |
 | Slash commands | Admitted inbound text is matched against `SLASH_COMMANDS` in `handleMessage`; a snippet is expanded into the turn, an action runs out-of-band and replies, and an unknown command falls through. Actions act on the sender through `SlashSessionControls` (`newSession` → worker reset, `stop` → worker abort, `status` → worker state, `history` → a read-only read of that peer's newest session). |
 | Peer dialogs | `bindExtensions({ mode: "rpc", uiContext })` on each peer session, with `createPeerUIContext(channel)` routing `select`/`confirm`/`input`/`editor` to that peer and marking the context for `askHuman`'s file/text preface. The terminal's shared `ctx.ui` is deliberately not adapted: a host turn is never answered remotely, so its dialogs stay local even while a peer turn runs. |
-| Status | The bridge's connection state (`running` / `expired` / `stopped`) is published through `onStateChange` to `ctx.ui.setStatus(STATUS_KEYS.wechat, …)`; an expiry keeps a persistent error chip, and the status bar renders it on line 2. |
+| Status | The bridge's connection state (`running` / `paused` / `expired` / `stopped`) is published through `onStateChange` to `ctx.ui.setStatus(STATUS_KEYS.wechat, …)`; an expiry keeps a persistent error chip, pause keeps a warning chip, and the status bar renders it on line 2. |
 | State | Files under `<agent-dir>/wechat/`; the bridge is not authoritative UI, so nothing is stored in the transcript. |
-| Lifecycle | The factory only registers. The poll loop starts on `session_start` when an account is stored (and after `/wechat login`); `session_shutdown` closes it. One bridge per extension runtime: it is built once, `open()` is a no-op while running (so the RPC double `session_start` on a session switch cannot start a second poller), and shutdown is idempotent, so the reload and replacement paths (`/reload`, `/new`, resume, fork — all of which re-run the factory and emit shutdown before the new start) each end with exactly one poller. `/wechat` screens use `ctx.ui.custom`, so they degrade (status) or decline (login, logout) while a peer turn runs. |
+| Lifecycle | The factory only registers. The poll loop starts on `session_start` when an account is stored (and after `/wechat login`); `session_shutdown` closes it. One bridge per extension runtime: it is built once, `open()` is a no-op while running or paused (so the RPC double `session_start` on a session switch cannot start a second poller or resume a paused one), and shutdown is idempotent, so the reload and replacement paths (`/reload`, `/new`, resume, fork — all of which re-run the factory and emit shutdown before the new start) each end with exactly one poller. `pause()` stops the loop and releases the lock while keeping the worker, so a running turn can finish; `resume()` reacquires the lock and starts a new loop. Pause is runtime-local, so a reload or restart starts a fresh running bridge. `/wechat` screens use `ctx.ui.custom`, so they degrade (status) or decline (login, logout) while a peer turn runs. |
 
 ## Design notes
 
@@ -483,7 +506,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 +520,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";
@@ -61,7 +65,7 @@ export function isInboundMessage(message: WeixinMessage): message is WeixinMessa
 }
 
 /** The bridge's connection state, published to the UI for the status chip. */
-export type BridgeState = "stopped" | "running" | "expired";
+export type BridgeState = "stopped" | "running" | "expired" | "paused";
 
 export interface BridgeDeps {
 	config: WechatConfig;
@@ -95,12 +99,16 @@ 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 {
 	open: boolean;
 	/** Whether the bridge stopped because the session expired and needs a re-login. */
 	expired: boolean;
+	/** Whether the operator paused polling; the account and peer sessions are kept. */
+	paused: boolean;
 	owner?: string;
 	peerCount: number;
 	queued: number;
@@ -114,6 +122,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 {
@@ -124,6 +148,10 @@ export interface SendResult {
 export interface Bridge {
 	open(): void;
 	close(): Promise<void>;
+	/** Stop polling new messages; running turns may finish. False when not running. */
+	pause(): Promise<boolean>;
+	/** Reacquire the lock and start polling again. False when not paused or the lock is taken. */
+	resume(): Promise<boolean>;
 	shutdown(): Promise<void>;
 	/** Stop one peer's running turn; false when that peer is idle. */
 	stop(peer: string): boolean;
@@ -143,7 +171,13 @@ export function createBridge(deps: BridgeDeps): Bridge {
 	const sleep = deps.sleep ?? defaultSleep;
 	const armTimer = deps.armTimer ?? defaultTimer;
 	let running = false;
+	let paused = 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;
@@ -168,11 +202,12 @@ export function createBridge(deps: BridgeDeps): Bridge {
 
 	/** Report the current connection state to the host, for a status chip. */
 	function publishState(): void {
-		deps.onStateChange?.(running ? "running" : expired ? "expired" : "stopped");
+		deps.onStateChange?.(running ? "running" : expired ? "expired" : paused ? "paused" : "stopped");
 	}
 
 	function handleExpired(): void {
 		running = false;
+		paused = false;
 		expired = true;
 		// An expiry can be discovered by a send while the loop is parked in
 		// `getUpdates`; abort it so it cannot wake up beside a later `open()`.
@@ -204,6 +239,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 +461,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 +485,10 @@ export function createBridge(deps: BridgeDeps): Bridge {
 		budget.reset();
 		admission.reset();
 		inbound.reset();
+		lastPollAt = undefined;
+		lastPollError = undefined;
+		lastSendError = undefined;
+		pollHoldMs = undefined;
 	}
 
 	function releaseSafe(): void {
@@ -448,6 +499,21 @@ export function createBridge(deps: BridgeDeps): Bridge {
 		}
 	}
 
+	/**
+	 * Serialize lifecycle transitions. A pause and a resume from the control
+	 * screen, or a shutdown racing either, must not leave two poll loops or a
+	 * released lock behind a running bridge.
+	 */
+	let lifecycle: Promise<void> = Promise.resolve();
+	function serial<T>(work: () => Promise<T>): Promise<T> {
+		const run = lifecycle.then(work, work);
+		lifecycle = run.then(
+			() => undefined,
+			() => undefined,
+		);
+		return run;
+	}
+
 	return {
 		open(): void {
 			if (running) return;
@@ -480,8 +546,10 @@ export function createBridge(deps: BridgeDeps): Bridge {
 				deps.saveState(state);
 			}
 			running = true;
+			paused = false;
 			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.
@@ -519,28 +587,71 @@ export function createBridge(deps: BridgeDeps): Bridge {
 			});
 		},
 
-		async close(): Promise<void> {
-			if (!running && !abort) {
+		close(): Promise<void> {
+			return serial(async () => {
+				running = false;
+				paused = false;
+				expired = false;
+				abort?.abort();
+				abort = undefined;
+				try {
+					await loopPromise;
+				} catch {
+					// Errors are surfaced by the loop's own catch.
+				}
+				loopPromise = undefined;
+				// A paused bridge has no loop and no abort controller but still owns a
+				// worker, so close it unconditionally rather than leaking the sessions.
+				const closing = worker;
+				worker = undefined;
+				await closing?.close();
+				resetEphemeral();
+				publishState();
+				releaseSafe();
+			});
+		},
+
+		pause(): Promise<boolean> {
+			return serial(async () => {
+				if (!running) return false;
+				running = false;
+				paused = true;
+				// Clear the abort controller before withdrawing the prompt: its send must
+				// not be cancelled by the poll abort that follows.
+				const stopping = abort;
+				abort = undefined;
+				if (interaction.hasPending()) interaction.cancel();
+				stopping?.abort();
+				try {
+					await loopPromise;
+				} catch {
+					// Errors are surfaced by the loop's own catch.
+				}
+				loopPromise = undefined;
+				// No poller means no lock to keep: another runtime may take the account
+				// while this one is paused. Resume reacquires it and reports a conflict.
 				releaseSafe();
 				publishState();
-				return;
-			}
-			running = false;
-			expired = false;
-			abort?.abort();
-			abort = undefined;
-			try {
-				await loopPromise;
-			} catch {
-				// Errors are surfaced by the loop's own catch.
-			}
-			loopPromise = undefined;
-			const closing = worker;
-			worker = undefined;
-			await closing?.close();
-			resetEphemeral();
-			publishState();
-			releaseSafe();
+				return true;
+			});
+		},
+
+		resume(): Promise<boolean> {
+			return serial(async () => {
+				if (!paused || expired || !worker || !account) return false;
+				if (!deps.acquireLock()) {
+					notify("Another Pi session is already polling this WeChat account.", "warning");
+					return false;
+				}
+				paused = false;
+				running = true;
+				abort = new AbortController();
+				loopPromise = poll.run(abort.signal).catch((error) => {
+					notify(`WeChat bridge stopped: ${messageOf(error)}`, "error");
+				});
+				publishState();
+				return true;
+			});
 		},
 
 		async shutdown(): Promise<void> {
@@ -565,6 +676,7 @@ export function createBridge(deps: BridgeDeps): Bridge {
 				peerStates: states,
 				open: running,
 				expired,
+				paused,
 				owner: state.ownerId ?? account?.ilinkUserId,
 				peerCount: Object.keys(state.peers).length,
 				queued: states.reduce((total, entry) => total + entry.state.queued, 0),
@@ -573,6 +685,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,13 @@ 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: "pause", description: "Stop polling new messages; running turns may finish" },
+	{ verb: "resume", description: "Resume polling after /wechat pause" },
+	{ 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 +114,102 @@ 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(),
+		}),
+	);
+}
+
+/** Pause or resume polling; the account and peer sessions stay in place. */
+async function runPauseToggle(ctx: ExtensionContext, deps: CommandDeps, resume: boolean): Promise<void> {
+	const bridge = deps.getBridge();
+	if (!bridge) {
+		ctx.ui.notify("WeChat is not running.", "warning");
+		return;
+	}
+	if (resume) {
+		if (!bridge.status().paused) {
+			ctx.ui.notify("WeChat is not paused.");
+			return;
+		}
+		const ok = await bridge.resume();
+		ctx.ui.notify(
+			ok ? "WeChat polling resumed." : "WeChat could not resume; check the terminal notice.",
+			ok ? "info" : "warning",
+		);
+		return;
+	}
+	const ok = await bridge.pause();
+	ctx.ui.notify(
+		ok
+			? "WeChat polling paused. Running turns may finish; no new messages will arrive."
+			: bridge.status().paused
+				? "WeChat is already paused."
+				: "WeChat is not running.",
+		ok ? "info" : "warning",
+	);
+}
+
+/** 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 +326,45 @@ 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.";
+					},
+					togglePause: async () => {
+						const bridge = deps.getBridge();
+						if (!bridge) return "WeChat bridge is not running.";
+						if (bridge.status().paused) {
+							return (await bridge.resume()) ? "Resumed polling." : "Could not resume; see the notice.";
+						}
+						return (await bridge.pause()) ? "Paused polling. Running turns may finish." : "WeChat is not running.";
+					},
+				},
 				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 +444,16 @@ 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 "pause":
+			return runPauseToggle(ctx, deps, false);
+		case "resume":
+			return runPauseToggle(ctx, deps, true);
 		case "stop":
 			return runPeerAction(ctx, deps, "stop", peerArg);
 		case "reset":
@@ -311,7 +469,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 | pause | resume | 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 };
 		},