commandmate 0.17.0 → 0.19.0

package/dist/server/src/lib/tmux/read-mode.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Reading mode: `prefix+g` opens a squeezed transcript in a tmux popup (Issue #1623, 案A).
+ *
+ * Attaching to a CommandMate session shows nothing readable. The pane is pinned to
+ * 200x1000 (Issue #1163), the agent draws its composer at the bottom and its
+ * transcript at the top, and tmux follows the cursor — which sits at row 997.
+ * Measured on a live session: an attached 72-row client sees ZERO transcript rows.
+ * This module adds an on-demand way to read, WITHOUT touching the geometry that
+ * status detection, Auto-Yes and the response saver depend on.
+ *
+ * ## This module mutates state CommandMate does not own — read before changing it
+ *
+ * `bind-key` writes the tmux server's GLOBAL prefix key table. Every session on
+ * that server inherits it, including ones CommandMate knows nothing about. Four
+ * guards keep that intervention honest, and all four are load-bearing:
+ *
+ * 1. **Capability probe.** `display-popup` is tmux 3.2+. Measured on 3.5a:
+ *    `tmux list-commands <unknown>` exits 0 with EMPTY stdout, so the exit code is
+ *    useless as a probe — the presence of output is the signal. Older tmux gets
+ *    no binding at all (a genuine no-op), and the CLI viewer is the fallback.
+ * 2. **Conflict check.** `list-keys -T prefix <key>` exits 1 with `unknown key`
+ *    when the key is free and exits 0 printing the binding when it is taken. A key
+ *    already bound to something that is not ours is left ALONE. The Issue's claim
+ *    that `prefix+g` is unbound on stock tmux 3.5a is true here, but says nothing
+ *    about a user's own `.tmux.conf`.
+ * 3. **Session-name guard.** The binding fires `if-shell -F '#{m:mcbd-*,...}'`, so
+ *    pressing the key in a non-CommandMate session does nothing (measured: the
+ *    format yields 1 for `mcbd-*` sessions and 0 for everything else).
+ * 4. **Opt-out that converges.** `CM_READ_MODE=off` does not merely skip
+ *    installation — it REMOVES a binding a previous run installed. That is the
+ *    uninstall path, and it is why shutdown does not unbind (see below).
+ *
+ * ## Why shutdown does not unbind
+ *
+ * CommandMate supports several servers at once (`commandmate start --issue N`),
+ * all sharing one tmux server. Unbinding when one of them stops would rip the key
+ * out from under the others, and the popup needs no CommandMate server to work —
+ * it only shells out to tmux. Removal is therefore an explicit user action
+ * (`CM_READ_MODE=off` + restart), not a shutdown side effect.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_READ_MODE_KEY = exports.MCBD_SESSION_PREFIX = void 0;
+exports.getPagerScriptPath = getPagerScriptPath;
+exports.isReadModeEnabled = isReadModeEnabled;
+exports.resolveReadModeKey = resolveReadModeKey;
+exports.quoteForTmuxCommand = quoteForTmuxCommand;
+exports.buildBindKeyArgs = buildBindKeyArgs;
+exports.supportsDisplayPopup = supportsDisplayPopup;
+exports.readExistingBinding = readExistingBinding;
+exports.materializePagerScript = materializePagerScript;
+exports.buildUnbindKeyArgs = buildUnbindKeyArgs;
+exports.reconcileReadModeBinding = reconcileReadModeBinding;
+exports.initReadMode = initReadMode;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const os_1 = require("os");
+const path_1 = require("path");
+const fs_1 = require("fs");
+const read_mode_pager_1 = require("./read-mode-pager");
+const logger_1 = require("../logger");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const logger = (0, logger_1.createLogger)('tmux-read-mode');
+/** tmux calls here are interactive-latency, not long-running. */
+const TMUX_TIMEOUT = 5000;
+/**
+ * Session-name prefix every CommandMate tmux session carries.
+ *
+ * Not imported from `cli-tools/base.ts` because it is a template literal there,
+ * not a constant. `tests/unit/lib/tmux/read-mode.test.ts` asserts that a real
+ * `getSessionName()` still starts with this, so a rename breaks the test instead
+ * of silently turning the guard into a permanent "never fire".
+ */
+exports.MCBD_SESSION_PREFIX = 'mcbd-';
+/** Key bound under the prefix table when `CM_READ_MODE_KEY` is unset. */
+exports.DEFAULT_READ_MODE_KEY = 'g';
+/**
+ * Accepted `CM_READ_MODE_KEY` values: a single alphanumeric, an F-key, either
+ * optionally with a `C-` / `M-` / `S-` modifier. Deliberately narrow — a typo
+ * should be rejected loudly rather than bound to something surprising in the
+ * user's global key table.
+ */
+const READ_MODE_KEY_PATTERN = /^(?:[CMS]-)?(?:[A-Za-z0-9]|F(?:[1-9]|1[0-2]))$/;
+/** Popup geometry. Large enough to read, small enough to still see it is a popup. */
+const POPUP_WIDTH = '90%';
+const POPUP_HEIGHT = '85%';
+/**
+ * Absolute path of the materialized pager script.
+ *
+ * Always under `~/.commandmate/`, never the install directory and never the cwd:
+ * `bind-key` is server-global and long-lived, so the path it names has to outlive
+ * a `npx` cache eviction or a `cd`.
+ */
+function getPagerScriptPath() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'bin', read_mode_pager_1.PAGER_SCRIPT_FILENAME);
+}
+/** True unless the user set `CM_READ_MODE=off` (or `0` / `false`). */
+function isReadModeEnabled() {
+    const raw = (process.env.CM_READ_MODE ?? '').trim().toLowerCase();
+    return raw !== 'off' && raw !== '0' && raw !== 'false';
+}
+/**
+ * Resolve the configured key, or undefined when it is malformed.
+ * @returns The key to bind, or undefined if `CM_READ_MODE_KEY` fails validation
+ */
+function resolveReadModeKey() {
+    const raw = (process.env.CM_READ_MODE_KEY ?? '').trim();
+    if (raw === '')
+        return exports.DEFAULT_READ_MODE_KEY;
+    return READ_MODE_KEY_PATTERN.test(raw) ? raw : undefined;
+}
+/**
+ * Quote a path for the shell-command tmux stores in a binding.
+ *
+ * tmux lexes the stored command itself before handing words to `/bin/sh`, so the
+ * quoting has to survive that pass. POSIX `'...'` with `'\''` for embedded quotes
+ * satisfies both. Returns undefined for a path that cannot be represented (a
+ * newline has no single-quoted form tmux will parse), which callers treat as
+ * "do not install".
+ */
+function quoteForTmuxCommand(path) {
+    if (path.includes('\n') || path.includes('\r'))
+        return undefined;
+    return `'${path.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * The exact `bind-key` argument vector for a given key and script path.
+ * Exported so tests assert the wire form rather than a paraphrase of it.
+ */
+function buildBindKeyArgs(key, quotedScriptPath) {
+    return [
+        'bind-key',
+        '-T',
+        'prefix',
+        key,
+        'if-shell',
+        '-F',
+        `#{m:${exports.MCBD_SESSION_PREFIX}*,#{session_name}}`,
+        `display-popup -w ${POPUP_WIDTH} -h ${POPUP_HEIGHT} -E ${quotedScriptPath}`,
+    ];
+}
+/**
+ * Whether this tmux understands `display-popup` (3.2+).
+ *
+ * Probes on OUTPUT, not exit status: measured on 3.5a, `list-commands` exits 0
+ * for an unknown command name and simply prints nothing.
+ */
+async function supportsDisplayPopup() {
+    try {
+        const { stdout } = await execFileAsync('tmux', ['list-commands', 'display-popup'], {
+            timeout: TMUX_TIMEOUT,
+        });
+        return stdout.trim() !== '';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Current prefix-table binding for `key`, or undefined when the key is free.
+ *
+ * @param key - tmux key name
+ * @returns The `bind-key ...` line tmux reports, or undefined if unbound
+ */
+async function readExistingBinding(key) {
+    try {
+        const { stdout } = await execFileAsync('tmux', ['list-keys', '-T', 'prefix', key], {
+            timeout: TMUX_TIMEOUT,
+        });
+        const line = stdout.trim();
+        return line === '' ? undefined : line;
+    }
+    catch {
+        // Exit 1 + `unknown key: <k>` on stderr is how tmux reports "not bound".
+        return undefined;
+    }
+}
+/**
+ * Write the pager script to {@link getPagerScriptPath}, if its content changed.
+ *
+ * Idempotent by content comparison so a restart does not churn the file's mtime,
+ * and re-executable after a `chmod` accident because the mode is re-applied.
+ *
+ * @returns The absolute path written
+ */
+function materializePagerScript() {
+    const scriptPath = getPagerScriptPath();
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(scriptPath), { recursive: true });
+    let current;
+    if ((0, fs_1.existsSync)(scriptPath)) {
+        try {
+            current = (0, fs_1.readFileSync)(scriptPath, 'utf-8');
+        }
+        catch {
+            current = undefined;
+        }
+    }
+    if (current !== read_mode_pager_1.PAGER_SCRIPT) {
+        (0, fs_1.writeFileSync)(scriptPath, read_mode_pager_1.PAGER_SCRIPT, { mode: 0o755 });
+    }
+    (0, fs_1.chmodSync)(scriptPath, 0o755);
+    return scriptPath;
+}
+/**
+ * The exact argument vector that removes the binding again.
+ *
+ * Paired with {@link buildBindKeyArgs} and exported for the same reason: the
+ * install and uninstall paths are asserted against these builders rather than
+ * against re-typed literals, so a test cannot drift from what actually runs —
+ * and `tests/unit/config/tmux-live-test-safety.test.ts` keeps its meaning,
+ * because the mutating verbs appear in exactly one place, here in `src/`.
+ */
+function buildUnbindKeyArgs(key) {
+    return ['unbind-key', '-T', 'prefix', key];
+}
+/**
+ * Remove the binding, but ONLY when it is still the one we installed.
+ *
+ * A user who rebound the key after us owns it now; clobbering that would be the
+ * same rudeness the conflict check exists to avoid.
+ */
+async function removeOwnBinding(key, scriptPath) {
+    const existing = await readExistingBinding(key);
+    if (existing === undefined)
+        return 'not-installed';
+    if (!existing.includes(scriptPath))
+        return 'key-conflict';
+    await execFileAsync('tmux', buildUnbindKeyArgs(key), { timeout: TMUX_TIMEOUT });
+    return 'removed';
+}
+/**
+ * Reconcile the tmux prefix key table with the configured reading-mode state.
+ *
+ * Safe to call on every server start: installing twice is a no-op, and the
+ * disabled path removes what an earlier run installed. Never throws — reading
+ * mode is a convenience, and no failure here may keep the server from starting.
+ *
+ * @returns What was done, for logging and for tests
+ */
+async function reconcileReadModeBinding() {
+    const key = resolveReadModeKey();
+    const scriptPath = getPagerScriptPath();
+    if (key === undefined) {
+        return {
+            installed: false,
+            outcome: 'invalid-key',
+            key: process.env.CM_READ_MODE_KEY ?? '',
+            scriptPath,
+            detail: 'CM_READ_MODE_KEY must be a single alphanumeric or F-key, optionally with a C-/M-/S- modifier',
+        };
+    }
+    try {
+        if (!isReadModeEnabled()) {
+            const outcome = await removeOwnBinding(key, scriptPath);
+            return { installed: false, outcome, key, scriptPath, detail: 'CM_READ_MODE=off' };
+        }
+        if (!(await supportsDisplayPopup())) {
+            return {
+                installed: false,
+                outcome: 'unsupported-tmux',
+                key,
+                scriptPath,
+                detail: 'display-popup requires tmux 3.2+; use `commandmate capture <id> --pane` instead',
+            };
+        }
+        const quoted = quoteForTmuxCommand(scriptPath);
+        if (quoted === undefined) {
+            return { installed: false, outcome: 'unsafe-script-path', key, scriptPath };
+        }
+        const existing = await readExistingBinding(key);
+        if (existing !== undefined && !existing.includes(scriptPath)) {
+            return {
+                installed: false,
+                outcome: 'key-conflict',
+                key,
+                scriptPath,
+                detail: `prefix+${key} is already bound: ${existing}`,
+            };
+        }
+        materializePagerScript();
+        await execFileAsync('tmux', buildBindKeyArgs(key, quoted), { timeout: TMUX_TIMEOUT });
+        return {
+            installed: true,
+            outcome: existing === undefined ? 'installed' : 'already-installed',
+            key,
+            scriptPath,
+        };
+    }
+    catch (error) {
+        return {
+            installed: false,
+            outcome: 'error',
+            key,
+            scriptPath,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Startup entry point: reconcile and log the outcome once.
+ *
+ * `server.ts` must reach this through `await import()`, never a top-level static
+ * import — pulling module graphs into server.ts's eval-time graph perturbs Next's
+ * AsyncLocalStorage bootstrap under `tsx server.ts` and the first request that
+ * compiles middleware dies (see the Skill reconciler note in server.ts).
+ */
+async function initReadMode() {
+    const status = await reconcileReadModeBinding();
+    switch (status.outcome) {
+        case 'installed':
+        case 'already-installed':
+            logger.info('read-mode:ready', { key: status.key, scriptPath: status.scriptPath });
+            break;
+        case 'removed':
+        case 'not-installed':
+        case 'disabled':
+            logger.info('read-mode:disabled', { key: status.key, outcome: status.outcome });
+            break;
+        default:
+            logger.warn('read-mode:not-installed', {
+                outcome: status.outcome,
+                key: status.key,
+                detail: status.detail,
+            });
+    }
+    return status;
+}

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

@@ -198,7 +198,7 @@ async function listSessions() {
  * await createSession({
  *   sessionName: 'my-session',
  *   workingDirectory: '/path/to/project',
- *   historyLimit: 50000,
+ *   historyLimit: TMUX_HISTORY_LIMIT,
  * });
  * ```
  */
@@ -212,7 +212,7 @@ async function createSession(sessionNameOrOptions, cwd) {
         // Legacy signature
         sessionName = sessionNameOrOptions;
         workingDirectory = cwd;
-        historyLimit = 50000;
+        historyLimit = tmux_pane_config_1.TMUX_HISTORY_LIMIT;
         windowWidth = tmux_pane_config_1.TUI_PANE_WIDTH;
         windowHeight = tmux_pane_config_1.TUI_PANE_HEIGHT;
     }
@@ -220,7 +220,7 @@ async function createSession(sessionNameOrOptions, cwd) {
         // New signature with options
         sessionName = sessionNameOrOptions.sessionName;
         workingDirectory = sessionNameOrOptions.workingDirectory;
-        historyLimit = sessionNameOrOptions.historyLimit || 50000;
+        historyLimit = sessionNameOrOptions.historyLimit || tmux_pane_config_1.TMUX_HISTORY_LIMIT;
         windowWidth = sessionNameOrOptions.windowWidth || tmux_pane_config_1.TUI_PANE_WIDTH;
         windowHeight = sessionNameOrOptions.windowHeight || tmux_pane_config_1.TUI_PANE_HEIGHT;
     }
@@ -228,6 +228,40 @@ async function createSession(sessionNameOrOptions, cwd) {
         // Create session with explicit window size to avoid 80x24 default
         // This is critical for TUI tools (Copilot, OpenCode) that use alternate screen
         await execFileAsync('tmux', ['new-session', '-d', '-s', sessionName, '-c', workingDirectory, '-x', String(windowWidth), '-y', String(windowHeight)], { timeout: DEFAULT_TIMEOUT });
+        // Issue #1624: `history-limit` must be set BEFORE the pane that uses it exists.
+        //
+        // It is a session option, but a pane sizes its scrollback buffer ONCE, from
+        // the value in effect at pane-creation time. `new-session` above already
+        // created window 0 and its pane, so the old order (new-session → set-option)
+        // left every pane on tmux's built-in 2000 lines while `show-options` happily
+        // reported 50000 — the session option was set, and utterly inert. Measured on
+        // tmux 3.5a: pane `#{history_limit}` stayed 2000, and a live
+        // `mcbd-codex-*` session sat at 1977/2000 lines used, silently dropping the
+        // oldest transcript. `respawn-pane -k` does NOT fix it either (the pane reuses
+        // its existing buffer); only creating a NEW pane does.
+        await execFileAsync('tmux', ['set-option', '-t', exactTarget(sessionName), 'history-limit', String(historyLimit)], { timeout: DEFAULT_TIMEOUT });
+        // Rebuild window 0 IN PLACE so its pane is allocated against the option just
+        // set. `-k` replaces the existing window at index 0 rather than appending,
+        // which keeps `#{window_index}` at 0 and the session at exactly one window —
+        // no call site has to care that the window was recreated.
+        //
+        // `-c` is REQUIRED and not redundant: a bare `new-window` does NOT inherit the
+        // session's `-c` directory, it starts in the tmux CLIENT's cwd (verified: a
+        // session created with `-c /usr/local` produced a pane in the server process's
+        // cwd instead). Omitting it silently launches every agent in the wrong repo.
+        //
+        // Best-effort, matching the geometry step below: if this fails the session is
+        // still usable, just with tmux's default 2000-line scrollback.
+        try {
+            await execFileAsync('tmux', ['new-window', '-k', '-t', `${exactTarget(sessionName)}0`, '-c', workingDirectory], { timeout: DEFAULT_TIMEOUT });
+        }
+        catch (error) {
+            logger.warn('session-history-limit:window-rebuild-failed', {
+                sessionName,
+                historyLimit,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
         // Issue #1163: Pin the pane to a fixed height so alternate-screen TUIs
         // (Claude/Codex/etc.) keep enough visible rows for capture-pane.
         //
@@ -239,9 +273,13 @@ async function createSession(sessionNameOrOptions, cwd) {
         // tracking (the global option is never touched), and an explicit
         // `resize-window` then locks in the intended geometry. Best-effort: a failure
         // here must not abort session creation (some environments restrict resize).
+        //
+        // Issue #1624: this MUST stay AFTER the window rebuild above. A window created
+        // by `new-window` does not inherit `window-size manual` from the window it
+        // 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 });
-        // Set history limit
-        await execFileAsync('tmux', ['set-option', '-t', exactTarget(sessionName), 'history-limit', String(historyLimit)], { timeout: DEFAULT_TIMEOUT });
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.17.0",
+  "version": "0.19.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",