@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,356 @@
+# ARCHITECTURE
+
+## 1. Shape
+
+```
+                  one mailbox
+                       │
+        ┌──────────────▼───────────────┐
+        │  daemon (one per machine)    │   IMAP IDLE, 1 connection
+        │  port 4177, token-auth'd     │   UID-cursor scan
+        │                              │
+        │  pending store (durable)     │
+        │  registry (1 decision/sess)  │
+        └───────┬──────────────┬───────┘
+                │ poll: /pending│   poll: /mode
+      ┌─────────▼────┐   ┌─────▼────────┐
+      │ pi session A │   │ pi session B │   thin clients (in-process extensions)
+      │ claim → ack  │   │ claim → ack  │
+      └──────────────┘   └──────────────┘
+```
+
+**One watcher, many sessions.** The daemon owns the single IMAP connection (plus one short-lived read-back per notification when
+`mail.imap.sentFolder` is set); pi
+sessions are thin clients over loopback HTTP: they poll `/pending` and replay it, which
+needs no reconnect logic because replay is idempotent. (`/events` also offers SSE for a
+push client; nothing uses it today.) This is the same
+topology as `opencode-afk` and it is the reason multi-session works: there is no
+N-way race for mailbox state, because only one process reads the mailbox.
+
+The extension (inside pi) never touches IMAP or SMTP on the delivery path: it sends mail
+through the daemon and receives replies from it. The one exception is the `/mailbridge
+smoke` diagnostic, which sends a real mail and then opens the folder over its own
+short-lived connection to prove both sides work (and `/mailbridge prime`, which opens one
+to move the cursor without reading anything).
+
+## 2. Delivery pipeline (the part that must not lose mail)
+
+```
+new UID ──► fetch ──► self-echo marker ──► authorize ──► route (id / token / chain) ──► persist pending (durable)
+                                                        │
+                                                        ▼
+                                     waiting for the next poll tick
+                                                        │
+                              ┌─────────────────────────┴──────────┐
+                              │ every session sees it; only the    │
+                              │ one whose session id matches claims│
+                              └─────────────────────────┬──────────┘
+                                                        ▼
+                                          pi.sendUserMessage(body, followUp)
+                                                        │
+                                                        ▼
+                                       ack ──► \Seen + journal append
+```
+
+Invariants:
+
+- **Nothing is marked `\Seen` before the ack.** A crash at any earlier point
+  leaves mail unseen and the pending entry durable → retried, not lost.
+- **The cursor only advances after persist**, never after broadcast.
+- **At-least-once, deduped by journal.** A duplicated delivery is caught by the
+  journal (UID already acked), not by timing.
+- **The claim is short-lived.** It prevents two sessions with the same id (an
+  old and new runtime during `/reload`) from injecting twice.
+
+## 3. Daemon HTTP surface
+
+Loopback only by default (`daemon.host`). Every request except `/health` carries
+`Authorization: Bearer <token>` from
+`$XDG_STATE_HOME/pi-mailbridge/secret.key`; comparison is constant-time.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/health` | liveness probe; **unauthenticated** by design (mode, pending count, the decision-registry size, emitted as both `sessions` and `registry` — sessions *with an outstanding decision*, not live sessions; live ones are `clients` — ping timing, SSE subscribers, the last scan's summary, `configLoadedAt`, `version`, `apiVersion` and `capabilities`; no content, no addresses) |
+| GET | `/events` | SSE: `delivery`, `mode` (no client uses it; sessions poll) |
+| GET | `/pending` | the delivery channel: polled every 10 s, replayed on reconnect; returns the daemon's own device's records plus untagged ones |
+| POST | `/claim` | `{uid, instanceId, uidValidity?}` — atomic claim; refused as `stale-space` for another UID space and `foreign-device` for a record another device scanned |
+| POST | `/ack` | `{uid, instanceId, uidValidity?}` — claimant-only; refused as `stale-space` when the record (or the caller) belongs to another UID space; journals in the **record's** space, then `\Seen` + prune |
+| POST | `/register` | reserve a session's single outstanding decision |
+| POST | `/bye` | a session is leaving; the daemon exits when the last one goes |
+| POST | `/ping` | heartbeat, the other half of the idle exit |
+| DELETE | `/register` | release the reservation |
+| GET/POST | `/mode` | global `on`/`off`, persisted + broadcast |
+| POST | `/send` | send one mail via the daemon's SMTP config; at most ten `notification` sends a minute, then `429 send_budget` (`kind: "settle"` and `"decision"` are exempt) |
+| POST | `/reload` | re-read config: stop the watcher, reload, redial. On failure it restores the previous config and warns; a refused connect returns `ok` with a warning |
+| POST | `/shutdown` | stop the daemon (used by the restart path) |
+
+Bounds: body ≤ 1 MB, registry ≤ 10 000 entries, SSE clients ≤ 100. A second daemon start exits 0
+on `daemon.lock` (and, as a second guard, on `EADDRINUSE`) — quiet by design.
+
+## 4. Routing token
+
+Subject format:
+
+```
+[pi:f913c9] <human subject>
+```
+
+A six- to eight-hex-character **local route id**, resolved from `store/routes.ts`. It replaced a
+signed token (39 characters, in an 87-character subject) that made every subject unreadable in a notification
+preview. Signed tokens still verify, so mail already in flight keeps working.
+
+The id is a lookup key, not a credential: an unknown id resolves to nothing, and
+authorization remains the sender allowlist plus DMARC (SECURITY.md §2.2) — except in the
+single-mailbox layout, where DMARC is off (README, One mailbox or two?). Because routes are
+local, an id minted on one machine simply does not resolve on another — which is the
+desired behaviour, not an error.
+
+- A local lookup key, not a signature: an id that was never minted here resolves to
+  nothing. (Legacy tokens *are* HMAC-signed, and are verified when they appear.)
+- Records the **device that minted it**. A daemon only persists a delivery whose
+  route (or chain entry, or legacy token) names its own device, so several machines
+  sharing one mailbox never hold stale copies of each other's replies. A record with
+  no device claim is accepted (single-device installs).
+- Replies keep the id because mail clients prefix — `Re: [pi:…] …`. Parsing
+  tolerates `Re:`, `RE:`, `AW:`, `Re[2]:`.
+- Expiry bounds replay: an id older than `tokenTtlHours` resolves to nothing, and the
+  reply chain ages out on the same clock.
+
+### What identifies a reply
+
+An inbound message is matched to a session by the first rule that succeeds:
+
+1. **Short route id** — `[pi:f913c9]`, matched anywhere in the subject, so `Re:` /
+   `RE:` / `Aw:` / `Re[2]:` prefixes are irrelevant. This is what every new
+   notification carries. It is a lookup key into this machine's `store/routes.ts`, not a
+   signature: an id minted elsewhere (or expired) resolves to nothing, and then rule 2 is
+   tried.
+2. **Legacy signed token** — `[pi:<payload>.<mac>]`, a 39-character HMAC-signed payload
+   carrying `sessionId`, expiry and the minting device. Still verified so mail sent before
+   the short id keeps working; no longer minted.
+3. **Reply chain** — `In-Reply-To`, or any id in `References`, equals a Message-ID
+   recorded in `store/threads.ts`. This is what survives a human editing the
+   subject or a client rewriting it. The chain is searched newest-first, so the
+   closest ancestor wins, and entries age out with `security.tokenTtlHours` so the chain
+   cannot route mail forever.
+   Some providers replace the `Message-ID` we stamp (QQ rewrites it to `<tencent_…@qq.com>`),
+   so the id the reply actually references is one we never minted. With
+   `mail.imap.sentFolder` set — which `setup` writes automatically for `qq.com` and
+   `foxmail.com`, so a QQ install holds this extra connection by default — the daemon reads the
+   just-sent copy back and records the
+   delivered id as well. Best-effort: it retries for about two minutes — six attempts totalling 112 s (the provider appends the
+   copy asynchronously) and matches on the `X-Pi-Mailbridge-Id` header we stamp, so it can only
+   ever record the copy of that exact notification. A capture in flight when the daemon stops
+   is lost, and that notification falls back to the subject id.
+4. Otherwise the message is rejected (`no-token`) and left unread - the cursor has moved
+   past it, so the retry is a new reply, not an edited subject.
+
+None of these is authentication: they route, they do not authorize. Authorization is the
+allowlist plus DMARC (off in the single-mailbox layout), and it happens before any of this
+(§2). A signed token is not
+stronger than a short id for routing purposes — the signature stops someone *predicting*
+an id, but guessing is pointless when any unresolvable id simply falls through to no
+route. `security.allowHeaderThreading: false` disables rule 3 only.
+
+The token is **not** authentication. It routes; it does not authorize. See
+SECURITY.md.
+
+### Device identity
+
+`device.name` defaults to the first label of `os.hostname()`. It appears in every **settle**
+notification's subject and body, and is stored on the routing record so the daemon that
+minted the reply can claim it. (The two agent tools carry the routing id and their own
+text, not a device line.) It exists for two reasons:
+
+1. **Human routing.** With pi on a laptop, a desktop and a build box, "which
+   machine is asking?" must be answerable from a notification preview.
+2. **Machine routing.** Two daemons watching one mailbox would otherwise both
+   fetch every reply. The device claim lets the non-owner skip it at scan time
+   (`other-device`), without persisting and without marking it seen.
+
+### UIDVALIDITY, and what a renumbered mailbox does
+
+UIDs are only meaningful within one `UIDVALIDITY`. If a provider recreates, migrates or
+"repairs" a folder, UIDs restart at 1 - and a persisted high-water cursor then skips every
+future message, with `examined 0` as the only symptom.
+
+The daemon records the mailbox's `UIDVALIDITY` beside the cursor and compares it on every
+connect. On a change it resets the cursor (except the first observation after an upgrade, unless the
+cursor has fallen outside the new range) and ignores `journal.json` entries from the old
+numbering (they describe a space that no longer exists). Queued records tagged with another numbering are dropped
+on **every** connect, not only on a change - a crash between the cursor write and the drop
+would otherwise leave a record that nothing can claim and nothing ever removes. Records with
+*no* space tag predate that field: an ordinary connect keeps them (an upgrade must not discard
+a queued reply), but a detected renumbering drops them too, because they cannot be shown to
+belong to the new numbering - live, one was claimed there and delivered a different message's
+body.
+The cost is explicit: **a renumbering can re-deliver replies that were acked inside the
+route TTL**, because the only durable dedupe is UID-based. Nothing is lost; recent mail may
+arrive once more. The daemon logs the change, the reset and how many records it dropped.
+
+## 5. Modes
+
+`/mailbridge on` → mode `on`: decisions mail the human and end the turn.
+`/mailbridge off` → mode `off`: decisions use the terminal as usual. A drain re-checks the mode
+between records, so an `off` arriving as a reply stops the batch it came in — the records behind
+it stay pending and unseen until the mode goes back on.
+
+Mode is global per machine (one human, one mailbox) and persisted, so a daemon
+restart does not silently re-enable mailing. Each session reads it on its poll tick (the
+daemon also broadcasts it to any `/events` subscriber, of which there are none today).
+
+## 6. Deliberately out of scope: creating sessions
+
+`ctx.newSession()` **replaces** the active session in-process, and only a
+command handler can call it — which is why `opencode-afk` needs a two-phase
+`create`→`resume` dance and why `pi-wechat-assistant` gates on `ctx.isIdle()`.
+
+pi-mailbridge does not create or switch sessions. It notifies about, and
+resumes, sessions the human already started. Anything else needs a different
+process topology (an RPC supervisor owning `pi --mode rpc` children).
+
+## 6a. Lifetime: singleton, and it stops when you do
+
+**Who starts it.** Whichever comes first: the extension on `session_start`; `/mailbridge
+setup` or `/mailbridge restart` when the session has no runtime yet; or the poll tick, which respawns a daemon that exited while the session was
+still alive. It is spawned *detached* so it outlives the process that started it and can
+serve other sessions. When a session finds one already running, it compares `/health`'s
+`configLoadedAt` with `config.json`'s mtime and issues `/reload` if the file is newer, so a
+hand-edited config is not served stale. Two limits worth knowing: the comparison is mtime
+based, so an edit that preserves the mtime (`cp -p`, a restore) is not noticed until
+`smoke`/`restart`; and only the daemon re-reads — the session's own copy of the config
+refreshes on the next `/mailbridge` command or pi restart.
+
+**Singleton.** `daemon.lock` in the state directory is the lock, with the owner's pid inside: a
+live holder makes the newcomer exit 0, and a file left by a crash is stolen by an atomic rename
+(not an unlink-then-retake, which lets two starters both win). The listening port is a second
+guard, for a foreign listener - a bind failure also exits 0. `ensureDaemon()` then probes `/health` and reuses the winner.
+
+**Two versions, two clocks.** `/health` carries both: `apiVersion` (the wire contract, `API_VERSION`)
+and `version` (the package build, diagnostic). A session replaces a daemon whose `apiVersion`
+differs - never negotiates - and additive wire changes are gated by `capabilities` rather than a
+protocol bump. State files carry `v` (`STATE_VERSION`): absent means schema 1 and is read and
+stamped on the next save, older is migrated on read, newer is refused for reading *and* writing.
+
+**A device rename strands what it scanned.** Records carry the device that scanned them, and
+`/pending` offers only this device's, so renaming `device.name` while replies are queued leaves
+those records neither offered nor claimable. `/mailbridge status` reports the count under "held for
+another device". They are your own mail and the mailbox still holds them unread, but the UID cursor
+has already passed them, so the recovery is to restore the previous `device.name` (the records are
+delivered again) or to have the human reply again. Rename before a quiet mailbox, not during.
+
+**One owner for replacement.** A dead daemon, a protocol mismatch and `/mailbridge restart` all go
+through one `replaceRuntime()`: capture the notifier, rebuild, flush the pending settle. Three
+paths each doing it themselves is how the same dropped notification was fixed three times.
+
+**A command that stops the daemon parks the poll first.** The tick runs every ten seconds and a
+restart waits up to five for the port to close, so a tick landing inside that window would hear the
+dying daemon's ping fail, respawn it, and hand the command the "something still answers" evidence
+it is measuring. `restart` therefore parks the loop, *joins* a tick that is already in flight
+(bounded by an internal budget longer than a spawn, so a daemon that tick is starting exists
+first), and re-arms in a `finally`. The pause flag is checked after every await in the tick, because a tick suspended
+before the park cannot be recalled - only made to stop at its next step.
+
+**It starts when a session needs it.** `pi install` runs nothing. On `session_start`, if the config
+is usable, the extension probes `/health` and spawns the daemon detached when nothing answers; in-pi
+`/mailbridge setup` does the same after writing the config, while headless `--setup` only writes
+the file. The daemon is not tied to the mode: `on`/`off` gate scanning and delivery, not existence.
+
+**It stops when the last session does.** Every session pings `/ping` on its poll tick
+(10s) and sends `/bye` on `session_shutdown`. Once no ping has arrived for
+`daemon.idleTimeoutSecs` (default 120), the daemon exits. This is deliberate:
+
+- an updated package cannot leave an orphaned process running old code - the exact trap
+  that cost an evening, where a daemon started at 15:09 kept serving after several code
+  changes because nothing could replace it. Idle exit alone is not enough while a session is
+  open, so `/health` reports the daemon's protocol and a session replaces a daemon on another
+  protocol (throttled to once a minute);
+- no session means no consumer: settle notifications are sent *by* a session, and no
+  session can claim a pending reply;
+- a daemon with no sessions still fetches and parses every incoming message looking for
+  a routing tag. Stopping it stops reading a mailbox nothing will use.
+
+Mail that arrives while it is down is not lost: the **catch-up scan** runs on the next
+start, from the stored UID cursor.
+
+There is deliberately no switch to keep it resident: with no sessions it scans but cannot deliver,
+so a daemon that outlived pi would read a mailbox for nobody. Idleness is measured from the
+daemon's own start until a session pings, so a hand-started daemon gets one full grace period and
+then exits - it is not exempt.
+
+## 7. Failure modes
+
+| Failure | Behaviour |
+| --- | --- |
+| IMAP drops | exponential backoff 1 s → 60 s; IDLE renews at 25 min |
+| IDLE `EXISTS` never fires | a catch-up scan runs every `daemon.scanIntervalSecs` (default 60, `0` disables) while mode is on and the watcher is healthy — observed live after a reply sat unscanned |
+| Daemon dies | sessions keep working; extension reconnects; missed mail recovered from `/pending` |
+| Session exits before ack | mail stays unseen, pending durable → redelivered |
+| SMTP fails | decision is *not* reserved as outstanding; error surfaces to the tool |
+| Mailbox full of non-token mail | cursor advances, nothing is claimed, no state grows |
+| Clock skew | expiry is compared against the local clock (`expiresAt <= now`), so a clock more than a TTL **ahead** refuses fresh ids, and a clock **behind** keeps expired ones alive |
+
+## 8. Module layout
+
+```
+src/
+  extension.ts          pi entry: tools, commands, polling client, session lifecycle
+  core/
+    attachments.ts      image/markdown attachment rendering
+    authz.ts            loop/bounce → robot → allowlist → DMARC (off for one mailbox)
+    commands.ts         /mailbridge parsing + usage text
+    config.ts           layered config, env overrides, type validation
+    config-freshness.ts  is the daemon's config older than the file?
+    deliveries.ts       claim → inject → ack, serialized per process
+    discover.ts         account autodiscovery
+    header-encoding.ts  RFC 2047 decode/encode
+    html.ts             text → HTML with quoted-history folding
+    inline-images.ts    local images → cid: parts; linked files → attachments (inside the project)
+    mailer.ts           nodemailer transport (password | XOAUTH2), headers
+    mail-command.ts     a reply that is a command → the safe subset, else text
+    prime.ts            "watch from now on" - first run only, guarded by the cursor
+    markdown.ts         notifications render as markdown
+    oauth*.ts           device-code + OpenID flows, one-retry token provider
+    reply-parse.ts      quote stripping, address + AR-header pinning
+    settle.ts           idle debounce, turn-settled notification
+    status.ts           scan summary → the lines /mailbridge status prints
+    version.ts          this build's version (diagnostic; replacement keys on apiVersion)
+    sent-index.ts       record the Message-ID the provider actually delivered
+    setup.ts            first-run scaffolding
+    smoke.ts            end-to-end send-and-read-back check
+    token.ts            HMAC sign/verify, subjects
+    token-source.ts     XOAUTH2 command tokens
+  daemon/
+    api.ts              the wire contract: API_VERSION, capabilities, endpoint list
+    imapflow.ts         imapflow adapter
+    main.ts             CLI + lifecycle
+    process.ts          UID-cursor scan → authorize → route → parse → persist
+    scan-queue.ts       one scan at a time; bursts coalesce into a follow-up
+    script.ts           which daemon entry to spawn: the build when one exists
+    send-budget.ts      outbound mail per minute, so a loop cannot spend the quota
+    source-proxy.ts     the MailSource the daemon really uses: live watcher + UIDVALIDITY
+    service.ts          the HTTP surface: /health /pending /claim /ack /send /events …
+    spawn.ts            ensureDaemon, single-instance
+    watcher.ts          imapflow IDLE, renew, backoff
+  store/
+    journal.ts          acked UIDs — durable replay protection
+    mode-store.ts       on/off
+    oauth-store.ts      refresh tokens, 0600
+    paths.ts            XDG dirs
+    pending-store.ts    durable pending + claim/ack state machine
+    registry.ts         one outstanding decision per session
+    schema.ts           on-disk schema version: refuse newer, migrate older
+    routes.ts           short routing ids, TTL
+    secret.ts           shared HMAC/bearer key, atomic 0600
+    threads.ts          outbound Message-IDs: threading + reply chain
+    uid-cursor.ts       cursor + UID space; resets when the mailbox is renumbered
+test/                   hermetic unit tests; no IMAP, no SMTP, no sockets
+```
+
+`/events` (SSE) exists on the daemon for push clients; the extension currently polls
+`/pending` every few seconds instead, because replaying it is idempotent and needs no
+reconnect logic.
+
+`MailSource` (in `daemon/process.ts`) is the seam: `watcher.ts` implements it over
+imapflow, tests implement it over an in-memory fixture. That is why the whole
+pipeline is testable without a mailbox.

package/docs/MAPPING.md

@@ -0,0 +1,201 @@
+# docs/MAPPING.md — `opencode-afk` → `pi-mailbridge`
+
+Module-by-module mapping from the reference implementation
+[`7emotions/afk`](https://github.com/7emotions/afk) (npm `opencode-afk`, MIT,
+v0.1.5, 3,988 lines JS) onto Pi's extension API.
+
+Read this alongside `ARCHITECTURE.md`. The goal is to port a proven design,
+not to reinvent it — while deleting the parts that only exist because OpenCode
+is driven out-of-process.
+
+---
+
+## 0. The one structural difference
+
+`opencode-afk` injects replies through the **OpenCode SDK over HTTP**, because
+its daemon lives outside the agent process. Pi extensions run **inside** the
+agent process, so injection is a local function call.
+
+That single change deletes three pieces of machinery:
+
+| afk machinery | Why it exists | pi-mailbridge |
+| --- | --- | --- |
+| `resolveRootSessionID()` parent-chain walk | opencode subagent sessions have `parentID`; the plugin must find the ROOT session to stamp the token with | Not needed. Pi reports the session id directly via `ctx.sessionManager.getSessionId()`. Revisit only if pi subagents surface as child sessions. |
+| Ownership self-check by `session.directory` | daemon broadcasts to all instances; each must decide if a reply is "for me" | Direct: compare the token's session id to `getSessionId()`. |
+| `POST /claim {sessionID, instanceId}` with HTTP 500-on-gone handling | the SDK call may fail because the session vanished | Not needed for routing. The claim remains, but only to make **ack ordering** crash-safe (see §3). |
+
+Everything else ports essentially as-is.
+
+---
+
+## 1. Module map
+
+| `opencode-afk` file | Lines | pi-mailbridge target | Change |
+| --- | --- | --- | --- |
+| `index.js` | 391 | `src/extension.ts` | Rewritten: opencode tool/command registration → `pi.registerTool` / `pi.registerCommand` |
+| `daemon.js` | 473 | `src/daemon/main.ts` + `src/daemon/service.ts` | Ported: HTTP surface + SSE in `service.ts`, CLI/lifecycle and single-instance lock in `main.ts` (port **4177**, not 4100) |
+| `core/watcher.js` | 261 | `src/daemon/watcher.ts` | Ported verbatim — `imapflow` IDLE, renew < 29 min, exponential backoff |
+| `core/process.js` | 314 | `src/daemon/process.ts` | Ported — UID-cursor incremental scan → fetch → parse → persist |
+| `core/reply-parse.js` | 265 | `src/core/reply-parse.ts` | Ported — quote stripping, address/AR-header pinning (token verify lives in `core/token.ts`) |
+| `core/inject.js` | 181 | `src/extension.ts` (in-process) | **Replaced** by `pi.sendUserMessage(body, { deliverAs: "followUp" })` |
+| `core/pause-notify.js` | 143 | `src/extension.ts` → `pi.on("agent_settled")` | Replaced by the pi event (§4) |
+| `core/subscribe.js` | 271 | `src/extension.ts` | Replaced — polls `/pending` and replays it (idempotent); `/events` SSE stays available for push clients |
+| `core/new-session.js` | 103 | **out of scope** | Deferred. Pi can do it (`ctx.newSession`) but it replaces the active session; see ARCHITECTURE §6 |
+| `request-decision.js` | 187 | `src/extension.ts` | Ported as a `pi.registerTool` |
+| `notify.js` | 125 | `src/extension.ts` | Ported as a `pi.registerTool` |
+| `mailer.js` | 86 | `src/core/mailer.ts` | Ported — `[omo:…]` → `[pi:…]`, nodemailer transport |
+| `config.js` | 184 | `src/core/config.ts` | Ported — layered config + env overrides |
+| `messages.js` | 102 | *(inlined)* | Folded into the modules that emit the text (`commands.ts`, `settle.ts`, `smoke.ts`) — no separate table |
+| `install.js` | 168 | **dropped** | opencode-specific installer; pi installs via `pi install npm:@dumbmice/pi-mailbridge` |
+| `store/paths.js` | 88 | `src/store/paths.ts` | Ported — XDG state dir |
+| `store/secret.js` | 116 | `src/store/secret.ts` | Ported — HMAC key file, first-writer-wins |
+| `store/pending-store.js` | 215 | `src/store/pending-store.ts` | Ported — durable pending replies |
+| `store/uid-cursor.js` | 123 | `src/store/uid-cursor.ts` | Ported, then extended — monotonic within a UID space; resets when the mailbox renumbers |
+| `store/mode-store.js` | 86 | `src/store/mode-store.ts` | Ported — global on/off via `/mailbridge on` · `off` |
+| `store/registry.js` | 106 | `src/store/registry.ts` | Ported — one-outstanding-decision guard |
+| `command/afk.md`, `command/back.md` | short | `/mailbridge on` · `off` subcommands | Renamed and namespaced: `back` is too generic a top-level name |
+| `AGENTS.md` | — | `AGENTS.md` | Rewritten for contributors + agents |
+
+---
+
+## 2. API substitutions
+
+### Registering a tool
+
+```js
+// opencode-afk
+export const request_decision = tool({
+  description: "…",
+  args: { subject: z.string(), question: z.string() },
+  async execute(args, ctx) { /* … */ },
+})
+```
+
+```ts
+// pi-mailbridge
+pi.registerTool({
+  name: "request_decision",
+  label: "Request decision",
+  description: "Email the user a decision request and end the turn.",
+  parameters: Type.Object({
+    subject: Type.String(),
+    question: Type.String(),
+    options: Type.Optional(Type.Array(Type.String())),
+    recommendation: Type.Optional(Type.String()),
+  }),
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    /* … */
+    return { content: [{ type: "text", text: "Email sent." }], details: {} };
+  },
+})
+```
+
+### Inbound injection
+
+```js
+// opencode-afk (core/inject.js)
+await client.session.prompt({
+  path: { id: sessionID }, query: { directory },
+  body: { parts: [{ type: "text", text: body }] },
+})
+```
+
+```ts
+// pi-mailbridge — in-process, cannot "not find" the session
+pi.sendUserMessage(body, { deliverAs: "followUp", expandPromptTemplates: false })
+```
+
+`deliverAs: "followUp"` queues the reply if a run is in flight — matching afk's
+behaviour when a decision is answered late.
+
+`expandPromptTemplates: false` is a correctness requirement, not an optimisation. With expansion
+on, pi dispatches any message starting with `/` to a registered command and returns without a
+turn, and it returns `void` — the caller cannot tell a command that ran from a prompt pi rejected
+(no model, expired credentials, compaction in progress), while this package acks and marks
+`\Seen` after that call returns. Commands by mail are therefore dispatched by this package
+(`core/mail-command.ts`), which limits them to the safe subset; everything else stays text.
+
+### Lifecycle signal
+
+```js
+// opencode-afk: polling/idle heuristics in core/pause-notify.js
+```
+
+```ts
+// pi-mailbridge: a real event, and the correct one
+pi.on("agent_settled", (event) => {
+  if (event.aborted && !config.notify.notifyOnAborted) return   // Escape ≠ finished
+  scheduleSettledMail()                                          // debounced
+})
+```
+
+`agent_end` is **wrong** here: pi may still retry, compact, or run queued
+follow-ups after it.
+
+### Commands
+
+```js
+// opencode-afk: command/afk.md + command/back.md
+```
+
+```ts
+pi.registerCommand("mailbridge", {
+	description: "Status, on/off, setup, check, auth, smoke, restart",
+	handler: (args, ctx) => …,   // one command; away/here became on/off, and no top-level commands
+})
+```
+
+---
+
+## 3. What we keep exactly (these are the hard-won parts)
+
+1. **UID-cursor polling, not `\Seen`.** afk searches `UID > cursor`, never
+   `UNSEEN` and never by SUBJECT. `\Seen` is shared mutable state — any other
+   mail client can set it and silently eat a reply.
+2. **Ack ordering.** Parse → persist to durable pending → notify → inject →
+   **then** `\Seen` + journal append. A crash anywhere before the ack leaves
+   the mail unseen and the pending durable, so nothing is lost. Never mark
+   seen at parse time.
+3. **Single watcher per machine.** One daemon, one IMAP IDLE connection, fixed
+   port, `EADDRINUSE` = "already running, exit quietly". This is what makes
+   multi-session polling sane: N pi sessions, 1 mailbox connection.
+4. **A routing id in the subject — but no longer a signature.** Shipped as a 6-hex
+   local route id (`[pi:f913c9]`, six hex, eight on the rare collision), looked up in
+   `store/routes.ts`. This is the one
+   deliberate reversal from the baseline: a signed token made every subject preview
+   unreadable (a 39-character token, in a subject over 80 characters). HMAC tokens still
+   verify for mail already in flight, and
+   authorization never depended on the token either way.
+5. **Global mode store.** `/mailbridge on` and `/mailbridge off` are explicit, persisted, and
+   independent of focus heuristics.
+6. **Backoff + IDLE renew.** Renew well under the ~29-minute server timeout;
+   exponential reconnect 1 s → 60 s.
+7. **Bounded resources.** Registry cap, SSE client cap, request body cap,
+   constant-time token comparison.
+
+---
+
+## 4. Deliberate differences
+
+| Area | afk | pi-mailbridge | Why |
+| --- | --- | --- | --- |
+| New session from mail (`/new`) | supported | deferred | `ctx.newSession()` *replaces* the active session; needs its own design pass |
+| Service | opencode/qq mail tuned | provider-neutral | `config.mail.*`; no hard-coded host |
+| Transport | SMTP password | SMTP password **or** OAuth2/XOAUTH2 | Outlook requires OAuth2 since 2024-09-16 |
+| Reply parsing | hand-rolled | hand-rolled, quote-stripping covered by tests | no `inreply` dependency: the stripping rules are ours and tested |
+| Auth check | allowlist | allowlist + DMARC header (pinned when `trustedAuthservId` is set; **off for a single mailbox** — SECURITY.md §5) | see SECURITY.md §2 |
+| Port | 4100 | 4177 | avoid colliding with a running afk |
+
+---
+
+## 5. Publish checklist
+
+- [x] `package.json` `files` limited to `dist`, `src`, `bin`, `docs`, `config.example.json`,
+      `CHANGELOG.md`, `scripts/render-teaser.ts`. `dist` is load-bearing: the installed extension
+      spawns `dist/daemon/main.js` (Node cannot strip types inside `node_modules`)
+- [x] no secrets in the package; `config.json` is gitignored and never shipped
+- [x] `pi` manifest points at `./src/extension.ts`
+- [x] peer deps on `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai` and `@sinclair/typebox`, not hard deps
+- [x] tests run with `node --test` and never touch real IMAP/SMTP
+- [x] docs state the daemon is a **local, authenticated** service that can inject prompts
+- [x] README states the threat model before the install steps ("Security first", and the install section points at SECURITY.md)