commandmate 0.30.2 → 0.31.0

package/dist/server/src/lib/tmux/geometry-delegation.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Phase D of Issue #2317, server side: knowing when a human owns the geometry.
+ *
+ * `commandmate attach --live` hands a session's window from the pinned
+ * 200x1000 canvas to the attached terminal (`window-size latest`) so the agent
+ * re-lays-out and the transcript is actually readable, then pins it back on
+ * detach. While that handover is in force the session carries `@cm_delegated=1`,
+ * and the server has to behave differently in exactly two places:
+ *
+ * 1. **`reconcileSessionGeometry` must not resize.** Every `send` to a live
+ *    session reaches `reconcileExistingSession()`, which would snap the window
+ *    back to 200x1000 mid-read — the #1623 rejection note assumed this happened
+ *    on every send and it does not, but it does happen on a session restart and
+ *    on the reuse path, which is enough to break a delegated read.
+ * 2. **The poller must not save a scraped reply.** At 44 rows the frame is a
+ *    fraction of the turn, and every extraction rule in `response-checker` was
+ *    measured against the 1000-row canvas. claude — the only tool `--live`
+ *    accepts — writes its History from its own transcript JSONL, so suppressing
+ *    the scrape loses nothing and prevents a truncated reply being recorded.
+ *
+ * ## Why the flag is read from tmux rather than held in memory
+ *
+ * The delegation is performed by the CLI process (`commandmate attach --live`),
+ * which is not the server. The tmux session is the only thing both of them can
+ * see, and a user option on it is the cheapest shared channel that survives the
+ * CLI exiting, the server restarting, and a `client-detached` hook firing when
+ * neither is watching.
+ *
+ * ## Why the read is cached
+ *
+ * `checkForResponse` runs about every two seconds per active session. A
+ * `show-options` per poll would be one extra tmux round-trip per session per
+ * poll for a value that changes twice a day, so reads are memoised for
+ * {@link DELEGATION_TTL_MS}. The TTL is short enough that the restore edge is
+ * observed within one poll of the detach.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELEGATION_TTL_MS = void 0;
+exports.isGeometryDelegated = isGeometryDelegated;
+exports.probeGeometryDelegation = probeGeometryDelegation;
+exports.hasHumanClientAttached = hasHumanClientAttached;
+exports.forgetGeometryDelegation = forgetGeometryDelegation;
+exports.resetGeometryDelegationState = resetGeometryDelegationState;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const tmux_session_surface_1 = require("../session/tmux-session-surface");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/** tmux calls here are interactive-latency, not long-running. */
+const TMUX_TIMEOUT = 5000;
+/**
+ * How long a delegation read is reused.
+ *
+ * One second, against a ~2s poll: short enough that the poll after a detach sees
+ * the restore, long enough that the several readers of one session in one poll
+ * (the status helper, the response checker) share a single tmux round-trip.
+ */
+exports.DELEGATION_TTL_MS = 1000;
+const cache = globalThis.__cmGeometryDelegationCache ??
+    (globalThis.__cmGeometryDelegationCache = new Map());
+const lastObserved = globalThis.__cmGeometryDelegationEdge ??
+    (globalThis.__cmGeometryDelegationEdge = new Map());
+/**
+ * Whether `@cm_delegated` is set to `1` on a session.
+ *
+ * Never throws: a session that has gone away, or a tmux that is not running, is
+ * "not delegated" — the answer that leaves every caller on its normal path.
+ *
+ * @param sessionName - Target session
+ * @param now - Epoch ms, injectable for tests
+ */
+async function isGeometryDelegated(sessionName, now = Date.now()) {
+    const cached = cache.get(sessionName);
+    if (cached && now - cached.readAt < exports.DELEGATION_TTL_MS)
+        return cached.delegated;
+    let delegated = false;
+    try {
+        const { stdout } = await execFileAsync('tmux', (0, tmux_session_surface_1.buildShowSessionOptionValueArgs)(sessionName, tmux_session_surface_1.CM_DELEGATED_OPTION), { timeout: TMUX_TIMEOUT });
+        delegated = stdout.trim() === '1';
+    }
+    catch {
+        // THE ORDINARY CASE, not an error path. Measured on tmux 3.5a: asking for a
+        // user option a session does not carry exits NON-ZERO with
+        // `invalid option: @cm_delegated` — it is not an empty string and it is not
+        // exit 0. So "this session has never been delegated" arrives here, and it
+        // arrives here on every poll of every session, which is why nothing is
+        // logged. A session that is gone, and a tmux that is not running, land in
+        // the same place and mean the same thing.
+        delegated = false;
+    }
+    cache.set(sessionName, { delegated, readAt: now });
+    return delegated;
+}
+/**
+ * Read the delegation flag and report the release edge.
+ *
+ * The edge is what the poller needs: on restore the pane goes back to 1000 rows,
+ * so a `last_captured_line` recorded against a 44-row frame indexes into
+ * nothing. Resetting the cursor at that moment is what closes both the
+ * double-save window (a cursor too low re-saves) and the never-save window (a
+ * cursor too high suppresses forever).
+ *
+ * @param sessionName - Target session
+ * @param now - Epoch ms, injectable for tests
+ */
+async function probeGeometryDelegation(sessionName, now = Date.now()) {
+    const delegated = await isGeometryDelegated(sessionName, now);
+    const previous = lastObserved.get(sessionName) ?? false;
+    lastObserved.set(sessionName, delegated);
+    return { delegated, released: previous && !delegated };
+}
+/**
+ * Whether any NON-control-mode client is attached to the session.
+ *
+ * Used by `reconcileSessionGeometry` as the second half of its skip condition:
+ * `@cm_delegated` says "a `--live` attach is in force", this says "somebody is
+ * looking at it right now". A control-mode client — CommandMate's own transport
+ * — never counts, which is what keeps the server from treating its own
+ * connection as a reason to stop pinning the canvas.
+ *
+ * Never throws; an unreadable client list is "nobody is attached".
+ */
+async function hasHumanClientAttached(sessionName) {
+    try {
+        const { stdout } = await execFileAsync('tmux', (0, tmux_session_surface_1.buildListClientsArgs)(sessionName), {
+            timeout: TMUX_TIMEOUT,
+        });
+        return (0, tmux_session_surface_1.countHumanClients)(stdout) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Drop every memo for a session — call when it is known to be gone. */
+function forgetGeometryDelegation(sessionName) {
+    cache.delete(sessionName);
+    lastObserved.delete(sessionName);
+}
+/** Test seam: drop every memo, for suites that drive several sessions. */
+function resetGeometryDelegationState() {
+    cache.clear();
+    lastObserved.clear();
+}

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

@@ -112,18 +112,31 @@ exports.PAGER_SCRIPT_FILENAME = 'cm-read-pane.sh';
  * stopped.
  */
 exports.PAGER_SCRIPT = `#!/bin/sh
-# CommandMate reading mode (Issue #1623) — generated file, edits are overwritten.
+# CommandMate reading mode (Issue #1623; --follow added by #2317) — 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
+#   sh ~/.commandmate/bin/${exports.PAGER_SCRIPT_FILENAME} --follow mcbd-claude-my-worktree
 #
-# The popup is a SNAPSHOT. Press the key again to refresh it.
+# Without --follow the popup is a SNAPSHOT. Press the key again to refresh it.
+# With --follow (Issue #2317 Phase C) it redraws every CM_READ_FOLLOW_INTERVAL
+# seconds and closes on \`q\`. Neither mode alters the pane, the window or the
+# session — the popup is per-client and leaves nothing behind when it closes.
 set -u
 
-SESSION="\${1:-}"
+FOLLOW=0
+SESSION=""
+for arg in "$@"; do
+  case "$arg" in
+    --follow|-f) FOLLOW=1 ;;
+    -*) ;;
+    *) if [ -z "$SESSION" ]; then SESSION="$arg"; fi ;;
+  esac
+done
+
 if [ -z "$SESSION" ]; then
   SESSION=$(tmux display-message -p '#{session_name}' 2>/dev/null) || SESSION=""
 fi
@@ -137,6 +150,65 @@ case "$LINES_BACK" in
   ''|*[!0-9]*) LINES_BACK=1000 ;;
 esac
 
+# 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.
+cm_read_render() {
+  tmux capture-pane -pe -t "=$SESSION:" -S "-$LINES_BACK" -E - \\
+    | LC_ALL=${exports.SQUEEZE_AWK_LOCALE} awk '${exports.SQUEEZE_AWK_PROGRAM}'
+}
+
+if [ "$FOLLOW" = "1" ]; then
+  INTERVAL="\${CM_READ_FOLLOW_INTERVAL:-2}"
+  case "$INTERVAL" in
+    ''|*[!0-9]*) INTERVAL=2 ;;
+  esac
+  if [ "$INTERVAL" -lt 1 ]; then INTERVAL=1; fi
+  # The key check below waits 0.2s per tick (stty \`time 2\`), so one tick is a
+  # fifth of a second and the key is answered long before the next redraw.
+  TICKS=$((INTERVAL * 5))
+
+  OLD_STTY=$(stty -g 2>/dev/null) || OLD_STTY=""
+  cm_read_restore_tty() {
+    if [ -n "$OLD_STTY" ]; then stty "$OLD_STTY" 2>/dev/null || true; fi
+    printf '\\033[?25h'
+  }
+  trap 'cm_read_restore_tty' EXIT
+  trap 'cm_read_restore_tty; exit 0' INT TERM
+  # \`min 0 time 2\` is what makes a single-byte read non-blocking-with-a-deadline:
+  # it returns after 0.2s with nothing when no key was pressed. Without it the
+  # loop would either block forever on the key or busy-spin between redraws.
+  if [ -n "$OLD_STTY" ]; then stty -icanon -echo min 0 time 2 2>/dev/null || true; fi
+  printf '\\033[?25l'
+
+  ROWS=$(tput lines 2>/dev/null) || ROWS=40
+  case "$ROWS" in
+    ''|*[!0-9]*) ROWS=40 ;;
+  esac
+  BODY_ROWS=$((ROWS - 2))
+  if [ "$BODY_ROWS" -lt 1 ]; then BODY_ROWS=1; fi
+
+  while :; do
+    FRAME=$(cm_read_render | tail -n "$BODY_ROWS")
+    printf '\\033[H\\033[2J%s\\n' "$FRAME"
+    printf '\\033[7m[CommandMate] following %s — press q to close\\033[0m' "$SESSION"
+    TICK=0
+    while [ "$TICK" -lt "$TICKS" ]; do
+      if [ -n "$OLD_STTY" ]; then
+        KEY=$(dd bs=1 count=1 2>/dev/null)
+        case "$KEY" in
+          q|Q) exit 0 ;;
+        esac
+      else
+        sleep 1
+        TICK="$TICKS"
+      fi
+      TICK=$((TICK + 1))
+    done
+  done
+fi
+
 if [ -n "\${CM_READ_PAGER:-}" ]; then
   PAGER_CMD="$CM_READ_PAGER"
 elif command -v less >/dev/null 2>&1; then
@@ -145,13 +217,7 @@ 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
+cm_read_render | $PAGER_CMD
 
 # Without a pager the popup would close before anything could be read.
 if [ "$PAGER_CMD" = "cat" ]; then

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

@@ -45,9 +45,11 @@
  * (`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.READ_MODE_FOLLOW_ENV = exports.DEFAULT_READ_MODE_KEY = exports.MCBD_SESSION_PREFIX = void 0;
 exports.getPagerScriptPath = getPagerScriptPath;
 exports.isReadModeEnabled = isReadModeEnabled;
+exports.isReadModeFollowEnabled = isReadModeFollowEnabled;
+exports.buildPopupCommand = buildPopupCommand;
 exports.resolveReadModeKey = resolveReadModeKey;
 exports.quoteForTmuxCommand = quoteForTmuxCommand;
 exports.buildBindKeyArgs = buildBindKeyArgs;
@@ -79,6 +81,26 @@ const TMUX_TIMEOUT = 5000;
 exports.MCBD_SESSION_PREFIX = 'mcbd-';
 /** Key bound under the prefix table when `CM_READ_MODE_KEY` is unset. */
 exports.DEFAULT_READ_MODE_KEY = 'g';
+/**
+ * Environment variable that makes `prefix + <key>` open the FOLLOWING popup
+ * instead of the snapshot one (Issue #2317, Phase C).
+ *
+ * ## Why one key and an option, rather than a second binding
+ *
+ * Issue #2317 offers two shapes for the follow mode — a second bound key
+ * (`CM_READ_MODE_FOLLOW_KEY`, default `G`) or a switch — and leaves the choice
+ * to implementation. This is the switch, for a reason that outlives the choice:
+ * a `bind-key` writes the tmux server's GLOBAL prefix table, which every session
+ * on the machine inherits including ones CommandMate knows nothing about. #2317
+ * 決定事項 2 says the new surface must stay session-scoped; a SECOND global key
+ * would have doubled the one global intervention the feature was allowed to
+ * keep. An environment variable costs no key table at all.
+ *
+ * The follow popup remains reachable two other ways with no key at all:
+ * `commandmate capture <id> --pane --follow`, and the opt-in
+ * `CM_READ_MODE_AUTO_POPUP=on`, which opens it on attach.
+ */
+exports.READ_MODE_FOLLOW_ENV = 'CM_READ_MODE_FOLLOW';
 /**
  * Accepted `CM_READ_MODE_KEY` values: a single alphanumeric, an F-key, either
  * optionally with a `C-` / `M-` / `S-` modifier. Deliberately narrow — a typo
@@ -104,6 +126,26 @@ function isReadModeEnabled() {
     const raw = (process.env.CM_READ_MODE ?? '').trim().toLowerCase();
     return raw !== 'off' && raw !== '0' && raw !== 'false';
 }
+/** True when the operator asked `prefix + <key>` to follow rather than snapshot. */
+function isReadModeFollowEnabled() {
+    return (process.env[exports.READ_MODE_FOLLOW_ENV] ?? '').trim().toLowerCase() === 'on';
+}
+/**
+ * The shell command the popup runs: the pager script, plus `--follow` when the
+ * operator asked for it.
+ *
+ * One word per argument and no quoting of its own — {@link quoteForTmuxCommand}
+ * wraps the WHOLE line, so tmux hands `/bin/sh` a single command string. That is
+ * the same shape the snapshot form has always had; the flag rides inside the
+ * quotes rather than after them, because a word after the closing quote would be
+ * a second argument to `display-popup`, not to the script.
+ *
+ * @param scriptPath - Absolute path of the materialized pager script
+ * @param follow - Whether to append `--follow`
+ */
+function buildPopupCommand(scriptPath, follow) {
+    return follow ? `${scriptPath} --follow` : scriptPath;
+}
 /**
  * Resolve the configured key, or undefined when it is malformed.
  * @returns The key to bind, or undefined if `CM_READ_MODE_KEY` fails validation
@@ -283,7 +325,7 @@ async function reconcileReadModeBinding() {
                 detail: 'display-popup requires tmux 3.2+; use `commandmate capture <id> --pane` instead',
             };
         }
-        const quoted = quoteForTmuxCommand(scriptPath);
+        const quoted = quoteForTmuxCommand(buildPopupCommand(scriptPath, isReadModeFollowEnabled()));
         if (quoted === undefined) {
             return { installed: false, outcome: 'unsafe-script-path', key, scriptPath };
         }

package/dist/server/src/lib/tmux/session-hook-scripts.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * The shell scripts session-scoped tmux hooks run (Issue #2317, Phases C and D).
+ *
+ * ## Why the text is embedded rather than shipped as a file
+ *
+ * The same reason `read-mode-pager.ts` gives for `cm-read-pane.sh`:
+ * `package.json`'s `files` list does not publish `scripts/`, and an `npx`
+ * install lives in a cache npm may garbage-collect out from under a hook that
+ * outlives the process which installed it. Embedding the text and materializing
+ * it into `~/.commandmate/bin/` gives every hook one absolute path that is
+ * stable across global / local / npx installs.
+ *
+ * ## Why the hooks call scripts instead of doing the work inline
+ *
+ * Measured on tmux 3.5a (Issue #2317 技術検証): a hook body of the shape
+ * `if-shell -F '#{…}' '<command>'` is accepted by `set-hook` and then never
+ * fires — silently, with no error anywhere. A
+ * `run-shell -b '<script> #{session_name} #{client_control_mode}'` DOES fire.
+ * So the formats are handed to a script and every branch is taken in `sh`.
+ *
+ * The hook environment is the tmux SERVER's, which carries `TMUX` — so the bare
+ * `tmux` these scripts call reaches the same server that fired the hook, private
+ * socket included. That is verified, not assumed: the whole live probe for this
+ * Issue ran under `tmux -L cm2317` and the scripts reached that server.
+ *
+ * ## Both scripts refuse to touch a session that is not CommandMate's
+ *
+ * A hook is session-scoped, so in principle it can only fire on the session it
+ * was installed on. The `mcbd-` guard is still there because these scripts are
+ * also runnable by hand and because a session can be renamed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTO_POPUP_SCRIPT = exports.LIVE_DELEGATE_SCRIPT = exports.LIVE_RESTORE_SCRIPT = exports.AUTO_POPUP_SCRIPT_FILENAME = exports.LIVE_DELEGATE_SCRIPT_FILENAME = exports.LIVE_RESTORE_SCRIPT_FILENAME = void 0;
+exports.getScriptDir = getScriptDir;
+exports.getScriptPath = getScriptPath;
+exports.materializeScript = materializeScript;
+exports.materializeLiveRestoreScript = materializeLiveRestoreScript;
+exports.materializeLiveDelegateScript = materializeLiveDelegateScript;
+exports.materializeAutoPopupScript = materializeAutoPopupScript;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const tmux_pane_config_1 = require("../../config/tmux-pane-config");
+const tmux_session_surface_1 = require("../session/tmux-session-surface");
+const read_mode_pager_1 = require("./read-mode-pager");
+/** Basename of the Phase D geometry-restore script. */
+exports.LIVE_RESTORE_SCRIPT_FILENAME = 'cm-live-restore.sh';
+/** Basename of the Phase D geometry-delegation script. */
+exports.LIVE_DELEGATE_SCRIPT_FILENAME = 'cm-live-delegate.sh';
+/** Basename of the Phase C auto-popup script. */
+exports.AUTO_POPUP_SCRIPT_FILENAME = 'cm-auto-popup.sh';
+/**
+ * Restore a session's pinned canvas once no human client is attached.
+ *
+ * NOT a hook body — tmux 3.5a never fires a session-scoped `client-detached`
+ * (see the measurement table in `live-attach.ts`). Two things run this sequence:
+ * `commandmate attach --live` when `attach-session` returns, and the server's
+ * status poll (`reconcileDelegatedGeometry`) for every case where the CLI never
+ * got to — it was killed, the terminal window was closed, or the detach happened
+ * from a client this process never saw. This script is the third, manual, path:
+ * the escape hatch for a session left delegated while no server is running.
+ *
+ * The control-mode test is the whole reason the client count is not simply
+ * `#{session_attached}`: CommandMate's own transport attaches as a `tmux -C`
+ * client and never leaves, so a session with the human gone still reports
+ * `session_attached=1`. `client_control_mode` is `1` for those and `0` for a
+ * terminal, so the restore waits for the HUMAN count to reach zero
+ * (Issue #2317 受入条件 Phase D 4).
+ */
+exports.LIVE_RESTORE_SCRIPT = `#!/bin/sh
+# CommandMate live-attach restore (Issue #2317) — generated file, edits are overwritten.
+#
+#   sh ~/.commandmate/bin/${exports.LIVE_RESTORE_SCRIPT_FILENAME} <session> [control_mode] [width] [height]
+#
+# Pins the session's window back to CommandMate's canvas once no human client is
+# attached to it any more. Safe to run when nothing is delegated: it then simply
+# re-applies the geometry the session already has.
+set -u
+
+SESSION="\${1:-}"
+CONTROL_MODE="\${2:-0}"
+WIDTH="\${3:-${tmux_pane_config_1.TUI_PANE_WIDTH}}"
+HEIGHT="\${4:-${tmux_pane_config_1.TUI_PANE_HEIGHT}}"
+
+case "$SESSION" in
+  ${tmux_session_surface_1.MCBD_SESSION_PREFIX}*) ;;
+  *) exit 0 ;;
+esac
+
+# A control-mode client detaching is CommandMate's own transport reconnecting,
+# not the human leaving. Doing the restore here would fight the human's attach.
+if [ "$CONTROL_MODE" = "1" ]; then
+  exit 0
+fi
+
+# Anyone left who is NOT a control client? Then the geometry is still theirs.
+HUMANS=$(tmux list-clients -t "=$SESSION:" -F '#{client_control_mode}' 2>/dev/null \\
+  | grep -c -v '^1$') || HUMANS=0
+if [ "\${HUMANS:-0}" -gt 0 ]; then
+  exit 0
+fi
+
+tmux set-window-option -t "=$SESSION:" window-size manual 2>/dev/null || exit 0
+tmux resize-window -t "=$SESSION:" -x "$WIDTH" -y "$HEIGHT" 2>/dev/null || true
+tmux set-option -u -t "=$SESSION:" @cm_delegated 2>/dev/null || true
+`;
+/**
+ * Hand a session's geometry to the terminal that just attached.
+ *
+ * The opt-in half of Phase D: `commandmate attach --live` performs these two
+ * writes itself, and this script is what makes a HAND-ROLLED `tmux attach`
+ * behave the same way when the operator asked for it with
+ * `CM_LIVE_ATTACH_HOOK=on`.
+ *
+ * claude-only by session-name prefix, and that is not a shortcut. The session
+ * name is `mcbd-<tool>-<worktree>`, no other CLI tool id begins with `claude`,
+ * and the script has nothing but the name to go on — a hook fires with tmux
+ * formats, not with CommandMate's roster. Widening it means widening
+ * `LIVE_ATTACH_TOOLS` too, and that needs the per-tool re-measurement
+ * Issue #2317 puts out of scope.
+ */
+exports.LIVE_DELEGATE_SCRIPT = `#!/bin/sh
+# CommandMate live-attach delegate (Issue #2317) — generated file, edits are overwritten.
+#
+#   sh ~/.commandmate/bin/${exports.LIVE_DELEGATE_SCRIPT_FILENAME} <session> <control_mode> [client]
+#
+# Hands the session's window from CommandMate's pinned canvas to the terminal
+# that just attached, so an alternate-screen agent re-lays-out and its transcript
+# becomes readable. Installed as a session-scoped \`client-attached[0]\` hook only
+# when CM_LIVE_ATTACH_HOOK=on; \`commandmate attach --live\` does the same two
+# writes itself and needs no hook.
+#
+# The window is put back by whoever notices the human is gone first: the CLI on
+# return from attach-session, or the server's status poll. This script never
+# restores — the attach edge is the only edge tmux 3.5a lets a session-scoped
+# hook see.
+set -u
+
+SESSION="\${1:-}"
+CONTROL_MODE="\${2:-0}"
+
+case "$SESSION" in
+  ${tmux_session_surface_1.MCBD_SESSION_PREFIX}claude-*) ;;
+  *) exit 0 ;;
+esac
+
+# A control-mode client is CommandMate's own transport. Handing it the geometry
+# would resize the canvas to whatever that connection negotiated, which is the
+# #1163 regression this whole feature is built to avoid.
+if [ "$CONTROL_MODE" = "1" ]; then
+  exit 0
+fi
+
+# Raised BEFORE the size change, so a status poll landing between the two sees
+# "delegated, still pinned" rather than "not delegated, 44 rows".
+tmux set-option -t "=$SESSION:" @cm_delegated 1 2>/dev/null || exit 0
+tmux set-window-option -t "=$SESSION:" window-size latest 2>/dev/null || true
+`;
+/**
+ * Open the following transcript popup when a human attaches (Phase C, opt-in).
+ *
+ * Default off, and it has to be: the popup owns the keyboard until `q` is
+ * pressed, so opening it unasked would make every attach start by taking input
+ * away from the composer. `CM_READ_MODE_AUTO_POPUP=on` is the opt-in, and even
+ * then the control-mode test below keeps it from firing for CommandMate's own
+ * transport — a popup opened on a control client would be a popup nobody can
+ * see and nobody can close.
+ */
+exports.AUTO_POPUP_SCRIPT = `#!/bin/sh
+# CommandMate auto read popup (Issue #2317) — generated file, edits are overwritten.
+#
+#   sh ~/.commandmate/bin/${exports.AUTO_POPUP_SCRIPT_FILENAME} <session> <control_mode> <client>
+#
+# Opens the following transcript popup for a human client attaching to a
+# CommandMate session. Never opens for a control-mode client.
+set -u
+
+SESSION="\${1:-}"
+CONTROL_MODE="\${2:-0}"
+CLIENT="\${3:-}"
+
+case "$SESSION" in
+  ${tmux_session_surface_1.MCBD_SESSION_PREFIX}*) ;;
+  *) exit 0 ;;
+esac
+
+if [ "$CONTROL_MODE" = "1" ]; then
+  exit 0
+fi
+
+PAGER_SCRIPT="$HOME/.commandmate/bin/${read_mode_pager_1.PAGER_SCRIPT_FILENAME}"
+[ -x "$PAGER_SCRIPT" ] || exit 0
+
+if [ -n "$CLIENT" ]; then
+  tmux display-popup -c "$CLIENT" -w 90% -h 85% -E "sh \\"$PAGER_SCRIPT\\" --follow \\"$SESSION\\"" 2>/dev/null || true
+else
+  tmux display-popup -w 90% -h 85% -E "sh \\"$PAGER_SCRIPT\\" --follow \\"$SESSION\\"" 2>/dev/null || true
+fi
+`;
+/** Directory every materialized CommandMate script lives in. */
+function getScriptDir() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'bin');
+}
+/** Absolute path of a materialized script. */
+function getScriptPath(filename) {
+    return (0, path_1.join)(getScriptDir(), filename);
+}
+/**
+ * Write a script to `~/.commandmate/bin/<filename>` 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 —
+ * the same contract `materializePagerScript()` has had since #1623.
+ *
+ * @param filename - Basename to write
+ * @param content - Full script text
+ * @returns The absolute path written
+ */
+function materializeScript(filename, content) {
+    const scriptPath = getScriptPath(filename);
+    (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 !== content) {
+        (0, fs_1.writeFileSync)(scriptPath, content, { mode: 0o755 });
+    }
+    (0, fs_1.chmodSync)(scriptPath, 0o755);
+    return scriptPath;
+}
+/** Materialize the Phase D restore script and return its absolute path. */
+function materializeLiveRestoreScript() {
+    return materializeScript(exports.LIVE_RESTORE_SCRIPT_FILENAME, exports.LIVE_RESTORE_SCRIPT);
+}
+/** Materialize the Phase D delegate script and return its absolute path. */
+function materializeLiveDelegateScript() {
+    return materializeScript(exports.LIVE_DELEGATE_SCRIPT_FILENAME, exports.LIVE_DELEGATE_SCRIPT);
+}
+/** Materialize the Phase C auto-popup script and return its absolute path. */
+function materializeAutoPopupScript() {
+    return materializeScript(exports.AUTO_POPUP_SCRIPT_FILENAME, exports.AUTO_POPUP_SCRIPT);
+}