@fitchmultz/pi-subagents 0.47.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

@@ -8,14 +8,23 @@ import { getBrokerSocketPath } from "./broker/paths.ts";
 import { loadConfig, sameListener, type Config, type Identity } from "./bridge-config.ts";
 import { ASK_TIMEOUT, Fault, fingerprint, log } from "./bridge-protocol.ts";
 import { Session } from "./bridge-session.ts";
-import { operationFor, routeFor, type Operation } from "./bridge-routes.ts";
-import { reply } from "./bridge-http.ts";
-import { Launcher, sameIdentity } from "./bridge-launch.ts";
+import { operationFor, routeFor } from "./bridge-routes.ts";
+import { reply, replyFault } from "./bridge-http.ts";
+import { sameIdentity } from "./bridge-launch.ts";
+import { BridgeOperations } from "./bridge-operations.ts";
+import { authenticatedCertificateChain } from "./native-control-auth.ts";
 import { PersistentPresence } from "./bridge-presence.ts";
 import { WakeDeliveries } from "./bridge-wake.ts";
 import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
 
 const MAX_CONNECTIONS = 128;
+const LONG_ROUTES = new Set([
+  "POST /v1/start",
+  "POST /v1/spawn",
+  "POST /v1/resume",
+  "GET /v1/transcript",
+  "POST /v1/transcript",
+]);
 
 function validCertificateDates(starts: number, expires: number): boolean {
   return (
@@ -37,7 +46,7 @@ class Bridge {
   private readonly configPath: string;
   private readonly sessions = new Map<string, Session>();
   private readonly losses = new Map<string, number>();
-  private readonly launcher = new Launcher();
+  private readonly operations: BridgeOperations;
   private readonly sockets = new Set<Socket>();
   private readonly connections = new Map<TLSSocket, Connection>();
   private readonly server: Server;
@@ -49,11 +58,13 @@ class Bridge {
   constructor(config: Config, configPath: string) {
     this.config = config;
     this.configPath = configPath;
+    this.operations = new BridgeOperations(config.stateDir);
     this.deliveries = new WakeDeliveries(config.stateDir, (identity) => this.allowed(identity));
     if (config.stateDir !== undefined) {
       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)) {
@@ -143,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,
@@ -245,12 +257,12 @@ class Bridge {
       }
       this.config = next;
       this.revokeRemoved();
-      this.launcher.revoke(next.clients).catch(() => log("launch_cleanup", { result: "failed" }));
+      this.operations.revoke(next.clients).catch(() => log("launch_cleanup", { result: "failed" }));
       log("allowlist_reloaded", { result: "accepted", clients: next.clients.size });
     } catch {
       this.config = { ...this.config, clients: new Map() };
       this.deliveries.reload();
-      this.launcher
+      this.operations
         .revoke(this.config.clients)
         .catch(() => log("launch_cleanup", { result: "failed" }));
       for (const session of this.sessions.values()) {
@@ -289,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(() => {
@@ -312,7 +327,7 @@ class Bridge {
     await Promise.all([
       ...this.handlers,
       ...sessions.map((session) => session.settled()),
-      this.launcher.shutdown(),
+      this.operations.shutdown(),
       this.presence?.stop(),
       this.deliveries.stop(),
     ]);
@@ -321,6 +336,7 @@ class Bridge {
   private admission(req: IncomingMessage): {
     readonly identity: Identity;
     readonly expires: number;
+    readonly certificate: string;
   } {
     const socket = req.socket;
     const connection = socket instanceof TLSSocket ? this.connections.get(socket) : undefined;
@@ -339,7 +355,11 @@ class Bridge {
       this.drop(connection.fingerprint, fault);
       throw fault;
     }
-    return { identity, expires: connection.expires };
+    return {
+      identity,
+      expires: connection.expires,
+      certificate: authenticatedCertificateChain(socket),
+    };
   }
   private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
     const requestId = randomUUID();
@@ -348,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 = () => {
@@ -361,7 +384,7 @@ class Bridge {
       clearTimeout(deadline);
       deadline = setTimeout(
         () =>
-          session?.close(
+          cancel(
             new Fault(
               504,
               "request_timeout",
@@ -372,23 +395,27 @@ class Bridge {
       );
     };
     try {
-      const { identity, expires } = this.admission(req);
+      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;
       req.once("aborted", abort);
       res.once("close", onClose);
       const duration = route === "POST /v1/ask" ? ASK_TIMEOUT + 15000 : 15000;
-      setDeadline(route === "POST /v1/start" ? 75000 : duration);
+      setDeadline(LONG_ROUTES.has(route) ? 75000 : duration);
       const operation = await operationFor(req, route, signal);
       if (operation.route === "POST /v1/ask") {
         setDeadline(operation.timeoutMs + 15000);
+      } else if (operation.route === "GET /v1/transcript") {
+        setDeadline(75000);
       }
-      const data = await this.execute(operation, session, {
+      const data = await this.operations.execute(operation, session, {
         signal,
         requestId,
         expires,
+        certificate,
         onPeer: (id) => {
           peer = id;
         },
@@ -402,10 +429,7 @@ class Bridge {
           ? error
           : new Fault(503, "broker_unavailable", "Local broker operation failed.");
       log("request", { ...session?.fields(), requestId, peer, result: fault.code });
-      reply(res, requestId, fault.status, {
-        ok: false,
-        error: { code: fault.code, message: fault.message, ...fault.details },
-      });
+      replyFault(res, requestId, fault);
     } finally {
       clearTimeout(deadline);
       req.off("aborted", abort);
@@ -415,38 +439,6 @@ class Bridge {
       }
     }
   }
-  private async execute(
-    operation: Operation,
-    session: Readonly<Session>,
-    context: {
-      readonly signal: AbortSignal;
-      readonly requestId: string;
-      readonly expires: number;
-      readonly onPeer: (id: string) => void;
-    },
-  ) {
-    switch (operation.route) {
-      case "POST /v1/start":
-        return this.launcher.start(operation.name, {
-          identity: session.identity,
-          expires: context.expires,
-          signal: context.signal,
-          peers: (signal) => session.connectedPeers(signal),
-        });
-      case "GET /v1/sessions":
-        return this.launcher.list(session.identity);
-      case "POST /v1/stop":
-        return this.launcher.stop(session.identity, operation.sessionId);
-      case "GET /v1/list":
-      case "GET /v1/inbox":
-      case "POST /v1/register":
-      case "POST /v1/ask":
-      case "POST /v1/send":
-      case "POST /v1/reply":
-      case "POST /v1/ack":
-        return session.execute(operation, context);
-    }
-  }
 }
 
 function main(): void {

package/src/pi-intercom/broker/client.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "events";
 import type net from "net";
 import { randomUUID } from "crypto";
+import type { NativeControlEnvelope } from "../native-control-protocol.ts";
 import { writeMessage } from "./framing.ts";
 import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
@@ -51,6 +52,7 @@ interface SendOptions {
   readonly messageId?: string;
   readonly human?: HumanMessageOrigin;
   readonly topic?: TopicUpdate;
+  readonly control?: NativeControlEnvelope;
 }
 
 function toError(error: unknown): Error {
@@ -405,6 +407,7 @@ export class IntercomClient extends EventEmitter {
       expectsReply: options.expectsReply,
       ...(options.human ? { human: options.human } : {}),
       ...(options.topic ? { topic: options.topic } : {}),
+      ...(options.control ? { control: options.control } : {}),
       delivery: messageDelivery(options),
       queueMode: options.queueMode,
       threadId: options.threadId,

package/src/pi-intercom/connection.ts

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { IntercomClient } from "./broker/client.ts";
 import type { IntercomTransport } from "./transport.ts";
@@ -8,7 +7,7 @@ import type { IntercomLifecycle } from "./lifecycle.ts";
 import type { IntercomTopics } from "./topics.ts";
 import type { Message, SessionInfo, TopicChange } from "./types.ts";
 import { asError, errorMessage } from "./validation.ts";
-import { formatTargetOptions, resolveSessionTarget } from "./session-targets.ts";
+import { formatTargetOptions, resolveSessionTarget, nativePeerId } from "./session-targets.ts";
 
 export type ConnectionReason = "startup" | "background" | "tool" | "overlay" | "peer-awareness";
 type Lifecycle = Readonly<
@@ -233,7 +232,7 @@ export class IntercomConnection {
       }
       await next.connect(
         await this.lifecycle.registration(this.hooks.pendingAsks()),
-        `pi-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`,
+        nativePeerId(sessionId),
       );
       if (!this.lifecycle.live(ctx, generation)) {
         await next.disconnect();