@lelouchhe/webagent 0.3.0 → 0.5.1

package/lib/preflight.js

@@ -0,0 +1,214 @@
+// Startup preflight checks. Each check prints a uniform `[check] <name> ✓`
+// line on success, or `✗` with an actionable hint and exits 78 (sysexits
+// EX_CONFIG) on failure. Runs synchronously before any heavy init so
+// failures land on the operator's terminal first thing, not buried under
+// noise.
+//
+// Scope is intentionally narrow: things we can answer before binding the
+// port. Network reachability, agent login state, etc. are runtime
+// concerns and surface as warnings via the bridge / UI later.
+import { accessSync, constants, mkdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { detectAgent, formatDetectionFailure } from "./agent-detect.js";
+const PAD = 36;
+function pad(s) {
+    return s.length >= PAD ? s + " " : s + " ".repeat(PAD - s.length);
+}
+function printOk(c) {
+    console.log(`[check] ${pad(`${c.name}: ${c.detail}`)}  ✓`);
+}
+function printFail(c) {
+    console.error(`[check] ${pad(`${c.name}: ${c.detail}`)}  ✗`);
+    for (const line of c.hint.split("\n"))
+        console.error(`        ${line}`);
+}
+function checkNodeVersion() {
+    const v = process.versions.node;
+    const [maj, min] = v.split(".").map((n) => parseInt(n, 10));
+    // package.json declares engines.node >= 22.6.0; mirror that here so the
+    // diagnostic is friendly rather than a stack trace from a missing API.
+    const ok = maj > 22 || (maj === 22 && min >= 6);
+    if (ok)
+        return { ok: true, name: "node", detail: `v${v}` };
+    return {
+        ok: false,
+        name: "node",
+        detail: `v${v}`,
+        hint: "webagent requires Node.js v22.6.0 or newer (for --experimental-strip-types).\nInstall via: nvm install 22 && nvm use 22",
+    };
+}
+function checkDataDir(dir) {
+    const abs = resolve(dir);
+    // Create the directory if it doesn't exist (Store does this lazily but
+    // we want the failure surface here, before SQLite tries to open).
+    try {
+        if (!safeStat(abs))
+            mkdirSync(abs, { recursive: true });
+        accessSync(abs, constants.W_OK);
+        return { ok: true, name: "data_dir", detail: abs };
+    }
+    catch (err) {
+        const code = err.code ?? "unknown";
+        return {
+            ok: false,
+            name: "data_dir",
+            detail: abs,
+            hint: `cannot create or write to ${abs}: ${code}\nfix permissions or set data_dir in config.toml to a writable path.`,
+        };
+    }
+    function safeStat(p) {
+        try {
+            return statSync(p);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Resolve `agent_cmd`. If it's the "auto" sentinel, run PATH detection;
+ * otherwise verify the first token (the binary) exists in PATH so we
+ * fail at preflight instead of after `server.listen` with a cryptic
+ * ENOENT in the bridge stderr.
+ */
+function checkAgent(agentCmd) {
+    if (agentCmd === "auto") {
+        const r = detectAgent();
+        if (r.ok) {
+            return {
+                ok: true,
+                name: "acp agent",
+                detail: `${r.label} (${r.cmd})`,
+                resolved: r.cmd,
+            };
+        }
+        return {
+            ok: false,
+            name: "acp agent",
+            detail: "no ACP-ready binary in PATH",
+            hint: formatDetectionFailure(r).replace(/^\[bridge\] [^\n]*\n\n?/, ""),
+        };
+    }
+    // Explicit agent_cmd. Best-effort sanity: check first token's binary.
+    const bin = agentCmd.trim().split(/\s+/)[0];
+    if (!bin) {
+        return {
+            ok: false,
+            name: "acp agent",
+            detail: agentCmd,
+            hint: "agent_cmd is empty.",
+        };
+    }
+    // Use the same detection helper logic via a one-off PATH probe.
+    const which = process.platform === "win32" ? "where" : "which";
+    const r = spawnSync(which, [bin], { stdio: "ignore" });
+    if (r.status === 0) {
+        return {
+            ok: true,
+            name: "acp agent",
+            detail: agentCmd,
+            resolved: agentCmd,
+        };
+    }
+    return {
+        ok: false,
+        name: "acp agent",
+        detail: agentCmd,
+        hint: `'${bin}' not found in PATH.\nverify the binary is installed, or set agent_cmd to "auto" for automatic detection.`,
+    };
+}
+/**
+ * Probe whether `host:port` can be bound (matching what `server.listen`
+ * actually uses). Listens, then closes immediately. There's a tiny
+ * race window between close and the real server.listen() — that's
+ * fine for diagnostics: the goal is a friendly hint, not a hard
+ * guarantee.
+ *
+ * Port 0 means "let the OS pick"; we treat it as always-free.
+ *
+ * Probing the same host as the real server matters: a foreign
+ * listener on 0.0.0.0:PORT occupies 127.0.0.1:PORT too (more-specific
+ * bind fails when wildcard already bound), so binding the configured
+ * host catches conflicts and surfaces EADDRNOTAVAIL when the user
+ * typo'd an IP that isn't on any local interface.
+ */
+async function checkPort(port, host) {
+    const label = `${host}:${port}`;
+    // port=0 still gets probed: the OS picks any free port, but bind can
+    // still fail with EADDRNOTAVAIL if `host` isn't on any local
+    // interface — that's exactly the typo we want to catch.
+    const result = await new Promise((settle) => {
+        const probe = createServer();
+        probe.once("error", (err) => {
+            settle({ code: err.code ?? "unknown" });
+        });
+        probe.listen(port, host, () => {
+            const addr = probe.address();
+            const assigned = typeof addr === "object" && addr ? addr.port : port;
+            probe.close(() => {
+                settle({ assigned });
+            });
+        });
+    });
+    if (!result.code) {
+        if (port === 0) {
+            return {
+                ok: true,
+                name: "port",
+                detail: `${host}:0 (OS-assigned → ${result.assigned})`,
+            };
+        }
+        return { ok: true, name: "port", detail: label };
+    }
+    if (result.code === "EADDRINUSE") {
+        return {
+            ok: false,
+            name: "port",
+            detail: `${label} (in use)`,
+            hint: `${label} is already in use (EADDRINUSE).\nfind the owner: ${process.platform === "win32"
+                ? `netstat -ano | findstr :${port}`
+                : `lsof -nP -iTCP:${port} -sTCP:LISTEN`}\nor change \`port\` in config.toml to a free port.`,
+        };
+    }
+    if (result.code === "EADDRNOTAVAIL") {
+        return {
+            ok: false,
+            name: "port",
+            detail: `${label} (${result.code})`,
+            hint: `cannot bind ${label}: ${result.code}\nthe host '${host}' is not assigned to any local interface.\ncheck \`host\` in config.toml — typical values are "127.0.0.1" (loopback) or "0.0.0.0" (all interfaces).`,
+        };
+    }
+    return {
+        ok: false,
+        name: "port",
+        detail: `${label} (${result.code})`,
+        hint: `cannot bind ${label}: ${result.code}\ncheck firewall / permissions, or change \`host\`/\`port\` in config.toml.`,
+    };
+}
+/**
+ * Run all preflight checks in order. Prints each result; exits process
+ * (78) on first failure. On success, returns the resolved agent command
+ * so the caller doesn't need to re-detect.
+ */
+export async function runPreflight(opts) {
+    const checks = [];
+    checks.push(checkNodeVersion());
+    checks.push(checkDataDir(opts.data_dir));
+    const agent = checkAgent(opts.agent_cmd);
+    checks.push(agent);
+    checks.push(await checkPort(opts.port, opts.host));
+    for (const c of checks) {
+        if (c.ok)
+            printOk(c);
+        else {
+            printFail(c);
+            process.exit(78);
+        }
+    }
+    // After the loop above all checks are ok — narrow the agent result.
+    return {
+        agentCmd: agent.resolved,
+    };
+}

package/lib/push-service.js

@@ -1,21 +1,76 @@
 import webpush from "web-push";
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
+import { log } from "./log.js";
+const slog = log.scope("push");
+const elog = log.scope("egress");
 const VAPID_FILE = "vapid.json";
 /** Remove a subscription after this many consecutive send failures. */
 const MAX_CONSECUTIVE_FAILURES = 5;
+/** Derive the push tag for an ACP event. Kept module-level so it can be
+ *  reused by the close-on-handle path without instantiating the service. */
+export function pushTagForEvent(sessionId, event) {
+    switch (event.type) {
+        case "prompt_done":
+            return `sess-${sessionId}-done`;
+        case "permission_request":
+            return `sess-${sessionId}-perm-${event.eventId ?? "0"}`;
+        case "bash_done":
+            return `sess-${sessionId}-bash-${event.eventId ?? "0"}`;
+        default:
+            return `sess-${sessionId}-${event.type}`;
+    }
+}
+/**
+ * True iff the push endpoint is an Apple (APNs / Web Push on Apple) host.
+ *
+ * We deliberately filter silent `kind:"close"` pushes to these endpoints in
+ * `sendToAll` — iOS Safari PWA enforces an undocumented silent-push budget
+ * that, once exhausted, causes WebKit to drop ALL subsequent pushes for the
+ * subscription (including user-visible `kind:"notify"`). APNs returns 201
+ * throughout, so the server has zero visibility.
+ *
+ * macOS Safari shares the same host but is not subject to that budget; the
+ * conflation here is accepted collateral damage until we add a `platform`
+ * column to `push_subscriptions`.
+ */
+export function isAppleEndpoint(endpoint) {
+    let host;
+    try {
+        host = new URL(endpoint).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    return host === "web.push.apple.com" || host.endsWith(".push.apple.com");
+}
+function emptyClientState() {
+    return { endpoint: null };
+}
 export class PushService {
     store;
     vapidKeys;
-    clientVisibility = new Map(); // clientId → visible
-    clientEndpoints = new Map(); // clientId → push endpoint
-    clientSessions = new Map(); // clientId → currently viewed sessionId
+    /**
+     * Per-client transport state — only the push endpoint. Visibility lives
+     * in ClientRegistry as of Plan C Step 4.
+     */
+    clients = new Map();
     /** endpoint → consecutive failure count (absent or 0 = healthy) */
     failureCounts = new Map();
-    constructor(store, dataDir, vapidSubject) {
+    globalVisibilitySuppression;
+    visibilityTtlMs;
+    now;
+    clientRegistry;
+    constructor(store, dataDir, vapidSubject, options) {
         this.store = store;
         this.vapidKeys = this.loadOrGenerateKeys(dataDir);
         webpush.setVapidDetails(vapidSubject, this.vapidKeys.publicKey, this.vapidKeys.privateKey);
+        this.globalVisibilitySuppression =
+            options.globalVisibilitySuppression ?? true;
+        this.visibilityTtlMs = options.visibilityTtlMs ?? 60_000;
+        this.now = options.now ?? (() => Date.now());
+        this.clientRegistry = options.clientRegistry;
     }
     // ---------------------------------------------------------------------------
     // VAPID keys
@@ -25,12 +80,14 @@ export class PushService {
         if (existsSync(filePath)) {
             chmodSync(filePath, 0o600);
             const keys = JSON.parse(readFileSync(filePath, "utf8"));
-            console.log("[push] loaded VAPID keys");
+            slog.info("loaded VAPID keys");
             return keys;
         }
         const keys = webpush.generateVAPIDKeys();
-        writeFileSync(filePath, JSON.stringify(keys, null, 2) + "\n", { mode: 0o600 });
-        console.log("[push] generated new VAPID keys");
+        writeFileSync(filePath, JSON.stringify(keys, null, 2) + "\n", {
+            mode: 0o600,
+        });
+        slog.info("generated new VAPID keys");
         return keys;
     }
     getPublicKey() {
@@ -39,81 +96,107 @@ export class PushService {
     // ---------------------------------------------------------------------------
     // Notification formatting
     // ---------------------------------------------------------------------------
-    formatNotification(sessionId, sessionTitle, eventType, eventData) {
-        const title = sessionTitle || "WebAgent";
+    formatNotification(sessionId, sessionTitle, eventType, eventData, tag) {
+        const title = sessionTitle ?? "WebAgent";
         let body;
         switch (eventType) {
             case "permission_request":
-                body = `⚿ ${eventData.description ?? "Permission requested"}`;
+                body = `⚿ ${typeof eventData.description === "string" ? eventData.description : "Permission requested"}`;
                 break;
             case "prompt_done":
                 body = "✓ Task complete";
                 break;
             case "bash_done": {
-                const cmd = eventData.command ?? "command";
-                const code = eventData.exitCode ?? "?";
+                const cmd = typeof eventData.command === "string" ? eventData.command : "command";
+                const code = typeof eventData.exitCode === "number" ||
+                    typeof eventData.exitCode === "string"
+                    ? String(eventData.exitCode)
+                    : "?";
                 body = `$ ${cmd} — exit ${code}`;
                 break;
             }
             default:
                 body = eventType;
         }
-        return { title, body, data: { sessionId } };
+        return { kind: "notify", title, body, tag, data: { sessionId } };
     }
     // ---------------------------------------------------------------------------
-    // Client visibility tracking
+    // Endpoint mapping (transport-only as of Plan C Step 4)
     // ---------------------------------------------------------------------------
-    setClientVisibility(clientId, visible) {
-        this.clientVisibility.set(clientId, visible);
+    /**
+     * Set the push endpoint for a client. Identity-layer state (visibility,
+     * active session) goes through ClientRegistry.setVisibility, not here.
+     */
+    updateClient(clientId, patch) {
+        const prev = this.clients.get(clientId) ?? emptyClientState();
+        const next = { ...prev };
+        if (patch.endpoint !== undefined)
+            next.endpoint = patch.endpoint;
+        this.clients.set(clientId, next);
     }
-    setClientSession(clientId, sessionId) {
-        this.clientSessions.set(clientId, sessionId);
+    /**
+     * Read-only snapshot for tests and diagnostics. Do NOT mutate the
+     * returned object.
+     */
+    getClientState(clientId) {
+        return this.clients.get(clientId) ?? null;
     }
     registerClient(clientId, endpoint) {
-        this.clientEndpoints.set(clientId, endpoint);
+        this.updateClient(clientId, { endpoint });
     }
     removeClient(clientId) {
-        this.clientVisibility.delete(clientId);
-        this.clientEndpoints.delete(clientId);
-        this.clientSessions.delete(clientId);
+        this.clients.delete(clientId);
+        // Disconnect also wipes identity-layer state so visibility queries don't
+        // leak past the SSE lifetime. Production calls removeClient on SSE close
+        // (see sse-manager); tests expect the same.
+        this.clientRegistry.remove(clientId);
     }
     hasVisibleClient() {
-        for (const visible of this.clientVisibility.values()) {
-            if (visible)
-                return true;
-        }
-        return false;
+        return this.clientRegistry.hasAnyVisibleClient();
     }
-    /** Check if a specific endpoint has at least one visible client. */
+    /** Check if a specific endpoint has at least one visible (non-stale) client. */
     isEndpointVisible(endpoint) {
-        for (const [clientId, ep] of this.clientEndpoints) {
-            if (ep === endpoint && this.clientVisibility.get(clientId))
+        // Identity (visible) comes from registry, transport (endpoint↔clientId)
+        // stays with pushService.clients.
+        const reg = this.clientRegistry;
+        for (const [clientId, s] of this.clients) {
+            if (s.endpoint !== endpoint)
+                continue;
+            if (reg.isClientVisible(clientId))
                 return true;
         }
         return false;
     }
     /**
-     * Check if any client (across all endpoints) is visible and viewing the given session.
-     * A client with no session set does not suppress any session's push.
-     * Used for global suppression: if any client sees this session, all endpoints are skipped.
+     * Check if any client (across all endpoints) is visible and viewing the
+     * given session. A client with no session set does not suppress any
+     * session's push. Stale records (older than `visibilityTtlMs` since the
+     * last heartbeat refresh) are ignored — this is the server-side safety
+     * net for iOS PWA suspension, where the client's `visible:false` POST may
+     * never leave the device.
+     *
+     * Returns false unconditionally when global suppression is disabled via
+     * the `globalVisibilitySuppression` option (kill switch).
      */
     isSessionVisibleToAnyClient(sessionId) {
-        for (const [clientId, visible] of this.clientVisibility) {
-            if (visible && this.clientSessions.get(clientId) === sessionId)
-                return true;
-        }
-        return false;
+        if (!this.globalVisibilitySuppression)
+            return false;
+        return this.clientRegistry.isSessionVisibleToAnyClient(sessionId);
     }
     // ---------------------------------------------------------------------------
     // High-level: decide whether to push, and if so, send
     // ---------------------------------------------------------------------------
-    static NOTIFIABLE = new Set(["permission_request", "prompt_done", "bash_done"]);
+    static NOTIFIABLE = new Set([
+        "permission_request",
+        "prompt_done",
+        "bash_done",
+    ]);
     /**
      * Check if this event should trigger a push notification.
      * Returns true if a notification should be sent (caller should then call sendToAll).
      * Global session visibility suppression happens inside sendToAll.
      */
-    maybeNotify(sessionId, sessionTitle, eventType, eventData) {
+    maybeNotify(sessionId, sessionTitle, eventType, _eventData) {
         if (!PushService.NOTIFIABLE.has(eventType))
             return false;
         return true;
@@ -122,45 +205,207 @@ export class PushService {
     // Send push to all subscriptions
     // ---------------------------------------------------------------------------
     async sendToAll(notification) {
-        const subs = this.store.getAllSubscriptions();
-        if (subs.length === 0)
+        const allSubs = this.store.getAllSubscriptions();
+        if (allSubs.length === 0)
             return;
+        // Global visibility: if any client is viewing this session, suppress notify pushes.
+        // Close pushes are never suppressed — they're silent and are the mechanism
+        // by which cross-device recall actually closes banners on the "losing" devices.
+        if (notification.kind === "notify") {
+            const targetSession = notification.data.sessionId;
+            if (targetSession && this.isSessionVisibleToAnyClient(targetSession))
+                return;
+        }
+        // Skip Apple endpoints for silent close pushes to preserve iOS PWA's
+        // silent-push budget. See isAppleEndpoint() for rationale.
+        let subs = allSubs;
+        let filteredApple = 0;
+        if (notification.kind === "close") {
+            subs = allSubs.filter((s) => {
+                if (isAppleEndpoint(s.endpoint)) {
+                    filteredApple++;
+                    return false;
+                }
+                return true;
+            });
+            if (subs.length === 0) {
+                elog.info("sendClose", {
+                    tag: notification.tag,
+                    endpoints: 0,
+                    ok: 0,
+                    fail: 0,
+                    fail_410: 0,
+                    filtered_apple: filteredApple,
+                });
+                return;
+            }
+        }
         const payload = JSON.stringify(notification);
-        // Global visibility: if any client is viewing this session, suppress all push
-        if (this.isSessionVisibleToAnyClient(notification.data.sessionId))
-            return;
-        const results = await Promise.allSettled(subs.map((sub) => this.sendOne({ endpoint: sub.endpoint, keys: { auth: sub.auth, p256dh: sub.p256dh } }, payload)));
+        // Derive an RFC 8030 Topic so push services can collapse undelivered
+        // pushes on the wire. FCM (Chrome/Firefox desktop + Android) honors
+        // this and collapses correctly. APNs (iOS Safari PWA) does NOT — we
+        // verified in dogfood that two same-Topic pushes still surface as
+        // two stacked banners on iOS 17, even combined with the SW-side
+        // close-before-show workaround (see public/sw.js). Keep the header
+        // anyway: it's spec-compliant, cheap, and benefits every non-Apple
+        // client. iOS banner stacking is a platform limitation we accept.
+        const topic = tagToTopic(notification.tag);
+        const results = await Promise.allSettled(subs.map((sub) => this.sendOne({
+            endpoint: sub.endpoint,
+            keys: { auth: sub.auth, p256dh: sub.p256dh },
+        }, payload, { topic })));
+        let ok = 0;
+        let fail = 0;
+        let fail410 = 0;
         for (let i = 0; i < results.length; i++) {
             const result = results[i];
             const endpoint = subs[i].endpoint;
             if (result.status === "fulfilled") {
                 this.failureCounts.delete(endpoint);
+                ok++;
             }
             else {
+                fail++;
                 const err = result.reason;
                 if (err.statusCode === 410) {
-                    // Subscription expired — clean up immediately
+                    fail410++;
                     this.store.removeSubscription(endpoint);
                     this.failureCounts.delete(endpoint);
-                    console.log(`[push] removed expired subscription (410): ${endpoint.slice(0, 60)}…`);
+                    slog.info("removed expired subscription (410)", {
+                        endpoint: endpoint.slice(0, 60) + "…",
+                    });
                 }
                 else {
                     const count = (this.failureCounts.get(endpoint) ?? 0) + 1;
                     if (count >= MAX_CONSECUTIVE_FAILURES) {
                         this.store.removeSubscription(endpoint);
                         this.failureCounts.delete(endpoint);
-                        console.log(`[push] removed subscription after ${count} consecutive failures: ${endpoint.slice(0, 60)}…`);
+                        slog.info("removed subscription after consecutive failures", {
+                            count,
+                            endpoint: endpoint.slice(0, 60) + "…",
+                        });
                     }
                     else {
                         this.failureCounts.set(endpoint, count);
-                        console.error(`[push] send failed (${count}/${MAX_CONSECUTIVE_FAILURES}) for ${endpoint.slice(0, 60)}…:`, result.reason);
+                        slog.error("send failed", {
+                            count,
+                            max: MAX_CONSECUTIVE_FAILURES,
+                            endpoint: endpoint.slice(0, 60) + "…",
+                            error: result.reason,
+                        });
                     }
                 }
             }
         }
+        if (notification.kind === "close") {
+            // Observability signal #6 — aggregated per-call close outcome.
+            elog.info("sendClose", {
+                tag: notification.tag,
+                endpoints: subs.length,
+                ok,
+                fail,
+                fail_410: fail410,
+                filtered_apple: filteredApple,
+            });
+        }
+    }
+    /** Send a silent close push for the given tag. Never visibility-suppressed. */
+    async sendClose(tag) {
+        await this.sendToAll({ kind: "close", tag });
+    }
+    /**
+     * Send a push for an external message. Respects the message's `deliver`
+     * intent: `silent` sends nothing, `inapp` and `push` both send through
+     * web-push (the `inapp` vs `push` distinction is enforced by the SW /
+     * frontend rendering, not by the server).
+     *
+     * Tag = `msg-<id>` for unbound messages; bound messages get the
+     * `sess-<sid>-msg-<eid>` tag by taking a different code path in the
+     * consume handler.
+     */
+    async sendForMessage(msg) {
+        const deliver = msg.deliver ?? "push";
+        if (deliver === "silent")
+            return false;
+        const subs = this.store.getAllSubscriptions();
+        const title = msg.from_label ?? msg.from_ref ?? "Message";
+        const body = msg.body.length > 140 ? msg.body.slice(0, 137) + "…" : msg.body;
+        const tag = msg.dedup_key ? `dedup-${msg.to}-${msg.dedup_key}` : msg.id;
+        // If this message targets a specific session, surface the sid in the
+        // push data so SW notificationclick can route the user there. Without
+        // this, clicks fall back to "/" and land on whatever session was last
+        // open — a confusing UX when multiple sessions get background pushes.
+        const sessionId = msg.to.startsWith("session:")
+            ? msg.to.slice("session:".length)
+            : undefined;
+        // Observability signal #7 — sendForMessage entry.
+        elog.info("sendForMessage", {
+            msg_id: msg.id,
+            tag,
+            deliver,
+            endpoints: subs.length,
+            suppressed_by_visibility: false,
+        });
+        await this.sendToAll({
+            kind: "notify",
+            title,
+            body,
+            tag,
+            data: sessionId
+                ? { messageId: msg.id, sessionId }
+                : { messageId: msg.id },
+        });
+        return true;
+    }
+    /**
+     * Send a push for an ACP session event (permission_request / prompt_done /
+     * bash_done). Handles tag derivation, visibility suppression, and session-
+     * title lookup. Returns `true` if a push attempt was made.
+     */
+    async sendForEvent(sessionId, event) {
+        if (!PushService.NOTIFIABLE.has(event.type))
+            return false;
+        const session = this.store.getSession(sessionId);
+        const sessionTitle = session?.title ?? null;
+        const tag = pushTagForEvent(sessionId, event);
+        const eventData = {};
+        if (event.type === "permission_request" && event.title !== undefined) {
+            eventData.description = event.title;
+        }
+        if (event.type === "bash_done") {
+            if (event.command !== undefined)
+                eventData.command = event.command;
+            if (event.exitCode !== undefined)
+                eventData.exitCode = event.exitCode;
+        }
+        const suppressed = this.isSessionVisibleToAnyClient(sessionId);
+        const subs = this.store.getAllSubscriptions();
+        elog.info("sendForEvent", {
+            sess_id: sessionId.slice(0, 8),
+            type: event.type,
+            tag,
+            endpoints: subs.length,
+            suppressed_by_visibility: suppressed,
+        });
+        const notification = this.formatNotification(sessionId, sessionTitle, event.type, eventData, tag);
+        await this.sendToAll(notification);
+        return true;
     }
     /** Send a single push notification. Extracted for testability. */
-    sendOne(sub, payload) {
-        return webpush.sendNotification(sub, payload);
+    sendOne(sub, payload, options) {
+        return webpush.sendNotification(sub, payload, options);
     }
 }
+/**
+ * Derive an RFC 8030 `Topic` header value from a notification tag. The
+ * spec limits topic to ≤32 chars of URL-safe Base64, so we hash and
+ * truncate. FCM maps this to its on-wire collapse key and works
+ * correctly. APNs is documented to map Topic → `apns-collapse-id`,
+ * but in practice iOS Safari PWA (≤17 at least) still surfaces
+ * stacked banners for same-Topic pushes — confirmed in dogfood.
+ * We keep the header for the platforms where it does work and for
+ * spec compliance; don't expect it to fix iOS.
+ */
+function tagToTopic(tag) {
+    return createHash("sha256").update(tag).digest("base64url").slice(0, 22);
+}