commandmate 0.30.1 → 0.31.0

package/dist/server/src/lib/skills/compatibility-matrix.js

@@ -98,6 +98,21 @@ const MEASURED_DATE_2026_07_26 = '2026-07-26';
  */
 const OPENCODE_EVIDENCE_SOURCE = 'https://github.com/Kewton/CommandMate/blob/main/docs/design/opencode-server-live-verification.md#11-issue-2036--2037-opencode-11822-2026-08-25';
 const MEASURED_DATE_2026_08_25 = '2026-08-25';
+/**
+ * Evidence reference for the Command Code 1.49.0 measurement (Issue #2302).
+ *
+ * The reference doc carries the harness, both controls and the raw CLI output,
+ * which is the half of a row a reader can actually check.
+ */
+const COMMAND_CODE_EVIDENCE_SOURCE = 'https://github.com/Kewton/CommandMate/blob/main/docs/reference/skill-agent-compatibility.md#8-command-code-probe-log-issue-2302';
+const MEASURED_DATE_2026_09_05 = '2026-09-05';
+/**
+ * Evidence reference for the Copilot 1.0.83 measurement (Issue #2302).
+ *
+ * The same probe log also carries a Gemini 0.58.0 discovery measurement that is
+ * deliberately *not* recorded as a row — see the `gemini` entry below.
+ */
+const OTHER_AGENTS_EVIDENCE_SOURCE = 'https://github.com/Kewton/CommandMate/blob/main/docs/reference/skill-agent-compatibility.md#9-gemini--copilot-probe-log-issue-2302';
 function unmeasuredEntry(agent) {
     return {
         agent,
@@ -180,6 +195,16 @@ const AGENT_DISCOVERY_MATRIX = [
         reloadKey: exports.AGENT_RELOAD_MESSAGE_KEYS.SESSION_RESTART_NO_SLASH,
         skipReasonKey: null,
     },
+    // Issue #2302 *did* measure gemini 0.58.0 — `gemini skills list --all`
+    // returns `.agents/skills` with an absolute path, and `.claude/skills`
+    // planted at the same moment does not appear. It is still recorded as
+    // unmeasured here, on purpose: the invocation axis could not be measured at
+    // all (sign-in fails with "This client is no longer supported for Gemini Code
+    // Assist for individuals", so the TUI never reaches a composer), and landing
+    // the half-row is a change to `tests/integration/skills-agent-discovery-probe.test.ts`,
+    // which pins gemini as its example of an Agent with no measurement. The
+    // probe log is kept so the next pass starts from evidence rather than zero:
+    // `docs/reference/skill-agent-compatibility.md` §9.1.
     unmeasuredEntry('gemini'),
     unmeasuredEntry('vibe-local'),
     {
@@ -224,11 +249,102 @@ const AGENT_DISCOVERY_MATRIX = [
         reloadKey: exports.AGENT_RELOAD_MESSAGE_KEYS.SESSION_RESTART,
         skipReasonKey: null,
     },
-    unmeasuredEntry('copilot'),
+    {
+        agent: 'copilot',
+        // Issue #2302, GitHub Copilot CLI 1.0.83. The only Agent so far measured to
+        // read *both* CommandMate install roots from one listing: `copilot skill
+        // list` returns `.github/skills` (positive control), `.agents/skills` and
+        // `.claude/skills`, and the byte-identical dual-root install appears once
+        // rather than twice.
+        //
+        // `copilot skill --help` claims those roots too. That claim is not the
+        // evidence — the probe Skills are, one per root with its own token.
+        discoveryRoots: [constants_1.SKILL_INSTALL_ROOT_PREFIX, constants_1.SKILL_CLAUDE_INSTALL_ROOT_PREFIX],
+        discovery: {
+            outcome: 'verified',
+            evidenceKind: 'mechanical',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.verified,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.mechanical,
+            limitationKey: null,
+        },
+        invocation: {
+            // Typing `/probe` in Copilot's own composer offers all four planted
+            // Skills, `.claude/skills` included. Controls: `/zzzznotacommand` matched
+            // nothing and `/hel` matched the built-in commands, so the palette was
+            // filtering rather than listing everything.
+            //
+            // Measured at the palette, which is what this axis is — the same standard
+            // the Claude row was measured to. The model was not signed in during the
+            // probe, so a Skill actually running end to end is *not* claimed here.
+            outcome: 'verified',
+            evidenceKind: 'mechanical',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.verified,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.mechanical,
+            limitationKey: null,
+        },
+        testedVersion: '1.0.83',
+        testedDate: MEASURED_DATE_2026_09_05,
+        evidenceSource: OTHER_AGENTS_EVIDENCE_SOURCE,
+        // Whether a Skill added mid-session is picked up was not measured.
+        reloadKey: exports.AGENT_RELOAD_MESSAGE_KEYS.UNKNOWN,
+        skipReasonKey: null,
+    },
     // CommandMate's own slash palette serves `.agents/skills` entries to
     // antigravity sessions (#1504). That is CommandMate injecting a command, not
     // the Agent discovering a Skill, so it is not evidence for this table.
     unmeasuredEntry('antigravity'),
+    {
+        agent: 'command-code',
+        // Issue #2250 left this row unmeasured; Issue #2302 measured it on 1.49.0.
+        //
+        // Of CommandMate's two install roots, Command Code reads `.agents/skills`
+        // and does not read `.claude/skills`. `cmd skills list -d` names the roots
+        // it looks in — project `.commandcode/skills` and `.agents/skills`, the same
+        // pair under `$HOME` — and `.claude/skills` is not among them. A probe Skill
+        // was planted in each root at the same moment, so the split is the Agent's
+        // and not the install's: `.commandcode/skills` is the positive control and
+        // came back listed, `.claude/skills` is the negative control and did not.
+        //
+        // The dual-root install (#1460) is therefore half-read and still correct:
+        // one byte-identical payload in both roots is listed exactly once, from
+        // `.agents/skills`. Naming the unread root here would render as "installed
+        // and invisible" for anyone reading the table to decide where to look.
+        discoveryRoots: [constants_1.SKILL_INSTALL_ROOT_PREFIX],
+        discovery: {
+            outcome: 'verified',
+            evidenceKind: 'mechanical',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.verified,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.mechanical,
+            limitationKey: null,
+        },
+        invocation: {
+            // The axis codex and opencode both fail, and Command Code passes: typing
+            // `/probe` in its own composer offers the installed Skills as `[skill]`
+            // rows, and `/skills` lists them under "Project skills" with an
+            // `[.agents]` badge. So no limitation is attached here — CommandMate's
+            // palette is a convenience for this Agent, not the only route in.
+            //
+            // Headless is where it was machine-checked: `cmd -p "/<name>"` emits
+            // `{"type":"skill_loaded","name":"<name>"}` before the run starts and the
+            // model then answers the Skill's token. `--no-skills` is the control that
+            // makes that event mean discovery rather than prompt text — same prompt,
+            // no event.
+            outcome: 'verified',
+            evidenceKind: 'mechanical',
+            labelKey: exports.AGENT_AXIS_OUTCOME_LABEL_KEYS.verified,
+            evidenceKindKey: exports.AGENT_EVIDENCE_KIND_LABEL_KEYS.mechanical,
+            limitationKey: null,
+        },
+        testedVersion: '1.49.0',
+        testedDate: MEASURED_DATE_2026_09_05,
+        evidenceSource: COMMAND_CODE_EVIDENCE_SOURCE,
+        // Also measured: a Skill planted into a *running* session shows up in the
+        // `/skills` picker, which rescans when opened, but not in the composer's
+        // slash completion, which is built once at session start. A restart is what
+        // makes both agree, so that is the instruction.
+        reloadKey: exports.AGENT_RELOAD_MESSAGE_KEYS.SESSION_RESTART,
+        skipReasonKey: null,
+    },
 ];
 /** The measured matrix, in CLI-tool declaration order. */
 function getSkillAgentMatrix() {

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 };
         }