commandmate 0.31.2 → 0.32.0

package/dist/server/src/lib/realtime/model-change-broadcast.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * What happens when an agent instance changes model (Issue #2357).
+ *
+ * ## The edge, and its three receivers
+ *
+ * `agent-event-state` judges the model edge — the merged hook/frame value moving
+ * from one model to another, with the first sighting, the value going quiet
+ * and a spelling change all ruled out there — and hands it out through
+ * `onAgentModelChange`. This module is that subscription, and it is the ONE
+ * subscription: the three things the Issue asks for on the receiving side are
+ * fanned out from here, in the order that leaves the most durable trace first.
+ *
+ *  1. **The history row.** One assistant row in `chat_messages`, in the
+ *     readers' language, so the chat transcript and the History tab both keep
+ *     "the model changed from A to B" where the conversation is. Written
+ *     first, because it is the receiver that survives a phone being off.
+ *  2. **The room frames.** The row is pushed as a `message` frame — the same
+ *     frame `sendUserMessage` publishes — so a transcript that is open shows
+ *     the line without waiting for its poll; then the `model_changed` frame
+ *     itself, which is what the phone's session row turns amber on.
+ *  3. **The push.** `notifyModelChangePush`, fire-and-forget; it has its own
+ *     dedup and its own logging.
+ *
+ * Each receiver is wrapped separately: a database that cannot be written must
+ * not cost the reader the socket frame, and a socket with no owner must not
+ * cost them the push.
+ *
+ * ## Why `publish` is injected, and who arms this
+ *
+ * The same shape as `waiting-broadcast`, and armed by it: `ws-server` owns the
+ * rooms and calls `startWaitingStatusBroadcast(handleBroadcast)` from
+ * `setupWebSocket`, which is the one place in the process that knows which
+ * bundle's `rooms` a frame has to reach. That call now arms this subscription
+ * too, with the same publisher, and `stopWaitingStatusBroadcast` (from
+ * `closeWebSocket`) disarms both — so the listener's lifetime is the server's,
+ * and a suite that stands a server up and tears it down leaves nothing pointed
+ * at a dead room map.
+ *
+ * ## Authorization
+ *
+ * None is bypassed: the publisher is the room broadcaster, and a socket only
+ * joins a room through the authenticated `subscribe` path.
+ *
+ * @module lib/realtime/model-change-broadcast
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildModelChangedEvent = buildModelChangedEvent;
+exports.handleAgentModelChange = handleAgentModelChange;
+exports.startModelChangeBroadcast = startModelChangeBroadcast;
+exports.stopModelChangeBroadcast = stopModelChangeBroadcast;
+exports.isModelChangeBroadcastActive = isModelChangeBroadcastActive;
+const db_instance_1 = require("../../lib/db/db-instance");
+const chat_db_1 = require("../../lib/db/chat-db");
+const logger_1 = require("../../lib/logger");
+const model_change_push_notifier_1 = require("../../lib/push/model-change-push-notifier");
+const types_1 = require("../../lib/realtime/types");
+const agent_event_state_1 = require("../../lib/session/agent-event-state");
+const logger = (0, logger_1.createLogger)('model-change-broadcast');
+/**
+ * Translate a model edge into the frame clients receive.
+ *
+ * Field for field the producer's record; `instance` is already resolved there
+ * (`instanceId ?? cliToolId`), so a client can match it against its own pane
+ * without re-deriving the convention.
+ */
+function buildModelChangedEvent(change) {
+    return {
+        type: types_1.MODEL_CHANGED_EVENT_TYPE,
+        worktreeId: change.worktreeId,
+        cliTool: change.cliToolId,
+        instance: change.instanceId,
+        from: change.from,
+        to: change.to,
+        source: change.source,
+        at: change.at,
+    };
+}
+/**
+ * Write the history row and hand back the `message` frame for it, or null
+ * when the database could not take it.
+ *
+ * Never throws. The sentence is localized once, for the readers' registered
+ * language (`resolveReadersLocale`) — a stored row cannot be re-rendered per
+ * viewer the way the push body is.
+ */
+function recordModelChangeHistory(change) {
+    try {
+        const db = (0, db_instance_1.getDbInstance)();
+        const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
+        const message = (0, chat_db_1.createModelChangeMessage)(db, {
+            worktreeId: change.worktreeId,
+            cliToolId: change.cliToolId,
+            instanceId: change.instanceId,
+            content: (0, model_change_push_notifier_1.buildModelChangedSentence)(locale, change.from, change.to),
+            at: change.at,
+        });
+        return { type: 'message', worktreeId: change.worktreeId, message };
+    }
+    catch (error) {
+        logger.warn('model-change-history-failed', {
+            worktreeId: change.worktreeId,
+            instanceId: change.instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+/**
+ * Deliver one edge to all three receivers. Exported so a suite can drive the
+ * fan-out without a live subscription; never throws.
+ */
+function handleAgentModelChange(change, publish) {
+    logger.info('model-changed', {
+        worktreeId: change.worktreeId,
+        cliToolId: change.cliToolId,
+        instanceId: change.instanceId,
+        from: change.from,
+        to: change.to,
+        source: change.source,
+    });
+    const messageFrame = recordModelChangeHistory(change);
+    try {
+        if (messageFrame)
+            publish(change.worktreeId, messageFrame);
+        publish(change.worktreeId, buildModelChangedEvent(change));
+    }
+    catch (error) {
+        logger.warn('model-change-broadcast-failed', {
+            worktreeId: change.worktreeId,
+            instanceId: change.instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    // Fire-and-forget: `notifyModelChangePush` contains its own failures and
+    // logs its own decision, and nothing here has anything to do with the result.
+    void (0, model_change_push_notifier_1.notifyModelChangePush)(change);
+}
+/**
+ * Subscribe to the model edge and fan it out.
+ *
+ * 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 stopModelChangeBroadcast}).
+ */
+function startModelChangeBroadcast(publish) {
+    stopModelChangeBroadcast();
+    const unsubscribe = (0, agent_event_state_1.onAgentModelChange)((change) => {
+        handleAgentModelChange(change, publish);
+    });
+    globalThis.__modelChangeBroadcastUnsubscribe = unsubscribe;
+    return unsubscribe;
+}
+/**
+ * Drop the subscription, if any. Safe to call when none is active — and called
+ * from `stopWaitingStatusBroadcast`, i.e. from `closeWebSocket`.
+ */
+function stopModelChangeBroadcast() {
+    const existing = globalThis.__modelChangeBroadcastUnsubscribe;
+    if (existing) {
+        existing();
+        globalThis.__modelChangeBroadcastUnsubscribe = undefined;
+    }
+}
+/** Whether a subscription is currently active. Test seam. */
+function isModelChangeBroadcastActive() {
+    return globalThis.__modelChangeBroadcastUnsubscribe !== undefined;
+}

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

@@ -65,6 +65,10 @@ function snapshotFingerprint(payload) {
         payload.isPromptWaiting ?? false,
         payload.isSelectionListActive ?? false,
         payload.isPagerActive ?? false,
+        // Issue #2369: in the fingerprint for the same reason `sessionStatus` is —
+        // a redraw whose only change is "the /usage panel closed" has to reach the
+        // client, or the Esc card outlives the panel it dismisses.
+        payload.isDismissablePanelActive ?? false,
         payload.isUnclassifiedActive ?? false,
     ]);
 }
@@ -94,6 +98,7 @@ function emitTerminalSnapshot(worktreeId, cliToolId, payload, instanceId) {
         promptData: payload.promptData ?? null,
         isSelectionListActive: payload.isSelectionListActive ?? false,
         isPagerActive: payload.isPagerActive ?? false,
+        isDismissablePanelActive: payload.isDismissablePanelActive ?? false,
         isUnclassifiedActive: payload.isUnclassifiedActive ?? false,
         version: nextVersion(key),
     });

package/dist/server/src/lib/realtime/types.js

@@ -9,7 +9,7 @@
  * the canonical {@link RealtimeEvent}.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MESSAGES_INVALIDATED_EVENT_TYPE = exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH = exports.CHAT_TURN_PROGRESS_MIN_INTERVAL_MS = exports.CHAT_TURN_PROGRESS_EVENT_TYPE = exports.VERSION_MISMATCH_EVENT_TYPE = exports.CLIENT_VERSION_MESSAGE_TYPE = void 0;
+exports.MODEL_CHANGED_EVENT_TYPE = exports.MESSAGES_INVALIDATED_EVENT_TYPE = exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH = exports.CHAT_TURN_PROGRESS_MIN_INTERVAL_MS = exports.CHAT_TURN_PROGRESS_EVENT_TYPE = exports.VERSION_MISMATCH_EVENT_TYPE = exports.CLIENT_VERSION_MESSAGE_TYPE = void 0;
 exports.isVersionMismatch = isVersionMismatch;
 exports.truncateChatTurnProgressBody = truncateChatTurnProgressBody;
 exports.parseRealtimeEvent = parseRealtimeEvent;
@@ -143,6 +143,24 @@ function truncateChatTurnProgressBody(body, maxLength = exports.MAX_CHAT_TURN_PR
  * an omitted field would simply never match.
  */
 exports.MESSAGES_INVALIDATED_EVENT_TYPE = 'messages_invalidated';
+/**
+ * "This instance is now on a different model" (Issue #2357).
+ *
+ * Emitted once per transition from `agent-event-state`'s model edge, on the
+ * same room broadcast `session_status_changed` rides — so every client that
+ * subscribed to the worktree hears it, and one that never subscribed does not.
+ * It is its own type rather than a field on `session_status_changed` because
+ * the consumers do not overlap: the phone's session row is the only thing that
+ * reacts, and every `session_status_changed` listener would otherwise have to
+ * learn to ignore it.
+ *
+ * `from` and `to` are the resolved values `sessionStatusByInstance[].model`
+ * publishes, verbatim — the client shows them, it does not compare them. The
+ * suppression rules (`null → value`, `value → null`, a first sighting, a
+ * spelling change) are applied by the producer, and there is nothing here for
+ * a client to re-judge.
+ */
+exports.MODEL_CHANGED_EVENT_TYPE = 'model_changed';
 /**
  * Parse a raw WebSocket frame into the inner realtime event.
  *

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

@@ -37,6 +37,8 @@ exports.buildWaitingStatusEvent = buildWaitingStatusEvent;
 exports.startWaitingStatusBroadcast = startWaitingStatusBroadcast;
 exports.stopWaitingStatusBroadcast = stopWaitingStatusBroadcast;
 exports.isWaitingStatusBroadcastActive = isWaitingStatusBroadcastActive;
+const model_change_broadcast_1 = require("../../lib/realtime/model-change-broadcast");
+const relay_triggers_1 = require("../../lib/relay/relay-triggers");
 const waiting_episode_state_1 = require("../../lib/session/waiting-episode-state");
 /**
  * Translate a waiting crossing into the frame clients receive.
@@ -63,6 +65,14 @@ function buildWaitingStatusEvent(transition) {
  * Idempotent: calling it again replaces the previous subscription rather than
  * adding a second one, so a re-entered `setupWebSocket` cannot double-send.
  *
+ * Issue #2357: this is also where the model edge is armed. `setupWebSocket`
+ * calls exactly one function to start the edge → room subscriptions, and it
+ * is this one; the model-change fan-out (`model-change-broadcast`) needs the
+ * same publisher for the same reason the waiting edge does — the closure has
+ * to hold the bundle's own `rooms` — so it is started here with it, and
+ * stopped with it below, rather than growing a second arming call in
+ * `ws-server` for every edge that comes along.
+ *
  * @param publish - Room broadcaster, normally `ws-server`'s internal one.
  * @returns The unsubscribe function (also reachable as
  *   {@link stopWaitingStatusBroadcast}).
@@ -73,12 +83,25 @@ function startWaitingStatusBroadcast(publish) {
         publish(transition.worktreeId, buildWaitingStatusEvent(transition));
     });
     globalThis.__waitingStatusBroadcastUnsubscribe = unsubscribe;
+    (0, model_change_broadcast_1.startModelChangeBroadcast)(publish);
+    // Issue #2377: and the relay subsystem, for the third time and the same
+    // reason. Its two background jobs — "tell the requester their worker stopped
+    // on a dialog" and "expire deadlines / retry deliveries a busy composer
+    // refused" — are the server's lifetime, not a request's, and this is the one
+    // function `setupWebSocket` calls to say the server is up. Unlike the two
+    // above it needs no publisher: a relay's delivery is a message written through
+    // `sendUserMessage`, which broadcasts its own row.
+    (0, relay_triggers_1.startRelayTriggers)();
     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.
+ *
+ * Issue #2357: drops the model edge's subscription with it, for the same reason.
+ * Issue #2377: and the relay triggers, whose interval would otherwise keep
+ * ticking against a database the suite has closed.
  */
 function stopWaitingStatusBroadcast() {
     const existing = globalThis.__waitingStatusBroadcastUnsubscribe;
@@ -86,6 +109,8 @@ function stopWaitingStatusBroadcast() {
         existing();
         globalThis.__waitingStatusBroadcastUnsubscribe = undefined;
     }
+    (0, model_change_broadcast_1.stopModelChangeBroadcast)();
+    (0, relay_triggers_1.stopRelayTriggers)();
 }
 /** Whether a subscription is currently active. Test seam. */
 function isWaitingStatusBroadcastActive() {

package/dist/server/src/lib/relay/relay-delivery.js

@@ -0,0 +1,400 @@
+"use strict";
+/**
+ * Getting B's answer into A's composer (Issue #2377).
+ *
+ * ## Two moments, one path
+ *
+ * Something has to notice that B finished. Two things do, and they are the two
+ * `lib/polling/structured-history-gate`'s header describes:
+ *
+ *  - **Tools with a transcript** (claude, codex, antigravity, command-code, and
+ *    opencode over its stream). Their reader answers `true` only for a turn the
+ *    agent has CLOSED, which is a stronger statement than any amount of quiet,
+ *    so the capture is delivered as soon as it lands. Both triggers of that
+ *    capture — the Stop hook and the poller — reach the same function, which is
+ *    why this module needs one hook and not two.
+ *  - **Tools without one** (copilot, gemini, vibe-local). What a finished turn
+ *    leaves behind is the poller's copy of the SCREEN, judged by a string
+ *    analysis of a frame that may still be being drawn. The Issue asks for
+ *    「完了検知 + 数秒の静穏」, and {@link RELAY_SCRAPE_QUIET_MS} is that quiet:
+ *    the newest row is re-read after the delay and only delivered once it has
+ *    stopped moving.
+ *
+ * ## Deciding is not delivering
+ *
+ * A finished turn produces a STASH, not a send. A is frequently mid-turn when B
+ * finishes, and typing into a running composer interrupts it — so the body waits
+ * in the ledger (durable, survives a restart) and the pump retries it whenever
+ * A is next able to take it. That separation is also what makes the double
+ * detection harmless: `stashRelayPayload` is guarded on `pending_kind IS NULL`,
+ * so two producers finding one turn cost one delivery.
+ *
+ * Nothing here throws. Every entry point is called from a poller tick, a hook
+ * receiver or a timer, and in all three a failure must cost the relay, never the
+ * caller.
+ *
+ * @module lib/relay/relay-delivery
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetRelayDeliveryState = resetRelayDeliveryState;
+exports.findWorkerReply = findWorkerReply;
+exports.notifyRelayTurnCompleted = notifyRelayTurnCompleted;
+exports.notifyRelayPromptWaiting = notifyRelayPromptWaiting;
+exports.sweepExpiredRelays = sweepExpiredRelays;
+exports.pumpRelayDeliveries = pumpRelayDeliveries;
+exports.runRelayMaintenanceTick = runRelayMaintenanceTick;
+const db_instance_1 = require("../../lib/db/db-instance");
+const relay_db_1 = require("../../lib/db/relay-db");
+const chat_db_1 = require("../../lib/db/chat-db");
+const models_1 = require("../../types/models");
+const model_change_push_notifier_1 = require("../../lib/push/model-change-push-notifier");
+const send_user_message_1 = require("../../lib/session/send-user-message");
+const relay_messages_1 = require("../../lib/relay/relay-messages");
+const relay_policy_1 = require("../../lib/relay/relay-policy");
+const relay_readiness_1 = require("../../lib/relay/relay-readiness");
+const relay_session_ref_1 = require("../../lib/relay/relay-session-ref");
+const relay_system_line_1 = require("../../lib/relay/relay-system-line");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('relay-delivery');
+/**
+ * How many assistant rows back the reply is looked for.
+ *
+ * A turn can write several rows (a narration then a summary), and the relay
+ * wants the last one that is actually the agent talking. Bounded because an
+ * unbounded read of a long-lived worktree's history is a large query for one
+ * line of answer.
+ */
+const REPLY_LOOKBACK_MESSAGES = 40;
+/** How many times the scrape path re-reads before it gives up on stability. */
+const SCRAPE_STABILITY_ATTEMPTS = 3;
+const inFlight = (globalThis.__relayDeliveryInFlight ??= new Set());
+/** Forget every in-flight delivery. Test seam. */
+function resetRelayDeliveryState() {
+    inFlight.clear();
+    globalThis.__relayPumpRunning = false;
+}
+function senderLabel(db, relay) {
+    const worker = (0, relay_session_ref_1.resolveRelaySession)(db, relay.to);
+    return { alias: worker.alias, worktreeId: worker.worktreeId };
+}
+/**
+ * The newest thing B actually said, at or after `since`.
+ *
+ * Three kinds of row are stepped over, and each exclusion is load-bearing:
+ * prompt rows (a question is not an answer, and the confirmation notice is a
+ * separate delivery), relay SYSTEM rows (this session's own transcript
+ * furniture — delivering "Reply from X" back to X is the smallest possible
+ * loop), and empty bodies.
+ */
+function findWorkerReply(db, worker, since) {
+    const messages = (0, chat_db_1.getMessages)(db, worker.worktreeId, {
+        limit: REPLY_LOOKBACK_MESSAGES,
+        cliToolId: worker.cliToolId,
+        instanceId: worker.instanceId,
+        matchResolvedInstance: true,
+    });
+    // `getMessages` answers newest-first, so the first candidate IS the newest.
+    for (const message of messages) {
+        if (message.role !== 'assistant')
+            continue;
+        if (message.messageType === 'prompt')
+            continue;
+        if (message.requestId?.startsWith(chat_db_1.RELAY_SYSTEM_REQUEST_ID_PREFIX))
+            continue;
+        if (message.content.trim() === '')
+            continue;
+        return message.timestamp.getTime() < since ? null : message;
+    }
+    return null;
+}
+/** The options of B's open dialog, in the shape the notice lists them. */
+function promptOptionsOf(message) {
+    const data = message.promptData;
+    if (!(0, models_1.isAnswerablePromptData)(data))
+        return [];
+    if (data.type === 'yes_no') {
+        return data.options.map((label) => ({ key: label, label }));
+    }
+    return data.options.map((option) => ({
+        key: String(option.number),
+        label: option.label,
+    }));
+}
+/**
+ * Stash B's finished reply against every relay that is waiting for it.
+ *
+ * @returns How many relays took a payload from this call
+ */
+function stashReplyForOpenRelays(db, worker, now) {
+    const relays = (0, relay_db_1.listOpenRelaysTo)(db, {
+        worktreeId: worker.worktreeId,
+        instanceId: worker.instanceId,
+    });
+    if (relays.length === 0)
+        return 0;
+    let stashed = 0;
+    for (const relay of relays) {
+        // `createdAt` and not "the last time we looked": a reply written BEFORE the
+        // relay existed answered somebody else's question, and delivering it would
+        // hand session A the previous turn — the exact failure a bare `capture`
+        // after a `wait` has always had.
+        const reply = findWorkerReply(db, worker, relay.createdAt);
+        if (!reply)
+            continue;
+        const body = (0, relay_messages_1.buildRelayReplyMessage)(senderLabel(db, relay), reply.content);
+        if ((0, relay_db_1.stashRelayPayload)(db, relay.id, 'reply', body, now))
+            stashed += 1;
+    }
+    return stashed;
+}
+/** Sleep, so the scrape path can wait out its quiet window. */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * B finished a turn. Deliver it, or arrange to.
+ *
+ * @param worker - The session that finished
+ * @param options.settled - True when the completion came from the agent's own
+ *   transcript, i.e. the turn is closed and no quiet window is needed
+ */
+async function notifyRelayTurnCompleted(worker, options) {
+    try {
+        const db = (0, db_instance_1.getDbInstance)();
+        const waiting = (0, relay_db_1.listOpenRelaysTo)(db, {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+        });
+        if (waiting.length === 0)
+            return;
+        if (options.settled) {
+            if (stashReplyForOpenRelays(db, worker, Date.now()) > 0)
+                void pumpRelayDeliveries();
+            return;
+        }
+        // The scrape path. The row that is newest now may be a frame mid-draw, so
+        // the delivery waits until the newest row stops changing — bounded, because
+        // an agent that keeps writing is an agent whose next completion will trigger
+        // this again anyway.
+        let previousId = null;
+        for (let attempt = 0; attempt < SCRAPE_STABILITY_ATTEMPTS; attempt += 1) {
+            const before = findWorkerReply(db, worker, 0);
+            previousId = before?.id ?? null;
+            await sleep(relay_policy_1.RELAY_SCRAPE_QUIET_MS);
+            const after = findWorkerReply(db, worker, 0);
+            if ((after?.id ?? null) === previousId) {
+                if (stashReplyForOpenRelays(db, worker, Date.now()) > 0)
+                    void pumpRelayDeliveries();
+                return;
+            }
+        }
+        logger.info('relay-scrape-never-settled', {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+            attempts: SCRAPE_STABILITY_ATTEMPTS,
+        });
+    }
+    catch (error) {
+        logger.warn('relay-turn-completed-failed', {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * B stopped on a confirmation. Tell A, once per distinct dialog.
+ *
+ * The relay stays OPEN: answering the prompt lets B finish, and the reply is
+ * delivered from the `prompt` state. What changes is that A now knows why
+ * nothing has arrived, which is the whole difference between a delegation that
+ * is slow and one that is stuck.
+ */
+function notifyRelayPromptWaiting(worker) {
+    try {
+        const db = (0, db_instance_1.getDbInstance)();
+        const relays = (0, relay_db_1.listOpenRelaysTo)(db, {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+        });
+        if (relays.length === 0)
+            return;
+        const prompt = (0, chat_db_1.getLatestOpenPromptMessage)(db, worker.worktreeId, worker.cliToolId, worker.instanceId);
+        if (!prompt)
+            return;
+        const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
+        const options = promptOptionsOf(prompt);
+        const question = (0, models_1.isAnswerablePromptData)(prompt.promptData)
+            ? prompt.promptData.question
+            : (prompt.promptData?.question ?? prompt.content);
+        let stashed = 0;
+        for (const relay of relays) {
+            // The dialog's own row id is the signature: a wait that lasts twenty
+            // minutes is ONE row, so A is told once however many polls observe it.
+            if ((0, relay_db_1.getRelayPromptSignature)(db, relay.id) === prompt.id)
+                continue;
+            const body = (0, relay_messages_1.buildRelayPromptMessage)(locale, senderLabel(db, relay), {
+                question,
+                options,
+            });
+            if ((0, relay_db_1.stashRelayPayload)(db, relay.id, 'prompt', body)) {
+                // The signature is recorded HERE, before the delivery, and not after it:
+                // it is what stops every later poll of the same twenty-minute dialog
+                // from stashing the same notice again while A is still busy. The state
+                // moving to `prompt` is an OPEN state, so the reply that follows once
+                // the dialog is answered can still be stashed and delivered.
+                (0, relay_db_1.markRelayPromptNotified)(db, relay.id, prompt.id);
+                stashed += 1;
+            }
+        }
+        if (stashed > 0)
+            void pumpRelayDeliveries();
+    }
+    catch (error) {
+        logger.warn('relay-prompt-notify-failed', {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Close every relay whose deadline has passed, telling A once.
+ *
+ * The stash goes in BEFORE the state changes, because `stashRelayPayload` only
+ * accepts an open relay — and the once-ness the Issue asks for comes from
+ * {@link markRelayExpired} being a guarded update, not from this ordering.
+ */
+function sweepExpiredRelays(db, now = Date.now()) {
+    let expired = 0;
+    for (const relay of (0, relay_db_1.listExpiredOpenRelays)(db, now)) {
+        try {
+            const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
+            // A payload that never went out is superseded by the expiry notice: A
+            // asked for an answer, and what they are getting is the news that there
+            // will not be one.
+            (0, relay_db_1.clearRelayPending)(db, relay.id, now);
+            const body = (0, relay_messages_1.buildRelayExpiredMessage)(locale, senderLabel(db, relay), relay.expiresAt - relay.createdAt);
+            const stashed = (0, relay_db_1.stashRelayPayload)(db, relay.id, 'expired', body, now);
+            if (!(0, relay_db_1.markRelayExpired)(db, relay.id, now)) {
+                if (stashed)
+                    (0, relay_db_1.clearRelayPending)(db, relay.id, now);
+                continue;
+            }
+            expired += 1;
+            (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'expired', (0, relay_session_ref_1.resolveRelaySession)(db, relay.from), (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+        }
+        catch (error) {
+            logger.warn('relay-expire-failed', {
+                relayId: relay.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return expired;
+}
+/**
+ * Try to put one stashed payload into A's composer.
+ *
+ * The order — readiness, then send, then ledger — is deliberate. Marking first
+ * would lose the answer whenever the send failed, and the send path has real
+ * refusals in it (`prompt_waiting`, a session that went away mid-attempt). A
+ * repeat delivery is prevented by the in-flight set within a process and by
+ * `markRelayDelivered`'s guarded update across one, which is the idempotency the
+ * Issue asks for by name.
+ */
+async function deliverOne(db, relayId, kind, body) {
+    const relay = (0, relay_db_1.getRelayById)(db, relayId);
+    if (!relay)
+        return 'skipped';
+    const requester = (0, relay_session_ref_1.resolveRelaySession)(db, relay.from);
+    const hold = await (0, relay_readiness_1.findRelayHoldReason)(requester.worktreeId, requester.cliToolId, requester.instanceId);
+    if (hold) {
+        logger.debug('relay-delivery-held', { relayId, kind, reason: hold });
+        return 'held';
+    }
+    const result = await (0, send_user_message_1.sendUserMessage)(db, {
+        worktreeId: requester.worktreeId,
+        content: body,
+        cliToolId: requester.cliToolId,
+        instanceId: requester.instanceId,
+        messageType: 'relay',
+        // The pointer back at the ledger. Also `session_relays.sent_request_id` for
+        // a reply, which carries a UNIQUE index — so a second delivery of the same
+        // relay cannot be recorded even if one were somehow attempted.
+        requestId: kind === 'reply' ? (0, chat_db_1.relayRequestId)(relay.id) : undefined,
+    });
+    if (!result.ok) {
+        logger.info('relay-delivery-refused', { relayId, kind, stage: result.stage });
+        return result.stage === 'prompt_waiting' ? 'held' : 'failed';
+    }
+    const now = Date.now();
+    if (kind === 'reply') {
+        if (!(0, relay_db_1.markRelayDelivered)(db, relay.id, (0, chat_db_1.relayRequestId)(relay.id), now)) {
+            // Somebody closed it underneath us. The message is already in A's
+            // composer, which is the outcome that mattered.
+            logger.info('relay-already-closed-on-deliver', { relayId });
+        }
+        (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'replied', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+    }
+    else if (kind === 'prompt') {
+        (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'waiting', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+    }
+    (0, relay_db_1.clearRelayPending)(db, relay.id, now);
+    logger.info('relay-delivered', { relayId, kind, to: `${requester.worktreeId}/${requester.instanceId}` });
+    return 'delivered';
+}
+/**
+ * Deliver every stashed payload that can be delivered now.
+ *
+ * Single-flight: a pump already running is the pump, and a second entry — the
+ * timer firing while a first pass awaits a capture — would read the same rows
+ * and race its own sends.
+ */
+async function pumpRelayDeliveries() {
+    if (globalThis.__relayPumpRunning)
+        return;
+    globalThis.__relayPumpRunning = true;
+    try {
+        const db = (0, db_instance_1.getDbInstance)();
+        for (const item of (0, relay_db_1.listRelaysWithPendingPayload)(db)) {
+            if (inFlight.has(item.relay.id))
+                continue;
+            inFlight.add(item.relay.id);
+            try {
+                await deliverOne(db, item.relay.id, item.kind, item.body);
+            }
+            catch (error) {
+                logger.warn('relay-delivery-failed', {
+                    relayId: item.relay.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                inFlight.delete(item.relay.id);
+            }
+        }
+    }
+    catch (error) {
+        logger.warn('relay-pump-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    finally {
+        globalThis.__relayPumpRunning = false;
+    }
+}
+/** One tick of the background loop: sweep the deadlines, then deliver. */
+async function runRelayMaintenanceTick() {
+    try {
+        sweepExpiredRelays((0, db_instance_1.getDbInstance)());
+    }
+    catch (error) {
+        logger.warn('relay-sweep-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    await pumpRelayDeliveries();
+}