commandmate 0.15.0 → 0.17.0

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

package/dist/cli/types/api-responses.d.ts

@@ -112,6 +112,41 @@ export interface SerializedReport {
     createdAt: string;
     updatedAt: string;
 }
+export interface VibeMetrics {
+    periodDays: number;
+    tasks: {
+        total: number;
+        succeeded: number;
+        failed: number;
+        notStarted: number;
+        cancelled: number;
+        /** 0..1 fraction; null when no tasks were created in the window. */
+        successRate: number | null;
+        /** null when nothing failed in the window. */
+        avgRetryLoops: number | null;
+    };
+    verification: {
+        runs: number;
+        passed: number;
+        failed: number;
+        notStarted: number;
+        /** 0..1 fraction; null when no runs started in the window. */
+        passRate: number | null;
+        gateFailBreakdown: Array<{
+            gateId: string;
+            failCount: number;
+        }>;
+    };
+    intervention: {
+        humanResponds: number;
+        autoAnswered: number;
+        /** Always null in v1: the policy suppression log is not persisted. */
+        suppressedByPolicy: number | null;
+    };
+}
+export interface VibeMetricsResponse {
+    metrics: VibeMetrics;
+}
 export interface TemplateResponse {
     id: string;
     name: string;
@@ -290,6 +325,31 @@ export interface SkillInstallResponse {
         }>;
     } | null;
 }
+/** Mirrors: api/worktrees/[id]/skills/[skillId]/git-workflow prepare response (Issue #1247). */
+export interface SkillGitWorkflowPrepareResponse {
+    workflowToken: string;
+    target: {
+        mode: string;
+        branch: string;
+        baseBranch: string | null;
+        headCommit: string;
+        branchCreated: boolean;
+        remote: string;
+    };
+}
+/** Mirrors: api/worktrees/[id]/skills/[skillId]/git-workflow apply response (Issue #1247). */
+export interface SkillGitWorkflowApplyResponse {
+    result: {
+        branch: string;
+        baseBranch: string | null;
+        changedPaths: string[];
+        committed: boolean;
+        commitSha: string;
+        pushed: boolean;
+        pullRequestUrl: string | null;
+        pullRequestExisted: boolean;
+    };
+}
 /** Mirrors: src/lib/skills/uninstall-plan.ts SkillUninstallPlanDto (subset). */
 export interface SkillUninstallPlan {
     token: string;
@@ -346,4 +406,154 @@ export interface SkillUninstallResponse {
         fullyRemoved?: boolean;
     } | null;
 }
+/** Mirrors: src/app/api/skills/reindex/route.ts POST response [Issue #1248]. */
+export interface SkillReindexResult {
+    scannedWorktrees: number;
+    indexed: number;
+    removed: number;
+    skipped: Array<{
+        worktreeId: string;
+        skillId: string;
+        /** Repository-relative root the directory was found at. */
+        root: string;
+        reason: string;
+    }>;
+    /** Registered worktrees whose directory is gone; their rows were left untouched. */
+    unreadableWorktreeIds: string[];
+}
+/** Mirrors: src/app/api/worktrees/[id]/verify/route.ts POST 202 response. */
+export interface VerifyStartResponse {
+    runId: number;
+}
+/**
+ * Mirrors: src/lib/db/verification-db.ts VerificationRunStatus.
+ * Declared here rather than imported so the CLI bundle stays free of the
+ * server's better-sqlite3 dependency graph.
+ */
+export type VerificationRunStatus = 'running' | 'passed' | 'failed' | 'not_started' | 'error' | 'cancelled';
+/** Mirrors: src/lib/db/verification-db.ts VerificationGateStatus. */
+export type VerificationGateStatus = 'running' | 'passed' | 'failed' | 'timeout' | 'skipped' | 'error';
+/**
+ * Mirrors: src/lib/db/verification-db.ts VerificationGateResult.
+ * Dates arrive as ISO strings because the route serializes them through JSON.
+ */
+export interface VerificationGateResultView {
+    id: number;
+    runId: number;
+    gateId: string;
+    command: string;
+    status: VerificationGateStatus;
+    exitCode: number | null;
+    durationMs: number | null;
+    logTail: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+}
+/** Mirrors: src/lib/db/verification-db.ts VerificationRunWithGates. */
+export interface VerificationRunView {
+    id: number;
+    worktreeId: string;
+    instanceId: string | null;
+    taskId: string | null;
+    trigger: string;
+    status: VerificationRunStatus;
+    baseRef: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    gates: VerificationGateResultView[];
+}
+/** Mirrors: src/app/api/worktrees/[id]/verify/runs/[runId]/route.ts GET response. */
+export interface VerifyRunResponse {
+    run: VerificationRunView;
+}
+/**
+ * Mirrors: src/lib/db/verification-db.ts VerificationGateSummary (Issue #1593).
+ * No `logTail` — the history listing does not carry log bodies, and declaring
+ * one here would let `history` code read a field the server never sends.
+ */
+export interface VerificationGateSummaryView {
+    gateId: string;
+    status: VerificationGateStatus;
+    exitCode: number | null;
+    durationMs: number | null;
+}
+/** Mirrors: src/lib/db/verification-db.ts VerificationRunWithGateSummaries. */
+export interface VerificationRunSummaryView {
+    id: number;
+    worktreeId: string;
+    instanceId: string | null;
+    taskId: string | null;
+    trigger: string;
+    status: VerificationRunStatus;
+    baseRef: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    gates: VerificationGateSummaryView[];
+}
+/** Mirrors: src/app/api/verification/runs/route.ts GET response. */
+export interface VerificationRunHistoryResponse {
+    runs: VerificationRunSummaryView[];
+}
+/** Mirrors: src/lib/db/tasks-db.ts TaskStatus. */
+export type TaskStatus = 'pending' | 'running' | 'waiting_input' | 'verifying' | 'succeeded' | 'failed' | 'not_started' | 'cancelled';
+/**
+ * Mirrors: src/lib/tasks/contract-parser.ts TaskContract.
+ * The snapshot taken at send time, as stored in `tasks.contract_json`.
+ */
+export interface TaskContractView {
+    version: number;
+    title: string;
+    goal: string;
+    scope: {
+        allow: string[];
+        deny: string[];
+    };
+    verify: {
+        gates: string[] | null;
+    };
+    autoYes: {
+        mode: string | null;
+        allowPromptTypes: string[];
+        denyPatterns: string[];
+    };
+    success: {
+        requireWorkEvidence: boolean;
+        requireScopeClean: boolean;
+    };
+}
+/**
+ * Mirrors: src/lib/db/tasks-db.ts Task.
+ * Dates arrive as ISO strings because the route serializes them through JSON.
+ */
+export interface TaskView {
+    id: string;
+    worktreeId: string;
+    cliToolId: string;
+    instanceId: string | null;
+    title: string;
+    goal: string;
+    contractPath: string | null;
+    contract: TaskContractView;
+    status: TaskStatus;
+    lastVerificationRunId: number | null;
+    createdAt: string;
+    updatedAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+/** Mirrors: src/app/api/worktrees/[id]/tasks/route.ts POST response. */
+export interface TaskCreateResponse {
+    task: TaskView;
+    /** Contract preamble + goal, composed server-side; this is what gets sent. */
+    message: string;
+}
+/** Mirrors: src/app/api/worktrees/[id]/tasks/route.ts GET response. */
+export interface TaskListResponse {
+    tasks: TaskView[];
+}
+/** Mirrors: src/app/api/tasks/[taskId]/route.ts GET response. */
+export interface TaskDetailResponse {
+    task: TaskView;
+    lastVerificationRun: VerificationRunView | null;
+}
 //# sourceMappingURL=api-responses.d.ts.map