commandmate 0.23.0 → 0.24.0

package/dist/server/src/lib/push/escalation-settings.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * The "still waiting" reminder setting (Issue #1790).
+ *
+ * A wait that nobody answers is the case push notifications exist for, and one
+ * notification is easy to miss — so after a threshold the server sends exactly
+ * one more. How long to wait, and whether to do it at all, is a user decision,
+ * and it is a *server-side* one: the check runs in the background with no
+ * request and no browser attached, so it cannot read a device's localStorage the
+ * way #1788's in-app toggle does. It is therefore stored once for the install
+ * and applies to every subscribed device.
+ *
+ * ## Why the SQL lives here
+ *
+ * `app_settings` (migration v27) is the generic key-value store this rides on,
+ * so no migration is added. Its typed helpers live in `db/app-settings-db`, but
+ * both existing ones are `string[]`-shaped and this value is an object with two
+ * fields of different types; a third helper there would be a fourth reader of
+ * the same table with no shared logic to gain. Keeping the accessor beside its
+ * only consumer also keeps the defaults — which the escalation tick applies on
+ * every failure path — in one file.
+ *
+ * Every read is total: a missing row, malformed JSON, an out-of-range threshold
+ * or an unopenable database all resolve to {@link DEFAULT_ESCALATION_SETTINGS}
+ * rather than throwing. The caller is a background timer whose failure mode
+ * must be "no reminder", never "the server logs an exception every minute".
+ *
+ * @module lib/push/escalation-settings
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ESCALATION_THRESHOLD_MINUTES = exports.MIN_ESCALATION_THRESHOLD_MINUTES = exports.ESCALATION_THRESHOLD_CHOICES = exports.DEFAULT_ESCALATION_SETTINGS = exports.ESCALATION_SETTINGS_KEY = void 0;
+exports.normalizeEscalationSettings = normalizeEscalationSettings;
+exports.getPushEscalationSettings = getPushEscalationSettings;
+exports.setPushEscalationSettings = setPushEscalationSettings;
+const db_instance_1 = require("../../lib/db/db-instance");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('push/escalation-settings');
+/** `app_settings.key` this setting is stored under. */
+exports.ESCALATION_SETTINGS_KEY = 'push_escalation';
+/**
+ * On by default at ten minutes, per the Issue.
+ *
+ * Defaulting to *on* is the same call #1788 made for the in-app toast: a user
+ * who never opened the settings screen is the one most likely to walk away from
+ * a waiting agent, and the cost of being wrong is one extra notification per
+ * unanswered wait — bounded, because there is only ever one.
+ */
+exports.DEFAULT_ESCALATION_SETTINGS = {
+    enabled: true,
+    thresholdMinutes: 10,
+};
+/** The thresholds the settings UI offers, in minutes. */
+exports.ESCALATION_THRESHOLD_CHOICES = [5, 10, 30, 60];
+/** Guard rails for a hand-written value: at least a minute, at most a day. */
+exports.MIN_ESCALATION_THRESHOLD_MINUTES = 1;
+exports.MAX_ESCALATION_THRESHOLD_MINUTES = 1440;
+/**
+ * Narrow arbitrary input to a usable setting, filling each field independently.
+ *
+ * Field-by-field rather than all-or-nothing so that a bad threshold does not
+ * silently switch the reminder back on (or off): the half the user did set is
+ * the half that is honoured.
+ */
+function normalizeEscalationSettings(value) {
+    if (typeof value !== 'object' || value === null)
+        return { ...exports.DEFAULT_ESCALATION_SETTINGS };
+    const record = value;
+    const enabled = typeof record.enabled === 'boolean' ? record.enabled : exports.DEFAULT_ESCALATION_SETTINGS.enabled;
+    const raw = record.thresholdMinutes;
+    const thresholdMinutes = typeof raw === 'number' &&
+        Number.isFinite(raw) &&
+        raw >= exports.MIN_ESCALATION_THRESHOLD_MINUTES &&
+        raw <= exports.MAX_ESCALATION_THRESHOLD_MINUTES
+        ? Math.round(raw)
+        : exports.DEFAULT_ESCALATION_SETTINGS.thresholdMinutes;
+    return { enabled, thresholdMinutes };
+}
+/** Read the setting. Never throws — see the module docblock. */
+function getPushEscalationSettings() {
+    try {
+        const row = (0, db_instance_1.getDbInstance)()
+            .prepare('SELECT value FROM app_settings WHERE key = ?')
+            .get(exports.ESCALATION_SETTINGS_KEY);
+        if (!row)
+            return { ...exports.DEFAULT_ESCALATION_SETTINGS };
+        return normalizeEscalationSettings(JSON.parse(row.value));
+    }
+    catch (error) {
+        logger.warn('escalation-settings-read-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { ...exports.DEFAULT_ESCALATION_SETTINGS };
+    }
+}
+/**
+ * Persist the setting, normalizing first so a malformed request cannot store a
+ * value later reads would have to reject anyway.
+ *
+ * @returns What was actually written.
+ */
+function setPushEscalationSettings(value) {
+    const settings = normalizeEscalationSettings(value);
+    const now = Date.now();
+    (0, db_instance_1.getDbInstance)()
+        .prepare(`
+      INSERT INTO app_settings (key, value, created_at, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET
+        value = excluded.value,
+        updated_at = excluded.updated_at
+    `)
+        .run(exports.ESCALATION_SETTINGS_KEY, JSON.stringify(settings), now, now);
+    return settings;
+}

package/dist/server/src/lib/push/index.js

@@ -1,7 +1,7 @@
 "use strict";
 /** Web Push module barrel (Issue #1125). */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DEDUP_WINDOW_MS = exports.resetNotificationDedup = exports.shouldSendNotification = exports.resolvePushLocale = exports.buildExcerpt = exports.buildPushPayload = exports.notifyPushSubscribers = exports.getVapidPublicKey = exports.isPushConfigured = exports.getVapidConfig = void 0;
+exports.MAX_ESCALATION_THRESHOLD_MINUTES = exports.MIN_ESCALATION_THRESHOLD_MINUTES = exports.ESCALATION_SETTINGS_KEY = exports.ESCALATION_THRESHOLD_CHOICES = exports.DEFAULT_ESCALATION_SETTINGS = exports.normalizeEscalationSettings = exports.setPushEscalationSettings = exports.getPushEscalationSettings = exports.ESCALATION_TICK_MS = exports.pendingEscalationCount = exports.runEscalationTick = exports.handleWaitingTransition = exports.isWaitingPushNotifierActive = exports.stopWaitingPushNotifier = exports.startWaitingPushNotifier = exports.resetWaitingPushDedup = exports.shouldSendWaitingPush = exports.DEFAULT_DEDUP_WINDOW_MS = exports.resetNotificationDedup = exports.shouldSendNotification = exports.resolvePushLocale = exports.buildExcerpt = exports.buildPushPayload = exports.notifyPushSubscribers = exports.getVapidPublicKey = exports.isPushConfigured = exports.getVapidConfig = void 0;
 var vapid_1 = require("./vapid");
 Object.defineProperty(exports, "getVapidConfig", { enumerable: true, get: function () { return vapid_1.getVapidConfig; } });
 Object.defineProperty(exports, "isPushConfigured", { enumerable: true, get: function () { return vapid_1.isPushConfigured; } });
@@ -15,3 +15,23 @@ var notification_dedup_1 = require("./notification-dedup");
 Object.defineProperty(exports, "shouldSendNotification", { enumerable: true, get: function () { return notification_dedup_1.shouldSendNotification; } });
 Object.defineProperty(exports, "resetNotificationDedup", { enumerable: true, get: function () { return notification_dedup_1.resetNotificationDedup; } });
 Object.defineProperty(exports, "DEFAULT_DEDUP_WINDOW_MS", { enumerable: true, get: function () { return notification_dedup_1.DEFAULT_DEDUP_WINDOW_MS; } });
+Object.defineProperty(exports, "shouldSendWaitingPush", { enumerable: true, get: function () { return notification_dedup_1.shouldSendWaitingPush; } });
+Object.defineProperty(exports, "resetWaitingPushDedup", { enumerable: true, get: function () { return notification_dedup_1.resetWaitingPushDedup; } });
+// Waiting-edge driven notifications (Issue #1790).
+var waiting_push_notifier_1 = require("./waiting-push-notifier");
+Object.defineProperty(exports, "startWaitingPushNotifier", { enumerable: true, get: function () { return waiting_push_notifier_1.startWaitingPushNotifier; } });
+Object.defineProperty(exports, "stopWaitingPushNotifier", { enumerable: true, get: function () { return waiting_push_notifier_1.stopWaitingPushNotifier; } });
+Object.defineProperty(exports, "isWaitingPushNotifierActive", { enumerable: true, get: function () { return waiting_push_notifier_1.isWaitingPushNotifierActive; } });
+Object.defineProperty(exports, "handleWaitingTransition", { enumerable: true, get: function () { return waiting_push_notifier_1.handleWaitingTransition; } });
+Object.defineProperty(exports, "runEscalationTick", { enumerable: true, get: function () { return waiting_push_notifier_1.runEscalationTick; } });
+Object.defineProperty(exports, "pendingEscalationCount", { enumerable: true, get: function () { return waiting_push_notifier_1.pendingEscalationCount; } });
+Object.defineProperty(exports, "ESCALATION_TICK_MS", { enumerable: true, get: function () { return waiting_push_notifier_1.ESCALATION_TICK_MS; } });
+var escalation_settings_1 = require("./escalation-settings");
+Object.defineProperty(exports, "getPushEscalationSettings", { enumerable: true, get: function () { return escalation_settings_1.getPushEscalationSettings; } });
+Object.defineProperty(exports, "setPushEscalationSettings", { enumerable: true, get: function () { return escalation_settings_1.setPushEscalationSettings; } });
+Object.defineProperty(exports, "normalizeEscalationSettings", { enumerable: true, get: function () { return escalation_settings_1.normalizeEscalationSettings; } });
+Object.defineProperty(exports, "DEFAULT_ESCALATION_SETTINGS", { enumerable: true, get: function () { return escalation_settings_1.DEFAULT_ESCALATION_SETTINGS; } });
+Object.defineProperty(exports, "ESCALATION_THRESHOLD_CHOICES", { enumerable: true, get: function () { return escalation_settings_1.ESCALATION_THRESHOLD_CHOICES; } });
+Object.defineProperty(exports, "ESCALATION_SETTINGS_KEY", { enumerable: true, get: function () { return escalation_settings_1.ESCALATION_SETTINGS_KEY; } });
+Object.defineProperty(exports, "MIN_ESCALATION_THRESHOLD_MINUTES", { enumerable: true, get: function () { return escalation_settings_1.MIN_ESCALATION_THRESHOLD_MINUTES; } });
+Object.defineProperty(exports, "MAX_ESCALATION_THRESHOLD_MINUTES", { enumerable: true, get: function () { return escalation_settings_1.MAX_ESCALATION_THRESHOLD_MINUTES; } });

package/dist/server/src/lib/push/notification-dedup.js

@@ -15,6 +15,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_DEDUP_WINDOW_MS = void 0;
 exports.shouldSendNotification = shouldSendNotification;
 exports.resetNotificationDedup = resetNotificationDedup;
+exports.shouldSendWaitingPush = shouldSendWaitingPush;
+exports.resetWaitingPushDedup = resetWaitingPushDedup;
 const crypto_1 = require("crypto");
 /** Default suppression window: repeats of identical content within this are dropped. */
 exports.DEFAULT_DEDUP_WINDOW_MS = 30_000;
@@ -40,3 +42,36 @@ function shouldSendNotification(event, now = Date.now(), windowMs = exports.DEFA
 function resetNotificationDedup() {
     lastSent.clear();
 }
+const waitingSent = globalThis.__waitingPushDedup ??
+    (globalThis.__waitingPushDedup = new Map());
+/**
+ * Whether this waiting notification should be sent, recording it if so.
+ *
+ * Replaces the content hash for the waiting path (Issue #1790). Content was
+ * never the right key here: two identical `Do you want to proceed?` prompts
+ * seconds apart are two separate waits a human has to answer twice, and the
+ * 30 s window dropped the second one — while a single wait that outlives the
+ * window could be notified again for the same question. The episode's `since`
+ * is the wait's identity, so "one notification per wait" becomes exact:
+ *
+ *  - first notification of an episode → sent, recorded;
+ *  - any repeat for the same `since` → suppressed, however it arrived (the
+ *    poller and the edge listener both report the same wait);
+ *  - the escalation → allowed exactly once per episode;
+ *  - a new episode (the wait ended and another began) → sent again, even if the
+ *    prompt text and the elapsed time are identical.
+ */
+function shouldSendWaitingPush(event) {
+    const key = `${event.worktreeId}::${event.instanceId}`;
+    const escalated = event.escalated === true;
+    const prev = waitingSent.get(key);
+    if (prev && prev.since === event.since && (prev.escalated || !escalated)) {
+        return false;
+    }
+    waitingSent.set(key, { since: event.since, escalated });
+    return true;
+}
+/** Clear the episode-scoped state (for tests). */
+function resetWaitingPushDedup() {
+    waitingSent.clear();
+}

package/dist/server/src/lib/push/push-sender.js

@@ -64,6 +64,36 @@ function buildExcerpt(text, maxLength = MAX_EXCERPT_LENGTH) {
         return collapsed;
     return collapsed.slice(0, maxLength - 1).trimEnd() + '…';
 }
+/**
+ * Whether this wait can only be dealt with at the terminal (Issue #1790).
+ *
+ * A `menu` (selection list / pager) and an `unclassified` wait share the one
+ * fact the reader acts on: tapping the notification will not present anything
+ * to answer. `prompt` — and an absent kind, which is every pre-#1790 caller —
+ * keeps the original "waiting for your reply" wording.
+ */
+function needsTerminal(waitingKind) {
+    return waitingKind === 'menu' || waitingKind === 'unclassified';
+}
+/** The body for a waiting notification, in the reader's language. */
+function buildWaitingBody(event, messages, excerpt, now) {
+    const terminal = needsTerminal(event.waitingKind);
+    if (event.escalated) {
+        // The excerpt is dropped on purpose: after ten minutes the question is no
+        // longer news, the elapsed time is.
+        const elapsedMs = now - (event.waitingSince ?? now);
+        const minutes = String(Math.max(1, Math.floor(elapsedMs / 60_000)));
+        return (terminal ? messages.stillWaitingTerminal : messages.stillWaitingPrompt).replace('{minutes}', minutes);
+    }
+    if (terminal) {
+        return excerpt
+            ? messages.terminalAttentionWithExcerpt.replace('{excerpt}', excerpt)
+            : messages.terminalAttention;
+    }
+    return excerpt
+        ? messages.promptWaitingWithExcerpt.replace('{excerpt}', excerpt)
+        : messages.promptWaiting;
+}
 /** Build the minimal notification payload for an event, in the reader's language. */
 function buildPushPayload(event, locale = i18n_config_1.DEFAULT_LOCALE, now = Date.now()) {
     const excerpt = buildExcerpt(event.excerpt);
@@ -71,9 +101,7 @@ function buildPushPayload(event, locale = i18n_config_1.DEFAULT_LOCALE, now = Da
     const title = `${event.worktreeName}${agentSuffix}`;
     const messages = PUSH_MESSAGES[resolvePushLocale(locale)];
     const body = event.kind === 'prompt'
-        ? excerpt
-            ? messages.promptWaitingWithExcerpt.replace('{excerpt}', excerpt)
-            : messages.promptWaiting
+        ? buildWaitingBody(event, messages, excerpt, now)
         : excerpt
             ? messages.completionWithExcerpt.replace('{excerpt}', excerpt)
             : messages.completion;
@@ -83,8 +111,12 @@ function buildPushPayload(event, locale = i18n_config_1.DEFAULT_LOCALE, now = Da
         body,
         worktreeId: event.worktreeId,
         url: `/worktrees/${event.worktreeId}`,
+        // Unchanged by #1790, and deliberately: the escalation carries the same tag
+        // as the notification it follows up, so the Service Worker replaces the
+        // stale one instead of stacking a second card for the same wait.
         tag: `${event.worktreeId}:${event.kind}`,
         timestamp: now,
+        ...(event.waitingKind ? { waitingKind: event.waitingKind } : {}),
     };
 }
 async function sendToOne(sub, payload) {
@@ -102,19 +134,46 @@ async function sendToOne(sub, payload) {
         logger.warn('push-send-failed', { statusCode: statusCode ?? 'unknown' });
     }
 }
+/**
+ * Which guard applies to this event (Issue #1790).
+ *
+ * An episode-scoped waiting notification is deduped by the wait it belongs to;
+ * everything else — every completion, and any prompt event that predates the
+ * episode store — keeps the content hash and its 30 s window. Both record as
+ * they decide, so this must be called exactly once per event.
+ */
+function passesDedup(event) {
+    if (event.kind === 'prompt' && typeof event.waitingSince === 'number') {
+        return (0, notification_dedup_1.shouldSendWaitingPush)({
+            worktreeId: event.worktreeId,
+            instanceId: event.instanceId ?? event.agentName ?? '',
+            since: event.waitingSince,
+            escalated: event.escalated,
+        });
+    }
+    return (0, notification_dedup_1.shouldSendNotification)({
+        worktreeId: event.worktreeId,
+        kind: event.kind,
+        content: event.excerpt,
+    });
+}
 /**
  * Fan out a notification to all subscriptions opted into this event's kind.
  * Never throws — push is advisory and must not disrupt the poller. No-op when
  * push is unconfigured, deduped, or there are no matching subscriptions.
+ *
+ * `now` is injectable because the escalation body quotes how long the wait has
+ * lasted (Issue #1790): the reminder is raised from a periodic check that knows
+ * the tick's time, and reading the clock again here would report a different
+ * elapsed time from the one that decided to send.
  */
-async function notifyPushSubscribers(event) {
+async function notifyPushSubscribers(event, now = Date.now()) {
     try {
         const config = (0, vapid_1.getVapidConfig)();
         if (!config)
             return;
-        if (!(0, notification_dedup_1.shouldSendNotification)({ worktreeId: event.worktreeId, kind: event.kind, content: event.excerpt })) {
+        if (!passesDedup(event))
             return;
-        }
         const db = (0, db_instance_1.getDbInstance)();
         const subscriptions = (0, push_subscriptions_db_1.getPushSubscriptionsForKind)(db, event.kind);
         if (subscriptions.length === 0)
@@ -132,7 +191,7 @@ async function notifyPushSubscribers(event) {
                 byLocale.set(locale, [sub]);
         }
         await Promise.all(Array.from(byLocale, ([locale, subs]) => {
-            const payload = JSON.stringify(buildPushPayload(event, locale));
+            const payload = JSON.stringify(buildPushPayload(event, locale, now));
             return Promise.all(subs.map((sub) => sendToOne(sub, payload)));
         }));
     }

package/dist/server/src/lib/push/waiting-push-notifier.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * Send a push notification when an agent starts waiting, and one reminder if it
+ * is still waiting later (Issue #1790).
+ *
+ * ## Why this subscribes rather than detects
+ *
+ * The prompt notification used to be raised from one line inside the response
+ * poller, which made it inherit every one of that poller's boundaries: it only
+ * runs when a send-family API or Auto-Yes started it, it stops itself on the
+ * first prompt of a turn, it gives up after `MAX_POLLING_DURATION`, and it can
+ * only see waits the screen scraper classified as `isPrompt`. A wait that began
+ * after a `tmux` keystroke, a second prompt in the same turn, a wait that only
+ * the agent's own hook events reported, and a selection list were all silently
+ * unnotifiable.
+ *
+ * #1786 made the waiting edge observable exactly once, in
+ * `waiting-episode-state`, and #1788 already subscribes to it for the WebSocket
+ * frame. This module is the same subscription for push — it captures no pane,
+ * runs no detector, and keeps no "was it waiting last time?" of its own.
+ *
+ * ## The poller still notifies, and that is deliberate
+ *
+ * Contrary to the Issue's premise, the edge is *not* observed by a background
+ * process: `observeWaitingEdge`'s only caller is `worktree-status-helper`, on
+ * the worktree list / detail API probe. So the edge fires when a client is
+ * looking, and moving push onto it *alone* would have swapped one blind spot
+ * (no poller) for a worse one (nobody has the app open — the very situation a
+ * phone notification is for). The poller therefore keeps its call, and
+ * `response-checker` opens the same episode through `observeWaitingEdge` so both
+ * producers name the wait identically; `shouldSendWaitingPush` then collapses
+ * them to one notification. See the commit message for the measurement.
+ *
+ * ## Escalation
+ *
+ * There is no existing server-side sweep over waiting sessions to ride on, so
+ * this keeps a small interval of its own. It exists only while some wait is
+ * outstanding — created on the first open episode, cleared when the last one
+ * closes — so an install with nothing waiting has no timer, and one that never
+ * configured VAPID never even gets that far.
+ *
+ * Everything here is advisory: a failure must not disturb the status read that
+ * observed the edge (`emit` contains listener throws) nor the poller.
+ *
+ * @module lib/push/waiting-push-notifier
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ESCALATION_TICK_MS = void 0;
+exports.handleWaitingTransition = handleWaitingTransition;
+exports.runEscalationTick = runEscalationTick;
+exports.startWaitingPushNotifier = startWaitingPushNotifier;
+exports.stopWaitingPushNotifier = stopWaitingPushNotifier;
+exports.isWaitingPushNotifierActive = isWaitingPushNotifierActive;
+exports.pendingEscalationCount = pendingEscalationCount;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const db_instance_1 = require("../../lib/db/db-instance");
+const worktree_db_1 = require("../../lib/db/worktree-db");
+const logger_1 = require("../../lib/logger");
+const waiting_episode_state_1 = require("../../lib/session/waiting-episode-state");
+const escalation_settings_1 = require("./escalation-settings");
+const push_sender_1 = require("./push-sender");
+const vapid_1 = require("./vapid");
+const logger = (0, logger_1.createLogger)('push/waiting-notifier');
+/** How often outstanding waits are re-checked. Minute granularity is enough. */
+exports.ESCALATION_TICK_MS = 60_000;
+const pending = globalThis.__waitingPushPending ??
+    (globalThis.__waitingPushPending = new Map());
+/**
+ * The worktree's display name, for the notification title.
+ *
+ * Falls back to the id rather than dropping the notification: a database that
+ * cannot answer is a reason to send a less readable title, not a reason to
+ * leave the user waiting in silence.
+ */
+function resolveWorktreeName(worktreeId) {
+    try {
+        return (0, worktree_db_1.getWorktreeById)((0, db_instance_1.getDbInstance)(), worktreeId)?.name ?? worktreeId;
+    }
+    catch {
+        return worktreeId;
+    }
+}
+/** Fan one waiting notification out. Never throws. */
+async function sendWaitingPush(wait, escalated, now) {
+    const instanceId = wait.instanceId ?? wait.cliToolId;
+    try {
+        await (0, push_sender_1.notifyPushSubscribers)({
+            worktreeId: wait.worktreeId,
+            worktreeName: resolveWorktreeName(wait.worktreeId),
+            kind: 'prompt',
+            agentName: instanceId,
+            instanceId,
+            waitingKind: wait.kind,
+            waitingSince: wait.since,
+            escalated,
+        }, 
+        // The deciding tick's clock, not a fresh reading: the reminder's body
+        // quotes the elapsed time this call was made on.
+        now);
+    }
+    catch (error) {
+        logger.warn('waiting-push-failed', {
+            worktreeId: wait.worktreeId,
+            instanceId,
+            escalated,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function startEscalationTimer() {
+    if (globalThis.__waitingPushEscalationTimer !== undefined)
+        return;
+    const timer = setInterval(() => {
+        runEscalationTick();
+    }, exports.ESCALATION_TICK_MS);
+    // Never hold the process open for a reminder; the server exiting is a far
+    // stronger signal than "someone might still be waiting".
+    timer.unref?.();
+    globalThis.__waitingPushEscalationTimer = timer;
+}
+function stopEscalationTimerIfIdle() {
+    if (pending.size > 0)
+        return;
+    const timer = globalThis.__waitingPushEscalationTimer;
+    if (timer !== undefined) {
+        clearInterval(timer);
+        globalThis.__waitingPushEscalationTimer = undefined;
+    }
+}
+/**
+ * Handle one crossing of the waiting edge.
+ *
+ * Exported for tests, which drive it directly rather than through the
+ * subscription so a failure points at this function and not at #1786's store.
+ */
+function handleWaitingTransition(transition) {
+    // Nothing downstream can do anything without VAPID keys, so an install
+    // without push does not track waits, does not read the database and does not
+    // start a timer — it is inert rather than merely quiet.
+    if (!(0, vapid_1.isPushConfigured)())
+        return;
+    const key = (0, auto_yes_state_1.buildCompositeKey)(transition.worktreeId, transition.cliToolId, transition.instanceId);
+    if (!transition.waiting || transition.since === null) {
+        pending.delete(key);
+        stopEscalationTimerIfIdle();
+        return;
+    }
+    const wait = {
+        worktreeId: transition.worktreeId,
+        cliToolId: transition.cliToolId,
+        instanceId: transition.instanceId,
+        since: transition.since,
+        kind: transition.kind,
+    };
+    pending.set(key, wait);
+    startEscalationTimer();
+    void sendWaitingPush(wait, false, transition.at);
+}
+/**
+ * Re-notify every wait that has outlived the threshold, once each.
+ *
+ * Exported so tests can advance a fake clock instead of a real minute.
+ */
+function runEscalationTick(now = Date.now()) {
+    if (pending.size === 0) {
+        stopEscalationTimerIfIdle();
+        return;
+    }
+    const settings = (0, escalation_settings_1.getPushEscalationSettings)();
+    const thresholdMs = settings.thresholdMinutes * 60_000;
+    for (const [key, wait] of Array.from(pending)) {
+        // The episode store, not this map, is the authority on whether the wait is
+        // still going: it is written by the status probe, so an answer given in
+        // another tab — or a wait whose closing edge this module never saw — is
+        // caught here even when `pending` still lists it.
+        const episode = (0, waiting_episode_state_1.getWaitingEpisode)(wait.worktreeId, wait.cliToolId, wait.instanceId);
+        if (episode === null || episode.since !== wait.since) {
+            pending.delete(key);
+            continue;
+        }
+        if (!settings.enabled)
+            continue;
+        if (now - wait.since < thresholdMs)
+            continue;
+        // Dropped before sending, not after: the reminder is once per episode, and
+        // an in-flight fan-out must not be able to earn a second one.
+        pending.delete(key);
+        void sendWaitingPush({ ...wait, kind: episode.kind ?? wait.kind }, true, now);
+    }
+    stopEscalationTimerIfIdle();
+}
+/**
+ * Subscribe to the waiting edge.
+ *
+ * Idempotent by replacement, like #1788's broadcast: calling it again drops the
+ * previous subscription rather than adding a second one, so a module evaluated
+ * twice cannot double-notify.
+ *
+ * @returns The unsubscribe function (also reachable as
+ *   {@link stopWaitingPushNotifier}).
+ */
+function startWaitingPushNotifier() {
+    stopWaitingPushNotifier();
+    const unsubscribe = (0, waiting_episode_state_1.onWaitingTransition)((transition) => {
+        handleWaitingTransition(transition);
+    });
+    globalThis.__waitingPushUnsubscribe = unsubscribe;
+    return unsubscribe;
+}
+/**
+ * Drop the subscription, the outstanding waits and the timer. Safe when none is
+ * active, and the seam a test uses to leave no interval behind (CI runs the
+ * whole suite in one process).
+ */
+function stopWaitingPushNotifier() {
+    const existing = globalThis.__waitingPushUnsubscribe;
+    if (existing) {
+        existing();
+        globalThis.__waitingPushUnsubscribe = undefined;
+    }
+    pending.clear();
+    stopEscalationTimerIfIdle();
+}
+/** Whether a subscription is currently active. Test seam. */
+function isWaitingPushNotifierActive() {
+    return globalThis.__waitingPushUnsubscribe !== undefined;
+}
+/** How many waits are awaiting their reminder. Test seam. */
+function pendingEscalationCount() {
+    return pending.size;
+}

package/dist/server/src/lib/realtime/waiting-broadcast.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Push the waiting edge to every subscriber of a worktree room (Issue #1788).
+ *
+ * ## Why this file exists rather than a detector
+ *
+ * Issue #1786 made the false→true / true→false crossing observable exactly once,
+ * in `waiting-episode-state`, and handed out `onWaitingTransition` for the
+ * surfaces that need the instant rather than the level. This module is that
+ * subscription and nothing more: it translates a {@link WaitingTransition} into
+ * a {@link SessionStatusEvent} and publishes it. It does not capture a pane, does
+ * not read the structured events, and does not keep a "was it waiting last
+ * time?" of its own — three surfaces each keeping their own answer to that is
+ * precisely what #1786 exists to prevent.
+ *
+ * Because it subscribes to the edge and not to the response poller, a wait that
+ * only the agent's own hook events could see (#1725) broadcasts exactly like one
+ * the screen scraper read, and a wait that lasts twenty minutes broadcasts once.
+ *
+ * ## Why `publish` is injected
+ *
+ * `ws-server` owns the rooms and starts this subscription from
+ * `setupWebSocket`, so importing `broadcast` here would close an import cycle
+ * (ws-server → waiting-broadcast → ws-server). Taking the publisher as an
+ * argument also makes the translation testable without standing up a server.
+ *
+ * ## Authorization
+ *
+ * None is bypassed. The publisher is the room broadcaster, and a socket only
+ * joins a room through the authenticated `subscribe` path (#331/#332): a client
+ * that never subscribed to a worktree still never hears about it.
+ *
+ * @module lib/realtime/waiting-broadcast
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWaitingStatusEvent = buildWaitingStatusEvent;
+exports.startWaitingStatusBroadcast = startWaitingStatusBroadcast;
+exports.stopWaitingStatusBroadcast = stopWaitingStatusBroadcast;
+exports.isWaitingStatusBroadcastActive = isWaitingStatusBroadcastActive;
+const waiting_episode_state_1 = require("../../lib/session/waiting-episode-state");
+/**
+ * Translate a waiting crossing into the frame clients receive.
+ *
+ * `isRunning` is deliberately omitted — see the field's doc on
+ * {@link SessionStatusEvent}. `instance` is normalized to the instance id the
+ * per-instance status map is keyed by (the CLI tool id for the primary), so a
+ * client can look the entry up without re-deriving the convention.
+ */
+function buildWaitingStatusEvent(transition) {
+    return {
+        type: 'session_status_changed',
+        worktreeId: transition.worktreeId,
+        cliTool: transition.cliToolId,
+        instance: transition.instanceId ?? transition.cliToolId,
+        isWaitingForResponse: transition.waiting,
+        waitingKind: transition.kind ?? null,
+        waitingSince: transition.since,
+    };
+}
+/**
+ * Subscribe to the waiting edge and publish it to the worktree's room.
+ *
+ * Idempotent: calling it again replaces the previous subscription rather than
+ * adding a second one, so a re-entered `setupWebSocket` cannot double-send.
+ *
+ * @param publish - Room broadcaster, normally `ws-server`'s internal one.
+ * @returns The unsubscribe function (also reachable as
+ *   {@link stopWaitingStatusBroadcast}).
+ */
+function startWaitingStatusBroadcast(publish) {
+    stopWaitingStatusBroadcast();
+    const unsubscribe = (0, waiting_episode_state_1.onWaitingTransition)((transition) => {
+        publish(transition.worktreeId, buildWaitingStatusEvent(transition));
+    });
+    globalThis.__waitingStatusBroadcastUnsubscribe = unsubscribe;
+    return unsubscribe;
+}
+/**
+ * Drop the subscription, if any. Safe to call when none is active — and called
+ * from `closeWebSocket`, so a suite that stands a server up and tears it down
+ * does not leave a listener pointed at a dead room map.
+ */
+function stopWaitingStatusBroadcast() {
+    const existing = globalThis.__waitingStatusBroadcastUnsubscribe;
+    if (existing) {
+        existing();
+        globalThis.__waitingStatusBroadcastUnsubscribe = undefined;
+    }
+}
+/** Whether a subscription is currently active. Test seam. */
+function isWaitingStatusBroadcastActive() {
+    return globalThis.__waitingStatusBroadcastUnsubscribe !== undefined;
+}