@fitchmultz/pi-subagents 0.48.0 → 0.49.0

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

@@ -1,174 +1,263 @@
+import { createHash } from "node:crypto";
 import { log } from "./bridge-protocol.ts";
 import { Mailbox, type PendingNotification } from "./bridge-mailbox.ts";
-import type { Identity, WakePolicy } from "./bridge-config.ts";
+import type { Identity } from "./bridge-config.ts";
+import { WakeState } from "./bridge-wake-state.ts";
 
-const POLL_MS = 15000;
-const FALLBACK_AFTER_MS = 120000;
-const MAX_BACKOFF_MS = 300000;
+interface Delivery {
+  readonly identity: Identity;
+  readonly mailbox: Mailbox;
+  readonly expires: number;
+  readonly controller: AbortController;
+}
+interface Candidate {
+  readonly delivery: Delivery;
+  readonly entry: PendingNotification;
+}
+
+function actionable(entry: PendingNotification): boolean {
+  const message = entry.message;
+  if (entry.acknowledged || message.passive === true || message.delivery === "passive") {
+    return false;
+  }
+  return (
+    message.expectsReply === true ||
+    !/^(?:ACK|DUP-ACK|FYI|NOTE|RECEIPT|NOWAKE)(?=$|[\s:])/.test(message.content.text)
+  );
+}
+
+function bucket(identity: Identity): string {
+  return createHash("sha256")
+    .update(identity.wake?.url ?? "")
+    .digest("hex");
+}
 
-export class WakeDelivery {
+/** Mailbox commits and durable retry/quota deadlines drive wakes; there is no intake scan timer. */
+export class WakeDeliveries {
+  private readonly stateDir: string | undefined;
+  private readonly state?: WakeState;
+  private readonly allowed: (identity: Identity) => boolean;
+  private readonly deliveries = new Map<string, Delivery>();
   private readonly controller = new AbortController();
   private timer?: NodeJS.Timeout;
   private running?: Promise<void>;
-  private backoff = POLL_MS;
-  private readonly name: string;
-  private readonly mailbox: Pick<Mailbox, "pendingNotifications" | "notificationAccepted">;
-  private readonly policy: WakePolicy;
-  private readonly authorized: () => boolean;
-
-  constructor(
-    name: string,
-    mailbox: Pick<Mailbox, "pendingNotifications" | "notificationAccepted">,
-    policy: WakePolicy,
-    authorized: () => boolean,
-  ) {
-    this.name = name;
-    this.mailbox = mailbox;
-    this.policy = policy;
-    this.authorized = authorized;
-  }
+  private dirty = false;
+  private storageBackoff = 15000;
 
-  start(): void {
-    if (!this.running && !this.controller.signal.aborted) {
-      this.schedule(0);
-    }
+  constructor(stateDir: string | undefined, allowed: (identity: Identity) => boolean) {
+    this.stateDir = stateDir;
+    this.allowed = allowed;
+    // Initialize before any presence proof/mailbox is created, so genuinely fresh installs start now.
+    this.state = stateDir === undefined ? undefined : new WakeState(stateDir);
   }
 
-  private schedule(delay: number): void {
-    clearTimeout(this.timer);
-    this.timer = setTimeout(() => {
-      this.running = this.deliver()
-        .catch(() => {
-          log("wake_delivery", { name: this.name, result: "storage_unavailable" });
-          this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
-        })
-        .finally(() => {
-          this.running = undefined;
-          if (!this.controller.signal.aborted) {
-            this.schedule(this.backoff);
-          }
-        });
-    }, delay);
+  session(identity: Identity, expires: number): void {
+    if (
+      !identity.wake ||
+      this.stateDir === undefined ||
+      this.deliveries.has(identity.fingerprint256)
+    ) {
+      return;
+    }
+    this.deliveries.set(identity.fingerprint256, {
+      identity,
+      expires,
+      mailbox: new Mailbox(this.stateDir, identity.fingerprint256, true),
+      controller: new AbortController(),
+    });
+    // Startup restores every certificate proof synchronously before the scheduled reconciliation.
+    // An empty first fingerprint must not clear another retained fingerprint's durable cold batch.
+    this.changed(false);
   }
 
-  private async deliver(): Promise<void> {
-    if (!this.authorized()) {
+  changed(reconcile = true): void {
+    if (this.controller.signal.aborted) {
       return;
     }
-    const entries = this.mailbox.pendingNotifications().messages;
-    for (const entry of entries) {
-      if (entry.acknowledged) {
-        // The box's durable worker owns primary wake/replay after acknowledgement.
-        this.mailbox.notificationAccepted(entry.message.id);
+    try {
+      // ACK may be followed by fresh mail before the event timer runs. Clear completed batches now
+      // so a new obligation does not inherit a completed batch's uncertainty/backoff.
+      if (reconcile) {
+        this.reconcile();
       }
+    } catch {
+      // The scheduled storage recovery fails closed; never let an event bypass durable admission.
     }
-    const next = entries.find(
-      (entry) => !entry.acknowledged && Date.now() - entry.receivedAt >= FALLBACK_AFTER_MS,
+    if (this.running) {
+      this.dirty = true;
+    } else {
+      this.schedule(Date.now());
+    }
+  }
+
+  private reconcile(): void {
+    for (const [key, candidate] of this.groups()) {
+      if (candidate) {
+        this.state?.deadline(key);
+      } else {
+        this.state?.retire(key);
+      }
+    }
+  }
+
+  private schedule(deadline: number): void {
+    clearTimeout(this.timer);
+    this.timer = setTimeout(
+      () => {
+        this.dirty = false;
+        let next = Infinity;
+        this.running = this.deliver()
+          .then((due) => {
+            next = due;
+            this.storageBackoff = 15000;
+            return;
+          })
+          .catch(() => {
+            log("wake_delivery", { result: "storage_unavailable" });
+            next = Date.now() + this.storageBackoff;
+            this.storageBackoff = Math.min(this.storageBackoff * 2, 300000);
+          })
+          .finally(() => {
+            this.running = undefined;
+            if (!this.controller.signal.aborted && (this.dirty || Number.isFinite(next))) {
+              this.schedule(this.dirty ? Date.now() : next);
+            }
+          });
+      },
+      Math.max(0, Math.min(deadline - Date.now(), 0x7fffffff)),
     );
-    if (next) {
-      // One fallback wakes the box to drain the remaining mailbox; never flood a reset VM.
-      await this.post(next);
-      return;
+  }
+
+  private authorized(delivery: Delivery): boolean {
+    return (
+      !this.controller.signal.aborted &&
+      this.allowed(delivery.identity) &&
+      delivery.expires > Date.now()
+    );
+  }
+
+  private pending(delivery: Delivery): PendingNotification | undefined {
+    let after = 0;
+    let next: PendingNotification | undefined;
+    let page;
+    do {
+      page = delivery.mailbox.pendingNotifications(after);
+      for (const entry of page.messages) {
+        if (!actionable(entry)) {
+          // Retire only notification intent. Payload/reply obligations require actual ACK/reply.
+          delivery.mailbox.notificationAccepted(entry.message.id);
+        } else if (!next) {
+          next = entry;
+        }
+      }
+      after = Number(page.nextCursor);
+    } while (page.hasMore);
+    return next;
+  }
+
+  private groups(): Map<string, Candidate | undefined> {
+    const groups = new Map<string, Candidate | undefined>();
+    for (const delivery of this.deliveries.values()) {
+      if (!this.authorized(delivery)) {
+        continue;
+      }
+      const key = bucket(delivery.identity);
+      const entry = this.pending(delivery);
+      const previous = groups.get(key);
+      if (
+        !groups.has(key) ||
+        (entry && (!previous || entry.receivedAt < previous.entry.receivedAt))
+      ) {
+        groups.set(key, entry ? { delivery, entry } : undefined);
+      }
+    }
+    return groups;
+  }
+
+  private async deliver(): Promise<number> {
+    const state = this.state;
+    let next = Infinity;
+    if (!state) {
+      return next;
+    }
+    // ACK can remove the final candidate while its failed completion write still needs recovery.
+    state.retrySettlement();
+    for (const [key, candidate] of this.groups()) {
+      if (!candidate) {
+        state.retire(key);
+        continue;
+      }
+      const due = state.deadline(key);
+      if (due > Date.now()) {
+        next = Math.min(next, due);
+        continue;
+      }
+      const deferred = state.reserve(key);
+      if (deferred !== undefined) {
+        next = Math.min(next, deferred);
+        continue;
+      }
+      // ponytail: two cold Macs can each admit one wake. Literal cross-Mac single admission
+      // requires a neutral quota authority governing every writer, not a URL hash or HTTP 2xx.
+      try {
+        // oxlint-disable-next-line no-await-in-loop
+        await this.post(candidate);
+      } finally {
+        // Expiry starts after response/error/abort, never before COMMIT or connect/TLS.
+        state.settle();
+      }
+      // Re-read ACKs and all groups after transport I/O; a snapshot must not wake already consumed mail.
+      return Date.now();
     }
-    this.backoff = POLL_MS;
+    return next;
   }
 
-  private async post(entry: PendingNotification): Promise<void> {
-    if (!this.authorized()) {
+  private async post({ delivery, entry }: Candidate): Promise<void> {
+    const policy = delivery.identity.wake;
+    if (!policy || !this.authorized(delivery)) {
       return;
     }
-    const fields = { name: this.name, messageId: entry.message.id };
+    const fields = { name: delivery.identity.name, messageId: entry.message.id };
     try {
-      const response = await fetch(this.policy.url, {
+      const response = await fetch(policy.url, {
         method: "POST",
         redirect: "error",
-        headers: {
-          Authorization: `Bearer ${this.policy.key}`,
-          "Content-Type": "application/json",
-        },
+        headers: { Authorization: `Bearer ${policy.key}`, "Content-Type": "application/json" },
         body: JSON.stringify({
           from: entry.from.name ?? entry.from.id,
           from_id: entry.from.id,
-          to: this.name,
+          to: delivery.identity.name,
           message_id: entry.message.id,
           ask_id: entry.message.expectsReply === true ? entry.message.id : null,
           text: entry.message.content.text,
         }),
-        signal: AbortSignal.any([this.controller.signal, AbortSignal.timeout(10000)]),
+        signal: AbortSignal.any([
+          this.controller.signal,
+          delivery.controller.signal,
+          AbortSignal.timeout(10000),
+        ]),
       });
       await response.body?.cancel();
-      if (response.ok && !this.controller.signal.aborted && this.authorized()) {
-        // HTTP acceptance cannot prove durable intake; the same ID remains pending until inbox ACK.
-        this.backoff = MAX_BACKOFF_MS;
-        log("wake_delivery", { ...fields, result: "accepted" });
-      } else {
-        this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
-        log("wake_delivery", { ...fields, result: "http_rejected", status: response.status });
-      }
+      // Acceptance does not consume mail or reset uncertainty: only real inbox ACK retires intent.
+      log("wake_delivery", {
+        ...fields,
+        result: response.ok ? "accepted" : "http_rejected",
+        status: response.status,
+      });
     } catch {
-      this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
       if (!this.controller.signal.aborted) {
         log("wake_delivery", { ...fields, result: "transport_unconfirmed" });
       }
     }
   }
 
-  async stop(): Promise<void> {
-    this.controller.abort();
-    clearTimeout(this.timer);
-    await this.running;
-  }
-}
-
-export class WakeDeliveries {
-  private readonly stateDir: string | undefined;
-  private readonly allowed: (identity: Identity) => boolean;
-  private readonly deliveries = new Map<
-    string,
-    { readonly identity: Identity; readonly mailbox: Mailbox; readonly worker: WakeDelivery }
-  >();
-  private readonly cleanup = new Set<Promise<unknown>>();
-
-  constructor(stateDir: string | undefined, allowed: (identity: Identity) => boolean) {
-    this.stateDir = stateDir;
-    this.allowed = allowed;
-  }
-
-  session(identity: Identity, expires: number): void {
-    if (
-      !identity.wake ||
-      this.stateDir === undefined ||
-      this.deliveries.has(identity.fingerprint256)
-    ) {
-      return;
-    }
-    const mailbox = new Mailbox(this.stateDir, identity.fingerprint256, true);
-    const worker = new WakeDelivery(
-      identity.name,
-      mailbox,
-      identity.wake,
-      () => this.allowed(identity) && expires > Date.now(),
-    );
-    this.deliveries.set(identity.fingerprint256, { identity, mailbox, worker });
-    worker.start();
-  }
-
   drop(fp: string): void {
     const delivery = this.deliveries.get(fp);
-    if (!delivery) {
-      return;
-    }
     this.deliveries.delete(fp);
-    const cleanup = delivery.worker
-      .stop()
-      .then(() => delivery.mailbox.close())
-      .catch(() => {
-        log("wake_delivery", { name: delivery.identity.name, result: "cleanup_failed" });
-      })
-      .finally(() => {
-        this.cleanup.delete(cleanup);
-      });
-    this.cleanup.add(cleanup);
+    delivery?.controller.abort();
+    delivery?.mailbox.close();
+    // Membership removal alone is not an ACK. Reload restores proof-backed replacements first.
+    this.changed(false);
   }
 
   reload(): void {
@@ -177,12 +266,17 @@ export class WakeDeliveries {
         this.drop(fp);
       }
     }
+    this.changed(false);
   }
 
   async stop(): Promise<void> {
-    for (const fp of this.deliveries.keys()) {
-      this.drop(fp);
+    this.controller.abort();
+    clearTimeout(this.timer);
+    await this.running;
+    for (const delivery of this.deliveries.values()) {
+      delivery.mailbox.close();
     }
-    await Promise.all(this.cleanup);
+    this.deliveries.clear();
+    this.state?.close();
   }
 }

package/src/pi-intercom/bridge.ts

@@ -64,6 +64,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)) {
@@ -153,6 +154,7 @@ class Bridge {
         {
           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,
@@ -299,6 +301,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();
   }
   private stop(): void {
     this.shutdown().catch(() => {
@@ -363,8 +368,11 @@ class Bridge {
     let controller: AbortController | undefined;
     let deadline: NodeJS.Timeout | undefined;
     let peer: string | undefined;
+    let readOnlyInbox = false;
+    const cancel = (fault: Readonly<Fault>) =>
+      readOnlyInbox ? controller?.abort(fault) : session?.close(fault);
     const abort = () =>
-      session?.close(
+      cancel(
         new Fault(499, "client_aborted", "HTTP client disconnected; delivery may be unknown."),
       );
     const onClose = () => {
@@ -376,7 +384,7 @@ class Bridge {
       clearTimeout(deadline);
       deadline = setTimeout(
         () =>
-          session?.close(
+          cancel(
             new Fault(
               504,
               "request_timeout",
@@ -389,6 +397,7 @@ class Bridge {
     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;