commandmate 0.29.1 → 0.30.0

package/dist/server/src/lib/polling/structured-history-gate.js

@@ -1,32 +1,62 @@
 "use strict";
 /**
- * Whether somebody better-informed is already recording this turn (Issue #2041).
+ * Whether somebody better-informed is already recording this turn (Issue #2041,
+ * extended for Claude Code in #2121, codex in #2197 and antigravity in #2198).
  *
  * The poller's job has always been to be the only writer of conversation
- * history, because for five of the six tools the terminal is the only place the
- * reply exists. opencode is the exception: since #1763 CommandMate holds an SSE
- * connection to the agent's own server, and since this Issue that connection
- * carries the reply's Markdown source. Two writers for one turn would put the
- * same answer in History twice — once as the agent wrote it and once as its TUI
- * drew it — so one of them has to stand down, and it is the one reading the
- * screen.
+ * history, because for most of the six tools the terminal is the only place the
+ * reply exists. Four of them now have a second writer: opencode publishes its
+ * replies over the SSE stream CommandMate subscribes to (#1763/#2041), and
+ * claude, codex and antigravity each keep their own transcript file on disk.
+ * Two writers for one turn would put the same answer in History twice — once as
+ * the agent wrote it and once as its TUI drew it — so one of them has to stand
+ * down, and it is the one reading the screen.
  *
  * ## Why this is a module and not an `if`
  *
  * Two reasons, and the second is the one that matters. The obvious one is that
  * `response-checker` is 1,000 lines with a single tool-agnostic spine, and a
  * `cliToolId === 'opencode' && …` in the middle of the save path is exactly the
- * kind of branch that gets copied to the next tool that grows a server. The
- * real one is the import: `@/lib/hooks/sources/opencode/subscription` reaches
- * the whole opencode client through its module graph, and the poller's tests
- * replace that graph wholesale. One named seam is one thing to stub.
+ * kind of branch that gets copied to the next tool that grows a reader. The real
+ * one is the import: `@/lib/hooks/sources/opencode/subscription` reaches the
+ * whole opencode client through its module graph, and the poller's tests replace
+ * that graph wholesale. One named seam is one thing to stub.
+ *
+ * ## The tool names are gone (Issue #2197)
+ *
+ * Until this Issue the two functions below opened with `if (cliToolId !==
+ * 'opencode')` and `if (cliToolId !== CLAUDE_CLI_TOOL_ID)`, which is the branch
+ * the module comment above says it exists to prevent — the third tool arrived
+ * and the third `!==` was about to be written. What replaces them is a value the
+ * source declares about itself:
+ * `AgentSourceCapabilities.transcriptHistory` (`'pull' | 'push' | null`, see
+ * `lib/hooks/agent-event-types`). A tool with no second writer says `null` and
+ * both questions below answer false for it without naming it — which is what let
+ * #2198 add antigravity by editing its own `source.ts` and this file's reader
+ * table and nothing else, and what leaves gemini and copilot on the scraper
+ * without a line of code mentioning them.
+ *
+ * The word has three values rather than two because the two shapes are asked
+ * *different questions*:
+ *
+ *  - **push** — a subscription is already receiving the reply, so the only thing
+ *    to ask is whether that connection is live
+ *    ({@link isStructuredHistoryWriterLive}).
+ *  - **pull** — there is no connection, only a file, and nothing reads it until
+ *    something asks. So the question is not "is anyone recording?" but "record
+ *    it now, and tell me whether you did"
+ *    ({@link captureStructuredHistoryTurn}). The call has to be here rather than
+ *    in the hook receiver for a reason beyond tidiness: a hook post is answered
+ *    and forgotten, so the only moment CommandMate knows a turn is *finished and
+ *    about to be written* is this one, and doing the handover at the point of
+ *    the write is what makes it impossible for both writers to run.
  *
  * ## What is NOT gated
  *
  * Only the two calls that *record the reply* — the `chat_messages` row and the
  * Markdown conversation log. Prompt rows, Auto-Yes, the waiting-episode edges,
  * push notifications, task events and the session-state cursor all stay on the
- * scraper, because none of them are things the event stream duplicates: a
+ * scraper, because none of them are things the second writer duplicates: a
  * `permission.asked` becomes a pending decision, never a history row, and the
  * push fan-out has no second producer at all. Gating them would trade a
  * duplicated reply for a silent notification, which is the worse failure.
@@ -35,14 +65,61 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isStructuredHistoryWriterLive = isStructuredHistoryWriterLive;
+exports.captureStructuredHistoryTurn = captureStructuredHistoryTurn;
 const logger_1 = require("../../lib/logger");
 const subscription_1 = require("../../lib/hooks/sources/opencode/subscription");
+const history_1 = require("../../lib/hooks/sources/claude/history");
+const history_2 = require("../../lib/hooks/sources/codex/history");
+const history_3 = require("../../lib/hooks/sources/antigravity/history");
+const tool_id_1 = require("../../lib/hooks/sources/claude/tool-id");
+const tool_id_2 = require("../../lib/hooks/sources/codex/tool-id");
+const tool_id_3 = require("../../lib/hooks/sources/antigravity/tool-id");
+const registry_1 = require("../../lib/hooks/sources/registry");
 const logger = (0, logger_1.createLogger)('lib/polling/structured-history-gate');
+/**
+ * Which reader answers for which tool.
+ *
+ * The one place a tool id still appears, and it is a dispatch table rather than
+ * a decision: *whether* to ask is
+ * `AgentSourceCapabilities.transcriptHistory === 'pull'`, and this only says who
+ * to ask. It cannot be folded into the capability itself because #1921 D3
+ * requires every declared capability to be JSON-serialisable — the block is
+ * copied onto the wire in `structuredEvents.source`, so a capability that were a
+ * function would vanish silently on the way out.
+ *
+ * A tool that declares `'pull'` and is missing here is a bug, and a loud one:
+ * {@link captureStructuredHistoryTurn} logs it and falls back to the scraper.
+ */
+const PULL_TRANSCRIPT_READERS = {
+    [tool_id_1.CLAUDE_CLI_TOOL_ID]: (target, capture) => (0, history_1.captureClaudeTranscriptTurn)(target, capture),
+    [tool_id_2.CODEX_CLI_TOOL_ID]: (target, capture) => (0, history_2.captureCodexTranscriptTurn)(target, capture),
+    [tool_id_3.ANTIGRAVITY_CLI_TOOL_ID]: (target, capture) => (0, history_3.captureAntigravityTranscriptTurn)(target, capture),
+};
+/**
+ * What this tool's source says about who records its replies.
+ *
+ * Never throws: a registry that cannot be reached is one that declares nothing,
+ * and nothing means the scraper keeps writing — the safe direction, as
+ * everywhere else in this module.
+ */
+function transcriptHistoryModeOf(cliToolId) {
+    try {
+        return (0, registry_1.getAgentEventSource)(cliToolId).capabilities.transcriptHistory ?? null;
+    }
+    catch (error) {
+        logger.warn('structured-history-capability-unavailable', {
+            cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
 /**
  * Whether the agent's own server is recording this instance's replies.
  *
- * False for every tool but opencode, and false for an opencode instance whose
- * subscription is anything other than `live` — see
+ * False for every tool whose source does not declare `transcriptHistory: 'push'`
+ * — today that is all of them but opencode — and false for an opencode instance
+ * whose subscription is anything other than `live`; see
  * {@link isOpencodeStructuredHistoryLive} for why `lost` counts as "nobody is
  * writing this down" rather than as "somebody will". The fallback direction is
  * the safe one: two writers duplicate a reply, no writer loses it.
@@ -54,9 +131,12 @@ const logger = (0, logger_1.createLogger)('lib/polling/structured-history-gate')
  * @param instanceId - The agent instance; defaults to the primary
  */
 function isStructuredHistoryWriterLive(worktreeId, cliToolId, instanceId) {
-    if (cliToolId !== 'opencode')
+    if (transcriptHistoryModeOf(cliToolId) !== 'push')
         return false;
     try {
+        // One probe, because there is one push source. A second one adds a table
+        // here of the shape `PULL_TRANSCRIPT_READERS` already has; it does not add
+        // another `cliToolId ===`.
         return (0, subscription_1.isOpencodeStructuredHistoryLive)({
             worktreeId,
             cliToolId,
@@ -73,3 +153,54 @@ function isStructuredHistoryWriterLive(worktreeId, cliToolId, instanceId) {
         return false;
     }
 }
+/**
+ * Ask the pull-mode structured writer to record this turn now (#2121, #2197).
+ *
+ * The file-backed half of the stand-down. Returns true when `chat_messages`
+ * holds this turn as the agent's own Markdown — because this call wrote it, or
+ * because an earlier poll of the same finished turn already did — and the caller
+ * must therefore drop the scraped copy.
+ *
+ * False for every tool that does not declare `transcriptHistory: 'pull'`, and
+ * false for one that does whenever anything at all prevented the write: no
+ * session pointer (a pane started without hooks, or with hooks codex has not
+ * been told to trust), no transcript file, an unreadable one, a window with no
+ * prompt in it, or a turn the agent has not finished writing. That is the
+ * fail-open every one of these Issues' acceptance criteria asks for in as many
+ * words — 転写ファイルが無い / 読めない場合は従来のスクレイプ経路にフォール
+ * バックする. Two writers duplicate a reply; no writer loses one.
+ *
+ * Never throws, for the same reason {@link isStructuredHistoryWriterLive} does
+ * not: this runs inside the poller's save path, and an exception here would cost
+ * the scraped reply as well as the structured one.
+ *
+ * @param worktreeId - The worktree
+ * @param cliToolId - The tool driving the pane
+ * @param instanceId - The agent instance; defaults to the primary
+ * @param capture - Where to look; see {@link StructuredHistoryCapture}
+ */
+async function captureStructuredHistoryTurn(worktreeId, cliToolId, instanceId, capture) {
+    if (transcriptHistoryModeOf(cliToolId) !== 'pull')
+        return false;
+    const reader = PULL_TRANSCRIPT_READERS[cliToolId];
+    if (!reader) {
+        logger.warn('structured-history-reader-missing', {
+            worktreeId,
+            cliToolId,
+            instanceId: instanceId ?? cliToolId,
+        });
+        return false;
+    }
+    try {
+        return await reader({ worktreeId, cliToolId, instanceId: instanceId ?? cliToolId }, capture);
+    }
+    catch (error) {
+        logger.warn('structured-history-capture-unavailable', {
+            worktreeId,
+            cliToolId,
+            instanceId: instanceId ?? cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}

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

@@ -317,9 +317,29 @@ async function notifyPushSubscribers(event, now = Date.now()) {
         // from one that was never attempted — `push-send-failed` is per device and
         // sits below the default log level's attention, and success said nothing at
         // all. One line per fan-out names both halves, and no endpoint.
+        //
+        // Issue #2133: it also names *whose* fan-out it was. Without the subject,
+        // two worktrees notifying in the same second print two identical lines, so
+        // the UAT steps that pass by counting zero notifications
+        // (`docs/qa/2001-cross-device-dismissal-uat.md` T-4 / T-6 / T-7) read a
+        // neighbour's push as their own — which is what the Epic #2002 run hit on
+        // 2026-08-29, and only the co-timed `resolution-push-sent` (which does carry
+        // `worktreeId`) rescued the reading. A waiting push has no such partner.
+        //
+        // The key names match `resolution-push-notifier`'s context on purpose, so
+        // both halves of one episode grep together. `instanceId` resolves exactly as
+        // the episode dedup key above does, and is left absent — `JSON.stringify`
+        // drops `undefined` — rather than logged as an empty string when no producer
+        // named an instance.
         const delivered = outcomes.filter(Boolean).length;
         const failed = outcomes.length - delivered;
-        logger.info('push-fanout-complete', { kind: event.kind, delivered, failed });
+        logger.info('push-fanout-complete', {
+            kind: event.kind,
+            worktreeId: event.worktreeId,
+            instanceId: event.instanceId ?? event.agentName,
+            delivered,
+            failed,
+        });
     }
     catch (err) {
         logger.warn('push-fanout-error', {

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

@@ -39,19 +39,31 @@
  * closes — so an install with nothing waiting has no timer, and one that never
  * configured VAPID never even gets that far.
  *
+ * ## Holding a wait that has not named itself
+ *
+ * The edge fires once, and for a dialog drawn between two probes it fires
+ * before anything on the pane can be classified — so #2156's `AskUserQuestion`
+ * arrived here as `unclassified` and was announced as "check the terminal"
+ * although the app could answer it. The kind is refreshed in place afterwards
+ * and that refresh is deliberately not an edge, so the fix is on this side:
+ * an unnamed wait is held for {@link CLASSIFICATION_GRACE_MS} and then sent
+ * under whatever the episode is called at that point. One notification either
+ * way — no correction push, and nothing at all if the wait ended meanwhile.
+ *
  * 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.CLASSIFICATION_GRACE_MS = exports.ESCALATION_TICK_MS = void 0;
 exports.handleWaitingTransition = handleWaitingTransition;
 exports.runEscalationTick = runEscalationTick;
 exports.startWaitingPushNotifier = startWaitingPushNotifier;
 exports.stopWaitingPushNotifier = stopWaitingPushNotifier;
 exports.isWaitingPushNotifierActive = isWaitingPushNotifierActive;
 exports.pendingEscalationCount = pendingEscalationCount;
+exports.heldWaitCount = heldWaitCount;
 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");
@@ -65,8 +77,33 @@ 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;
+/**
+ * How long a wait that has not named itself yet is held before it notifies
+ * (Issue #2156).
+ *
+ * `AskUserQuestion` opens the episode before the pane carries anything the
+ * screen scraper can read, so the *first* classification of that wait is
+ * `unclassified` and the body would say "check the terminal" about a dialog the
+ * app can answer. `waiting-episode-state` refreshes the kind in place on the
+ * next probe and deliberately emits nothing for it (a wait that changes
+ * character is still one wait), so the notifier only ever saw the provisional
+ * verdict.
+ *
+ * Measured on the session in the Issue: the edge opened at 00:08:38.837 with no
+ * usable classification and the next status probe refined it to `prompt` at
+ * 00:08:44.863 — 6.03 s later; 8 s is that measurement plus one probe's jitter
+ * and nothing more, because the hold is silence on the phone and it is meant to
+ * buy exactly one reclassification.
+ *
+ * Only an unnamed wait pays it: `prompt` and `menu` are positive verdicts and
+ * still notify on the edge itself.
+ */
+exports.CLASSIFICATION_GRACE_MS = 8_000;
 const pending = globalThis.__waitingPushPending ??
     (globalThis.__waitingPushPending = new Map());
+/** Composite key -> the timer holding that wait's first notification (#2156). */
+const graceTimers = globalThis.__waitingPushGraceTimers ??
+    (globalThis.__waitingPushGraceTimers = new Map());
 /**
  * The worktree's display name, for the notification title.
  *
@@ -109,6 +146,73 @@ async function sendWaitingPush(wait, escalated, now) {
         });
     }
 }
+/**
+ * Whether this classification is still provisional (Issue #2156).
+ *
+ * `unclassified` is what `deriveWaitingKind` returns for a frame the scraper
+ * could not read at all, and a null kind is the same admission from a producer
+ * that passed none — both mean "waiting, but nobody has said what for" and both
+ * are the verdict that arrives first when a dialog is drawn between two probes.
+ * `prompt` and `menu` are positive readings of the pane and are taken at once.
+ */
+function isUnnamedWait(kind) {
+    return kind === null || kind === undefined || kind === 'unclassified';
+}
+/** Drop the hold on this wait without sending anything. */
+function cancelGrace(key) {
+    const timer = graceTimers.get(key);
+    if (timer === undefined)
+        return;
+    clearTimeout(timer);
+    graceTimers.delete(key);
+}
+/**
+ * The Auto-Yes gate, then the fan-out.
+ *
+ * In that order because `shouldSendWaitingPush` records the episode at the
+ * moment it decides to send, so a notification dropped after the fan-out began
+ * would still consume the episode's one slot — see `prompt-push-gate`.
+ */
+function gateAndSend(wait, now) {
+    if ((0, prompt_push_gate_1.isPromptPushSuppressed)({
+        worktreeId: wait.worktreeId,
+        cliToolId: wait.cliToolId,
+        instanceId: wait.instanceId,
+        waitingSince: wait.since,
+    })) {
+        return;
+    }
+    void sendWaitingPush(wait, false, now);
+}
+/**
+ * The grace elapsed: send the held wait with whatever it is called *now*
+ * (Issue #2156).
+ *
+ * The episode store is the authority here for the same reason it is in
+ * {@link runEscalationTick}: it carries the classification every later probe
+ * refined, and its absence is the wait having ended. Nothing is sent in that
+ * case — a wait answered inside the grace never needed a notification, and
+ * dropping it is the direction #1999/#2000 asked for rather than a correction
+ * push chasing one that was already wrong.
+ */
+function releaseHeldWait(key) {
+    graceTimers.delete(key);
+    const held = pending.get(key);
+    // Gone means the closing edge dropped it, or a reminder already claimed it.
+    if (held === undefined)
+        return;
+    const episode = (0, waiting_episode_state_1.getWaitingEpisode)(held.worktreeId, held.cliToolId, held.instanceId);
+    if (episode === null || episode.since !== held.since) {
+        pending.delete(key);
+        stopEscalationTimerIfIdle();
+        return;
+    }
+    // Written back so the reminder quotes the settled kind even if the episode is
+    // gone by the time it runs.
+    const settled = { ...held, kind: episode.kind };
+    pending.set(key, settled);
+    gateAndSend(settled, Date.now());
+}
 function startEscalationTimer() {
     if (globalThis.__waitingPushEscalationTimer !== undefined)
         return;
@@ -143,6 +247,8 @@ function handleWaitingTransition(transition) {
         return;
     const key = (0, auto_yes_state_1.buildCompositeKey)(transition.worktreeId, transition.cliToolId, transition.instanceId);
     if (!transition.waiting || transition.since === null) {
+        // Issue #2156: a wait still inside its grace is answered, not notified.
+        cancelGrace(key);
         pending.delete(key);
         stopEscalationTimerIfIdle();
         // Issue #2001: this is the moment the notification on every *other* device
@@ -180,15 +286,20 @@ function handleWaitingTransition(transition) {
     // episode at the moment it decides to send.
     pending.set(key, wait);
     startEscalationTimer();
-    if ((0, prompt_push_gate_1.isPromptPushSuppressed)({
-        worktreeId: wait.worktreeId,
-        cliToolId: wait.cliToolId,
-        instanceId: wait.instanceId,
-        waitingSince: wait.since,
-    })) {
+    // Issue #2156: a wait nobody has named yet is held for one probe interval so
+    // it can notify under the kind it turns out to be, rather than under the
+    // placeholder it opened with. A named wait notifies on the edge, as before.
+    if (isUnnamedWait(wait.kind)) {
+        cancelGrace(key);
+        const timer = setTimeout(() => {
+            releaseHeldWait(key);
+        }, exports.CLASSIFICATION_GRACE_MS);
+        // Same reasoning as the escalation interval: never hold the process open.
+        timer.unref?.();
+        graceTimers.set(key, timer);
         return;
     }
-    void sendWaitingPush(wait, false, transition.at);
+    gateAndSend(wait, transition.at);
 }
 /**
  * Re-notify every wait that has outlived the threshold, once each.
@@ -267,6 +378,9 @@ function stopWaitingPushNotifier() {
         existing();
         globalThis.__waitingPushUnsubscribe = undefined;
     }
+    for (const timer of graceTimers.values())
+        clearTimeout(timer);
+    graceTimers.clear();
     pending.clear();
     stopEscalationTimerIfIdle();
 }
@@ -278,3 +392,7 @@ function isWaitingPushNotifierActive() {
 function pendingEscalationCount() {
     return pending.size;
 }
+/** How many waits are held waiting to be classified (#2156). Test seam. */
+function heldWaitCount() {
+    return graceTimers.size;
+}

package/dist/server/src/lib/realtime/publisher-registry.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Process-local registry naming the one module instance that owns live
+ * WebSocket rooms (Issue #2220).
+ *
+ * ## The failure this exists to close
+ *
+ * `ws-server` keeps `wss`, `clients` and `rooms` in its module scope, and only
+ * the instance the custom server called `setupWebSocket()` on ever holds a
+ * socket. That was believed to be a `next dev` nicety; it is not. A production
+ * build has two graphs, and the build artifacts say so:
+ *
+ * ```
+ * dist/server/server.js          -> require("./src/lib/ws-server")   // owner
+ * .next/server/app/api/**\/route.js -> .next/server/chunks/<n>.js      // a second copy
+ * ```
+ *
+ * `setupWebSocket` appears in the `.next` chunk only as an exported binding —
+ * grep it and the sole hit is the export map, never a call. So the route
+ * bundle's `rooms` is empty for the life of the process, and every
+ * `broadcast()` reached from a route handler returned in silence.
+ *
+ * ## What is shared and what is not
+ *
+ * Only the *capability* crosses the boundary: four functions the owner hands
+ * over. `wss`, the socket set, `clients` and `rooms` stay inside the owner's
+ * module scope, so a route bundle can ask for a frame to be published but can
+ * neither enumerate nor mutate the connection state. Putting the maps
+ * themselves on `globalThis` would work — same process, same `globalThis` — but
+ * it exposes the central state to every bundle and leaves ownership undefined
+ * once two instances have both initialised.
+ *
+ * This is the shape #1788 already uses for the waiting edge
+ * (`waiting-episode-state`'s `globalThis` listener set, written by
+ * `ws-server`'s `setupWebSocket`), and it is measurably cross-bundle in the same
+ * build: `__sessionWaitingTransitionListeners` appears in both `dist/server` and
+ * the `.next` chunks.
+ *
+ * ## Ownership
+ *
+ * Registration is a generation counter that only ever moves forward, and
+ * withdrawal is authorised by the token handed out at registration. A stale
+ * instance calling `closeWebSocket()` after a newer one has taken over
+ * therefore cannot silence the live server — the classic HMR / re-entered
+ * `setupWebSocket` hazard.
+ *
+ * ## Import discipline
+ *
+ * This module must stay a leaf: it imports the logger and nothing else. Both
+ * `ws-server` and every producer reach it, so an edge back into either would
+ * rebuild the module-scope cycle `tests/unit/guards/no-ws-server-manager-cycle-1984.test.ts`
+ * exists to forbid.
+ *
+ * @module lib/realtime/publisher-registry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNROUTED_PUBLISH_WARN_INTERVAL_MS = void 0;
+exports.registerRoomPublisher = registerRoomPublisher;
+exports.unregisterRoomPublisher = unregisterRoomPublisher;
+exports.getRoomPublisher = getRoomPublisher;
+exports.getRoomPublisherGeneration = getRoomPublisherGeneration;
+exports.recordUnroutedPublish = recordUnroutedPublish;
+exports.getUnroutedPublishStats = getUnroutedPublishStats;
+exports.__resetRoomPublisherRegistryForTest = __resetRoomPublisherRegistryForTest;
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('publisher-registry');
+/** At most one warning per minute; the rest are counted, not printed. */
+exports.UNROUTED_PUBLISH_WARN_INTERVAL_MS = 60_000;
+function unroutedState() {
+    return (globalThis.__realtimeUnroutedPublish ??= {
+        total: 0,
+        suppressed: 0,
+        lastWarnedAt: null,
+        operations: {},
+    });
+}
+/**
+ * Claim ownership of the process's rooms.
+ *
+ * Called from `setupWebSocket()` and nowhere else. A second call supersedes the
+ * first rather than being rejected: re-entering `setupWebSocket` builds a new
+ * `WebSocketServer`, and the newest one is the one holding sockets.
+ *
+ * @param publisher - The owner's implementation, closed over its own maps.
+ * @returns A handle whose `unregister()` is honoured only while it is current.
+ */
+function registerRoomPublisher(publisher) {
+    const token = (globalThis.__realtimeRoomPublisherGeneration ?? 0) + 1;
+    globalThis.__realtimeRoomPublisherGeneration = token;
+    globalThis.__realtimeRoomPublisher = { generation: token, publisher };
+    // A live owner means the frames counted below are no longer being dropped;
+    // carrying the old totals forward would keep warning about a fixed process.
+    globalThis.__realtimeUnroutedPublish = undefined;
+    return {
+        token,
+        unregister: () => unregisterRoomPublisher(token),
+    };
+}
+/**
+ * Withdraw the registration identified by `token`.
+ *
+ * A token that is not the current generation is ignored. That is the whole
+ * point: under HMR — or in a suite that stands two servers up — the instance
+ * being torn down is frequently *not* the one that owns the live sockets, and
+ * its `closeWebSocket()` must not take the running server's publisher with it.
+ *
+ * @returns Whether this call actually cleared the registration.
+ */
+function unregisterRoomPublisher(token) {
+    const current = globalThis.__realtimeRoomPublisher;
+    if (!current || current.generation !== token)
+        return false;
+    globalThis.__realtimeRoomPublisher = undefined;
+    return true;
+}
+/** The owner's publisher, or null when no instance has claimed the rooms. */
+function getRoomPublisher() {
+    return globalThis.__realtimeRoomPublisher?.publisher ?? null;
+}
+/** Generation of the current registration; 0 when there is none. */
+function getRoomPublisherGeneration() {
+    return globalThis.__realtimeRoomPublisher?.generation ?? 0;
+}
+/**
+ * Note that a publish found no owner, warning at most once a minute.
+ *
+ * Without this the failure has no symptom at all. The room lookup returns
+ * `undefined`, the function returns, and the browser still shows the socket as
+ * `connected` — because it is: the socket is healthy and only the server-side
+ * publisher is missing. That is the state #2220 sat in unnoticed. The counters
+ * are readable through {@link getUnroutedPublishStats} so a test can assert the
+ * signal exists rather than trusting a log line.
+ *
+ * @param operation - The surface that lost the frame, e.g. `'broadcast'`.
+ * @param worktreeId - Room the frame was addressed to.
+ */
+function recordUnroutedPublish(operation, worktreeId, now = Date.now()) {
+    const state = unroutedState();
+    state.total += 1;
+    state.operations[operation] = (state.operations[operation] ?? 0) + 1;
+    if (state.lastWarnedAt !== null && now - state.lastWarnedAt < exports.UNROUTED_PUBLISH_WARN_INTERVAL_MS) {
+        state.suppressed += 1;
+        return;
+    }
+    const suppressed = state.suppressed;
+    state.suppressed = 0;
+    state.lastWarnedAt = now;
+    logger.warn('realtime:no-room-publisher', {
+        operation,
+        worktreeId,
+        total: state.total,
+        suppressedSinceLastWarning: suppressed,
+        operations: { ...state.operations },
+    });
+}
+/** Read-only view of the unrouted-publish counters. */
+function getUnroutedPublishStats() {
+    const state = unroutedState();
+    return { ...state, operations: { ...state.operations } };
+}
+/**
+ * Drop the registration and the counters.
+ *
+ * Test seam. The generation counter is deliberately NOT reset — a suite that
+ * reset it could hand two different registrations the same token and stop
+ * exercising the ownership rule this module is built around.
+ */
+function __resetRoomPublisherRegistryForTest() {
+    globalThis.__realtimeRoomPublisher = undefined;
+    globalThis.__realtimeUnroutedPublish = undefined;
+}

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

@@ -23,7 +23,8 @@ const logger_1 = require("../../lib/logger");
 const manager_1 = require("../../lib/cli-tools/manager");
 const tmux_capture_cache_1 = require("../../lib/tmux/tmux-capture-cache");
 const logger = (0, logger_1.createLogger)('terminal-broadcast');
-const versionCounters = new Map();
+const versionCounters = globalThis.__terminalSnapshotVersions ??
+    (globalThis.__terminalSnapshotVersions = new Map());
 exports.INTERACTION_SNAPSHOT_RETRY_DELAYS_MS = [100, 250, 500, 750];
 function nextVersion(key) {
     const version = (versionCounters.get(key) ?? 0) + 1;
@@ -54,6 +55,12 @@ function snapshotFingerprint(payload) {
     return JSON.stringify([
         payload.fullOutput ?? '',
         payload.isRunning,
+        // Issue #2240: part of the frame since the snapshot started carrying it, so
+        // a redraw whose only change is the verdict (`waiting` -> `running` on an
+        // answered dialog, say) is still published. Leaving it out would put the
+        // field back in the position this issue took it out of — present on the
+        // wire, but not deliverable by the path that actually feeds a live turn.
+        payload.sessionStatus,
         payload.thinking ?? false,
         payload.isPromptWaiting ?? false,
         payload.isSelectionListActive ?? false,
@@ -76,6 +83,12 @@ function emitTerminalSnapshot(worktreeId, cliToolId, payload, instanceId) {
         instanceId: resolvedInstanceId,
         output: payload.fullOutput ?? '',
         isRunning: payload.isRunning,
+        // Issue #2240: straight through, so push and poll answer the same question
+        // with the same value. `/current-output` returns this very payload, so the
+        // two paths differ only in transport. Not `?? something` — the builder
+        // types it as a required `string` and publishes `'idle'` for a session that
+        // is not running, so there is no absent case to invent a default for.
+        sessionStatus: payload.sessionStatus,
         thinking: payload.thinking ?? false,
         isPromptWaiting: payload.isPromptWaiting ?? false,
         promptData: payload.promptData ?? null,