@fitchmultz/pi-subagents 0.52.19 → 0.52.20

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## 0.52.20 - 2026-11-07
+
+<!-- npm-release:unreleased:start -->
+<!-- npm-release:unreleased:end -->
+
+- refactor: centralize request settlement and snapshot phases (#354) ([335c7e2](https://github.com/fitchmultz/pi-subagents/commit/335c7e269936467672f7e8d70cc67bf875a0a1c6))
+
+### What's Changed
+
+- refactor: centralize broker request settlement by @fitchmultz in https://github.com/fitchmultz/pi-subagents/pull/354
+- refactor: make bridge scheduler ownership explicit by @fitchmultz in https://github.com/fitchmultz/pi-subagents/pull/355
+
+**Full Changelog**: https://github.com/fitchmultz/pi-subagents/compare/v0.52.19...v0.52.20
+
 ## 0.52.19 - 2026-11-07
 
 <!-- npm-release:unreleased:start -->
@@ -12,8 +26,10 @@
 - Bind parent attachment to explicit detached, waiting, attaching and attached phases; managed readiness attaches only its own still-current waiting binding and shutdown joins admitted publication before releasing the matching generation.
 - Add optional `delegate.thinking` to select child effort independently of the parent on all supported hosts, including official Pi 1.5.0. Omission keeps inherited effort. Native model suffixes must agree with an explicit field. Pi still clamps effort to model capabilities; guidance and saved continuations retain the child's saved effort.
 - Represent child accounting as unrecorded, verified, pending or unavailable while keeping execution status and saved result formats unchanged.
+- Give bridge wake and presence schedulers explicit timer, running, and stopped ownership while retaining durable wake policy.
 - Make directory-watch availability and the coalesced wake's single-owner contract explicit without changing polling fallback.
 - Preserve stranded last-good builds until a complete replacement publishes, and report retained recovery paths when a later build fails.
+- Centralize broker request settlement and close multipart snapshot readers after completion or failure.
 - Give prepared topic transactions action-specific payloads while preserving validate-before-commit and stale-restore normalization.
 
 <!-- npm-release:unreleased:end -->

package/dist/build-info.js

@@ -1 +1 @@
-export const EXTENSION_BUILD = Object.freeze({"version":"0.52.19","sha256":"a5cb823f7d9194659bb3c3e53c68e90032ef520a962758d896dccee78a3bd2c5"});
+export const EXTENSION_BUILD = Object.freeze({"version":"0.52.20","sha256":"6698668f485ef551faf914031fee7ad7165c9062a38c31b2827077d8e93e94b9"});

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

@@ -4,9 +4,7 @@ import { readBridgeFile, writeBridgeJson } from "./bridge-files.js";
 import { log } from "./bridge-protocol.js";
 export class PersistentPresence {
     registrations = new Map();
-    stopped = false;
-    timer;
-    running;
+    phase = { kind: "idle" };
     owner;
     constructor(owner) {
         this.owner = owner;
@@ -61,21 +59,28 @@ export class PersistentPresence {
         this.start();
     }
     start() {
-        if (!this.stopped && !this.running) {
-            clearTimeout(this.timer);
-            this.timer = setTimeout(() => {
-                this.running = this.maintain().finally(() => {
-                    this.running = undefined;
-                    if (!this.stopped) {
-                        this.timer = setTimeout(() => this.start(), 15000);
-                    }
-                });
-            }, 0);
+        if (this.phase.kind === "running" || this.phase.kind === "stopped") {
+            return;
+        }
+        this.schedule(0);
+    }
+    schedule(delay) {
+        if (this.phase.kind === "scheduled") {
+            clearTimeout(this.phase.timer);
         }
+        const timer = setTimeout(() => {
+            const task = this.maintain().finally(() => {
+                if (this.phase.kind !== "stopped") {
+                    this.schedule(15000);
+                }
+            });
+            this.phase = { kind: "running", task };
+        }, delay);
+        this.phase = { kind: "scheduled", timer };
     }
     async maintain() {
         for (const registration of this.registrations.values()) {
-            if (this.stopped) {
+            if (this.phase.kind === "stopped") {
                 return;
             }
             const identity = this.owner.clients().get(registration.fingerprint);
@@ -95,9 +100,16 @@ export class PersistentPresence {
             }
         }
     }
-    async stop() {
-        this.stopped = true;
-        clearTimeout(this.timer);
-        await this.running;
+    stop() {
+        const phase = this.phase;
+        if (phase.kind === "stopped") {
+            return phase.task;
+        }
+        if (phase.kind === "scheduled") {
+            clearTimeout(phase.timer);
+        }
+        const task = phase.kind === "running" ? phase.task : Promise.resolve();
+        this.phase = { kind: "stopped", task };
+        return task;
     }
 }

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

@@ -22,9 +22,7 @@ export class WakeDeliveries {
     allowed;
     deliveries = new Map();
     controller = new AbortController();
-    timer;
-    running;
-    dirty = false;
+    phase = { kind: "idle" };
     storageBackoff = 15000;
     constructor(stateDir, allowed) {
         this.stateDir = stateDir;
@@ -62,11 +60,17 @@ export class WakeDeliveries {
         catch {
             // The scheduled storage recovery fails closed; never let an event bypass durable admission.
         }
-        if (this.running) {
-            this.dirty = true;
-        }
-        else {
-            this.schedule(Date.now());
+        const phase = this.phase;
+        switch (phase.kind) {
+            case "running":
+                this.phase = { kind: "running-dirty", task: phase.task };
+                return;
+            case "running-dirty":
+            case "stopped":
+                return;
+            case "idle":
+            case "scheduled":
+                this.schedule(Date.now());
         }
     }
     reconcile() {
@@ -80,28 +84,36 @@ export class WakeDeliveries {
         }
     }
     schedule(deadline) {
-        clearTimeout(this.timer);
-        this.timer = setTimeout(() => {
-            this.dirty = false;
-            let next = Infinity;
-            this.running = this.deliver()
-                .then((due) => {
-                next = due;
-                this.storageBackoff = 15000;
+        if (this.phase.kind === "scheduled") {
+            clearTimeout(this.phase.timer);
+        }
+        const timer = setTimeout(() => this.startDelivery(), Math.max(0, Math.min(deadline - Date.now(), 0x7fffffff)));
+        this.phase = { kind: "scheduled", timer };
+    }
+    startDelivery() {
+        let next = Infinity;
+        const task = 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(() => {
+            if (this.phase.kind === "stopped") {
                 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)));
+            }
+            const dirty = this.phase.kind === "running-dirty";
+            this.phase = { kind: "idle" };
+            if (dirty || Number.isFinite(next)) {
+                this.schedule(dirty ? Date.now() : next);
+            }
+        });
+        this.phase = { kind: "running", task };
     }
     authorized(delivery) {
         return (!this.controller.signal.aborted &&
@@ -233,14 +245,25 @@ export class WakeDeliveries {
         }
         this.changed(false);
     }
-    async stop() {
-        this.controller.abort();
-        clearTimeout(this.timer);
-        await this.running;
-        for (const delivery of this.deliveries.values()) {
-            delivery.mailbox.close();
+    stop() {
+        const phase = this.phase;
+        if (phase.kind === "stopped") {
+            return phase.task;
+        }
+        if (phase.kind === "scheduled") {
+            clearTimeout(phase.timer);
         }
-        this.deliveries.clear();
-        this.state?.close();
+        const running = phase.kind === "running" || phase.kind === "running-dirty" ? phase.task : undefined;
+        const task = Promise.resolve(running).then(() => {
+            for (const delivery of this.deliveries.values()) {
+                delivery.mailbox.close();
+            }
+            this.deliveries.clear();
+            this.state?.close();
+            return;
+        });
+        this.phase = { kind: "stopped", task };
+        this.controller.abort();
+        return task;
     }
 }

package/dist/pi-intercom/broker/client-last.js

@@ -3,6 +3,7 @@ import { errorMessage } from "../../shared/unknown.js";
 import { isNativeReadQuery, isNativeReadResult, isLastMessageResult, isReceiptResult, } from "./last.js";
 import { normalizeSessionInfo, } from "../types.js";
 import { writeMessage } from "./framing.js";
+import { PendingRequests } from "./pending-requests.js";
 /** A peer's read of this session or, for a main, of its exited `parked` child. */
 export function lastRequest(msg) {
     const from = normalizeSessionInfo(msg.from);
@@ -24,26 +25,20 @@ export class LastMessageRequests {
     constructor(timeoutMs) {
         this.timeoutMs = timeoutMs;
     }
-    pending = new Map();
+    pending = new PendingRequests();
     fail(error) {
         this.lastMessages = false;
         this.receiptReads = false;
-        for (const pending of this.pending.values()) {
-            clearTimeout(pending.timer);
-            pending.reject(error);
-        }
-        this.pending.clear();
+        this.pending.fail(error);
     }
     receive(message) {
         if (typeof message.requestId !== "string" || !isNativeReadResult(message.result)) {
             throw new Error("Invalid last-message response");
         }
-        const pending = this.pending.get(message.requestId);
+        const pending = this.pending.take(message.requestId);
         if (!pending) {
             return;
         }
-        clearTimeout(pending.timer);
-        this.pending.delete(message.requestId);
         pending.resolve(message.result);
     }
     async last(socket, to, query) {
@@ -66,19 +61,12 @@ export class LastMessageRequests {
         }
         return new Promise((resolve, reject) => {
             const requestId = randomUUID();
-            const timer = setTimeout(() => {
-                this.pending.delete(requestId);
-                reject(new Error("Last-message read timeout"));
-            }, this.timeoutMs);
-            timer.unref();
-            this.pending.set(requestId, { resolve, reject, timer });
+            this.pending.set(requestId, { resolve, reject }, this.timeoutMs, () => new Error("Last-message read timeout"));
             try {
                 writeMessage(socket, { type: "last_request", requestId, to, query });
             }
             catch (error) {
-                clearTimeout(timer);
-                this.pending.delete(requestId);
-                reject(new Error(errorMessage(error)));
+                this.pending.take(requestId)?.reject(new Error(errorMessage(error)));
             }
         });
     }

package/dist/pi-intercom/broker/client.js

@@ -3,6 +3,7 @@ import { randomUUID } from "crypto";
 import { writeMessage } from "./framing.js";
 import { BrokerConnection, connectBrokerSocket } from "./connection.js";
 import { SnapshotReader } from "./snapshot-reader.js";
+import { PendingRequests } from "./pending-requests.js";
 import { LastMessageRequests, lastRequest } from "./client-last.js";
 import { ParkRequests } from "./client-park.js";
 import { WakeMessages } from "./client-wake.js";
@@ -36,8 +37,8 @@ export class IntercomClient extends EventEmitter {
     wakes = new WakeMessages(this, () => this.requireActiveSocket());
     guardedDeliverySupported = false;
     lastRequests;
-    pendingSends = new Map();
-    pendingLists = new Map();
+    pendingSends = new PendingRequests();
+    pendingLists = new PendingRequests();
     connecting = false;
     disconnecting = false;
     sendTimeoutMs;
@@ -50,14 +51,8 @@ export class IntercomClient extends EventEmitter {
     }
     failPending(error) {
         this.lastRequests.fail(error);
-        for (const pending of this.pendingSends.values()) {
-            pending.reject(error);
-        }
-        this.pendingSends.clear();
-        for (const pending of this.pendingLists.values()) {
-            pending.reject(error);
-        }
-        this.pendingLists.clear();
+        this.pendingSends.fail(error);
+        this.pendingLists.fail(error);
     }
     get sessionId() {
         return this._sessionId;
@@ -240,12 +235,11 @@ export class IntercomClient extends EventEmitter {
         if (type !== "delivered" && typeof reason !== "string") {
             throw new Error(`Invalid ${errorMessage(type)} message`);
         }
-        const pending = this.pendingSends.get(messageId);
+        const pending = this.pendingSends.take(messageId);
         // Late responses are harmless after the caller has timed out.
         if (!pending) {
             return;
         }
-        this.pendingSends.delete(messageId);
         pending.resolve({
             id: messageId,
             accepted: type !== "delivery_failed",
@@ -266,14 +260,12 @@ export class IntercomClient extends EventEmitter {
             return;
         }
         if (typeof error === "string") {
-            this.pendingLists.delete(requestId);
-            pending.reject(new Error(error));
+            this.pendingLists.take(requestId)?.reject(new Error(error));
             return;
         }
         pending.reader.append(sessions, receipts);
         if (more !== true) {
-            this.pendingLists.delete(requestId);
-            pending.resolve(pending.reader.finish());
+            this.pendingLists.take(requestId)?.resolve(pending.reader.finish());
         }
     }
     park(on = true) {
@@ -319,8 +311,8 @@ export class IntercomClient extends EventEmitter {
         }
         return new Promise((resolve, reject) => {
             const requestId = randomUUID();
+            const reader = new SnapshotReader();
             const wrappedResolve = (snapshot) => {
-                clearTimeout(timeout);
                 try {
                     // Commit confirmed subscriptions before handling a following message in the same read.
                     onAccepted?.(snapshot);
@@ -331,21 +323,14 @@ export class IntercomClient extends EventEmitter {
                 }
             };
             const wrappedReject = (error) => {
-                clearTimeout(timeout);
+                reader.fail();
                 reject(error);
             };
-            const timeout = setTimeout(() => {
-                if (this.pendingLists.has(requestId)) {
-                    this.pendingLists.delete(requestId);
-                    wrappedReject(Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }));
-                }
-            }, this.listTimeoutMs);
-            timeout.unref();
             this.pendingLists.set(requestId, {
                 resolve: wrappedResolve,
                 reject: wrappedReject,
-                reader: new SnapshotReader(),
-            });
+                reader,
+            }, this.listTimeoutMs, () => Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }));
             try {
                 writeMessage(socket, {
                     type: "list",
@@ -355,9 +340,7 @@ export class IntercomClient extends EventEmitter {
                 });
             }
             catch (error) {
-                clearTimeout(timeout);
-                this.pendingLists.delete(requestId);
-                reject(toError(error));
+                this.pendingLists.take(requestId)?.reject(toError(error));
             }
         });
     }
@@ -377,7 +360,7 @@ export class IntercomClient extends EventEmitter {
             return Promise.reject(toError(error));
         }
         const messageId = options.messageId ?? (options.guard ? "" : randomUUID());
-        if (this.pendingSends.has(messageId)) {
+        if (this.pendingSends.get(messageId)) {
             return Promise.reject(new Error("Message ID already has a pending send"));
         }
         const message = {
@@ -402,22 +385,7 @@ export class IntercomClient extends EventEmitter {
             return Promise.reject(new Error("Invalid message format"));
         }
         return new Promise((resolve, reject) => {
-            const wrappedResolve = (result) => {
-                clearTimeout(timeout);
-                resolve(result);
-            };
-            const wrappedReject = (error) => {
-                clearTimeout(timeout);
-                reject(error);
-            };
-            const timeout = setTimeout(() => {
-                if (this.pendingSends.has(messageId)) {
-                    this.pendingSends.delete(messageId);
-                    wrappedReject(new Error("Send timeout"));
-                }
-            }, this.sendTimeoutMs);
-            timeout.unref();
-            this.pendingSends.set(messageId, { resolve: wrappedResolve, reject: wrappedReject });
+            this.pendingSends.set(messageId, { resolve, reject }, this.sendTimeoutMs, () => new Error("Send timeout"));
             try {
                 writeMessage(socket, {
                     type: "send",
@@ -426,9 +394,7 @@ export class IntercomClient extends EventEmitter {
                 });
             }
             catch (error) {
-                clearTimeout(timeout);
-                this.pendingSends.delete(messageId);
-                reject(toError(error));
+                this.pendingSends.take(messageId)?.reject(toError(error));
             }
         });
     }

package/dist/pi-intercom/broker/pending-requests.d.ts

@@ -0,0 +1,12 @@
+interface Request {
+    readonly reject: (error: Readonly<Error>) => void;
+}
+/** Map membership owns settlement; taking a request also releases its deadline. */
+export declare class PendingRequests<T extends Request> {
+    private readonly pending;
+    get(id: string): T | undefined;
+    set(id: string, value: T, timeoutMs: number, timeoutError: () => Error): void;
+    take(id: string): T | undefined;
+    fail(error: Readonly<Error>): void;
+}
+export {};

package/dist/pi-intercom/broker/pending-requests.js

@@ -0,0 +1,26 @@
+/** Map membership owns settlement; taking a request also releases its deadline. */
+export class PendingRequests {
+    pending = new Map();
+    get(id) {
+        return this.pending.get(id)?.value;
+    }
+    set(id, value, timeoutMs, timeoutError) {
+        const timer = setTimeout(() => this.take(id)?.reject(timeoutError()), timeoutMs);
+        timer.unref();
+        this.pending.set(id, { value, timer });
+    }
+    take(id) {
+        const pending = this.pending.get(id);
+        if (pending === undefined) {
+            return;
+        }
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        return pending.value;
+    }
+    fail(error) {
+        for (const id of this.pending.keys()) {
+            this.take(id)?.reject(error);
+        }
+    }
+}

package/dist/pi-intercom/broker/snapshot-reader.d.ts

@@ -1,8 +1,9 @@
 import { type SessionSnapshot } from "../types.ts";
 /** Multipart frames build a private cache; only a complete validated snapshot escapes. */
 export declare class SnapshotReader {
-    private readonly sessions;
-    private readonly receipts;
+    private phase;
+    private open;
+    fail(): void;
     private addSession;
     append(sessions: readonly unknown[], receipts: unknown): void;
     finish(): SessionSnapshot;

package/dist/pi-intercom/broker/snapshot-reader.js

@@ -48,15 +48,25 @@ function appendRows(previous, rows, supplied) {
 }
 /** Multipart frames build a private cache; only a complete validated snapshot escapes. */
 export class SnapshotReader {
-    sessions = new Map();
-    receipts = [];
-    addSession(row) {
+    phase = { kind: "open", sessions: new Map(), receipts: [] };
+    open() {
+        if (this.phase.kind !== "open") {
+            throw new Error(`Session snapshot is ${this.phase.kind}`);
+        }
+        return this.phase;
+    }
+    fail() {
+        if (this.phase.kind === "open") {
+            this.phase = { kind: "failed" };
+        }
+    }
+    addSession(state, row) {
         if (!isRecord(row) || typeof row.id !== "string") {
             throw new Error("Invalid session snapshot row");
         }
         const topics = optionalArray(row.topics);
         const subscriptions = optionalArray(row.subscriptions);
-        const previous = this.sessions.get(row.id);
+        const previous = state.sessions.get(row.id);
         const info = normalizeSessionInfo({
             ...previous?.info,
             ...row,
@@ -67,33 +77,42 @@ export class SnapshotReader {
             throw new Error("Invalid session snapshot");
         }
         const { topics: newTopics, subscriptions: newSubscriptions, ...identity } = info;
-        this.sessions.set(info.id, {
+        state.sessions.set(info.id, {
             info: identity,
             topics: appendRows(previous?.topics, newTopics, "topics" in row),
             subscriptions: appendRows(previous?.subscriptions, newSubscriptions, "subscriptions" in row),
         });
     }
     append(sessions, receipts) {
-        for (const row of sessions) {
-            this.addSession(row);
-        }
-        if (receipts === undefined) {
-            return;
+        const state = this.open();
+        try {
+            for (const row of sessions) {
+                this.addSession(state, row);
+            }
+            if (receipts === undefined) {
+                return;
+            }
+            if (!isUnknownArray(receipts)) {
+                throw new Error("Invalid topic delivery receipts");
+            }
+            state.receipts.push(...receipts.map(receipt));
         }
-        if (!isUnknownArray(receipts)) {
-            throw new Error("Invalid topic delivery receipts");
+        catch (error) {
+            this.fail();
+            throw error;
         }
-        this.receipts.push(...receipts.map(receipt));
     }
     finish() {
+        const state = this.open();
         const sessions = [];
-        for (const { info, topics, subscriptions } of this.sessions.values()) {
+        for (const { info, topics, subscriptions } of state.sessions.values()) {
             sessions.push({
                 ...info,
                 ...(topics !== undefined ? { topics } : {}),
                 ...(subscriptions !== undefined ? { subscriptions } : {}),
             });
         }
-        return { sessions, receipts: this.receipts };
+        this.phase = { kind: "finished" };
+        return { sessions, receipts: state.receipts };
     }
 }

package/package.json

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

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

@@ -18,11 +18,15 @@ interface PresenceOwner {
   readonly restored: (identity: Identity, expires: number) => void;
 }
 
+type PresencePhase =
+  | { readonly kind: "idle" }
+  | { readonly kind: "scheduled"; readonly timer: NodeJS.Timeout }
+  | { readonly kind: "running"; readonly task: Promise<void> }
+  | { readonly kind: "stopped"; readonly task: Promise<void> };
+
 export class PersistentPresence {
   private readonly registrations = new Map<string, Registration>();
-  private stopped = false;
-  private timer?: NodeJS.Timeout;
-  private running?: Promise<void> | undefined;
+  private phase: PresencePhase = { kind: "idle" };
   private readonly owner: PresenceOwner;
 
   constructor(owner: PresenceOwner) {
@@ -88,22 +92,30 @@ export class PersistentPresence {
   }
 
   start(): void {
-    if (!this.stopped && !this.running) {
-      clearTimeout(this.timer);
-      this.timer = setTimeout(() => {
-        this.running = this.maintain().finally(() => {
-          this.running = undefined;
-          if (!this.stopped) {
-            this.timer = setTimeout(() => this.start(), 15000);
-          }
-        });
-      }, 0);
+    if (this.phase.kind === "running" || this.phase.kind === "stopped") {
+      return;
+    }
+    this.schedule(0);
+  }
+
+  private schedule(delay: number): void {
+    if (this.phase.kind === "scheduled") {
+      clearTimeout(this.phase.timer);
     }
+    const timer = setTimeout(() => {
+      const task = this.maintain().finally(() => {
+        if (this.phase.kind !== "stopped") {
+          this.schedule(15000);
+        }
+      });
+      this.phase = { kind: "running", task };
+    }, delay);
+    this.phase = { kind: "scheduled", timer };
   }
 
   private async maintain(): Promise<void> {
     for (const registration of this.registrations.values()) {
-      if (this.stopped) {
+      if (this.phase.kind === "stopped") {
         return;
       }
       const identity = this.owner.clients().get(registration.fingerprint);
@@ -125,9 +137,16 @@ export class PersistentPresence {
     }
   }
 
-  async stop(): Promise<void> {
-    this.stopped = true;
-    clearTimeout(this.timer);
-    await this.running;
+  stop(): Promise<void> {
+    const phase = this.phase;
+    if (phase.kind === "stopped") {
+      return phase.task;
+    }
+    if (phase.kind === "scheduled") {
+      clearTimeout(phase.timer);
+    }
+    const task = phase.kind === "running" ? phase.task : Promise.resolve();
+    this.phase = { kind: "stopped", task };
+    return task;
   }
 }

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

@@ -15,6 +15,12 @@ interface Candidate {
   readonly entry: PendingNotification;
 }
 
+type DeliveryPhase =
+  | { readonly kind: "idle" }
+  | { readonly kind: "scheduled"; readonly timer: NodeJS.Timeout }
+  | { readonly kind: "running" | "running-dirty"; readonly task: Promise<void> }
+  | { readonly kind: "stopped"; readonly task: Promise<void> };
+
 function actionable(entry: PendingNotification): boolean {
   const message = entry.message;
   if (entry.acknowledged || message.passive === true || message.delivery === "passive") {
@@ -39,9 +45,7 @@ export class WakeDeliveries {
   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> | undefined;
-  private dirty = false;
+  private phase: DeliveryPhase = { kind: "idle" };
   private storageBackoff = 15000;
 
   constructor(stateDir: string | undefined, allowed: (identity: Identity) => boolean) {
@@ -83,10 +87,17 @@ export class WakeDeliveries {
     } catch {
       // The scheduled storage recovery fails closed; never let an event bypass durable admission.
     }
-    if (this.running) {
-      this.dirty = true;
-    } else {
-      this.schedule(Date.now());
+    const phase = this.phase;
+    switch (phase.kind) {
+      case "running":
+        this.phase = { kind: "running-dirty", task: phase.task };
+        return;
+      case "running-dirty":
+      case "stopped":
+        return;
+      case "idle":
+      case "scheduled":
+        this.schedule(Date.now());
     }
   }
 
@@ -101,31 +112,40 @@ export class WakeDeliveries {
   }
 
   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);
-            }
-          });
-      },
+    if (this.phase.kind === "scheduled") {
+      clearTimeout(this.phase.timer);
+    }
+    const timer = setTimeout(
+      () => this.startDelivery(),
       Math.max(0, Math.min(deadline - Date.now(), 0x7fffffff)),
     );
+    this.phase = { kind: "scheduled", timer };
+  }
+
+  private startDelivery(): void {
+    let next = Infinity;
+    const task = 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(() => {
+        if (this.phase.kind === "stopped") {
+          return;
+        }
+        const dirty = this.phase.kind === "running-dirty";
+        this.phase = { kind: "idle" };
+        if (dirty || Number.isFinite(next)) {
+          this.schedule(dirty ? Date.now() : next);
+        }
+      });
+    this.phase = { kind: "running", task };
   }
 
   private authorized(delivery: Delivery): boolean {
@@ -267,14 +287,26 @@ export class WakeDeliveries {
     this.changed(false);
   }
 
-  async stop(): Promise<void> {
-    this.controller.abort();
-    clearTimeout(this.timer);
-    await this.running;
-    for (const delivery of this.deliveries.values()) {
-      delivery.mailbox.close();
+  stop(): Promise<void> {
+    const phase = this.phase;
+    if (phase.kind === "stopped") {
+      return phase.task;
     }
-    this.deliveries.clear();
-    this.state?.close();
+    if (phase.kind === "scheduled") {
+      clearTimeout(phase.timer);
+    }
+    const running =
+      phase.kind === "running" || phase.kind === "running-dirty" ? phase.task : undefined;
+    const task = Promise.resolve(running).then(() => {
+      for (const delivery of this.deliveries.values()) {
+        delivery.mailbox.close();
+      }
+      this.deliveries.clear();
+      this.state?.close();
+      return;
+    });
+    this.phase = { kind: "stopped", task };
+    this.controller.abort();
+    return task;
   }
 }

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

@@ -18,6 +18,7 @@ import {
   type SessionInfo,
 } from "../types.ts";
 import { writeMessage } from "./framing.ts";
+import { PendingRequests } from "./pending-requests.ts";
 
 /** A peer's read of this session or, for a main, of its exited `parked` child. */
 export function lastRequest(msg: UnknownRecord): {
@@ -46,35 +47,25 @@ export class LastMessageRequests {
   constructor(timeoutMs: number) {
     this.timeoutMs = timeoutMs;
   }
-  private readonly pending = new Map<
-    string,
-    {
-      readonly resolve: (result: NativeReadResult) => void;
-      readonly reject: (error: Readonly<Error>) => void;
-      readonly timer: NodeJS.Timeout;
-    }
-  >();
+  private readonly pending = new PendingRequests<{
+    readonly resolve: (result: NativeReadResult) => void;
+    readonly reject: (error: Readonly<Error>) => void;
+  }>();
 
   fail(error: Readonly<Error>): void {
     this.lastMessages = false;
     this.receiptReads = false;
-    for (const pending of this.pending.values()) {
-      clearTimeout(pending.timer);
-      pending.reject(error);
-    }
-    this.pending.clear();
+    this.pending.fail(error);
   }
 
   receive(message: UnknownRecord): void {
     if (typeof message.requestId !== "string" || !isNativeReadResult(message.result)) {
       throw new Error("Invalid last-message response");
     }
-    const pending = this.pending.get(message.requestId);
+    const pending = this.pending.take(message.requestId);
     if (!pending) {
       return;
     }
-    clearTimeout(pending.timer);
-    this.pending.delete(message.requestId);
     pending.resolve(message.result);
   }
 
@@ -100,18 +91,16 @@ export class LastMessageRequests {
     }
     return new Promise((resolve, reject) => {
       const requestId = randomUUID();
-      const timer = setTimeout(() => {
-        this.pending.delete(requestId);
-        reject(new Error("Last-message read timeout"));
-      }, this.timeoutMs);
-      timer.unref();
-      this.pending.set(requestId, { resolve, reject, timer });
+      this.pending.set(
+        requestId,
+        { resolve, reject },
+        this.timeoutMs,
+        () => new Error("Last-message read timeout"),
+      );
       try {
         writeMessage(socket, { type: "last_request", requestId, to, query });
       } catch (error) {
-        clearTimeout(timer);
-        this.pending.delete(requestId);
-        reject(new Error(errorMessage(error)));
+        this.pending.take(requestId)?.reject(new Error(errorMessage(error)));
       }
     });
   }

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

@@ -4,6 +4,7 @@ import { randomUUID } from "crypto";
 import { writeMessage } from "./framing.ts";
 import { BrokerConnection, connectBrokerSocket } from "./connection.ts";
 import { SnapshotReader } from "./snapshot-reader.ts";
+import { PendingRequests } from "./pending-requests.ts";
 import { LastMessageRequests, lastRequest } from "./client-last.ts";
 import { ParkRequests } from "./client-park.ts";
 import { WakeMessages } from "./client-wake.ts";
@@ -70,18 +71,15 @@ export class IntercomClient extends EventEmitter {
   readonly wakes = new WakeMessages(this, () => this.requireActiveSocket());
   private guardedDeliverySupported = false;
   private readonly lastRequests: LastMessageRequests;
-  private readonly pendingSends = new Map<
-    string,
-    { readonly resolve: (r: SendResult) => void; readonly reject: (e: Readonly<Error>) => void }
-  >();
-  private readonly pendingLists = new Map<
-    string,
-    {
-      readonly resolve: (snapshot: SessionSnapshot) => void;
-      readonly reject: (e: Readonly<Error>) => void;
-      readonly reader: SnapshotReader;
-    }
-  >();
+  private readonly pendingSends = new PendingRequests<{
+    readonly resolve: (r: SendResult) => void;
+    readonly reject: (e: Readonly<Error>) => void;
+  }>();
+  private readonly pendingLists = new PendingRequests<{
+    readonly resolve: (snapshot: SessionSnapshot) => void;
+    readonly reject: (e: Readonly<Error>) => void;
+    readonly reader: SnapshotReader;
+  }>();
   private connecting = false;
   private disconnecting = false;
   private readonly sendTimeoutMs: number;
@@ -96,14 +94,8 @@ export class IntercomClient extends EventEmitter {
 
   private failPending(error: Readonly<Error>): void {
     this.lastRequests.fail(error);
-    for (const pending of this.pendingSends.values()) {
-      pending.reject(error);
-    }
-    this.pendingSends.clear();
-    for (const pending of this.pendingLists.values()) {
-      pending.reject(error);
-    }
-    this.pendingLists.clear();
+    this.pendingSends.fail(error);
+    this.pendingLists.fail(error);
   }
 
   get sessionId(): string | null {
@@ -301,12 +293,11 @@ export class IntercomClient extends EventEmitter {
     if (type !== "delivered" && typeof reason !== "string") {
       throw new Error(`Invalid ${errorMessage(type)} message`);
     }
-    const pending = this.pendingSends.get(messageId);
+    const pending = this.pendingSends.take(messageId);
     // Late responses are harmless after the caller has timed out.
     if (!pending) {
       return;
     }
-    this.pendingSends.delete(messageId);
     pending.resolve({
       id: messageId,
       accepted: type !== "delivery_failed",
@@ -330,14 +321,12 @@ export class IntercomClient extends EventEmitter {
       return;
     }
     if (typeof error === "string") {
-      this.pendingLists.delete(requestId);
-      pending.reject(new Error(error));
+      this.pendingLists.take(requestId)?.reject(new Error(error));
       return;
     }
     pending.reader.append(sessions, receipts);
     if (more !== true) {
-      this.pendingLists.delete(requestId);
-      pending.resolve(pending.reader.finish());
+      this.pendingLists.take(requestId)?.resolve(pending.reader.finish());
     }
   }
 
@@ -396,8 +385,8 @@ export class IntercomClient extends EventEmitter {
 
     return new Promise((resolve, reject) => {
       const requestId = randomUUID();
+      const reader = new SnapshotReader();
       const wrappedResolve = (snapshot: SessionSnapshot) => {
-        clearTimeout(timeout);
         try {
           // Commit confirmed subscriptions before handling a following message in the same read.
           onAccepted?.(snapshot);
@@ -407,23 +396,19 @@ export class IntercomClient extends EventEmitter {
         }
       };
       const wrappedReject = (error: Readonly<Error>) => {
-        clearTimeout(timeout);
+        reader.fail();
         reject(error);
       };
-      const timeout = setTimeout(() => {
-        if (this.pendingLists.has(requestId)) {
-          this.pendingLists.delete(requestId);
-          wrappedReject(
-            Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }),
-          );
-        }
-      }, this.listTimeoutMs);
-      timeout.unref();
-      this.pendingLists.set(requestId, {
-        resolve: wrappedResolve,
-        reject: wrappedReject,
-        reader: new SnapshotReader(),
-      });
+      this.pendingLists.set(
+        requestId,
+        {
+          resolve: wrappedResolve,
+          reject: wrappedReject,
+          reader,
+        },
+        this.listTimeoutMs,
+        () => Object.assign(new Error("List sessions timeout"), { code: "list_timeout" }),
+      );
       try {
         writeMessage(socket, {
           type: "list",
@@ -432,9 +417,7 @@ export class IntercomClient extends EventEmitter {
           ...(change ? { change } : {}),
         });
       } catch (error) {
-        clearTimeout(timeout);
-        this.pendingLists.delete(requestId);
-        reject(toError(error));
+        this.pendingLists.take(requestId)?.reject(toError(error));
       }
     });
   }
@@ -456,7 +439,7 @@ export class IntercomClient extends EventEmitter {
     }
 
     const messageId = options.messageId ?? (options.guard ? "" : randomUUID());
-    if (this.pendingSends.has(messageId)) {
+    if (this.pendingSends.get(messageId)) {
       return Promise.reject(new Error("Message ID already has a pending send"));
     }
     const message: Message = {
@@ -482,22 +465,12 @@ export class IntercomClient extends EventEmitter {
       return Promise.reject(new Error("Invalid message format"));
     }
     return new Promise((resolve, reject) => {
-      const wrappedResolve = (result: SendResult) => {
-        clearTimeout(timeout);
-        resolve(result);
-      };
-      const wrappedReject = (error: Readonly<Error>) => {
-        clearTimeout(timeout);
-        reject(error);
-      };
-      const timeout = setTimeout(() => {
-        if (this.pendingSends.has(messageId)) {
-          this.pendingSends.delete(messageId);
-          wrappedReject(new Error("Send timeout"));
-        }
-      }, this.sendTimeoutMs);
-      timeout.unref();
-      this.pendingSends.set(messageId, { resolve: wrappedResolve, reject: wrappedReject });
+      this.pendingSends.set(
+        messageId,
+        { resolve, reject },
+        this.sendTimeoutMs,
+        () => new Error("Send timeout"),
+      );
 
       try {
         writeMessage(socket, {
@@ -506,9 +479,7 @@ export class IntercomClient extends EventEmitter {
           message: this._topicsSupported ? compactTopicMessage(message) : message,
         });
       } catch (error) {
-        clearTimeout(timeout);
-        this.pendingSends.delete(messageId);
-        reject(toError(error));
+        this.pendingSends.take(messageId)?.reject(toError(error));
       }
     });
   }

package/src/pi-intercom/broker/pending-requests.ts

@@ -0,0 +1,37 @@
+interface Request {
+  readonly reject: (error: Readonly<Error>) => void;
+}
+
+/** Map membership owns settlement; taking a request also releases its deadline. */
+export class PendingRequests<T extends Request> {
+  private readonly pending = new Map<
+    string,
+    { readonly value: T; readonly timer: NodeJS.Timeout }
+  >();
+
+  get(id: string): T | undefined {
+    return this.pending.get(id)?.value;
+  }
+
+  set(id: string, value: T, timeoutMs: number, timeoutError: () => Error): void {
+    const timer = setTimeout(() => this.take(id)?.reject(timeoutError()), timeoutMs);
+    timer.unref();
+    this.pending.set(id, { value, timer });
+  }
+
+  take(id: string): T | undefined {
+    const pending = this.pending.get(id);
+    if (pending === undefined) {
+      return;
+    }
+    this.pending.delete(id);
+    clearTimeout(pending.timer);
+    return pending.value;
+  }
+
+  fail(error: Readonly<Error>): void {
+    for (const id of this.pending.keys()) {
+      this.take(id)?.reject(error);
+    }
+  }
+}

package/src/pi-intercom/broker/snapshot-reader.ts

@@ -58,6 +58,14 @@ interface SessionParts {
   readonly subscriptions: TopicSubscription[] | undefined;
 }
 
+type SnapshotPhase =
+  | {
+      readonly kind: "open";
+      readonly sessions: Map<string, SessionParts>;
+      readonly receipts: Receipt[];
+    }
+  | { readonly kind: "finished" | "failed" };
+
 function appendRows<T>(
   previous: T[] | undefined,
   rows: readonly T[] | undefined,
@@ -75,16 +83,28 @@ function appendRows<T>(
 
 /** Multipart frames build a private cache; only a complete validated snapshot escapes. */
 export class SnapshotReader {
-  private readonly sessions = new Map<string, SessionParts>();
-  private readonly receipts: Receipt[] = [];
+  private phase: SnapshotPhase = { kind: "open", sessions: new Map(), receipts: [] };
+
+  private open(): Extract<SnapshotPhase, { readonly kind: "open" }> {
+    if (this.phase.kind !== "open") {
+      throw new Error(`Session snapshot is ${this.phase.kind}`);
+    }
+    return this.phase;
+  }
 
-  private addSession(row: unknown): void {
+  fail(): void {
+    if (this.phase.kind === "open") {
+      this.phase = { kind: "failed" };
+    }
+  }
+
+  private addSession(state: Extract<SnapshotPhase, { readonly kind: "open" }>, row: unknown): void {
     if (!isRecord(row) || typeof row.id !== "string") {
       throw new Error("Invalid session snapshot row");
     }
     const topics = optionalArray(row.topics);
     const subscriptions = optionalArray(row.subscriptions);
-    const previous = this.sessions.get(row.id);
+    const previous = state.sessions.get(row.id);
     const info = normalizeSessionInfo({
       ...previous?.info,
       ...row,
@@ -95,7 +115,7 @@ export class SnapshotReader {
       throw new Error("Invalid session snapshot");
     }
     const { topics: newTopics, subscriptions: newSubscriptions, ...identity } = info;
-    this.sessions.set(info.id, {
+    state.sessions.set(info.id, {
       info: identity,
       topics: appendRows(previous?.topics, newTopics, "topics" in row),
       subscriptions: appendRows(previous?.subscriptions, newSubscriptions, "subscriptions" in row),
@@ -103,27 +123,35 @@ export class SnapshotReader {
   }
 
   append(sessions: readonly unknown[], receipts: unknown): void {
-    for (const row of sessions) {
-      this.addSession(row);
-    }
-    if (receipts === undefined) {
-      return;
-    }
-    if (!isUnknownArray(receipts)) {
-      throw new Error("Invalid topic delivery receipts");
+    const state = this.open();
+    try {
+      for (const row of sessions) {
+        this.addSession(state, row);
+      }
+      if (receipts === undefined) {
+        return;
+      }
+      if (!isUnknownArray(receipts)) {
+        throw new Error("Invalid topic delivery receipts");
+      }
+      state.receipts.push(...receipts.map(receipt));
+    } catch (error) {
+      this.fail();
+      throw error;
     }
-    this.receipts.push(...receipts.map(receipt));
   }
 
   finish(): SessionSnapshot {
+    const state = this.open();
     const sessions: SessionInfo[] = [];
-    for (const { info, topics, subscriptions } of this.sessions.values()) {
+    for (const { info, topics, subscriptions } of state.sessions.values()) {
       sessions.push({
         ...info,
         ...(topics !== undefined ? { topics } : {}),
         ...(subscriptions !== undefined ? { subscriptions } : {}),
       });
     }
-    return { sessions, receipts: this.receipts };
+    this.phase = { kind: "finished" };
+    return { sessions, receipts: state.receipts };
   }
 }