@fitchmultz/pi-subagents 0.48.0 → 0.49.0

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

@@ -0,0 +1,293 @@
+import { lstatSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { privateDatabase, privateFile, stateDirectory } from "./bridge-storage.js";
+import { readBridgeFile } from "./bridge-files.js";
+import { isRecord, isUnknownArray } from "../shared/unknown.js";
+import { object } from "./bridge-protocol.js";
+import { WakeOwner, WAKE_OWNER_FILE, stoppedWakeOwner } from "./bridge-wake-owner.js";
+const HOUR_MS = 3600000;
+const LIMIT = 20;
+const RETRY_MS = 30000;
+const MAX_BACKOFF_MS = 300000;
+const FILE = "wake-quota.sqlite";
+const ATTEMPTS = `CREATE TABLE wake_attempts(
+  sequence INTEGER PRIMARY KEY, attemptedAt INTEGER NOT NULL,
+  settledAt INTEGER, owner TEXT,
+  CHECK(settledAt IS NOT NULL OR owner IS NOT NULL))`;
+function integer(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error("Invalid durable wake state.");
+    }
+    return value;
+}
+/** One helper ledger, independent of identity, certificate, URL and credential rotation. */
+export class WakeState {
+    db;
+    path;
+    stateDir;
+    inode;
+    device;
+    owner;
+    finishing = false;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        this.path = join(stateDir, FILE);
+        const { db, created } = privateDatabase(stateDir, FILE);
+        this.db = db;
+        const stat = lstatSync(this.path);
+        this.inode = stat.ino;
+        this.device = stat.dev;
+        try {
+            if (created) {
+                this.initialize();
+            }
+            this.verify();
+            this.migrate();
+            this.owner = this.createOwner();
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    verify() {
+        const db = this.db;
+        if (db.prepare("PRAGMA quick_check").get()?.quick_check !== "ok") {
+            throw new Error("Wake ledger is corrupt.");
+        }
+        const meta = db.prepare("SELECT version, clock FROM wake_meta WHERE singleton=1").get();
+        if (!meta || (meta.version !== 1 && meta.version !== 2)) {
+            throw new Error("Unsupported wake ledger.");
+        }
+        integer(meta.clock);
+        this.verifyAttempts(meta.version);
+        for (const row of db.prepare("SELECT due, backoff FROM wake_batches").all()) {
+            integer(row.due);
+            const backoff = integer(row.backoff);
+            if ((backoff !== 0 && backoff < RETRY_MS) || backoff > MAX_BACKOFF_MS) {
+                throw new Error("Invalid wake retry state.");
+            }
+        }
+    }
+    createOwner() {
+        let owner;
+        try {
+            // Recovery holds this same ledger lock: it cannot reap a file before its owner locks it.
+            return this.transaction(() => {
+                owner = new WakeOwner(this.stateDir);
+                return owner;
+            });
+        }
+        catch (error) {
+            owner?.close();
+            throw error;
+        }
+    }
+    verifyAttempts(version) {
+        for (const row of this.db.prepare("SELECT attemptedAt FROM wake_attempts").all()) {
+            integer(row.attemptedAt);
+        }
+        if (version !== 2) {
+            return;
+        }
+        for (const row of this.db
+            .prepare("SELECT attemptedAt, settledAt, owner FROM wake_attempts")
+            .all()) {
+            if (row.settledAt !== null) {
+                if (integer(row.settledAt) < integer(row.attemptedAt)) {
+                    throw new Error("Invalid wake completion time.");
+                }
+            }
+            else if (typeof row.owner !== "string" || !WAKE_OWNER_FILE.test(row.owner)) {
+                throw new Error("Invalid open wake attempt.");
+            }
+        }
+    }
+    initialize() {
+        // Timestamped legacy outcomes omit crash-before-log attempts. Verified preflight may provide
+        // complete history plus a bounded unknown reservation; absent proof reserves the full hour.
+        const legacy = readdirSync(this.stateDir).some((name) => name !== FILE && (name.endsWith(".sqlite") || name.startsWith("presence-")));
+        const now = Date.now();
+        const attempts = this.history(now) ?? (legacy ? Array(LIMIT).fill(now) : []);
+        this.db.exec(`BEGIN IMMEDIATE;
+      CREATE TABLE wake_meta(singleton INTEGER PRIMARY KEY CHECK(singleton=1), version INTEGER NOT NULL, clock INTEGER NOT NULL);
+      ${ATTEMPTS};
+      CREATE TABLE wake_batches(bucket TEXT PRIMARY KEY, due INTEGER NOT NULL, backoff INTEGER NOT NULL);`);
+        this.db.prepare("INSERT INTO wake_meta VALUES(1,2,?)").run(now);
+        const insert = this.db.prepare("INSERT INTO wake_attempts(attemptedAt,settledAt) VALUES(?,?)");
+        for (const timestamp of attempts) {
+            insert.run(timestamp, timestamp);
+        }
+        this.db.exec("COMMIT");
+    }
+    migrate() {
+        this.transaction(() => {
+            if (this.db.prepare("SELECT version FROM wake_meta").get()?.version !== 1) {
+                return;
+            }
+            // V1 timestamps precede COMMIT/connect/TLS, so none prove when a POST finished.
+            // Stop all old writers before upgrading; the new CHECK also denies their old INSERT shape.
+            const now = Math.max(Date.now(), integer(this.db.prepare("SELECT clock FROM wake_meta").get()?.clock));
+            this.db.exec(`ALTER TABLE wake_attempts RENAME TO wake_attempts_v1; ${ATTEMPTS};`);
+            this.db
+                .prepare(`INSERT INTO wake_attempts(sequence,attemptedAt,settledAt)
+        SELECT sequence,attemptedAt,MAX(attemptedAt,?) FROM wake_attempts_v1`)
+                .run(now);
+            this.db.exec("DROP TABLE wake_attempts_v1");
+            this.db.prepare("UPDATE wake_meta SET version=2,clock=?").run(now);
+        });
+    }
+    history(now) {
+        const path = join(this.stateDir, "wake-history.json");
+        let input;
+        try {
+            privateFile(path);
+            input = JSON.parse(readBridgeFile(path, true, 1024 * 1024).toString("utf8"));
+        }
+        catch (error) {
+            if (isRecord(error) && error.code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
+        const raw = object(input, ["coveredSince", "stoppedAt", "attempts", "unknownAttempts"]);
+        const coveredSince = integer(raw.coveredSince);
+        const stoppedAt = integer(raw.stoppedAt);
+        const unknownAttempts = integer(raw.unknownAttempts);
+        if (coveredSince > stoppedAt - HOUR_MS ||
+            stoppedAt > now ||
+            unknownAttempts > LIMIT ||
+            !isUnknownArray(raw.attempts) ||
+            raw.attempts.length > 10000) {
+            throw new Error("Invalid legacy wake history; never reset prior usage.");
+        }
+        const attempts = raw.attempts.map(integer);
+        if (attempts.some((timestamp) => timestamp < coveredSince || timestamp > stoppedAt)) {
+            throw new Error("Attempt outside attested history coverage.");
+        }
+        return attempts
+            .filter((timestamp) => timestamp > now - HOUR_MS)
+            .concat(Array(unknownAttempts).fill(now));
+    }
+    validate() {
+        stateDirectory(this.stateDir);
+        privateFile(this.path);
+        const stat = lstatSync(this.path);
+        if (stat.ino !== this.inode || stat.dev !== this.device) {
+            throw new Error("Wake ledger was replaced.");
+        }
+    }
+    deadline(bucket) {
+        this.validate();
+        const existing = this.db.prepare("SELECT due FROM wake_batches WHERE bucket=?").get(bucket);
+        if (existing) {
+            return integer(existing.due);
+        }
+        // First observation occurs only after mailbox FULL commit, never at the pre-write receivedAt.
+        // Keep this grace durable too: new arrivals/reload/restart cannot restart an existing deadline.
+        this.db
+            .prepare("INSERT OR IGNORE INTO wake_batches VALUES(?,?,0)")
+            .run(bucket, Date.now() + 2000);
+        return integer(this.db.prepare("SELECT due FROM wake_batches WHERE bucket=?").get(bucket)?.due);
+    }
+    retire(bucket) {
+        this.validate();
+        this.db.prepare("DELETE FROM wake_batches WHERE bucket=?").run(bucket);
+    }
+    /** Persist quota and uncertainty BEFORE dispatch. Returning a deadline means no attempt admitted. */
+    reserve(bucket) {
+        this.retrySettlement();
+        return this.transaction(() => this.reservation(bucket));
+    }
+    retrySettlement() {
+        if (this.finishing) {
+            this.settle();
+        }
+    }
+    transaction(action) {
+        this.validate();
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = action();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    /** A failed settlement stays open and must be retried before this owner can dispatch again. */
+    settle() {
+        this.finishing = true;
+        this.transaction(() => this.finishOwner(this.owner.name));
+        this.finishing = false;
+    }
+    finishOwner(owner) {
+        const now = Math.max(Date.now(), integer(this.db.prepare("SELECT clock FROM wake_meta").get()?.clock));
+        this.db
+            .prepare(`UPDATE wake_attempts SET settledAt=MAX(attemptedAt,?)
+      WHERE owner=? AND settledAt IS NULL`)
+            .run(now, owner);
+        this.db.prepare("UPDATE wake_meta SET clock=?").run(now);
+    }
+    recover() {
+        const names = new Set(readdirSync(this.stateDir).filter((name) => WAKE_OWNER_FILE.test(name)));
+        for (const row of this.db
+            .prepare("SELECT DISTINCT owner FROM wake_attempts WHERE settledAt IS NULL")
+            .all()) {
+            if (typeof row.owner !== "string") {
+                throw new Error("Invalid open wake owner.");
+            }
+            names.add(row.owner);
+        }
+        for (const name of names) {
+            if (name !== this.owner.name && stoppedWakeOwner(this.stateDir, name)) {
+                // The owner cannot send again. Unknown outcomes retain a full hour from this observation.
+                this.finishOwner(name);
+                rmSync(join(this.stateDir, name), { force: true });
+            }
+        }
+    }
+    reservation(bucket) {
+        this.recover();
+        const clock = integer(this.db.prepare("SELECT clock FROM wake_meta WHERE singleton=1").get()?.clock);
+        const now = Date.now();
+        if (now < clock) {
+            return clock;
+        }
+        const row = this.db.prepare("SELECT due, backoff FROM wake_batches WHERE bucket=?").get(bucket);
+        if (row && integer(row.due) > now) {
+            return integer(row.due);
+        }
+        this.db.prepare("DELETE FROM wake_attempts WHERE settledAt<=?").run(now - HOUR_MS);
+        const attempts = this.db
+            .prepare("SELECT settledAt FROM wake_attempts ORDER BY settledAt")
+            .all();
+        if (attempts.length >= LIMIT) {
+            const oldest = attempts.find((attempt) => attempt.settledAt !== null);
+            // Only open/unknown attempts have no expiry yet; revisit on the existing recovery backoff.
+            return oldest ? integer(oldest.settledAt) + HOUR_MS : now + RETRY_MS;
+        }
+        const backoff = row
+            ? Math.max(RETRY_MS, Math.min(integer(row.backoff) * 2, MAX_BACKOFF_MS))
+            : RETRY_MS;
+        this.db
+            .prepare("INSERT INTO wake_attempts(attemptedAt,owner) VALUES(?,?)")
+            .run(now, this.owner.name);
+        this.db.prepare("UPDATE wake_meta SET clock=? WHERE singleton=1").run(now);
+        this.db
+            .prepare("INSERT OR REPLACE INTO wake_batches VALUES(?,?,?)")
+            .run(bucket, now + backoff, backoff);
+        return;
+    }
+    close() {
+        try {
+            this.settle();
+        }
+        finally {
+            this.db.close();
+            this.owner.close();
+        }
+    }
+}

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

@@ -1,146 +1,232 @@
+import { createHash } from "node:crypto";
 import { log } from "./bridge-protocol.js";
 import { Mailbox } from "./bridge-mailbox.js";
-const POLL_MS = 15000;
-const FALLBACK_AFTER_MS = 120000;
-const MAX_BACKOFF_MS = 300000;
-export class WakeDelivery {
+import { WakeState } from "./bridge-wake-state.js";
+function actionable(entry) {
+    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) {
+    return createHash("sha256")
+        .update(identity.wake?.url ?? "")
+        .digest("hex");
+}
+/** Mailbox commits and durable retry/quota deadlines drive wakes; there is no intake scan timer. */
+export class WakeDeliveries {
+    stateDir;
+    state;
+    allowed;
+    deliveries = new Map();
     controller = new AbortController();
     timer;
     running;
-    backoff = POLL_MS;
-    name;
-    mailbox;
-    policy;
-    authorized;
-    constructor(name, mailbox, policy, authorized) {
-        this.name = name;
-        this.mailbox = mailbox;
-        this.policy = policy;
-        this.authorized = authorized;
+    dirty = false;
+    storageBackoff = 15000;
+    constructor(stateDir, allowed) {
+        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);
+    }
+    session(identity, expires) {
+        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);
+    }
+    changed(reconcile = true) {
+        if (this.controller.signal.aborted) {
+            return;
+        }
+        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.
+        }
+        if (this.running) {
+            this.dirty = true;
+        }
+        else {
+            this.schedule(Date.now());
+        }
     }
-    start() {
-        if (!this.running && !this.controller.signal.aborted) {
-            this.schedule(0);
+    reconcile() {
+        for (const [key, candidate] of this.groups()) {
+            if (candidate) {
+                this.state?.deadline(key);
+            }
+            else {
+                this.state?.retire(key);
+            }
         }
     }
-    schedule(delay) {
+    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;
+                return;
+            })
                 .catch(() => {
-                log("wake_delivery", { name: this.name, result: "storage_unavailable" });
-                this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+                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.schedule(this.backoff);
+                if (!this.controller.signal.aborted && (this.dirty || Number.isFinite(next))) {
+                    this.schedule(this.dirty ? Date.now() : next);
                 }
             });
-        }, delay);
+        }, Math.max(0, Math.min(deadline - Date.now(), 0x7fffffff)));
+    }
+    authorized(delivery) {
+        return (!this.controller.signal.aborted &&
+            this.allowed(delivery.identity) &&
+            delivery.expires > Date.now());
+    }
+    pending(delivery) {
+        let after = 0;
+        let next;
+        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;
+    }
+    groups() {
+        const groups = new Map();
+        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;
     }
     async deliver() {
-        if (!this.authorized()) {
-            return;
+        const state = this.state;
+        let next = Infinity;
+        if (!state) {
+            return next;
         }
-        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);
+        // 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();
         }
-        const next = entries.find((entry) => !entry.acknowledged && Date.now() - entry.receivedAt >= FALLBACK_AFTER_MS);
-        if (next) {
-            // One fallback wakes the box to drain the remaining mailbox; never flood a reset VM.
-            await this.post(next);
-            return;
-        }
-        this.backoff = POLL_MS;
+        return next;
     }
-    async post(entry) {
-        if (!this.authorized()) {
+    async post({ delivery, entry }) {
+        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() {
-        this.controller.abort();
-        clearTimeout(this.timer);
-        await this.running;
-    }
-}
-export class WakeDeliveries {
-    stateDir;
-    allowed;
-    deliveries = new Map();
-    cleanup = new Set();
-    constructor(stateDir, allowed) {
-        this.stateDir = stateDir;
-        this.allowed = allowed;
-    }
-    session(identity, expires) {
-        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) {
         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() {
         for (const [fp, delivery] of this.deliveries) {
@@ -148,11 +234,16 @@ export class WakeDeliveries {
                 this.drop(fp);
             }
         }
+        this.changed(false);
     }
     async stop() {
-        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();
     }
 }