commandmate 0.30.2 → 0.31.0

package/README.md

@@ -50,14 +50,24 @@ If this is the kind of AI development workflow you want, [give the repo a star](
 | **Skills Catalog** | Install and update official Skills per worktree, from the web UI or `commandmate skill` | The method is installed for the agent to read, not kept in someone's head |
 | **Never miss a waiting agent** | A waiting agent shows up as a badge, a toast, the tab title, the PWA app badge and a push notification | You find out the moment an agent needs you, even away from the desk |
 | **Git Worktree Sessions** | One session per worktree, parallel execution | Multiple issues progress simultaneously without interference |
-| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity or local models per worktree | Pick the right agent for each task |
+| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, Command Code or local models per worktree | Pick the right agent for each task |
 | **Auto Yes Mode** | Agent runs without stopping for confirmations | Optional unattended mode for trusted workflows — review the Security section before enabling |
 | **Web UI (Desktop & Mobile)** | Full session control from any browser | Monitor and steer from your desk or your phone |
+| **Conversation view** | Switch a session's output between the raw terminal and a chat transcript — replies render in full, tool runs and approvals fold into chips, and a TUI dialog is answerable from the chat surface | Follow the run and answer it — from your desk or your phone — without reading the TUI |
 | **File Viewer & Markdown Editor** | Browse and edit worktree files in the browser | Review changes and update AI instructions without opening an IDE |
 | **Screenshot Instructions** | Attach images to your prompts | Snap a bug → "Fix this" — the agent sees the screenshot |
 | **Scheduled Execution** | Cron-based auto-run via CMATE.md | Daily reviews, nightly tests — agents work on a schedule |
 | **Token Authentication** | SHA-256 hashed token + HTTPS + rate limiting | Secure remote access — no credentials leaked, brute-force protected |
 
+### Supported agents
+
+All eight are first-class. Each one gets the same treatment inside CommandMate — its own launch path, its own hook source and its own status detection — so the worktree session, the task contract, the verification gates and the evidence trail behave the same way whichever agent you pick.
+
+- **Claude Code**, **Codex**, **Gemini CLI**, **Copilot**, **Antigravity** — choose per worktree, per task.
+- **OpenCode** — the open-source terminal agent, driven through the same contract-and-gate path as the rest.
+- **Command Code** — driven the same way, its hooks and its transcript included.
+- **Local models** (`vibe-local`) — run the same loop against a model you host yourself.
+
 ---
 
 ## Use Cases
@@ -341,20 +351,36 @@ commandmate start -p 3001
 
 ### Session stuck or not responding?
 
-Check tmux sessions directly. CommandMate manages sessions with the naming format `mcbd-{tool}-{worktree}`:
+Look at the session with CommandMate's own commands — they resolve the tmux session name for you:
 
 ```bash
-# List all CommandMate sessions
-tmux list-sessions | grep mcbd
+# What every worktree's agent is doing, and the tmux session it runs in
+commandmate ls
+commandmate ls --json | jq -r '.[] | "\(.id)\t\(.tmuxSession)"'
+
+# Read the transcript WITHOUT attaching
+commandmate capture <worktree-id> --pane --tail 60
+commandmate capture <worktree-id> --pane --follow    # follow a reply as it is generated
 
-# View session output (without attaching)
-tmux capture-pane -t "mcbd-claude-feature-123" -p
+# Attach this terminal (detach with Ctrl+b then d)
+commandmate attach <worktree-id>
+commandmate attach <worktree-id> --live              # re-lay out to your terminal (claude only)
+```
+
+**Why a bare `tmux attach` looks empty.** A CommandMate session is pinned to a 200x1000 canvas so
+`capture-pane` keeps enough history for status detection. Alternate-screen agents (claude / opencode /
+copilot) draw their transcript at the top of that canvas and their composer at the bottom, and tmux
+follows the cursor — so a normal-sized terminal sees the composer, blank rows, and not one line of the
+conversation. Nothing is broken. Read it with `capture --pane` above, with `prefix + g` while
+attached, or hand the window to your terminal with `attach --live`.
 
-# Attach to inspect (detach with Ctrl+b then d)
-tmux attach -t "mcbd-claude-feature-123"
+From tmux itself, without attaching at all:
+
+```bash
+tmux ls -F '#{session_name} #{@cm_status} #{@cm_tool}/#{@cm_instance}'
 
-# Kill a broken session
-tmux kill-session -t "mcbd-claude-feature-123"
+# Kill a broken session (`=name:` is an exact match; quote it — zsh eats a bare `=`)
+tmux kill-session -t '=mcbd-claude-feature-123:'
 ```
 
 > **Note:** When attached, avoid typing directly into the session — this can interfere with CommandMate's session management. Use `Ctrl+b` then `d` to detach and operate through the CommandMate UI instead.
@@ -446,7 +472,7 @@ The comparison that matters is not against other products; it is against the way
 | Evidence | A chat transcript | Commits, gate logs, `verify history`, `report metrics` |
 | Parallel work | Terminal tabs | One worktree and one contract per task |
 | When it stops | You notice, eventually | Waiting is surfaced: badge, toast, tab title, push |
-| Which agent | Locked to one | Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, local models |
+| Which agent | Locked to one | Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, Command Code, local models |
 
 </details>
 

package/dist/cli/commands/attach.d.ts

@@ -0,0 +1,50 @@
+/**
+ * attach Command - open a worktree's tmux session in this terminal (Issue #2317, Phase A/D)
+ *
+ *   commandmate attach <worktree-id> [--instance <id>] [--read-only] [--live]
+ *
+ * ## Why this exists when `tmux attach` already does
+ *
+ * Three reasons, and each one is a thing an operator got wrong before it:
+ *
+ * 1. **The session name.** It is `mcbd-<tool>-<worktree>[-<suffix>]`, and the
+ *    suffix depends on the agent-instance roster. `commandmate ls` did not print
+ *    it, so the name had to be assembled by hand from three facts spread across
+ *    two commands.
+ * 2. **The `=` trap.** The exact-match target form is `'=<name>:'` (Issue #1156),
+ *    and in zsh an unquoted `=name` is an equals expansion — `tmux attach -t
+ *    =mcbd-…:` fails with `not found` before tmux ever runs. Measured; it is in
+ *    the Issue. This command quotes it so nobody has to know.
+ * 3. **What you will see.** For an alternate-screen agent a bare attach shows
+ *    the composer and nothing else — the transcript is at the top of a 1000-row
+ *    canvas and tmux follows the cursor at row 997. That is not a fault to
+ *    debug, it is the geometry, and the hint printed before attaching says so
+ *    and names the three ways to read anyway.
+ *
+ * ## `--live` is claude-only, and that is a measurement
+ *
+ * See `LIVE_ATTACH_TOOLS` in `lib/tmux/session-surface.ts`. Every other tool
+ * either reads its reply off the pane, or has detection rules measured only at
+ * 200x1000, or cannot survive a width change at all.
+ */
+import { Command } from 'commander';
+/**
+ * The lines printed to stderr before the terminal is handed to tmux.
+ *
+ * stderr, not stdout: the session takes the screen over immediately afterwards,
+ * and a caller piping this command's stdout is not asking for advice.
+ *
+ * Exported so the test asserts the text a user actually sees rather than a
+ * paraphrase of it.
+ *
+ * @param cliToolId - Resolved CLI tool
+ * @param worktreeId - Worktree id, so the hint's commands are copy-pasteable
+ * @param sessionName - Resolved tmux session name
+ * @param options - The flags as given
+ */
+export declare function buildAttachHints(cliToolId: string, worktreeId: string, sessionName: string, options: {
+    readOnly?: boolean;
+    live?: boolean;
+}): string[];
+export declare function createAttachCommand(): Command;
+//# sourceMappingURL=attach.d.ts.map

package/dist/cli/commands/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuDpC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,EAAE,CAmCV;AAiDD,wBAAgB,mBAAmB,IAAI,OAAO,CAmE7C"}

package/dist/cli/commands/attach.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * attach Command - open a worktree's tmux session in this terminal (Issue #2317, Phase A/D)
+ *
+ *   commandmate attach <worktree-id> [--instance <id>] [--read-only] [--live]
+ *
+ * ## Why this exists when `tmux attach` already does
+ *
+ * Three reasons, and each one is a thing an operator got wrong before it:
+ *
+ * 1. **The session name.** It is `mcbd-<tool>-<worktree>[-<suffix>]`, and the
+ *    suffix depends on the agent-instance roster. `commandmate ls` did not print
+ *    it, so the name had to be assembled by hand from three facts spread across
+ *    two commands.
+ * 2. **The `=` trap.** The exact-match target form is `'=<name>:'` (Issue #1156),
+ *    and in zsh an unquoted `=name` is an equals expansion — `tmux attach -t
+ *    =mcbd-…:` fails with `not found` before tmux ever runs. Measured; it is in
+ *    the Issue. This command quotes it so nobody has to know.
+ * 3. **What you will see.** For an alternate-screen agent a bare attach shows
+ *    the composer and nothing else — the transcript is at the top of a 1000-row
+ *    canvas and tmux follows the cursor at row 997. That is not a fault to
+ *    debug, it is the geometry, and the hint printed before attaching says so
+ *    and names the three ways to read anyway.
+ *
+ * ## `--live` is claude-only, and that is a measurement
+ *
+ * See `LIVE_ATTACH_TOOLS` in `lib/tmux/session-surface.ts`. Every other tool
+ * either reads its reply off the pane, or has detection rules measured only at
+ * 200x1000, or cannot survive a width change at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAttachHints = buildAttachHints;
+exports.createAttachCommand = createAttachCommand;
+const child_process_1 = require("child_process");
+const commander_1 = require("commander");
+const types_1 = require("../types");
+const api_client_1 = require("../utils/api-client");
+const command_helpers_1 = require("../utils/command-helpers");
+const cli_tool_ids_1 = require("../config/cli-tool-ids");
+const agent_target_options_1 = require("../config/agent-target-options");
+const session_target_1 = require("../utils/session-target");
+const session_name_1 = require("../../lib/cli-tools/session-name");
+const tmux_session_surface_1 = require("../../lib/session/tmux-session-surface");
+/** Run one tmux command, inheriting nothing. Returns true on exit 0. */
+function runTmux(args) {
+    const result = (0, child_process_1.spawnSync)('tmux', args, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return result.status === 0;
+}
+/**
+ * Resolve which (tool, instance) pair the worktree id addresses.
+ *
+ * Through the server's resolver, exactly as `send` / `capture` / `wait` do
+ * (Issue #1925): the tool id is half the tmux session name, so a locally-guessed
+ * one is a different session. A `--agent` the roster contradicts is a hard error
+ * here rather than a warning — attaching is a thing you do WITH a session, and
+ * doing it to the wrong one wastes the reader's time in a way a wrong `capture`
+ * does not.
+ */
+async function resolveTarget(client, worktreeId, options) {
+    const target = await (0, session_target_1.resolveSessionTarget)(client, worktreeId, {
+        instanceId: options.instance,
+        requestedCliTool: options.agent,
+    });
+    if (target.conflict) {
+        console.error(`Error: ${(0, session_target_1.describeSessionTargetConflict)(target.conflict)}`);
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    return {
+        cliToolId: target.cliToolId ?? options.agent ?? cli_tool_ids_1.DEFAULT_CLI_TOOL_ID,
+        instanceId: target.instanceId ?? options.instance,
+    };
+}
+/**
+ * The lines printed to stderr before the terminal is handed to tmux.
+ *
+ * stderr, not stdout: the session takes the screen over immediately afterwards,
+ * and a caller piping this command's stdout is not asking for advice.
+ *
+ * Exported so the test asserts the text a user actually sees rather than a
+ * paraphrase of it.
+ *
+ * @param cliToolId - Resolved CLI tool
+ * @param worktreeId - Worktree id, so the hint's commands are copy-pasteable
+ * @param sessionName - Resolved tmux session name
+ * @param options - The flags as given
+ */
+function buildAttachHints(cliToolId, worktreeId, sessionName, options) {
+    const hints = [`Attaching to ${sessionName} (${cliToolId}). Detach with Ctrl+b then d.`];
+    if ((0, tmux_session_surface_1.usesAltScreen)(cliToolId) && !options.live) {
+        hints.push(`${cliToolId} draws its transcript at the top of a 200x1000 canvas and its composer at the`, 'bottom, and tmux follows the cursor — so this attach shows the composer and blank rows,', 'not the conversation. To read it:', `  prefix + g                                     popup, in this terminal`, `  commandmate capture ${worktreeId} --pane --tail 60   without attaching`, `  commandmate capture ${worktreeId} --pane --follow    live, without attaching`);
+        if ((0, tmux_session_surface_1.isLiveAttachSupported)(cliToolId)) {
+            hints.push(`  commandmate attach ${worktreeId} --live               re-lay-out to this terminal`);
+        }
+    }
+    if (options.readOnly) {
+        hints.push('Read-only attach: tmux delivers no keys but the detach one, so prefix + g does NOT open', 'the popup here. Read with `commandmate capture <id> --pane --follow` in another terminal.');
+    }
+    if (options.live) {
+        hints.push('Live attach: this session follows THIS terminal until you detach, then goes back to', '200x1000. The web terminal shows the smaller frame while you are attached.');
+    }
+    hints.push(`Status without attaching:  tmux ls -F '#{session_name} #{@cm_status}'`);
+    return hints;
+}
+/**
+ * Hand the geometry over, attach, and hand it back (Phase D).
+ *
+ * The restore runs in a `finally`, so a tmux that exits non-zero — or a
+ * `attach-session` interrupted by a signal — still gives the canvas back. The
+ * server's poll (`reconcileDelegatedGeometry`) is the second net for the case
+ * this process does not survive to run it.
+ */
+function attachLive(sessionName, readOnly) {
+    for (const args of (0, tmux_session_surface_1.buildDelegateGeometryCommands)(sessionName)) {
+        runTmux(args);
+    }
+    try {
+        const result = (0, child_process_1.spawnSync)('tmux', (0, tmux_session_surface_1.buildAttachArgs)(sessionName, readOnly), {
+            stdio: 'inherit',
+        });
+        return result.status ?? types_1.ExitCode.UNEXPECTED_ERROR;
+    }
+    finally {
+        for (const args of (0, tmux_session_surface_1.buildRestoreGeometryCommands)(sessionName)) {
+            runTmux(args);
+        }
+    }
+}
+/**
+ * Attach, or switch this tmux client, to `sessionName`.
+ *
+ * `switch-client` rather than an error when `$TMUX` is set: attaching a session
+ * inside another session is what tmux refuses, and switching is what the user
+ * meant. When the switch fails — the ambient `$TMUX` is a DIFFERENT tmux server,
+ * which is the case CommandMate's own agents run under — the manual command is
+ * printed, quoted, rather than a bare "nested sessions" complaint.
+ */
+function attachOrSwitch(sessionName, readOnly) {
+    if (process.env.TMUX) {
+        if (runTmux((0, tmux_session_surface_1.buildSwitchClientArgs)(sessionName)))
+            return types_1.ExitCode.SUCCESS;
+        console.error('Error: already inside tmux, and this client could not switch to that session '
+            + '(a different tmux server?). From a terminal outside tmux, run:\n'
+            + `  tmux attach -t '${(0, tmux_session_surface_1.exactSessionTarget)(sessionName)}'`);
+        return types_1.ExitCode.UNEXPECTED_ERROR;
+    }
+    const result = (0, child_process_1.spawnSync)('tmux', (0, tmux_session_surface_1.buildAttachArgs)(sessionName, readOnly), { stdio: 'inherit' });
+    return result.status ?? types_1.ExitCode.UNEXPECTED_ERROR;
+}
+function createAttachCommand() {
+    const cmd = new commander_1.Command('attach');
+    cmd
+        .description("Attach this terminal to a worktree's agent tmux session")
+        .argument('<worktree-id>', 'Worktree ID')
+        .option('--instance <id>', agent_target_options_1.INSTANCE_OPTION_DESCRIPTION)
+        .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
+        .option('-r, --read-only', 'Attach without sending any input to the session')
+        .option('--live', 'Re-lay the session out to this terminal while attached, restoring 200x1000 on detach (claude only)')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (worktreeId, options) => {
+        try {
+            if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
+                console.error('Error: Invalid worktree ID format.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            if (options.agent && !(0, cli_tool_ids_1.isCliToolId)(options.agent)) {
+                console.error('Error: Invalid agent.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            if (options.instance && !(0, api_client_1.isValidInstanceId)(options.instance)) {
+                console.error('Error: Invalid --instance. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            const client = new api_client_1.ApiClient({ token: options.token });
+            const { cliToolId, instanceId } = await resolveTarget(client, worktreeId, options);
+            if (options.live && !(0, tmux_session_surface_1.isLiveAttachSupported)(cliToolId)) {
+                console.error(`Error: --live is not supported for ${cliToolId}. It is claude-only until each other `
+                    + "agent's detection rules are re-measured at a terminal-sized pane (Issue #2317). "
+                    + `Attach without it, or read with: commandmate capture ${worktreeId} --pane --follow`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            const sessionName = (0, session_name_1.resolveSessionName)(cliToolId, worktreeId, instanceId);
+            if (!runTmux(['has-session', '-t', (0, tmux_session_surface_1.exactSessionTarget)(sessionName)])) {
+                console.error(`Error: no tmux session named ${sessionName}.\n`
+                    + `  commandmate ls                      which worktrees have a running session\n`
+                    + `  commandmate instances ${worktreeId}   which agents this worktree runs`);
+                process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+            }
+            for (const line of buildAttachHints(cliToolId, worktreeId, sessionName, {
+                readOnly: options.readOnly,
+                live: options.live,
+            })) {
+                console.error(line);
+            }
+            const status = options.live
+                ? attachLive(sessionName, Boolean(options.readOnly))
+                : attachOrSwitch(sessionName, Boolean(options.readOnly));
+            process.exit(status);
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}

package/dist/cli/commands/capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8RpC,wBAAgB,oBAAoB,IAAI,OAAO,CAmG9C"}
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwYpC,wBAAgB,oBAAoB,IAAI,OAAO,CA4H9C"}

package/dist/cli/commands/capture.js

@@ -28,6 +28,17 @@ const transcript_squeeze_1 = require("../../lib/tmux/transcript-squeeze");
  * RESULT instead (see {@link CaptureOptions.tail}).
  */
 const PANE_CAPTURE_LINES = 1000;
+/**
+ * Default redraw interval of `--pane --follow`, in milliseconds (Issue #2317).
+ *
+ * Two seconds, matching the response poller's own cadence: a faster redraw
+ * cannot show anything the server has not captured yet, and would only add tmux
+ * round-trips to a session someone is already watching.
+ */
+const DEFAULT_FOLLOW_INTERVAL_MS = 2000;
+/** Floor and ceiling for `--interval`. */
+const MIN_FOLLOW_INTERVAL_MS = 250;
+const MAX_FOLLOW_INTERVAL_MS = 60_000;
 /**
  * `promptData.type` the server writes for a frame the detection layer could not
  * classify (Issue #1708). Mirrors UNCLASSIFIED_PROMPT_TYPE in
@@ -247,6 +258,85 @@ async function capturePane(worktreeId, options) {
     }
     (0, pager_1.printMaybePaged)(text);
 }
+/**
+ * Parse and validate `--interval <ms>`.
+ *
+ * @param raw - Raw option value, if the user passed one
+ * @returns The interval in milliseconds
+ */
+function parseFollowInterval(raw) {
+    if (raw === undefined)
+        return DEFAULT_FOLLOW_INTERVAL_MS;
+    const value = Number(raw);
+    if (!Number.isInteger(value) ||
+        value < MIN_FOLLOW_INTERVAL_MS ||
+        value > MAX_FOLLOW_INTERVAL_MS) {
+        console.error(`Error: --interval must be an integer between ${MIN_FOLLOW_INTERVAL_MS} and ${MAX_FOLLOW_INTERVAL_MS} (milliseconds).`);
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    return value;
+}
+/**
+ * `--pane --follow`: redraw the squeezed transcript on an interval (Issue #2317).
+ *
+ * ## Why this exists next to `prefix + g`
+ *
+ * The popup #1623 added is a SNAPSHOT and needs a key press to refresh, and it
+ * does not work at all under `tmux attach -r` (a read-only client is delivered
+ * no keys but the detach one). This is the reading path that needs neither a
+ * tmux client nor a key table: it works from any terminal, over ssh, and while
+ * somebody else is attached.
+ *
+ * ## What it does NOT do
+ *
+ * It never writes. Every iteration makes exactly the request `--pane` already
+ * makes — same route, same {@link PANE_CAPTURE_LINES} — so the detection
+ * pipeline sees no different payload because a human is watching, and the
+ * session's geometry is untouched (Issue #2317 受入条件 Phase C 2).
+ *
+ * Ctrl-C is the exit, and it needs no handler: SIGINT's default action ends the
+ * process, and the alternate screen is left with the cursor restored by the
+ * `finally` below.
+ */
+async function capturePaneFollow(worktreeId, options) {
+    if (!process.stdout.isTTY) {
+        console.error('Error: --follow needs a terminal (it redraws the screen). '
+            + 'Without one, loop over `commandmate capture <id> --pane --tail N` instead.');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const tail = parseTail(options.tail);
+    const intervalMs = parseFollowInterval(options.interval);
+    const cliToolId = await resolvePaneCliTool(client, worktreeId, options.agent, options.instance);
+    // Hide the cursor while redrawing, and put it back whatever ends the loop.
+    process.stdout.write('\u001b[?25l');
+    const restoreCursor = () => {
+        process.stdout.write('\u001b[?25h');
+    };
+    process.on('exit', restoreCursor);
+    try {
+        for (;;) {
+            const data = await client.post(`/api/worktrees/${worktreeId}/capture`, {
+                cliToolId,
+                lines: PANE_CAPTURE_LINES,
+                ...(options.instance ? { instanceId: options.instance } : {}),
+            });
+            const squeezed = (0, transcript_squeeze_1.squeezeTranscript)(data.output ?? '', { tail });
+            // The visible rows, minus one for the footer. Slicing HERE rather than
+            // asking the server for fewer lines is the same choice `--tail` makes: the
+            // squeeze has to run over the whole frame or the blank padding is what
+            // gets kept.
+            const rows = Math.max(1, (process.stdout.rows || 40) - 1);
+            const body = squeezed.text.split('\n').slice(-rows).join('\n');
+            process.stdout.write(`\u001b[H\u001b[2J${body}\n`);
+            process.stdout.write(`\u001b[7m[CommandMate] ${worktreeId} / ${cliToolId} — Ctrl-C to stop\u001b[0m`);
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    finally {
+        restoreCursor();
+    }
+}
 function createCaptureCommand() {
     const cmd = new commander_1.Command('capture');
     cmd
@@ -258,6 +348,9 @@ function createCaptureCommand() {
         .option('--pane', 'Read the raw tmux pane as a transcript, with blank layout rows squeezed')
         .option('--tail <n>', 'With --pane: keep only the last N lines OF THE SQUEEZED transcript')
         .option('--raw', 'With --pane: skip the squeeze and print the pane verbatim')
+        // Issue #2317: the reading path that needs no tmux client and no key table.
+        .option('--follow', 'With --pane: redraw on an interval instead of printing once (Ctrl-C to stop)')
+        .option('--interval <ms>', `With --pane --follow: redraw interval in milliseconds (default ${DEFAULT_FOLLOW_INTERVAL_MS})`)
         // Issue #1685: audit trail of resolved prompts (question/options/answer/answeredBy)
         .option('--prompts', 'List recent prompts from chat history (including ones Auto-Yes already resolved)')
         .option('--limit <n>', `With --prompts: number of most recent prompts to list (default ${DEFAULT_PROMPTS_LIMIT})`)
@@ -286,6 +379,23 @@ function createCaptureCommand() {
                 console.error('Error: --tail and --raw require --pane.');
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
+            // Issue #2317: same rule as --tail/--raw. A --follow that silently did
+            // nothing outside --pane would look like the flag was accepted.
+            if (!options.pane && (options.follow || options.interval !== undefined)) {
+                console.error('Error: --follow and --interval require --pane.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            if (options.interval !== undefined && !options.follow) {
+                console.error('Error: --interval requires --follow.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            // The follow loop redraws the screen; --json and --raw are both "give me
+            // the bytes", and neither has a meaning that survives being overwritten
+            // every two seconds.
+            if (options.follow && (options.json || options.raw)) {
+                console.error('Error: --follow cannot be combined with --json or --raw.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
             // Issue #1685: --prompts reads history, --pane reads the live pane —
             // asking for both at once has no meaningful answer.
             if (options.prompts && options.pane) {
@@ -301,6 +411,10 @@ function createCaptureCommand() {
                 return;
             }
             if (options.pane) {
+                if (options.follow) {
+                    await capturePaneFollow(worktreeId, options);
+                    return;
+                }
                 await capturePane(worktreeId, options);
                 return;
             }

package/dist/cli/commands/instances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAwC,MAAM,qBAAqB,CAAC;AAiGtF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB7B;AAwND,wBAAgB,sBAAsB,IAAI,OAAO,CAqEhD"}
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAwC,MAAM,qBAAqB,CAAC;AA8HtF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB7B;AA2ND,wBAAgB,sBAAsB,IAAI,OAAO,CAqEhD"}

package/dist/cli/commands/instances.js

@@ -19,6 +19,23 @@ const command_helpers_1 = require("../utils/command-helpers");
 const cli_tool_ids_1 = require("../config/cli-tool-ids");
 const agent_instances_1 = require("../utils/agent-instances");
 const session_target_1 = require("../utils/session-target");
+// Issue #2317: the tmux session name each instance runs in, so `commandmate
+// attach` / `tmux attach` need no hand-assembly of `mcbd-<tool>-<wt>[-<suffix>]`.
+const session_name_1 = require("../../lib/cli-tools/session-name");
+/**
+ * The tmux session name for one roster row, or null.
+ *
+ * @param worktreeId - Worktree ID
+ * @param inst - Roster entry
+ */
+function deriveInstanceSession(worktreeId, inst) {
+    try {
+        return (0, session_name_1.resolveSessionName)(inst.cliTool, worktreeId, inst.id);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Longest session title printed in the table (Issue #2038).
  *
@@ -39,8 +56,8 @@ function formatInstancesTable(rows) {
     const headers = [
         'INSTANCE_ID', 'ALIAS', 'CLI_TOOL', 'RUNNING', 'AUTO_YES', 'MODEL', 'EFFORT',
         // Issue #2038 appends, exactly as #1785 did, so anything reading this table
-        // by column position keeps working.
-        'SESSION_ID', 'SESSION_TITLE',
+        // by column position keeps working. Issue #2317 appends for the same reason.
+        'SESSION_ID', 'SESSION_TITLE', 'TMUX_SESSION',
     ];
     const dataRows = rows.map(r => [
         r.instanceId,
@@ -55,6 +72,7 @@ function formatInstancesTable(rows) {
         r.reasoningEffort ?? '',
         r.sessionId ?? '',
         (r.sessionTitle ?? '').slice(0, MAX_SESSION_TITLE_COLUMN),
+        r.tmuxSession ?? '',
     ]);
     const colWidths = headers.map((h, i) => Math.max(h.length, ...dataRows.map(r => r[i].length)));
     const headerLine = headers.map((h, i) => h.padEnd(colWidths[i])).join('  ');
@@ -158,6 +176,9 @@ async function listInstances(worktreeId, options) {
             // Issue #2038: additive, and absent for every tool that is not opencode.
             sessionId: opencodeSessions.get(inst.id)?.sessionId ?? null,
             sessionTitle: opencodeSessions.get(inst.id)?.title ?? null,
+            // Issue #2317: additive, and in both the table and `--json` — the table
+            // is where somebody who does not know the naming rule will see it.
+            tmuxSession: deriveInstanceSession(worktreeId, inst),
         };
     }));
     if (options.json) {

package/dist/cli/commands/ls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ls.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkJpC;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CA8CzC"}
+{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ls.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6LpC;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CA8CzC"}

package/dist/cli/commands/ls.js

@@ -11,6 +11,10 @@ const api_client_1 = require("../utils/api-client");
 // and the server must not be able to disagree about what `exited` is spelled.
 const status_reason_1 = require("../../lib/detection/status-reason");
 const command_helpers_1 = require("../utils/command-helpers");
+// Issue #2317: the tmux session name, so nobody has to assemble
+// `mcbd-<tool>-<worktree>[-<suffix>]` by hand from two commands' output.
+const cli_tool_ids_1 = require("../config/cli-tool-ids");
+const session_name_1 = require("../../lib/cli-tools/session-name");
 /**
  * Derive display status from worktree flags.
  *
@@ -117,6 +121,35 @@ function formatTable(worktrees) {
     const dataLines = rows.map(r => r.map((cell, i) => cell.padEnd(colWidths[i])).join('  '));
     return [headerLine, separator, ...dataLines].join('\n');
 }
+/**
+ * The tmux session name of this worktree's DEFAULT agent, or null (Issue #2317).
+ *
+ * The default agent's PRIMARY instance, which is the session `commandmate
+ * attach <id>` opens with no flags — so the two answers cannot disagree. A
+ * worktree running several agents has several sessions, and this field names one
+ * of them on purpose: the complete per-instance list is what
+ * `commandmate instances <id>` is for, and duplicating it here would put the
+ * roster in two places.
+ *
+ * Null when the row names no default agent, or names one this CLI does not know
+ * (a server newer than the CLI), or when the id would not survive
+ * `validateSessionName` — the same three cases in which there is no name to
+ * give rather than a wrong one.
+ *
+ * Computed CLIENT-side. The server does not publish it, and asking it to would
+ * mean `/api/worktrees` — the sidebar's poll, for every worktree, every couple
+ * of seconds — carrying a string derivable from two fields already in the row.
+ */
+function deriveTmuxSession(wt) {
+    if (!wt.cliToolId || !(0, cli_tool_ids_1.isCliToolId)(wt.cliToolId))
+        return null;
+    try {
+        return (0, session_name_1.resolveSessionName)(wt.cliToolId, wt.id);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Format output based on options [DR1-02]
  *
@@ -135,7 +168,14 @@ function formatTable(worktrees) {
  */
 function formatOutput(worktrees, options) {
     if (options.json) {
-        return JSON.stringify(worktrees, null, 2);
+        // Issue #2317 appends one key and changes nothing else: every field the
+        // server sent still passes through verbatim, so a consumer reading
+        // `sessionStatusByCli.<tool>.statusEvidence` is unaffected.
+        const rows = worktrees.map((wt) => ({
+            ...wt,
+            tmuxSession: deriveTmuxSession(wt),
+        }));
+        return JSON.stringify(rows, null, 2);
     }
     if (options.quiet) {
         return worktrees.map(wt => wt.id).join('\n');

package/dist/cli/config/cli-dependencies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-dependencies.d.ts","sourceRoot":"","sources":["../../../src/cli/config/cli-dependencies.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,eAAe,EAiEzC,CAAC;AAEF;;GAEG;AACH,wBAAgB,eAAe,IAAI,eAAe,EAAE,CAEnD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,eAAe,EAAE,CAE3D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,eAAe,EAAE,CAE3D"}
+{"version":3,"file":"cli-dependencies.d.ts","sourceRoot":"","sources":["../../../src/cli/config/cli-dependencies.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,eAAe,EAmGzC,CAAC;AAEF;;GAEG;AACH,wBAAgB,eAAe,IAAI,eAAe,EAAE,CAEnD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,eAAe,EAAE,CAE3D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,eAAe,EAAE,CAE3D"}