@dumbmice/pi-mailbridge 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.1.4 — 2026-11-13
+
+- **`/mailbridge` no longer freezes the agent process on a lock.** `ensureRouteForSession` ran under
+  `routes.lock` for every notification, and the wait sleeps the calling thread - measured at 3012 ms
+  with the lock held, on the pi main thread. A session with a live route now returns it without
+  taking the lock, and the route is only refreshed (or re-pointed at a renamed device) when needed.
+- **The pending queue is bounded in bytes, not only in records.** 1 000 records at the 100k-char
+  body cap was a ~100 MB file rewritten on every claim and ack; the ceiling is now 8 MB of stored
+  records as well. Refusal is a stall, not a drop: the cursor holds and the reply is retried, and a
+  queue inherited from an earlier version that is already over 8 MB simply defers *new* mail until
+  it drains - nothing is discarded, and the seven-day pressure expiry still frees an abandoned
+  backlog.
+- **The stored subject is capped at 300 characters.** It is display only (routing read the raw
+  header), and it was the one field the scanner did not bound: a multi-megabyte `Subject:` header
+  produced a record bigger than the queue's ceiling, which would then be refused on every scan with
+  nothing to expire.
+
+- **The persisted subject and attachment filenames are capped** (300 and 200 characters). Both are
+  mail-controlled and were unbounded; a multi-megabyte header or MIME filename produced a record
+  larger than the queue's new ceiling, which would then be refused on every scan with nothing to
+  expire - a permanent stall. Bodies were already capped; the display fields were not.
+- **The attachment-only path can now dig itself out of a full queue.** It skipped the age-expiry
+  that the record path runs, so it stalled where a reply with a body would have recovered.
+
+Also: a non-loopback `daemon.host` is now reported by `/mailbridge check` and fails
+`pi-mailbridge --check` (it was silent), and the panel names both queue bounds instead of a count
+that could not explain a byte-full queue; an expiry is listed as its own line rather than under
+"rejections" beside `rejected 0`.
+
+## 0.1.3 — 2026-11-13
+
+- **The package page showed alt text instead of the images.** The README's markup was fixed to
+  absolute URLs in 0.1.2, which npm requires - but `raw.githubusercontent.com` is unreachable on
+  many mainland networks (GitHub has no CDN there), so the reader saw red alt text while the
+  server answered 200 elsewhere. Both images now come from jsDelivr's npm mirror
+  (`cdn.jsdelivr.net/npm/@dumbmice/pi-mailbridge@latest/docs/images/…`): byte-identical files,
+  served out of the published package, on a CDN that is reachable where raw is not, and `@latest`
+  so the URL follows the release instead of rotting.
+
 ## 0.1.2 — 2026-11-13
 
 The release that fixes the ways this package could quietly do the wrong thing.

package/README.md

@@ -8,7 +8,7 @@ continues**, with your answer as the next message. Notifications also carry rend
 images embedded in the body where the agent put them, and any local file it linked attached with
 its real name.
 
-![A pi-mailbridge notification in a mail client: a decision request with rendered Markdown, a recommendation, and a build log attached](https://raw.githubusercontent.com/DumbMice/pi-mailbridge/main/docs/images/notification.png)
+![A pi-mailbridge notification in a mail client: a decision request with rendered Markdown, a recommendation, and a build log attached](https://cdn.jsdelivr.net/npm/@dumbmice/pi-mailbridge@latest/docs/images/notification.png)
 
 - **Your inbox is the client.** No app, no account, no relay, no push service. Any device with
   email works: a phone, a tablet, another PC, a webmail tab.
@@ -342,7 +342,7 @@ Every scan records why each message was refused, so this is answerable:
 ```
 
 ```
-daemon: healthy (http://127.0.0.1:4177) — daemon version 0.1.2
+daemon: healthy (http://127.0.0.1:4177) — daemon version 0.1.4, protocol 1
 device: dev-box-7
 mode: on
 imap: connected
@@ -383,9 +383,9 @@ proof the channel is open.
 | `attachment-only-dropped` | the reply's only content was an attachment that was dropped (over the 1 MB total, a refused type); a note naming the drop is delivered | send the text, or a smaller file |
 | `empty-body` | no prose, no attachment at all | — |
 | `attachment-*` | an attachment was dropped (type, size, count) | see the suffix |
-| `pending-full` | 1 000 undelivered replies are queued | start a session so they drain |
+| `pending-full` | the queue is at its limit: 1 000 undelivered replies, or 8 MB of queued bodies and attachments - a few attachment-heavy replies can fill it | start a session so they drain; nothing is discarded, the cursor waits |
 | `send_budget` | more than ten notifications in a minute were requested | a loop is mailing; the budget refuses rather than spending the account's quota |
-| `too-large` | over 8 MiB, refused before the body was downloaded | send a smaller one; inbound attachments are capped at 4 files and 1 MB *in total* |
+| `too-large` | over 8 MB, refused before the body was downloaded | send a smaller one; inbound attachments are capped at 4 files and 1 MB *in total* |
 
 Where to look:
 
@@ -449,7 +449,7 @@ environment variables. A working example: [`config.example.json`](https://github
 | `security.trustedAuthservId` | unset | pin the trusted `Authentication-Results` host; leave unset for Microsoft consumer accounts |
 | `security.allowHeaderThreading` | `true` | accept a reply whose subject id was lost, by matching `In-Reply-To`/`References` |
 | `security.allowSelfReplies` | `false` | one address for both roles: accept a self-addressed message, but only a real reply |
-| `security.tokenTtlHours` | `720` | lifetime of a route id, signed token and reply-chain entry |
+| `security.tokenTtlHours` | `720` | lifetime of a signed token and a reply-chain entry; a route id is refreshed once half its TTL is left, so it is guaranteed for at least `tokenTtlHours / 2` after the last notification, and the chain covers the rest |
 | `daemon.host` / `.port` | `127.0.0.1` / `4177` | loopback HTTP; a lock file in the state directory is the instance lock, and the port is a second guard |
 | `daemon.idleTimeoutSecs` | `120` | grace period after the last ping |
 | `daemon.scanIntervalSecs` | `60` | catch-up scan while mode is on, so a silent IDLE cannot strand a reply; `0` disables |
@@ -566,7 +566,7 @@ that is the credential that actually reaches your mailbox.
 
 ## How it works
 
-![Diagram: the pi session sends through the local daemon over SMTP to your mailbox; you reply from any device; the daemon reads it over IMAP, authorizes, routes and persists it; the session claims it, injects it, and acknowledges, which marks the mail seen](https://raw.githubusercontent.com/DumbMice/pi-mailbridge/main/docs/images/flow.svg)
+![Diagram: the pi session sends through the local daemon over SMTP to your mailbox; you reply from any device; the daemon reads it over IMAP, authorizes, routes and persists it; the session claims it, injects it, and acknowledges, which marks the mail seen](https://cdn.jsdelivr.net/npm/@dumbmice/pi-mailbridge@latest/docs/images/flow.svg)
 
 The numbered path is the whole product. **1** The agent finishes its turn and goes idle — that is
 the normal case, one mail per finished turn — or it stops to ask you a question; either way the
@@ -583,7 +583,7 @@ table and the module map: [docs/ARCHITECTURE.md](https://github.com/DumbMice/pi-
 
 ## Status
 
-`0.1.2` — feature-complete for the single-user, one-mailbox case, and exercised end to end
+`0.1.4` — feature-complete for the single-user, one-mailbox case, and exercised end to end
 against a live QQ mailbox in both layouts: two addresses (DMARC verified on the reply) and one
 address for both roles (self-delivery, the self-echo guard, and a reply routed by the chain).
 

package/dist/core/attachments.js

@@ -14,6 +14,15 @@ export const ALLOWED_IMAGE_MIMES = ["image/png", "image/jpeg", "image/gif", "ima
 export const ALLOWED_TEXT_MIMES = ["text/plain", "text/markdown", "application/json"];
 export const MAX_ATTACHMENTS = 4;
 export const MAX_TOTAL_BYTES = 1_000_000;
+/**
+ * Longest filename we keep.
+ *
+ * The name is persisted with the record and there is no upstream bound on the MIME `filename`
+ * parameter - a message at the 8 MB message ceiling can carry a multi-megabyte one. Unbounded, it
+ * was the last field that could push a record past `PENDING_MAX_BYTES` and be refused on every
+ * scan with nothing to expire. Outbound already caps names (`safeFilename`, inline-images.ts).
+ */
+export const MAX_NAME_CHARS = 200;
 function isImage(mime) {
     return ALLOWED_IMAGE_MIMES.includes(mime);
 }
@@ -36,7 +45,8 @@ export function selectAttachments(raw, limits = {}) {
     let total = 0;
     for (const item of raw) {
         const mimeType = normalizeMime(item.contentType);
-        const name = (item.filename ?? "").trim() || `attachment-${accepted.length + dropped.length + 1}`;
+        const name = (item.filename ?? "").trim().slice(0, MAX_NAME_CHARS) ||
+            `attachment-${accepted.length + dropped.length + 1}`;
         if (!isImage(mimeType) && !isText(mimeType)) {
             dropped.push({ name, reason: "mime-not-allowed" });
             continue;

package/dist/core/status.js

@@ -3,6 +3,7 @@
 // Pure on purpose: this is the answer to "why did my reply not arrive", and it lived inline
 // in the extension where no test could reach it - which is how an unconditional "queue full"
 // line shipped in its first version.
+import { PENDING_CAP, PENDING_MAX_BYTES } from "../store/pending-store.js";
 /**
  * Counter keys that are not refusals.
  *
@@ -22,6 +23,24 @@ const HANDLED = new Set([
 ]);
 /** Deferred, not dropped: the queue was full and the same UID is retried. */
 const DEFERRED = new Set(["pending-full"]);
+/**
+ * Aged out under queue pressure. Not a rejection of anything in *this* scan - the record was
+ * already queued and undeliverable - so listing it under "rejections" beside `rejected 0` read
+ * as the same contradiction the counter fix was meant to remove.
+ */
+const EXPIRED = new Set(["expired"]);
+/**
+ * The queue's two bounds, named from the constants.
+ *
+ * Hardcoding the numbers here is how the panel would start lying the day one of them changed -
+ * with a green suite, because the only assertion matched the words "queue full".
+ */
+export function queueLimits() {
+    // Grouped like the docs ("1 000"), not `1000`: the panel and the troubleshooting table are read
+    // side by side, and two spellings of one number read as two different limits.
+    const grouped = String(PENDING_CAP).replace(/\B(?=(\d{3})+(?!\d))/g, " ");
+    return `${grouped} replies or ${Math.round(PENDING_MAX_BYTES / 1024 / 1024)} MB queued`;
+}
 export function formatScan(summary) {
     if (!summary)
         return ["last scan: (never — is the daemon running?)"];
@@ -36,7 +55,8 @@ export function formatScan(summary) {
         .filter(([reason]) => pick(reason))
         .map(([reason, n]) => `${reason} ${n}`)
         .join(", ");
-    const refused = list((r) => !HANDLED.has(r) && !DEFERRED.has(r) && !r.startsWith("attachment-"));
+    const refused = list((r) => !HANDLED.has(r) && !DEFERRED.has(r) && !EXPIRED.has(r) && !r.startsWith("attachment-"));
+    const expired = list((r) => EXPIRED.has(r));
     const handled = list((r) => HANDLED.has(r));
     const dropped = list((r) => r.startsWith("attachment-"));
     const deferred = entries.some(([reason]) => DEFERRED.has(reason));
@@ -50,7 +70,12 @@ export function formatScan(summary) {
         `rejections: ${refused || "none"}`,
         ...(handled ? [`handled: ${handled}`] : []),
         ...(dropped ? [`attachments dropped: ${dropped}`] : []),
-        // Conditional, and it says what the reader should do about it.
-        ...(deferred ? ["queue full: replies are deferred, not dropped — start a session so they drain"] : []),
+        ...(expired ? [`aged out under queue pressure: ${expired}`] : []),
+        // Conditional, and it says what the reader should do about it. Both bounds are named: a
+        // byte-full queue can hold six replies, so the count alone read as a contradiction with
+        // the "pending replies: 6" line right above it.
+        ...(deferred
+            ? [`queue full: ${queueLimits()} — deferred, not dropped; start a session so they drain`]
+            : []),
     ];
 }

package/dist/daemon/process.js

@@ -27,6 +27,19 @@ import { isJournaled } from "../store/journal.js";
 import { advanceCursor, readCursor } from "../store/uid-cursor.js";
 /** Longest body we keep. Well above any real instruction; far below "a whole newsletter". */
 export const MAX_BODY_CHARS = 100_000;
+/**
+ * Longest subject we persist. Routing already happened on the raw header, so this is a display
+ * field - and it is the one field the scanner does not otherwise bound (`MAX_MESSAGE_BYTES` is the
+ * only upstream limit, and it is the same size as the whole queue's ceiling). Without this cap a
+ * single message carrying a multi-megabyte `Subject:` header produced a record larger than
+ * `PENDING_MAX_BYTES`, which `addPending` then refused on every scan with nothing to expire: a
+ * permanent stall of all inbound mail. `test/pending-store.test.ts` pins the relationship.
+ */
+export const MAX_SUBJECT_CHARS = 300;
+export function persistedSubject(subject) {
+    const value = subject ?? "";
+    return value.length > MAX_SUBJECT_CHARS ? `${value.slice(0, MAX_SUBJECT_CHARS)} [truncated]` : value;
+}
 function bump(reasons, key) {
     reasons[key] = (reasons[key] ?? 0) + 1;
 }
@@ -164,6 +177,32 @@ export async function scanAndProcess(config, deps) {
             result.cursor = advanceCursor(env, uid);
             continue;
         }
+        /**
+     * Persist, and if the queue is full make room by expiring records nothing can deliver any more.
+     *
+     * Shared by both insertion sites. The age-expiry recovery is the only relief a full queue has,
+     * and the attachment-only stub used to skip it: a byte-full queue stalled there where a real
+     * record would have recovered, which contradicted ARCHITECTURE's promise that refusal is a
+     * stall the queue digs itself out of.
+     */
+        function persistWithPressure(record) {
+            if (addPending(env, record).ok)
+                return true;
+            const expired = expirePending(env);
+            if (expired.length === 0)
+                return false;
+            // Not a rejection of *this* message: the reason says what was dropped, and the counts stay
+            // usable ("examined 1, rejected 0"), which they did not when the expiry was counted as one.
+            bump(result.reasons, "expired");
+            // Free a slot only when nothing else is queued for that session, or a live record would
+            // lose its reservation.
+            const stillQueued = new Set(listPending(env).map((r) => r.sessionId));
+            for (const gone of expired) {
+                if (!stillQueued.has(gone.sessionId))
+                    deps.onDropped?.(gone.sessionId);
+            }
+            return addPending(env, record).ok;
+        }
         // A body cap as well as a message cap: the pending store is re-read on every poll and
         // on every /health, so one enormous reply would be paid for repeatedly.
         const stripped = stripQuoted(message.text);
@@ -196,14 +235,13 @@ export async function scanAndProcess(config, deps) {
                     uid,
                     sessionId,
                     from: authz.from,
-                    subject: message.subject ?? "",
+                    subject: persistedSubject(message.subject),
                     body: note,
                     receivedAt: message.receivedAt ?? now(),
                     ...(uidValidity === undefined ? {} : { uidValidity }),
                     device: config.device.name,
                 };
-                const persisted = addPending(env, stub);
-                if (!persisted.ok) {
+                if (!persistWithPressure(stub)) {
                     // Same rule as a real record: do not advance past it, retry when there is room.
                     bump(result.reasons, "pending-full");
                     break;
@@ -221,7 +259,7 @@ export async function scanAndProcess(config, deps) {
             uid,
             sessionId,
             from: authz.from,
-            subject: message.subject ?? "",
+            subject: persistedSubject(message.subject),
             body,
             ...(accepted.length ? { attachments: accepted } : {}),
             receivedAt: message.receivedAt,
@@ -232,29 +270,7 @@ export async function scanAndProcess(config, deps) {
                 : { uidValidity: deps.source.uidValidity?.() ?? uidValidity }),
         };
         // Persist BEFORE the cursor moves. A crash here leaves the mail unseen.
-        const added = addPending(env, { ...record, device: config.device.name });
-        if (!added.ok) {
-            // The queue is full. Before stalling every future reply, drop records nothing can
-            // deliver any more - a session that has not come back in a week. This is the only
-            // place age-based expiry runs, because it is the only place the loss buys progress.
-            const expired = expirePending(env);
-            if (expired.length > 0) {
-                result.rejected++;
-                bump(result.reasons, "expired");
-                // The same rule as the UID-space drop: free a slot only when nothing else is
-                // queued for that session, or a live record would lose its reservation.
-                const stillQueued = new Set(listPending(env).map((r) => r.sessionId));
-                for (const gone of expired) {
-                    if (!stillQueued.has(gone.sessionId))
-                        deps.onDropped?.(gone.sessionId);
-                }
-                const retry = addPending(env, { ...record, device: config.device.name });
-                if (retry.ok) {
-                    result.persisted++;
-                    result.cursor = advanceCursor(env, uid);
-                    continue;
-                }
-            }
+        if (!persistWithPressure({ ...record, device: config.device.name })) {
             // The queue is full. STOP the batch: advancing past this UID would lose it, and
             // so would processing a later UID (the cursor is monotonic, so it would jump
             // over this one). The mail stays unread and the whole batch is retried once

package/dist/store/pending-store.js

@@ -13,6 +13,20 @@ import { statePath } from "./paths.js";
 import { StateVersionError, checkStateVersion, stamp } from "./schema.js";
 /** Bound the store so a stuck mailbox cannot grow it without limit. */
 export const PENDING_CAP = 1_000;
+/**
+ * Byte ceiling for the whole store, because the record cap alone was not a bound.
+ *
+ * `save()` rewrites the entire array on every claim and every ack, so 1000 records at the
+ * `MAX_BODY_CHARS` body cap is a ~100 MB file rewritten several times a minute - and the queue is
+ * already misbehaving when it is that full.
+ *
+ * It must stay comfortably above the largest single record the scanner can accept, or the queue
+ * would refuse that record forever with nothing to expire (the stall described in process.ts).
+ * That record is `MAX_BODY_CHARS` (100 000) plus a 1 MB attachment total base64'd (~1.33 MB) plus a
+ * subject capped at `MAX_SUBJECT_CHARS` (300), so ~1.5 MB; 8 MB leaves room for several.
+ * `test/pending-store.test.ts` asserts the relationship rather than trusting this comment.
+ */
+export const PENDING_MAX_BYTES = 8 * 1024 * 1024;
 /** A claim older than this is considered abandoned and may be re-taken. */
 export const CLAIM_TTL_MS = 120_000;
 function path(env) {
@@ -91,18 +105,43 @@ export function listPendingForSession(env, sessionId) {
 export function getPending(env, uid) {
     return load(env).find((r) => r.uid === uid);
 }
+/**
+ * What a record costs on disk: its serialised UTF-8 bytes.
+ *
+ * Serialised, because that is what `save()` writes and what a count of body + attachment data
+ * misses: the subject, the sender, attachment names and mime types, and JSON's escaping (one
+ * control character becomes six ASCII characters). Bytes rather than characters, because a CJK
+ * body costs up to three bytes per character in the file and one per character in a string index.
+ */
+export function recordBytes(record) {
+    return Buffer.byteLength(JSON.stringify(record), "utf8");
+}
 /**
  * Add or replace the record for `uid`. Idempotent on replay.
  *
- * Refuses a NEW record once the store is full rather than making room by discarding an
- * older one: every record here was already accepted, and the caller's cursor is about to
- * move past it. Replacing an existing uid (replay) is always allowed.
+ * Refuses rather than making room by discarding an older record: every record here was already
+ * accepted, and the caller's cursor is about to move past it. Two bounds, both checked here so
+ * the refusal happens before the cursor moves:
+ *
+ *   - `PENDING_CAP` records. Replacing an existing uid is allowed regardless (a replay cannot
+ *     grow the count).
+ *   - `PENDING_MAX_BYTES` of serialised records. A replacement is re-measured rather than trusted:
+ *     an over-size replay would otherwise be the one way past the ceiling.
+ *
+ * `claimPending` is the one writer that does not measure: it adds `claimedBy` (an instance id from
+ * a request body, itself capped at 1 MB) and `claimedAt` to one record. The scanner never sets
+ * those, so a stored record can only grow by a bounded field at claim time.
  */
-export function addPending(env, record) {
+export function addPending(env, record, options = {}) {
     const existing = load(env);
     const without = existing.filter((r) => r.uid !== record.uid);
     if (without.length >= PENDING_CAP)
         return { ok: false, reason: "full" };
+    // The same rule as the count cap, for the same reason: refuse at insertion, so the caller's
+    // cursor stays put and the reply is retried instead of dropped.
+    const candidateBytes = without.reduce((total, r) => total + recordBytes(r), 0) + recordBytes(record);
+    if (candidateBytes > (options.maxBytes ?? PENDING_MAX_BYTES))
+        return { ok: false, reason: "full" };
     without.push(record);
     save(env, without);
     return { ok: true, record };

package/dist/store/routes.js

@@ -173,11 +173,32 @@ function registerLocked(options, env, now, ttlHours) {
  * id stable per session means the subject is byte-identical across notifications, so
  * Outlook's conversation topic and Gmail's subject grouping both keep one thread, and
  * the RFC 5322 headers we also set have something stable to point at.
+ *
+ * Lifetime guarantee: the id is refreshed once less than half its TTL remains, so a session that
+ * notifies at least once per TTL/2 keeps the same id indefinitely (15 days either side at the
+ * default 720 h). That is half of what the always-refresh version promised, which the reply-chain
+ * fallback covers: `recordOutbound` stamps the chain at send time with the full
+ * `security.tokenTtlHours`, so a reply to a mail older than TTL/2 still routes.
  */
 export function ensureRouteForSession(options) {
     const env = options.env ?? process.env;
     const now = options.now ?? Date.now();
     const ttlHours = options.ttlHours ?? 30 * 24;
+    // Fast path, and it is the common case: a session that already has a healthy route needs no
+    // write at all, so it needs no lock. This matters because every caller is the pi process on
+    // its main thread - settle, request_decision, notify_user - and `withLock` sleeps with
+    // `Atomics.wait` while it waits. A held lock used to freeze the session for up to ~3s on a
+    // path that runs on every notification. Reads are safe without the lock: `save()` publishes
+    // with an atomic rename, so a reader sees one complete file or the other.
+    const live = load(env).find((r) => r.sessionId === options.sessionId && r.expiresAt > now);
+    if (live) {
+        // Refresh only when it is worth a write: less than half the TTL left. Refreshing on every
+        // notification was pure write amplification, and the subject is diagnostic only.
+        const refreshBefore = now + (ttlHours * 3600_000) / 2;
+        const deviceUnchanged = (live.device ?? undefined) === (options.device ?? undefined);
+        if (live.expiresAt > refreshBefore && deviceUnchanged)
+            return live.id;
+    }
     return withLock(env, () => {
         const items = load(env);
         const existing = items.find((r) => r.sessionId === options.sessionId && r.expiresAt > now);

package/docs/ARCHITECTURE.md

@@ -61,6 +61,12 @@ Invariants:
   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.
+- **Persistence is bounded, and refusal is a stall, not a drop.** The pending store holds at most
+  1 000 records or 8 MB of serialised records (`PENDING_CAP`, `PENDING_MAX_BYTES`). A refused
+  record leaves the cursor and the mail unread and stops the batch, which is retried once space
+  appears - that is why the byte ceiling must stay above the largest single record the scanner
+  accepts. The only deliberate loss is age: records older than seven days are expired *under that
+  pressure only*, never on connect.
 
 ## 3. Daemon HTTP surface
 
@@ -114,7 +120,9 @@ desired behaviour, not an error.
 - 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.
+  reply chain ages out on the same clock. A short id is refreshed once less than half its TTL
+  remains, so after the last notification it is valid for between `tokenTtlHours / 2` and the
+  full TTL — and the chain, stamped with the full TTL at send time, covers the gap.
 
 ### What identifies a reply
 

package/docs/SECURITY.md

@@ -118,7 +118,10 @@ A legitimate email can still contain text that reads like instructions
   therefore exfiltrate over SMTP. That is inside the trust boundary - the same process can read
   your mail - but worth knowing when deciding what runs as you.
 - Defaults to binding `127.0.0.1`; `daemon.host` can change that, but there is no TLS and
-  no user model beyond the bearer token, so do not. Nothing else about the daemon is
+  no user model beyond the bearer token, so do not. It is loud if you do: `/mailbridge check`
+  reports it and `pi-mailbridge --check` **exits non-zero**, the same way an `allowSelfReplies` +
+  `requireDmarcPass` combination does - a supported setting that a supervisor should not gate on
+  silently. Nothing else about the daemon is
   reachable without the token, apart from the `/health` liveness probe. That returns mode,
   pending/clients counts, the decision-registry size, ping timing, the number of SSE subscribers,
   the last scan's reason *counts*, the build and protocol versions, and the config file's mtime and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dumbmice/pi-mailbridge",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Drive Pi coding-agent sessions from your mailbox: get an email when an agent settles, reply to resume that exact session.",
   "keywords": [
     "pi",

package/src/core/attachments.ts

@@ -16,6 +16,15 @@ export const ALLOWED_TEXT_MIMES = ["text/plain", "text/markdown", "application/j
 
 export const MAX_ATTACHMENTS = 4
 export const MAX_TOTAL_BYTES = 1_000_000
+/**
+ * Longest filename we keep.
+ *
+ * The name is persisted with the record and there is no upstream bound on the MIME `filename`
+ * parameter - a message at the 8 MB message ceiling can carry a multi-megabyte one. Unbounded, it
+ * was the last field that could push a record past `PENDING_MAX_BYTES` and be refused on every
+ * scan with nothing to expire. Outbound already caps names (`safeFilename`, inline-images.ts).
+ */
+export const MAX_NAME_CHARS = 200
 
 export type UserContent =
 	| { type: "text"; text: string }
@@ -76,7 +85,9 @@ export function selectAttachments(
 
 	for (const item of raw) {
 		const mimeType = normalizeMime(item.contentType)
-		const name = (item.filename ?? "").trim() || `attachment-${accepted.length + dropped.length + 1}`
+		const name =
+			(item.filename ?? "").trim().slice(0, MAX_NAME_CHARS) ||
+			`attachment-${accepted.length + dropped.length + 1}`
 
 		if (!isImage(mimeType) && !isText(mimeType)) {
 			dropped.push({ name, reason: "mime-not-allowed" })

package/src/core/status.ts

@@ -4,6 +4,8 @@
 // in the extension where no test could reach it - which is how an unconditional "queue full"
 // line shipped in its first version.
 
+import { PENDING_CAP, PENDING_MAX_BYTES } from "../store/pending-store.ts"
+
 export interface ScanSummary {
 	/** When the last scan that saw mail ran; absent until one has. */
 	at?: number
@@ -36,6 +38,26 @@ const HANDLED = new Set([
 /** Deferred, not dropped: the queue was full and the same UID is retried. */
 const DEFERRED = new Set(["pending-full"])
 
+/**
+ * Aged out under queue pressure. Not a rejection of anything in *this* scan - the record was
+ * already queued and undeliverable - so listing it under "rejections" beside `rejected 0` read
+ * as the same contradiction the counter fix was meant to remove.
+ */
+const EXPIRED = new Set(["expired"])
+
+/**
+ * The queue's two bounds, named from the constants.
+ *
+ * Hardcoding the numbers here is how the panel would start lying the day one of them changed -
+ * with a green suite, because the only assertion matched the words "queue full".
+ */
+export function queueLimits(): string {
+	// Grouped like the docs ("1 000"), not `1000`: the panel and the troubleshooting table are read
+	// side by side, and two spellings of one number read as two different limits.
+	const grouped = String(PENDING_CAP).replace(/\B(?=(\d{3})+(?!\d))/g, " ")
+	return `${grouped} replies or ${Math.round(PENDING_MAX_BYTES / 1024 / 1024)} MB queued`
+}
+
 export function formatScan(summary: ScanSummary | null | undefined): string[] {
 	if (!summary) return ["last scan: (never — is the daemon running?)"]
 	if (summary.at === undefined) {
@@ -52,7 +74,8 @@ export function formatScan(summary: ScanSummary | null | undefined): string[] {
 			.map(([reason, n]) => `${reason} ${n}`)
 			.join(", ")
 
-	const refused = list((r) => !HANDLED.has(r) && !DEFERRED.has(r) && !r.startsWith("attachment-"))
+	const refused = list((r) => !HANDLED.has(r) && !DEFERRED.has(r) && !EXPIRED.has(r) && !r.startsWith("attachment-"))
+	const expired = list((r) => EXPIRED.has(r))
 	const handled = list((r) => HANDLED.has(r))
 	const dropped = list((r) => r.startsWith("attachment-"))
 	const deferred = entries.some(([reason]) => DEFERRED.has(reason))
@@ -69,7 +92,12 @@ export function formatScan(summary: ScanSummary | null | undefined): string[] {
 		`rejections: ${refused || "none"}`,
 		...(handled ? [`handled: ${handled}`] : []),
 		...(dropped ? [`attachments dropped: ${dropped}`] : []),
-		// Conditional, and it says what the reader should do about it.
-		...(deferred ? ["queue full: replies are deferred, not dropped — start a session so they drain"] : []),
+		...(expired ? [`aged out under queue pressure: ${expired}`] : []),
+		// Conditional, and it says what the reader should do about it. Both bounds are named: a
+		// byte-full queue can hold six replies, so the count alone read as a contradiction with
+		// the "pending replies: 6" line right above it.
+		...(deferred
+			? [`queue full: ${queueLimits()} — deferred, not dropped; start a session so they drain`]
+			: []),
 	]
 }

package/src/daemon/process.ts

@@ -30,6 +30,20 @@ import { advanceCursor, readCursor } from "../store/uid-cursor.ts"
 
 /** Longest body we keep. Well above any real instruction; far below "a whole newsletter". */
 export const MAX_BODY_CHARS = 100_000
+/**
+ * Longest subject we persist. Routing already happened on the raw header, so this is a display
+ * field - and it is the one field the scanner does not otherwise bound (`MAX_MESSAGE_BYTES` is the
+ * only upstream limit, and it is the same size as the whole queue's ceiling). Without this cap a
+ * single message carrying a multi-megabyte `Subject:` header produced a record larger than
+ * `PENDING_MAX_BYTES`, which `addPending` then refused on every scan with nothing to expire: a
+ * permanent stall of all inbound mail. `test/pending-store.test.ts` pins the relationship.
+ */
+export const MAX_SUBJECT_CHARS = 300
+
+export function persistedSubject(subject: string | undefined): string {
+	const value = subject ?? ""
+	return value.length > MAX_SUBJECT_CHARS ? `${value.slice(0, MAX_SUBJECT_CHARS)} [truncated]` : value
+}
 
 export interface RawMessage {
 	uid: number
@@ -237,7 +251,31 @@ export async function scanAndProcess(config: ResolvedConfig, deps: ScanDeps): Pr
 			continue
 		}
 
-		// A body cap as well as a message cap: the pending store is re-read on every poll and
+		/**
+	 * Persist, and if the queue is full make room by expiring records nothing can deliver any more.
+	 *
+	 * Shared by both insertion sites. The age-expiry recovery is the only relief a full queue has,
+	 * and the attachment-only stub used to skip it: a byte-full queue stalled there where a real
+	 * record would have recovered, which contradicted ARCHITECTURE's promise that refusal is a
+	 * stall the queue digs itself out of.
+	 */
+	function persistWithPressure(record: PendingRecord): boolean {
+		if (addPending(env, record).ok) return true
+		const expired = expirePending(env)
+		if (expired.length === 0) return false
+		// Not a rejection of *this* message: the reason says what was dropped, and the counts stay
+		// usable ("examined 1, rejected 0"), which they did not when the expiry was counted as one.
+		bump(result.reasons, "expired")
+		// Free a slot only when nothing else is queued for that session, or a live record would
+		// lose its reservation.
+		const stillQueued = new Set(listPending(env).map((r) => r.sessionId))
+		for (const gone of expired) {
+			if (!stillQueued.has(gone.sessionId)) deps.onDropped?.(gone.sessionId)
+		}
+		return addPending(env, record).ok
+	}
+
+	// A body cap as well as a message cap: the pending store is re-read on every poll and
 		// on every /health, so one enormous reply would be paid for repeatedly.
 		const stripped = stripQuoted(message.text)
 		// Marked, not silently cut: the agent must be able to tell that its instruction is
@@ -271,14 +309,13 @@ export async function scanAndProcess(config: ResolvedConfig, deps: ScanDeps): Pr
 					uid,
 					sessionId,
 					from: authz.from,
-					subject: message.subject ?? "",
+					subject: persistedSubject(message.subject),
 					body: note,
 					receivedAt: message.receivedAt ?? now(),
 					...(uidValidity === undefined ? {} : { uidValidity }),
 					device: config.device.name,
 				}
-				const persisted = addPending(env, stub)
-				if (!persisted.ok) {
+				if (!persistWithPressure(stub)) {
 					// Same rule as a real record: do not advance past it, retry when there is room.
 					bump(result.reasons, "pending-full")
 					break
@@ -297,7 +334,7 @@ export async function scanAndProcess(config: ResolvedConfig, deps: ScanDeps): Pr
 			uid,
 			sessionId,
 			from: authz.from,
-			subject: message.subject ?? "",
+			subject: persistedSubject(message.subject),
 			body,
 			...(accepted.length ? { attachments: accepted } : {}),
 			receivedAt: message.receivedAt,
@@ -309,28 +346,7 @@ export async function scanAndProcess(config: ResolvedConfig, deps: ScanDeps): Pr
 		}
 
 		// Persist BEFORE the cursor moves. A crash here leaves the mail unseen.
-		const added = addPending(env, { ...record, device: config.device.name })
-		if (!added.ok) {
-			// The queue is full. Before stalling every future reply, drop records nothing can
-			// deliver any more - a session that has not come back in a week. This is the only
-			// place age-based expiry runs, because it is the only place the loss buys progress.
-			const expired = expirePending(env)
-			if (expired.length > 0) {
-				result.rejected++
-				bump(result.reasons, "expired")
-				// The same rule as the UID-space drop: free a slot only when nothing else is
-				// queued for that session, or a live record would lose its reservation.
-				const stillQueued = new Set(listPending(env).map((r) => r.sessionId))
-				for (const gone of expired) {
-					if (!stillQueued.has(gone.sessionId)) deps.onDropped?.(gone.sessionId)
-				}
-				const retry = addPending(env, { ...record, device: config.device.name })
-				if (retry.ok) {
-					result.persisted++
-					result.cursor = advanceCursor(env, uid)
-					continue
-				}
-			}
+		if (!persistWithPressure({ ...record, device: config.device.name })) {
 			// The queue is full. STOP the batch: advancing past this UID would lose it, and
 			// so would processing a later UID (the cursor is monotonic, so it would jump
 			// over this one). The mail stays unread and the whole batch is retried once

package/src/store/pending-store.ts

@@ -16,6 +16,20 @@ import { StateVersionError, checkStateVersion, stamp } from "./schema.ts"
 
 /** Bound the store so a stuck mailbox cannot grow it without limit. */
 export const PENDING_CAP = 1_000
+/**
+ * Byte ceiling for the whole store, because the record cap alone was not a bound.
+ *
+ * `save()` rewrites the entire array on every claim and every ack, so 1000 records at the
+ * `MAX_BODY_CHARS` body cap is a ~100 MB file rewritten several times a minute - and the queue is
+ * already misbehaving when it is that full.
+ *
+ * It must stay comfortably above the largest single record the scanner can accept, or the queue
+ * would refuse that record forever with nothing to expire (the stall described in process.ts).
+ * That record is `MAX_BODY_CHARS` (100 000) plus a 1 MB attachment total base64'd (~1.33 MB) plus a
+ * subject capped at `MAX_SUBJECT_CHARS` (300), so ~1.5 MB; 8 MB leaves room for several.
+ * `test/pending-store.test.ts` asserts the relationship rather than trusting this comment.
+ */
+export const PENDING_MAX_BYTES = 8 * 1024 * 1024
 /** A claim older than this is considered abandoned and may be re-taken. */
 export const CLAIM_TTL_MS = 120_000
 
@@ -130,17 +144,46 @@ export function getPending(env: NodeJS.ProcessEnv, uid: number): PendingRecord |
 
 export type AddResult = { ok: true; record: PendingRecord } | { ok: false; reason: "full" }
 
+/**
+ * What a record costs on disk: its serialised UTF-8 bytes.
+ *
+ * Serialised, because that is what `save()` writes and what a count of body + attachment data
+ * misses: the subject, the sender, attachment names and mime types, and JSON's escaping (one
+ * control character becomes six ASCII characters). Bytes rather than characters, because a CJK
+ * body costs up to three bytes per character in the file and one per character in a string index.
+ */
+export function recordBytes(record: PendingRecord): number {
+	return Buffer.byteLength(JSON.stringify(record), "utf8")
+}
+
 /**
  * Add or replace the record for `uid`. Idempotent on replay.
  *
- * Refuses a NEW record once the store is full rather than making room by discarding an
- * older one: every record here was already accepted, and the caller's cursor is about to
- * move past it. Replacing an existing uid (replay) is always allowed.
+ * Refuses rather than making room by discarding an older record: every record here was already
+ * accepted, and the caller's cursor is about to move past it. Two bounds, both checked here so
+ * the refusal happens before the cursor moves:
+ *
+ *   - `PENDING_CAP` records. Replacing an existing uid is allowed regardless (a replay cannot
+ *     grow the count).
+ *   - `PENDING_MAX_BYTES` of serialised records. A replacement is re-measured rather than trusted:
+ *     an over-size replay would otherwise be the one way past the ceiling.
+ *
+ * `claimPending` is the one writer that does not measure: it adds `claimedBy` (an instance id from
+ * a request body, itself capped at 1 MB) and `claimedAt` to one record. The scanner never sets
+ * those, so a stored record can only grow by a bounded field at claim time.
  */
-export function addPending(env: NodeJS.ProcessEnv, record: PendingRecord): AddResult {
+export function addPending(
+	env: NodeJS.ProcessEnv,
+	record: PendingRecord,
+	options: { maxBytes?: number } = {},
+): AddResult {
 	const existing = load(env)
 	const without = existing.filter((r) => r.uid !== record.uid)
 	if (without.length >= PENDING_CAP) return { ok: false, reason: "full" }
+	// The same rule as the count cap, for the same reason: refuse at insertion, so the caller's
+	// cursor stays put and the reply is retried instead of dropped.
+	const candidateBytes = without.reduce((total, r) => total + recordBytes(r), 0) + recordBytes(record)
+	if (candidateBytes > (options.maxBytes ?? PENDING_MAX_BYTES)) return { ok: false, reason: "full" }
 	without.push(record)
 	save(env, without)
 	return { ok: true, record }

package/src/store/routes.ts

@@ -212,28 +212,49 @@ function registerLocked(options: RegisterRouteOptions, env: NodeJS.ProcessEnv, n
  * id stable per session means the subject is byte-identical across notifications, so
  * Outlook's conversation topic and Gmail's subject grouping both keep one thread, and
  * the RFC 5322 headers we also set have something stable to point at.
+ *
+ * Lifetime guarantee: the id is refreshed once less than half its TTL remains, so a session that
+ * notifies at least once per TTL/2 keeps the same id indefinitely (15 days either side at the
+ * default 720 h). That is half of what the always-refresh version promised, which the reply-chain
+ * fallback covers: `recordOutbound` stamps the chain at send time with the full
+ * `security.tokenTtlHours`, so a reply to a mail older than TTL/2 still routes.
  */
 export function ensureRouteForSession(options: RegisterRouteOptions): string {
 	const env = options.env ?? process.env
 	const now = options.now ?? Date.now()
 	const ttlHours = options.ttlHours ?? 30 * 24
 
+	// Fast path, and it is the common case: a session that already has a healthy route needs no
+	// write at all, so it needs no lock. This matters because every caller is the pi process on
+	// its main thread - settle, request_decision, notify_user - and `withLock` sleeps with
+	// `Atomics.wait` while it waits. A held lock used to freeze the session for up to ~3s on a
+	// path that runs on every notification. Reads are safe without the lock: `save()` publishes
+	// with an atomic rename, so a reader sees one complete file or the other.
+	const live = load(env).find((r) => r.sessionId === options.sessionId && r.expiresAt > now)
+	if (live) {
+		// Refresh only when it is worth a write: less than half the TTL left. Refreshing on every
+		// notification was pure write amplification, and the subject is diagnostic only.
+		const refreshBefore = now + (ttlHours * 3600_000) / 2
+		const deviceUnchanged = (live.device ?? undefined) === (options.device ?? undefined)
+		if (live.expiresAt > refreshBefore && deviceUnchanged) return live.id
+	}
+
 	return withLock(env, () => {
-	const items = load(env)
-	const existing = items.find((r) => r.sessionId === options.sessionId && r.expiresAt > now)
-	if (existing) {
-		// Refresh so a long-lived session keeps its id, and keep the subject current.
-		existing.expiresAt = now + ttlHours * 3600_000
-		if (existing.device !== options.device) {
-			if (options.device) existing.device = options.device
-			else delete existing.device
+		const items = load(env)
+		const existing = items.find((r) => r.sessionId === options.sessionId && r.expiresAt > now)
+		if (existing) {
+			// Refresh so a long-lived session keeps its id, and keep the subject current.
+			existing.expiresAt = now + ttlHours * 3600_000
+			if (existing.device !== options.device) {
+				if (options.device) existing.device = options.device
+				else delete existing.device
+			}
+			existing.subject = options.subject
+			save(env, items)
+			return existing.id
 		}
-		existing.subject = options.subject
-		save(env, items)
-		return existing.id
-	}
-	// registerLocked, not registerRoute: the lock is not re-entrant.
-	return registerLocked(options, env, now, ttlHours)
+		// registerLocked, not registerRoute: the lock is not re-entrant.
+		return registerLocked(options, env, now, ttlHours)
 	})
 }