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

package/{extensions/wechat/README.md → docs/extensions/wechat.md}

@@ -1,76 +1,130 @@
 # wechat — a WeChat bridge with one Pi conversation per peer
 
 Connect Pi to WeChat over Tencent's Weixin iLink bot API. Each admitted sender
-gets their own Pi session - own history, own model context, the package's tools -
+gets their own Pi session — own history, own model context, the package's tools —
 so a WeChat message starts a turn immediately and the terminal conversation is
 never mixed into it. The sessions live in-process through the Pi SDK; there is no
 subprocess per peer.
 
-```
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet in a tagged release, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+### Conversation
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| One session per peer | automatic: an inbound message | Each admitted sender gets their own Pi session — history, model context, tools — resumed on the next message. | Shipped |
+| Per-message turn | automatic: the wait timers | Each message gets its own turn and answer; a wait is acknowledged once, and an empty or failed turn says so. | Shipped |
+| Inbound media | automatic: an inbound image or file | Images arrive as model image content, files are saved and referenced by path, and voice uses the server's transcript. | Shipped |
+| Isolated terminal | automatic: an inbound message | A WeChat turn runs in the peer's session, so the terminal transcript never sees the exchange. | Shipped |
+| Two peers at once | `PEER_CONCURRENCY` | Two peers' turns run concurrently; a third waits in a fair queue and is acknowledged. | Unreleased |
+| Inbound replay safety | automatic: the WeChat message id | A replayed message id is answered once, remembered for an hour across a reconnect or reload. | Shipped |
+| Inbound text cap | `maxInboundChars` | Text past the configured cap is truncated with a marker instead of becoming an unbounded prompt. | Shipped |
+| Peer language | automatic: a message written in Chinese | Notices and `/help` answer in the peer's language, and a neutral reply does not switch it back. | Shipped |
+| Peer slash commands | `/new`, `/stop`, `/status`, `/history`, `/help` | The peer restarts, stops, inspects, or asks for help without spending a turn. | Shipped |
+| Fresh host session | `/wechat new` | A new terminal session starts; every peer conversation keeps running and stays on disk. | Shipped |
+| Typing indicator | `typingIndicator` | The phone can tell a long turn from a dead bridge. | Shipped |
+
+### Remote control
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Plan review over chat | automatic: an `exit_plan_mode` on a WeChat turn | The plan arrives as a file, then one compact editor prompt with three actions. | Shipped |
+| Forwarded dialogs | `remotePrompts` | A dialog raised inside a WeChat turn is asked and answered in that peer's chat. | Shipped |
+| Peer questions | `ask_user_question` | The peer answers their own question, numbered, and a reply cannot reach another peer's prompt. | Shipped |
+| Control screen | `/wechat` | Account, connection, per-peer rows, activity, and any waiting prompt on one live screen. | Shipped |
+| Prompt cancellation | `/wechat`, `c` on the control screen | One waiting question is withdrawn with a notice, without stopping the peer's turn. | Shipped |
+| Peer steering | `/wechat stop <peer>`, `/wechat reset <peer>` | One peer's running turn stops, or their conversation starts fresh. | Shipped |
+
+### Security and admission
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Owner-only admission | `allowedPeers`, `/wechat allow [peer]` | Only the owner who scanned the QR drives the agent until another sender is named. | Shipped |
+| Per-peer tool allowlist | `peers[<id>].tools` | An extra admitted peer can be narrowed to named tools; an empty list leaves none. | Shipped |
+| One poller per account | `poller.lock` | A second `pi` process is refused instead of stealing the account's messages. | Shipped |
+
+### Delivery and reliability
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Streamed replies | automatic: the reply pipeline | A long answer arrives as it is produced, not as one long silence. | Shipped |
+| Proactive message | `send_wechat` | The model messages the owner one text or one local image, sent as a picture. | Partial |
+| Abandoned-turn notice | automatic: shutdown, `/reload`, `/new`, logout | Each peer with work gets one line saying the turn stopped, rather than silence. | Unreleased |
+| Outbound files | the upload flow, `askHuman` | A remote prompt can deliver a local file before its question, and a failed upload falls back to text. | Shipped |
+| Plain chat text | `maxReplyChars` | Markdown markers are flattened, and a part still over the limit is numbered. | Shipped |
+
+### Pairing and transport
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| QR login | `/wechat login` | One scan stores the account and the bridge starts polling it, replacing a running poller. | Shipped |
+| Reconnect after expiry | `/wechat login`, `l` on the control screen | A fresh login clears the expired chip and starts a new worker instead of leaving a dead token. | Shipped |
+| Automatic start | `session_start`, a stored account | The bridge runs whenever credentials exist: the account is the on/off switch, so there is no start command. | Shipped |
+| Pause and resume | `/wechat pause`, `/wechat resume` | Polling stops while running turns finish, the lock is released, and resume takes it back. | Shipped |
+| Status chip | `/wechat status` | The status bar names the state — `✆ wechat`, `✆ wechat paused`, or a persistent `✆ wechat expired`. | Shipped |
+| Logout | `/wechat logout` | One confirmation discards the credentials and stops polling. | Shipped |
+
+### Upkeep
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Health report | `/wechat doctor` | Connection, token age, last poll, lock holder, per-peer queues, and recent failures in one read-only report. | Shipped |
+| Idle session cleanup | automatic: the 30-minute idle sweep | An idle peer's Pi session is disposed, so idle conversations do not keep costing context or memory. | Shipped |
+| Peer history | `/wechat history <peer> [n]` | That peer's recent messages, ten by default and twenty at most, without a live session. | Shipped |
+| Command help | `/wechat help` | Every subcommand with a line each, printed in the transcript. | Shipped |
+
+## Quickstart
+
+```bash
 pi --extension ./extensions/wechat   # load just this extension
 pi -e .                              # load the whole @gavin-hu/my-pi-agent package
-pi install ./                        # install the package
+pi install ./                        # install the package for a user
 ```
 
-## Tool rendering
+```text
+/wechat login    # scan the QR with the WeChat app; the bridge starts on the scan
+/wechat          # the control screen: account, connection, peers, waiting prompt
+```
 
-How the `send_wechat` call and its result look in the transcript — the call line as a headline and the body indented under it:
+The account is the on/off switch: once one is stored, `session_start` opens the
+bridge, so there is no start command to run.
+
+## Tool
 
 <img src="../../assets/tools/send_wechat.png" alt="The send_wechat tool's call and result: the call line and an indented body with the message text and the sent confirmation" width="100%">
 
-## What it does
-
-- **Inbound** — one long-poll loop receives WeChat text, images, and files and
-  hands them to the sender's own session; that turn's text is sent back to the
-  sender. Nothing is injected into the terminal session, so the two
-  conversations cannot contaminate each other.
-- **One conversation per peer** — a session per admitted peer, persisted under
-  `<agent-dir>/wechat/sessions/<peer>/`, resumed on the next message and disposed
-  after half an hour idle. Turns run one at a time across peers by default, so a
-  forwarded dialog always has a single owner.
-- **Inbound media** — images are downloaded, AES-128-ECB decrypted, and attached
-  as model image content; files are saved under `<agent-dir>/wechat/media/` and
-  referenced by path. Voice uses the transcript the server provides. An
-  attachment the bridge could not read (too large, a failed download, no key) is
-  reported to the peer and to the model instead of vanishing.
-- **Outbound** — replies stream to the chat as they are produced: a part goes out
-  at each paragraph boundary, after two silent seconds, or at 400 characters,
-  whichever comes first, so a long answer is not one long silence. Text is plain
-  chat text (Markdown fences, headings, and emphasis markers are flattened), and
-  a single part longer than `maxReplyChars` still arrives in numbered parts. The
-  owner-only `send_wechat` tool lets the model message the owner proactively; it
-  is refused while a turn with that peer is in flight, so the answer cannot
-  arrive twice.
-- **Typing indicator** — the native typing status is set as soon as a message is
-  queued and refreshed for as long as the turn runs (`typingIndicator`, on by
-  default), so the phone can tell a long turn from a dead bridge.
-- **Peer feedback** — a burst that arrives while a turn is still running is
-  answered once, a message waiting on another conversation is acknowledged once,
-  a slow turn says so, and a turn that ends without text says so instead of going
-  quiet. Notices and `/help` follow the peer's language: a Chinese message sets it,
-  and a language-neutral reply (`1`, `ok`) does not switch it back. The peer can
-  also stop (`/stop`), restart (`/new`), and ask what is happening (`/status`).
-- **Remote prompts** — the peer session's own UI is bound to that peer, so
-  `ask_user_question`, plan approval, and any other dialog raised inside a
-  WeChat turn is sent to WeChat and answered there. Terminal turns keep the TUI,
-  including while a peer turn runs (`remotePrompts`, on by default).
-- **Status chip** — the status bar shows `✆ wechat` while the bridge runs and
-  keeps an error-colored `✆ wechat expired` after a session expiry
-  (`ctx.ui.setStatus`), so the outage stays visible until `/wechat login`
-  reconnects or `/wechat logout` stops the bridge; it clears on shutdown.
-- **Owner-only by default** — only the account owner (who scanned the login QR)
-  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. `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.
+`send_wechat` — direct exposure (the default), `executionMode: "sequential"`,
+read-write, open-world. It messages the account owner and nobody else: the
+recipient is not a parameter, so untrusted generated text cannot be aimed at
+another account. Give exactly one of `text` or `image`; neither or both is
+refused with the reason. A text send is also refused while a turn with the owner
+is in flight, because the bridge is already answering it, while an image is
+allowed there — an image cannot duplicate the streamed answer.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `text` | string, optional | Plain text, 1–4000 characters. |
+| `image` | string, optional | Path to a local image, up to 4096 characters; the bytes must sniff as an image. |
+
+Result (`details` / `structuredContent`): `{ sent, error? }`. A failed send is an
+error result carrying the same shape, so the model can report what went wrong.
+
+```text
+send_wechat({ text: "The build is green again." })
+send_wechat({ image: "/tmp/plot.png" })
+```
+
+The call line carries the message text, or an image's file name rather than its
+path; the result is one line — `sent to WeChat owner`, or the failure with a
+reason.
 
 ## Commands
 
+`/wechat` is one command with a verb table: a bare `/wechat` opens the control
+screen, and every subcommand is the same action one of the screen's keys runs.
+
 | Command | Effect |
 |---|---|
 | `/wechat` | TUI: the control screen. Elsewhere: a one-line summary. |
@@ -104,6 +158,8 @@ A session that expires while running keeps the `✆ wechat expired` chip:
 `/wechat status` reports it and points at the fix, and `/wechat login` is the
 one-step recovery.
 
+### The control screen
+
 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 the waiting remote prompt
@@ -117,7 +173,18 @@ polling. `l` logs in or reconnects, `n` starts a new session, `o` logs out,
 actions and the only route outside the TUI; an unknown subcommand reports the
 valid ones.
 
-<img src="../../assets/wechat.png" alt="The /wechat control screen: account and an open connection, peer, queued, refused, and waiting-prompt rows, three conversation rows showing running, queued, and idle states, and the key hints" width="100%">
+<img src="../../assets/screens/wechat.png" alt="The /wechat control screen: account and an open connection, peer, queued, and refused rows, one waiting-prompt row per peer that was asked a question, three conversation rows showing two running peers with one queued behind them and an idle peer, and the key hints" width="100%">
+
+### Admission
+
+An entry in `allowedPeers` 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. `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.
+
+### Pause and resume
 
 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,
@@ -126,6 +193,8 @@ 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.
 
+### While a peer turn runs
+
 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
 one-line summary, and `login`/`logout`/`new` reply that they are unavailable
@@ -134,7 +203,7 @@ until the turn finishes. (`login`/`logout` would drop the connection mid-turn an
 unanswered.) The terminal's own dialogs are unaffected: they are never forwarded
 to a peer.
 
-## Slash commands
+### Peer slash commands
 
 A peer can type a slash command in the chat. The bridge intercepts it before it
 becomes a turn, so a command never reaches the model unless it is unknown.
@@ -166,6 +235,57 @@ becomes a turn, so a command never reaches the model unless it is unknown.
 | `rpc` | The bridge auto-starts and `status` prints the one-line summary; `login` needs the TUI (the QR screen is unavailable over RPC), while `logout`'s confirmation is forwarded through the RPC UI protocol like any other dialog. |
 | `json`, `print` | Ephemeral; the bridge does not auto-start and no UI is available, so `logout` reports that it needs a confirmation dialog instead of failing silently. |
 
+## Configuration
+
+The `wechat` section of the shared `bytefly.json`, the global document overridden
+by the project `<cwd>/.pi/bytefly.json` (project wins); resolution rules and every
+default are in
+[`../configuration.md`](../configuration.md#wechat--the-wechat-bridge).
+
+```jsonc
+// bytefly.json → "wechat"
+{
+  "allowedPeers": [],        // extra peers, by id or label (alice / alice@im.wechat)
+  "peers": {},              // per-peer overrides, e.g. { "alice": { "tools": ["read", "todo"] } }
+  "maxTurnsPerHour": 0,     // turns per peer per rolling hour; 0 = unlimited
+  "maxReplyChars": 4000,     // replies longer than this are split into messages
+  "botAgent": "pi-wechat",   // sent as base_info.bot_agent
+  "channelVersion": "0.1.0", // sent as base_info.channel_version
+  "cdnBaseUrl": "https://novac2c.cdn.weixin.qq.com/c2c", // CDN media base
+  "maxMediaBytes": 20971520, // inbound media larger than this is skipped
+  "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": 3000      // experimental: request a shorter long-poll hold; unset by default
+}
+```
+
+State lives under `<agent-dir>/wechat/`: `credentials.json` (mode `0600`, every
+stored account plus the active one), `state.json` (cursor, owner, per-peer reply
+tokens, and recently handled message ids), `media/` (downloaded inbound files),
+`sessions/<peer>/` (one conversation per peer), and `poller.lock` (stops two
+sessions polling one account).
+
+## Security
+
+- WeChat text is **untrusted**, and in this design it becomes a turn in your live
+  session **with that session's tools** (including `bash`/`write`/`edit`).
+  Admission control is the only gate: the default is **owner-only**, and
+  `allowedPeers` is an explicit opt-in. A refused sender is counted and named in
+  `/wechat status`, not run. `peers[<id>].tools` narrows an admitted peer to a
+  tool allowlist (an empty list leaves it with none), so an extra peer need not
+  get `bash`.
+- Inbound text is sanitized (control characters stripped) before it reaches the
+  transcript.
+- Inbound media is **untrusted**: images become model image content, and files
+  are saved under `<agent-dir>/wechat/media/` with sanitized names and a size cap
+  (`maxMediaBytes`). Inbound text is capped by `maxInboundChars` before it reaches
+  the model, and a replayed message id is answered once. Nothing is executed.
+- Credentials are written `0600` and redacted from diagnostics; egress is only to
+  the Weixin endpoint.
+- Automated or unofficial WeChat use can violate WeChat's terms and risk account
+  restriction. Single-owner, low-volume use is recommended.
+
 ## What the peer experiences
 
 The peer has only the chat window, so the bridge carries the signals the phone
@@ -174,20 +294,23 @@ needs. Per action:
 | Peer action | What they see |
 |---|---|
 | Sends a message | The native typing indicator starts as soon as the message is picked up; the answer is sent when the run settles. |
-| Sends several messages quickly | At most one acknowledgement, then a single answer that covers the burst in order. |
+| Sends several messages quickly | Each message is its own turn; one acknowledgement per wait, then the answers in order. |
+| Waits behind two running peers | One line after four seconds, then one more at a minute (`前面还有一条正在处理…` / “Your message is queued behind another conversation…”), and the answer when a slot frees. The next free slot goes to whoever has been waiting longest. |
 | Waits behind a long turn | The indicator keeps refreshing, and after four seconds one short `收到，正在排队，轮到就回你。` / “Got it — queued; I’ll answer when it’s my turn.”; a turn still running at 30 seconds adds one `还在处理这条，发送 /stop 可取消。` / “Still working — send /stop to cancel.”, so the way out is named when it is wanted. |
-| Sends while another peer's turn runs | One line after four seconds, then one more at a minute (`前面还有一条正在处理…` / “Your message is queued behind another conversation…”), and the answer when the slot frees. |
+| Sends while another peer's turn runs | Both conversations are answered in parallel, each with its own typing indicator and its own place in a dialog. |
 | Sends a photo or a file | The model reads it; an attachment that could not be read (too large, a failed download, no key) is named in the answer. |
+| Is sent an image by the bot | A picture in the chat, from `send_wechat` with a local path, not a document attachment. |
 | Sends a voice note or video | One line: voice without a transcript and video are not supported. |
 | Reads a long answer | Streamed as it is produced — one part per paragraph, per two silent seconds, or per 400 characters — and numbered (`[1/3] …`) only when a single part exceeds `maxReplyChars`. |
 | Reads an answer | Plain chat text — Markdown fences, headings, and emphasis markers are flattened, code-block bodies survive. |
-| Is asked a question | A numbered prompt; 确定/是/yes or 不是/否/no answers it, 取消 dismisses. Ignored, it is nudged at the halfway point of its window and then cancelled: three minutes for a dialog, ten for a plan review, where the plan has to be read first. |
+| Is asked a question | Their own prompt, never another peer's: a reply answers the question their own conversation is blocked on. A numbered prompt; 确定/是/yes or 不是/否/no answers it, 取消 dismisses. Ignored, it is nudged at the halfway point of its window and then cancelled: three minutes for a dialog, ten for a plan review, where the plan has to be read first. |
 | Types `/help`, `/new`, `/stop`, or `/status` | The command list, a fresh conversation, a stopped answer, or the current state — including the dialog a blocked turn is waiting on; `/new` is declined while their run is in flight. A command works while a dialog waits: it is never read as an answer to it. |
 | Types `/history` | The last eight messages of this conversation (or the requested number, up to 20), one line each. |
 | Floods the chat | Past eight queued messages, one line asking to wait rather than an unbounded queue. |
 | Sends the same message twice (a server replay) | Answered once: the WeChat message id is remembered for an hour, across a reconnect or reload. |
 | Pastes a very long message | The first `maxInboundChars` characters reach the model, followed by a truncation marker, instead of an unbounded prompt. |
 | Gets an aborted turn | `已停止。` / “Stopped.” |
+| Exits, reloads, or forks mid-turn | One line: `会话已停止，这条还没答完。恢复后再发一次即可。` / “The session stopped before this answer finished — send it again when it's back.”, sent to every peer that still had work before the connection closes. |
 | Gets a turn that produced no text | `这条处理完了，但没有文字输出。` / “That turn finished without any text to send.” |
 | Gets a turn that could not start | `处理失败，请稍后重试。` / “Something went wrong — please try again.”, and the terminal says why. |
 | Keeps messaging an expired or logged-out bridge | Nothing — the bot goes quiet, and only the terminal chip says why. |
@@ -223,9 +346,10 @@ A dialog raised while a WeChat turn is in flight is forwarded to the sender:
   so, so a plan review without it does not pretend free text is a choice.
 - `confirm` — reply 是/否, 确定/不是, or yes/no.
 - `input` / `editor` — reply with the text.
-- Reply 取消 (or cancel) to dismiss; `退出`, `退出 plan 模式`, and
-  `exit plan mode` are recognized as cancel intent. In a plan review a dismissal
-  leaves plan mode without approving.
+- Reply 取消 (or cancel, quit, exit, 退出) to dismiss. In a plan review a
+  dismissal leaves plan mode without approving, and a reply the three actions do
+  not name — `exit plan mode`, or 退出 plan 模式 — is feedback the model applies
+  before asking again.
 - Hints are rendered in the peer’s language, one language per prompt. A reply
   that cannot be read re-sends the prompt with a short “didn’t recognize that”
   notice instead of repeating it silently.
@@ -239,9 +363,10 @@ A dialog raised while a WeChat turn is in flight is forwarded to the sender:
   dialog cannot freeze the session. A dialog uses three minutes; the plan review
   uses ten. A timed-out plan review is treated like a dismissal: plan mode ends
   without approval, and the plan file remains.
-- A prompt that goes away before it is answered — a pause, a `/stop`, a shutdown —
-  says so (`问题已撤回。` / “That question was withdrawn.”) instead of reusing the
-  timeout line: the peer was not slow, the question left.
+- A prompt that goes away before it is answered says so: a pause withdraws it with
+  `问题已撤回。` / “That question was withdrawn.”, a `/stop` ends its turn with
+  `已停止。`, and a shutdown reports the abandoned turn — the peer was not slow, the
+  question or the session left.
 
 Each peer session is created with its own UI context (`bindExtensions` with
 `mode: "rpc"`), so its dialogs go to that peer by construction rather than by
@@ -262,39 +387,11 @@ calls `cancel_plan_mode`, which needs no plan path and records no todo or goal.
 The flow mirrors the
 reference client: `getuploadurl` → AES-128-ECB encrypt → `POST` the ciphertext
 (`Content-Type: application/octet-stream`) → read `x-encrypted-param` → send a
-`type: 4` file item. No current flow uses it; images, video, and voice are not
-sent outbound.
-
-## Configuration
-
-The `wechat` section of the shared `bytefly.json`, the global document
-overridden by the project `<cwd>/.pi/bytefly.json` (project wins):
-
-```jsonc
-// bytefly.json → "wechat"
-{
-  "allowedPeers": [],        // extra peers, by id or label (alice / alice@im.wechat)
-  "peers": {},              // per-peer overrides, e.g. { "alice": { "tools": ["read", "todo"] } }
-  "maxTurnsPerHour": 0,     // turns per peer per rolling hour; 0 = unlimited
-  "maxReplyChars": 4000,     // replies longer than this are split into messages
-  "botAgent": "pi-wechat",   // sent as base_info.bot_agent
-  "channelVersion": "0.1.0", // sent as base_info.channel_version
-  "cdnBaseUrl": "https://novac2c.cdn.weixin.qq.com/c2c", // CDN media base
-  "maxMediaBytes": 20971520, // inbound media larger than this is skipped
-  "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": 3000      // experimental: request a shorter long-poll hold; unset by default
-}
-```
-
-State lives under `<agent-dir>/wechat/`: `credentials.json` (mode `0600`, every
-stored account plus the active one), `state.json` (cursor, owner, per-peer reply
-tokens, and recently handled message ids), `media/` (downloaded inbound files),
-`sessions/<peer>/` (one conversation per peer), and `poller.lock` (stops two
-sessions polling one account).
+`type: 4` file item. The plan review is the flow that uses it; `send_wechat`
+uploads an image over the same path as a `type: 2` item, while video and voice
+are not sent outbound.
 
-### The long-poll hold
+## The long-poll hold
 
 A WeChat message is only visible to Pi when a `getupdates` request returns, and
 the server decides how long it holds one. Measured here: **~18 s**, which is the
@@ -306,7 +403,7 @@ different value is not documented, so it is opt-in and unset by default. To find
 out on your account, quit `pi` and run this from a repository checkout:
 
 ```bash
-bun scripts/wechat-poll-probe.ts 3000
+bun run probe:wechat 3000
 ```
 
 It prints the requested hold, the measured one, and the value the server echoed,
@@ -314,25 +411,11 @@ then says whether the request was honoured. It refuses to run while a bridge is
 polling (two clients on one account can steal each other's messages), and it
 never touches the stored cursor.
 
-## Security
-
-- WeChat text is **untrusted**, and in this design it becomes a turn in your live
-  session **with that session's tools** (including `bash`/`write`/`edit`).
-  Admission control is the only gate: the default is **owner-only**, and
-  `allowedPeers` is an explicit opt-in. A refused sender is counted and named in
-  `/wechat status`, not run. `peers[<id>].tools` narrows an admitted peer to a
-  tool allowlist (an empty list leaves it with none), so an extra peer need not
-  get `bash`.
-- Inbound text is sanitized (control characters stripped) before it reaches the
-  transcript.
-- Inbound media is **untrusted**: images become model image content, and files
-  are saved under `<agent-dir>/wechat/media/` with sanitized names and a size cap
-  (`maxMediaBytes`). Inbound text is capped by `maxInboundChars` before it reaches
-  the model, and a replayed message id is answered once. Nothing is executed.
-- Credentials are written `0600` and redacted from diagnostics; egress is only to
-  the Weixin endpoint.
-- Automated or unofficial WeChat use can violate WeChat's terms and risk account
-  restriction. Single-owner, low-volume use is recommended.
+The same run answers a second question: every message it receives is printed with
+the `group_id` and `session_id` the protocol supplied, when it supplied them.
+Nothing in the bridge routes on either — a conversation is keyed by sender — so a
+message posted in a group is the only way to learn whether rooms are delivered at
+all, which is what the roadmap's group-chat item turns on.
 
 ## Troubleshooting
 
@@ -373,11 +456,12 @@ never touches the stored cursor.
 - An expired bridge or a `/wechat logout` is silence on the phone: the token that
   would carry a notice is the one that expired, so only the terminal chip and
   `/wechat status` say what happened.
-- Turns run one at a time across peers, fixed at one: a second peer's message
-  waits for the first peer's turn. That keeps a forwarded dialog unambiguous
-  (the shared interaction channel has one owner); a peer who is waiting is
-  acknowledged and told why. More concurrency needs a per-peer channel, not a
-  config value.
+- Two peers' turns run at once (`PEER_CONCURRENCY`), not more, and it is not a
+  setting: every extra concurrent turn is a full model run on the user's budget.
+  A third peer's message waits in a fair queue — the oldest wait takes the next
+  free slot, so a talkative peer cannot starve a quiet one — and that peer is
+  acknowledged and told why. A forwarded dialog stays unambiguous because each
+  peer has its own interaction channel.
 - Each peer conversation is a full Pi session: it carries its own context and
   costs its own model tokens, and it loads the package's tools (minus this
   bridge) in the same workspace. The idle sweep disposes a session after 30
@@ -389,40 +473,49 @@ never touches the stored cursor.
 - Parts are flushed at a paragraph boundary, after two silent seconds, or at 400
   characters, so an answer that stalls mid-paragraph still arrives in pieces. A
   part that is itself longer than `maxReplyChars` is numbered.
-- A `/wechat new`, `/reload`, fork, or process exit during a WeChat turn abandons
-  that turn's reply: the shutdown aborts the send, and the peer gets nothing.
+- An abandoned turn's notice is one attempt, not a queue. Any close — `/wechat
+  new`, `/reload`, a fork, a logout, or a process exit — sends one short line per
+  peer that still had work, and a queued message shares its peer's line rather
+  than earning its own bubble. It needs a live connection: a notice the transport
+  cannot deliver within five seconds is reported on the terminal and dropped, not
+  retried. The one close that stays silent is the worker an expired connection
+  replaces on reconnect, whose token is already dead.
 - Inbound **video** is not handled, and there is no group-chat support. Voice is
   handled only through the server-provided transcript. Both are answered with a
   one-line notice rather than being dropped silently, and a voice note the
   server gave no transcript for is treated the same way.
-- Outbound **files** are supported (used by the plan review); outbound images,
-  video, and voice are not, and `send_wechat` sends text only.
+- Outbound **files** are supported (used by the plan review), and so are
+  **images**, which `send_wechat` sends as a picture when given a local path whose
+  bytes sniff as one. Outbound video and voice are not supported.
 - Remote prompts cover the standard dialogs (`select`/`confirm`/`input`/`editor`).
   A full-screen `ctx.ui.custom` component cannot be answered over WeChat: a peer
   session's UI context refuses it, exactly like RPC mode.
 - A peer can only be replied to after they have messaged first (the protocol
   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.
+  list yet, and `/new`, `/stop`, `/status`, `/history`, and `/help` are
+  registered.
 - 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
 
-Outbound image/video/voice media, video, model-callable sends to arbitrary
-recipients, group chats, a local quote cache, and a long-lived RPC child (peer
-sessions are in-process).
+Outbound video or voice, model-callable sends to arbitrary recipients, group
+chats, a local quote cache, and a long-lived RPC child (peer sessions are
+in-process).
 
 ## Pi integration
 
 | Integration point | Detail |
 |---|---|
 | 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`. |
+| Tools | `send_wechat` — one text or one local image, to the owner only; registered at factory time with direct exposure (the default), `executionMode: "sequential"`, `openWorldHint: true`. |
+| Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true` |
+| Output | `outputSchema` — `{ sent, error? }` — also returned as `structuredContent`; a failed send is an `isError` result with the same shape. |
 | 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. |
+| Turn ownership | `peer-worker.ts`: a serial queue per peer, `session.prompt()`/`session.abort()`, `getLastAssistantText()` for the answer, one idle sweep per session, and the one notice an abandoning close sends per peer. `PEER_CONCURRENCY` is 2, and `dialog/channels.ts` gives each running peer its own channel, so a forwarded dialog has one owner without serializing the bridge. |
 | 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` / `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. |
@@ -501,39 +594,43 @@ status, which is what the old start/stop guidance used to do.
 | File | Responsibility |
 |---|---|
 | `index.ts` | Factory: gate, register the command and tool, wire the lifecycle events, build the bridge, open peer sessions from the host context. |
-| `bridge.ts` | The composition root: wires the poll loop, delivery, presence, admission, and inbound modules to the live client/account/cursor/state; owns the connection lifecycle, slash dispatch, the status snapshot, and `sendToOwner`. |
-| `poll.ts` | The long-poll loop: `getupdates`, the watchdog and retry, backoff, cursor persistence, and the expiry stop. |
-| `deliver.ts` | The one outbound text path (reply, dialog preface, `send_wechat`) plus file delivery: flatten, split, number, expiry, rejection, and the once-per-outage notice. |
-| `presence.ts` | Typing, acknowledgement, and the slow/busy lines; all per-peer wait timers in one registry. |
-| `admission.ts` | The rolling-hour turn budget and the per-peer serial admission chain. |
-| `inbound.ts` | Inbound media resolution (download, decrypt, save, attach) and the hand-off to a peer's session. |
-| `peer-session.ts` | One SDK `AgentSession` per peer: workspace, model, history under the state dir, dialogs bound to that peer, this bridge excluded from its resources, and the channel prompt appended. |
-| `channel.ts` | The phone-chat contract appended to a peer session's system prompt. |
-| `peer-worker.ts` | Per-peer queue, one turn at a time (`concurrency`), prompt/abort/reset, streamed reply parts, idle-session sweep. |
-| `reply-pipeline.ts` | Where a streamed answer is split (paragraph, quiet period, size), sent in order, and finished without duplicating a part. |
-| `commands.ts` | `/wechat login|new|status|stop|reset|logout|help`: the verb table that drives the help text and completions, the dispatch, the panel, login/logout, and the per-peer stop/reset; `login`/`new`/`logout` decline and `status` degrades to the summary while a peer turn runs. |
-| `tools.ts` | The `send_wechat` tool (owner-only proactive text). |
-| `client.ts` | iLink HTTP client (QR, getupdates, sendmessage, file sendmessage, getuploadurl, getconfig, sendtyping, CDN download/upload) with an injected runner. |
-| `media.ts` | Media key/encrypt/decrypt, padded size, upload/download URL, MIME sniff, filename sanitize, and save helpers. |
-| `outbound.ts` | Upload and send a local file: hash, encrypt, `getUploadUrl`, upload, `sendFileMessage`. |
-| `login.ts` | QR login state machine. |
-| `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`): 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`). |
+| `bridge.ts` | The composition root: wires the poll loop, delivery, presence, admission, and inbound modules to the live client/account/cursor/state; owns the connection lifecycle, the status snapshot, and `sendToOwner`. |
+| `intake.ts` | The inbound path: who is refused, what is a replay, what is a command, what answers a pending prompt, and what is queued or turned away; the admission predicates live here too. |
+| `tools.ts` | The `send_wechat` tool: owner-only proactive text or one image, with the neither-or-both refusal. |
 | `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). |
-| `lock.ts` | Poller lockfile. |
-| `format.ts` | Sanitize, chunk, and label helpers (text only). |
-| `notices.ts` | The peer-facing notice catalog: one line per kind, in the peer's language. |
+| `types.ts` | Wire and domain types. |
 | `errors.ts` | Re-exports `messageOf` from `lib/errors.ts`, the one error-to-line helper every notice and tool error uses. |
 | `timer.ts` | The timer seam: the cancellable one-shot `ArmTimer`, `defaultTimer`, and the abortable `defaultSleep`. |
-| `interaction.ts` | The WeChat `InteractionChannel`: pending-prompt state machine and reply routing. |
-| `prompt.ts` | Pure prompt formatting and reply parsing. |
-| `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. |
+| `transport/client.ts` | iLink HTTP client (QR, getupdates, sendmessage, file and image sendmessage, getuploadurl, getconfig, sendtyping, CDN download/upload) with an injected runner. |
+| `transport/poll.ts` | The long-poll loop: `getupdates`, the watchdog and retry, backoff, cursor persistence, and the expiry stop. |
+| `transport/deliver.ts` | The one outbound text path (reply, dialog preface, `send_wechat`) plus file and image delivery: flatten, split, number, expiry, rejection, and the once-per-outage notice. |
+| `transport/outbound.ts` | Upload and send local media: one hash/encrypt/`getUploadUrl`/upload body, then a file item or an image item, and an image must sniff as one. |
+| `transport/inbound.ts` | Inbound media resolution (download, decrypt, save, attach) and the hand-off to a peer's session. |
+| `transport/media.ts` | Media key/encrypt/decrypt, padded size, upload/download URL, image MIME sniff (undefined when the bytes are no image), filename sanitize, and save helpers. |
+| `state/state.ts` | `state.json` (cursor, owner, per-peer tokens, recent message ids). |
+| `state/credentials.ts` | `credentials.json` (`0600`, every stored account and the active one). |
+| `state/lock.ts` | Poller lockfile. |
+| `peer/peer-session.ts` | One SDK `AgentSession` per peer: workspace, model, history under the state dir, dialogs bound to that peer, this bridge excluded from its resources, and the channel prompt appended. |
+| `peer/peer-worker.ts` | Per-peer queue, two peers' turns at once (`PEER_CONCURRENCY`), the fair slot hand-off, prompt/abort/reset, streamed reply parts, idle-session sweep, and the notice an abandoning close sends. |
+| `peer/admission.ts` | The rolling-hour turn budget and the per-peer serial admission chain. |
+| `peer/reply-pipeline.ts` | Where a streamed answer is split (paragraph, quiet period, size), sent in order, and finished without duplicating a part. |
+| `peer/presence.ts` | Typing, acknowledgement, and the slow/busy lines; all per-peer wait timers in one registry. |
+| `commands/commands.ts` | `/wechat login\|new\|status\|stop\|reset\|logout\|help`: the verb table that drives the help text and completions, the dispatch, the panel, login/logout, and the per-peer stop/reset; `login`/`new`/`logout` decline and `status` degrades to the summary while a peer turn runs. |
+| `commands/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. |
+| `commands/doctor.ts` | The plain-text `/wechat doctor` report: connection/token age, poll, lock, peer sessions, recent failures, and config. |
+| `commands/login.ts` | QR login state machine. |
+| `commands/history.ts` | Read-only `/history`: opens the peer's newest session, formats the last user/assistant messages, and never writes. |
+| `text/format.ts` | Sanitize, chunk, and label helpers (text only). |
+| `text/notices.ts` | The peer-facing notice catalog: one line per kind, in the peer's language. |
+| `text/channel.ts` | The phone-chat contract appended to a peer session's system prompt. |
+| `dialog/interaction.ts` | One peer's `InteractionChannel`: pending-prompt state machine, the other-answer stash, and reply routing for that peer. |
+| `dialog/channels.ts` | The per-peer channel registry: one channel each, inbound reply routing, the waiting prompts for the control screen, and cancel-all on a pause. |
+| `dialog/prompt.ts` | Pure prompt formatting and reply parsing. |
+| `dialog/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. |
+| `view/login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`), drawn from the `lib/tui/` kit (`titleRule`, `clip`, `isCloseKey`). |
+| `view/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`). |
+
+Modules are grouped by the role they play: `transport/` is the only place that talks to iLink, `state/` owns the three files a session leaves on disk, `peer/` runs one peer's session and its queue, `commands/` holds a slash verb, `text/` words everything a peer reads, `dialog/` asks a question over WeChat, and `view/` draws a full-screen surface. `index.ts`, `bridge.ts`, `tools.ts`, `config.ts`, `types.ts`, `errors.ts`, and `timer.ts` stay at the root — the factory, the composition root, the public surface, and the seams the directories import.
 
 ## Testing