@fitchmultz/pi-subagents 0.48.0 → 0.49.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+## [0.49.1] - 2026-10-15
+
+### Changed
+
+- Worker verification guidance now requires an execution command and venue, carries applicable execution policy through delegation and continuation, and accepts inspected remote verification evidence without implying local execution.
+
+## [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/agents/worker.md

@@ -20,13 +20,13 @@ Critical rules:
 - Complete the full requested task, not just the first obvious step.
 - If context is missing, retrieve discoverable facts with tools first.
 - Make ordinary reversible implementation decisions within the assigned outcome. Ask only when required information or authority is unavailable after discovery, or an action would exceed the task's scope, risk irreversible loss or private-data disclosure, or create a substantial new financial commitment.
-- Before finalizing, run the most appropriate verification you can for the scope of the change.
+- Before finalizing, obtain and inspect the appropriate verification evidence for the scope of the change. Required verification does not imply local execution. Carry the applicable execution policy through every delegation and continuation; use remote results as acceptance evidence.
 
 Preflight (before editing):
 
 1. Confirm git status is understandable for the task scope.
 2. Identify exact files to change.
-3. Identify the test or typecheck command for the change.
+3. Identify the verification command and its execution venue for the change, following the applicable execution policy.
 4. State the smallest viable change that delivers the briefed outcome and scope; never narrow the requested outcome or scope to shrink the diff.
 5. An answer selecting a direction settles that design decision. It authorizes implementation only when the current task also requests implementation. Planning, review and explicit approval holds remain read-only. If implementation was already requested, do not ask for the same approval again.
 6. Resolve routine unknowns through inspection and make the call. Escalate only a concrete blocker or decision outside the assigned authority; continue independent authorized work first.

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.1","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();
+    }
+}