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

package/extensions/todo/nudge.ts

@@ -18,12 +18,15 @@ import { TODO_TOOL } from "../../lib/tool-names.ts";
 import { currentTodo, hasOpenTodos } from "./state.ts";
 import type { Todo } from "./types.ts";
 
+/** Tools that run a command, where reading and writing look the same by name. */
+const SHELL_TOOL_NAMES: ReadonlySet<string> = new Set(["bash", "powershell"]);
+
 /**
  * Tools whose calls mean the working tree may have changed: the built-in
- * writers and shells. Kept explicit so a reader or an MCP tool that does not
+ * writers and the shells. Kept explicit so a reader or an MCP tool that does not
  * declare a hint cannot force a continuation.
  */
-export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit", "bash", "powershell"]);
+export const MUTATING_TOOL_NAMES: ReadonlySet<string> = new Set(["write", "edit", ...SHELL_TOOL_NAMES]);
 
 /**
  * Whether a finished tool call counts as work for lag detection. The `todo`
@@ -37,22 +40,68 @@ export function isMutatingTool(toolName: string, annotations?: ToolAnnotations):
 }
 
 /**
- * Whether a reminder is due: work happened since the last update, no reminder
- * was sent for it yet, and the list still has an unfinished item.
+ * Whether a finished tool call can have changed files, as opposed to a shell
+ * command that may only have read them. The reminder for a run that never
+ * started a list needs this: three `rg` calls are investigation, not unplanned
+ * work, and a shell call cannot be told apart from one that wrote. So it is a
+ * mutating call that is not a shell.
+ */
+export function isFileWrite(toolName: string, annotations?: ToolAnnotations): boolean {
+	if (toolName === TODO_TOOL || SHELL_TOOL_NAMES.has(toolName)) return false;
+	return isMutatingTool(toolName, annotations);
+}
+
+/**
+ * Successful mutating calls needed before a run with no list at all is worth a
+ * reminder. A plan that was never started has no item to fall behind, and a
+ * false positive costs a whole extra model request, so one edit is not enough
+ * evidence that the work needed a list.
+ */
+export const EMPTY_LIST_MUTATIONS = 3;
+
+/** What the current turn knows about its work and the list. */
+export interface NudgeState {
+	/** Successful mutating calls since the turn began or the list was last written. */
+	mutations: number;
+	/** How many of those can change files, as opposed to a shell command that may have read. */
+	writes: number;
+	/** Whether the model wrote or cleared the list since the turn began. */
+	touched: boolean;
+	/** Whether a reminder was already sent this turn. */
+	nudged: boolean;
+	/** The current list. */
+	todos: Todo[];
+}
+
+/**
+ * Whether a reminder is due. With an unfinished item, one mutation is enough.
+ * With no list at all, the turn must also have written something: repeated
+ * inspection with no file change is not unplanned work. A list the model wrote
+ * or cleared this turn is its own answer, so an explicit clear is never
+ * second-guessed.
  */
-export function shouldNudge(dirty: boolean, nudged: boolean, todos: Todo[]): boolean {
-	return dirty && !nudged && hasOpenTodos(todos);
+export function shouldNudge({ mutations, writes, touched, nudged, todos }: NudgeState): boolean {
+	if (nudged || mutations <= 0) return false;
+	if (hasOpenTodos(todos)) return true;
+	return todos.length === 0 && !touched && writes > 0 && mutations >= EMPTY_LIST_MUTATIONS;
 }
 
 /** Marker on the injected reminder, so it is recognizable and filterable. */
 export const TODO_NUDGE_MARKER = "[TODO SYNC]";
 
 /**
- * Model-facing reminder injected before settlement. Points at the item the list
- * currently considers active, so the model can correct it without rereading the
- * whole list.
+ * Model-facing reminder injected before settlement. For a list with unfinished
+ * work it points at the item the list currently considers active, so the model
+ * can correct it without rereading the whole list; for no list at all it asks
+ * for one.
  */
 export function formatNudge(todos: Todo[]): string {
+	if (todos.length === 0) {
+		return (
+			`${TODO_NUDGE_MARKER} Work happened but no todo list was recorded. ` +
+			"Call the todo tool with the steps of this work, then continue."
+		);
+	}
 	const current = currentTodo(todos);
 	const item = current ? (current.activeForm ?? current.content) : undefined;
 	const pointer = item ? ` The list still points at "${item}".` : "";

package/extensions/todo/runtime.ts

@@ -4,10 +4,10 @@
  *
  * The list is reconstructed from the active branch on session start and tree
  * navigation, and the persistent widget mirrors it whenever it changes. Only
- * interactive (`tui`) sessions get a widget; the widget's row budget and
- * whether a finished list stays visible come from the todo config. The same
- * runtime carries the lag-tracking flags the `agent_before_settle` reminder
- * reads, so they reset with the session and the branch.
+ * interactive (`tui`) sessions get a widget; whether a finished list stays
+ * visible comes from the todo config. The same runtime carries the lag-tracking
+ * counters the `agent_before_settle` reminder reads, so they reset with the
+ * session and the branch.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -27,8 +27,8 @@ export interface TodoRuntime {
 	reconstruct(ctx: ExtensionContext): void;
 	/** Apply the widget config (loaded per session). */
 	setConfig(config: TodoConfig): void;
-	/** Record that a mutating tool ran since the last update. */
-	noteWork(): void;
+	/** Record a successful mutating call; `fileWrite` marks one that can change files. */
+	noteWork(fileWrite?: boolean): void;
 	/** Whether a lag reminder is due and has not been sent for it yet. */
 	nudgeDue(): boolean;
 	/** Mark the current lag as reminded, activating the injected reminder. */
@@ -53,11 +53,15 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 	let lastTuiCtx: ExtensionContext | undefined;
 	// True while a dock screen owns the editor slot; the rail stays hidden.
 	let suppressed = false;
-	// Lag tracking: `dirty` is set when a mutating tool runs and cleared by a
-	// todo update, `nudged` caps the reminder to one per user turn, and
-	// `nudgeActive` marks an injected reminder as current so `context` keeps it
-	// for the continuation and drops it on the next user turn.
-	let dirty = false;
+	// Lag tracking: `mutations` counts successful mutating calls since the list
+	// was last written and `writes` how many of those can change files,
+	// `touched` records that the model wrote or cleared the list this turn (so an
+	// explicit clear is not second-guessed), `nudged` caps the reminder to one per
+	// user turn, and `nudgeActive` marks an injected reminder as current so
+	// `context` keeps it for the continuation and drops it on the next user turn.
+	let mutations = 0;
+	let writes = 0;
+	let touched = false;
 	let nudged = false;
 	let nudgeActive = false;
 	// Screens watching the list (for example the open `/todos` screen) so they
@@ -104,13 +108,17 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 			todos = next;
 			// A todo update is the model syncing the list, so the lag is cleared.
 			// `nudged` is not: the reminder stays capped at one per user turn.
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = true;
 			syncWidget(ctx);
 			notify();
 		},
 		reconstruct: (ctx) => {
 			todos = reconstructTodos(ctx.sessionManager.getBranch());
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = false;
 			nudged = false;
 			nudgeActive = false;
 			syncWidget(ctx);
@@ -119,10 +127,11 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 		setConfig: (next) => {
 			config = next;
 		},
-		noteWork: () => {
-			dirty = true;
+		noteWork: (fileWrite = false) => {
+			mutations++;
+			if (fileWrite) writes++;
 		},
-		nudgeDue: () => shouldNudge(dirty, nudged, todos),
+		nudgeDue: () => shouldNudge({ mutations, writes, touched, nudged, todos }),
 		markNudged: () => {
 			nudged = true;
 			nudgeActive = true;
@@ -132,7 +141,9 @@ export function createTodoRuntime(pi?: Pick<ExtensionAPI, "events">): TodoRuntim
 		},
 		isNudgeActive: () => nudgeActive,
 		resetNudge: () => {
-			dirty = false;
+			mutations = 0;
+			writes = 0;
+			touched = false;
 			nudged = false;
 		},
 		onChange: (listener) => {

package/extensions/web-access/README.md

@@ -96,7 +96,7 @@ and unknown keys are ignored.
 {
   "search": {
     "provider": "auto",                                    // "auto" | "duckduckgo" | "searxng" | "brave"
-    "endpoint": "http://localhost:8080",                   // SearXNG base URL; "" means SearXNG is unavailable
+    "endpoint": "",                                        // SearXNG base URL, e.g. "http://localhost:8080"; "" means SearXNG is unavailable
     "language": "auto",                                     // SearXNG: "auto" (zh-CN for Han, else en) | language code
     "safeSearch": 0,                                        // SearXNG: 0 off, 1 moderate, 2 strict
     "categories": "general",                                // SearXNG categories
@@ -264,9 +264,9 @@ the content type and size.
 
 | Integration point | Value |
 |---|---|
-| Tools | `web_search`, `web_fetch`; `exposure: "direct"`, both `defaultActive: true` |
+| Tools | `web_search`, `web_fetch`; direct exposure, active on registration (the defaults, so not declared) |
 | Execution mode | `web_search`: `sequential`; `web_fetch`: default |
-| Annotations | both `readOnlyHint: true`, `openWorldHint: true`, `destructiveHint: false` |
+| Annotations | both `readOnlyHint: true`, `openWorldHint: true`; a read-only tool declares no `destructiveHint` |
 | Output | `outputSchema` (`WebSearchOutput` / `WebFetchOutput`) plus matching `structuredContent` |
 | State | none in the session branch; one fetch page cache per registration (`web_search` keeps a per-instance throttle) |
 | Lifecycle | the factory only registers (`index.ts`); `registerFetchTool` owns the page cache and clears it on `session_start` and idempotent `session_shutdown` |

package/extensions/web-access/fetch/tool.ts

@@ -191,9 +191,7 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 		],
 		parameters: WebFetchParams,
 		outputSchema: WebFetchOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: true, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: true },
 		// The page cache is shared in-memory state created per registration, so
 		// sibling calls must not run concurrently (matches web_search's throttle).
 		executionMode: "sequential",

package/extensions/web-access/search/tool.ts

@@ -46,9 +46,7 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 		],
 		parameters: WebSearchParams,
 		outputSchema: WebSearchOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: true, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: true },
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {

package/extensions/wechat/README.md

@@ -76,6 +76,8 @@ 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. |
@@ -108,10 +110,18 @@ what is queued behind it), activity counters, and the waiting remote prompt
 `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.
+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
@@ -262,7 +272,7 @@ overridden by the project `<cwd>/.pi/bytefly.json` (project wins):
   "maxInboundChars": 8000, // inbound text longer than this is truncated
   "typingIndicator": true,   // show typing while a turn is generated
   "remotePrompts": true,     // answer interactive dialogs on WeChat during a WeChat turn
-  "pollHoldMs": 0            // experimental: ask the server for a shorter long-poll hold
+  // "pollHoldMs": 3000      // experimental: request a shorter long-poll hold; unset by default
 }
 ```
 
@@ -382,8 +392,9 @@ never touches the stored cursor.
   supplies a `context_token` only then).
 - Slash commands are fixed built-ins; there is no user-defined snippet or action
   list yet, and `/new`, `/stop`, `/status`, and `/help` are registered.
-- There is no pause. The bridge runs whenever an account is stored, and
-  `/wechat logout` is the only way to stop it (and it discards the credentials).
+- Pause is runtime-local. `/wechat pause` stops polling and releases the lock,
+  but a reload, `/new`, or restart builds a fresh running bridge; only
+  `/wechat logout` stops it persistently (and discards the credentials).
 
 ## Non-goals
 
@@ -395,16 +406,16 @@ sessions are in-process).
 
 | Integration point | Detail |
 |---|---|
-| 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`. |
+| 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 direct exposure (the default), `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
 

package/extensions/wechat/bridge.ts

@@ -65,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;
@@ -107,6 +107,8 @@ 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;
@@ -146,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;
@@ -165,6 +171,7 @@ 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;
@@ -195,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()`.
@@ -491,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;
@@ -523,6 +546,7 @@ export function createBridge(deps: BridgeDeps): Bridge {
 				deps.saveState(state);
 			}
 			running = true;
+			paused = false;
 			expired = false;
 			resetEphemeral();
 			startedAt = deps.now();
@@ -563,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> {
@@ -609,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),

package/extensions/wechat/commands.ts

@@ -61,6 +61,8 @@ 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>" },
@@ -124,6 +126,36 @@ async function runDoctor(ctx: ExtensionContext, deps: CommandDeps): Promise<void
 	);
 }
 
+/** 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) {
@@ -313,6 +345,14 @@ async function runPanel(ctx: ExtensionCommandContext, deps: CommandDeps): Promis
 						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(),
 			}),
@@ -410,6 +450,10 @@ async function dispatch(
 			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":
@@ -425,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 | doctor | stop | reset | history | allow | 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/doctor.ts

@@ -34,6 +34,7 @@ function age(now: number, at: number | undefined): string {
 }
 
 function connection(status: BridgeStatus | undefined, account: BotCredentials | undefined, now: number): string {
+	if (status?.paused) return "paused · run /wechat resume";
 	if (!status?.open) {
 		return status?.expired ? "expired · run /wechat login" : "closed";
 	}

package/extensions/wechat/index.ts

@@ -43,6 +43,8 @@ export function wechatChip(theme: Theme, state: BridgeState): string | undefined
 			return paint(theme, "ok", `${GLYPHS.wechat} wechat`);
 		case "expired":
 			return paint(theme, "bad", `${GLYPHS.wechat} wechat expired`);
+		case "paused":
+			return paint(theme, "warn", `${GLYPHS.wechat} wechat paused`);
 		case "stopped":
 			return undefined;
 	}
@@ -154,7 +156,7 @@ export default function wechat(pi: ExtensionAPI, deps: WechatDeps = {}): void {
 	const autoStart = (ctx: ExtensionContext): void => {
 		if (ctx.mode !== "tui" && ctx.mode !== "rpc") return;
 		if (!primaryAccount()) return;
-		if (bridge?.status().open) return;
+		if (bridge?.status().open || bridge?.status().paused) return;
 		try {
 			bridge = bridge ?? build(ctx);
 			bridge.open();