commandmate 0.18.0 → 0.20.0

package/dist/cli/commands/update.js

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateCommand = updateCommand;
 const dotenv_1 = require("dotenv");
 const fs_1 = require("fs");
+const path_1 = require("path");
 const types_1 = require("../types");
 const logger_1 = require("../utils/logger");
 const paths_1 = require("../utils/paths");
@@ -41,6 +42,12 @@ const update_lock_1 = require("../../lib/app-update/update-lock");
 const logger = new logger_1.CLILogger();
 /** npm package name (kept as a literal: never build it from a dynamic path) */
 const PACKAGE_NAME = 'commandmate';
+/**
+ * Update log file name. Must stay identical to `UPDATE_LOG_FILENAME` in
+ * api/app/update/route.ts:36 — that route reports the path to the UI, and it resolves it the
+ * same way (`join(ensureConfigDir(), ...)`), so both must name the same file.
+ */
+const UPDATE_LOG_FILENAME = 'update.log';
 /**
  * Execute the update command.
  *
@@ -271,6 +278,8 @@ async function updateCommand(options = {}) {
  * stop the freshly-started daemon). npx env hygiene lives inside npx-runner.
  */
 async function runNpxSelfUpdate() {
+    // Issue #1633: surfaced first, so it is recorded even when the update itself aborts below.
+    warnStaleGlobalInstall();
     // .env must exist and be loaded before status/auth resolution so the health
     // check URL and token resolve correctly (mirrors step 6).
     const envPath = (0, env_setup_1.getEnvPath)();
@@ -385,6 +394,63 @@ async function runNpxSelfUpdate() {
     printNpxManualRelaunch();
     process.exit(types_1.ExitCode.START_FAILED);
 }
+/**
+ * Warn when a `npm install -g` install is still on the machine (Issue #1633).
+ *
+ * The npx self-update replaces only the npx cache. A global install keeps shadowing
+ * `commandmate` on PATH at whatever version it was last installed at, and nothing used to say
+ * so: one machine ran a 0.18.0 server (self-updated via npx) behind a 0.2.4 global CLI for
+ * months, which is how #1632 stayed invisible.
+ *
+ * This is advisory only. Detection failures (npm missing, `npm root -g` refused) skip the
+ * notice; they never abort the update.
+ */
+function warnStaleGlobalInstall() {
+    let installed;
+    try {
+        installed = (0, npm_runner_1.findGlobalInstallation)(PACKAGE_NAME);
+    }
+    catch {
+        return;
+    }
+    if (installed === null) {
+        return;
+    }
+    const label = installed.version ? `v${installed.version}` : 'unknown version';
+    const lines = [
+        `A global install of ${PACKAGE_NAME} (${label}) is still present at ${installed.path}.`,
+        `This npx update only refreshes the npx cache, so that copy stays at ${label} and keeps ` +
+            `shadowing "${PACKAGE_NAME}" on your PATH.`,
+        `Update it as well:  npm install -g ${PACKAGE_NAME}@latest`,
+        `Or remove it:       npm uninstall -g ${PACKAGE_NAME}`,
+    ];
+    for (const line of lines) {
+        logger.warn(line);
+    }
+    appendUpdateLog(lines.map((line) => `[WARN] ${line}`));
+}
+/**
+ * Append lines to ~/.commandmate/update.log.
+ *
+ * When the GUI starts this command the child's stdout/stderr are already the update log
+ * (api/app/update/route.ts:129-159), so console output lands there too and these lines appear
+ * twice. The explicit write is what keeps the record when the command is run by hand, where
+ * stdout is a terminal and nothing would otherwise be persisted.
+ *
+ * Logging must never break an update, so every failure is swallowed.
+ */
+function appendUpdateLog(lines) {
+    try {
+        const logPath = (0, path_1.join)((0, install_context_1.ensureConfigDir)(), UPDATE_LOG_FILENAME);
+        const timestamp = new Date().toISOString();
+        (0, fs_1.appendFileSync)(logPath, lines.map((line) => `${timestamp} ${line}\n`).join(''), {
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Best effort: the console output above already carried the message.
+    }
+}
 /**
  * Read the version from the installed package.json.
  * @throws if package.json cannot be read or has no version

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

@@ -4,10 +4,13 @@
  *
  * Exit codes [DR1-03]:
  * - 0: SUCCESS (agent completed)
- * - 10: PROMPT_DETECTED (agent waiting for user input)
+ * - 10: PROMPT_DETECTED (agent waiting for user input, including arrow-key
+ *       selection lists — Issue #1628)
  * - 124: TIMEOUT (--timeout exceeded)
  * Issue #1544 adds --verify / --require-work, which can turn a detected
  * completion into 20 (VERIFY_FAILED) or 21 (NOT_STARTED).
+ * Issue #1628 also returns 21 without --verify when the session was never
+ * running: a wait with nothing to wait for must not report success.
  * Infrastructure errors use ExitCode (1, 2, 99)
  */
 import { Command } from 'commander';

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

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2NpC,wBAAgB,iBAAiB,IAAI,OAAO,CAuG3C"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAySpC,wBAAgB,iBAAiB,IAAI,OAAO,CA6G3C"}

package/dist/cli/commands/wait.js

@@ -5,10 +5,13 @@
  *
  * Exit codes [DR1-03]:
  * - 0: SUCCESS (agent completed)
- * - 10: PROMPT_DETECTED (agent waiting for user input)
+ * - 10: PROMPT_DETECTED (agent waiting for user input, including arrow-key
+ *       selection lists — Issue #1628)
  * - 124: TIMEOUT (--timeout exceeded)
  * Issue #1544 adds --verify / --require-work, which can turn a detected
  * completion into 20 (VERIFY_FAILED) or 21 (NOT_STARTED).
+ * Issue #1628 also returns 21 without --verify when the session was never
+ * running: a wait with nothing to wait for must not report success.
  * Infrastructure errors use ExitCode (1, 2, 99)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -18,8 +21,19 @@ const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const verify_runner_1 = require("../utils/verify-runner");
+const agent_target_options_1 = require("../config/agent-target-options");
 /** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
 const POLL_INTERVAL_MS = 5000;
+/**
+ * `type` reported for a blocked-on-a-human frame that carries no parsable prompt
+ * (Issue #1628). Arrow-key menus — Codex's pager and `/model`, antigravity's
+ * permission menu, OpenCode's `/models` overlay — are deliberately published as
+ * selection lists rather than prompts so the UI renders NavigationButtons, which
+ * left `wait` with no signal at all for them: it polled until the timeout while
+ * the agent sat stopped. They are not answerable as a prompt, so the payload
+ * names the state instead of inventing options.
+ */
+const SELECTION_LIST_PROMPT_TYPE = 'selection_list';
 /**
  * Poll a single worktree until completion, prompt, or timeout.
  */
@@ -27,6 +41,14 @@ async function pollWorktree(client, worktreeId, options) {
     const startTime = Date.now();
     let lastActivityTime = Date.now();
     let lastContent = '';
+    /**
+     * Issue #1628: whether this wait ever saw the session alive. `!isRunning` on the
+     * FIRST poll is "there is nothing here to wait for", not "the agent finished" —
+     * reporting SUCCESS for it is how a wait on a worktree whose agent never started
+     * (wrong tool, wrong instance, session never created) came back `Completed` in
+     * milliseconds and handed a `passed` verdict to whatever ran next.
+     */
+    let everRunning = false;
     while (true) {
         // Check timeout
         if (options.timeout) {
@@ -55,6 +77,9 @@ async function pollWorktree(client, worktreeId, options) {
                 lastContent = data.content;
                 lastActivityTime = Date.now();
             }
+            if (data.isRunning) {
+                everRunning = true;
+            }
             // Prompt detected
             if (data.isPromptWaiting && data.promptData) {
                 // [DR1-03] Prompt detection exit code
@@ -75,10 +100,42 @@ async function pollWorktree(client, worktreeId, options) {
                 };
                 return { exitCode: types_1.WaitExitCode.PROMPT_DETECTED, output: promptOutput };
             }
+            // Issue #1628: an arrow-key menu is the agent blocked on a human just as much
+            // as a numbered prompt is, but it is published with isPromptWaiting=false so
+            // the UI can render NavigationButtons instead of PromptPanel. Treat it as a
+            // prompt here — otherwise `wait` polls a stopped agent until --timeout.
+            if (data.isSelectionListActive) {
+                if (options.onPrompt === 'human') {
+                    console.error(`Selection list active on ${worktreeId} (${data.sessionStatusReason ?? 'selection_list'}). ` +
+                        'Waiting for human response...');
+                    await sleep(POLL_INTERVAL_MS);
+                    continue;
+                }
+                return {
+                    exitCode: types_1.WaitExitCode.PROMPT_DETECTED,
+                    output: {
+                        worktreeId,
+                        cliToolId: data.cliToolId || 'claude',
+                        type: SELECTION_LIST_PROMPT_TYPE,
+                        question: data.sessionStatusReason ?? SELECTION_LIST_PROMPT_TYPE,
+                        options: [],
+                        status: 'pending',
+                    },
+                };
+            }
             // Completion check [DR1-04]:
-            // Path A: tmux session not running (session terminated or not started)
+            // Path A: the tmux session went away after we had seen it alive — the agent
+            //         finished and its session was stopped.
             // Path B: agent completed task (sessionStatus === 'ready', input prompt detected)
-            // Both indicate "no more work in progress" from wait command's perspective
+            // Both indicate "no more work in progress" from wait command's perspective.
+            //
+            // Issue #1628 narrowed Path A: a session that was NEVER seen running is
+            // "nothing to wait for" (NOT_STARTED), not a completion. See `everRunning`.
+            if (!data.isRunning && !everRunning) {
+                console.error(`Not started: ${worktreeId} has no running ${data.cliToolId ?? 'agent'} session` +
+                    `${options.instance ? ` for instance ${options.instance}` : ''}.`);
+                return { exitCode: types_1.VerifyExitCode.NOT_STARTED };
+            }
             if (!data.isRunning || data.sessionStatus === 'ready') {
                 console.error(`Completed: ${worktreeId}`);
                 return { exitCode: types_1.WaitExitCode.SUCCESS };
@@ -102,6 +159,21 @@ function sleep(ms) {
 function verifyRequested(options) {
     return Boolean(options.verify || options.requireWork);
 }
+/**
+ * Whether this poll outcome should still be handed to the verification gates.
+ *
+ * A completion is the obvious case. NOT_STARTED joins it (Issue #1628) so the
+ * operator gets the gate results instead of a bare "no session": work committed
+ * by an agent whose session has since gone away is still worth reporting. The
+ * verdict is merged rather than substituted — mergeExitCode never lets a passing
+ * run overwrite NOT_STARTED, so "wait never saw this agent" survives to the exit
+ * code even when the gates are green.
+ */
+function shouldVerify(exitCode, options) {
+    if (!verifyRequested(options))
+        return false;
+    return exitCode === types_1.WaitExitCode.SUCCESS || exitCode === types_1.VerifyExitCode.NOT_STARTED;
+}
 /**
  * Task statuses that mean "this wait is about that task".
  *
@@ -201,7 +273,7 @@ function createWaitCommand() {
         .option('--timeout <seconds>', 'Maximum wait time in seconds', parseInt)
         .option('--on-prompt <mode>', 'Prompt handling: agent (default) or human')
         .option('--stall-timeout <seconds>', 'Maximum time without output change', parseInt)
-        .option('--instance <id>', 'Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). Defaults to the agent\'s primary instance.')
+        .option('--instance <id>', agent_target_options_1.WAIT_INSTANCE_OPTION_DESCRIPTION)
         .option('--verify', 'After completion, run every verification gate; exit 20 when a gate fails, 21 when there is nothing to verify')
         .option('--require-work', 'After completion, run only the work-evidence gate; exit 21 when the worktree has no commits and no uncommitted changes')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
@@ -237,8 +309,8 @@ function createWaitCommand() {
                 }
                 // Issue #1544: only a detected completion is worth verifying — a
                 // prompt or a timeout means the agent never claimed to be done.
-                const exitCode = result.exitCode === types_1.WaitExitCode.SUCCESS && verifyRequested(options)
-                    ? await verifyAfterWait(client, worktreeIds[0], options, boundTaskIds[0])
+                const exitCode = shouldVerify(result.exitCode, options)
+                    ? mergeExitCode(result.exitCode, await verifyAfterWait(client, worktreeIds[0], options, boundTaskIds[0]))
                     : result.exitCode;
                 process.exit(exitCode);
                 return;
@@ -254,8 +326,11 @@ function createWaitCommand() {
                     if (result.value.output) {
                         outputs.push(result.value.output);
                     }
-                    if (result.value.exitCode === types_1.WaitExitCode.SUCCESS && verifyRequested(options)) {
+                    if (shouldVerify(result.value.exitCode, options)) {
                         verifyTargets.push({ id: worktreeIds[index], taskId: boundTaskIds[index] });
+                        // Issue #1628: fold NOT_STARTED in before verification so a green
+                        // gate run cannot promote "no session was ever running" to success.
+                        finalExitCode = mergeExitCode(finalExitCode, result.value.exitCode);
                         return;
                     }
                     finalExitCode = mergeExitCode(finalExitCode, result.value.exitCode);

package/dist/cli/config/agent-target-options.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared help text for the two flags that name *where* a message goes:
+ * `--instance` (the instance) and `--agent` (the CLI tool behind it).
+ *
+ * Issue #1638: the flags were not interchangeable and the docs did not say so.
+ * `--instance` is accepted by `send` / `wait` / `respond` / `capture` /
+ * `auto-yes`; `--agent` is accepted by every one of those except `wait`, which
+ * rejects it with `unknown option` (exit 1). A worktree cut for Codex therefore
+ * ran Claude in silence when a workflow copied from the quick start omitted the
+ * target flag on the one command that could not take it.
+ *
+ * ## Why `--agent` is kept rather than removed
+ *
+ * Removing it would break every shipped script, the embedded `commandmate docs`
+ * guide and the published user guide, in exchange for making the flag set look
+ * symmetric. It also cannot be removed outright: `send --register` needs an
+ * explicit CLI tool whenever the instance id is not itself a tool id
+ * (`--instance codex-3 --register` has no other way to say "this is codex"),
+ * and an ad-hoc instance the roster has never seen carries no tool either.
+ *
+ * So `--agent` stays as-is — same parsing, same precedence (Issue #1629: the
+ * roster wins, a contradiction is an error) — and only its *position* changes:
+ * it is the supplement for ad-hoc, roster-less instances, not the way to pick
+ * an agent. The recommended form is `--instance <id>` on its own, which works
+ * on all five commands: a rostered instance carries its CLI tool, and an
+ * instance id that is itself a tool id (`--instance codex`) resolves to that
+ * tool's primary instance without a roster row.
+ *
+ * Adding `wait --agent` was rejected in #1629: without an instance, `--agent
+ * codex` does not say *which* codex session to wait on.
+ */
+/**
+ * `--agent` description for send / respond / capture / auto-yes.
+ * `instances add --agent` is deliberately NOT this text: there the flag
+ * declares the tool of a new roster entry and is required, not a supplement.
+ */
+export declare const AGENT_OPTION_DESCRIPTION: string;
+/** `--instance` description, shared by send / respond / capture / auto-yes. */
+export declare const INSTANCE_OPTION_DESCRIPTION: string;
+/**
+ * `--instance` description for `wait`, which has no `--agent` to fall back on.
+ * Spelling that out here is the point of the Issue: a workflow that names the
+ * agent on `send` and nothing on `wait` waits on the wrong session in silence.
+ */
+export declare const WAIT_INSTANCE_OPTION_DESCRIPTION: string;
+//# sourceMappingURL=agent-target-options.d.ts.map

package/dist/cli/config/agent-target-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-target-options.d.ts","sourceRoot":"","sources":["../../../src/cli/config/agent-target-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAGoD,CAAC;AAE1F,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,QAGO,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,QAEgB,CAAC"}

package/dist/cli/config/agent-target-options.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Shared help text for the two flags that name *where* a message goes:
+ * `--instance` (the instance) and `--agent` (the CLI tool behind it).
+ *
+ * Issue #1638: the flags were not interchangeable and the docs did not say so.
+ * `--instance` is accepted by `send` / `wait` / `respond` / `capture` /
+ * `auto-yes`; `--agent` is accepted by every one of those except `wait`, which
+ * rejects it with `unknown option` (exit 1). A worktree cut for Codex therefore
+ * ran Claude in silence when a workflow copied from the quick start omitted the
+ * target flag on the one command that could not take it.
+ *
+ * ## Why `--agent` is kept rather than removed
+ *
+ * Removing it would break every shipped script, the embedded `commandmate docs`
+ * guide and the published user guide, in exchange for making the flag set look
+ * symmetric. It also cannot be removed outright: `send --register` needs an
+ * explicit CLI tool whenever the instance id is not itself a tool id
+ * (`--instance codex-3 --register` has no other way to say "this is codex"),
+ * and an ad-hoc instance the roster has never seen carries no tool either.
+ *
+ * So `--agent` stays as-is — same parsing, same precedence (Issue #1629: the
+ * roster wins, a contradiction is an error) — and only its *position* changes:
+ * it is the supplement for ad-hoc, roster-less instances, not the way to pick
+ * an agent. The recommended form is `--instance <id>` on its own, which works
+ * on all five commands: a rostered instance carries its CLI tool, and an
+ * instance id that is itself a tool id (`--instance codex`) resolves to that
+ * tool's primary instance without a roster row.
+ *
+ * Adding `wait --agent` was rejected in #1629: without an instance, `--agent
+ * codex` does not say *which* codex session to wait on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WAIT_INSTANCE_OPTION_DESCRIPTION = exports.INSTANCE_OPTION_DESCRIPTION = exports.AGENT_OPTION_DESCRIPTION = void 0;
+const cli_tool_ids_1 = require("./cli-tool-ids");
+/**
+ * `--agent` description for send / respond / capture / auto-yes.
+ * `instances add --agent` is deliberately NOT this text: there the flag
+ * declares the tool of a new roster entry and is required, not a supplement.
+ */
+exports.AGENT_OPTION_DESCRIPTION = `Ad-hoc CLI tool for an instance the roster does not know (${cli_tool_ids_1.CLI_TOOL_IDS.join(', ')}). `
+    + 'Prefer --instance on its own: a rostered instance already carries its CLI tool, '
+    + 'and --instance is the only target flag every command accepts (wait has no --agent).';
+/** `--instance` description, shared by send / respond / capture / auto-yes. */
+exports.INSTANCE_OPTION_DESCRIPTION = 'Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). '
+    + 'Recommended way to name the target; accepted by send/wait/respond/capture/auto-yes. '
+    + "Defaults to the agent's primary instance.";
+/**
+ * `--instance` description for `wait`, which has no `--agent` to fall back on.
+ * Spelling that out here is the point of the Issue: a workflow that names the
+ * agent on `send` and nothing on `wait` waits on the wrong session in silence.
+ */
+exports.WAIT_INSTANCE_OPTION_DESCRIPTION = `${exports.INSTANCE_OPTION_DESCRIPTION} wait takes no --agent, so name the instance here `
+    + '(e.g. --instance codex for the codex primary instance).';

package/dist/cli/docs/agent-operations.d.ts

@@ -5,6 +5,6 @@
  * This content is embedded as a string constant so that it's available
  * even when installed via `npm install -g commandmate` (where docs/ is not included).
  */
-export declare const AGENT_OPERATIONS_GUIDE = "# CLI Agent Operations Guide\n\nOperate agent sessions from the CommandMate CLI.\nThese commands enable coding agents (Claude Code, Codex, etc.) to orchestrate other agents in parallel.\n\n## Prerequisites\n\n- CommandMate server must be running: commandmate start --daemon\n- Target worktrees must be registered (visible in browser UI sidebar)\n- Use CM_PORT env var to connect to a different port (default: 3000)\n- Use CM_AUTH_TOKEN env var for authenticated servers\n\n## Commands\n\n### commandmate ls\n  List worktrees with status.\n\n  commandmate ls                          # Table format (ID, NAME, STATUS, DEFAULT)\n  commandmate ls --json                   # JSON output (for agent consumption)\n  commandmate ls --quiet                  # IDs only, one per line (for piping)\n  commandmate ls --branch <prefix>        # Filter by branch name prefix\n  commandmate ls --id <prefix>            # Filter by worktree id prefix\n\n  Worktree ids are <repo>-<branch> slugs (e.g. anvil-develop). --id / --branch\n  front-match is case-sensitive and does NOT guarantee uniqueness (e.g.\n  --id anvil-develop also matches anvil-develop-2). --branch and --id combine\n  as AND. Use --id to disambiguate the same branch across repositories.\n\n  STATUS values:\n    idle     - Session not started\n    ready    - Session running, waiting for input (task completed)\n    running  - Agent executing a task\n    waiting  - Confirmation prompt active (Yes/No, etc.)\n\n### commandmate send <worktree-id> \"<message>\"\n  Send a message to an agent (async). Starts session automatically if not running.\n\n  Options:\n    --agent <id>           Agent type: claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity\n    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). See \"Multi-Session\" below.\n    --register             Register the --instance session into the agent-instance roster\n    --auto-yes             Enable auto-yes before sending\n    --duration <d>         Auto-yes duration: 1h, 3h, 8h (default: 1h)\n    --stop-pattern <p>     Auto-yes stop condition (regex)\n\n  Finding worktree IDs:\n    WT=$(commandmate ls --branch feature/101 --quiet)\n    WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)\n    commandmate send \"$WT\" \"Implement this\"\n\n### commandmate wait <worktree-id...>\n  Block until agent completes or prompt is detected.\n\n  Options:\n    --timeout <seconds>        Maximum wait time\n    --on-prompt <mode>         agent (default) or human\n    --stall-timeout <seconds>  Max time without output change\n    --verify                   After completion, run every verification gate\n    --require-work             After completion, run only the work-evidence gate\n\n  Exit codes:\n    0   - Completed (agent idle/ready), and verified when --verify was given\n    10  - Prompt detected (--on-prompt agent mode)\n    20  - A verification gate failed (--verify)\n    21  - Nothing to verify: no commits, no uncommitted changes\n    124 - Timeout exceeded\n\n  --on-prompt modes:\n    agent  - Returns exit 10 immediately with prompt JSON on stdout\n    human  - Keeps blocking until human responds via browser UI\n\n  Prompt JSON output (exit 10):\n    {\"worktreeId\":\"...\",\"cliToolId\":\"claude\",\"type\":\"yes_no\",\"question\":\"...\",\"options\":[\"yes\",\"no\"],\"status\":\"pending\"}\n\n  --verify turns \"the agent stopped\" into \"the work passes the repository's own\n  checks\". Verification only runs when completion was detected: a prompt (10) or\n  a timeout (124) is reported as-is and never verified. With several worktrees,\n  gates run one worktree at a time because the server caps concurrent runs.\n\n### commandmate verify <worktree-id>\n  Run the gates declared in .commandmate/verify.yaml against a worktree.\n\n  Options:\n    --gates <id1,id2>     Gate ids to run (default: work-evidence + all declared)\n    --instance <id>       Attribute the run to an agent instance\n    --timeout <seconds>   Stop polling after N seconds (exit 124)\n    --json                Print the run and its gate results as JSON on stdout\n\n  Exit codes:\n    0   - Every gate passed\n    20  - A gate failed, timed out, or errored\n    21  - work-evidence found nothing to verify (no commits, no changes)\n    99  - The run produced no verdict (bad verify.yaml, gates skipped, cancelled)\n    124 - --timeout elapsed while the run was still going\n\n  Output (progress on stderr, verdict on stdout):\n    GATE work-evidence PASS (commits=3, uncommitted=2)\n    GATE lint PASS (exit=0, 12.3s)\n    GATE unit FAIL (exit=1, 45.0s)\n    RESULT failed\n\n  Gates run in the worktree's own directory. Gates are skipped (run status 99,\n  never 0) in the checkout the server itself runs from when verify.yaml sets\n  options.skipInPrimaryCheckout, so a 'build' gate cannot replace the assets the\n  live app is serving.\n\n### commandmate verify history / commandmate verify show <run-id>\n  Read past verification runs. Both are read-only and never start a run, so\n  neither returns 20 or 21 \u2014 those mean \"this tree failed verification\", and a\n  question about history is not a verdict on the current tree.\n\n  commandmate verify history                          # every worktree, newest 50\n  commandmate verify history --worktree <id>          # one worktree\n  commandmate verify history --days 14 --limit 100    # window and page size\n  commandmate verify history --json                   # JSON array on stdout\n  commandmate verify show 42                          # gates + log tails\n  commandmate verify show 42 --json\n\n  history options:\n    --worktree <id>       Restrict to one worktree (default: all)\n    --days <n>            Look back n days, 1..90 (default: no lower bound)\n    --limit <n>           Maximum runs, 1..500 (default: 50)\n\n  One run per line. The leading #<run-id> is what \"verify show\" takes:\n    #42  2026-07-31T04:12:00.000Z  myrepo-feature-101  manual  failed  failed: unit,build\n\n  The listing carries gate verdicts but NOT gate log bodies \u2014 logTail is absent\n  from the JSON, not null. Use \"verify show <run-id>\" when you need the log.\n\n  Exit codes:\n    0   - Read succeeded (also when nothing matched: stderr note, or [] in JSON)\n    2   - Bad argument (--days/--limit out of range, bad worktree or run id)\n    99  - No such run (404), or an unexpected failure\n\n### commandmate respond <worktree-id> \"<answer>\"\n  Respond to an agent's prompt.\n\n  commandmate respond <id> \"yes\"          # Yes/No\n  commandmate respond <id> \"2\"            # Multiple choice (number)\n  commandmate respond <id> \"custom text\"  # Free text\n\n  Exit codes:\n    0  - Response sent\n    99 - Prompt already dismissed (prompt_no_longer_active)\n\n### commandmate capture <worktree-id>\n  Get current terminal output.\n\n  commandmate capture <id>                # Plain text\n  commandmate capture <id> --json         # JSON with status info\n  commandmate capture <id> --agent codex  # Specific agent\n\n### commandmate auto-yes <worktree-id>\n  Control auto-yes (automatic prompt response).\n\n  commandmate auto-yes <id> --enable                    # Enable (default 1h)\n  commandmate auto-yes <id> --enable --duration 3h      # With duration\n  commandmate auto-yes <id> --enable --stop-pattern \"error\"\n  commandmate auto-yes <id> --disable                   # Disable\n\n### commandmate instances <worktree-id> [action] [args]\n  Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).\n\n  commandmate instances <id>                            # List roster + running/auto-yes status\n  commandmate instances <id> --json                     # JSON output\n  commandmate instances <id> add --agent codex          # Add an instance (auto-generates ID, e.g. codex-2)\n  commandmate instances <id> add --agent codex --alias \"Review\" --id codex-3\n  commandmate instances <id> remove <instance-id>       # Remove from roster\n  commandmate instances <id> remove <instance-id> --kill  # Remove and kill its session\n  commandmate instances <id> alias <instance-id> \"New Name\"\n  commandmate instances <id> kill <instance-id>         # Kill only that instance's session\n\n  See \"Multi-Session\" below for the ID convention and roster semantics.\n\n### commandmate skill <subcommand>\n  Manage official Agent Skills. Every subcommand is a thin client over the same\n  APIs the browser UI uses: the CLI never downloads, extracts, writes or deletes\n  anything itself, and never sends a filesystem path, artifact URL, file list or\n  checksum (the API rejects those outright).\n\n  commandmate skill list [--json] [--prerelease]\n  commandmate skill info <skill-id> [--version <v>] [--json]\n  commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]\n  commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>] [--json]\n  commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]\n  commandmate skill status <skill-id> --worktree <id> [--json]\n\n  Confirmation contract (writes = install / uninstall):\n    - A plan is always built and shown first. --dry-run stops there.\n    - Without a TTY, a write REQUIRES --yes. A missing --yes is refused, never\n      assumed: an environment that cannot prompt must not install silently.\n    - A high-risk Skill additionally requires --ack-risk <skill-id>@<version>\n      with the exact id and version. --yes alone never carries a high-risk\n      install, in a TTY or out of one.\n\n  Exit codes:\n    0   success\n    1   the server or the Catalog could not be reached (retryable)\n    2   invalid arguments, unknown Skill or unknown version\n    11  the worktree refused it (local change, conflict, lock, plan drift)\n    12  the write was never confirmed (no --yes, declined, or missing --ack-risk)\n    13  files changed but the operation needs reconciliation\n\n  --json prints the API response body verbatim on stdout; diagnostics, prompts\n  and errors always go to stderr, so a failed --json run leaves stdout empty.\n\n  'skill status' reports one Skill in one worktree, read from the install\n  receipt on disk. There is no per-worktree listing endpoint yet, so <skill-id>\n  is required.\n\n## Multi-Session (1 agent, multiple sessions)\n\n  A worktree can run several sessions of the same CLI tool concurrently. Each\n  session is an \"instance\" identified by an instance ID:\n    <agent>        - the agent's primary instance (e.g. \"claude\")\n    <agent>-<n>    - an additional instance, n >= 2 (e.g. \"claude-2\", \"claude-3\")\n\n  --instance is accepted by send / wait / respond / capture / auto-yes.\n  send --instance auto-starts the session if it is not already running.\n\n  The roster (visible in the browser UI's Agent panel) is the list of known\n  instances with aliases and display order. Ad-hoc sessions started via\n  'send --instance' do NOT appear in the roster unless registered:\n    commandmate send <id> \"...\" --instance claude-2 --register\n  Without --register, the session still runs and responds to CLI commands,\n  but it will not show up in the UI sidebar/roster until added there or via\n  'commandmate instances <id> add'.\n\n  Per-instance auto-yes: --instance scopes --auto-yes/--duration/--stop-pattern\n  to that specific session, independent of other instances of the same agent.\n\n  commandmate instances <id>                        # discover valid --instance values\n  commandmate send <id> \"task\" --agent codex --instance codex-2 --auto-yes\n  commandmate wait <id> --instance codex-2 --timeout 600\n  commandmate capture <id> --agent codex --instance codex-2\n\n## All Exit Codes\n\n  0   SUCCESS          - Completed successfully\n  1   DEPENDENCY_ERROR - Server not running\n  2   CONFIG_ERROR     - Validation error (invalid agent, duration, etc.)\n  10  PROMPT_DETECTED  - Prompt detected during wait\n  20  VERIFY_FAILED    - A verification gate failed (verify, wait --verify)\n  21  NOT_STARTED      - Nothing to verify: no commits, no uncommitted changes\n  99  UNEXPECTED_ERROR - Unexpected error / resource not found / no verdict\n  124 TIMEOUT          - Wait or verification timeout exceeded\n\n  When one 'wait' covers several worktrees, the reported code is the highest\n  priority one observed: 10 > 20 > 21 > 124.\n\n## Troubleshooting\n\n  Server not running:\n    commandmate start --daemon\n    CM_PORT=3011 commandmate ls        # Different port\n\n  Worktree not found:\n    commandmate ls --quiet             # Check registered IDs\n    curl -s -X POST http://localhost:3000/api/repositories/sync  # Sync new worktrees\n\n  Authentication:\n    CM_AUTH_TOKEN=your-token commandmate ls\n";
-export declare const AGENT_OPERATIONS_SAMPLES = "# CLI Agent Operations - Workflow Samples\n\nCopy and adapt these patterns for your use case.\n\n## 1. Basic: send, wait, capture\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101 with TDD\"\n  commandmate wait \"$WT\" --timeout 600\n  commandmate capture \"$WT\"\n\n## 2. With Auto-Yes (unattended execution)\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101\" --auto-yes --duration 3h\n  commandmate wait \"$WT\" --timeout 1800\n  commandmate auto-yes \"$WT\" --disable    # Disable for safety\n  commandmate capture \"$WT\" --json\n\n## 3. Prompt Response Loop\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Refactor this module\"\n\n  while true; do\n    commandmate wait \"$WT\" --timeout 600 --on-prompt agent\n    EXIT_CODE=$?\n\n    if [ $EXIT_CODE -eq 0 ]; then\n      echo \"Done\"\n      break\n    elif [ $EXIT_CODE -eq 10 ]; then\n      commandmate respond \"$WT\" \"yes\"\n    elif [ $EXIT_CODE -eq 124 ]; then\n      echo \"Timeout\"\n      break\n    fi\n  done\n\n  commandmate capture \"$WT\"\n\n## 4. Parallel Worktrees\n\n  WT1=$(commandmate ls --branch feature/101 --quiet)\n  WT2=$(commandmate ls --branch feature/102 --quiet)\n\n  commandmate send \"$WT1\" \"Implement #101\" --auto-yes\n  commandmate send \"$WT2\" \"Implement #102\" --auto-yes --agent codex\n\n  commandmate wait \"$WT1\" \"$WT2\" --timeout 1800\n\n  commandmate capture \"$WT1\" --json\n  commandmate capture \"$WT2\" --json\n\n## 5. Check status before sending\n\n  # Find worktrees and check status\n  commandmate ls --json | python3 -c \"\n  import sys, json\n  for wt in json.load(sys.stdin):\n      if wt['name'].startswith('feature/'):\n          print(f\\\"{wt['id']}  {wt['name']}\\\")\n  \"\n\n## 6. Error handling pattern\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  if [ -z \"$WT\" ]; then\n    echo \"Error: worktree not found\"\n    exit 1\n  fi\n\n  commandmate send \"$WT\" \"Fix the bug\" --auto-yes\n  commandmate wait \"$WT\" --timeout 600\n  EXIT_CODE=$?\n\n  case $EXIT_CODE in\n    0)   echo \"Success\"; commandmate capture \"$WT\" ;;\n    10)  echo \"Prompt detected\"; commandmate respond \"$WT\" \"yes\" ;;\n    124) echo \"Timeout\"; commandmate capture \"$WT\" --json ;;\n    *)   echo \"Error: exit $EXIT_CODE\" ;;\n  esac\n\n## 7. Multi-Session: run a second Codex session alongside the primary agent\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  # Discover the roster before picking an --instance value\n  commandmate instances \"$WT\"\n\n  # Register a second Codex instance, then send/wait/capture scoped to it\n  commandmate instances \"$WT\" add --agent codex --alias \"Review\"\n  commandmate send \"$WT\" \"Review the diff\" --agent codex --instance codex-2 --auto-yes\n  commandmate wait \"$WT\" --instance codex-2 --timeout 600\n  commandmate capture \"$WT\" --agent codex --instance codex-2 --json\n\n  # Ad-hoc instance without pre-registering (still runs; register to show in UI)\n  commandmate send \"$WT\" \"Quick check\" --agent codex --instance codex-3 --register\n\n  # Clean up when done\n  commandmate instances \"$WT\" remove codex-2 --kill\n\n## 8. Verify the work instead of trusting \"the agent stopped\"\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101 with TDD\" --auto-yes\n\n  # One call: wait for completion, then run every gate in .commandmate/verify.yaml\n  commandmate wait \"$WT\" --timeout 1800 --verify\n  case $? in\n    0)  echo \"Verified\" ;;\n    10) commandmate respond \"$WT\" \"yes\" ;;\n    20) echo \"A gate failed\"; commandmate verify \"$WT\" --json ;;\n    21) echo \"The agent produced nothing\" ;;\n  esac\n\n  # Cheap pre-check: is there any work at all, before paying for the full suite?\n  commandmate wait \"$WT\" --require-work || echo \"no commits and no changes\"\n\n  # Re-run a subset after a fix, without waiting on the agent\n  commandmate verify \"$WT\" --gates lint,unit\n";
+export declare const AGENT_OPERATIONS_GUIDE = "# CLI Agent Operations Guide\n\nOperate agent sessions from the CommandMate CLI.\nThese commands enable coding agents (Claude Code, Codex, etc.) to orchestrate other agents in parallel.\n\n## Prerequisites\n\n- CommandMate server must be running: commandmate start --daemon\n- Target worktrees must be registered (visible in browser UI sidebar)\n- Use CM_PORT env var to connect to a different port (default: 3000)\n- Use CM_AUTH_TOKEN env var for authenticated servers\n\n## Commands\n\n### commandmate ls\n  List worktrees with status.\n\n  commandmate ls                          # Table format (ID, NAME, STATUS, DEFAULT)\n  commandmate ls --json                   # JSON output (for agent consumption)\n  commandmate ls --quiet                  # IDs only, one per line (for piping)\n  commandmate ls --branch <prefix>        # Filter by branch name prefix\n  commandmate ls --id <prefix>            # Filter by worktree id prefix\n\n  Worktree ids are <repo>-<branch> slugs (e.g. anvil-develop). --id / --branch\n  front-match is case-sensitive and does NOT guarantee uniqueness (e.g.\n  --id anvil-develop also matches anvil-develop-2). --branch and --id combine\n  as AND. Use --id to disambiguate the same branch across repositories.\n\n  STATUS values:\n    idle     - Session not started\n    ready    - Session running, waiting for input (task completed)\n    running  - Agent executing a task\n    waiting  - Confirmation prompt active (Yes/No, etc.)\n\n### commandmate send <worktree-id> \"<message>\"\n  Send a message to an agent (async). Starts session automatically if not running.\n\n  Options:\n    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2, or codex\n                           for the codex primary instance). The recommended way to name a\n                           target: send / wait / respond / capture / auto-yes all take it.\n    --agent <id>           Ad-hoc CLI tool for an instance the roster does not know:\n                           claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity\n    --register             Register the --instance session into the agent-instance roster\n    --auto-yes             Enable auto-yes before sending\n    --duration <d>         Auto-yes duration: 1h, 3h, 8h (default: 1h)\n    --stop-pattern <p>     Auto-yes stop condition (regex)\n\n  Finding worktree IDs:\n    WT=$(commandmate ls --branch feature/101 --quiet)\n    WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)\n    commandmate send \"$WT\" \"Implement this\"\n\n  Targeting a non-default agent (Issue #1638): pass --instance, not --agent. Only\n  --instance is accepted by every command -- 'wait --agent' does not exist -- so a\n  workflow that names the agent on 'send' and nothing on 'wait' waits on the wrong\n  session in silence.\n    commandmate send \"$WT\" \"Implement this\" --instance codex\n    commandmate wait \"$WT\" --instance codex\n\n### commandmate wait <worktree-id...>\n  Block until agent completes or prompt is detected.\n\n  Options:\n    --timeout <seconds>        Maximum wait time\n    --on-prompt <mode>         agent (default) or human\n    --stall-timeout <seconds>  Max time without output change\n    --instance <id>            Agent instance to wait on. There is no --agent here.\n    --verify                   After completion, run every verification gate\n    --require-work             After completion, run only the work-evidence gate\n\n  Exit codes:\n    0   - Completed (agent idle/ready), and verified when --verify was given\n    10  - Prompt detected (--on-prompt agent mode)\n    20  - A verification gate failed (--verify)\n    21  - Nothing to verify: no commits, no uncommitted changes\n    124 - Timeout exceeded\n\n  --on-prompt modes:\n    agent  - Returns exit 10 immediately with prompt JSON on stdout\n    human  - Keeps blocking until human responds via browser UI\n\n  Prompt JSON output (exit 10):\n    {\"worktreeId\":\"...\",\"cliToolId\":\"claude\",\"type\":\"yes_no\",\"question\":\"...\",\"options\":[\"yes\",\"no\"],\"status\":\"pending\"}\n\n  --verify turns \"the agent stopped\" into \"the work passes the repository's own\n  checks\". Verification only runs when completion was detected: a prompt (10) or\n  a timeout (124) is reported as-is and never verified. With several worktrees,\n  gates run one worktree at a time because the server caps concurrent runs.\n\n### commandmate verify <worktree-id>\n  Run the gates declared in .commandmate/verify.yaml against a worktree.\n\n  Options:\n    --gates <id1,id2>     Gate ids to run (default: work-evidence + all declared)\n    --instance <id>       Attribute the run to an agent instance\n    --timeout <seconds>   Stop polling after N seconds (exit 124)\n    --json                Print the run and its gate results as JSON on stdout\n\n  Exit codes:\n    0   - Every gate passed\n    20  - A gate failed, timed out, or errored\n    21  - work-evidence found nothing to verify (no commits, no changes)\n    99  - The run produced no verdict (bad verify.yaml, gates skipped, cancelled)\n    124 - --timeout elapsed while the run was still going\n\n  Output (progress on stderr, verdict on stdout):\n    GATE work-evidence PASS (commits=3, uncommitted=2)\n    GATE lint PASS (exit=0, 12.3s)\n    GATE unit FAIL (exit=1, 45.0s)\n    RESULT failed\n\n  Gates run in the worktree's own directory. Gates are skipped (run status 99,\n  never 0) in the checkout the server itself runs from when verify.yaml sets\n  options.skipInPrimaryCheckout, so a 'build' gate cannot replace the assets the\n  live app is serving.\n\n### commandmate verify history / commandmate verify show <run-id>\n  Read past verification runs. Both are read-only and never start a run, so\n  neither returns 20 or 21 \u2014 those mean \"this tree failed verification\", and a\n  question about history is not a verdict on the current tree.\n\n  commandmate verify history                          # every worktree, newest 50\n  commandmate verify history --worktree <id>          # one worktree\n  commandmate verify history --days 14 --limit 100    # window and page size\n  commandmate verify history --json                   # JSON array on stdout\n  commandmate verify show 42                          # gates + log tails\n  commandmate verify show 42 --json\n\n  history options:\n    --worktree <id>       Restrict to one worktree (default: all)\n    --days <n>            Look back n days, 1..90 (default: no lower bound)\n    --limit <n>           Maximum runs, 1..500 (default: 50)\n\n  One run per line. The leading #<run-id> is what \"verify show\" takes:\n    #42  2026-07-31T04:12:00.000Z  myrepo-feature-101  manual  failed  failed: unit,build\n\n  The listing carries gate verdicts but NOT gate log bodies \u2014 logTail is absent\n  from the JSON, not null. Use \"verify show <run-id>\" when you need the log.\n\n  Exit codes:\n    0   - Read succeeded (also when nothing matched: stderr note, or [] in JSON)\n    2   - Bad argument (--days/--limit out of range, bad worktree or run id)\n    99  - No such run (404), or an unexpected failure\n\n### commandmate respond <worktree-id> \"<answer>\"\n  Respond to an agent's prompt.\n\n  commandmate respond <id> \"yes\"          # Yes/No\n  commandmate respond <id> \"2\"            # Multiple choice (number)\n  commandmate respond <id> \"custom text\"  # Free text\n  commandmate respond <id> \"yes\" --instance codex-2   # Specific instance\n\n  Exit codes:\n    0  - Response sent\n    99 - Prompt already dismissed (prompt_no_longer_active)\n\n### commandmate capture <worktree-id>\n  Get current terminal output.\n\n  commandmate capture <id>                   # Plain text\n  commandmate capture <id> --json            # JSON with status info\n  commandmate capture <id> --instance codex  # Specific instance\n\n### commandmate auto-yes <worktree-id>\n  Control auto-yes (automatic prompt response).\n\n  commandmate auto-yes <id> --enable                    # Enable (default 1h)\n  commandmate auto-yes <id> --enable --duration 3h      # With duration\n  commandmate auto-yes <id> --enable --stop-pattern \"error\"\n  commandmate auto-yes <id> --disable                   # Disable\n  commandmate auto-yes <id> --enable --instance codex-2 # Scoped to one instance\n\n### commandmate instances <worktree-id> [action] [args]\n  Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).\n\n  commandmate instances <id>                            # List roster + running/auto-yes status\n  commandmate instances <id> --json                     # JSON output\n  commandmate instances <id> add --agent codex          # Add an instance (auto-generates ID, e.g. codex-2)\n  commandmate instances <id> add --agent codex --alias \"Review\" --id codex-3\n  commandmate instances <id> remove <instance-id>       # Remove from roster\n  commandmate instances <id> remove <instance-id> --kill  # Remove and kill its session\n  commandmate instances <id> alias <instance-id> \"New Name\"\n  commandmate instances <id> kill <instance-id>         # Kill only that instance's session\n\n  See \"Multi-Session\" below for the ID convention and roster semantics.\n\n### commandmate skill <subcommand>\n  Manage official Agent Skills. Every subcommand is a thin client over the same\n  APIs the browser UI uses: the CLI never downloads, extracts, writes or deletes\n  anything itself, and never sends a filesystem path, artifact URL, file list or\n  checksum (the API rejects those outright).\n\n  commandmate skill list [--json] [--prerelease]\n  commandmate skill info <skill-id> [--version <v>] [--json]\n  commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]\n  commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>] [--json]\n  commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]\n  commandmate skill status <skill-id> --worktree <id> [--json]\n\n  Confirmation contract (writes = install / uninstall):\n    - A plan is always built and shown first. --dry-run stops there.\n    - Without a TTY, a write REQUIRES --yes. A missing --yes is refused, never\n      assumed: an environment that cannot prompt must not install silently.\n    - A high-risk Skill additionally requires --ack-risk <skill-id>@<version>\n      with the exact id and version. --yes alone never carries a high-risk\n      install, in a TTY or out of one.\n\n  Exit codes:\n    0   success\n    1   the server or the Catalog could not be reached (retryable)\n    2   invalid arguments, unknown Skill or unknown version\n    11  the worktree refused it (local change, conflict, lock, plan drift)\n    12  the write was never confirmed (no --yes, declined, or missing --ack-risk)\n    13  files changed but the operation needs reconciliation\n\n  --json prints the API response body verbatim on stdout; diagnostics, prompts\n  and errors always go to stderr, so a failed --json run leaves stdout empty.\n\n  'skill status' reports one Skill in one worktree, read from the install\n  receipt on disk. There is no per-worktree listing endpoint yet, so <skill-id>\n  is required.\n\n## Multi-Session (1 agent, multiple sessions)\n\n  A worktree can run several sessions of the same CLI tool concurrently. Each\n  session is an \"instance\" identified by an instance ID:\n    <agent>        - the agent's primary instance (e.g. \"claude\")\n    <agent>-<n>    - an additional instance, n >= 2 (e.g. \"claude-2\", \"claude-3\")\n\n  --instance is accepted by send / wait / respond / capture / auto-yes.\n  send --instance auto-starts the session if it is not already running.\n\n  --instance alone is the recommended way to name a target (Issue #1638). It is\n  the only flag all five commands share: --agent is rejected by 'wait'. A\n  rostered instance already carries its CLI tool (Issue #1629), and an instance\n  id that is itself a tool id resolves to that tool's primary instance even\n  without a roster entry, so '--instance codex' needs no --agent.\n\n  --agent remains accepted by send / respond / capture / auto-yes as the\n  supplement for ad-hoc instances the roster does not know -- notably\n  '--register', which cannot infer the tool from an id like codex-3. Passing an\n  --agent that contradicts the roster is an error (exit 2), not an override.\n\n  The roster (visible in the browser UI's Agent panel) is the list of known\n  instances with aliases and display order. Ad-hoc sessions started via\n  'send --instance' do NOT appear in the roster unless registered:\n    commandmate send <id> \"...\" --instance claude-2 --register\n  Without --register, the session still runs and responds to CLI commands,\n  but it will not show up in the UI sidebar/roster until added there or via\n  'commandmate instances <id> add'.\n\n  Per-instance auto-yes: --instance scopes --auto-yes/--duration/--stop-pattern\n  to that specific session, independent of other instances of the same agent.\n\n  commandmate instances <id>                        # discover valid --instance values\n  commandmate send <id> \"task\" --instance codex-2 --auto-yes\n  commandmate wait <id> --instance codex-2 --timeout 600\n  commandmate capture <id> --instance codex-2\n\n## All Exit Codes\n\n  0   SUCCESS          - Completed successfully\n  1   DEPENDENCY_ERROR - Server not running\n  2   CONFIG_ERROR     - Validation error (invalid agent, duration, etc.)\n  10  PROMPT_DETECTED  - Prompt detected during wait\n  20  VERIFY_FAILED    - A verification gate failed (verify, wait --verify)\n  21  NOT_STARTED      - Nothing to verify: no commits, no uncommitted changes\n  99  UNEXPECTED_ERROR - Unexpected error / resource not found / no verdict\n  124 TIMEOUT          - Wait or verification timeout exceeded\n\n  When one 'wait' covers several worktrees, the reported code is the highest\n  priority one observed: 10 > 20 > 21 > 124.\n\n## Troubleshooting\n\n  Server not running:\n    commandmate start --daemon\n    CM_PORT=3011 commandmate ls        # Different port\n\n  Worktree not found:\n    commandmate ls --quiet             # Check registered IDs\n    curl -s -X POST http://localhost:3000/api/repositories/sync  # Sync new worktrees\n\n  Authentication:\n    CM_AUTH_TOKEN=your-token commandmate ls\n";
+export declare const AGENT_OPERATIONS_SAMPLES = "# CLI Agent Operations - Workflow Samples\n\nCopy and adapt these patterns for your use case.\n\n## 1. Basic: send, wait, capture\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101 with TDD\"\n  commandmate wait \"$WT\" --timeout 600\n  commandmate capture \"$WT\"\n\n## 2. With Auto-Yes (unattended execution)\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101\" --auto-yes --duration 3h\n  commandmate wait \"$WT\" --timeout 1800\n  commandmate auto-yes \"$WT\" --disable    # Disable for safety\n  commandmate capture \"$WT\" --json\n\n## 3. Prompt Response Loop\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Refactor this module\"\n\n  while true; do\n    commandmate wait \"$WT\" --timeout 600 --on-prompt agent\n    EXIT_CODE=$?\n\n    if [ $EXIT_CODE -eq 0 ]; then\n      echo \"Done\"\n      break\n    elif [ $EXIT_CODE -eq 10 ]; then\n      commandmate respond \"$WT\" \"yes\"\n    elif [ $EXIT_CODE -eq 124 ]; then\n      echo \"Timeout\"\n      break\n    fi\n  done\n\n  commandmate capture \"$WT\"\n\n## 4. Parallel Worktrees\n\n  WT1=$(commandmate ls --branch feature/101 --quiet)\n  WT2=$(commandmate ls --branch feature/102 --quiet)\n\n  commandmate send \"$WT1\" \"Implement #101\" --auto-yes\n  commandmate send \"$WT2\" \"Implement #102\" --auto-yes --instance codex\n\n  # One --instance covers every worktree id in the call, so worktrees on\n  # different instances need one wait each. Both agents keep running while the\n  # first wait blocks, so this costs no wall clock over a combined wait.\n  # A bare 'wait \"$WT2\"' would watch WT2's DEFAULT agent, not the codex session:\n  # 'wait' has no --agent to correct that with.\n  commandmate wait \"$WT1\" --timeout 1800\n  commandmate wait \"$WT2\" --instance codex --timeout 1800\n\n  commandmate capture \"$WT1\" --json\n  commandmate capture \"$WT2\" --instance codex --json\n\n## 5. Check status before sending\n\n  # Find worktrees and check status\n  commandmate ls --json | python3 -c \"\n  import sys, json\n  for wt in json.load(sys.stdin):\n      if wt['name'].startswith('feature/'):\n          print(f\\\"{wt['id']}  {wt['name']}\\\")\n  \"\n\n## 6. Error handling pattern\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  if [ -z \"$WT\" ]; then\n    echo \"Error: worktree not found\"\n    exit 1\n  fi\n\n  commandmate send \"$WT\" \"Fix the bug\" --auto-yes\n  commandmate wait \"$WT\" --timeout 600\n  EXIT_CODE=$?\n\n  case $EXIT_CODE in\n    0)   echo \"Success\"; commandmate capture \"$WT\" ;;\n    10)  echo \"Prompt detected\"; commandmate respond \"$WT\" \"yes\" ;;\n    124) echo \"Timeout\"; commandmate capture \"$WT\" --json ;;\n    *)   echo \"Error: exit $EXIT_CODE\" ;;\n  esac\n\n## 7. Multi-Session: run a second Codex session alongside the primary agent\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  # Discover the roster before picking an --instance value\n  commandmate instances \"$WT\"\n\n  # Register a second Codex instance, then send/wait/capture scoped to it.\n  # Once it is in the roster, --instance alone carries the CLI tool.\n  commandmate instances \"$WT\" add --agent codex --alias \"Review\"\n  commandmate send \"$WT\" \"Review the diff\" --instance codex-2 --auto-yes\n  commandmate wait \"$WT\" --instance codex-2 --timeout 600\n  commandmate capture \"$WT\" --instance codex-2 --json\n\n  # Ad-hoc instance without pre-registering (still runs; register to show in UI).\n  # --agent is required here: codex-3 is not in the roster yet, so nothing else\n  # says which CLI tool to start.\n  commandmate send \"$WT\" \"Quick check\" --agent codex --instance codex-3 --register\n\n  # Clean up when done\n  commandmate instances \"$WT\" remove codex-2 --kill\n\n## 8. Verify the work instead of trusting \"the agent stopped\"\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101 with TDD\" --auto-yes\n\n  # One call: wait for completion, then run every gate in .commandmate/verify.yaml\n  commandmate wait \"$WT\" --timeout 1800 --verify\n  case $? in\n    0)  echo \"Verified\" ;;\n    10) commandmate respond \"$WT\" \"yes\" ;;\n    20) echo \"A gate failed\"; commandmate verify \"$WT\" --json ;;\n    21) echo \"The agent produced nothing\" ;;\n  esac\n\n  # Cheap pre-check: is there any work at all, before paying for the full suite?\n  commandmate wait \"$WT\" --require-work || echo \"no commits and no changes\"\n\n  # Re-run a subset after a fix, without waiting on the agent\n  commandmate verify \"$WT\" --gates lint,unit\n";
 //# sourceMappingURL=agent-operations.d.ts.map

package/dist/cli/docs/agent-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,yiZAsQlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,igIA0HpC,CAAC"}
+{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,+icA8RlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,klJAmIpC,CAAC"}

package/dist/cli/docs/agent-operations.js

@@ -46,8 +46,11 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   Send a message to an agent (async). Starts session automatically if not running.
 
   Options:
-    --agent <id>           Agent type: claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity
-    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). See "Multi-Session" below.
+    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2, or codex
+                           for the codex primary instance). The recommended way to name a
+                           target: send / wait / respond / capture / auto-yes all take it.
+    --agent <id>           Ad-hoc CLI tool for an instance the roster does not know:
+                           claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity
     --register             Register the --instance session into the agent-instance roster
     --auto-yes             Enable auto-yes before sending
     --duration <d>         Auto-yes duration: 1h, 3h, 8h (default: 1h)
@@ -58,6 +61,13 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
     WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)
     commandmate send "$WT" "Implement this"
 
+  Targeting a non-default agent (Issue #1638): pass --instance, not --agent. Only
+  --instance is accepted by every command -- 'wait --agent' does not exist -- so a
+  workflow that names the agent on 'send' and nothing on 'wait' waits on the wrong
+  session in silence.
+    commandmate send "$WT" "Implement this" --instance codex
+    commandmate wait "$WT" --instance codex
+
 ### commandmate wait <worktree-id...>
   Block until agent completes or prompt is detected.
 
@@ -65,6 +75,7 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
     --timeout <seconds>        Maximum wait time
     --on-prompt <mode>         agent (default) or human
     --stall-timeout <seconds>  Max time without output change
+    --instance <id>            Agent instance to wait on. There is no --agent here.
     --verify                   After completion, run every verification gate
     --require-work             After completion, run only the work-evidence gate
 
@@ -148,6 +159,7 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   commandmate respond <id> "yes"          # Yes/No
   commandmate respond <id> "2"            # Multiple choice (number)
   commandmate respond <id> "custom text"  # Free text
+  commandmate respond <id> "yes" --instance codex-2   # Specific instance
 
   Exit codes:
     0  - Response sent
@@ -156,9 +168,9 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
 ### commandmate capture <worktree-id>
   Get current terminal output.
 
-  commandmate capture <id>                # Plain text
-  commandmate capture <id> --json         # JSON with status info
-  commandmate capture <id> --agent codex  # Specific agent
+  commandmate capture <id>                   # Plain text
+  commandmate capture <id> --json            # JSON with status info
+  commandmate capture <id> --instance codex  # Specific instance
 
 ### commandmate auto-yes <worktree-id>
   Control auto-yes (automatic prompt response).
@@ -167,6 +179,7 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   commandmate auto-yes <id> --enable --duration 3h      # With duration
   commandmate auto-yes <id> --enable --stop-pattern "error"
   commandmate auto-yes <id> --disable                   # Disable
+  commandmate auto-yes <id> --enable --instance codex-2 # Scoped to one instance
 
 ### commandmate instances <worktree-id> [action] [args]
   Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).
@@ -228,6 +241,17 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   --instance is accepted by send / wait / respond / capture / auto-yes.
   send --instance auto-starts the session if it is not already running.
 
+  --instance alone is the recommended way to name a target (Issue #1638). It is
+  the only flag all five commands share: --agent is rejected by 'wait'. A
+  rostered instance already carries its CLI tool (Issue #1629), and an instance
+  id that is itself a tool id resolves to that tool's primary instance even
+  without a roster entry, so '--instance codex' needs no --agent.
+
+  --agent remains accepted by send / respond / capture / auto-yes as the
+  supplement for ad-hoc instances the roster does not know -- notably
+  '--register', which cannot infer the tool from an id like codex-3. Passing an
+  --agent that contradicts the roster is an error (exit 2), not an override.
+
   The roster (visible in the browser UI's Agent panel) is the list of known
   instances with aliases and display order. Ad-hoc sessions started via
   'send --instance' do NOT appear in the roster unless registered:
@@ -240,9 +264,9 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   to that specific session, independent of other instances of the same agent.
 
   commandmate instances <id>                        # discover valid --instance values
-  commandmate send <id> "task" --agent codex --instance codex-2 --auto-yes
+  commandmate send <id> "task" --instance codex-2 --auto-yes
   commandmate wait <id> --instance codex-2 --timeout 600
-  commandmate capture <id> --agent codex --instance codex-2
+  commandmate capture <id> --instance codex-2
 
 ## All Exit Codes
 
@@ -318,12 +342,18 @@ Copy and adapt these patterns for your use case.
   WT2=$(commandmate ls --branch feature/102 --quiet)
 
   commandmate send "$WT1" "Implement #101" --auto-yes
-  commandmate send "$WT2" "Implement #102" --auto-yes --agent codex
+  commandmate send "$WT2" "Implement #102" --auto-yes --instance codex
 
-  commandmate wait "$WT1" "$WT2" --timeout 1800
+  # One --instance covers every worktree id in the call, so worktrees on
+  # different instances need one wait each. Both agents keep running while the
+  # first wait blocks, so this costs no wall clock over a combined wait.
+  # A bare 'wait "$WT2"' would watch WT2's DEFAULT agent, not the codex session:
+  # 'wait' has no --agent to correct that with.
+  commandmate wait "$WT1" --timeout 1800
+  commandmate wait "$WT2" --instance codex --timeout 1800
 
   commandmate capture "$WT1" --json
-  commandmate capture "$WT2" --json
+  commandmate capture "$WT2" --instance codex --json
 
 ## 5. Check status before sending
 
@@ -362,13 +392,16 @@ Copy and adapt these patterns for your use case.
   # Discover the roster before picking an --instance value
   commandmate instances "$WT"
 
-  # Register a second Codex instance, then send/wait/capture scoped to it
+  # Register a second Codex instance, then send/wait/capture scoped to it.
+  # Once it is in the roster, --instance alone carries the CLI tool.
   commandmate instances "$WT" add --agent codex --alias "Review"
-  commandmate send "$WT" "Review the diff" --agent codex --instance codex-2 --auto-yes
+  commandmate send "$WT" "Review the diff" --instance codex-2 --auto-yes
   commandmate wait "$WT" --instance codex-2 --timeout 600
-  commandmate capture "$WT" --agent codex --instance codex-2 --json
+  commandmate capture "$WT" --instance codex-2 --json
 
-  # Ad-hoc instance without pre-registering (still runs; register to show in UI)
+  # Ad-hoc instance without pre-registering (still runs; register to show in UI).
+  # --agent is required here: codex-3 is not in the roster yet, so nothing else
+  # says which CLI tool to start.
   commandmate send "$WT" "Quick check" --agent codex --instance codex-3 --register
 
   # Clean up when done

package/dist/cli/types/index.d.ts

@@ -314,6 +314,22 @@ export interface CaptureOptions {
     token?: string;
     /** Issue #868: agent instance ID or alias (defaults to the agent's primary instance) */
     instance?: string;
+    /**
+     * Issue #1623: read the raw tmux pane instead of the accumulated response.
+     * `capture` without this answers "what is the agent saying right now" and is
+     * empty while idle; `--pane` answers "what is on screen", which is what a
+     * human wants to read.
+     */
+    pane?: boolean;
+    /**
+     * Issue #1623: with `--pane`, keep only the last N lines of the SQUEEZED
+     * transcript. Counting after the squeeze is what makes the number useful — on
+     * a 1000-row canvas whose transcript ends at row 254, tailing the raw frame
+     * would return blank padding.
+     */
+    tail?: string;
+    /** Issue #1623: with `--pane`, print the frame verbatim (no blank-row squeeze). */
+    raw?: boolean;
 }
 /** auto-yes command options [Issue #518] */
 export interface AutoYesOptions {