commandmate 0.19.0 → 0.21.0

package/dist/cli/commands/skill.js

@@ -6,6 +6,8 @@
  *   commandmate skill list [--json]
  *   commandmate skill info <skill-id> [--version <v>] [--json]
  *   commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]
+ *   commandmate skill update-plan <skill-id> --worktree <id> [--version <v>] [--range <r>] [--json]
+ *   commandmate skill update <skill-id> --worktree <id> [--version <v>] [--dry-run] [--yes] [--ack-risk <id>@<version>] [--ack-risk-increase]
  *   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]
@@ -98,6 +100,36 @@ async function planInstall(skillId, options) {
     if (!plan.installable)
         process.exit(types_1.SkillExitCode.BLOCKED);
 }
+/** Ask the server to build an Update Plan. The only inputs are what to move to. */
+async function requestUpdatePlan(client, target, options) {
+    const body = {};
+    if (options.version)
+        body.version = options.version;
+    if (options.prerelease)
+        body.includePrerelease = true;
+    if (options.range)
+        body.range = options.range;
+    const response = await client.post(`/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/update-plan`, body);
+    return (0, api_client_1.assertResponseShape)(response, ['plan'], 'POST .../skills/update-plan').plan;
+}
+/**
+ * Preview updating an installed Skill to a newer exact version (Issue #1243).
+ *
+ * Plan-only by design: the server reads the installed version from the on-disk
+ * receipt, resolves the candidate against the Catalog, verifies the artifact
+ * and reports the version diff, the risk change and every blocker. Applying is
+ * `skill update` (#1244).
+ */
+async function planUpdate(skillId, options) {
+    const target = resolveTarget(skillId, options.worktree);
+    if (!target)
+        return;
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const plan = await requestUpdatePlan(client, target, options);
+    console.log(options.json ? JSON.stringify({ plan }, null, 2) : (0, skill_format_1.formatUpdatePlan)(plan));
+    if (!plan.updatable)
+        process.exit(types_1.SkillExitCode.BLOCKED);
+}
 /**
  * Report whether one Skill is installed in one worktree.
  *
@@ -316,6 +348,83 @@ async function installSkill(skillId, options) {
         console.log(describeGitOutcome(git.result));
     }
 }
+/**
+ * Update an installed Skill to a newer exact version (Issue #1244).
+ *
+ * The same thin-client contract as install: the CLI shows the server-built
+ * plan, collects the confirmations the plan demands, and presents the token
+ * back unchanged. Both risk gates fail closed — a high-risk candidate needs
+ * `--ack-risk <id>@<version>`, and a risk *increase* additionally needs
+ * `--ack-risk-increase` — so `--yes` alone can never carry either.
+ */
+async function updateSkill(skillId, options) {
+    const target = resolveTarget(skillId, options.worktree);
+    if (!target)
+        return;
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const plan = await requestUpdatePlan(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) {
+        console.log(options.json ? JSON.stringify({ plan }, null, 2) : (0, skill_format_1.formatUpdatePlan)(plan));
+        if (!plan.updatable)
+            process.exit(types_1.SkillExitCode.BLOCKED);
+        return;
+    }
+    console.error((0, skill_format_1.formatUpdatePlan)(plan));
+    if (!plan.updatable) {
+        (0, skill_guards_1.refuse)('The update is blocked by the findings listed above; nothing was written.', types_1.SkillExitCode.BLOCKED);
+        return;
+    }
+    // Checked before the generic confirmation so `--yes` alone can never carry a
+    // high-risk update, in a TTY or out of one.
+    if (plan.requiresRiskAcknowledgement &&
+        !(0, skill_guards_1.riskAcknowledgementMatches)(options.ackRisk, plan.skill.id, plan.update.toVersion)) {
+        (0, skill_guards_1.refuse)(`${plan.skill.id} ${plan.update.toVersion} is high risk. Re-run with --ack-risk ${plan.skill.id}@${plan.update.toVersion} to acknowledge it explicitly.`, types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    // The escalation gate is separate from the high-risk gate on purpose: a risk
+    // increase must be named as its own fact, not folded into a flag the caller
+    // may already be passing for other reasons.
+    if (plan.riskIncreased && options.ackRiskIncrease !== true) {
+        (0, skill_guards_1.refuse)(`Updating ${plan.skill.id} to ${plan.update.toVersion} raises its effective risk (${plan.securityDiff.risk.from.effective} -> ${plan.securityDiff.risk.to.effective}). Re-run with --ack-risk-increase to confirm the escalation explicitly.`, types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    const outcome = await (0, skill_guards_1.resolveWriteConfirmation)(`Update ${plan.skill.id} ${plan.update.fromVersion} -> ${plan.update.toVersion} in ${plan.target.worktreeId} (${(0, skill_format_1.formatInstallRoots)(plan.target.installRoots, plan.target.installRoot)})?`, options);
+    if (outcome === 'non_interactive') {
+        (0, skill_guards_1.refuse)('Refusing to update without a confirmation. Pass --yes to update from a non-interactive environment.', types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    if (outcome === 'declined') {
+        (0, skill_guards_1.refuse)('Update declined; nothing was written.', types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    const response = await client.post(`/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/update`, {
+        planToken: plan.token,
+        version: plan.update.toVersion,
+        acknowledgeRisk: plan.requiresRiskAcknowledgement,
+        acknowledgeRiskIncrease: plan.riskIncreased,
+    });
+    const body = (0, api_client_1.assertResponseShape)(response, ['operation', 'update'], 'POST .../skills/update');
+    if (options.json) {
+        console.log(JSON.stringify(body, null, 2));
+    }
+    else {
+        console.log(`Updated ${body.update?.skillId ?? target.skillId} ${body.update?.fromVersion ?? plan.update.fromVersion} -> ${body.update?.toVersion ?? body.update?.version ?? plan.update.toVersion} in ${(0, skill_format_1.formatInstallRoots)(body.update?.installRoots, body.update?.installRoot ?? plan.target.installRoot)}`);
+        for (const agent of body.reload?.agents ?? []) {
+            console.error(`Reload: restart the ${agent.agent} session in this worktree to pick up the new version.`);
+        }
+        if (body.rollback?.available) {
+            console.error(`Rollback: version ${body.rollback.backup.fromVersion} is preserved in verified backup ${body.rollback.backup.backupId} (restore ships separately).`);
+        }
+    }
+    if (body.operation.result === 'committed_reconciling') {
+        // The new payload is on disk; saying "update failed" would contradict what
+        // the user can see. Report it as needing attention instead.
+        console.error(`Warning: the new version landed but the operation did not finish cleanly (${body.operation.nextActionKey}). Reconciliation will converge it.`);
+        process.exit(types_1.SkillExitCode.COMMITTED_RECONCILING);
+    }
+}
 async function uninstallSkill(skillId, options) {
     const target = resolveTarget(skillId, options.worktree);
     if (!target)
@@ -411,6 +520,24 @@ function createSkillCommand() {
             (0, skill_guards_1.handleSkillCommandError)(error);
         }
     });
+    skill
+        .command('update-plan')
+        .description('Preview updating an installed Skill to a newer version. Never writes.')
+        .argument('<skill-id>', 'Installed Skill ID')
+        .option('--worktree <id>', 'Target worktree ID (see: commandmate ls)')
+        .option('--version <version>', 'Exact candidate version (default: the recommended candidate)')
+        .option('--range <range>', 'Only consider candidates satisfying this version range')
+        .option('--json', 'JSON output (the API response body, verbatim)')
+        .option('--prerelease', 'Include prerelease candidates')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (skillId, options) => {
+        try {
+            await planUpdate(skillId, options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
     skill
         .command('install')
         .description('Install a Skill into a worktree, after showing the plan and confirming')
@@ -434,6 +561,28 @@ function createSkillCommand() {
             (0, skill_guards_1.handleSkillCommandError)(error);
         }
     });
+    skill
+        .command('update')
+        .description('Update an installed Skill to a newer version, after showing the plan and confirming')
+        .argument('<skill-id>', 'Installed Skill ID')
+        .option('--worktree <id>', 'Target worktree ID (see: commandmate ls)')
+        .option('--version <version>', 'Exact candidate version (default: the recommended candidate)')
+        .option('--range <range>', 'Only consider candidates satisfying this version range')
+        .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 candidate. Required in addition to --yes.')
+        .option('--ack-risk-increase', 'Explicitly confirm an update that raises the Skill\'s effective risk. Required in addition to --yes.')
+        .option('--json', 'JSON output (the API response body, verbatim)')
+        .option('--prerelease', 'Include prerelease candidates')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (skillId, options) => {
+        try {
+            await updateSkill(skillId, options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
     skill
         .command('uninstall')
         .description('Remove an installed Skill from a worktree, after showing the plan and confirming')

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

@@ -0,0 +1,14 @@
+/**
+ * sync Command - Trigger a server-side worktree re-scan
+ * Issue #1680: worktrees created with `git worktree add` stay invisible to
+ * `commandmate ls` until the GUI sync button is pressed. This command calls the
+ * same endpoint (POST /api/repositories/sync) so worktree creation → dispatch
+ * completes from the CLI alone.
+ */
+import { Command } from 'commander';
+/**
+ * Create the sync command.
+ * [DR1-08] Factory pattern for addCommand() registration.
+ */
+export declare function createSyncCommand(): Command;
+//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAmC3C"}

package/dist/cli/commands/sync.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * sync Command - Trigger a server-side worktree re-scan
+ * Issue #1680: worktrees created with `git worktree add` stay invisible to
+ * `commandmate ls` until the GUI sync button is pressed. This command calls the
+ * same endpoint (POST /api/repositories/sync) so worktree creation → dispatch
+ * completes from the CLI alone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSyncCommand = createSyncCommand;
+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");
+/**
+ * Create the sync command.
+ * [DR1-08] Factory pattern for addCommand() registration.
+ */
+function createSyncCommand() {
+    const cmd = new commander_1.Command('sync');
+    cmd
+        .description('Re-scan repositories and sync worktrees to the server (same as the GUI sync button)')
+        .option('--json', 'JSON output (API response as-is)')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (options) => {
+        try {
+            const client = new api_client_1.ApiClient({ token: options.token });
+            const data = await client.post('/api/repositories/sync');
+            if (options.json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            console.log(data.message);
+            if (data.deletedCount > 0) {
+                console.log(`Removed ${data.deletedCount} stale worktree(s).`);
+            }
+            for (const warning of data.cleanupWarnings ?? []) {
+                console.error(`Warning: ${warning}`);
+            }
+        }
+        catch (error) {
+            // The route's only 400 is "No repositories configured..." — the server's
+            // wording names the fix (WORKTREE_REPOS / CM_ROOT_DIR), so pass it
+            // through instead of the generic "Bad request" mapping.
+            if (error instanceof api_client_1.ApiError && error.statusCode === 400 && error.payload?.error) {
+                console.error(`Error: ${error.payload.error}`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAuBzE;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwP9E"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAmCzE;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwP9E"}

package/dist/cli/commands/update.js

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

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

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

package/dist/cli/commands/wait.js

@@ -21,6 +21,7 @@ const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const verify_runner_1 = require("../utils/verify-runner");
+const agent_target_options_1 = require("../config/agent-target-options");
 /** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
 const POLL_INTERVAL_MS = 5000;
 /**
@@ -270,9 +271,9 @@ function createWaitCommand() {
         .description('Wait for agent completion (1 worktree per CLI instance recommended)')
         .argument('<worktree-ids...>', 'Worktree ID(s) to wait on')
         .option('--timeout <seconds>', 'Maximum wait time in seconds', parseInt)
-        .option('--on-prompt <mode>', 'Prompt handling: agent (default) or human')
+        .option('--on-prompt <mode>', 'Prompt handling: agent (default) exits 10 with a prompt JSON payload on stdout (read it before re-capturing); human keeps waiting for a human reply')
         .option('--stall-timeout <seconds>', 'Maximum time without output change', parseInt)
-        .option('--instance <id>', 'Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). Defaults to the agent\'s primary instance.')
+        .option('--instance <id>', agent_target_options_1.WAIT_INSTANCE_OPTION_DESCRIPTION)
         .option('--verify', 'After completion, run every verification gate; exit 20 when a gate fails, 21 when there is nothing to verify')
         .option('--require-work', 'After completion, run only the work-evidence gate; exit 21 when the worktree has no commits and no uncommitted changes')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)

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

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

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

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

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

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

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

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

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

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