commandmate 0.18.0 → 0.20.0

package/dist/server/src/lib/tmux/control-mode-tmux-transport.js

@@ -69,6 +69,13 @@ class ControlModeTmuxTransport {
     getSubscriberCount(sessionName) {
         return this.registry.getSubscriberCount(sessionName);
     }
+    /**
+     * Re-file a live control-mode attach after the tmux session was renamed
+     * (Issue #1621 Phase 3). See TmuxControlRegistry.renameSession.
+     */
+    renameSession(oldName, newName) {
+        return this.registry.renameSession(oldName, newName);
+    }
     async killSession(sessionName) {
         return (0, tmux_1.killSession)(sessionName);
     }

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,347 @@
+"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`.
+ *    ORDER IS LOAD-BEARING: guard 1 runs first, and must keep doing so. On tmux
+ *    3.0 and older `list-keys` takes no key argument either (`usage: list-keys
+ *    [-T key-table]`, measured in #1641), so this check degrades to "the key is
+ *    always free" there. It is harmless only because those versions never reach
+ *    it — guard 1 has already returned `unsupported-tmux`.
+ * 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 against real binaries in
+ * containers (Issue #1641; harness: `scripts/verify-legacy-tmux-readmode.sh`):
+ *
+ * | tmux | `list-commands display-popup` | verdict |
+ * |---|---|---|
+ * | 2.8 / 3.0a | exit 1, `usage: list-commands [-F format]` | false |
+ * | 3.1c | exit 0, EMPTY stdout | false |
+ * | 3.3a / 3.5a | exit 0, the command's help line | true |
+ *
+ * Two different reasons produce the same right answer, and only the output test
+ * covers both: an exit-code probe calls 3.1c capable, and a stderr probe calls
+ * 3.3a incapable.
+ *
+ * NOT a general-purpose capability prober. On tmux 3.0 and older `list-commands`
+ * takes no command argument at all, so it answers `usage:` for names that tmux
+ * DOES support — reusing this shape for a command that predates 3.1 would report
+ * a false negative on every old tmux.
+ */
+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-capture-cache.js

@@ -20,6 +20,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CACHE_MAX_CAPTURE_LINES = exports.CACHE_MAX_ENTRIES = exports.CACHE_TTL_MS = void 0;
+exports.isCaptureWindowSaturated = isCaptureWindowSaturated;
 exports.sliceOutput = sliceOutput;
 exports.getCachedCapture = getCachedCapture;
 exports.setCachedCapture = setCachedCapture;
@@ -45,6 +46,38 @@ exports.CACHE_TTL_MS = 5000;
 exports.CACHE_MAX_ENTRIES = 100;
 /** Maximum capture lines for cache storage */
 exports.CACHE_MAX_CAPTURE_LINES = 10000;
+// =========================================================================
+// isCaptureWindowSaturated()
+// =========================================================================
+/**
+ * Whether a capture came back clipped by the capture window (Issue #1670).
+ *
+ * Every capture in this app is a SLIDING WINDOW over the tail of the pane, not a
+ * view of the whole buffer: `captureSessionOutput()` asks tmux for
+ * `-S -CACHE_MAX_CAPTURE_LINES` and `sliceOutput()` then keeps only the last
+ * `requestedLines` rows. So the returned line count is
+ * `min(pane_scrollback + pane_height, windowLines)`.
+ *
+ * While the pane holds fewer rows than the window, that count GROWS with the
+ * transcript, which is what makes `session_states.last_captured_line` usable as a
+ * "how far have I read" cursor. Once the pane outgrows the window the count is
+ * pinned at `windowLines` forever and the window merely slides: a line index
+ * recorded earlier no longer denotes the same line, and no later capture can ever
+ * report a larger count. Callers must stop trusting the cursor at that point —
+ * see `usesAlternateScreen` in lib/cli-tools/types.ts for the sibling condition
+ * (#1268), where the same thing happens at `pane_height` instead.
+ *
+ * Raising `windowLines` does not avoid this; it only moves where it happens
+ * (`TMUX_HISTORY_LIMIT` is the hard ceiling), which is why the check is written
+ * against the window in use rather than against a specific constant.
+ *
+ * @param capturedLineCount - Number of lines the capture actually returned
+ * @param windowLines - Size of the capture window that produced it
+ * @returns True when the capture was clipped, i.e. the line count is no longer a cursor
+ */
+function isCaptureWindowSaturated(capturedLineCount, windowLines = exports.CACHE_MAX_CAPTURE_LINES) {
+    return windowLines > 0 && capturedLineCount >= windowLines;
+}
 function getCache() {
     return (globalThis.__tmuxCaptureCache ??= new Map());
 }

package/dist/server/src/lib/tmux/tmux-control-client.js

@@ -101,6 +101,18 @@ class TmuxControlClient {
     isStarted() {
         return this.started;
     }
+    /**
+     * Point this client's bookkeeping at a session that has been renamed
+     * underneath it (Issue #1621 Phase 3).
+     *
+     * The attach itself needs no repair: `attach-session` binds to the session
+     * object, not to its name, so a `rename-session` leaves the child process,
+     * its pipe and its scrollback untouched (measured in #1621). Only the name
+     * this client reports in its logs would otherwise go stale.
+     */
+    setSessionName(sessionName) {
+        this.sessionName = sessionName;
+    }
     emit(event) {
         for (const handler of this.handlers) {
             handler(event);

package/dist/server/src/lib/tmux/tmux-control-registry.js

@@ -70,6 +70,45 @@ class TmuxControlRegistry {
         this.handlers.clear();
         this.updateMetrics();
     }
+    /**
+     * Re-file a live control-mode attach under a session's new name
+     * (Issue #1621 Phase 3).
+     *
+     * `rename-session` does not disturb an attached control client, so the child
+     * process, its pipe and its scrollback all survive — what breaks is this
+     * registry, which is keyed by name. Without re-keying, `sendInput(newName)`
+     * throws "No control client registered" while a perfectly healthy attach sits
+     * under the old key: the session is alive but input no longer reaches it.
+     * Re-keying is therefore strictly better than tearing the attach down and
+     * re-establishing it, and it keeps every subscriber connected.
+     *
+     * @returns true when an entry was moved; false when nothing was registered
+     *          under `oldName`, or when `newName` is already registered (the
+     *          existing attach wins — clobbering it would strand a live child
+     *          process with no way to stop it)
+     */
+    renameSession(oldName, newName) {
+        if (oldName === newName)
+            return false;
+        const entry = this.entries.get(oldName);
+        if (!entry)
+            return false;
+        if (this.entries.has(newName)) {
+            logger.warn('rename:destination-occupied', { oldName, newName });
+            return false;
+        }
+        this.entries.delete(oldName);
+        entry.sessionName = newName;
+        this.entries.set(newName, entry);
+        entry.client.setSessionName(newName);
+        const handlers = this.handlers.get(oldName);
+        if (handlers) {
+            this.handlers.delete(oldName);
+            this.handlers.set(newName, handlers);
+        }
+        logger.debug('rename', { oldName, newName });
+        return true;
+    }
     ensureEntry(sessionName) {
         const existing = this.entries.get(sessionName);
         if (existing) {
@@ -77,23 +116,26 @@ class TmuxControlRegistry {
         }
         const client = this.createClient(sessionName);
         client.start(sessionName);
-        const unsubscribeClientEvent = client.onEvent((event) => {
-            const handlers = this.handlers.get(sessionName);
+        const entry = {
+            client,
+            subscribers: new Set(),
+            // Replaced immediately below; the entry has to exist first so the event
+            // handler can read its current name rather than capture the old one.
+            unsubscribeClientEvent: () => { },
+            idleTimer: null,
+            sessionName,
+        };
+        entry.unsubscribeClientEvent = client.onEvent((event) => {
+            const handlers = this.handlers.get(entry.sessionName);
             if (handlers) {
                 for (const handler of handlers) {
                     handler(event);
                 }
             }
             if (event.type === 'exit' || event.type === 'error') {
-                this.deleteEntry(sessionName);
+                this.deleteEntry(entry.sessionName);
             }
         });
-        const entry = {
-            client,
-            subscribers: new Set(),
-            unsubscribeClientEvent,
-            idleTimer: null,
-        };
         this.entries.set(sessionName, entry);
         this.updateMetrics();
         return entry;
@@ -116,8 +158,10 @@ class TmuxControlRegistry {
         }
         this.cancelIdleCleanup(entry);
         entry.idleTimer = setTimeout(() => {
-            logger.debug('idle-cleanup', { sessionName });
-            this.deleteEntry(sessionName);
+            // entry.sessionName, not the captured `sessionName`: the session may have
+            // been renamed while this timer was pending (see renameSession).
+            logger.debug('idle-cleanup', { sessionName: entry.sessionName });
+            this.deleteEntry(entry.sessionName);
         }, this.idleTimeoutMs);
     }
     cancelIdleCleanup(entry) {