@dumbmice/pi-mailbridge 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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

package/README.md

@@ -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.3
+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 |
@@ -583,7 +583,7 @@ table and the module map: [docs/ARCHITECTURE.md](https://github.com/DumbMice/pi-
 
 ## Status
 
-`0.1.3` — 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.3",
+  "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)
 	})
 }