commandmate 0.16.0 → 0.17.0

package/dist/cli/commands/verify.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * verify Command - Run the repository verification gates for a worktree
+ * Issue #1544
+ *
+ * Exit codes:
+ * - 0:   SUCCESS (every gate passed)
+ * - 20:  VERIFY_FAILED (a gate failed, timed out, or errored)
+ * - 21:  NOT_STARTED (work-evidence found nothing to verify)
+ * - 124: TIMEOUT (--timeout elapsed before the run reached a verdict)
+ * Infrastructure errors and verdict-less runs use ExitCode (1, 2, 99).
+ *
+ * Issue #1593 adds two read-only subcommands, `history` and `show`. They never
+ * return 20/21: those codes mean "this working tree failed verification", and a
+ * query about past runs is not a verdict on the current one. A read that
+ * succeeds exits 0 even when it finds nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVerifyCommand = createVerifyCommand;
+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 verify_runner_1 = require("../utils/verify-runner");
+/** Mirrors MAX_RUN_HISTORY_DAYS / MAX_RUN_HISTORY_LIMIT in verification-db.ts. */
+const MAX_HISTORY_DAYS = 90;
+const MAX_HISTORY_LIMIT = 500;
+/** Gate statuses that mean the gate did not pass. `skipped` is not a failure. */
+const FAILED_GATE_STATUSES = new Set(['failed', 'timeout', 'error']);
+function formatSeconds(durationMs) {
+    return durationMs === null ? 'n/a' : `${(durationMs / 1000).toFixed(1)}s`;
+}
+/**
+ * Read a flag that `verify` and its read subcommands both declare.
+ *
+ * Commander binds a flag to whichever command in the chain declared it and
+ * reached it first, so in `verify history --json` the parent's own `--json`
+ * (used by the run mode) swallows the flag before `history` ever sees it.
+ * Falling back to the parent's options is what makes `--json` work where users
+ * actually type it, without changing the root program's option scoping.
+ */
+function inheritedFlag(own, command, key) {
+    if (own !== undefined)
+        return own;
+    return command.parent?.opts()[key];
+}
+/**
+ * One run per line.
+ *
+ * The run id leads the line even though it is not in the requested field list:
+ * without it there is no way to reach `verify show`, which is the only reason
+ * to read this listing in the first place.
+ */
+function formatHistoryLine(run) {
+    const failed = run.gates
+        .filter((gate) => FAILED_GATE_STATUSES.has(gate.status))
+        .map((gate) => gate.gateId);
+    const suffix = failed.length > 0 ? `  failed: ${failed.join(',')}` : '';
+    return `#${run.id}  ${run.startedAt}  ${run.worktreeId}  ${run.trigger}  ${run.status}${suffix}`;
+}
+function createVerifyCommand() {
+    const cmd = new commander_1.Command('verify');
+    cmd
+        .description('Run the verification gates declared in .commandmate/verify.yaml for a worktree')
+        .argument('<worktree-id>', 'Worktree ID to verify')
+        .option('--instance <id>', 'Agent instance ID the run is attributed to (e.g. codex-2)')
+        .option('--gates <ids>', 'Comma-separated gate ids to run (default: work-evidence plus every declared gate)')
+        .option('--json', 'Print the run and its gate results as JSON on stdout')
+        .option('--timeout <seconds>', 'Stop polling after this many seconds (exit 124)', parseInt)
+        .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: ${worktreeId}`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            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);
+                return;
+            }
+            const gateIds = (0, verify_runner_1.parseGateIds)(options.gates);
+            if (gateIds === null) {
+                console.error('Error: --gates must name at least one gate id.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            const client = new api_client_1.ApiClient({ token: options.token });
+            const outcome = await (0, verify_runner_1.runVerification)(client, {
+                worktreeId,
+                trigger: 'manual',
+                instanceId: options.instance,
+                gateIds,
+                timeoutSec: options.timeout,
+                suppressResultLine: options.json,
+            });
+            if (options.json && outcome.run) {
+                console.log(JSON.stringify(outcome.run));
+            }
+            process.exit(outcome.exitCode);
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    addHistoryCommand(cmd);
+    addShowCommand(cmd);
+    return cmd;
+}
+/** `commandmate verify history [--worktree <id>] [--days N] [--limit N] [--json]` */
+function addHistoryCommand(parent) {
+    parent
+        .command('history')
+        .description('List past verification runs, newest first')
+        .option('--worktree <id>', 'Restrict to one worktree (default: every worktree)')
+        .option('--days <days>', `Look back this many days (1..${MAX_HISTORY_DAYS})`, parseInt)
+        .option('--limit <n>', `Maximum runs to list (1..${MAX_HISTORY_LIMIT}, default 50)`, parseInt)
+        .option('--json', 'Print the runs as a JSON array on stdout')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (options, command) => {
+        try {
+            const json = inheritedFlag(options.json, command, 'json');
+            const token = inheritedFlag(options.token, command, 'token');
+            if (options.worktree !== undefined && !(0, api_client_1.isValidWorktreeId)(options.worktree)) {
+                console.error(`Error: Invalid worktree ID format: ${options.worktree}`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            if (options.days !== undefined &&
+                (!Number.isInteger(options.days) || options.days < 1 || options.days > MAX_HISTORY_DAYS)) {
+                console.error(`Error: --days must be an integer between 1 and ${MAX_HISTORY_DAYS}.`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            if (options.limit !== undefined &&
+                (!Number.isInteger(options.limit) ||
+                    options.limit < 1 ||
+                    options.limit > MAX_HISTORY_LIMIT)) {
+                console.error(`Error: --limit must be an integer between 1 and ${MAX_HISTORY_LIMIT}.`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            const query = [];
+            if (options.worktree !== undefined) {
+                query.push(`worktreeId=${encodeURIComponent(options.worktree)}`);
+            }
+            if (options.days !== undefined)
+                query.push(`days=${options.days}`);
+            if (options.limit !== undefined)
+                query.push(`limit=${options.limit}`);
+            const suffix = query.length > 0 ? `?${query.join('&')}` : '';
+            const client = new api_client_1.ApiClient({ token });
+            const data = await client.get(`/api/verification/runs${suffix}`);
+            const runs = data.runs ?? [];
+            if (json) {
+                // Always valid JSON, including the empty case: a consumer piping this
+                // into jq must not have to special-case "no runs".
+                console.log(JSON.stringify(runs, null, 2));
+                return;
+            }
+            if (runs.length === 0) {
+                console.error('No verification runs found.');
+                return;
+            }
+            for (const run of runs) {
+                console.log(formatHistoryLine(run));
+            }
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+}
+/** `commandmate verify show <run-id> [--json]` */
+function addShowCommand(parent) {
+    parent
+        .command('show')
+        .description('Show one verification run with its gate results and log tails')
+        .argument('<run-id>', 'Verification run ID (from `verify history`)')
+        .option('--json', 'Print the run as JSON on stdout')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (runId, options, command) => {
+        try {
+            const json = inheritedFlag(options.json, command, 'json');
+            const token = inheritedFlag(options.token, command, 'token');
+            if (!/^[1-9]\d*$/.test(runId)) {
+                console.error(`Error: Invalid run ID: ${runId}. Expected a positive integer.`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            const client = new api_client_1.ApiClient({ token });
+            let data;
+            try {
+                data = await client.get(`/api/verification/runs/${runId}`);
+            }
+            catch (error) {
+                // The generic 404 message names the worktree id, which this command
+                // never takes. Say what was actually not found.
+                if (error instanceof api_client_1.ApiError && error.statusCode === 404) {
+                    console.error(`Verification run ${runId} not found.`);
+                    process.exit(error.exitCode);
+                    return;
+                }
+                throw error;
+            }
+            const run = data.run;
+            if (json) {
+                console.log(JSON.stringify(run, null, 2));
+                return;
+            }
+            console.log(`run #${run.id}  ${run.status}  worktree=${run.worktreeId}  trigger=${run.trigger}`);
+            console.log(`started=${run.startedAt}  finished=${run.finishedAt ?? '-'}`);
+            console.log(`baseRef=${run.baseRef ?? '-'}  instance=${run.instanceId ?? '-'}  task=${run.taskId ?? '-'}`);
+            for (const gate of run.gates) {
+                const exit = gate.exitCode === null ? 'n/a' : String(gate.exitCode);
+                console.log(`  ${gate.gateId}  ${gate.status}  exit=${exit}  ${formatSeconds(gate.durationMs)}`);
+                if (gate.logTail) {
+                    for (const line of gate.logTail.split('\n')) {
+                        console.log(`    | ${line}`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+}

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

@@ -6,6 +6,8 @@
  * - 0: SUCCESS (agent completed)
  * - 10: PROMPT_DETECTED (agent waiting for user input)
  * - 124: TIMEOUT (--timeout exceeded)
+ * Issue #1544 adds --verify / --require-work, which can turn a detected
+ * completion into 20 (VERIFY_FAILED) or 21 (NOT_STARTED).
  * 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;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuGpC,wBAAgB,iBAAiB,IAAI,OAAO,CA4E3C"}
+{"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;AAkKpC,wBAAgB,iBAAiB,IAAI,OAAO,CA6F3C"}

package/dist/cli/commands/wait.js

@@ -7,6 +7,8 @@
  * - 0: SUCCESS (agent completed)
  * - 10: PROMPT_DETECTED (agent waiting for user input)
  * - 124: TIMEOUT (--timeout exceeded)
+ * Issue #1544 adds --verify / --require-work, which can turn a detected
+ * completion into 20 (VERIFY_FAILED) or 21 (NOT_STARTED).
  * Infrastructure errors use ExitCode (1, 2, 99)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -15,6 +17,7 @@ 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 verify_runner_1 = require("../utils/verify-runner");
 /** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
 const POLL_INTERVAL_MS = 5000;
 /**
@@ -95,6 +98,57 @@ async function pollWorktree(client, worktreeId, options) {
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/** True when the caller asked for a verdict rather than "the agent stopped". */
+function verifyRequested(options) {
+    return Boolean(options.verify || options.requireWork);
+}
+/**
+ * Run verification for one worktree after its completion was detected.
+ *
+ * Swallows ApiError into an exit code: with several worktrees in flight, one
+ * unreachable run must not abort the verdicts of the others.
+ */
+async function verifyAfterWait(client, worktreeId, options) {
+    // --verify runs every gate, and work-evidence is always part of "every gate",
+    // so combining it with --require-work is a superset rather than a conflict.
+    const gateIds = options.verify ? undefined : [verify_runner_1.WORK_EVIDENCE_GATE_ID];
+    try {
+        const outcome = await (0, verify_runner_1.runVerification)(client, {
+            worktreeId,
+            trigger: 'wait',
+            instanceId: options.instance,
+            gateIds,
+            // stdout stays reserved for the prompt JSON contract.
+            resultStream: 'stderr',
+        });
+        return outcome.exitCode;
+    }
+    catch (error) {
+        if (error instanceof api_client_1.ApiError) {
+            console.error(`Error: ${error.message}`);
+            return error.exitCode;
+        }
+        console.error(`Error: verification of ${worktreeId} failed: ${error instanceof Error ? error.message : String(error)}`);
+        return types_1.ExitCode.UNEXPECTED_ERROR;
+    }
+}
+/**
+ * Fold one worktree's exit code into the aggregate.
+ *
+ * Ranked codes (see WAIT_EXIT_CODE_PRIORITY) beat unranked infrastructure
+ * codes, and among equals the first one observed stands.
+ */
+function mergeExitCode(current, candidate) {
+    if (candidate === types_1.WaitExitCode.SUCCESS)
+        return current;
+    if (current === types_1.WaitExitCode.SUCCESS)
+        return candidate;
+    const rank = (code) => {
+        const index = types_1.WAIT_EXIT_CODE_PRIORITY.indexOf(code);
+        return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+    };
+    return rank(candidate) < rank(current) ? candidate : current;
+}
 function createWaitCommand() {
     const cmd = new commander_1.Command('wait');
     cmd
@@ -104,6 +158,8 @@ function createWaitCommand() {
         .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('--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)
         .action(async (worktreeIds, options) => {
         try {
@@ -112,12 +168,14 @@ function createWaitCommand() {
                 if (!(0, api_client_1.isValidWorktreeId)(id)) {
                     console.error(`Error: Invalid worktree ID format: ${id}`);
                     process.exit(types_1.ExitCode.CONFIG_ERROR);
+                    return;
                 }
             }
             // Issue #868: Validate instance ID if provided
             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);
+                return;
             }
             const client = new api_client_1.ApiClient({ token: options.token });
             if (worktreeIds.length === 1) {
@@ -127,34 +185,41 @@ function createWaitCommand() {
                     // stdout for result (JSON output)
                     console.log(JSON.stringify(result.output));
                 }
-                process.exit(result.exitCode);
+                // 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)
+                    : result.exitCode;
+                process.exit(exitCode);
+                return;
             }
             // [DR1-07] Multiple worktrees: Promise.allSettled for error isolation
             const results = await Promise.allSettled(worktreeIds.map(id => pollWorktree(client, id, options)));
             // Collect results
             const outputs = [];
             let finalExitCode = types_1.WaitExitCode.SUCCESS;
-            for (const result of results) {
+            const verifyTargets = [];
+            results.forEach((result, index) => {
                 if (result.status === 'fulfilled') {
                     if (result.value.output) {
                         outputs.push(result.value.output);
                     }
-                    if (result.value.exitCode === types_1.WaitExitCode.PROMPT_DETECTED) {
-                        finalExitCode = types_1.WaitExitCode.PROMPT_DETECTED;
-                    }
-                    else if (result.value.exitCode !== types_1.WaitExitCode.SUCCESS && finalExitCode === types_1.WaitExitCode.SUCCESS) {
-                        finalExitCode = result.value.exitCode;
+                    if (result.value.exitCode === types_1.WaitExitCode.SUCCESS && verifyRequested(options)) {
+                        verifyTargets.push(worktreeIds[index]);
+                        return;
                     }
+                    finalExitCode = mergeExitCode(finalExitCode, result.value.exitCode);
                 }
                 else {
                     const err = result.reason;
-                    if (err instanceof api_client_1.ApiError && finalExitCode === types_1.WaitExitCode.SUCCESS) {
-                        finalExitCode = err.exitCode;
-                    }
-                    else if (finalExitCode === types_1.WaitExitCode.SUCCESS) {
-                        finalExitCode = types_1.ExitCode.UNEXPECTED_ERROR;
-                    }
+                    finalExitCode = mergeExitCode(finalExitCode, err instanceof api_client_1.ApiError ? err.exitCode : types_1.ExitCode.UNEXPECTED_ERROR);
                 }
+            });
+            // Issue #1544: serial on purpose. The server caps concurrent runs
+            // process-wide, so firing them together only queues them behind each
+            // other while every gate competes for the same machine.
+            for (const id of verifyTargets) {
+                finalExitCode = mergeExitCode(finalExitCode, await verifyAfterWait(client, id, options));
             }
             if (outputs.length > 0) {
                 console.log(JSON.stringify(outputs));

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\n  Exit codes:\n    0   - Completed (agent idle/ready)\n    10  - Prompt detected (--on-prompt agent mode)\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### 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  99  UNEXPECTED_ERROR - Unexpected error / resource not found\n  124 TIMEOUT          - Wait timeout exceeded\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";
+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";
 //# 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,u9RAiMlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,osGAsGpC,CAAC"}
+{"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"}

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

@@ -65,10 +65,14 @@ 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
+    --verify                   After completion, run every verification gate
+    --require-work             After completion, run only the work-evidence gate
 
   Exit codes:
-    0   - Completed (agent idle/ready)
+    0   - Completed (agent idle/ready), and verified when --verify was given
     10  - Prompt detected (--on-prompt agent mode)
+    20  - A verification gate failed (--verify)
+    21  - Nothing to verify: no commits, no uncommitted changes
     124 - Timeout exceeded
 
   --on-prompt modes:
@@ -78,6 +82,66 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   Prompt JSON output (exit 10):
     {"worktreeId":"...","cliToolId":"claude","type":"yes_no","question":"...","options":["yes","no"],"status":"pending"}
 
+  --verify turns "the agent stopped" into "the work passes the repository's own
+  checks". Verification only runs when completion was detected: a prompt (10) or
+  a timeout (124) is reported as-is and never verified. With several worktrees,
+  gates run one worktree at a time because the server caps concurrent runs.
+
+### commandmate verify <worktree-id>
+  Run the gates declared in .commandmate/verify.yaml against a worktree.
+
+  Options:
+    --gates <id1,id2>     Gate ids to run (default: work-evidence + all declared)
+    --instance <id>       Attribute the run to an agent instance
+    --timeout <seconds>   Stop polling after N seconds (exit 124)
+    --json                Print the run and its gate results as JSON on stdout
+
+  Exit codes:
+    0   - Every gate passed
+    20  - A gate failed, timed out, or errored
+    21  - work-evidence found nothing to verify (no commits, no changes)
+    99  - The run produced no verdict (bad verify.yaml, gates skipped, cancelled)
+    124 - --timeout elapsed while the run was still going
+
+  Output (progress on stderr, verdict on stdout):
+    GATE work-evidence PASS (commits=3, uncommitted=2)
+    GATE lint PASS (exit=0, 12.3s)
+    GATE unit FAIL (exit=1, 45.0s)
+    RESULT failed
+
+  Gates run in the worktree's own directory. Gates are skipped (run status 99,
+  never 0) in the checkout the server itself runs from when verify.yaml sets
+  options.skipInPrimaryCheckout, so a 'build' gate cannot replace the assets the
+  live app is serving.
+
+### commandmate verify history / commandmate verify show <run-id>
+  Read past verification runs. Both are read-only and never start a run, so
+  neither returns 20 or 21 — those mean "this tree failed verification", and a
+  question about history is not a verdict on the current tree.
+
+  commandmate verify history                          # every worktree, newest 50
+  commandmate verify history --worktree <id>          # one worktree
+  commandmate verify history --days 14 --limit 100    # window and page size
+  commandmate verify history --json                   # JSON array on stdout
+  commandmate verify show 42                          # gates + log tails
+  commandmate verify show 42 --json
+
+  history options:
+    --worktree <id>       Restrict to one worktree (default: all)
+    --days <n>            Look back n days, 1..90 (default: no lower bound)
+    --limit <n>           Maximum runs, 1..500 (default: 50)
+
+  One run per line. The leading #<run-id> is what "verify show" takes:
+    #42  2026-07-31T04:12:00.000Z  myrepo-feature-101  manual  failed  failed: unit,build
+
+  The listing carries gate verdicts but NOT gate log bodies — logTail is absent
+  from the JSON, not null. Use "verify show <run-id>" when you need the log.
+
+  Exit codes:
+    0   - Read succeeded (also when nothing matched: stderr note, or [] in JSON)
+    2   - Bad argument (--days/--limit out of range, bad worktree or run id)
+    99  - No such run (404), or an unexpected failure
+
 ### commandmate respond <worktree-id> "<answer>"
   Respond to an agent's prompt.
 
@@ -186,8 +250,13 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   1   DEPENDENCY_ERROR - Server not running
   2   CONFIG_ERROR     - Validation error (invalid agent, duration, etc.)
   10  PROMPT_DETECTED  - Prompt detected during wait
-  99  UNEXPECTED_ERROR - Unexpected error / resource not found
-  124 TIMEOUT          - Wait timeout exceeded
+  20  VERIFY_FAILED    - A verification gate failed (verify, wait --verify)
+  21  NOT_STARTED      - Nothing to verify: no commits, no uncommitted changes
+  99  UNEXPECTED_ERROR - Unexpected error / resource not found / no verdict
+  124 TIMEOUT          - Wait or verification timeout exceeded
+
+  When one 'wait' covers several worktrees, the reported code is the highest
+  priority one observed: 10 > 20 > 21 > 124.
 
 ## Troubleshooting
 
@@ -304,4 +373,24 @@ Copy and adapt these patterns for your use case.
 
   # Clean up when done
   commandmate instances "$WT" remove codex-2 --kill
+
+## 8. Verify the work instead of trusting "the agent stopped"
+
+  WT=$(commandmate ls --branch feature/101 --quiet)
+  commandmate send "$WT" "Implement Issue #101 with TDD" --auto-yes
+
+  # One call: wait for completion, then run every gate in .commandmate/verify.yaml
+  commandmate wait "$WT" --timeout 1800 --verify
+  case $? in
+    0)  echo "Verified" ;;
+    10) commandmate respond "$WT" "yes" ;;
+    20) echo "A gate failed"; commandmate verify "$WT" --json ;;
+    21) echo "The agent produced nothing" ;;
+  esac
+
+  # Cheap pre-check: is there any work at all, before paying for the full suite?
+  commandmate wait "$WT" --require-work || echo "no commits and no changes"
+
+  # Re-run a subset after a fix, without waiting on the agent
+  commandmate verify "$WT" --gates lint,unit
 `;

package/dist/cli/program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AA4D5C;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CA4KtC"}
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AA8D5C;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAkLtC"}

package/dist/cli/program.js

@@ -22,6 +22,8 @@ const wait_1 = require("./commands/wait");
 const respond_1 = require("./commands/respond");
 const capture_1 = require("./commands/capture");
 const auto_yes_1 = require("./commands/auto-yes");
+const verify_1 = require("./commands/verify");
+const task_1 = require("./commands/task");
 // Issue #636: Report command
 const report_1 = require("./commands/report");
 // Issue #1000: Agent-instance roster management (discover/add/remove/alias/kill)
@@ -204,6 +206,10 @@ function buildProgram() {
     program.addCommand((0, respond_1.createRespondCommand)());
     program.addCommand((0, capture_1.createCaptureCommand)());
     program.addCommand((0, auto_yes_1.createAutoYesCommand)());
+    // Issue #1544: verification gates (.commandmate/verify.yaml)
+    program.addCommand((0, verify_1.createVerifyCommand)());
+    // Issue #1545: execution contracts (.commandmate/tasks/<name>.yaml)
+    program.addCommand((0, task_1.createTaskCommand)());
     // Issue #636: Report command
     program.addCommand((0, report_1.createReportCommand)());
     // Issue #1000: Agent-instance roster management