commandmate 0.34.1 → 0.36.0

package/dist/server/src/lib/detection/tools/command-code/dialog.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * Command Code's footer-less `AskUserQuestion`, read as an answerable prompt
+ * (Issue #2522).
+ *
+ * ## What Issue #2521 left here
+ *
+ * #2521 taught the status chain to RECOGNISE this screen. It draws a 200-column
+ * rule, a tab strip (`● Dispatch | ◯ Review`), a question and a strict `1.`…`N.`
+ * run with one `❯` on it — and no hint-bar footer at all — and when an option's
+ * description wraps, the continuation row begins with a SINGLE space:
+ *
+ *     ────────────────────────────… (200 columns of U+2500)
+ *     ● Dispatch | ◯ Review
+ *
+ *     Approve proceeding from the plan into worktree creation and dispatch?
+ *
+ *     ❯ 1. Prepare worktrees + dispatch (Recommended)
+ *          I create the worktrees and pause for you to
+ *      answer).
+ *       2. Worktrees only, then pause
+ *     …
+ *
+ * `isContinuationLine` in the shared multiple-choice parser refuses ` answer).`
+ * (one leading space, five characters or more, no path shape), so the generic
+ * reverse scan stops there one row short of option 1, collects `[2,3,4]`, and
+ * rejects the block for not starting at `1`. #2521's answer was a manual-operation
+ * fallback: `waiting` / `COMMAND_CODE_SELECTION_LIST` / `hasActivePrompt: false`,
+ * which stops `wait` exiting 0 and raises a card a human drives with the arrows.
+ *
+ * This module is the other half. It reads the SAME region #2521 recognises
+ * ({@link readCommandCodeQuestionRegion}) and produces the `multiple_choice`
+ * payload that `respond`, the chat surface's answer buttons, the prompt-history
+ * rows, the push notification and Auto-Yes all consume — so a frame this reads
+ * is published as `PROMPT_DETECTED` and the fallback no longer applies to it.
+ *
+ * ## Three states, one reading
+ *
+ * {@link readCommandCodeQuestionDialog} answers a discriminated union rather
+ * than `PromptDetectionResult | null`, because "this is not that screen" and
+ * "this IS that screen and I cannot read it" need opposite handling and a `null`
+ * cannot tell them apart (Issue #2522 確定仕様 B):
+ *
+ * | `kind`        | what it means                              | what the caller does |
+ * |---------------|--------------------------------------------|----------------------|
+ * | `none`        | not Command Code's question screen          | every existing tool-specific / generic path, unchanged |
+ * | `prompt`      | read in full                                | use this prompt; do not let the generic parser overwrite it |
+ * | `unsupported` | the question UI is plainly up, and a gap / a duplicate / an over-tall region / an unreadable option run stopped the reading | #2521's manual-operation fallback. No `promptData`, no auto-answer, and NOT the generic parser's partial list |
+ *
+ * ## Why it is not "call the generic parser, fall back to this"
+ *
+ * Because the generic parser SUCCEEDS on the short spelling of this screen —
+ * one-line descriptions, nothing wrapped — and succeeds badly: `extractQuestionText`
+ * walks up to {@link QUESTION_CONTEXT_LINES} rows above the options and would
+ * take the tab strip, the rule and the transcript's TODOS row into the question.
+ * So this reader runs FIRST wherever it runs at all, and the question it produces
+ * is bounded by the tab row rather than by a row count.
+ *
+ * ## Input contract
+ *
+ * A frame with its BOX DRAWING INTACT — `capture-pane -p -e` output, or that
+ * with ANSI removed. The region is anchored on a pure-U+2500 rule row, and
+ * `stripBoxDrawing` blanks exactly that row, so a `captureAndCleanOutput`
+ * spelling reaches `none` here however plainly the dialog is on screen. That is
+ * the trap #2522 確定仕様 C is written against: the three consumers that clean
+ * their frames (`detectPromptWithOptions`, the Auto-Yes poller, `/prompt-response`)
+ * each keep the RAW capture from the same tick and hand it here, and hand the
+ * cleaned string to everything else. ANSI is stripped internally, per row, off
+ * the same split the region indices address, so either spelling reads alike.
+ *
+ * Pure and side-effect free: no status, no poller, no database, no UI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMAND_CODE_QUESTION_MAX_REGION_ROWS = void 0;
+exports.readCommandCodeQuestionDialog = readCommandCodeQuestionDialog;
+exports.detectCommandCodeQuestionPrompt = detectCommandCodeQuestionPrompt;
+const ansi_1 = require("../../ansi");
+const prompt_detect_multiple_choice_1 = require("../../prompt-detect-multiple-choice");
+const selection_shape_1 = require("../../selection-shape");
+const dialog_block_1 = require("../dialog-block");
+/**
+ * How many rows of dialog this reader will parse.
+ *
+ * 確定仕様 A forbids truncating to the 15-row detection window or the 40-row
+ * selection-shape tail — a wrapped description is exactly what pushes the
+ * question out of those — and equally forbids reporting a PARTIAL list as a
+ * success when a cap is hit. So the cap is stated here, generously, and hitting
+ * it is `unsupported` rather than "the options I managed to see".
+ *
+ * Sixty rows is the tallest this screen can plausibly be (a tab strip, a blank,
+ * a question wrapped over half a dozen rows, and nine options with four rows of
+ * description each) and equals {@link findNumberedOptionBlock}'s own
+ * `MAX_BLOCK_ROWS`, so the two cannot disagree about which one declined: the
+ * region is measured first and the block walk can no longer reach its limit.
+ */
+exports.COMMAND_CODE_QUESTION_MAX_REGION_ROWS = 60;
+/**
+ * How many non-blank rows under the LAST option may be its own description.
+ *
+ * The region ends at the last row carrying content, so the rows
+ * {@link findNumberedOptionBlock} files as `footer` are not chrome — this screen
+ * draws none — they are the wrapped tail of the bottom option, and 確定仕様 A
+ * says a description under the last option folds into it exactly as one under
+ * any other option does. Same trade agy's reader makes for the same reason.
+ */
+const LAST_OPTION_TAIL_ROWS = 12;
+/** The cursor glyph, restated from the region reader's own private constant. */
+const COMMAND_CODE_CURSOR_GLYPH = '❯';
+/**
+ * The cursor row's own option number, for the cross-check below.
+ *
+ * The region reading already proved there is exactly one `❯` in the region and
+ * that it sits on an option row; this recovers WHICH option it is, so the
+ * default can be pinned against {@link findNumberedOptionBlock}'s own answer
+ * instead of trusting a glyph union (`[❯›●>]`) that is wider than this screen's.
+ */
+const CURSOR_OPTION_NUMBER_PATTERN = /❯[^\S\n]*(\d{1,2})[.)]/;
+/**
+ * The one option on this screen that is NOT answerable by its number
+ * (Issue #2522 確定仕様 A / D).
+ *
+ * Command Code draws `4. Type something...` as the last row of the list, and it
+ * is not a fourth choice: the measured `QuestionPrompt` gives the ordinary
+ * choices to a `SelectInput` and renders this one as a separate `TextInput`. It
+ * is kept as a displayed option — a human has to see that the screen offers free
+ * text — and marked `requiresTextInput`, which is what stops `resolveBaseAnswer`
+ * auto-selecting it and what makes the answer UIs open a text field instead of
+ * sending a bare `4`.
+ *
+ * Added to the shared builder's result rather than to `TEXT_INPUT_PATTERNS`,
+ * because that list is the GENERIC one every CLI is read through and 対象外
+ * forbids widening it: `/enter\s+/`-class patterns there already over-match, and
+ * one more entry would change what every other tool's options mean.
+ *
+ * Anchored at the start of the label so the fold-in of a description below the
+ * row (`Type something... Write your own answer.`) still matches.
+ */
+const COMMAND_CODE_FREE_TEXT_OPTION_PATTERN = /^[^\S\n]*type\s+something\b/i;
+/**
+ * A checkbox option — the row shape of a MULTI-select question.
+ *
+ * The same expression `prompt-answer-sender` and `prompt-answer-semantic` use to
+ * recognise one, restated here (both are private to their modules) because this
+ * reader has to DECLINE the screen rather than answer it: 対象外 says Review,
+ * multi-select and free-text screens are not to be pushed through the
+ * single-select parser, and the reason is mechanical. On a checkbox list the
+ * digit TOGGLES a box and the confirm is a separate `Next` row, so a payload
+ * that claimed "option 2 is the answer" would have `respond 2` tick a box and
+ * stop — leaving the question up and the operator told it was answered.
+ *
+ * `unsupported` rather than `none`: the screen IS a live question and the human
+ * has to be sent to the pane for it, which is exactly #2521's fallback.
+ */
+const CHECKBOX_OPTION_PATTERN = /^\[[ x]\]\s/i;
+/**
+ * The same tail limits `prompt-detector.ts` applies to `rawContent`
+ * (`RAW_CONTENT_MAX_LINES` / `RAW_CONTENT_MAX_CHARS`), restated because that
+ * helper is private to it. A prompt row stores this text as its message body.
+ *
+ * In practice neither bound binds here — the region is at most
+ * {@link COMMAND_CODE_QUESTION_MAX_REGION_ROWS} rows — which is the point: what
+ * used to reach these consumers for this screen was the whole 1000-row pane.
+ */
+const RAW_CONTENT_MAX_LINES = 200;
+const RAW_CONTENT_MAX_CHARS = 5000;
+function truncateRawContent(content) {
+    const lines = content.split('\n');
+    const tail = lines.length > RAW_CONTENT_MAX_LINES ? lines.slice(-RAW_CONTENT_MAX_LINES) : lines;
+    const joined = tail.join('\n');
+    return joined.length > RAW_CONTENT_MAX_CHARS ? joined.slice(-RAW_CONTENT_MAX_CHARS) : joined;
+}
+function unsupported(reason) {
+    return { kind: 'unsupported', reason };
+}
+/**
+ * Read Command Code's `AskUserQuestion` off one capture (Issue #2522).
+ *
+ * @param frame - a capture with its box drawing intact (ANSI optional, CRLF
+ *   tolerated). A `stripBoxDrawing`-ed string answers `none`; see the module
+ *   docblock for why that is a contract and not a limitation to work around.
+ */
+function readCommandCodeQuestionDialog(frame) {
+    if (!frame)
+        return { kind: 'none' };
+    // The positive recognition is #2521's, unchanged and not re-derived: the last
+    // qualifying rule row, a tab strip under it, a question, a strict `1.`…`N.`
+    // run and exactly one `❯` on one of its rows, with the pickers and panels the
+    // other branches own excluded. Everything below is READING what it recognised.
+    const region = (0, selection_shape_1.readCommandCodeQuestionRegion)(frame);
+    if (region === null) {
+        // The strict reading declined. Two very different frames arrive here, and
+        // 確定仕様 B needs them told apart: one is any other screen in the world,
+        // the other is THIS screen with a gap in its numbering, a repeated row or a
+        // second cursor. `hasCommandCodeQuestionChrome` is the same structural scan
+        // with the two list-shaped conditions dropped, so it says which — and a
+        // question screen nobody can parse still stops `wait` instead of being
+        // handed back to the composer check that publishes `ready` off its own `❯`.
+        return (0, selection_shape_1.hasCommandCodeQuestionChrome)(frame)
+            ? unsupported('numbering-unreadable')
+            : { kind: 'none' };
+    }
+    const lines = frame.replace(/\r\n/g, '\n').split('\n').map(ansi_1.stripAnsi);
+    const regionRows = lines.slice(region.firstLineIndex, region.lastLineIndex + 1);
+    if (regionRows.length > exports.COMMAND_CODE_QUESTION_MAX_REGION_ROWS) {
+        return unsupported('region-too-tall');
+    }
+    const tabOffset = region.tabLineIndex - region.firstLineIndex;
+    // The shared block reader, on the region alone. Walking UP from the bottom is
+    // what folds a wrapped description into the option ABOVE it — which is the
+    // rule 確定仕様 A states for indent 0, 1 and 2 alike, and the one the generic
+    // parser's `isContinuationLine` could not follow.
+    const block = (0, dialog_block_1.findNumberedOptionBlock)(regionRows, regionRows.length, LAST_OPTION_TAIL_ROWS);
+    if (block === null)
+        return unsupported('option-block-unreadable');
+    const labels = [...block.options];
+    if (block.footer !== '') {
+        // Rows below the bottom option. The region's lower edge is the last row with
+        // content and this screen draws no footer, so they are that option's own
+        // description.
+        const last = labels.length - 1;
+        labels[last] = [labels[last], ...block.footer.split('\n')].join(' ').trim();
+    }
+    if (labels.length !== region.optionCount)
+        return unsupported('option-count-mismatch');
+    if (labels.some((label) => CHECKBOX_OPTION_PATTERN.test(label)))
+        return unsupported('multi-select');
+    // The default. Not `selectedGlyph` alone: `findNumberedOptionBlock`'s glyph
+    // union is `[❯›●>]` because it serves every CLI, and `●` is this screen's TAB
+    // marker — so the answer is cross-checked against the row the region reading
+    // actually found the one `❯` on, and a disagreement declines rather than
+    // guessing which option a human is about to confirm.
+    const cursorRow = regionRows[region.cursorLineIndex - region.firstLineIndex] ?? '';
+    const cursorMatch = CURSOR_OPTION_NUMBER_PATTERN.exec(cursorRow);
+    if (block.selectedIndex < 0 ||
+        block.selectedGlyph !== COMMAND_CODE_CURSOR_GLYPH ||
+        cursorMatch === null ||
+        Number(cursorMatch[1]) !== block.selectedIndex + 1) {
+        return unsupported('default-unresolved');
+    }
+    // The question: everything between the tab strip and option 1, blanks dropped,
+    // wrapped rows joined with ONE space and in draw order. Bounded by the tab row
+    // rather than by a row count, so neither the rule, the TODOS row above it nor
+    // the tab strip itself can reach it — and not narrowed to "the last row ending
+    // in `?`", so a question wrapped over three rows keeps its first two. `?` is
+    // usable evidence elsewhere and is deliberately not required here.
+    const questionRows = regionRows
+        .slice(tabOffset + 1, block.firstRow)
+        .map((row) => row.trim())
+        .filter((row) => row !== '');
+    if (questionRows.length === 0)
+        return unsupported('question-missing');
+    const question = questionRows.join(' ');
+    // The dialog's own rows, and nothing above the rule. Both surfaces are built
+    // from the same slice on purpose: `instructionText` is what the answer panels
+    // show a human, `approvalTarget` is what the contract's deny patterns are
+    // matched against (#1699), and for THIS screen they are the same text — the
+    // region already excludes the previous turn, so there is no wider human-facing
+    // window to offer and no narrower machine-facing one to carve out. What
+    // matters is that the descriptions are inside both: a deny pattern has to see
+    // the sentence the option is actually promising.
+    const dialogText = (0, prompt_detect_multiple_choice_1.joinApprovalTarget)(regionRows, tabOffset + 1, regionRows.length);
+    const built = (0, prompt_detect_multiple_choice_1.buildMultipleChoiceResult)(question, labels.map((label, index) => ({
+        number: index + 1,
+        label,
+        isDefault: index === block.selectedIndex,
+    })), { instructionText: dialogText, approvalTarget: dialogText }, regionRows.join('\n'), truncateRawContent, 
+    // 確定仕様 D. The measured `QuestionPrompt` hands the ordinary choices to a
+    // `SelectInput`, which calls `onSelect` on the DIGIT — so a trailing Enter
+    // would land on whatever the tool painted next (the following question, or
+    // Review), confirming a second operation nobody chose. `answer_only` is also
+    // the safe direction if that measurement is ever wrong for a build: a digit
+    // that selects nothing leaves the dialog exactly where it was, while the
+    // Enter it would otherwise be paired with cannot be taken back.
+    'answer_only', 
+    // This IS an AskUserQuestion — a tab strip, a question and its own choices,
+    // not a permission prompt. It changes no keystroke for this tool (the cursor
+    // navigation arm of `sendPromptAnswer` is claude's and agy's), and it is what
+    // lets `/prompt-response` tell "the picker is up but unreadable" from "the
+    // prompt is gone".
+    true);
+    const promptData = built.promptData;
+    /* c8 ignore next -- buildMultipleChoiceResult always returns multiple_choice */
+    if (promptData === undefined || promptData.type !== 'multiple_choice') {
+        return unsupported('option-block-unreadable');
+    }
+    return {
+        kind: 'prompt',
+        region,
+        prompt: {
+            ...built,
+            promptData: {
+                ...promptData,
+                options: promptData.options.map((option) => option.requiresTextInput === true ||
+                    COMMAND_CODE_FREE_TEXT_OPTION_PATTERN.test(option.label)
+                    ? { ...option, requiresTextInput: true }
+                    : option),
+            },
+        },
+    };
+}
+/**
+ * The same reading as a `PromptDetectionResult | null`, for the call sites whose
+ * only question is "is there an answerable prompt here?".
+ *
+ * `null` for BOTH `none` and `unsupported`, which is safe exactly where the
+ * caller has already decided what to do about the second — the detector's
+ * `beforePrompt` publishes #2521's fallback for it, and `/prompt-response`
+ * refuses it with `unsupported_dialog_layout`. A caller that cannot tell the two
+ * apart must use {@link readCommandCodeQuestionDialog} instead.
+ */
+function detectCommandCodeQuestionPrompt(frame) {
+    const reading = readCommandCodeQuestionDialog(frame);
+    return reading.kind === 'prompt' ? reading.prompt : null;
+}

package/dist/server/src/lib/detection/tools/verified-against.js

@@ -112,6 +112,26 @@ exports.ANTIGRAVITY_VERIFIED_AGAINST = {
  * tmux socket at the production geometry — the default pane size does not
  * reproduce the 200-column rules that fence the composer, and the status row
  * drops its `esc to interrupt` tail below 72 columns.
+ *
+ * ## Deliberately NOT advanced by Issues #2521 / #2522
+ *
+ * Both read the `AskUserQuestion` screen, and both did it from the anonymised
+ * capture in `tests/fixtures/command-code-askuserquestion-2521/` — whose rows
+ * 410-423 are verbatim from a live pane, but whose version is what the reporting
+ * session SAID it was (1.53.0) rather than something re-probed. #2522's own
+ * fixture directory is synthetic throughout, and the send mode
+ * (`submitMode: 'answer_only'`) was chosen from a STATIC reading of a locally
+ * installed 1.53.1 `QuestionPrompt` plus the safe-direction argument in
+ * `tools/command-code/dialog.ts` — not from a keystroke sent at a live pane.
+ *
+ * None of that is the measurement this stamp records. #2304 set the precedent in
+ * the other direction: seven frames re-captured live on 1.49.0 changed no rule,
+ * and the stamp still says 1.40.1 because that is the build the rules were READ
+ * OFF. Advancing it here on a reported version, a synthetic fixture and a
+ * package read off disk would make `getDetectorFreshness` claim a measurement
+ * nobody took. When a live 1.53.x session is probed — the question screen, the
+ * keys it accepts and what one of them advances — bump this to that exact
+ * version with its own `capturedAt`.
  */
 exports.COMMAND_CODE_VERIFIED_AGAINST = {
     version: '1.40.1',

package/dist/server/src/lib/polling/response-checker.js

@@ -18,6 +18,7 @@ const db_1 = require("../../lib/db");
 const ws_server_1 = require("../../lib/ws-server");
 const prompt_detector_1 = require("../../lib/detection/prompt-detector");
 const dialog_1 = require("../../lib/detection/tools/antigravity/dialog");
+const dialog_2 = require("../../lib/detection/tools/command-code/dialog");
 const conversation_logger_1 = require("../../lib/conversation-logger");
 const types_1 = require("../../lib/cli-tools/types");
 const claude_output_1 = require("../../lib/claude-output");
@@ -205,13 +206,29 @@ function buildPromptExtractionResult(lines, lastCapturedLine, totalLines, buffer
  * doubly-bordered row loses a second character on the second pass). Taking the
  * already-clean frame here is what keeps the two callers reading identical text.
  *
+ * ## The raw frame, and why it is a SECOND argument rather than a replacement
+ *
+ * Issue #2522. Command Code's `AskUserQuestion` is anchored on a 200-column
+ * U+2500 rule row, and `stripBoxDrawing` blanks exactly that row — so the
+ * reading that recognises the screen answers `null` on the spelling this
+ * function takes, however plainly the dialog is on the pane. The frame the
+ * cleaning started from is therefore passed alongside it: the caller has it in
+ * hand from the same tick, no second capture is taken, and `stripBoxDrawing`
+ * (which is not idempotent) still runs exactly once per tick, upstream.
+ *
+ * Omitting `rawFrame` is not an error and not a silent downgrade for anything
+ * else: only Command Code's reader consults it, and a caller that has no raw
+ * frame for this tool reaches the same `null` the old code did.
+ *
  * @param cleanOutput - tmux output with ANSI **and** box drawing already removed
  * @param cliToolId - CLI tool identifier for building detection options
  * @param precomputedLines - `cleanOutput.split('\n')` when the caller already has it
  *   (Issue #499 Item 4); must be the split of THIS string, not of the raw capture
+ * @param rawFrame - the SAME tick's capture with its box drawing intact (ANSI
+ *   optional), for the tool readers anchored on it (Issue #2522)
  * @returns PromptDetectionResult with isPrompt, promptData, and cleanContent
  */
-function detectPromptOnCleanFrame(cleanOutput, cliToolId, precomputedLines) {
+function detectPromptOnCleanFrame(cleanOutput, cliToolId, precomputedLines, rawFrame) {
     // Issue #2364: agy's `↑/↓ Navigate` dialogs are read by agy's own reader
     // before the generic pass, on the same spelling `tools/antigravity/detect.ts`
     // reads them on. The generic multiple-choice parser takes one row per option
@@ -232,6 +249,31 @@ function detectPromptOnCleanFrame(cleanOutput, cliToolId, precomputedLines) {
         if (dialog !== null)
             return dialog;
     }
+    // Issue #2522: Command Code's footer-less `AskUserQuestion`, read by the same
+    // module `tools/command-code/detect.ts` publishes its status from — so the
+    // status API, the row this poller stores, the push notification's excerpt and
+    // `/prompt-response`'s re-verification all describe ONE screen with one
+    // question, one option list and one default.
+    //
+    // Ahead of the generic pass rather than after it, and both halves matter:
+    //
+    //  - `prompt` — the generic parser SUCCEEDS on the short, unwrapped spelling
+    //    of this screen and drags the tab strip and the transcript row above it
+    //    into the question, so "fall back to the reader" would leave the frames
+    //    that look fine looking wrong;
+    //  - `unsupported` — the question UI is up and the reading declined (a gap in
+    //    the numbering, an over-tall region). 確定仕様 B: no `promptData`, and
+    //    explicitly NOT the generic parser's partial list either. The status path
+    //    publishes #2521's manual-operation fallback for the same frame, so a
+    //    human is still told to answer it at the pane.
+    if (cliToolId === 'command-code' && rawFrame !== undefined) {
+        const reading = (0, dialog_2.readCommandCodeQuestionDialog)(rawFrame);
+        if (reading.kind === 'prompt')
+            return reading.prompt;
+        if (reading.kind === 'unsupported') {
+            return { isPrompt: false, cleanContent: cleanOutput.trim() };
+        }
+    }
     const promptOptions = (0, cli_patterns_1.buildDetectPromptOptions)(cliToolId);
     return (0, prompt_detector_1.detectPrompt)(cleanOutput, precomputedLines ? { ...promptOptions, precomputedLines } : promptOptions);
 }
@@ -295,7 +337,11 @@ function isNumberedDialogVouched(cliToolId, promptDetection, frame) {
  * @returns PromptDetectionResult with isPrompt, promptData, and cleanContent
  */
 function detectPromptWithOptions(output, cliToolId) {
-    return detectPromptOnCleanFrame((0, cli_patterns_1.stripBoxDrawing)((0, cli_patterns_1.stripAnsi)(output)), cliToolId);
+    // Issue #2522: `output` is the capture, so the box-drawing-bearing spelling is
+    // right here and is handed on as `rawFrame`. Nothing is captured twice and
+    // nothing is cleaned twice — the fourth argument is the string the first one
+    // was DERIVED from.
+    return detectPromptOnCleanFrame((0, cli_patterns_1.stripBoxDrawing)((0, cli_patterns_1.stripAnsi)(output)), cliToolId, undefined, output);
 }
 // ============================================================================
 // extractResponse (internal)

package/dist/server/src/lib/ws-server.js

@@ -40,6 +40,7 @@ const waiting_broadcast_1 = require("../lib/realtime/waiting-broadcast");
 // build has two instances of it (`dist/server` + a `.next/server/chunks` copy).
 // The registry is how a route handler's copy reaches the one holding sockets.
 const publisher_registry_1 = require("../lib/realtime/publisher-registry");
+const websocket_config_1 = require("../config/websocket-config");
 const logger_1 = require("../lib/logger");
 const logger = (0, logger_1.createLogger)('ws-server');
 // Global state
@@ -54,6 +55,14 @@ const rooms = new Map();
  * bare "clear the registry" would let a torn-down instance silence a newer one.
  */
 let publisherHandle = null;
+/**
+ * Issue #2502: the heartbeat sweep's interval, or null while no server is up.
+ *
+ * Module-scoped like `wss` and torn down with it — a timer that outlived
+ * `closeWebSocket` would go on pinging a `clients` map nobody reads, and CI
+ * shares one process across the whole suite.
+ */
+let heartbeatTimer = null;
 const MAX_TERMINAL_INPUT_LENGTH = 4096;
 const MAX_TERMINAL_SUBSCRIBERS_PER_SESSION = 4;
 const TERMINAL_FALLBACK_CAPTURE_LINES = -200;
@@ -289,6 +298,79 @@ function isExpectedWebSocketError(error) {
         error.message?.includes('ECONNRESET') ||
         error.message?.includes('EPIPE'));
 }
+/**
+ * One heartbeat sweep over every connected client (Issue #2502).
+ *
+ * The `ws` library's standard liveness recipe, with one addition. The recipe:
+ * a connection that has not ponged since the previous sweep is gone — the peer
+ * crashed, or the path between us is half-open — so `terminate()` it rather
+ * than `close()` it. A close handshake needs a live peer to answer, which is
+ * exactly what is in question, so `close()` on a dead path just parks the
+ * socket in CLOSING until the OS TCP timeout fires, minutes later, with the
+ * room membership and any terminal subscription still held open the whole time.
+ *
+ * The addition is the application-level beat. A browser answers protocol pings
+ * for free but exposes neither the ping nor its own pong to page JavaScript, so
+ * the ping alone only ever teaches the SERVER that a client is gone. The extra
+ * frame is what lets the tab reach the same conclusion about us
+ * (`useWebSocket`'s liveness check).
+ *
+ * Exported through `__internal` so the behaviour can be tested without waiting
+ * {@link WS_SERVER_HEARTBEAT_INTERVAL_MS} for a real interval to fire.
+ */
+function runHeartbeatSweep() {
+    clients.forEach((clientInfo, ws) => {
+        if (!clientInfo.isAlive) {
+            logger.warn('heartbeat:terminate', { rooms: clientInfo.worktreeIds.size });
+            try {
+                ws.terminate();
+            }
+            catch {
+                // Already destroyed; the disconnect bookkeeping below still has to run.
+            }
+            // `terminate()` emits 'close' and that handler cleans up too, but this is
+            // not belt-and-braces: on an already-destroyed socket no event fires at
+            // all, and `handleDisconnect` is idempotent (it returns early for a ws it
+            // no longer knows). Deleting the current key mid-`forEach` is defined
+            // behaviour for a Map.
+            handleDisconnect(ws);
+            return;
+        }
+        clientInfo.isAlive = false;
+        try {
+            ws.ping();
+        }
+        catch (error) {
+            logger.error('heartbeat:ping-failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (ws.readyState !== ws_1.WebSocket.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify({ type: websocket_config_1.WS_HEARTBEAT_MESSAGE_TYPE, at: Date.now() }));
+        }
+        catch {
+            // Best-effort: a failing send means the socket is already going away, and
+            // the next sweep terminates it.
+        }
+    });
+}
+/** Start the heartbeat sweep, replacing any previous one. */
+function startHeartbeat() {
+    stopHeartbeat();
+    heartbeatTimer = setInterval(runHeartbeatSweep, websocket_config_1.WS_SERVER_HEARTBEAT_INTERVAL_MS);
+    // Never the reason the process stays alive: `commandmate stop` and the CLI's
+    // short-lived server should not have to wait out a 30s tick.
+    heartbeatTimer.unref?.();
+}
+/** Stop the heartbeat sweep. Safe to call when none is running. */
+function stopHeartbeat() {
+    if (heartbeatTimer !== null) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+    }
+}
 /**
  * Setup WebSocket server on HTTP or HTTPS server
  * Issue #331: Added auth check on WebSocket upgrade
@@ -317,6 +399,9 @@ function setupWebSocket(server, options) {
     // — and so the closure it registers is the one holding *this* bundle's `rooms`
     // map, which is what a broadcast has to reach.
     (0, waiting_broadcast_1.startWaitingStatusBroadcast)(handleBroadcast);
+    // Issue #2502: and the liveness sweep, for the same lifetime reason — it has
+    // to die with this `wss`, not with the process.
+    startHeartbeat();
     // Handle upgrade requests - only accept app WebSocket connections, not Next.js HMR
     const handleUpgrade = (request, socket, head) => {
         const pathname = request.url || '/';
@@ -415,8 +500,17 @@ function setupWebSocket(server, options) {
             ws,
             worktreeIds: new Set(),
             terminalSubscription: null,
+            isAlive: true,
         };
         clients.set(ws, clientInfo);
+        // Issue #2502: the other half of the liveness recipe. Browsers answer a
+        // protocol ping automatically, so a client needs no code for this to work —
+        // silence here is evidence about the path, not about the page.
+        ws.on('pong', () => {
+            const info = clients.get(ws);
+            if (info)
+                info.isAlive = true;
+        });
         // Issue #573: Removed _socket direct access (as unknown as pattern).
         // ws.on('error') handler below covers socket-level errors because the ws library
         // internally propagates underlying socket errors to the WebSocket 'error' event
@@ -1105,6 +1199,10 @@ function closeWebSocket() {
     if (wasOwner || (0, publisher_registry_1.getRoomPublisher)() === null) {
         (0, waiting_broadcast_1.stopWaitingStatusBroadcast)();
     }
+    // Issue #2502: unconditionally — unlike the waiting-edge subscription this is
+    // a plain module-local timer, not a `globalThis` slot, so a superseded
+    // instance clearing it cannot reach a live server's sweep.
+    stopHeartbeat();
     if (wss) {
         // Close all client connections
         clients.forEach((clientInfo) => {
@@ -1121,6 +1219,9 @@ function closeWebSocket() {
 }
 exports.__internal = {
     handleMessage,
+    runHeartbeatSweep,
+    startHeartbeat,
+    stopHeartbeat,
     handleClientVersion,
     handleProxyUpgrade,
     handleTerminalSubscribe,
@@ -1128,17 +1229,26 @@ exports.__internal = {
     handleTerminalResize,
     handleTerminalUnsubscribe,
     handleDisconnect,
-    registerClientForTest(ws) {
+    registerClientForTest(ws, isAlive = true) {
         clients.set(ws, {
             ws,
             worktreeIds: new Set(),
             terminalSubscription: null,
+            isAlive,
         });
     },
     getClientInfoForTest(ws) {
         return clients.get(ws);
     },
+    /**
+     * Every live client, for tests that hold the *client* end of a real socket and
+     * therefore have no handle on the server-side `WebSocket` to look up by.
+     */
+    listClientsForTest() {
+        return Array.from(clients.values());
+    },
     resetStateForTest() {
+        stopHeartbeat();
         clients.clear();
         rooms.clear();
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "description": "A local control plane for agent CLIs — orchestration and visibility for Claude Code, Codex, Gemini CLI, and more across Git worktrees",
   "keywords": [
     "claude-code",

package/public/sw.js

@@ -26,6 +26,18 @@ const OFFLINE_URL = '/offline';
 const PRECACHE_URLS = [OFFLINE_URL];
 
 // Denylist — never cached (mirror of EXCLUDED_PATH_PREFIXES).
+//
+// `/api` is load-bearing and is not a default anyone forgot to revisit: Issue
+// #2504 asked for two of its GETs to be served from cache while revalidating,
+// and was closed wontfix. The short reason is that a cache read in this file
+// cannot be authenticated — the auth cookie is httpOnly and invisible here, the
+// server sends no `Vary: Cookie`, and the token is one server-wide secret, so
+// there is no identity to key a cache on. Whatever lands in the Cache API is
+// readable by anyone who can open this origin in this browser profile.
+// Note also that `matchesPrefix` below is a PREFIX match: `/api/worktrees` is
+// 36 routes, among them current-output, files, env, messages and terminal.
+// The rest of the reasoning is in src/lib/pwa/cache-policy.ts; the full argument
+// is the design policy filed on Issue #2504.
 const EXCLUDED_PATH_PREFIXES = ['/api', '/login', '/proxy'];
 // Allowlist — cache-first (mirror of STATIC_CACHE_PREFIXES / STATIC_CACHE_EXACT).
 const STATIC_CACHE_PREFIXES = ['/_next/static/', '/icons/'];

package/.next/server/chunks/120.js

@@ -1 +0,0 @@
-exports.id=120,exports.ids=[120],exports.modules={29701:(a,b,c)=>{"use strict";c.d(b,{A:()=>n});var d=c(86723),e=c(14549),f=c(46831);let g={}.hasOwnProperty;function h(a,b){if(b&&"object"==typeof b)switch("string"==typeof b.type?b.type:""){case"comment":var c=a,d=b;if(c.schema.allowComments){let a="string"==typeof d.value?d.value:"",b=a.indexOf("--\x3e"),c={type:"comment",value:b<0?a:a.slice(0,b)};return l(c,d),c}return;case"doctype":var e=a,f=b;if(e.schema.allowDoctypes){let a={type:"doctype"};return l(a,f),a}return;case"element":return function(a,b){let c="string"==typeof b.tagName?b.tagName:"";a.stack.push(c);let d=i(a,b.children),e=function(a,b){let c,d=a.stack[a.stack.length-1],e=a.schema.attributes,f=a.schema.required,h=e&&g.call(e,d)?e[d]:void 0,i=e&&g.call(e,"*")?e["*"]:void 0,k=b&&"object"==typeof b?b:{},l={};for(c in k)if(g.call(k,c)){let b=k[c],d=j(a,m(h,c),c,b);null==d&&(d=j(a,m(i,c),c,b)),null!=d&&(l[c]=d)}if(f&&g.call(f,d)){let a=f[d];for(c in a)g.call(a,c)&&!g.call(l,c)&&(l[c]=a[c])}return l}(a,b.properties);a.stack.pop();let f=!1;if(c&&"*"!==c&&(!a.schema.tagNames||a.schema.tagNames.includes(c))&&(f=!0,a.schema.ancestors&&g.call(a.schema.ancestors,c))){let b=a.schema.ancestors[c],d=-1;for(f=!1;++d<b.length;)a.stack.includes(b[d])&&(f=!0)}if(!f)return a.schema.strip&&!a.schema.strip.includes(c)?d:void 0;let h={type:"element",tagName:c,properties:e,children:d};return l(h,b),h}(a,b);case"root":var h=a,k=b;let n={type:"root",children:i(h,k.children)};return l(n,k),n;case"text":var o=b;let p={type:"text",value:"string"==typeof o.value?o.value:""};return l(p,o),p}}function i(a,b){let c=[];if(Array.isArray(b)){let d=-1;for(;++d<b.length;){let e=h(a,b[d]);e&&(Array.isArray(e)?c.push(...e):c.push(e))}}return c}function j(a,b,c,d){return b?Array.isArray(d)?function(a,b,c,d){let e=-1,f=[];for(;++e<d.length;){let g=k(a,b,c,d[e]);("number"==typeof g||"string"==typeof g)&&f.push(g)}return f}(a,b,c,d):k(a,b,c,d):void 0}function k(a,b,c,d){if(("boolean"==typeof d||"number"==typeof d||"string"==typeof d)&&function(a,b,c){let d=a.schema.protocols&&g.call(a.schema.protocols,b)?a.schema.protocols[b]:void 0;if(!d||0===d.length)return!0;let e=String(c),f=e.indexOf(":"),h=e.indexOf("?"),i=e.indexOf("#"),j=e.indexOf("/");if(f<0||j>-1&&f>j||h>-1&&f>h||i>-1&&f>i)return!0;let k=-1;for(;++k<d.length;){let a=d[k];if(f===a.length&&e.slice(0,a.length)===a)return!0}return!1}(a,c,d)){if("object"==typeof b&&b.length>1){let a=!1,c=0;for(;++c<b.length;){let e=b[c];if(e&&"object"==typeof e&&"flags"in e){if(e.test(String(d))){a=!0;break}}else if(e===d){a=!0;break}}if(!a)return}return a.schema.clobber&&a.schema.clobberPrefix&&a.schema.clobber.includes(c)?a.schema.clobberPrefix+d:d}}function l(a,b){let c=(0,e.G1)(b);b.data&&(a.data=(0,d.Ay)(b.data)),c&&(a.position=c)}function m(a,b){let c,d=-1;if(a)for(;++d<a.length;){let e=a[d],f="string"==typeof e?e:e[0];if(f===b)return e;"data*"===f&&(c=e)}if(b.length>4&&"data"===b.slice(0,4).toLowerCase())return c}function n(a){return function(b){var c=b,d=a;let e={type:"root",children:[]},g=h({schema:d?{...f.j,...d}:f.j,stack:[]},c);return g&&(Array.isArray(g)?1===g.length?e=g[0]:e.children=g:e=g),e}}},31230:()=>{},46831:(a,b,c)=>{"use strict";c.d(b,{j:()=>e});let d=["ariaDescribedBy","ariaLabel","ariaLabelledBy"],e={ancestors:{tbody:["table"],td:["table"],th:["table"],thead:["table"],tfoot:["table"],tr:["table"]},attributes:{a:[...d,"dataFootnoteBackref","dataFootnoteRef",["className","data-footnote-backref"],"href"],blockquote:["cite"],code:[["className",/^language-./]],del:["cite"],div:["itemScope","itemType"],dl:[...d],h2:[["className","sr-only"]],img:[...d,"longDesc","src"],input:[["disabled",!0],["type","checkbox"]],ins:["cite"],li:[["className","task-list-item"]],ol:[...d,["className","contains-task-list"]],q:["cite"],section:["dataFootnotes",["className","footnotes"]],source:["srcSet"],summary:[...d],table:[...d],ul:[...d,["className","contains-task-list"]],"*":["abbr","accept","acceptCharset","accessKey","action","align","alt","axis","border","cellPadding","cellSpacing","char","charOff","charSet","checked","clear","colSpan","color","cols","compact","coords","dateTime","dir","encType","frame","hSpace","headers","height","hrefLang","htmlFor","id","isMap","itemProp","label","lang","maxLength","media","method","multiple","name","noHref","noShade","noWrap","open","prompt","readOnly","rev","rowSpan","rows","rules","scope","selected","shape","size","span","start","summary","tabIndex","title","useMap","vAlign","value","width"]},clobber:["ariaDescribedBy","ariaLabelledBy","id","name"],clobberPrefix:"user-content-",protocols:{cite:["http","https"],href:["http","https","irc","ircs","mailto","xmpp"],longDesc:["http","https"],src:["http","https"]},required:{input:{disabled:!0,type:"checkbox"}},strip:["script"],tagNames:["a","b","blockquote","br","code","dd","del","details","div","dl","dt","em","h1","h2","h3","h4","h5","h6","hr","i","img","input","ins","kbd","li","ol","p","picture","pre","q","rp","rt","ruby","s","samp","section","source","span","strike","strong","sub","summary","sup","table","tbody","td","tfoot","th","thead","tr","tt","ul","var"]}}};