commandmate 0.30.1 → 0.31.0

package/dist/server/src/lib/tmux/tmux.js

@@ -4,7 +4,7 @@
  * Provides functions to manage tmux sessions for Claude CLI integration
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NAVIGATION_KEY_VALUES = exports.SPECIAL_KEY_VALUES = void 0;
+exports.REPAINT_INVALIDATE_DELAY_MS = exports.NAVIGATION_KEY_VALUES = exports.SPECIAL_KEY_VALUES = void 0;
 exports.exactTarget = exactTarget;
 exports.reconcileSessionGeometry = reconcileSessionGeometry;
 exports.isTmuxAvailable = isTmuxAvailable;
@@ -28,6 +28,7 @@ exports.sendSpecialKeysAndInvalidate = sendSpecialKeysAndInvalidate;
 const child_process_1 = require("child_process");
 const util_1 = require("util");
 const tmux_capture_cache_1 = require("./tmux-capture-cache");
+const geometry_delegation_1 = require("./geometry-delegation");
 const validation_1 = require("../../lib/cli-tools/validation");
 const tmux_pane_config_1 = require("../../config/tmux-pane-config");
 const logger_1 = require("../../lib/logger");
@@ -77,6 +78,24 @@ function exactTarget(sessionName) {
  * Failures are intentionally non-fatal: geometry improves capture fidelity but
  * must never make an otherwise healthy CLI session unusable.
  *
+ * ## It stands down while a human is attached (Issue #2317, Phase D)
+ *
+ * `commandmate attach --live` hands the window to the terminal looking at it so
+ * the transcript is readable at all; every `send` to a running session reaches
+ * here through `reconcileExistingSession()`, and snapping the canvas back to
+ * 200x1000 mid-read would undo that under the reader's hands. So when the
+ * geometry does NOT already match, this asks whether a NON-control-mode client
+ * is attached and leaves the window alone if one is.
+ *
+ * Two properties of that ordering are load-bearing:
+ *
+ *  - the question is asked only on the path that would actually resize, so the
+ *    overwhelmingly common "already correct" call still costs exactly the two
+ *    tmux round-trips it always has;
+ *  - it keys off a live client rather than off `@cm_delegated`, so a flag left
+ *    behind by a CLI that was killed can never pin a window open forever — the
+ *    next reconcile with nobody attached repairs it.
+ *
  * @returns true when at least one tmux option was changed.
  */
 async function reconcileSessionGeometry(sessionName, options = {}) {
@@ -103,6 +122,13 @@ async function reconcileSessionGeometry(sessionName, options = {}) {
     const sizeMatches = currentWidth === windowWidth && currentHeight === windowHeight;
     if (modeMatches && sizeMatches)
         return false;
+    // Issue #2317: a human is reading this pane at their terminal's size. See the
+    // docblock — asked here, after the cheap match, so the ordinary call is
+    // unchanged.
+    if ((options.respectAttachedClient ?? true) && (await (0, geometry_delegation_1.hasHumanClientAttached)(sessionName))) {
+        logger.info('session-geometry:delegated-to-client', { sessionName });
+        return false;
+    }
     try {
         if (!modeMatches) {
             await execFileAsync('tmux', ['set-window-option', '-t', target, 'window-size', 'manual'], { timeout: DEFAULT_TIMEOUT });
@@ -316,7 +342,13 @@ async function createSession(sessionNameOrOptions, cwd) {
         // replaced (verified: `show-window-options -v window-size` came back empty),
         // so reconciling first would have the setting thrown away and leave the pane
         // tracking the latest client again.
-        await reconcileSessionGeometry(sessionName, { windowWidth, windowHeight });
+        await reconcileSessionGeometry(sessionName, {
+            windowWidth,
+            windowHeight,
+            // Nothing can be attached to a session this call is still creating, so the
+            // Phase D client probe would be a round-trip with one possible answer.
+            respectAttachedClient: false,
+        });
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -433,6 +465,20 @@ const ALLOWED_SPECIAL_KEYS = new Set([
     // are tmux named keys; 'q' is the pager's literal "quit" character (sent verbatim by
     // `tmux send-keys`, no injection risk — single fixed char via execFile, not a shell).
     'PageUp', 'PageDown', 'Home', 'End', 'q',
+    // Issue #2254: the answer characters `1`-`9` / `y` / `n`, so a dialog nobody
+    // could parse can be answered from the chat surface's dialog card instead of
+    // only from the terminal. Literal characters on the wire like `q` above.
+    // `n` was already deliverable as an opencode chord letter and is not repeated.
+    '1', '2', '3', '4', '5', '6', '7', '8', '9', 'y',
+    // Issue #2297: claude's "use this session only" key. Its `/model` footer reads
+    // `Enter to set as default · s to use this session only · Esc to cancel`, and
+    // `Enter` there rewrites `model` in ~/.claude/settings.json (#1495) — so
+    // without this the chat surface could deliver the destructive half of that
+    // footer and not the safe half. A literal character like `q` / `y` above.
+    // Deliverable here for every session; only claude and Command Code DECLARE it
+    // (`CLAUDE_NAVIGATION_KEY_VALUES`), so the route answers 400 for anyone else —
+    // which matters, because `s` is `sort:relevance` on copilot's session picker.
+    's',
     // Issue #2046: opencode's own chords. `C-x` is its leader prefix (measured
     // default of 1.18.22, 2000 ms window), `C-p` opens the command palette and
     // `C-t` cycles the model variant. The lower-case letters complete a leader
@@ -802,6 +848,36 @@ async function clearComposerLine(sessionName) {
 function isAllowedSpecialKey(key, vocabulary = terminal_keys_1.NAVIGATION_KEY_VALUES) {
     return vocabulary.includes(key) && isSendableSpecialKey(key);
 }
+/**
+ * How long after a key lands the TUI is still allowed to be repainting
+ * (Issue #2297).
+ *
+ * `invalidateCache()` fires the instant `tmux send-keys` returns, which is
+ * BEFORE the CLI has drawn the consequence of the key. The next capture — the
+ * chat surface's own `onKeysSent` refresh, or any of the pollers that share this
+ * cache (the sidebar status probe, the global session poller) — therefore has a
+ * good chance of storing the PRE-repaint frame, and {@link CACHE_TTL_MS} then
+ * serves that stale frame for five seconds. That is the "the highlight does not
+ * move" report in Issue #2297: the send worked, the cache was invalidated, and
+ * the surface still drew the old dialog.
+ *
+ * 250 ms is comfortably past an ink/bubbletea repaint (`SPECIAL_KEY_DELAY_MS`,
+ * the gap this transport already leaves BETWEEN keys of one chord, is 100 ms)
+ * and comfortably inside the 1-second budget the Issue sets for seeing the
+ * highlight move.
+ */
+exports.REPAINT_INVALIDATE_DELAY_MS = 250;
+/**
+ * Drop the cached frame again once the TUI has had time to repaint.
+ *
+ * Fire-and-forget on purpose: the route must not wait 250 ms to answer, and the
+ * work is one `Map.delete`. The timer is `unref()`ed where the runtime supports
+ * it so a pending invalidation can never hold a process (or a test runner) open.
+ */
+function scheduleRepaintInvalidation(sessionName) {
+    const timer = setTimeout(() => (0, tmux_capture_cache_1.invalidateCache)(sessionName), exports.REPAINT_INVALIDATE_DELAY_MS);
+    timer.unref?.();
+}
 /**
  * Send special keys to a tmux session and invalidate the capture cache.
  * Wrapper combining sendSpecialKeys() + invalidateCache() for DRY (DR1-003).
@@ -812,4 +888,5 @@ function isAllowedSpecialKey(key, vocabulary = terminal_keys_1.NAVIGATION_KEY_VA
 async function sendSpecialKeysAndInvalidate(sessionName, keys) {
     await sendSpecialKeys(sessionName, keys);
     (0, tmux_capture_cache_1.invalidateCache)(sessionName);
+    scheduleRepaintInvalidation(sessionName);
 }

package/dist/server/src/lib/version-checker.js

@@ -20,12 +20,15 @@ exports.isNewerVersion = isNewerVersion;
 exports.getClientVersion = getClientVersion;
 exports.getServerVersion = getServerVersion;
 exports.getCurrentVersion = getCurrentVersion;
+exports.getServedBundleVersion = getServedBundleVersion;
+exports.resolveBundleDrift = resolveBundleDrift;
 exports.validateReleaseUrl = validateReleaseUrl;
 exports.sanitizeReleaseName = sanitizeReleaseName;
 exports.checkForUpdate = checkForUpdate;
 exports.resetCacheForTesting = resetCacheForTesting;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const types_1 = require("../lib/realtime/types");
 // =============================================================================
 // Constants
 // =============================================================================
@@ -60,6 +63,17 @@ const FETCH_TIMEOUT_MS = 5000;
  * project directory) leaking a foreign version.
  */
 const PACKAGE_NAME = 'commandmate';
+/**
+ * The manifest `next build` writes beside the client bundle, relative to the
+ * package root. [Issue #2271]
+ *
+ * It snapshots the *resolved* next.config — the `env` block included — so
+ * `config.env.NEXT_PUBLIC_APP_VERSION` is literally the string that build
+ * inlined into every browser bundle it emitted. That makes it the only file on
+ * disk that can answer "which version is the bundle we are serving?" without
+ * asking the bundle itself.
+ */
+const NEXT_BUILD_MANIFEST_PATH = ['.next', 'required-server-files.json'];
 const cache = globalThis.__versionCheckCache ??
     (globalThis.__versionCheckCache = {
         result: null,
@@ -162,6 +176,99 @@ function getServerVersion() {
 function getCurrentVersion() {
     return getServerVersion();
 }
+// =============================================================================
+// Served bundle identity (Issue #2271)
+// =============================================================================
+/**
+ * Memoised answer of {@link getServedBundleVersion}, resolved on first use and
+ * then frozen for the life of the process. [Issue #2271]
+ *
+ * Frozen on purpose. The question is "which build is this process serving?",
+ * and a running Next production server answers that once — at startup, from the
+ * `.next` it opened. Re-reading the manifest on every call would let a
+ * `next build` performed *underneath* the running server rename the served
+ * build without the server having reloaded a single byte of it, which is the
+ * false positive this Issue exists to remove, in a new disguise.
+ */
+let servedBundleVersion = null;
+/**
+ * Read the version `next build` inlined into the client bundle, from the build
+ * manifest it left on disk. [Issue #2271]
+ *
+ * @returns The baked version, or null when the manifest is absent, unreadable,
+ *   malformed, or predates the `env` block.
+ */
+function readServedBundleVersionFromBuild() {
+    try {
+        const raw = (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), ...NEXT_BUILD_MANIFEST_PATH), 'utf-8');
+        const parsed = JSON.parse(raw);
+        const baked = parsed.config?.env?.NEXT_PUBLIC_APP_VERSION;
+        if (typeof baked === 'string' && baked.length > 0)
+            return baked;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** First-use resolution behind {@link getServedBundleVersion}'s memo. */
+function resolveServedBundleVersion() {
+    // `next dev` compiles on demand and never writes the build manifest, but a
+    // stale one left by an earlier `npm run build` is still sitting in `.next` —
+    // and it names a version the dev bundle was never built from. Under dev the
+    // live next.config populates `process.env` for the server too, so the baked
+    // value already *is* the honest answer and the manifest must not be consulted.
+    if (process.env.NODE_ENV === 'production') {
+        const built = readServedBundleVersionFromBuild();
+        if (built)
+            return built;
+    }
+    return getClientVersion();
+}
+/**
+ * The version of the **client bundle this server is serving**. [Issue #2271]
+ *
+ * Deliberately *not* {@link getServerVersion}. That one reads package.json at
+ * runtime, which is the right answer for "is there a newer release on GitHub?"
+ * and the wrong one for "should this tab reload?": the release procedure bumps
+ * package.json on `develop` and never rebuilds the primary checkout (doing so
+ * would swap `.next` out from under the running server — see the release
+ * skill's Phase 2-3), so `package.json > bundle` is the steady state after
+ * every release. Comparing against it therefore told **every** tab, forever,
+ * that it was out of date.
+ *
+ * The honest comparand is the build the bundle came from, so this reads the
+ * `next build` manifest and falls back — never to package.json — to the baked
+ * `NEXT_PUBLIC_APP_VERSION`, and finally to `'0.0.0'`, which
+ * {@link isVersionMismatch} treats as "unknown" and never reports as drift.
+ *
+ * @returns Served bundle version string (e.g., "0.2.3"), or "0.0.0" as fallback
+ */
+function getServedBundleVersion() {
+    servedBundleVersion ??= resolveServedBundleVersion();
+    return servedBundleVersion;
+}
+/**
+ * Decide whether a tab running `clientBundleVersion` is on a stale build.
+ * [Issue #2271]
+ *
+ * The single seam the WebSocket version handshake calls, so "what counts as
+ * drift" has exactly one definition and one place to test it. Both sides are
+ * build identities: the client sends the `NEXT_PUBLIC_APP_VERSION` its bundle
+ * was compiled with, and this compares it against the version of the bundle
+ * being served — so a bare `package.json` bump moves neither side, and only a
+ * rebuild does.
+ *
+ * @param clientBundleVersion - The version the tab's bundle was built from
+ * @returns The drifted pair, or null when the two builds agree or either side
+ *   is an unknown/fallback version
+ */
+function resolveBundleDrift(clientBundleVersion) {
+    const serverVersion = getServedBundleVersion();
+    if (!(0, types_1.isVersionMismatch)(serverVersion, clientBundleVersion))
+        return null;
+    return { serverVersion, clientVersion: clientBundleVersion };
+}
 /**
  * Validate that a URL is a legitimate GitHub Releases URL.
  * [SEC-SF-001] OWASP A03:2021 - Prevents injection via DNS pollution/MITM.
@@ -259,6 +366,9 @@ function resetCacheForTesting() {
     cache.result = null;
     cache.fetchedAt = 0;
     cache.rateLimitResetAt = null;
+    // Issue #2271: the served-bundle memo is frozen for the life of a process, so
+    // a suite that moves process.cwd() between cases must be able to thaw it.
+    servedBundleVersion = null;
 }
 // =============================================================================
 // Internal Functions

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

@@ -426,28 +426,34 @@ function handleMessage(ws, message) {
     }
 }
 /**
- * Handle a client-version hello (#1338/#1356).
+ * Handle a client-version hello (#1338/#1356/#2271).
  *
- * The client announces its baked bundle version on every (re)connect. If the
- * server's actually-running version (runtime package.json, resolved by
- * getServerVersion) has drifted from it, reply with a version_mismatch event so
- * the tab can surface a reload nudge. Stays silent when the versions match or
- * either side is an unknown/fallback version (受入条件: 誤検知しない).
+ * The client announces the version its bundle was built from on every
+ * (re)connect. `resolveBundleDrift` compares that against the version of the
+ * bundle **this server is serving** and answers null unless the two builds
+ * really differ; on drift, reply with a version_mismatch event so the tab can
+ * surface a reload nudge.
+ *
+ * Issue #2271: this used to ask `getServerVersion()`, i.e. the installed
+ * package.json. Releases bump that file without rebuilding the running server's
+ * `.next` — by design — so the comparison was permanently unequal and every tab
+ * carried an undismissable banner. The resolver, not this handler, is where
+ * "what counts as drift" is defined; keep it that way.
  */
 function handleClientVersion(ws, message) {
     const clientVersion = typeof message.version === 'string' ? message.version : '';
     if (!clientVersion)
         return;
-    const serverVersion = (0, version_checker_1.getServerVersion)();
-    if (!(0, types_2.isVersionMismatch)(serverVersion, clientVersion))
+    const drift = (0, version_checker_1.resolveBundleDrift)(clientVersion);
+    if (!drift)
         return;
     if (ws.readyState !== ws_1.WebSocket.OPEN)
         return;
     try {
         ws.send(JSON.stringify({
             type: types_2.VERSION_MISMATCH_EVENT_TYPE,
-            serverVersion,
-            clientVersion,
+            serverVersion: drift.serverVersion,
+            clientVersion: drift.clientVersion,
         }));
     }
     catch (error) {

package/dist/server/src/types/agent-transcript.js

@@ -39,7 +39,7 @@
  * @module types/agent-transcript
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_MARKDOWN_REQUEST_ID_PREFIXES = exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX = exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX = exports.CODEX_PROMPT_REQUEST_ID_PREFIX = exports.CODEX_MARKDOWN_REQUEST_ID_PREFIX = exports.CLAUDE_PROMPT_REQUEST_ID_PREFIX = exports.CLAUDE_MARKDOWN_REQUEST_ID_PREFIX = exports.AGENT_MARKDOWN_REQUEST_ID_PREFIX = void 0;
+exports.AGENT_MARKDOWN_REQUEST_ID_PREFIXES = exports.COMMAND_CODE_PROMPT_REQUEST_ID_PREFIX = exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX = exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX = exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX = exports.CODEX_PROMPT_REQUEST_ID_PREFIX = exports.CODEX_MARKDOWN_REQUEST_ID_PREFIX = exports.CLAUDE_PROMPT_REQUEST_ID_PREFIX = exports.CLAUDE_MARKDOWN_REQUEST_ID_PREFIX = exports.AGENT_MARKDOWN_REQUEST_ID_PREFIX = void 0;
 exports.isAgentAuthoredMarkdown = isAgentAuthoredMarkdown;
 exports.opencodeTurnRequestId = opencodeTurnRequestId;
 exports.claudeTurnRequestId = claudeTurnRequestId;
@@ -48,6 +48,8 @@ exports.codexTurnRequestId = codexTurnRequestId;
 exports.codexPromptRequestId = codexPromptRequestId;
 exports.antigravityTurnRequestId = antigravityTurnRequestId;
 exports.antigravityPromptRequestId = antigravityPromptRequestId;
+exports.commandCodeTurnRequestId = commandCodeTurnRequestId;
+exports.commandCodePromptRequestId = commandCodePromptRequestId;
 /**
  * Prefix on `chat_messages.request_id` for a row whose `content` is opencode's
  * own Markdown rather than a scrape of its terminal.
@@ -152,6 +154,40 @@ exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX = 'antigravity-turn:';
  * a codex turn can.
  */
 exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX = 'antigravity-prompt:';
+/**
+ * The same, for a turn read out of Command Code's transcript JSONL (Issue #2252).
+ *
+ * A fifth namespace for the fifth reader, for the reason
+ * {@link CLAUDE_MARKDOWN_REQUEST_ID_PREFIX} gives: the value is an idempotency
+ * key as well as a marker, and Command Code names its records with an **8-hex
+ * short id of its own minting** (`cb06ab09`), which is a far smaller space than
+ * claude's uuids. Sharing a prefix with claude would therefore not merely be
+ * untidy — a `command-code` id is exactly the shape a claude uuid's first
+ * segment has, and a collision between two tools' ids reads as "already saved",
+ * which is the one failure a key must not have.
+ *
+ * `command-code-` and not `cc-`: the string is what an operator reads in the row
+ * when they ask why History shows Markdown, and the tool id is what they will
+ * search the codebase for.
+ */
+exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX = 'command-code-turn:';
+/**
+ * Prefix on a **user** row whose text was read out of Command Code's transcript
+ * JSONL (Issue #2252).
+ *
+ * Deliberately absent from {@link AGENT_MARKDOWN_REQUEST_ID_PREFIXES}, for the
+ * whole of the reason {@link CLAUDE_PROMPT_REQUEST_ID_PREFIX} states: the
+ * operator's own text is drawn verbatim and must not change shape because it
+ * happened to contain a `#` or a `|`.
+ *
+ * Keyed on the same record id as the turn's assistant row, which is claude's
+ * arrangement rather than codex's. It is the right one here because Command
+ * Code opens a turn with exactly one fresh `role: "user"` record — its own
+ * `isFreshUserTurn` is `role === 'user' && no tool_result block`, and a prompt
+ * typed while a turn is running is appended as a `meta.source: "steering"`
+ * record that opens a turn of its own rather than joining the one in flight.
+ */
+exports.COMMAND_CODE_PROMPT_REQUEST_ID_PREFIX = 'command-code-prompt:';
 /**
  * Every prefix that means "this row holds source, not a rendering".
  *
@@ -166,6 +202,7 @@ exports.AGENT_MARKDOWN_REQUEST_ID_PREFIXES = [
     exports.CLAUDE_MARKDOWN_REQUEST_ID_PREFIX,
     exports.CODEX_MARKDOWN_REQUEST_ID_PREFIX,
     exports.ANTIGRAVITY_MARKDOWN_REQUEST_ID_PREFIX,
+    exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX,
 ];
 /**
  * Whether this row's `content` may be rendered as Markdown.
@@ -314,3 +351,38 @@ function antigravityTurnRequestId(conversationId, stepIndex) {
 function antigravityPromptRequestId(conversationId, stepIndex) {
     return `${exports.ANTIGRAVITY_PROMPT_REQUEST_ID_PREFIX}${antigravityTurnKey(conversationId, stepIndex)}`;
 }
+/**
+ * The row id for one Command Code turn (Issue #2252).
+ *
+ * The turn is named by the **prompt record it answers** — the `id` of the fresh
+ * `role: "user"` record the operator's text arrived on. That is claude's
+ * arrangement (#2121) and antigravity's (#2198) rather than codex's, because
+ * Command Code writes nothing that closes a turn and nothing that links a reply
+ * back to its prompt: `parentId` chains one record to the previous one in file
+ * order, not a reply to its question, so what opens the turn is the only
+ * boundary in the file.
+ *
+ * Deliberately not the assistant record's own `id`: one turn produces one
+ * assistant record per round of the agent loop — the captured two-tool turn has
+ * two — and keying on those would split one reply into several History rows.
+ *
+ * @param promptId - `id` of the user record that opened the turn
+ */
+function commandCodeTurnRequestId(promptId) {
+    return `${exports.COMMAND_CODE_MARKDOWN_REQUEST_ID_PREFIX}${promptId}`;
+}
+/**
+ * The row id for the **prompt** that opened one Command Code turn (Issue #2252).
+ *
+ * Same `id`, different prefix, and therefore a different row — exactly the
+ * relationship {@link claudePromptRequestId} has with {@link claudeTurnRequestId},
+ * and for the same reason: one record names one turn, and a turn is a user row
+ * plus an assistant row, so keying both on the record that opened it is what
+ * makes the pair reconstructible from the transcript alone, including on a
+ * re-read where both halves must resolve to "already there" independently.
+ *
+ * @param promptId - `id` of the user record the operator's text arrived on
+ */
+function commandCodePromptRequestId(promptId) {
+    return `${exports.COMMAND_CODE_PROMPT_REQUEST_ID_PREFIX}${promptId}`;
+}

package/dist/server/src/types/terminal-keys.js

@@ -19,7 +19,74 @@
  * Values only — no tmux process access — so this module is safe from any layer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TERMINAL_KEY_VALUES = exports.OPENCODE_NAVIGATION_KEY_VALUES = exports.OPENCODE_DIRECT_KEY_VALUES = exports.OPENCODE_LEADER_CHORD_VALUES = exports.OPENCODE_LEADER_KEY = exports.NAVIGATION_KEY_VALUES = void 0;
+exports.TERMINAL_KEY_VALUES = exports.OPENCODE_NAVIGATION_KEY_VALUES = exports.OPENCODE_DIRECT_KEY_VALUES = exports.OPENCODE_LEADER_CHORD_VALUES = exports.OPENCODE_LEADER_KEY = exports.SESSION_SCOPE_KEY_TOOL_IDS = exports.CLAUDE_NAVIGATION_KEY_VALUES = exports.NAVIGATION_KEY_VALUES = exports.SESSION_SCOPE_KEY = exports.ANSWER_KEY_VALUES = void 0;
+/**
+ * The characters a dialog is answered WITH rather than navigated by (Issue #2254).
+ *
+ * `1`–`9` are the option numbers every numbered TUI dialog in this repository
+ * offers (codex's trust / `/model` pickers, claude's `PermissionRequest`
+ * screens, the hooks-review flow), and `y` / `n` are the two letters a bare
+ * `[y/n]` accepts. They are LITERAL characters on the wire, exactly like the
+ * codex pager's `q` has been since #1017 and opencode's chord letters since
+ * #2046 — `tmux send-keys -- 1` types a `1`.
+ *
+ * WHY THEY ARE IN THE BASE VOCABULARY, i.e. offered to every tool
+ * ---------------------------------------------------------------
+ * The state this exists for is "a wait is on screen and nothing could read it"
+ * (`ChatSurface`'s `promptUnreadable`). By construction nobody knows which tool
+ * drew that dialog *shape*, so there is no per-tool declaration to hang these
+ * off; what IS known is that the dialog is waiting for an answer, and that the
+ * chat surface had no way to send one before this Issue — the `/send` route
+ * refuses with `prompt_waiting`, and `/special-keys` published only arrows.
+ *
+ * The cost is the same one #2046 weighed for opencode's letters: a caller may
+ * POST `{cliToolId:"claude", keys:["y"]}` at an IDLE pane and type a `y` into
+ * the composer. That is a typo, not an escalation — the route has always been
+ * able to type `q` into any composer, sending a character is what the route is
+ * FOR, and the UI only draws these buttons while a wait is unreadable. What is
+ * deliberately still refused is a free string: `/send`'s `prompt_waiting` guard
+ * is untouched, `MAX_KEYS_LENGTH` is 10, and every other letter stays a 400.
+ *
+ * Note the overlap with {@link OPENCODE_LEADER_CHORD_VALUES}: `n` is in both,
+ * and `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts` pins the
+ * intersection to exactly `['n']` so a future widening of either list cannot
+ * quietly hand another tool an opencode chord letter.
+ */
+exports.ANSWER_KEY_VALUES = [
+    '1', '2', '3', '4', '5', '6', '7', '8', '9',
+    'y', 'n',
+];
+/**
+ * claude's "use this session only" key (Issue #2297).
+ *
+ * MEASURED on claude 2.1.259 / 2.1.260 (`tests/fixtures/chat-dialog-card-2254/
+ * claude-model-2-1-259.txt`, and a live 200x1000 probe re-run for #2297): the
+ * `/model` overlay's footer reads
+ *
+ *     Enter to set as default · s to use this session only · Esc to cancel
+ *
+ * so on that ONE screen `Enter` is not "confirm" — it rewrites `model` in
+ * `~/.claude/settings.json` (Issue #1495), and `s` is the only key that takes
+ * the highlighted model for the current session and leaves the file alone.
+ * Neither the shared pad nor the transport carried `s`, so the chat surface
+ * could offer the destructive half of that footer and not the safe half.
+ *
+ * A LITERAL character on the wire, exactly like the codex pager's `q` (#1017),
+ * opencode's chord letters (#2046) and the answer characters (#2254):
+ * `tmux send-keys -- s` types an `s`.
+ *
+ * WHY IT IS **NOT** IN {@link NAVIGATION_KEY_VALUES}
+ * -------------------------------------------------
+ * Unlike #2254's answer characters, this one has a named owner. `s` is a live
+ * binding on other tools' screens — copilot's session picker footer reads
+ * `s sort:relevance` (measured on 1.0.82), and opencode types a bare letter
+ * into its composer whenever a leader chord is not in flight. Publishing `s` to
+ * every tool would hand those screens a button that does something else. So it
+ * is declared by the claude-family tools alone, through
+ * {@link CLAUDE_NAVIGATION_KEY_VALUES}, and the route's per-tool check
+ * (Issue #2046) answers 400 for everyone else.
+ */
+exports.SESSION_SCOPE_KEY = 's';
 /**
  * Navigation keys accepted by the special-keys API and the terminal UI.
  *
@@ -34,7 +101,46 @@ exports.NAVIGATION_KEY_VALUES = [
     // Issue #1017: Codex pager / edit-previous mode keys surfaced by NavigationButtons.
     // 'q' is the pager quit key (literal char). PageUp/PageDown/Home/End are tmux named keys.
     'PageUp', 'PageDown', 'Home', 'End', 'q',
+    // Issue #2254: the answer characters. Appended rather than interleaved so the
+    // pre-#2254 prefix of this list is still readable as one line in a diff.
+    ...exports.ANSWER_KEY_VALUES,
 ];
+/**
+ * What a claude-family pane may be sent: the base pad plus
+ * {@link SESSION_SCOPE_KEY} (Issue #2297).
+ *
+ * Returned by `ClaudeTool.navigationKeys()` and `CommandCodeTool.navigationKeys()`
+ * — the two tools whose TUI is claude's inline overlay renderer. Command Code
+ * takes it for kinship rather than for a measured `/model` footer of its own:
+ * its own picker (v1.40.1, measured for this Issue) is a name list with a search
+ * box and an `enter to select · esc to cancel` footer and offers no session
+ * scope at all, so nothing DRAWS the `s` button there — see
+ * `readSelectionListShape()`, which gates the button on the footer being on
+ * screen rather than on the tool id. Declaring the key for both keeps the two
+ * halves of the claude family from drifting apart the day Command Code grows the
+ * footer, and costs nothing while it has not: an undrawn button sends nothing.
+ *
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts` pins the membership
+ * in both directions, and the #2046 suite still pins every OTHER tool to the
+ * base pad exactly.
+ */
+exports.CLAUDE_NAVIGATION_KEY_VALUES = [
+    ...exports.NAVIGATION_KEY_VALUES,
+    exports.SESSION_SCOPE_KEY,
+];
+/**
+ * The tool ids whose `navigationKeys()` carry {@link SESSION_SCOPE_KEY}.
+ *
+ * Read by the chat surface, which cannot call `navigationKeys()` — that lives
+ * behind the CLITool gateway on the server — but must not draw a button whose
+ * key the route would answer 400 for. Pinned against the real registry by
+ * `tests/unit/lib/cli-tools/session-scope-key-2297.test.ts`, so this list and
+ * the declarations cannot disagree.
+ *
+ * Typed as a plain string tuple rather than `CLIToolType[]` so this module keeps
+ * the "values only, safe from any layer" property its header depends on.
+ */
+exports.SESSION_SCOPE_KEY_TOOL_IDS = ['claude', 'command-code'];
 // ---------------------------------------------------------------------------
 // Per-tool vocabularies (Issue #2046)
 // ---------------------------------------------------------------------------
@@ -74,6 +180,25 @@ exports.OPENCODE_LEADER_CHORD_VALUES = [
  * `Tab` / `BTab` cycle the agent and are already in {@link NAVIGATION_KEY_VALUES}.
  */
 exports.OPENCODE_DIRECT_KEY_VALUES = ['C-p', 'C-t'];
+/**
+ * {@link OPENCODE_LEADER_CHORD_VALUES} minus what the base pad already carries.
+ *
+ * Issue #2254 moved `n` into {@link ANSWER_KEY_VALUES}, and therefore into
+ * {@link NAVIGATION_KEY_VALUES}, which every tool's declaration starts from —
+ * so spreading the full chord list into the two unions below would list `n`
+ * twice. A duplicate is harmless to `Array.prototype.includes`, which is all the
+ * route does with these, and that is exactly why it needs its own guard: the
+ * only thing that would notice is the "no duplicate entries" assertion in
+ * `tests/unit/cli-tools/navigation-keys-declaration-2046.test.ts`.
+ *
+ * Written out rather than filtered at runtime because both unions are `as const`
+ * tuples whose LITERAL member types are the `TerminalKey` union — a
+ * `.filter()` would collapse them to `string[]` and take the compile-time check
+ * with it. The same suite pins this list to
+ * `OPENCODE_LEADER_CHORD_VALUES \ NAVIGATION_KEY_VALUES` so it cannot drift out
+ * of step with either side.
+ */
+const OPENCODE_CHORD_ONLY_VALUES = ['a', 'l', 't', 'm', 'g', 'u', 'r', 'c'];
 /**
  * Everything an opencode pane may be sent — the base navigation pad plus this
  * tool's own chords. Returned by `OpenCodeTool.navigationKeys()`.
@@ -82,7 +207,7 @@ exports.OPENCODE_NAVIGATION_KEY_VALUES = [
     ...exports.NAVIGATION_KEY_VALUES,
     exports.OPENCODE_LEADER_KEY,
     ...exports.OPENCODE_DIRECT_KEY_VALUES,
-    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+    ...OPENCODE_CHORD_ONLY_VALUES,
 ];
 /**
  * The union of every tool's vocabulary — what the tmux transport must be able to
@@ -99,7 +224,10 @@ exports.OPENCODE_NAVIGATION_KEY_VALUES = [
  */
 exports.TERMINAL_KEY_VALUES = [
     ...exports.NAVIGATION_KEY_VALUES,
+    // Issue #2297: claude / Command Code declare it; nothing else does.
+    exports.SESSION_SCOPE_KEY,
     exports.OPENCODE_LEADER_KEY,
     ...exports.OPENCODE_DIRECT_KEY_VALUES,
-    ...exports.OPENCODE_LEADER_CHORD_VALUES,
+    // Issue #2254: `n` is in the base pad now — see OPENCODE_CHORD_ONLY_VALUES.
+    ...OPENCODE_CHORD_ONLY_VALUES,
 ];