commandmate 0.15.0 → 0.17.0

package/dist/cli/commands/skill.js

@@ -6,9 +6,10 @@
  *   commandmate skill list [--json]
  *   commandmate skill info <skill-id> [--version <v>] [--json]
  *   commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]
- *   commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>]
+ *   commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>] [--git current|dedicated] [--push] [--pr]
  *   commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]
  *   commandmate skill status <skill-id> --worktree <id> [--json]
+ *   commandmate skill reindex [--json]
  *
  * The CLI never downloads, extracts, writes or deletes anything: it asks the
  * server for a plan, shows it, and presents the token the server issued back to
@@ -137,6 +138,103 @@ async function showStatus(skillId, options) {
         `Removable:    ${plan.removable ? 'yes' : 'no'}`,
     ].join('\n'));
 }
+/**
+ * Rebuild the installed-Skill index from the receipts on disk (Issue #1248).
+ *
+ * Like every other subcommand this is a thin client: the server decides which
+ * worktrees to visit and reads the receipts itself. The CLI supplies no path and
+ * reconstructs nothing, so there is no way for it to index something the API
+ * would have refused.
+ */
+async function reindexSkills(options) {
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const response = await client.post('/api/skills/reindex');
+    const body = (0, api_client_1.assertResponseShape)(response, ['scannedWorktrees', 'indexed', 'removed', 'skipped'], 'POST /api/skills/reindex');
+    if (options.json) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    console.log([
+        `Scanned ${body.scannedWorktrees} worktree(s).`,
+        `Indexed:  ${body.indexed}`,
+        `Removed:  ${body.removed}`,
+        `Skipped:  ${body.skipped.length}`,
+    ].join('\n'));
+    for (const skip of body.skipped) {
+        console.error(`  skipped ${skip.worktreeId}/${skip.root}: ${skip.reason}`);
+    }
+    for (const worktreeId of body.unreadableWorktreeIds) {
+        console.error(`  not scanned (worktree directory missing): ${worktreeId}`);
+    }
+}
+// =============================================================================
+// Git workflow (Issue #1247)
+// =============================================================================
+/** How `--git` maps onto the API's mode. Absent means no Git side effects at all. */
+const GIT_MODES = {
+    current: 'current_branch',
+    dedicated: 'dedicated_branch',
+};
+/**
+ * Read the Git side effects off the flags, or null when none were asked for.
+ *
+ * `--git` has no default: committing to the user's branch is a consequence they
+ * must name, which is the same rule the API enforces (UX-09). `--pr` implies
+ * `--push` because a pull request for an unpushed branch cannot exist.
+ */
+function resolveGitChoice(options) {
+    if (!options.git) {
+        if (options.push || options.pr) {
+            (0, skill_guards_1.refuse)('--push / --pr require --git <current|dedicated>.', types_1.ExitCode.CONFIG_ERROR);
+            return 'invalid';
+        }
+        return null;
+    }
+    const mode = GIT_MODES[options.git];
+    if (!mode) {
+        (0, skill_guards_1.refuse)('--git must be `current` or `dedicated`.', types_1.ExitCode.CONFIG_ERROR);
+        return 'invalid';
+    }
+    const createPullRequest = options.pr === true;
+    return { mode, push: createPullRequest || options.push === true, createPullRequest };
+}
+function gitWorkflowPath(target) {
+    return `/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/git-workflow`;
+}
+/** Fix the branch before the plan exists, so the plan is never stale by construction. */
+async function prepareGitWorkflow(client, target, version, choice) {
+    const response = await client.post(gitWorkflowPath(target), {
+        phase: 'prepare',
+        mode: choice.mode,
+        version,
+        push: choice.push,
+    });
+    return (0, api_client_1.assertResponseShape)(response, ['workflowToken', 'target'], 'POST .../skills/git-workflow (prepare)');
+}
+async function applyGitWorkflow(client, target, workflowToken, choice) {
+    const response = await client.post(gitWorkflowPath(target), {
+        phase: 'apply',
+        workflowToken,
+        push: choice.push,
+        createPullRequest: choice.createPullRequest,
+    });
+    return (0, api_client_1.assertResponseShape)(response, ['result'], 'POST .../skills/git-workflow (apply)');
+}
+function describeGitOutcome(result) {
+    const lines = [
+        result.committed
+            ? `Committed ${result.changedPaths.length} file(s) to ${result.branch} (${result.commitSha.slice(0, 12)})`
+            : `Already committed on ${result.branch} (${result.commitSha.slice(0, 12)})`,
+    ];
+    if (result.pushed)
+        lines.push(`Pushed ${result.branch}`);
+    if (result.pullRequestUrl) {
+        lines.push(result.pullRequestExisted
+            ? `Pull request already open: ${result.pullRequestUrl}`
+            : `Draft pull request: ${result.pullRequestUrl}`);
+    }
+    return lines.join('\n');
+}
 // =============================================================================
 // Write commands
 // =============================================================================
@@ -148,8 +246,11 @@ async function installSkill(skillId, options) {
         (0, skill_guards_1.refuse)('--version <exact> is required for install. Inspect published versions with: commandmate skill info ' + skillId, types_1.ExitCode.CONFIG_ERROR);
         return;
     }
+    const gitChoice = resolveGitChoice(options);
+    if (gitChoice === 'invalid')
+        return;
     const client = new api_client_1.ApiClient({ token: options.token });
-    const plan = await requestInstallPlan(client, target, options);
+    let plan = await requestInstallPlan(client, target, options);
     // --dry-run stops here by construction: the plan is the whole output and no
     // token is ever presented back to the server.
     if (options.dryRun) {
@@ -179,6 +280,19 @@ async function installSkill(skillId, options) {
         (0, skill_guards_1.refuse)('Install declined; nothing was written.', types_1.SkillExitCode.CONFIRMATION_REQUIRED);
         return;
     }
+    // The branch is fixed only once the user has agreed to the install, and the
+    // plan shown above is then discarded: a plan is bound to the branch and HEAD
+    // it was built against, so re-planning is what keeps the checkout from making
+    // SKILL_PLAN_STALE the guaranteed outcome (Issue #1247).
+    let workflowToken = null;
+    if (gitChoice !== null) {
+        const prepared = await prepareGitWorkflow(client, target, plan.skill.version, gitChoice);
+        workflowToken = prepared.workflowToken;
+        console.error(prepared.target.branchCreated
+            ? `Created branch ${prepared.target.branch} from ${prepared.target.baseBranch ?? 'HEAD'}`
+            : `Committing to the current branch ${prepared.target.branch}`);
+        plan = await requestInstallPlan(client, target, { ...options, version: plan.skill.version });
+    }
     const response = await client.post(`/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/install`, {
         planToken: plan.token,
         version: plan.skill.version,
@@ -197,6 +311,10 @@ async function installSkill(skillId, options) {
         console.error(`Warning: the files landed but the operation did not finish cleanly (${body.operation.nextActionKey}). Reconciliation will converge it.`);
         process.exit(types_1.SkillExitCode.COMMITTED_RECONCILING);
     }
+    if (workflowToken !== null && gitChoice !== null) {
+        const git = await applyGitWorkflow(client, target, workflowToken, gitChoice);
+        console.log(describeGitOutcome(git.result));
+    }
 }
 async function uninstallSkill(skillId, options) {
     const target = resolveTarget(skillId, options.worktree);
@@ -302,6 +420,9 @@ function createSkillCommand() {
         .option('--dry-run', 'Build and print the plan, then stop without writing')
         .option('-y, --yes', 'Skip the confirmation prompt (required for non-interactive use)')
         .option('--ack-risk <skill-id@version>', 'Explicitly acknowledge a high-risk Skill. Required in addition to --yes.')
+        .option('--git <mode>', 'Commit the install: `current` (this branch) or `dedicated` (a new Skill branch)')
+        .option('--push', 'Push the commit to origin (requires --git)')
+        .option('--pr', 'Open a draft pull request for the pushed branch (implies --push)')
         .option('--json', 'JSON output (the API response body, verbatim)')
         .option('--prerelease', 'Allow a prerelease --version')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
@@ -345,6 +466,19 @@ function createSkillCommand() {
             (0, skill_guards_1.handleSkillCommandError)(error);
         }
     });
+    skill
+        .command('reindex')
+        .description('Rebuild the installed-Skill index from the receipts on disk')
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (options) => {
+        try {
+            await reindexSkills(options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
     skill.addHelpText('after', `
 Confirmation contract:
   - Writes (install, uninstall) always build a plan first and print it.

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

@@ -0,0 +1,11 @@
+/**
+ * task Command - Inspect execution contracts and their outcomes
+ * Issue #1545 (Phase 2-1)
+ *
+ * `task list` answers "what was this worktree asked to do", `task show` answers
+ * "what did the gates say about it" — the two halves of a contract that used to
+ * exist only inside the message text.
+ */
+import { Command } from 'commander';
+export declare function createTaskCommand(): Command;
+//# sourceMappingURL=task.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/task.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,wBAAgB,iBAAiB,IAAI,OAAO,CAmH3C"}

package/dist/cli/commands/task.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * task Command - Inspect execution contracts and their outcomes
+ * Issue #1545 (Phase 2-1)
+ *
+ * `task list` answers "what was this worktree asked to do", `task show` answers
+ * "what did the gates say about it" — the two halves of a contract that used to
+ * exist only inside the message text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskCommand = createTaskCommand;
+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 MAX_LIST_LIMIT = 100;
+/** crypto.randomUUID() output; mirrors TASK_ID_PATTERN in the API route. */
+const TASK_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function formatTimestamp(value) {
+    return value ?? '-';
+}
+function printTaskLine(task) {
+    const gates = task.contract.verify.gates;
+    console.log([
+        task.id,
+        task.status,
+        task.cliToolId + (task.instanceId ? `/${task.instanceId}` : ''),
+        gates ? gates.join('+') : 'all-gates',
+        task.title,
+    ].join('\t'));
+}
+function createTaskCommand() {
+    const cmd = new commander_1.Command('task');
+    cmd.description('List and inspect execution contracts (tasks)');
+    // ---- task list ----
+    cmd
+        .command('list')
+        .description('List tasks for a worktree, newest first')
+        .argument('<worktree-id>', 'Worktree ID')
+        .option('--limit <n>', `Maximum tasks to list (1..${MAX_LIST_LIMIT})`, parseInt)
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (worktreeId, options) => {
+        try {
+            if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
+                console.error('Error: Invalid worktree ID format.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            if (options.limit !== undefined &&
+                (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > MAX_LIST_LIMIT)) {
+                console.error(`Error: --limit must be an integer 1..${MAX_LIST_LIMIT}.`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            const client = new api_client_1.ApiClient({ token: options.token });
+            const query = options.limit === undefined ? '' : `?limit=${options.limit}`;
+            const response = await client.get(`/api/worktrees/${worktreeId}/tasks${query}`);
+            const { tasks } = (0, api_client_1.assertResponseShape)(response, ['tasks'], 'GET /api/worktrees/:id/tasks');
+            if (options.json) {
+                console.log(JSON.stringify(tasks));
+                return;
+            }
+            if (tasks.length === 0) {
+                console.error(`No tasks recorded for worktree '${worktreeId}'.`);
+                return;
+            }
+            tasks.forEach(printTaskLine);
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    // ---- task show ----
+    cmd
+        .command('show')
+        .description('Show one task with the verification run that last judged it')
+        .argument('<task-id>', 'Task ID')
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (taskId, options) => {
+        try {
+            if (!TASK_ID_PATTERN.test(taskId)) {
+                console.error('Error: Invalid task ID format.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+                return;
+            }
+            const client = new api_client_1.ApiClient({ token: options.token });
+            const response = await client.get(`/api/tasks/${taskId}`);
+            const detail = (0, api_client_1.assertResponseShape)(response, ['task', 'lastVerificationRun'], 'GET /api/tasks/:taskId');
+            if (options.json) {
+                console.log(JSON.stringify(detail));
+                return;
+            }
+            const { task, lastVerificationRun } = detail;
+            console.log(`ID:        ${task.id}`);
+            console.log(`STATUS:    ${task.status}`);
+            console.log(`WORKTREE:  ${task.worktreeId}`);
+            console.log(`AGENT:     ${task.cliToolId}${task.instanceId ? `/${task.instanceId}` : ''}`);
+            console.log(`TITLE:     ${task.title}`);
+            console.log(`CONTRACT:  ${task.contractPath ?? '-'}`);
+            console.log(`SCOPE:     ${task.contract.scope.allow.join(', ') || '-'}`);
+            if (task.contract.scope.deny.length > 0) {
+                console.log(`DENY:      ${task.contract.scope.deny.join(', ')}`);
+            }
+            console.log(`GATES:     ${task.contract.verify.gates?.join(', ') ?? 'all-gates'}`);
+            console.log(`AUTO-YES:  ${task.contract.autoYes.mode ?? 'unset'}`);
+            console.log(`CREATED:   ${task.createdAt}`);
+            console.log(`STARTED:   ${formatTimestamp(task.startedAt)}`);
+            console.log(`FINISHED:  ${formatTimestamp(task.finishedAt)}`);
+            if (!lastVerificationRun) {
+                console.log('VERIFY:    (no verification run yet)');
+                return;
+            }
+            console.log(`VERIFY:    run ${lastVerificationRun.id} ${lastVerificationRun.status}`);
+            for (const gate of lastVerificationRun.gates) {
+                const exit = gate.exitCode === null ? '-' : String(gate.exitCode);
+                console.log(`  GATE ${gate.gateId} ${gate.status} (exit=${exit})`);
+            }
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+import { Command } from 'commander';
+export declare function createVerifyCommand(): Command;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoDpC,wBAAgB,mBAAmB,IAAI,OAAO,CA0D7C"}

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