commandmate 0.18.0 → 0.19.0

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

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * The shell pager that `prefix+g` opens inside a tmux popup (Issue #1623, 案A).
+ *
+ * ## Why the script is embedded here instead of shipped as a file
+ *
+ * `package.json`'s `files` list publishes `bin/`, `dist/`, `.next/`, `public/`,
+ * `scripts/hooks/` and `.env.example` — NOT `scripts/`. A path into the repo
+ * therefore does not exist in a global install, and an `npx` install lives in a
+ * cache directory npm may garbage-collect out from under a long-lived `bind-key`.
+ * Embedding the text and materializing it into `~/.commandmate/bin/` gives the
+ * binding one absolute path that is stable across global / local / npx installs.
+ *
+ * ## Why the squeeze is reimplemented in awk
+ *
+ * The popup must not depend on the CommandMate server, a node binary, or a built
+ * `dist/` — it only has tmux and a shell. awk is present everywhere those are.
+ * The duplication is not left to trust: `tests/unit/lib/tmux/transcript-squeeze.test.ts`
+ * runs THIS awk program over real captures and asserts byte equality with
+ * `squeezeTranscript()`, so the two cannot drift apart silently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAGER_SCRIPT = exports.PAGER_SCRIPT_FILENAME = exports.SQUEEZE_AWK_PROGRAM = exports.SQUEEZE_AWK_LOCALE = void 0;
+/**
+ * Locale the squeeze awk program MUST run under.
+ *
+ * Not cosmetic — the program is byte-oriented by construction, and `%c` is the
+ * one place where awk implementations disagree about what a "character" is:
+ *
+ * | awk                     | `sprintf("%c", 194)` |
+ * |-------------------------|----------------------|
+ * | mawk, BWK awk           | byte `0xC2`          |
+ * | gawk, `LC_ALL=C`        | byte `0xC2`          |
+ * | gawk, `*.UTF-8` locale  | U+00C2 -> `C3 82`    |
+ *
+ * `NBSP` below is assembled from bytes `C2 A0`, so under gawk in a UTF-8 locale
+ * it becomes a four-byte string that can never match a real NBSP — NBSP-only
+ * rows stop counting as blank and the frame comes back unsqueezed. That is not
+ * hypothetical: it is exactly how this shipped broken, green on macOS (BWK awk)
+ * and red on `ubuntu-latest`, whose `/usr/bin/awk` is gawk (Debian ranks the
+ * gawk alternative above mawk) under a UTF-8 locale.
+ *
+ * Pinning the locale — rather than making the regex match both encodings — is
+ * deliberate: an alternation covering the character form
+ * (`sprintf("%c%c",194,160) "|" sprintf("%c",160)`) fixes gawk but makes BWK awk
+ * abort with `multibyte conversion failure` in a UTF-8 locale. Measured on all
+ * three implementations, `LC_ALL=C` is the only setting where every one of them
+ * agrees, and it is byte-transparent: the same 1000-row fixture comes out with
+ * an identical sha256 from BWK awk, mawk and gawk.
+ *
+ * Scoped to the awk process alone, so `less` and tmux keep the user's locale and
+ * still render UTF-8 box drawing.
+ */
+exports.SQUEEZE_AWK_LOCALE = 'C';
+/**
+ * awk implementation of {@link import('./transcript-squeeze').squeezeTranscript}.
+ *
+ * Mirrors the TypeScript rules exactly:
+ * - `ANSI` is built from `sprintf("%c")` rather than a regex literal because
+ *   `\033` / `\a` escapes inside a regex literal are not portable across awk
+ *   implementations (macOS ships BWK awk, Linux usually gawk/mawk).
+ * - NBSP (UTF-8 `C2 A0`) is folded to a space before trimming, because
+ *   JavaScript's `.trim()` treats U+00A0 as whitespace and awk's `[ \t]` does not.
+ *   Without this the two implementations disagree on NBSP-only rows. This is the
+ *   line that requires {@link SQUEEZE_AWK_LOCALE} — read that doc before editing.
+ * - Leading/trailing blank runs are dropped, runs of 1-2 kept verbatim, runs of
+ *   3+ collapsed to a single row carrying the run's ANSI sequences.
+ */
+exports.SQUEEZE_AWK_PROGRAM = `BEGIN {
+  ESC = sprintf("%c", 27); BEL = sprintf("%c", 7); NBSP = sprintf("%c%c", 194, 160)
+  ANSI = ESC "\\\\[[0-9;]*[a-zA-Z]|" ESC "\\\\][^" BEL "]*" BEL "|\\\\[[0-9;]*m"
+  n = 0
+}
+{ line[++n] = $0 }
+END {
+  for (i = 1; i <= n; i++) {
+    s = line[i]; gsub(ANSI, "", s); gsub(NBSP, " ", s)
+    gsub(/^[ \\t\\r\\f\\v]+|[ \\t\\r\\f\\v]+$/, "", s)
+    blank[i] = (s == "")
+  }
+  seen = 0; i = 1
+  while (i <= n) {
+    if (!blank[i]) { print line[i]; seen = 1; i++; continue }
+    j = i; while (j <= n && blank[j]) j++
+    if (seen && j <= n) {
+      if (j - i <= 2) { for (k = i; k < j; k++) print line[k] }
+      else {
+        joined = ""; for (k = i; k < j; k++) joined = joined line[k]
+        keep = ""
+        while (match(joined, ANSI)) {
+          keep = keep substr(joined, RSTART, RLENGTH); joined = substr(joined, RSTART + RLENGTH)
+        }
+        print keep
+      }
+    }
+    i = j
+  }
+}`;
+/** Basename of the materialized script. */
+exports.PAGER_SCRIPT_FILENAME = 'cm-read-pane.sh';
+/**
+ * Full text of the pager script.
+ *
+ * Session resolution is done INSIDE the script on purpose. `display-popup` does
+ * NOT expand tmux formats in its shell-command (measured on 3.5a: a literal
+ * `#{session_name}` reaches the shell unexpanded), so the session cannot be baked
+ * into the binding. `tmux display-message -p` inside the popup returns the correct
+ * session and client, which is what makes one global binding serve every session.
+ *
+ * `=NAME:` is the exact-match target form required by Issue #1156 — a bare name
+ * prefix-matches and would show the `-2` instance's pane while the primary is
+ * stopped.
+ */
+exports.PAGER_SCRIPT = `#!/bin/sh
+# CommandMate reading mode (Issue #1623) — generated file, edits are overwritten.
+#
+# Renders the transcript of a CommandMate tmux session with layout-only blank rows
+# squeezed away, so a pager lands on the composer instead of hundreds of rows of
+# padding. Invoked by \`prefix+g\` through \`display-popup -E\`; also runnable by hand:
+#
+#   sh ~/.commandmate/bin/${exports.PAGER_SCRIPT_FILENAME} mcbd-claude-my-worktree
+#
+# The popup is a SNAPSHOT. Press the key again to refresh it.
+set -u
+
+SESSION="\${1:-}"
+if [ -z "$SESSION" ]; then
+  SESSION=$(tmux display-message -p '#{session_name}' 2>/dev/null) || SESSION=""
+fi
+if [ -z "$SESSION" ]; then
+  echo "cm-read-pane: no tmux session given and none could be resolved" >&2
+  exit 1
+fi
+
+LINES_BACK="\${CM_READ_LINES:-1000}"
+case "$LINES_BACK" in
+  ''|*[!0-9]*) LINES_BACK=1000 ;;
+esac
+
+if [ -n "\${CM_READ_PAGER:-}" ]; then
+  PAGER_CMD="$CM_READ_PAGER"
+elif command -v less >/dev/null 2>&1; then
+  PAGER_CMD="less -R +G"
+else
+  PAGER_CMD="cat"
+fi
+
+# LC_ALL is pinned for awk ONLY (not for less, which still renders UTF-8 box
+# drawing in the user's locale). Under gawk in a UTF-8 locale, sprintf("%c",194)
+# yields U+00C2 rather than the byte 0xC2 and the NBSP fold below silently stops
+# matching. See SQUEEZE_AWK_LOCALE in read-mode-pager.ts.
+tmux capture-pane -pe -t "=$SESSION:" -S "-$LINES_BACK" -E - \\
+  | LC_ALL=${exports.SQUEEZE_AWK_LOCALE} awk '${exports.SQUEEZE_AWK_PROGRAM}' \\
+  | $PAGER_CMD
+
+# Without a pager the popup would close before anything could be read.
+if [ "$PAGER_CMD" = "cat" ]; then
+  printf '\\n[CommandMate] end of transcript — press Enter to close.' >&2
+  read -r _unused || true
+fi
+`;

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.18.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",