@fitchmultz/pi-subagents 0.46.2 → 0.47.0

package/docs/intercom-bridge.md

@@ -10,9 +10,9 @@ Optional HTTPS messaging proxy and locally controlled Pi-session launcher for a
 
 **Auth/authority:** TLS 1.2+ with client certificates issued by a private CA **and** an explicit SHA-256 certificate fingerprint allowlist. Each allowlisted certificate fixes the peer name and Mac project directory; remote payloads cannot change identity, cwd, socket, shell commands, or presence. Certificates last seven days. TLS verifies the server CA and loopback SAN; never use `curl -k` or disable certificate checks. The proxy exposes register/list/send/ask/reply, inbox/ack receipt plumbing, and optional name-only start plus own-launched sessions/stop operations. No broker admin, topic operations, file reads, or shell endpoint.
 
-**Socket discovery:** reuse the actual `IntercomClient`, `getBrokerSocketPath()` and framing code. With the same Mac uid, `PI_CODING_AGENT_DIR` (default `~/.pi/agent`) and `TMPDIR` as Pi, the preferred path is `$TMPDIR/pi-intercom-<sha256(uid:agentDir)[0:16]>/broker.sock`; long paths fall back to `/tmp`. The client's existing owned-socket legacy fallback is retained. No hardcoded `/var/folders` path, chmod, broker spawn, PID-file operation, or broker restart. An unavailable broker returns an error; start a normal Pi session to bring it up.
+**Socket discovery:** reuse the actual `IntercomClient`, `getBrokerSocketPath()` and framing code. With the same Mac uid, `PI_CODING_AGENT_DIR` (default `~/.pi/agent`) and `TMPDIR` as Pi, the preferred path is `$TMPDIR/pi-intercom-<sha256(uid:agentDir)[0:16]>/broker.sock`; long paths fall back to `/tmp`. The client's existing owned-socket legacy fallback is retained. No hardcoded `/var/folders` path, socket chmod, or broker restart. Without `stateDir`, an unavailable broker returns an error; start a normal Pi session to bring it up. Durable presence uses Intercom's safe acquisition to start a detached broker only when none is running, including before any Pi session starts after reboot. Acquisition maintains the normal PID-file/spawn-lock bookkeeping, reuses a healthy broker and refuses to replace a live unhealthy broker that may own accepted work.
 
-**Delivery/lifecycle:** one broker peer per authorized certificate, registered lazily on the first API call, with a five-minute inactivity lease. Poll inbox to maintain presence. Send returns broker acceptance, not proof a model consumed it. Ask steers the recipient and waits at most two minutes for both the exact recipient ID and exact `replyTo`. One outgoing ask per identity. Revocation/expiry/shutdown/client disconnect terminate waits. Inbox is bounded and volatile; overflow is reported, not silently described as successful receipt. Restarting the helper loses inbox contents and pending replies. Upgrade to a durable inbox journal if restart recovery is required; existing Pi recipients still save their own messages normally.
+**Delivery/lifecycle:** one broker peer per authorized certificate. Without `stateDir`, registration is lazy and has a five-minute inactivity lease; poll inbox to maintain presence. With `stateDir`, an authenticated identity has durable presence restored after helper restart and refreshed without remote polling until expiry, revocation or helper shutdown. Send returns broker acceptance, not proof a model consumed it. Ask steers the recipient and waits at most two minutes for both the exact recipient ID and exact `replyTo`. One outgoing ask per identity. Revocation/expiry/shutdown/client disconnect terminate waits. With a local `stateDir`, inbox intake is committed to private SQLite storage before publication or satisfying an outgoing ask. Unacked messages and unanswered inbound asks survive helper restart, idle-lease retirement and broker outage. Inbox reads are non-destructive, bounded cursor pages; ack deletes only ordinary inbox payloads, and successful reply retires an inbound ask. Sender departure does not discard a reply obligation: reply still targets the saved exact sender ID and returns `peer_offline` without deletion while that ID is offline. Without `stateDir`, the legacy 256-message/4 MiB volatile inbox remains; overflow and lease/shutdown loss are reported. Outgoing HTTP ask waits themselves are not resumed after helper restart; persistent mode retains received answers in inbox for recovery and ack.
 
 **Audit:** JSONL metadata on stdout: request/connection identity, certificate fingerprint, operation, peer/message IDs and outcome. `session_closed` confirms broker disconnection and removal of the retiring session; cancellation still rejects requests immediately. Message/attachment bodies and keys are not logged. Protect logs (0700 directory, 0600 files); rotate them with your normal log tooling. Never publish private config/keys or raw inbox/list output as smoke evidence.
 
@@ -45,6 +45,24 @@ The last JSON line contains paths to the issued client `cert`/`key`, trusted `ca
 }
 ```
 
+### Enable durable mailboxes
+
+Create a dedicated owned **0700** directory and add its absolute path as top-level `stateDir` in the private configuration:
+
+```bash
+mkdir -m 700 "$BRIDGE/mailboxes"
+```
+
+```json
+{ "stateDir": "/Users/mitch/.pi/intercom-bridge/mailboxes" }
+```
+
+This opt-in does not enable Pi-session launches or require a Pi SDK. It does enable unattended broker acquisition for durable presence: after reboot or broker exit, the helper can start a broker without a running Pi session. It never restarts or replaces a live broker. Each certificate fingerprint owns a separate **0600** SQLite database. Directory symlinks, database/SQLite-sidecar symlinks, wrong ownership/modes and hard-linked files are rejected. SQLite uses full synchronous commits and a bounded cache; no mailbox-wide hydration is needed. Protect the directory and any backups: databases contain private message bodies, though audit logs do not. `stateDir` changes require helper restart, not SIGHUP.
+
+There is no automatic retention limit on unacked messages or unanswered asks. Pages contain at most 256 messages and 4 MiB of serialized envelopes (plus small response metadata); read additional pages with `nextCursor` while `hasMore` is true. Message IDs remain as payload-free tombstones after completion to suppress duplicate/replayed IDs, including after restart. Provision and monitor disk space. Failed disk admission sets durable `overflow`, `lostMessages` and `storageError` when the loss ledger can still be committed; if that also fails, the helper reports `mailbox_storage_failed` (HTTP 507), closes the affected broker peer and logs metadata with `lossRecorded:false`. A failing disk cannot guarantee durable loss bookkeeping. Broker acceptance alone never proves mailbox persistence or remote consumption.
+
+Persistent inbox/ack calls remain available while the broker is down; they do not require broker registration. Authenticate once with `register` or another successful connection to establish the private presence proof. Durable presence then reconnects independently, including after helper restart, without remote polling. Revoked/expired certificates still cannot read stored mail or restore presence. Mailboxes are fingerprint-scoped: rotating a certificate does not transfer old private mail to its replacement. Retain the old database for local recovery rather than automatically authorizing a new credential to read it.
+
 `cwd` controls presence/project association, **not** an authorization restriction. `list` intentionally returns all connected peer identities, omitting topics/subscriptions. Target full IDs or the returned `target` when names collide. Port `0` requests an ephemeral port, reported in the listening log; a fixed port is easier for SSH.
 
 Start the helper in a dedicated terminal (or supervise this exact command with launchd):
@@ -70,7 +88,7 @@ launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.fitchmultz.pi-i
 launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.fitchmultz.pi-intercom-bridge.plist"
 ```
 
-The installed agent has no `KeepAlive` auto-restart; stopping its helper really stops access. Remove its plist to disable future login starts permanently. Inspect/drain inbox before a planned helper restart because it is volatile.
+The installed agent has no `KeepAlive` auto-restart; stopping its helper really stops access. Remove its plist to disable future login starts permanently. With `stateDir` enabled, unacked mail survives helper restart. Inspect/drain inbox before restarting a legacy volatile-mode helper.
 
 ### Tunnel and provision Grok
 
@@ -172,7 +190,7 @@ node "$REMOTE" reply --reply-to QUESTION_ID_FROM_INBOX --message 'Proceed with t
 node "$REMOTE" ack ORDINARY_MESSAGE_ID_FROM_INBOX
 ```
 
-Poll inbox at a reasonable cadence (for example every 5–15 seconds) while Grok is available. Fetch is non-destructive, so retrying a fetch cannot lose messages; persist/consume then ack ordinary messages. Inbound asks remain in the inbox until `reply` succeeds; ack does not discard a reply obligation. Use `send` for most coordination and `ask` only when Grok really needs a blocking answer. The CLI has a hard request deadline (ask timeout + 15 seconds), validates TLS, emits JSON, and exits 1 on errors / 2 on invalid arguments. It never retries mutations automatically.
+Poll inbox at a reasonable cadence (for example every 5–15 seconds) while Grok is available. Fetch is non-destructive, so retrying a fetch cannot lose messages; persist/consume then ack ordinary messages. In persistent mode, follow `hasMore` using `inbox --after NEXT_CURSOR --limit 256`; do not treat the first page as the entire inbox. Restart a drain from cursor `0` to revisit unacked messages. Inbound asks remain in the inbox until `reply` succeeds; ack does not discard a reply obligation. Use `send` for most coordination and `ask` only when Grok really needs a blocking answer. The CLI has a hard request deadline (ask timeout + 15 seconds), validates TLS, emits JSON, and exits 1 on errors / 2 on invalid arguments. It never retries mutations automatically.
 
 Curl works too, with bounded waiting and the same TLS files:
 
@@ -188,18 +206,22 @@ curl --fail-with-body --max-time 135 \
 
 All routes require mTLS and the certificate allowlist. Unknown routes/fields, wrong methods, non-JSON bodies, unsafe control characters, and requests larger than 64 KiB are rejected. No CORS; browser-origin requests are rejected. Success is `{ "ok": true, ... }`; application failures are `{ "ok": false, "error": { "code": "...", "message": "..." } }` with a non-2xx status. Certificate/allowlist admission can terminate TLS before HTTP; the CLI reports that as a TLS/transport error. No remote-controlled broker frame or command is passed through.
 
-| Route               | Request                   | Success fields                                                            |
-| ------------------- | ------------------------- | ------------------------------------------------------------------------- |
-| `POST /v1/register` | `{}`                      | `sessionId`, `name` (also automatic on other operations)                  |
-| `GET /v1/list`      | none                      | `sessionId`, `sessions` (metadata + unambiguous targets)                  |
-| `POST /v1/send`     | `{to,message}`            | `id`, `accepted`, `delivered`                                             |
-| `POST /v1/ask`      | `{to,message,timeoutMs?}` | send receipt and `reply:{from,message}`                                   |
-| `GET /v1/inbox`     | none                      | `messages:[{from,message}]`, `overflow`, `lostMessages`                   |
-| `POST /v1/reply`    | `{replyTo,message}`       | send receipt; target derived from the received ask                        |
-| `POST /v1/ack`      | `{ids:[...]}`             | `acked`, `retained`                                                       |
-| `POST /v1/start`    | `{name}`                  | `session:{sessionId,peerId,name,status,pid,sessionFile,error?}`, `reused` |
-| `GET /v1/sessions`  | none                      | `sessions` (only current helper/identity-owned launch records)            |
-| `POST /v1/stop`     | `{sessionId}`             | `session` with observed `exited` status; journal retained                 |
+| Route               | Request                            | Success fields                                                                                   |
+| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `POST /v1/register` | `{}`                               | `sessionId`, `name` (also automatic on other operations)                                         |
+| `GET /v1/list`      | none                               | `sessionId`, `sessions` (metadata + unambiguous targets)                                         |
+| `POST /v1/send`     | `{to,message}`                     | `id`, `accepted`, `delivered`                                                                    |
+| `POST /v1/ask`      | `{to,message,timeoutMs?}`          | send receipt and `reply:{from,message}`                                                          |
+| `GET /v1/inbox`     | `?after=CURSOR&limit=N` (optional) | `messages:[{from,message}]`, `nextCursor`, `hasMore`, `overflow`, `lostMessages`, `storageError` |
+| `POST /v1/reply`    | `{replyTo,message}`                | send receipt; target derived from the received ask                                               |
+| `POST /v1/ack`      | `{ids:[...]}`                      | `acked`, `retained`                                                                              |
+| `POST /v1/start`    | `{name}`                           | `session:{sessionId,peerId,name,status,pid,sessionFile,error?}`, `reused`                        |
+| `GET /v1/sessions`  | none                               | `sessions` (only current helper/identity-owned launch records)                                   |
+| `POST /v1/stop`     | `{sessionId}`                      | `session` with observed `exited` status; journal retained                                        |
+
+Inbox `after` is an opaque decimal sequence cursor (`0` starts a drain), not a message ID or offset. `limit` is 1–256, default 256; unknown/repeated query keys and invalid cursors are rejected. Ack accepts at most 256 IDs per request and is idempotent; it returns asks in `retained`. Persistent duplicate IDs never increment loss counts or replace the original envelope. In persistent mode an answer returned by `ask` is also retained in inbox; ack its `reply.message.id` after consuming it.
+
+The storage API also supports opt-in durable notification intents for a local delivery worker: `Mailbox(stateDir, fingerprint, true)`, `pendingNotifications(after, limit)` and `notificationAccepted(messageId)`. Pending envelopes expose local `receivedAt` and `acknowledged` metadata. Intake and notification intent commit in one SQLite insert. Remote ack/reply hides the inbox row but preserves the notification envelope until the worker marks it accepted; notification acceptance never acknowledges unread mail. This API does not post webhooks or enable any wake service on its own.
 
 Timeout does **not** retract a delivered ask; a late answer can arrive in inbox. Offline/missing peers, broker outages, ambiguous/self targets, a second concurrent ask, invalid/revoked credentials, timeout, and resource limits have explicit errors. HTTP send/list deadlines are bounded by the real client (8/5 seconds); broker registration by 10 seconds. A lost HTTP response or acknowledgement timeout means **delivery unknown**—inspect inbox/local peer before retrying to avoid duplicate instructions.
 
@@ -230,7 +252,7 @@ Confirm the reload/revocation audit record, that Grok disappears from the local
 
 ## Verification / smoke transcript
 
-The process-boundary tests use a private real broker, real TLS certificates, actual HTTPS requests and the remote CLI. Launch tests use the actually installed Pi dependency graph with a selected-host native faux provider (no paid inference or external credentials); they prove native persistence, zero pre-startup inference, real Intercom wake/tool reply, ownership/caps, startup failure/abort/deadline, safe dialog cancellation, presence-lease independence, short-lived certificate expiry, rotation/revocation and child exit before helper shutdown completes:
+The process-boundary tests use a private real broker, real TLS certificates, actual HTTPS requests and the remote CLI. Mailbox coverage includes cold SIGKILL restart, sender reconnection, idle-lease retirement, broker-outage reads/acks, more than both former count/byte caps, bounded cursor drains, deduplication, failed storage admission, private-file enforcement and notification/ack races across process restarts. Launch tests use the actually installed Pi dependency graph with a selected-host native faux provider (no paid inference or external credentials); they prove native persistence, zero pre-startup inference, real Intercom wake/tool reply, ownership/caps, startup failure/abort/deadline, safe dialog cancellation, presence-lease independence, short-lived certificate expiry, rotation/revocation and child exit before helper shutdown completes:
 
 ```bash
 node --test test/integration/intercom-bridge.test.ts test/integration/intercom-bridge-launch.test.ts

package/package.json

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

package/scripts/intercom-bridge-credentials.mjs

@@ -22,13 +22,16 @@ function errorMessage(error) {
 }
 
 function help() {
-  console.log(`Usage: node scripts/intercom-bridge-credentials.mjs <init|issue|revoke> DIR [NAME] [--cwd PATH]
+  console.log(`Usage: node scripts/intercom-bridge-credentials.mjs <init|issue|revoke|renew-server> DIR [NAME] [--cwd PATH] [--port N] [--days N]
 
 init    Create a new private CA, loopback server certificate and grok-bot credential.
-issue   Issue a fresh 7-day client certificate; preserve local launch policy.
+issue   Issue a fresh client certificate; preserve local identity policies.
 revoke  Remove the named client from the allowlist. Does not delete saved credentials.
+renew-server  Renew the loopback server key/certificate using the same CA; preserve clients.
 
 Options: --cwd PATH  Local project identity for init/issue (default: current directory)
+         --port N    Loopback bridge port for init (default: 9443)
+         --days N    Certificate validity (1–3650; client default: 7, renew-server: 365)
          -h, --help  Show help
 Environment: OPENSSL  OpenSSL executable (default: openssl; requires -addext support)
 
@@ -38,6 +41,7 @@ Examples:
   node scripts/intercom-bridge-credentials.mjs revoke ~/.pi/intercom-bridge grok-bot
 
 After issue/revoke, send SIGHUP to the helper PID to activate the allowlist.
+After renew-server, restart only the helper; existing client credentials remain valid.
 Rotation/revocation stops that identity's helper-launched Pi children; journals remain.
 Concurrent credential commands fail rather than overwrite each other's authorization.
 After a crashed command, inspect DIR/.credentials.lock/owner and remove that lock
@@ -80,7 +84,7 @@ function key(path) {
   privatePath(path);
 }
 
-function issueCertificate(dir, stem, name, server = false) {
+function issueCertificate(dir, stem, name, { server = false, days = 7 } = {}) {
   const keyPath = join(dir, `${stem}.key`);
   const certPath = join(dir, `${stem}.crt`);
   const csrPath = join(dir, `${stem}.csr`);
@@ -105,7 +109,7 @@ function issueCertificate(dir, stem, name, server = false) {
       "-set_serial",
       `0x${randomBytes(16).toString("hex")}`,
       "-days",
-      server ? "365" : "7",
+      String(days),
       "-sha256",
       "-extfile",
       extPath,
@@ -145,23 +149,41 @@ function readConfig(path) {
 }
 
 let args;
+let port;
+let certificateDays;
 try {
   args = parseArgs({
     allowPositionals: true,
-    options: { help: { type: "boolean", short: "h" }, cwd: { type: "string" } },
+    options: {
+      help: { type: "boolean", short: "h" },
+      cwd: { type: "string" },
+      port: { type: "string" },
+      days: { type: "string" },
+    },
   });
   if (args.values.help) {
     help();
     process.exit(0);
   }
   const [action, dir, name] = args.positionals;
+  port = args.values.port === undefined ? 9443 : Number(args.values.port);
+  const defaultDays = action === "renew-server" ? 365 : 7;
+  certificateDays = args.values.days === undefined ? defaultDays : Number(args.values.days);
   if (
-    !["init", "issue", "revoke"].includes(action) ||
+    !["init", "issue", "revoke", "renew-server"].includes(action) ||
     !dir ||
     args.positionals.length > 3 ||
-    (action !== "init" && !name) ||
+    (["issue", "revoke"].includes(action) && !name) ||
+    (action === "renew-server" && (name || args.values.cwd)) ||
     (name && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) ||
-    (action === "revoke" && args.values.cwd)
+    (action === "revoke" && (args.values.cwd || args.values.days)) ||
+    (action !== "init" && args.values.port !== undefined) ||
+    !Number.isInteger(port) ||
+    port < 0 ||
+    port > 65535 ||
+    !Number.isInteger(certificateDays) ||
+    certificateDays < 1 ||
+    certificateDays > 3650
   ) {
     throw new Error("Invalid arguments; use --help.");
   }
@@ -217,9 +239,9 @@ try {
       "-out",
       join(dir, "ca.crt"),
     );
-    const server = issueCertificate(dir, "server", "localhost", true);
+    const server = issueCertificate(dir, "server", "localhost", { server: true, days: 365 });
     config = {
-      port: 9443,
+      port,
       ca: join(dir, "ca.crt"),
       cert: server.cert,
       key: server.key,
@@ -239,16 +261,36 @@ try {
     console.log(
       JSON.stringify({ revoked: name, config: configPath, next: "Send SIGHUP to the helper PID." }),
     );
+  } else if (action === "renew-server") {
+    privatePath(join(dir, "ca.key"));
+    const server = issueCertificate(dir, `server-${randomBytes(8).toString("hex")}`, "localhost", {
+      server: true,
+      days: certificateDays,
+    });
+    config.cert = server.cert;
+    config.key = server.key;
+    atomicConfig(configPath, config);
+    console.log(
+      JSON.stringify({
+        renewed: "server",
+        ...server,
+        ca: config.ca,
+        config: configPath,
+        next: "Restart only this helper; client keys and CA are unchanged.",
+      }),
+    );
   } else {
     privatePath(join(dir, "ca.key"));
-    const credential = issueCertificate(dir, `${name}-${randomBytes(8).toString("hex")}`, name);
+    const credential = issueCertificate(dir, `${name}-${randomBytes(8).toString("hex")}`, name, {
+      days: certificateDays,
+    });
     const previous = config.clients.find((client) => client.name === name);
     config.clients = config.clients.filter((client) => client.name !== name);
     config.clients.push({
+      ...previous,
       fingerprint256: credential.fingerprint256,
       name,
       cwd: resolve(args.values.cwd || previous?.cwd || process.cwd()),
-      ...(previous?.launch === undefined ? {} : { launch: previous.launch }),
     });
     atomicConfig(configPath, config);
     console.log(

package/scripts/intercom-remote.mjs

@@ -17,6 +17,8 @@ Options:
   --message TEXT       Message for send/ask/reply
   --reply-to ID        Inbound ask ID from inbox, for reply
   --timeout-ms MS      Ask timeout (100..120000, default: 120000)
+  --after CURSOR       Inbox cursor from nextCursor (default: 0)
+  --limit COUNT        Inbox page size (1..256, default: 256)
   --name NAME          Start/reuse a named idle Pi session under local policy
   --session-id ID      Stop only a Pi session launched by this identity/helper
   -h, --help           Show help
@@ -25,6 +27,7 @@ Examples:
   node intercom-remote.mjs list
   node intercom-remote.mjs ask --to planner --message 'What is the current status?'
   node intercom-remote.mjs inbox
+  node intercom-remote.mjs inbox --after NEXT_CURSOR --limit 64
   node intercom-remote.mjs reply --reply-to QUESTION_ID --message 'Proceed.'
   node intercom-remote.mjs ack MESSAGE_ID
   node intercom-remote.mjs start --name planner
@@ -36,6 +39,9 @@ No automatic retries: a lost response does not prove a message was unsent.`);
 }
 
 function allowedOptions(action) {
+  if (action === "inbox") {
+    return ["after", "limit"];
+  }
   if (action === "start") {
     return ["name"];
   }
@@ -119,7 +125,21 @@ function privateKey(path) {
   }
 }
 
-let body, action, origin, timeout;
+function inboxQuery(options) {
+  const after = options.after ?? "0";
+  const limit = options.limit ?? "256";
+  if (
+    !/^(0|[1-9]\d{0,15})$/.test(after) ||
+    !Number.isSafeInteger(Number(after)) ||
+    !/^[1-9]\d{0,2}$/.test(limit) ||
+    Number(limit) > 256
+  ) {
+    throw new Error("--after must be a nonnegative safe integer cursor; --limit must be 1..256.");
+  }
+  return new URLSearchParams({ after, limit }).toString();
+}
+
+let body, action, origin, timeout, query;
 try {
   const parsed = parseArgs({
     allowPositionals: true,
@@ -129,6 +149,8 @@ try {
       message: { type: "string" },
       "reply-to": { type: "string" },
       "timeout-ms": { type: "string" },
+      after: { type: "string" },
+      limit: { type: "string" },
       name: { type: "string" },
       "session-id": { type: "string" },
     },
@@ -167,6 +189,7 @@ try {
     throw new Error("--timeout-ms must be 100..120000.");
   }
   body = requestBody(action, options, parsed.positionals.slice(1), timeout);
+  query = action === "inbox" ? inboxQuery(options) : "";
   origin = new URL(process.env.INTERCOM_BRIDGE_URL || "https://127.0.0.1:9443");
   if (
     origin.protocol !== "https:" ||
@@ -194,6 +217,7 @@ try {
 try {
   const files = tlsFiles();
   origin.pathname = `/v1/${action}`;
+  origin.search = query;
   const payload = JSON.stringify(body);
   const get = ["list", "inbox", "sessions"].includes(action);
   const result = await new Promise((resolve, reject) => {

package/scripts/package-smoke.mjs

@@ -200,7 +200,7 @@ function installProduction(packed) {
   );
   if (
     !credentialHelp.includes(
-      "Usage: node scripts/intercom-bridge-credentials.mjs <init|issue|revoke>",
+      "Usage: node scripts/intercom-bridge-credentials.mjs <init|issue|revoke|renew-server>",
     )
   ) {
     throw new Error("installed credential CLI did not provide usage help");

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

@@ -1,27 +1,51 @@
-import {
-  constants,
-  closeSync,
-  fstatSync,
-  openSync,
-  readFileSync,
-  realpathSync,
-  statSync,
-} from "node:fs";
+import { realpathSync, statSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import { createSecureContext } from "node:tls";
+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 { readBridgeFile } from "./bridge-files.ts";
 
 const MAX_CLIENTS = 64;
 
+export interface WakePolicy {
+  readonly envFile: string;
+  readonly url: string;
+  readonly key: string;
+}
+
+function wakePolicy(value: unknown): WakePolicy | undefined {
+  if (value === undefined) {
+    return;
+  }
+  const input = object(value, ["envFile"]);
+  const envFile = label(input.envFile, "wake credential file", 4096);
+  if (!isAbsolute(envFile)) {
+    throw new Error("Wake credential file must be absolute.");
+  }
+  const env = parseEnv(readBridgeFile(envFile, true, 16384).toString("utf8"));
+  const url = new URL(label(env.GROK_WAKE_WEBHOOK_URL, "wake webhook URL", 8192));
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.hash !== "") {
+    throw new Error("Wake webhook requires HTTPS without URL credentials or a fragment.");
+  }
+  return {
+    envFile,
+    url: url.href,
+    key: label(env.GROK_WAKE_WEBHOOK_KEY, "wake webhook key", 4096),
+  };
+}
+
 export interface Identity {
   readonly fingerprint256: string;
   readonly name: string;
   readonly cwd: string;
   readonly launch?: LaunchPolicy;
+  readonly wake?: WakePolicy;
 }
 export interface Config {
+  readonly stateDir?: string;
   readonly port: number;
   readonly ca: string;
   readonly cert: string;
@@ -30,26 +54,6 @@ export interface Config {
   readonly tls: { readonly ca: Buffer; readonly cert: Buffer; readonly key: Buffer };
 }
 
-function readFile(path: string, privateFile: boolean, limit: number): Buffer {
-  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-  try {
-    const stat = fstatSync(fd);
-    if (!stat.isFile() || stat.size > limit) {
-      throw new Error("Configuration/TLS file must be a bounded regular file.");
-    }
-    if (privateFile && (stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600)) {
-      throw new Error("Config and TLS key must be owned by the current user with mode 0600.");
-    }
-    const data = readFileSync(fd);
-    if (data.length > limit) {
-      throw new Error("Configuration/TLS file exceeds its size limit.");
-    }
-    return data;
-  } finally {
-    closeSync(fd);
-  }
-}
-
 function identities(value: unknown): Map<string, Identity> {
   if (!isUnknownArray(value) || value.length > MAX_CLIENTS) {
     throw new Error(`clients must be an array of at most ${MAX_CLIENTS} identities.`);
@@ -57,7 +61,7 @@ function identities(value: unknown): Map<string, Identity> {
   const clients = new Map<string, Identity>();
   const names = new Set<string>();
   for (const raw of value) {
-    const entry = object(raw, ["fingerprint256", "name", "cwd", "launch"]);
+    const entry = object(raw, ["fingerprint256", "name", "cwd", "launch", "wake"]);
     const fingerprint256 = fingerprint(entry.fingerprint256);
     const name = label(entry.name, "name", 128).trim();
     const cwd = label(entry.cwd, "cwd", 4096);
@@ -76,6 +80,7 @@ function identities(value: unknown): Map<string, Identity> {
       name,
       cwd: launch ? realpathSync(cwd) : cwd,
       launch,
+      wake: wakePolicy(entry.wake),
     });
     names.add(name.toLowerCase());
   }
@@ -84,9 +89,9 @@ function identities(value: unknown): Map<string, Identity> {
 
 export function loadConfig(path: string): Config {
   const raw: unknown = JSON.parse(
-    new TextDecoder("utf-8", { fatal: true }).decode(readFile(path, true, BODY_LIMIT)),
+    new TextDecoder("utf-8", { fatal: true }).decode(readBridgeFile(path, true, BODY_LIMIT)),
   );
-  const input = object(raw, ["port", "ca", "cert", "key", "clients"]);
+  const input = object(raw, ["port", "ca", "cert", "key", "clients", "stateDir"]);
   const port = input.port === undefined ? 9443 : input.port;
   if (typeof port !== "number" || !Number.isInteger(port) || port < 0 || port > 65535) {
     throw new Error("Invalid HTTPS port.");
@@ -99,16 +104,21 @@ export function loadConfig(path: string): Config {
   }
   const clients = identities(input.clients);
   const tls = {
-    ca: readFile(ca, false, 1024 * 1024),
-    cert: readFile(cert, false, 1024 * 1024),
-    key: readFile(key, true, 1024 * 1024),
+    ca: readBridgeFile(ca, false, 1024 * 1024),
+    cert: readBridgeFile(cert, false, 1024 * 1024),
+    key: readBridgeFile(key, true, 1024 * 1024),
   };
   createSecureContext({ ...tls, minVersion: "TLSv1.2" });
-  return { port, ca, cert, key, clients, tls };
+  const stateDir = stateDirectory(input.stateDir);
+  if (stateDir === undefined && [...clients.values()].some((identity) => identity.wake)) {
+    throw new Error("Wake delivery requires a durable stateDir.");
+  }
+  return { port, ca, cert, key, clients, tls, stateDir };
 }
 
 export function sameListener(next: Config, current: Config): boolean {
   return (
+    next.stateDir === current.stateDir &&
     next.port === current.port &&
     next.ca === current.ca &&
     next.cert === current.cert &&

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

@@ -0,0 +1,59 @@
+import {
+  constants,
+  closeSync,
+  fstatSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export function readBridgeFile(path: string, privateFile: boolean, limit: number): Buffer {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > limit) {
+      throw new Error("Configuration/TLS file must be a bounded regular file.");
+    }
+    if (privateFile && (stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600)) {
+      throw new Error("Config and TLS key must be owned by the current user with mode 0600.");
+    }
+    const data = readFileSync(fd);
+    if (data.length > limit) {
+      throw new Error("Configuration/TLS file exceeds its size limit.");
+    }
+    return data;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function writeBridgeJson(path: string, value: object): void {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(
+    temporary,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    try {
+      writeFileSync(fd, JSON.stringify(value));
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(temporary, path);
+    const directory = openSync(dirname(path), constants.O_RDONLY | constants.O_DIRECTORY);
+    try {
+      fsyncSync(directory);
+    } finally {
+      closeSync(directory);
+    }
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}