commandmate 0.19.0 → 0.20.0

package/.next/types/routes.d.ts

@@ -4,7 +4,7 @@
 type AppRoutes = "/" | "/chat" | "/login" | "/more" | "/offline" | "/repositories" | "/review" | "/sessions" | "/skills" | "/skills/[skillId]" | "/skills/installed" | "/worktrees/[id]" | "/worktrees/[id]/files/[...path]" | "/worktrees/[id]/terminal"
 type AppRouteHandlerRoutes = "/api/app/update" | "/api/app/update-check" | "/api/assistant/conversation" | "/api/assistant/current-output" | "/api/assistant/messages" | "/api/assistant/session" | "/api/assistant/start" | "/api/assistant/terminal" | "/api/assistant/tools" | "/api/auth/login" | "/api/auth/logout" | "/api/auth/status" | "/api/daily-summary" | "/api/daily-summary/status" | "/api/external-apps" | "/api/external-apps/[id]" | "/api/external-apps/[id]/health" | "/api/fs/browse" | "/api/fs/recent-paths" | "/api/hooks/agent-event" | "/api/hooks/claude-done" | "/api/metrics/vibe" | "/api/ollama/models" | "/api/push/subscriptions" | "/api/push/vapid" | "/api/repositories" | "/api/repositories/[id]" | "/api/repositories/[id]/todos" | "/api/repositories/[id]/todos/[todoId]" | "/api/repositories/clone" | "/api/repositories/clone/[jobId]" | "/api/repositories/excluded" | "/api/repositories/restore" | "/api/repositories/scan" | "/api/repositories/sync" | "/api/repositories/validate-path" | "/api/sidebar/group-order" | "/api/skills" | "/api/skills/[id]" | "/api/skills/installations" | "/api/skills/operations" | "/api/skills/reindex" | "/api/slash-commands" | "/api/tasks/[taskId]" | "/api/tasks/[taskId]/cancel" | "/api/templates" | "/api/templates/[id]" | "/api/todos" | "/api/verification/runs" | "/api/verification/runs/[runId]" | "/api/worktrees" | "/api/worktrees/[id]" | "/api/worktrees/[id]/auto-yes" | "/api/worktrees/[id]/capture" | "/api/worktrees/[id]/cli-tool" | "/api/worktrees/[id]/cmate/schedules" | "/api/worktrees/[id]/current-output" | "/api/worktrees/[id]/execution-logs" | "/api/worktrees/[id]/execution-logs/[logId]" | "/api/worktrees/[id]/files/[...path]" | "/api/worktrees/[id]/git/branch/create" | "/api/worktrees/[id]/git/branch/delete" | "/api/worktrees/[id]/git/branches" | "/api/worktrees/[id]/git/checkout" | "/api/worktrees/[id]/git/commit" | "/api/worktrees/[id]/git/diff" | "/api/worktrees/[id]/git/fetch" | "/api/worktrees/[id]/git/log" | "/api/worktrees/[id]/git/pull" | "/api/worktrees/[id]/git/push" | "/api/worktrees/[id]/git/reset" | "/api/worktrees/[id]/git/revert" | "/api/worktrees/[id]/git/show/[commitHash]" | "/api/worktrees/[id]/git/stage" | "/api/worktrees/[id]/git/staged" | "/api/worktrees/[id]/git/stash" | "/api/worktrees/[id]/git/stash/[index]" | "/api/worktrees/[id]/git/stash/apply" | "/api/worktrees/[id]/git/stash/pop" | "/api/worktrees/[id]/git/stash/push" | "/api/worktrees/[id]/git/status" | "/api/worktrees/[id]/git/unstage" | "/api/worktrees/[id]/git/working-diff" | "/api/worktrees/[id]/interrupt" | "/api/worktrees/[id]/kill-session" | "/api/worktrees/[id]/logs" | "/api/worktrees/[id]/logs/[filename]" | "/api/worktrees/[id]/marp-render" | "/api/worktrees/[id]/memos" | "/api/worktrees/[id]/memos/[memoId]" | "/api/worktrees/[id]/messages" | "/api/worktrees/[id]/prompt-response" | "/api/worktrees/[id]/respond" | "/api/worktrees/[id]/schedules" | "/api/worktrees/[id]/schedules/[scheduleId]" | "/api/worktrees/[id]/schedules/active" | "/api/worktrees/[id]/search" | "/api/worktrees/[id]/send" | "/api/worktrees/[id]/skills" | "/api/worktrees/[id]/skills/[skillId]/git-workflow" | "/api/worktrees/[id]/skills/[skillId]/install" | "/api/worktrees/[id]/skills/[skillId]/plan" | "/api/worktrees/[id]/skills/[skillId]/uninstall" | "/api/worktrees/[id]/skills/[skillId]/uninstall-plan" | "/api/worktrees/[id]/slash-commands" | "/api/worktrees/[id]/special-keys" | "/api/worktrees/[id]/start-polling" | "/api/worktrees/[id]/tasks" | "/api/worktrees/[id]/terminal" | "/api/worktrees/[id]/timers" | "/api/worktrees/[id]/timers/history" | "/api/worktrees/[id]/todos" | "/api/worktrees/[id]/todos/[todoId]" | "/api/worktrees/[id]/tree" | "/api/worktrees/[id]/tree/[...path]" | "/api/worktrees/[id]/upload/[...path]" | "/api/worktrees/[id]/verify" | "/api/worktrees/[id]/verify/runs" | "/api/worktrees/[id]/verify/runs/[runId]" | "/api/worktrees/[id]/viewed" | "/proxy/[...path]"
 type PageRoutes = never
-type LayoutRoutes = "/"
+type LayoutRoutes = "/" | "/worktrees/[id]"
 type RedirectRoutes = never
 type RewriteRoutes = never
 type Routes = AppRoutes | PageRoutes | LayoutRoutes | RedirectRoutes | RewriteRoutes | AppRouteHandlerRoutes
@@ -153,6 +153,7 @@ export type ParamsOf<Route extends Routes> = ParamMap[Route]
 
 interface LayoutSlotMap {
   "/": never
+  "/worktrees/[id]": never
 }
 
 

package/.next/types/validator.ts

@@ -1274,3 +1274,12 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   // @ts-ignore
   type __Unused = __Check
 }
+
+// Validate ../../src/app/worktrees/[id]/layout.tsx
+{
+  type __IsExpected<Specific extends LayoutConfig<"/worktrees/[id]">> = Specific
+  const handler = {} as typeof import("../../src/app/worktrees/[id]/layout.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}

package/README.md

@@ -204,8 +204,9 @@ Operate agent sessions from the CLI. See the [CLI Operations Guide](./docs/en/us
 | `commandmate ls --id <prefix>` | Filter by worktree ID prefix |
 | `commandmate send <id> "message"` | Send a message to an agent |
 | `commandmate send <id> "msg" --auto-yes` | Send with auto-yes enabled |
-| `commandmate send <id> "msg" --agent codex` | Send to a specific agent |
+| `commandmate send <id> "msg" --instance codex` | Send to a specific agent instance |
 | `commandmate wait <id> --timeout 300` | Wait for agent completion (exit 0) or prompt (exit 10) |
+| `commandmate wait <id> --instance codex` | Wait on a specific agent instance |
 | `commandmate wait <id> --on-prompt human` | Wait, let human respond to prompts via browser UI |
 | `commandmate respond <id> "yes"` | Respond to an agent's prompt |
 | `commandmate capture <id>` | Get current terminal output |
@@ -213,6 +214,14 @@ Operate agent sessions from the CLI. See the [CLI Operations Guide](./docs/en/us
 | `commandmate auto-yes <id> --enable` | Enable auto-yes (default 1h) |
 | `commandmate auto-yes <id> --disable` | Disable auto-yes |
 
+> **Name the target with `--instance`, on every command.** It is the only target
+> flag `wait` accepts — `wait --agent` fails with `unknown option`. Naming the
+> agent only on `send` leaves `wait` watching the worktree's *default* agent, so
+> a worktree cut for Codex silently waits for Claude Code. `--agent` still works
+> on `send`/`respond`/`capture`/`auto-yes` as the supplement for instances the
+> roster does not know (it is what `--register` needs). See the
+> [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md).
+
 **Typical workflow:**
 
 ```bash

package/dist/cli/commands/auto-yes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-yes.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/auto-yes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,oBAAoB,IAAI,OAAO,CAoG9C"}
+{"version":3,"file":"auto-yes.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/auto-yes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,oBAAoB,IAAI,OAAO,CAoG9C"}

package/dist/cli/commands/auto-yes.js

@@ -11,6 +11,7 @@ const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const duration_constants_1 = require("../config/duration-constants");
 const cli_tool_ids_1 = require("../config/cli-tool-ids");
+const agent_target_options_1 = require("../config/agent-target-options");
 const instances_1 = require("./instances");
 function createAutoYesCommand() {
     const cmd = new commander_1.Command('auto-yes');
@@ -21,8 +22,8 @@ function createAutoYesCommand() {
         .option('--disable', 'Disable auto-yes')
         .option('--duration <duration>', `Duration (${duration_constants_1.ALLOWED_DURATIONS.join(', ')})`)
         .option('--stop-pattern <pattern>', 'Stop pattern (regex, max 500 chars)')
-        .option('--agent <agent>', 'CLI tool agent (claude, codex, gemini, vibe-local, opencode, copilot, antigravity)')
-        .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.INSTANCE_OPTION_DESCRIPTION)
+        .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .action(async (worktreeId, options) => {
         try {

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

@@ -1 +1 @@
-{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/capture.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6HpC,wBAAgB,oBAAoB,IAAI,OAAO,CA+E9C"}
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/capture.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8HpC,wBAAgB,oBAAoB,IAAI,OAAO,CA+E9C"}

package/dist/cli/commands/capture.js

@@ -11,6 +11,7 @@ const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const cli_tool_ids_1 = require("../config/cli-tool-ids");
+const agent_target_options_1 = require("../config/agent-target-options");
 const instances_1 = require("./instances");
 const pager_1 = require("../utils/pager");
 const transcript_squeeze_1 = require("../../lib/tmux/transcript-squeeze");
@@ -116,8 +117,8 @@ function createCaptureCommand() {
         .option('--pane', 'Read the raw tmux pane as a transcript, with blank layout rows squeezed')
         .option('--tail <n>', 'With --pane: keep only the last N lines OF THE SQUEEZED transcript')
         .option('--raw', 'With --pane: skip the squeeze and print the pane verbatim')
-        .option('--agent <agent>', 'CLI tool agent (claude, codex, gemini, vibe-local, opencode, copilot, antigravity)')
-        .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.INSTANCE_OPTION_DESCRIPTION)
+        .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .action(async (worktreeId, options) => {
         try {

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

@@ -1 +1 @@
-{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ls.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyDpC;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAwCzC"}
+{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ls.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyDpC;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CA8CzC"}

package/dist/cli/commands/ls.js

@@ -77,9 +77,15 @@ function createLsCommand() {
                 worktrees = worktrees.filter(wt => (wt.branch ?? wt.name).startsWith(options.branch));
             }
             // Issue #1005: Filter by worktree id prefix. Independent of `--branch`
-            // (AND-combined when both are given). Front-match / case-sensitive;
-            // the prefix does not guarantee uniqueness because ids are
-            // `<repo>-<branch>` slugs and startsWith can match sibling slugs.
+            // (AND-combined when both are given). Front-match / case-sensitive.
+            //
+            // Matched against the CURRENT ids only (Issue #1621): `/api/worktrees`
+            // returns live rows, and historical ids resolve exactly — never by
+            // prefix — via the alias table on the routes that take an `<id>`
+            // argument. A prefix still does not guarantee uniqueness: ids are now
+            // directory-basename slugs (`commandmate-issue-1644`), so sibling
+            // worktrees of the same feature share a prefix just as `<repo>-<branch>`
+            // slugs used to.
             if (options.id) {
                 worktrees = worktrees.filter(wt => wt.id.startsWith(options.id));
             }

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

@@ -1 +1 @@
-{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,oBAAoB,IAAI,OAAO,CAyE9C"}
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,oBAAoB,IAAI,OAAO,CAyE9C"}

package/dist/cli/commands/respond.js

@@ -12,6 +12,7 @@ const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const cli_tool_ids_1 = require("../config/cli-tool-ids");
+const agent_target_options_1 = require("../config/agent-target-options");
 const instances_1 = require("./instances");
 function createRespondCommand() {
     const cmd = new commander_1.Command('respond');
@@ -19,8 +20,8 @@ function createRespondCommand() {
         .description("Respond to an agent's prompt (yes/no, number, or text)")
         .argument('<worktree-id>', 'Worktree ID')
         .argument('<answer>', 'Response answer (yes, no, number, or free text)')
-        .option('--agent <agent>', 'CLI tool agent (claude, codex, gemini, vibe-local, opencode, copilot, antigravity)')
-        .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.INSTANCE_OPTION_DESCRIPTION)
+        .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .action(async (worktreeId, answer, options) => {
         try {

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

@@ -1 +1 @@
-{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgKpC,wBAAgB,iBAAiB,IAAI,OAAO,CAoK3C"}
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiKpC,wBAAgB,iBAAiB,IAAI,OAAO,CAoK3C"}

package/dist/cli/commands/send.js

@@ -11,6 +11,7 @@ const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const duration_constants_1 = require("../config/duration-constants");
 const cli_tool_ids_1 = require("../config/cli-tool-ids");
+const agent_target_options_1 = require("../config/agent-target-options");
 const model_validation_1 = require("../config/model-validation");
 const agent_instances_1 = require("../utils/agent-instances");
 const instances_1 = require("./instances");
@@ -132,9 +133,9 @@ function createSendCommand() {
         .description('Send a message to a worktree agent')
         .argument('<worktree-id>', 'Worktree ID')
         .argument('[message]', 'Message to send (omit when using --contract)')
-        .option('--agent <agent>', 'CLI tool agent (claude, codex, gemini, vibe-local, opencode, copilot, antigravity)')
-        .option('--instance <id>', 'Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). Defaults to the agent\'s primary instance.')
-        .option('--register', 'Register the --instance session into the agent-instance roster (Issue #1000)')
+        .option('--instance <id>', agent_target_options_1.INSTANCE_OPTION_DESCRIPTION)
+        .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
+        .option('--register', 'Register the --instance session into the agent-instance roster (needs --agent unless the instance id is itself a CLI tool id)')
         .option('--model <model>', 'Specify AI model for Copilot or Antigravity agent')
         .option('--auto-yes', 'Enable auto-yes before sending')
         .option('--duration <duration>', `Auto-yes duration (${duration_constants_1.ALLOWED_DURATIONS.join(', ')})`)

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;
 /**
@@ -272,7 +273,7 @@ function createWaitCommand() {
         .option('--timeout <seconds>', 'Maximum wait time in seconds', parseInt)
         .option('--on-prompt <mode>', 'Prompt handling: agent (default) or human')
         .option('--stall-timeout <seconds>', 'Maximum time without output change', parseInt)
-        .option('--instance <id>', 'Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). Defaults to the agent\'s primary instance.')
+        .option('--instance <id>', agent_target_options_1.WAIT_INSTANCE_OPTION_DESCRIPTION)
         .option('--verify', 'After completion, run every verification gate; exit 20 when a gate fails, 21 when there is nothing to verify')
         .option('--require-work', 'After completion, run only the work-evidence gate; exit 21 when the worktree has no commits and no uncommitted changes')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)

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

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

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

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

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

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

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

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

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

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