@fitchmultz/pi-subagents 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+## [0.49.0] - 2026-10-14
+
+### Added
+
+- Event-driven remote inbox waits through optional `waitMs` (0–10000 ms) and CLI `inbox --wait-ms`, preserving immediate reads by default, durable cursor paging and explicit acknowledgement.
+- Native fallback wake two seconds after mailbox commit without intake acknowledgement, with durable shared admission of at most 20 attempts per sliding hour across all identities and URLs. Pending cold batches coalesce, retain retry deadlines across crashes and rotations, and recover automatically when allowance returns.
+- Stopped-helper audit preflight for preserving known remaining wake allowance during migration; unverified legacy usage conservatively reserves the first hour.
+
+### Fixed
+
+- Cancelling an inbox read no longer disconnects the certificate-bound native identity or interrupts unrelated requests. Revocation, expiry, broker disconnect and shutdown still cancel outstanding waits.
+
 ## [0.48.0] - 2026-10-14
 
 ### Added

package/dist/extension/build-info.js

@@ -1 +1 @@
-export const EXTENSION_BUILD = Object.freeze({"version":"0.48.0","sha256":"288e6058a52baeafc2529e0a8bc267541c4dbb2e21de11af1ef89058f4809750"});
+export const EXTENSION_BUILD = Object.freeze({"version":"0.49.0","sha256":"6cd61dacb62268abb87c7005b638048a141cd17ad6091e486146bbd5e1d01338"});

package/dist/pi-intercom/bridge-config.js

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

package/dist/pi-intercom/bridge-mailbox.js

@@ -1,63 +1,11 @@
-import { closeSync, constants, fstatSync, lstatSync, openSync, realpathSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { privateDatabase } from "./bridge-storage.js";
 import { isRecord } from "../shared/unknown.js";
 import { normalizeMessage, normalizeSessionInfo } from "./types.js";
-import { Fault, INBOX_BYTES, INBOX_COUNT, fingerprint as certificateFingerprint, label, } from "./bridge-protocol.js";
-export function stateDirectory(value) {
-    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, create = false) {
-    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);
-    }
-}
+import { Fault, INBOX_BYTES, INBOX_COUNT, fingerprint as certificateFingerprint, } from "./bridge-protocol.js";
 function database(stateDir, fingerprint) {
-    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/dist/pi-intercom/bridge-presence.js

@@ -10,7 +10,10 @@ export class PersistentPresence {
     owner;
     constructor(owner) {
         this.owner = owner;
-        for (const identity of owner.clients().values()) {
+        this.restoreAll();
+    }
+    restoreAll() {
+        for (const identity of this.owner.clients().values()) {
             this.restore(identity);
         }
     }
@@ -33,6 +36,7 @@ export class PersistentPresence {
                     cwd: identity.cwd,
                     expires: value.expires,
                 });
+                this.owner.restored(identity, value.expires);
             }
         }
         catch {

package/dist/pi-intercom/bridge-routes.js

@@ -9,7 +9,7 @@ const fields = {
     "GET /v1/inbox": [],
     "POST /v1/register": [],
     "POST /v1/ack": ["ids"],
-    "POST /v1/send": ["to", "message"],
+    "POST /v1/send": ["to", "message", "passive", "messageId"],
     "POST /v1/ask": ["to", "message", "timeoutMs"],
     "POST /v1/reply": ["replyTo", "message"],
     "POST /v1/start": ["name"],
@@ -60,16 +60,23 @@ function queryFor(req, allowed) {
     return query;
 }
 function inboxQuery(req) {
-    const query = queryFor(req, ["after", "limit"]);
+    const query = queryFor(req, ["after", "limit", "waitMs"]);
     const after = query.get("after") ?? "0";
     const limit = query.get("limit") ?? String(INBOX_COUNT);
+    const waitMs = query.get("waitMs") ?? "0";
     if (!/^(0|[1-9]\d{0,15})$/.test(after) ||
         !Number.isSafeInteger(Number(after)) ||
         !/^[1-9]\d{0,2}$/.test(limit) ||
-        Number(limit) > INBOX_COUNT) {
-        throw new Fault(400, "invalid_input", "after must be a nonnegative safe integer cursor; limit must be 1..256.");
+        Number(limit) > INBOX_COUNT ||
+        !/^(0|[1-9]\d{0,3}|10000)$/.test(waitMs)) {
+        throw new Fault(400, "invalid_input", "after must be a nonnegative safe integer cursor; limit must be 1..256; waitMs must be 0..10000.");
     }
-    return { route: "GET /v1/inbox", after: Number(after), limit: Number(limit) };
+    return {
+        route: "GET /v1/inbox",
+        after: Number(after),
+        limit: Number(limit),
+        waitMs: Number(waitMs),
+    };
 }
 function pageNumber(value, fallback, min, max) {
     const number = value === null ? fallback : Number(value);
@@ -183,7 +190,7 @@ function messagingOperation(route, input, req) {
             }
             return { route, ids: [...new Set(input.ids.map((id) => label(id, "message ID")))] };
         case "POST /v1/send":
-            return { route, message: text(input.message), to: label(input.to, "to").trim() };
+            return send(input);
         case "POST /v1/ask":
             return {
                 route,
@@ -200,6 +207,18 @@ function messagingOperation(route, input, req) {
             return nativeControl(route, input);
     }
 }
+function send(input) {
+    if (input.passive !== undefined && typeof input.passive !== "boolean") {
+        throw new Fault(400, "invalid_input", "passive must be a boolean.");
+    }
+    return {
+        route: "POST /v1/send",
+        message: text(input.message),
+        to: label(input.to, "to").trim(),
+        passive: input.passive,
+        messageId: input.messageId === undefined ? undefined : label(input.messageId, "message ID"),
+    };
+}
 export async function operationFor(req, route, signal) {
     const input = await operationInput(req, route, signal);
     switch (route) {

package/dist/pi-intercom/bridge-session.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 import { IntercomClient } from "./broker/client.js";
 import { resolveSessionProjectId } from "./session-targets.js";
 import { Fault, cancelled, log, wait } from "./bridge-protocol.js";
@@ -21,6 +22,7 @@ export class Session {
     });
     requests = new Set();
     inbox;
+    inboxChanged = new AbortController();
     replying = new Set();
     pending;
     controls = new ControlReplies();
@@ -48,9 +50,7 @@ export class Session {
         this.touch();
     }
     guard(signal) {
-        if (signal) {
-            cancelled(signal);
-        }
+        signal?.throwIfAborted();
         if (this.closed) {
             throw this.closeReason;
         }
@@ -211,12 +211,22 @@ export class Session {
             this.close(new Fault(507, "mailbox_storage_failed", "Mailbox storage failed; inspect the metadata audit for unrecorded losses."));
             return;
         }
-        if (result === "lost" || (result === "duplicate" && !this.inbox.persistent)) {
-            this.owner.lost(this.identity.fingerprint256);
+        if (result !== "duplicate" || !this.inbox.persistent) {
+            if (result !== "stored") {
+                this.owner.lost(this.identity.fingerprint256);
+            }
+            this.inboxChanged.abort();
+            this.inboxChanged = new AbortController();
         }
-        this.recordReceive(from.id, message.id, result);
+        log(result === "lost" ? "inbox_overflow" : "received", {
+            ...this.fields(),
+            peer: from.id,
+            messageId: message.id,
+            result: result === "lost" && this.inbox.persistent ? "storage_failed" : result,
+        });
         if (result !== "lost") {
             this.resolveReply(from, message);
+            this.owner.mailboxChanged?.();
         }
         this.presence();
     }
@@ -228,14 +238,6 @@ export class Session {
         pending.resolve({ from, message });
         return true;
     }
-    recordReceive(peer, messageId, result) {
-        log(result === "lost" ? "inbox_overflow" : "received", {
-            ...this.fields(),
-            peer,
-            messageId,
-            result: result === "lost" && this.inbox.persistent ? "storage_failed" : result,
-        });
-    }
     presence() {
         if (this.closed) {
             return;
@@ -311,17 +313,6 @@ export class Session {
         const waiting = new WaitingAsk();
         this.pending = waiting;
         const { signal } = context;
-        const abort = () => {
-            try {
-                cancelled(signal);
-            }
-            catch (error) {
-                waiting.reject(error instanceof Error
-                    ? error
-                    : new Fault(499, "client_aborted", "HTTP client disconnected; delivery may be unknown."));
-            }
-        };
-        signal.addEventListener("abort", abort, { once: true });
         try {
             await this.connect(signal);
             const peer = await this.target(operation.to, signal);
@@ -338,16 +329,37 @@ export class Session {
         }
         finally {
             waiting.clear();
-            signal.removeEventListener("abort", abort);
-            if (this.pending === waiting) {
-                this.pending = undefined;
-            }
+            this.pending = undefined;
         }
     }
-    ack(ids) {
-        const result = this.inbox.ack(ids);
-        this.presence();
-        return result;
+    async readInbox(operation, context) {
+        const read = () => ({
+            ...this.inbox.page(operation.after, operation.limit),
+            ...this.inbox.status(this.owner.losses(this.identity.fingerprint256)),
+        });
+        const deadline = performance.now() + operation.waitMs;
+        const losses = read().lostMessages;
+        for (;;) {
+            // Subscribe to the post-commit signal before rereading the authoritative cursor page.
+            const signal = AbortSignal.any([this.inboxChanged.signal, context.signal]);
+            const page = read();
+            const remaining = deadline - performance.now();
+            if (page.messages.length > 0 || page.lostMessages !== losses || remaining <= 0) {
+                return page;
+            }
+            log("inbox_wait", { ...this.fields(), requestId: context.requestId, after: operation.after });
+            try {
+                // A nonmatching commit must rearm the same cursor, not start parallel readers.
+                // oxlint-disable-next-line no-await-in-loop
+                await delay(remaining, undefined, { signal });
+            }
+            catch (error) {
+                if (!signal.aborted) {
+                    throw error;
+                }
+            }
+            this.guard(context.signal);
+        }
     }
     async answer(replyTo, message, context) {
         const entry = this.inbox.get(replyTo);
@@ -371,6 +383,7 @@ export class Session {
             }
             const data = { ...(await this.send(peer, message, context, { replyTo })) };
             this.inbox.remove(replyTo);
+            this.owner.mailboxChanged?.();
             this.presence();
             return data;
         }
@@ -389,28 +402,30 @@ export class Session {
                 await this.connect(context.signal);
             }
             if (operation.route === "POST /v1/ack") {
-                return this.ack(operation.ids);
+                const result = this.inbox.ack(operation.ids);
+                this.owner.mailboxChanged?.();
+                this.presence();
+                return result;
             }
-            return {
-                ...this.inbox.page(operation.after, operation.limit),
-                ...this.inbox.status(this.owner.losses(this.identity.fingerprint256)),
-            };
+            return this.readInbox(operation, context);
         }
         await this.connect(context.signal);
         switch (operation.route) {
             case "POST /v1/register":
                 return { sessionId: this.client.sessionId, name: this.identity.name };
-            case "GET /v1/list": {
-                const sessions = await this.peers(context.signal);
+            case "GET /v1/list":
                 return {
                     sessionId: this.client.sessionId,
-                    sessions: bridgeSessionList(sessions),
+                    sessions: bridgeSessionList(await this.peers(context.signal)),
                 };
+            case "POST /v1/send": {
+                const peer = await this.target(operation.to, context.signal);
+                const receipt = await this.send(peer.id, operation.message, context, {
+                    messageId: operation.messageId,
+                    delivery: operation.passive === true ? "passive" : "steer",
+                });
+                return { ...receipt };
             }
-            case "POST /v1/send":
-                return {
-                    ...(await this.send((await this.target(operation.to, context.signal)).id, operation.message, context)),
-                };
             case "POST /v1/reply":
                 return this.answer(operation.replyTo, operation.message, context);
         }

package/dist/pi-intercom/bridge-storage.js

@@ -0,0 +1,73 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, realpathSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { isRecord } from "../shared/unknown.js";
+import { label } from "./bridge-protocol.js";
+export function stateDirectory(value) {
+    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);
+}
+export function privateFile(path) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() ||
+            stat.uid !== process.getuid?.() ||
+            (stat.mode & 0o777) !== 0o600 ||
+            stat.nlink !== 1) {
+            throw new Error("Storage files must be owned regular files with mode 0600 and one link.");
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Native SQLite FULL commits own durability; never replace an unreadable existing database. */
+export function privateDatabase(stateDir, name) {
+    stateDirectory(stateDir);
+    const path = join(stateDir, name);
+    let created = false;
+    try {
+        const fd = openSync(path, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        closeSync(fd);
+        created = true;
+    }
+    catch (error) {
+        if (!isRecord(error) || error.code !== "EEXIST") {
+            throw error;
+        }
+    }
+    privateFile(path);
+    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 });
+    try {
+        db.exec(`PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; PRAGMA secure_delete=ON;
+      PRAGMA cache_size=-1024; PRAGMA busy_timeout=1000;`);
+        return { db, created };
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}

package/dist/pi-intercom/bridge-wake-owner.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { privateDatabase, privateFile } from "./bridge-storage.js";
+import { isRecord } from "../shared/unknown.js";
+export const WAKE_OWNER_FILE = /^wake-owner-[0-9a-f-]{36}\.lock$/;
+/** SQLite's OS lock survives pauses and is released on exit, without PID reuse or stale leases. */
+export class WakeOwner {
+    name = `wake-owner-${randomUUID()}.lock`;
+    db;
+    path;
+    constructor(stateDir) {
+        this.path = join(stateDir, this.name);
+        this.db = privateDatabase(stateDir, this.name).db;
+        try {
+            this.db.exec("BEGIN EXCLUSIVE");
+        }
+        catch (error) {
+            this.db.close();
+            throw error;
+        }
+    }
+    close() {
+        this.db.close();
+        rmSync(this.path, { force: true });
+    }
+}
+export function stoppedWakeOwner(stateDir, name) {
+    if (!WAKE_OWNER_FILE.test(name)) {
+        throw new Error("Invalid wake owner.");
+    }
+    const path = join(stateDir, name);
+    try {
+        privateFile(path);
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT") {
+            return true;
+        }
+        throw error;
+    }
+    const db = new DatabaseSync(path);
+    try {
+        db.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE");
+        return true;
+    }
+    catch (error) {
+        if (isRecord(error) && error.errcode === 5) {
+            return false;
+        }
+        throw error;
+    }
+    finally {
+        db.close();
+    }
+}