@fitchmultz/pi-subagents 0.48.0 → 0.49.1

package/dist/pi-intercom/bridge.js

@@ -50,6 +50,7 @@ class Bridge {
             this.presence = new PersistentPresence({
                 stateDir: config.stateDir,
                 clients: () => this.config.clients,
+                restored: (identity, expires) => this.deliveries.session(identity, expires),
                 connect: async (identity, expires) => {
                     await spawnBrokerIfNeeded(process.execPath, []);
                     if (!this.allowed(identity)) {
@@ -132,6 +133,7 @@ class Bridge {
             session = new Session({
                 stateDir: this.config.stateDir,
                 notifications: identity.wake !== undefined,
+                mailboxChanged: () => this.deliveries.changed(),
                 allowed: (candidate) => this.allowed(candidate),
                 lost: (fp, count) => this.lost(fp, count),
                 losses: (fp) => this.losses.get(fp) ?? 0,
@@ -267,6 +269,9 @@ class Bridge {
                 this.losses.delete(fp);
             }
         }
+        // Retire stale sessions before publishing replacement delivery membership for the same pin.
+        this.presence?.restoreAll();
+        this.deliveries.changed();
     }
     stop() {
         this.shutdown().catch(() => {
@@ -325,7 +330,9 @@ class Bridge {
         let controller;
         let deadline;
         let peer;
-        const abort = () => session?.close(new Fault(499, "client_aborted", "HTTP client disconnected; delivery may be unknown."));
+        let readOnlyInbox = false;
+        const cancel = (fault) => readOnlyInbox ? controller?.abort(fault) : session?.close(fault);
+        const abort = () => cancel(new Fault(499, "client_aborted", "HTTP client disconnected; delivery may be unknown."));
         const onClose = () => {
             if (!res.writableFinished) {
                 abort();
@@ -333,11 +340,12 @@ class Bridge {
         };
         const setDeadline = (ms) => {
             clearTimeout(deadline);
-            deadline = setTimeout(() => session?.close(new Fault(504, "request_timeout", "HTTP operation deadline exceeded; delivery may be unknown.")), Math.max(1, ms - (Date.now() - started)));
+            deadline = setTimeout(() => cancel(new Fault(504, "request_timeout", "HTTP operation deadline exceeded; delivery may be unknown.")), Math.max(1, ms - (Date.now() - started)));
         };
         try {
             const { identity, expires, certificate } = this.admission(req);
             const route = routeFor(req);
+            readOnlyInbox = route === "GET /v1/inbox";
             session = this.session(identity, expires);
             controller = session.begin();
             const signal = controller.signal;

package/docs/intercom-bridge.md

@@ -92,22 +92,22 @@ Add `stateDir`, `wake` and `launch` to the generated `config.json`. Keep the fil
 
 This example gives the agent full authority over every Mac path. The defaults stay restrictive for other identities.
 
-| Field                             | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `stateDir`                        | Owned 0700 directory, required for unattended use. Holds one 0600 SQLite mailbox per certificate fingerprint, presence proofs and groups. Symlinks, wrong owner or mode, and hard links are rejected. Change it only with a helper restart. Without it, the helper falls back to a legacy volatile inbox (256 messages, 4 MiB) with no wake or presence restore, and keeps groups in `$PI_CODING_AGENT_DIR/intercom/bridge-state`. |
-| `cwd`                             | The identity's presence and project association, the legacy `start` directory and the default spawn directory. It doesn't limit access.                                                                                                                                                                                                                                                                                            |
-| `wake.envFile`                    | Absolute path to an owned 0600 file defining `GROK_WAKE_WEBHOOK_URL` (HTTPS, without URL credentials or fragment) and `GROK_WAKE_WEBHOOK_KEY`. Requires `stateDir`. Reread on SIGHUP.                                                                                                                                                                                                                                              |
-| `launch`                          | Enables saved-session browsing, spawn and resume. Omit it for a messaging-only identity.                                                                                                                                                                                                                                                                                                                                           |
-| `packageRoot`                     | The installed Pi package for children. The helper runs that package's `bin.pi` with its own physical Node. Use the intended installed Pi, not a development SDK with the same version.                                                                                                                                                                                                                                             |
-| `sessionDir`                      | Owned 0700 directory for new journals, written 0600.                                                                                                                                                                                                                                                                                                                                                                               |
-| `workspaceRoots`                  | Up to 32 directories. Spawn and resume directories must be inside one. `["/"]` approves every path; the default empty list rejects spawn and resume.                                                                                                                                                                                                                                                                               |
-| `resumeDirs`                      | Up to 32 owned directories searched, with `sessionDir`, for saved sessions. Every journal path component must be owned and symlink-free.                                                                                                                                                                                                                                                                                           |
-| `provider`, `model`               | Optional default model; set both or neither. Omit them to use Pi's normal model selection.                                                                                                                                                                                                                                                                                                                                         |
-| `extensions`                      | 1–32 absolute extension paths, including Intercom. With `discoverResources: true`, use the same physical Intercom path that native settings load, so a session never runs two Intercom copies.                                                                                                                                                                                                                                     |
-| `discoverResources`               | Default `false`. `true` keeps Pi's normal discovery of extensions, skills, prompts and context files.                                                                                                                                                                                                                                                                                                                              |
-| `trustProject`                    | Default `false`. Chooses native `--approve` or `--no-approve` for the selected directory.                                                                                                                                                                                                                                                                                                                                          |
-| `offline`                         | Default `false`. `true` disables automatic catalog and network activity; requested inference still runs.                                                                                                                                                                                                                                                                                                                           |
-| `maxSessions`, `startupTimeoutMs` | Owned-session cap per identity, 1–16 (default 4; 32 per helper), and readiness deadline, 1–60000 ms (default 15000).                                                                                                                                                                                                                                                                                                               |
+| Field                             | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stateDir`                        | Owned 0700 directory, required for unattended use. Holds one 0600 SQLite mailbox per certificate fingerprint, a helper-wide wake ledger, presence proofs and groups. Symlinks, wrong owner or mode, and hard links are rejected. Change it only with a helper restart. Without it, the helper falls back to a legacy volatile inbox (256 messages, 4 MiB) with no wake or presence restore, and keeps groups in `$PI_CODING_AGENT_DIR/intercom/bridge-state`. |
+| `cwd`                             | The identity's presence and project association, the legacy `start` directory and the default spawn directory. It doesn't limit access.                                                                                                                                                                                                                                                                                                                       |
+| `wake.envFile`                    | Absolute path to an owned 0600 file defining `GROK_WAKE_WEBHOOK_URL` (HTTPS, without URL credentials or fragment) and `GROK_WAKE_WEBHOOK_KEY`. Requires `stateDir`. Reread on SIGHUP.                                                                                                                                                                                                                                                                         |
+| `launch`                          | Enables saved-session browsing, spawn and resume. Omit it for a messaging-only identity.                                                                                                                                                                                                                                                                                                                                                                      |
+| `packageRoot`                     | The installed Pi package for children. The helper runs that package's `bin.pi` with its own physical Node. Use the intended installed Pi, not a development SDK with the same version.                                                                                                                                                                                                                                                                        |
+| `sessionDir`                      | Owned 0700 directory for new journals, written 0600.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `workspaceRoots`                  | Up to 32 directories. Spawn and resume directories must be inside one. `["/"]` approves every path; the default empty list rejects spawn and resume.                                                                                                                                                                                                                                                                                                          |
+| `resumeDirs`                      | Up to 32 owned directories searched, with `sessionDir`, for saved sessions. Every journal path component must be owned and symlink-free.                                                                                                                                                                                                                                                                                                                      |
+| `provider`, `model`               | Optional default model; set both or neither. Omit them to use Pi's normal model selection.                                                                                                                                                                                                                                                                                                                                                                    |
+| `extensions`                      | 1–32 absolute extension paths, including Intercom. With `discoverResources: true`, use the same physical Intercom path that native settings load, so a session never runs two Intercom copies.                                                                                                                                                                                                                                                                |
+| `discoverResources`               | Default `false`. `true` keeps Pi's normal discovery of extensions, skills, prompts and context files.                                                                                                                                                                                                                                                                                                                                                         |
+| `trustProject`                    | Default `false`. Chooses native `--approve` or `--no-approve` for the selected directory.                                                                                                                                                                                                                                                                                                                                                                     |
+| `offline`                         | Default `false`. `true` disables automatic catalog and network activity; requested inference still runs.                                                                                                                                                                                                                                                                                                                                                      |
+| `maxSessions`, `startupTimeoutMs` | Owned-session cap per identity, 1–16 (default 4; 32 per helper), and readiness deadline, 1–60000 ms (default 15000).                                                                                                                                                                                                                                                                                                                                          |
 
 Children inherit the helper's environment, minus enclosing `PI_SUBAGENT_*` metadata, so set `PATH` in the service. A launch succeeds only when the exact saved session ID, name and file run idle in RPC mode and the session's own Intercom peer is published. That proves startup, not working provider credentials. A Pi dialog that needs a human is cancelled, and the session is stopped with `interaction_required`.
 
@@ -193,7 +193,7 @@ The first authenticated connection establishes persistent presence (see [Mailbox
 
 ### More instances
 
-Run one helper per remote agent instance. Each instance gets its own client name and key, port, `stateDir`, wake webhook, LaunchAgent label, Tailscale Serve port and remote host.
+Prefer one helper per Mac with all remote agents in its `clients` allowlist. Each identity gets its own client name, key and optional wake webhook; all identities and webhook URLs share one 20-attempt/hour ledger. If separate listeners are necessary, share the same owned `stateDir` to retain one SQLite allowance, use disjoint client lists and separate ports/LaunchAgent labels, and retain the common CA. Separate state directories create independent budgets; do not use them to multiply the Mac's allocation.
 
 Helpers on the same Mac must share one CA; `init` always creates a new one. Pi sessions on the Mac check every native control (see [Stop and cancel](#stop-and-cancel)) against a single policy file: `PI_INTERCOM_BRIDGE_CONFIG`, else `$PI_CODING_AGENT_DIR/intercom/bridge.json`, else `~/.pi/intercom-bridge/config.json`. That file must name the common CA and list the current pin of every instance, so update it whenever you issue, rotate or revoke any instance's certificate. A different Mac has its own CA and policy file.
 
@@ -227,10 +227,10 @@ api() { # api METHOD PATH [JSON]
 | ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | `POST /v1/register`     | `{}`                                                      | `sessionId`, `name`; other routes register automatically                        |
 | `GET /v1/list`          | —                                                         | live peers with unambiguous `target`s                                           |
-| `POST /v1/send`         | `{to,message}`                                            | `id`, `accepted`, `delivered`                                                   |
+| `POST /v1/send`         | `{to,message,passive?,messageId?}`                        | `id`, `accepted`, `delivered`                                                   |
 | `POST /v1/ask`          | `{to,message,timeoutMs?}`                                 | send receipt and `reply:{from,message}`                                         |
 | `POST /v1/reply`        | `{replyTo,message}`                                       | send receipt to the ask's saved sender                                          |
-| `GET /v1/inbox`         | `?after=CURSOR&limit=1..256`                              | `messages`, `nextCursor`, `hasMore`, `overflow`, `lostMessages`, `storageError` |
+| `GET /v1/inbox`         | `?after=CURSOR&limit=1..256&waitMs=0..10000`              | `messages`, `nextCursor`, `hasMore`, `overflow`, `lostMessages`, `storageError` |
 | `POST /v1/ack`          | `{ids:[...]}`, at most 256                                | `acked`, `retained`                                                             |
 | `POST /v1/broadcast`    | `{message,group?}`                                        | `status`, per-target `receipts`, member `errors`                                |
 | `GET /v1/groups`        | —                                                         | this identity's `groups`                                                        |
@@ -248,19 +248,27 @@ api() { # api METHOD PATH [JSON]
 
 Ask waits up to two minutes (`timeoutMs` 100–120000) for the exact recipient and `replyTo`; each identity has one outgoing ask at a time. A timeout doesn't retract a delivered ask, and a late answer arrives in the inbox. Spawn, resume and transcript lookup have a 75-second helper deadline (90 seconds in the CLI); ask has its timeout plus 15 seconds; other routes have 15 seconds. Live transcript controls keep their separate native response deadline; saved name lookup may scan the full catalog.
 
+Send defaults to active delivery (`steer`). Only `send` accepts the optional boolean `passive`; `true` maps to native `delivery:"passive"`, and `false` keeps the default. Use `node intercom-remote.mjs send --passive --to PEER --message TEXT` for mail without a model wake. Older helpers reject the unknown `passive` field before sending; the client never retries without it or redirects a failed mutation. Upgrade the receiving helper and consumer before relying on end-to-end no-wake delivery.
+
+Only `send` accepts an optional `messageId` (`--id ID` in the CLI): a nonblank string of at most 512 characters with no C0/C1 control characters or DEL. The ID is passed unchanged to the native recipient and returned as the receipt's `id`; omitting it still generates a random UUID. A stable ID does not guarantee deduplication, exactly-once delivery or a single provider run, and does not make retrying an unknown outcome safe. Older helpers reject the unknown field without sending; the client never retries without it.
+
 ### Mailbox, presence and wake
 
 **Intake.** Every message addressed to the identity is committed to its SQLite mailbox (full synchronous writes) before the helper surfaces it or completes a waiting ask. Unread mail and unanswered asks survive helper crashes, restarts and broker outages. There is no retention limit, so monitor disk space. If a write fails, the mailbox records `overflow`, `lostMessages` and `storageError`. If the loss itself can't be recorded, requests return 507 `mailbox_storage_failed` and the audit log shows `lossRecorded:false`.
 
 **Reading.** `GET /v1/inbox` returns a non-destructive page of at most 256 messages and 4 MiB. Keep reading with `after=nextCursor` while `hasMore` is true; start again from `0` to revisit unacked mail. The cursor is an opaque sequence number. Inbox and ack work while the broker is down.
 
+`waitMs` is an optional integer from 0 to 10000 (default 0, an immediate read). If the requested cursor page is empty, a positive wait returns as soon as matching mail is committed, a new admission loss is recorded, or the wait expires. Existing backlog returns immediately. Timeout returns a fresh empty page with the same cursor and current loss status; reads and waits never ack or consume mail. Use `node intercom-remote.mjs inbox --after CURSOR --wait-ms 10000`. Cancelling an inbox request cancels only that read, not other requests or the identity's broker connection. Revocation, certificate expiry, broker disconnect and helper shutdown still cancel the Session's outstanding requests. All requests, including waiting reads, share the eight-request cap per identity.
+
 **Acknowledging.** Ack an ordinary message to delete its payload; its ID stays as a tombstone so replays are ignored. Ack an ask to record that you've stored it: it appears in `retained`, stays in the inbox as a reply obligation and never triggers a fallback wake. A successful `reply` retires the ask. Reply goes to the ask's saved sender ID; if that sender is offline, it returns `peer_offline` and keeps the obligation. Ack is idempotent. In persistent mode, an answer returned by `ask` is also kept in the inbox; ack `reply.message.id` once you've consumed it.
 
 **Presence.** After the first authenticated connection, the helper writes a private presence proof (identity, `cwd` and certificate expiry) to `stateDir` and keeps the identity registered with the broker, refreshing every 15 seconds. It stays registered without remote polling until the certificate expires, the identity changes or is revoked, or the helper stops. A restarted helper restores presence from that proof without any remote request. A revoked identity is never restored.
 
-**Primary wake.** The remote consumer owns waking its agent. Poll the inbox, for example every 15 seconds; append each message to durable storage and fsync it; only then ack it. A crash before the ack replays the message, so deduplicate by `message.id`.
+**Primary wake.** The remote consumer owns waking its agent. Reissue bounded inbox waits without a polling sleep; append each message to durable storage and fsync it; only then ack it. Advance an in-memory tail cursor only after durable intake, draining all `hasMore` pages immediately. Keep that cursor across waits so already-stored retained asks don't cause a busy loop; restart from `0` after a crash and deduplicate by `message.id`. Keep failed ack obligations for retry even after advancing the tail. Each identity needs its own outstanding wait so an empty inbox cannot delay another identity. A wait timeout or reconnect is not a reason to wake an agent. Intake ACK proves storage, not model completion. This notification path requires a running consumer; cold-consumer fallback remains separate.
+
+**Passive mail.** Native `delivery:"passive"` and legacy `passive:true` messages stay readable and ACKable in the mailbox, but never trigger the helper's fallback webhook, including after restart. Suppressing a notification does not acknowledge or consume the message. Consumers must also honor these flags: durably store and expose passive mail without invoking their own wake webhook. Passive backlogs do not prevent active mail on later pages from triggering fallback. Non-ask text beginning with the exact uppercase prefix `ACK`, `DUP-ACK`, `FYI`, `NOTE`, `RECEIPT` or `NOWAKE`, followed by whitespace, `:` or end of text, also retires notification intent only. Explicit `expectsReply:true` requests still wake regardless of these prefixes. Native passive intent always wins; there is no text-length cutoff.
 
-**Fallback wake.** If a message stays unacked for at least 120 seconds, the helper POSTs one wake for the oldest such message to `GROK_WAKE_WEBHOOK_URL` with `Authorization: Bearer <GROK_WAKE_WEBHOOK_KEY>` and this body:
+**Fallback wake.** The first observation after a successful mailbox commit durably schedules a two-second transport/fsync ACK grace. Time blocked on the mailbox's SQLite FULL write does not consume that grace. If actionable mail remains unacked, the helper POSTs one wake for the oldest such message to `GROK_WAKE_WEBHOOK_URL` with `Authorization: Bearer <GROK_WAKE_WEBHOOK_KEY>` and this body:
 
 ```json
 {
@@ -273,7 +281,29 @@ Ask waits up to two minutes (`timeoutMs` 100–120000) for the exact recipient a
 }
 ```
 
-`ask_id` is the message ID for asks. A 2xx response is logged as `accepted`, but it can't prove the consumer stored the message, so the wake stays pending: the helper posts the same oldest unacked message again every 5 minutes until the consumer acks it. Acking an ask counts. Deduplicate wakes by `message_id`. Other responses and transport failures retry with doubling backoff up to 5 minutes. Redirects are refused, each request times out after 10 seconds, and the helper sends at most one wake per cycle. Fallback stops while the identity is revoked or its certificate has expired.
+`ask_id` is the message ID for asks. All retained, authorized certificate fingerprints targeting the same wake URL form one cold batch. Later messages join that batch without another POST before its retry deadline. A 2xx response is logged as `accepted`, but cannot prove durable intake: notification and payload remain pending until real inbox ACK (acking an ask counts). Deduplicate wakes by `message_id`.
+
+**Durable admission.** `wake-quota.sqlite` reserves every POST attempt before dispatch, including rejection, timeout and unknown outcomes, under SQLite `synchronous=FULL`. Each slot remains occupied until a full hour after the POST settles (response, error or abort), so COMMIT, connection and TLS latency cannot shorten the wire-attempt window. All identities, bots, keys and URLs share at most **20 attempts in a sliding hour** per ledger. Restart, SIGHUP and certificate/URL rotation do not reset it. Uncertainty and backoff are committed with each reservation: retry after 30 seconds, doubling through 60, 120 and 240 seconds to a five-minute ceiling while the batch remains unacknowledged. Real ACK retirement clears only that batch's retry state; fresh work receives the two-second grace immediately when quota remains. Redirects are refused and each request times out after ten seconds. Storage errors fail closed before POST; repair permissions/disk/corruption without deleting or replacing the ledger to reset usage.
+
+An open attempt has no expiry while its listener is alive. Private `wake-owner-*.lock` SQLite files hold OS locks for each listener's lifetime, including across process pauses; they are not PID or timed leases. Owner-file creation and lock acquisition are serialized with ledger recovery, so another listener cannot reap an initializing owner. After a listener exits, another listener conservatively counts its unfinished attempts for a full hour from recovery. Failed settlement writes remain counted and are retried before that listener dispatches again. Do not remove these files or any ledger to regain quota. Stop **all** old listeners before upgrading a version-1 ledger: its pre-dispatch timestamps cannot prove POST completion, so migration retains every recorded slot for a full hour from upgrade (or its recorded future time, if later), preserving retry state. Subsequent opens do not restart that migration hold.
+
+Mailbox commits/ACKs, startup reconstruction and exact retry/budget deadlines drive fallback. There is no periodic intake scan. Presence maintenance's separate broker lease timer is not inbox polling. Pending mail recovers automatically after budget expiry, failures and helper restart. Revocation or certificate expiry stops that identity's fallback without deleting unread payload.
+
+**First upgrade and audit preflight.** Fresh empty installations start with an unused allowance. An installation with mailbox/presence state but no ledger has unknown legacy usage and conservatively reserves all 20 slots for one hour. This is a migration quota exception, not a first-wake latency policy. Native JSONL outcomes have timestamps, but omit crash-before-log attempts and may have `log_overflow` gaps. Do not treat them as a complete pre-dispatch ledger.
+
+Where immutable prior source/runtime and owned audit history prove complete coverage, stop every legacy writer (disable automatic restart) before preparing migration. Bound unconfirmed attempts independently from each prior worker's maximum in-flight dispatches; sum these across all identities. Do not assume zero merely because shutdown was requested. This preflight checks the supplied PID has exited, rejects audit overflow and existing ledger/history, and writes a private fsynced `wake-history.json`:
+
+```bash
+node "$PKG/scripts/intercom-bridge-wake-preflight.mjs" \
+  --state-dir "$BRIDGE/state" --audit "$BRIDGE/logs/audit.jsonl" \
+  --complete-since 'ISO_TIME_AT_LEAST_ONE_HOUR_BEFORE_STOP' \
+  --stopped-at 'ISO_TIME_AFTER_ALL_LEGACY_WRITERS_STOPPED' \
+  --stopped-pid OLD_HELPER_PID --unknown-attempts PROVEN_BOUND_0_TO_20
+```
+
+`--complete-since` attests verified coverage; outcomes alone cannot prove it. The operator must verify **all** previous writer processes are stopped, not just the checked PID, and no legacy writer may run after sealing history. If that proof or a bounded unknown count is unavailable, skip preflight and retain the conservative reservation. On first creation the helper seeds recorded attempts still within the sliding hour, plus unknown reservations at startup, preserving known remaining capacity. Existing ledgers never reseed; malformed, unreadable or corrupt state denies admission. Never manually edit/reset the database, switch state directories to gain quota, or roll back to a non-accounting helper without a new conservative reconciliation.
+
+**Distributed ceiling.** URL grouping is local coalescing, not provider-account identity or exactly-once execution. Two simultaneously cold Macs can each issue a wake before either sees intake. Literal cross-Mac single admission requires a neutral admission authority governing every writer; none is introduced here. A known controlled allocation of two Box senders at 20 each (including their offline-peer POSTs), plus Work Mac 20 and Personal Mac 20 across all bots, totals 80 attempts/hour. That neither governs unrelated account traffic nor proves the provider's whole-account 100/hour cap. Offline-peer communication remains the Box owners' responsibility when both Macs sleep/offline; sleeping Macs cannot deliver locally until online, and stored queues remain retained.
 
 ### Sessions
 
@@ -380,20 +410,21 @@ Credential commands hold `DIR/.credentials.lock` for the whole update and fail r
 | `broker_unavailable`, or a refusal to start a second broker | Let the unhealthy broker exit, or start a normal Pi session, then retry. Don't delete broker files or kill a working broker.                                            |
 | 507 `mailbox_storage_failed`                                | Fix disk space or `stateDir` permissions, then restart the helper. `lossRecorded:false` audit records mark uncounted losses.                                            |
 | No fallback wakes                                           | Check `wake_delivery` records (`http_rejected` with status, `transport_unconfirmed`, `storage_unavailable`) and the env file's mode and URL. Acked messages never wake. |
-| Repeated wakes for one `message_id`                         | Expected every 5 minutes after an `accepted` wake until the consumer acks the message. Fix the consumer's store-then-ack loop.                                          |
+| Repeated wakes for one `message_id`                         | Accepted-but-unacked batches retry on durable 30-second-to-five-minute backoff, within the shared quota. Fix the consumer's store-then-ack loop.                        |
 | Lost response, `task_unconfirmed` or `control_unconfirmed`  | The outcome is unknown. Inspect the inbox, sessions or peer before retrying.                                                                                            |
 | `launch_in_progress` or `stop_timeout`                      | Inspect `GET /v1/sessions`; retry stop until it reports `exited`.                                                                                                       |
 | `allowlist_reloaded` with `failed_closed`                   | The config is invalid; every identity is denied and owned sessions stopped. Fix the config and send SIGHUP again.                                                       |
 
 ## Verification
 
-The process-boundary tests use a private real broker, real certificates, real HTTPS and the remote CLI. Launch tests use the installed Pi dependency graph with a native faux provider, so no paid inference or external credentials are needed. Coverage includes cold SIGKILL restarts with mailbox and presence recovery, delayed fallback wakes and ack suppression, bounded cursor drains, storage failures, spawn and resume identity and model preservation, owned cancel and observed exit, native control authorization and old-owner timeouts, live transcripts and the saved-journal reader, same-CA server renewal with an unchanged client key, and restart-persistent groups.
+The process-boundary tests use a private real broker, real certificates, real HTTPS and the remote CLI. Launch tests use the installed Pi dependency graph with a native faux provider, so no paid inference or external credentials are needed. Coverage includes cold SIGKILL restarts with mailbox and presence recovery, event-driven fallback, shared durable quota and ack suppression, bounded cursor drains, storage failures, spawn and resume identity and model preservation, owned cancel and observed exit, native control authorization and old-owner timeouts, live transcripts and the saved-journal reader, same-CA server renewal with an unchanged client key, and restart-persistent groups.
 
 ```bash
 node --test test/integration/intercom-bridge.test.ts test/integration/intercom-bridge-delivery.test.ts \
+  test/integration/intercom-bridge-wake-budget.test.ts test/integration/intercom-bridge-wake-state.test.ts \
   test/integration/intercom-bridge-launch.test.ts test/integration/intercom-bridge-lifecycle.test.ts \
   test/integration/intercom-native-control.test.ts test/unit/intercom-transcript.test.ts
 env -u PI_TIMING -u PI_EXTENSION_PERFORMANCE npm run ci
 ```
 
-For a live smoke test from the remote host, run `list`, ask one deliberately chosen session to reply `bridge-smoke-ok`, and fetch `GET /v1/sessions?live=true&saved=true`. Pause the remote consumer for more than two minutes to confirm a fallback wake. Keep only a redacted record: platform, route, accepted or delivered flags and the reply text. Never publish config, keys, wake URLs or raw inbox and list output.
+For a live smoke test from the remote host, run `list`, ask one deliberately chosen session to reply `bridge-smoke-ok`, and fetch `GET /v1/sessions?live=true&saved=true`. With quota available, pause remote intake and send a deliberate actionable message to confirm fallback just after the two-second ACK grace; restore intake and verify actual ACK retires retry intent. Keep only a redacted record: platform, route, accepted or delivered flags and the reply text. Never publish config, keys, wake URLs or raw inbox and list output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.48.0",
+  "version": "0.49.1",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/intercom-bridge-wake-preflight.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { readBridgeFile, writeBridgeJson } from "../src/pi-intercom/bridge-files.ts";
+import { stateDirectory } from "../src/pi-intercom/bridge-storage.ts";
+import { isRecord } from "../src/shared/unknown.ts";
+
+// Run only after proving this history covers every legacy worker and stopping those workers.
+// --complete-since is the operator's coverage attestation, not something outcomes can prove.
+const { values } = parseArgs({
+  options: {
+    "state-dir": { type: "string" },
+    audit: { type: "string" },
+    "complete-since": { type: "string" },
+    "stopped-at": { type: "string" },
+    "stopped-pid": { type: "string" },
+    "unknown-attempts": { type: "string" },
+  },
+});
+try {
+  const stateDir = stateDirectory(values["state-dir"]);
+  const coveredSince = Date.parse(values["complete-since"] ?? "");
+  const stoppedAt = Date.parse(values["stopped-at"] ?? "");
+  const pid = Number(values["stopped-pid"]);
+  const unknownAttempts = Number(values["unknown-attempts"]);
+  if (
+    stateDir === undefined ||
+    values.audit === undefined ||
+    !Number.isSafeInteger(coveredSince) ||
+    !Number.isSafeInteger(stoppedAt) ||
+    coveredSince > stoppedAt - 3600000 ||
+    stoppedAt > Date.now() ||
+    !Number.isSafeInteger(pid) ||
+    pid <= 0 ||
+    values["unknown-attempts"] === undefined ||
+    !Number.isInteger(unknownAttempts) ||
+    unknownAttempts < 0 ||
+    unknownAttempts > 20
+  ) {
+    throw new Error(
+      "Require state-dir, private audit, complete-since (at least one hour before stopped-at), stopped-at, stopped-pid and unknown-attempts (0..20).",
+    );
+  }
+  try {
+    process.kill(pid, 0);
+    throw new Error("Legacy helper is still running; stop it before preflight.");
+  } catch (error) {
+    if (error.code !== "ESRCH") {
+      throw error;
+    }
+  }
+  if (
+    existsSync(join(stateDir, "wake-quota.sqlite")) ||
+    existsSync(join(stateDir, "wake-history.json"))
+  ) {
+    throw new Error("Preflight cannot replace an existing ledger/history. Preserve it.");
+  }
+  const attempts = [];
+  const outcomes = new Set(["accepted", "http_rejected", "transport_unconfirmed"]);
+  const audit = readBridgeFile(values.audit, true, 32 * 1024 * 1024).toString("utf8");
+  for (const line of audit.split("\n")) {
+    if (line.trim() === "") {
+      continue;
+    }
+    /** @type {unknown} */
+    const raw = JSON.parse(line);
+    if (!isRecord(raw) || typeof raw.timestamp !== "string") {
+      throw new Error("Invalid audit record.");
+    }
+    const entry = raw;
+    const timestamp = Date.parse(entry.timestamp);
+    if (!Number.isSafeInteger(timestamp)) {
+      throw new Error("Audit record has no valid timestamp.");
+    }
+    if (timestamp < coveredSince || timestamp > stoppedAt) {
+      continue;
+    }
+    if (entry.event === "log_overflow") {
+      throw new Error(
+        "Audit overflow prevents complete-history migration; use conservative startup.",
+      );
+    }
+    if (
+      entry.event === "wake_delivery" &&
+      typeof entry.result === "string" &&
+      outcomes.has(entry.result)
+    ) {
+      attempts.push(timestamp);
+    }
+  }
+  if (attempts.length > 10000) {
+    throw new Error("Attempt history exceeds bounded migration input.");
+  }
+  writeBridgeJson(join(stateDir, "wake-history.json"), {
+    coveredSince,
+    stoppedAt,
+    attempts,
+    unknownAttempts,
+  });
+  console.log(
+    JSON.stringify({
+      result: "prepared",
+      recordedAttempts: attempts.length,
+      unknownAttempts,
+      note: "Start the new helper against this same stateDir; never copy/reset its ledger. Coverage and unknown-attempt bounds remain operator-owned proof.",
+    }),
+  );
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/intercom-remote.mjs

@@ -15,9 +15,12 @@ Environment (required):
 Options:
   --to PEER            Recipient name, peer ID or native ID for messages/controls
   --message TEXT       Message for send/ask/reply
+  --id ID              Send only: exact message ID (default: random; no deduplication guarantee)
+  --passive            Send only: mailbox delivery without waking the recipient
   --reply-to ID        Inbound ask ID from inbox, for reply
   --timeout-ms MS      Ask: 100..120000 (default 120000); control: 100..10000 (default 3000)
   --after CURSOR       Inbox cursor from nextCursor (default: 0)
+  --wait-ms MS         Inbox: wait for new mail, 0..10000 (default: 0)
   --limit COUNT        Inbox: 1..256; sessions/transcript: 1..100
   --name NAME          Start/reuse a named idle Pi session under local policy
   --session-id ID      Native ID for resume, stop or cancel
@@ -56,7 +59,7 @@ No automatic retries: a lost response does not prove a message was unsent.`);
 
 function allowedOptions(action) {
   const fields = {
-    inbox: ["after", "limit"],
+    inbox: ["after", "limit", "wait-ms"],
     start: ["name"],
     spawn: ["name", "cwd", "task", "provider", "model"],
     resume: ["session-id", "name", "target", "task"],
@@ -68,7 +71,7 @@ function allowedOptions(action) {
     broadcast: ["message", "group"],
     "group-send": ["message", "group"],
     "group-upsert": ["name", "members", "name-pattern", "cwd-pattern"],
-    send: ["to", "message"],
+    send: ["to", "message", "passive", "id"],
     ask: ["to", "message", "timeout-ms"],
     reply: ["reply-to", "message"],
   };
@@ -86,6 +89,16 @@ function requireMessage(recipient, message) {
   }
 }
 
+function sendId(id) {
+  // Match the bridge's label bounds without changing the caller's ID.
+  // oxlint-disable-next-line no-control-regex
+  const controls = /[\u0000-\u001f\u007f-\u009f]/;
+  if (id !== undefined && (id.trim() === "" || id.length > 512 || controls.test(id))) {
+    throw new Error("Invalid message ID.");
+  }
+  return id;
+}
+
 function resumeBody(options) {
   if (["name", "session-id", "target"].filter((key) => options[key] !== undefined).length !== 1) {
     throw new Error("Resume requires exactly one --name, --session-id or --target.");
@@ -182,7 +195,9 @@ function requestBody(action, options, ids, timeout) {
     return {
       to: recipient,
       message: options.message,
+      messageId: sendId(options.id),
       ...(action === "ask" ? { timeoutMs: timeout } : {}),
+      ...(options.passive === true ? { passive: true } : {}),
     };
   }
   if (action === "ack") {
@@ -219,15 +234,23 @@ function privateKey(path) {
 function inboxQuery(options) {
   const after = options.after ?? "0";
   const limit = options.limit ?? "256";
+  const waitMs = options["wait-ms"] ?? "0";
   if (
     !/^(0|[1-9]\d{0,15})$/.test(after) ||
     !Number.isSafeInteger(Number(after)) ||
     !/^[1-9]\d{0,2}$/.test(limit) ||
-    Number(limit) > 256
+    Number(limit) > 256 ||
+    !/^(0|[1-9]\d{0,3}|10000)$/.test(waitMs)
   ) {
-    throw new Error("--after must be a nonnegative safe integer cursor; --limit must be 1..256.");
+    throw new Error(
+      "--after must be a nonnegative safe integer cursor; --limit must be 1..256; --wait-ms must be 0..10000.",
+    );
   }
-  return new URLSearchParams({ after, limit }).toString();
+  const query = new URLSearchParams({ after, limit });
+  if (options["wait-ms"] !== undefined) {
+    query.set("waitMs", waitMs);
+  }
+  return query.toString();
 }
 
 function requestQuery(action, options) {
@@ -245,13 +268,17 @@ let body, action, origin, timeout, query;
 try {
   const parsed = parseArgs({
     allowPositionals: true,
+    tokens: true,
     options: {
       help: { type: "boolean", short: "h" },
       to: { type: "string" },
       message: { type: "string" },
+      id: { type: "string" },
+      passive: { type: "boolean" },
       "reply-to": { type: "string" },
       "timeout-ms": { type: "string" },
       after: { type: "string" },
+      "wait-ms": { type: "string" },
       limit: { type: "string" },
       name: { type: "string" },
       "session-id": { type: "string" },
@@ -278,6 +305,13 @@ try {
     process.exit(0);
   }
   const options = parsed.values;
+  for (const name of ["wait-ms", "id"]) {
+    if (
+      parsed.tokens.filter((token) => token.kind === "option" && token.name === name).length > 1
+    ) {
+      throw new Error(`--${name} must not be repeated.`);
+    }
+  }
   [action] = parsed.positionals;
   if (
     ![

package/src/pi-intercom/bridge-config.ts

@@ -5,7 +5,7 @@ import { parseEnv } from "node:util";
 import { isUnknownArray } from "../shared/unknown.ts";
 import { BODY_LIMIT, object, label, fingerprint } from "./bridge-protocol.ts";
 import { launchPolicy, type LaunchPolicy } from "./bridge-launch-policy.ts";
-import { stateDirectory } from "./bridge-mailbox.ts";
+import { stateDirectory } from "./bridge-storage.ts";
 import { readBridgeFile } from "./bridge-files.ts";
 
 const MAX_CLIENTS = 64;

package/src/pi-intercom/bridge-mailbox.ts

@@ -1,6 +1,5 @@
-import { closeSync, constants, fstatSync, lstatSync, openSync, realpathSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import type { DatabaseSync } from "node:sqlite";
+import { privateDatabase } from "./bridge-storage.ts";
 import { isRecord, type UnknownRecord } from "../shared/unknown.ts";
 import { normalizeMessage, normalizeSessionInfo } from "./types.ts";
 import type { Envelope } from "./bridge-ask.ts";
@@ -9,7 +8,6 @@ import {
   INBOX_BYTES,
   INBOX_COUNT,
   fingerprint as certificateFingerprint,
-  label,
 } from "./bridge-protocol.ts";
 
 interface Entry extends Envelope {
@@ -32,64 +30,10 @@ export interface NotificationPage extends InboxPage {
   readonly messages: readonly PendingNotification[];
 }
 
-export function stateDirectory(value: unknown): string | undefined {
-  if (value === undefined) {
-    return;
-  }
-  const path = label(value, "stateDir", 4096);
-  const stat = lstatSync(path);
-  if (
-    !isAbsolute(path) ||
-    !stat.isDirectory() ||
-    stat.uid !== process.getuid?.() ||
-    (stat.mode & 0o777) !== 0o700
-  ) {
-    throw new Error("stateDir must be an absolute owned directory with mode 0700, not a symlink.");
-  }
-  return realpathSync(path);
-}
-
-function privateFile(path: string, create = false): void {
-  const flags = create ? constants.O_RDWR | constants.O_CREAT : constants.O_RDONLY;
-  const fd = openSync(path, flags | constants.O_NOFOLLOW, 0o600);
-  try {
-    const stat = fstatSync(fd);
-    if (
-      !stat.isFile() ||
-      stat.uid !== process.getuid?.() ||
-      (stat.mode & 0o777) !== 0o600 ||
-      stat.nlink !== 1
-    ) {
-      throw new Error("Mailbox files must be owned regular files with mode 0600 and one link.");
-    }
-  } finally {
-    closeSync(fd);
-  }
-}
-
 function database(stateDir: string, fingerprint: string): DatabaseSync {
-  stateDirectory(stateDir);
-  const path = join(stateDir, `${certificateFingerprint(fingerprint)}.sqlite`);
-  privateFile(path, true);
-  for (const suffix of ["-journal", "-wal", "-shm"]) {
-    try {
-      lstatSync(`${path}${suffix}`);
-    } catch (error) {
-      if (isRecord(error) && error.code === "ENOENT") {
-        continue;
-      }
-      throw error;
-    }
-    privateFile(`${path}${suffix}`);
-  }
-  const db = new DatabaseSync(path, { enableDoubleQuotedStringLiterals: false });
+  const { db } = privateDatabase(stateDir, `${certificateFingerprint(fingerprint)}.sqlite`);
   try {
     db.exec(`
-      PRAGMA journal_mode=DELETE;
-      PRAGMA synchronous=FULL;
-      PRAGMA secure_delete=ON;
-      PRAGMA cache_size=-1024;
-      PRAGMA busy_timeout=1000;
       CREATE TABLE IF NOT EXISTS mailbox (
         sequence INTEGER PRIMARY KEY AUTOINCREMENT,
         id TEXT NOT NULL UNIQUE,

package/src/pi-intercom/bridge-presence.ts

@@ -15,6 +15,7 @@ interface PresenceOwner {
   readonly stateDir: string;
   readonly clients: () => ReadonlyMap<string, Identity>;
   readonly connect: (identity: Identity, expires: number) => Promise<void>;
+  readonly restored: (identity: Identity, expires: number) => void;
 }
 
 export class PersistentPresence {
@@ -26,7 +27,11 @@ export class PersistentPresence {
 
   constructor(owner: PresenceOwner) {
     this.owner = owner;
-    for (const identity of owner.clients().values()) {
+    this.restoreAll();
+  }
+
+  restoreAll(): void {
+    for (const identity of this.owner.clients().values()) {
       this.restore(identity);
     }
   }
@@ -55,6 +60,7 @@ export class PersistentPresence {
           cwd: identity.cwd,
           expires: value.expires,
         });
+        this.owner.restored(identity, value.expires);
       }
     } catch {
       // An absent/invalid saved registration never grants a certificate identity.