commandmate 0.27.1 → 0.28.0

package/dist/cli/commands/respond.js

@@ -14,6 +14,112 @@ 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");
+/**
+ * Whether this instance's agent can be answered by naming a decision
+ * (Issue #2040).
+ *
+ * The declared capability, read off the server, never inferred from a tool id —
+ * §4 D3 of `docs/design/multi-agent-state-architecture.md` puts every such
+ * property on the source so exactly this kind of caller does not have to keep a
+ * list. `eventIdentity` non-null means the agent publishes a per-decision id,
+ * which is what makes an option number a VERDICT that can be POSTed rather than
+ * a key that has to be typed.
+ *
+ * One extra GET, on a command a human or an orchestrator runs once per dialog —
+ * not in a poll loop. It buys the thing the probe is for: `respond` never sends
+ * a side-effecting request to the endpoint that cannot serve it.
+ *
+ * **Fail-open, on every failure.** An older daemon (no `structuredEvents`), a
+ * server that is not reachable, a worktree that does not exist: all of them
+ * answer false, which is the pre-#2040 path, byte for byte. The real request is
+ * a step away and will report the same failure properly.
+ *
+ * @param agent - The resolved CLI tool, when the caller named or resolved one
+ * @param instance - `--instance`, when the caller gave one
+ */
+async function addressesDecisionsById(client, worktreeId, agent, instance) {
+    const query = new URLSearchParams();
+    if (agent)
+        query.set('cliTool', agent);
+    if (instance)
+        query.set('instance', instance);
+    const suffix = query.toString();
+    try {
+        const output = await client.get(`/api/worktrees/${worktreeId}/current-output${suffix ? `?${suffix}` : ''}`);
+        return output.structuredEvents?.source?.capabilities?.eventIdentity != null;
+    }
+    catch {
+        return false;
+    }
+}
+function readAmbiguousDecisions(payload) {
+    const list = payload?.decisions;
+    if (!Array.isArray(list))
+        return [];
+    return list.flatMap((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return [];
+        const { id, kind, toolName } = entry;
+        if (typeof id !== 'string' || typeof kind !== 'string')
+            return [];
+        return [{ id, kind, toolName: typeof toolName === 'string' ? toolName : null }];
+    });
+}
+/**
+ * Answer the one decision this instance is holding (Issue #2040).
+ *
+ * `POST /api/worktrees/:id/respond` with neither `messageId` nor `decisionId`.
+ * Nothing is typed at the pane on this path — the verdict, or the question's
+ * chosen label, goes to the agent's own API — which is why every refusal below
+ * can say plainly that the terminal is untouched.
+ *
+ * @returns The server's answer; `'fallback'` when the server says this target
+ *   has no addressable decision after all (see below); or null when this
+ *   function has already reported a refusal and set the exit code
+ */
+async function answerSolePendingDecision(client, worktreeId, body) {
+    try {
+        return await client.post(`/api/worktrees/${worktreeId}/respond`, body);
+    }
+    catch (error) {
+        if (!(error instanceof api_client_1.ApiError))
+            throw error;
+        if (error.apiCode === 'decision_not_found') {
+            console.error('Error: Answer was not sent. Reason: decision_not_found ' +
+                '(this agent instance is not waiting on an approval or a question).');
+            process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+            return null;
+        }
+        if (error.apiCode === 'multiple_pending_decisions') {
+            const decisions = readAmbiguousDecisions(error.payload);
+            console.error(`Error: Answer was not sent. Reason: multiple_pending_decisions ` +
+                `(${decisions.length || 'several'} are open, and an option number names a ` +
+                'position in one of them). Answer them in the terminal, or one at a time by id.');
+            // The ids are what `{ decisionId, answer }` takes, so the refusal has
+            // somewhere to go rather than being a dead end.
+            for (const decision of decisions) {
+                console.error(`  ${decision.id}  ${decision.kind}${decision.toolName ? `  ${decision.toolName}` : ''}`);
+            }
+            process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+            return null;
+        }
+        if (error.apiCode === 'decision_source_unaddressable') {
+            // The probe and this POST disagreed about which agent the target resolves
+            // to — a roster edit between the two requests does it. The server's own
+            // instruction for this code is "answer it through /prompt-response", so
+            // that is what happens, rather than failing a `respond` over a race.
+            return 'fallback';
+        }
+        if (error.apiCode === 'answer_out_of_range') {
+            // Issue #1726's rule, unchanged: a number the agent's own list does not
+            // offer is a bad argument, and nothing was sent.
+            console.error(`Error: Answer was not sent. Reason: answer_out_of_range${error.payload?.error ? ` (${error.payload.error})` : ''}`);
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+            return null;
+        }
+        throw error;
+    }
+}
 function createRespondCommand() {
     const cmd = new commander_1.Command('respond');
     cmd
@@ -68,7 +174,33 @@ function createRespondCommand() {
             if (options.instance) {
                 body.instanceId = options.instance;
             }
-            const result = await client.post(`/api/worktrees/${worktreeId}/prompt-response`, body);
+            // Issue #2040: for an agent that publishes per-decision ids (opencode
+            // today, and only opencode), a bare `respond <worktree> 3` names the ONE
+            // decision that agent is holding, and the number is resolved against
+            // THAT decision's own options — the three verdicts for an approval, the
+            // published choices for a question. Nothing is typed at the pane, and
+            // nothing is sent at all unless the count is exactly one.
+            //
+            // `--default` deliberately stays on the keystroke route. There is a
+            // highlighted option in the TUI and nothing on the wire says which, so
+            // the structured path refuses it (`answerStructuredDecision` says so in
+            // as many words) — while Enter at a `keys` dialog is a real answer that
+            // this command has always been able to give.
+            const structured = !useDefault && (await addressesDecisionsById(client, worktreeId, agent, options.instance));
+            let result = null;
+            if (structured) {
+                const outcome = await answerSolePendingDecision(client, worktreeId, body);
+                // Null means the refusal has already been reported and the exit code
+                // set; a mocked `process.exit` returns, so this is the line that keeps
+                // the reporting below from running on nothing.
+                if (outcome === null)
+                    return;
+                if (outcome !== 'fallback')
+                    result = outcome;
+            }
+            if (result === null) {
+                result = await client.post(`/api/worktrees/${worktreeId}/prompt-response`, body);
+            }
             if (result && !result.success) {
                 // [DR2-06] Check reason for failure
                 const reason = result.reason || 'unknown';
@@ -107,6 +239,19 @@ function createRespondCommand() {
                     console.log(`Answered approval ${resolved.decisionId ?? '(unknown id)'} with ` +
                         `option ${resolved.optionNumber}: ${resolved.optionLabel}`);
                 }
+                else if (resolved.via === 'structured-question') {
+                    // Issue #2040: a question, answered over `POST /question/:id/reply`.
+                    // What is printed is what reached the AGENT — the labels — rather
+                    // than the number that was typed: `respond <id> 2` at a question is
+                    // a position in the agent's own list, and an operator reconciling
+                    // what they meant against what was sent needs the other end of that
+                    // mapping. `freeText` prints the text for the same reason.
+                    const chosen = resolved.optionLabels ?? [];
+                    console.log(`Answered question ${resolved.decisionId ?? '(unknown id)'} with ` +
+                        (chosen.length > 0
+                            ? chosen.map((label, index) => `${resolved.optionNumbers?.[index] ?? '?'}: ${label}`).join(', ')
+                            : `free text: ${(resolved.answers?.[0] ?? []).join(', ')}`));
+                }
                 else if (resolved.via === 'semantic') {
                     console.log(`Resolved "${answer}" to option ${resolved.optionNumber}: ${resolved.optionLabel}`);
                 }

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

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAA2C,aAAa,EAAE,MAAM,UAAU,CAAC;AA+IlF;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2F9E"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAA2C,aAAa,EAAE,MAAM,UAAU,CAAC;AA0PlF;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiG9E"}

package/dist/cli/commands/status.js

@@ -16,6 +16,11 @@ const env_setup_1 = require("../utils/env-setup");
 const package_info_1 = require("../utils/package-info");
 const input_validators_1 = require("../utils/input-validators");
 const version_probes_1 = require("../../lib/detection/version-probes");
+const localhost_self_check_1 = require("../../lib/server/localhost-self-check");
+// Relative, NOT `@/lib/push/vapid`: tsconfig.cli.json resets `paths` to {}, so an alias
+// import here breaks `npm run build:cli`. The module file, not the '@/lib/push' barrel —
+// that barrel pulls in web-push and better-sqlite3, neither of which belongs in the CLI.
+const vapid_1 = require("../../lib/push/vapid");
 const logger = new logger_1.CLILogger();
 /**
  * Print the running daemon's version and, when it differs from the installed CLI, a warning.
@@ -33,6 +38,97 @@ function printVersionInfo(status) {
             'Restart the server ("commandmate stop && commandmate start") to run the current version.');
     }
 }
+/**
+ * Surface the startup self-check's verdict (Issue #2113).
+ *
+ * The server probes `http://localhost:<port>` after `listen` and, when something OTHER
+ * than itself answers, drops a record under `<configDir>/logs/self-check-<port>.json`. That
+ * is the only situation this prints in — the record is deleted on every clean check and
+ * on shutdown, so silence here means the advertised URL really does reach the server.
+ *
+ * Why a file rather than the PID file or a re-probe:
+ * - the PID file is written by the CLI parent with O_EXCL *before* the child binds, and
+ *   its hybrid layout is a forward-compatibility contract (#1632) — the server cannot
+ *   append to it without racing the parent and perturbing that format;
+ * - a re-probe from here cannot reproduce the verdict. Identity is established by the
+ *   server OBSERVING its own probe request in-process; a separate CLI process has no
+ *   way to tell "CommandMate answered" from "some other server answered", short of
+ *   platform-specific `lsof` parsing.
+ *
+ * Staleness is guarded on `startedAt`, NOT on the PID, and that distinction was measured
+ * rather than reasoned: `daemon.start()` spawns `npm run start`, so the state file holds
+ * the WRAPPER's PID while the record holds the PID of the `node dist/server/server.js`
+ * child that actually binds the port (2026-08-27, port 3902: state file 58882, listener
+ * 58937). A PID comparison here therefore never matched and the warning never reached
+ * `status` — the whole point of the Issue's "log AND status" acceptance condition.
+ * A record predating the current daemon's launch cannot be the current daemon's; one
+ * written after it can only have come from it, because the record is keyed by port and
+ * every startup either overwrites it or deletes it.
+ *
+ * A state file with no `startedAt` (written before #1354) leaves nothing to compare, so
+ * the record is reported: it is refreshed on every start, and hiding a real conflict is
+ * the worse failure.
+ *
+ * Never throws — a diagnostic must not be able to turn `status` into a failure.
+ */
+function printLocalhostConflict(status) {
+    try {
+        if (status.port === undefined)
+            return;
+        const record = (0, localhost_self_check_1.readLocalhostConflict)(status.port);
+        if (record === null)
+            return;
+        if (status.startedAt !== undefined && record.detectedAt < status.startedAt)
+            return;
+        console.log('');
+        logger.warn(`Startup self-check (${record.detectedAt}):`);
+        for (const line of (0, localhost_self_check_1.formatLocalhostConflictWarning)(record)) {
+            console.log(`  ${line}`);
+        }
+    }
+    catch {
+        // Config dir unreadable, record unparsable: report the server, drop the hint.
+    }
+}
+/**
+ * Report the server's Web Push configuration, or nothing when it is healthy
+ * (Issues #2123 / #2124).
+ *
+ * The Issues' acceptance condition is "the startup log OR `commandmate status`",
+ * and this is the half that is still readable a week later — a daemon started in
+ * the background writes its stdout wherever the launcher put it, and the reader
+ * who notices "my phone stopped buzzing" reaches for `status`.
+ *
+ * Read from the env the DAEMON runs with (`getEffectiveEnv()`), not from this
+ * process's own environment: `.env` outranks exported variables for the server
+ * child (Issue #1266), so `process.env` here would report this shell's idea of
+ * the configuration rather than the server's. Exactly what the `CM_ALLOWED_IPS`
+ * line below already does.
+ *
+ * The residual imprecision is the same one that line carries: a variable exported
+ * into the daemon's environment at launch and absent from `.env` is invisible
+ * here. `commandmate init` writes all three VAPID variables into `.env`, so the
+ * supported setup is covered; a hand-exported key pair would be reported as
+ * unconfigured, which is why the startup log carries the same lines.
+ *
+ * Silent on a healthy install — that silence is the negative control both Issues
+ * ask for. Never throws: a diagnostic must not turn `status` into a failure.
+ */
+function printVapidStatus(env) {
+    try {
+        const lines = (0, vapid_1.formatVapidReportLines)((0, vapid_1.inspectVapidConfig)(env));
+        if (lines.length === 0)
+            return;
+        console.log('');
+        logger.warn(lines[0]);
+        for (const line of lines.slice(1)) {
+            console.log(line);
+        }
+    }
+    catch {
+        // Unreadable .env, unparsable value: report the server, drop the hint.
+    }
+}
 /**
  * Warn when this build's detection rules were read off an older CLI than the one
  * installed (Issue #1929, design §4 D2).
@@ -103,6 +199,10 @@ async function showSingleStatus(issueNo) {
     if (status.url) {
         console.log(`URL:     ${status.url}`);
     }
+    // Issue #2113: the advertised localhost URL may not reach this server at all
+    printLocalhostConflict(status);
+    // Issue #2123 / #2124: whether Web Push can work at all on this server
+    printVapidStatus(daemonManager.getEffectiveEnv());
 }
 /**
  * Show status for all servers (main + all worktrees)
@@ -192,6 +292,10 @@ async function statusCommand(options = {}) {
         if (status.url) {
             console.log(`URL:     ${status.url}`);
         }
+        // Issue #2113: the advertised localhost URL may not reach this server at all
+        printLocalhostConflict(status);
+        // Issue #2123 / #2124: whether Web Push can work at all on this server
+        printVapidStatus(daemonManager.getEffectiveEnv());
         // Issue #332: Show IP restriction status
         // Issue #1266: read the env the server actually runs with. An exported CM_ALLOWED_IPS
         // shadowed the .env one here, reporting an ACL the server does not enforce.

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;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6DpC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AAy5BH,wBAAgB,iBAAiB,IAAI,OAAO,CAmJ3C"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6DpC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AAk8BH,wBAAgB,iBAAiB,IAAI,OAAO,CAmJ3C"}

package/dist/cli/commands/wait.js

@@ -139,6 +139,39 @@ const TURN_ADOPTION_GRACE_MS = POLL_INTERVAL_MS;
  *     for working around a detector bug, and the bug is the thing to fix.
  */
 const UNCLASSIFIED_DWELL_MS = 60_000;
+/**
+ * The keystroke that closes opencode's sidebar, in opencode's own notation
+ * (Issue #2095).
+ *
+ * A local copy of `OPENCODE_SIDEBAR_RECOVERY_CHORD` from
+ * `src/lib/detection/opencode-pane-obstruction.ts` and not an import: the CLI
+ * builds with `"paths": {}` (tsconfig.cli.json) and cannot reach `@/lib` at all,
+ * which is why `api-responses.ts` mirrors payload shapes rather than importing
+ * them. Taken from opencode's own keybind table, which its `ctrl+p` palette
+ * prints as `Show sidebar   ctrl+x b`.
+ */
+const OPENCODE_SIDEBAR_RECOVERY_CHORD = 'ctrl+x b';
+/**
+ * The cause sentence to append when the frame carries a pane obstruction, or ''
+ * (Issue #2095).
+ *
+ * Appended rather than substituted, and no exit code moves: the frame is
+ * genuinely unclassified and `wait` was already right to stop on it. What it
+ * could not say before is WHY, which left an operator with `capture --pane` and
+ * a screenful of box drawing to work it out from.
+ *
+ * Empty for a server too old to publish the field, which is the same output
+ * `wait` produced before this Issue.
+ */
+function describePaneObstruction(data) {
+    const obstruction = data.paneObstruction;
+    if (!obstruction)
+        return '';
+    return (` Cause: paneObstruction=${obstruction.id} — a second column is sharing rows with the ` +
+        `transcript (it reads ${JSON.stringify(obstruction.matchedText)}), which covers the marker ` +
+        `that ends a turn. Press \`${OPENCODE_SIDEBAR_RECOVERY_CHORD}\` in the pane to close ` +
+        `opencode's sidebar.`);
+}
 /**
  * How recent `autoYes.lastSuppression` must be to be reported as the reason this
  * wait is blocked (Issue #1699).
@@ -671,7 +704,12 @@ async function pollWorktree(client, worktreeId, options) {
                     const question = `Unclassified interactive frame on ${worktreeId} for ${dwellSeconds}s ` +
                         `(status=${data.sessionStatus ?? 'unknown'}/${data.sessionStatusReason ?? 'unknown'}). ` +
                         `The detection layer could not parse it; inspect the raw pane with ` +
-                        `\`commandmate capture ${worktreeId} --pane\`.`;
+                        `\`commandmate capture ${worktreeId} --pane\`.` +
+                        // Issue #2095: the sidebar is exactly this frame's reason, and the
+                        // one recovery is a keystroke in the pane. Riding the message keeps
+                        // the exit-code table (10, `type: unclassified`) unchanged for every
+                        // caller that already branches on it.
+                        describePaneObstruction(data);
                     if (options.onPrompt === 'human') {
                         console.error(question);
                         console.error('Waiting for human response...');

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

@@ -43,4 +43,16 @@ export declare const INSTANCE_OPTION_DESCRIPTION: string;
  * agent on `send` and nothing on `wait` waits on the wrong session in silence.
  */
 export declare const WAIT_INSTANCE_OPTION_DESCRIPTION: string;
+/**
+ * `--instance` description for `interrupt` (Issue #2101).
+ *
+ * `interrupt` takes no `--agent`, on the `wait` precedent and for the same
+ * reason #1629 gave: the flag would have to say *which* session, and a bare
+ * `--agent codex` does not. The default here is not "the primary instance"
+ * either — `POST /api/worktrees/:id/interrupt` with no `instanceId` stops EVERY
+ * running session of the worktree, so the flag is what narrows a multi-instance
+ * worktree to one, and its absence is a deliberate broadcast rather than a
+ * fallback.
+ */
+export declare const INTERRUPT_INSTANCE_OPTION_DESCRIPTION: string;
 //# sourceMappingURL=agent-target-options.d.ts.map

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

@@ -1 +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"}
+{"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;AAE9D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qCAAqC,QAGkB,CAAC"}

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

@@ -31,7 +31,7 @@
  * 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;
+exports.INTERRUPT_INSTANCE_OPTION_DESCRIPTION = 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.
@@ -52,3 +52,17 @@ exports.INSTANCE_OPTION_DESCRIPTION = 'Agent instance ID: <agent> or <agent>-<n>
  */
 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).';
+/**
+ * `--instance` description for `interrupt` (Issue #2101).
+ *
+ * `interrupt` takes no `--agent`, on the `wait` precedent and for the same
+ * reason #1629 gave: the flag would have to say *which* session, and a bare
+ * `--agent codex` does not. The default here is not "the primary instance"
+ * either — `POST /api/worktrees/:id/interrupt` with no `instanceId` stops EVERY
+ * running session of the worktree, so the flag is what narrows a multi-instance
+ * worktree to one, and its absence is a deliberate broadcast rather than a
+ * fallback.
+ */
+exports.INTERRUPT_INSTANCE_OPTION_DESCRIPTION = 'Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). '
+    + 'interrupt takes no --agent, so name the instance here. '
+    + 'Omitted, every running session of the worktree is interrupted.';

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- Connection target is resolved as: exported CM_PORT > ~/.commandmate/.env CM_PORT > 3000\n  (CM_BIND and the CM_HTTPS_CERT + CM_HTTPS_KEY pair are honoured the same way)\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    --ignore-structured-prompt\n                           Send even if only the agent's hooks report an open dialog.\n                           For a session whose pane looks idle but keeps refusing;\n                           a dialog visible in the terminal is still refused.\n\n  Refused while the agent is waiting on a prompt (exit 2). Keystrokes sent to\n  an open dialog never reach the agent -- they pile up in the dialog's own\n  input line, and the next respond then carries that text along as a message\n  instead of an answer. Nudging a stalled worker is how this gets worse.\n  Answer first: commandmate respond <id> <answer>. respond, special keys and\n  prompt-response are never refused -- they are the way out. Timer-fired sends\n  ARE refused (same service layer) and record [prompt_waiting] as their reason.\n  It fails open if the pane cannot be read, so treat it as a narrowing, not a\n  guarantee.\n\n  Two layers can report the dialog: the terminal scraper, and the agent's own\n  hooks. Either one is enough to refuse -- the dialog the scraper cannot read is\n  exactly the one that caused this. A frame neither layer classifies is still\n  wait's \"unclassified\" case instead.\n\n  A hook-reported dialog is released by the agent's next event, and hooks are\n  fail-open, so the record can outlive its dialog. It therefore stops blocking\n  sends 5 minutes after it was reported -- and immediately with\n  --ignore-structured-prompt, or CM_STRUCTURED_SEND_GUARD=off for the server.\n  A session nobody can send to is worse than a missed guard. Both bypasses are\n  narrow: a prompt on screen is still refused, and the payload still reports it\n  (wait and the UI do not go quiet).\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    Three \"type\" values share exit 10; only the first is answerable with\n    respond:\n      yes_no / multiple_choice  a parsed prompt        -> commandmate respond\n      selection_list            arrow-key menu         -> special keys\n      unclassified              the frame is interactive but detection could\n                                not parse it, and it has stayed that way for\n                                60s -> look at the pane: capture <id> --pane\n    \"unclassified\" exists because a frame that slips past detection disables\n    auto-yes, the contract's autoYes policy and this exit 10 all at once. It\n    needs the dwell: a capture taken mid-repaint can raise the flag once.\n    --on-prompt human keeps waiting for it, same as the other two.\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    commandmate status                 # Confirm 'ls' and 'status' report the same Port\n                                       # (with several servers running, an exported CM_PORT\n                                       #  points 'ls' at a different one)\n\n  Authentication:\n    CM_AUTH_TOKEN=your-token commandmate ls\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- Connection target is resolved as: exported CM_PORT > ~/.commandmate/.env CM_PORT > 3000\n  (CM_BIND and the CM_HTTPS_CERT + CM_HTTPS_KEY pair are honoured the same way)\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    --ignore-structured-prompt\n                           Send even if only the agent's hooks report an open dialog.\n                           For a session whose pane looks idle but keeps refusing;\n                           a dialog visible in the terminal is still refused.\n\n  Refused while the agent is waiting on a prompt (exit 2). Keystrokes sent to\n  an open dialog never reach the agent -- they pile up in the dialog's own\n  input line, and the next respond then carries that text along as a message\n  instead of an answer. Nudging a stalled worker is how this gets worse.\n  Answer first: commandmate respond <id> <answer>. respond, special keys and\n  prompt-response are never refused -- they are the way out. Timer-fired sends\n  ARE refused (same service layer) and record [prompt_waiting] as their reason.\n  It fails open if the pane cannot be read, so treat it as a narrowing, not a\n  guarantee.\n\n  Two layers can report the dialog: the terminal scraper, and the agent's own\n  hooks. Either one is enough to refuse -- the dialog the scraper cannot read is\n  exactly the one that caused this. A frame neither layer classifies is still\n  wait's \"unclassified\" case instead.\n\n  A hook-reported dialog is released by the agent's next event, and hooks are\n  fail-open, so the record can outlive its dialog. It therefore stops blocking\n  sends 5 minutes after it was reported -- and immediately with\n  --ignore-structured-prompt, or CM_STRUCTURED_SEND_GUARD=off for the server.\n  A session nobody can send to is worse than a missed guard. Both bypasses are\n  narrow: a prompt on screen is still refused, and the payload still reports it\n  (wait and the UI do not go quiet).\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    Three \"type\" values share exit 10; only the first is answerable with\n    respond:\n      yes_no / multiple_choice  a parsed prompt        -> commandmate respond\n      selection_list            arrow-key menu         -> special keys\n      unclassified              the frame is interactive but detection could\n                                not parse it, and it has stayed that way for\n                                60s -> look at the pane: capture <id> --pane\n    \"unclassified\" exists because a frame that slips past detection disables\n    auto-yes, the contract's autoYes policy and this exit 10 all at once. It\n    needs the dwell: a capture taken mid-repaint can raise the flag once.\n    --on-prompt human keeps waiting for it, same as the other two.\n\n    On opencode the commonest cause has a name and a one-key fix. If its\n    sidebar is on -- ctrl+x b, or \"Show sidebar\" in its ctrl+p palette -- it\n    shares screen rows with the transcript, covers the marker that ends a\n    turn, and every frame after that reads running/unknown_frame. wait says\n    so on stderr (paneObstruction=opencode_sidebar) and capture --json\n    publishes the same field. Press ctrl+x b in the pane to close it; Escape\n    does not.\n\n    An opencode DIALOG is the other one, and it exits 10 as selection_list\n    rather than waiting out the dwell. Its session list (ctrl+x l), agent list\n    (ctrl+x a), timeline (ctrl+x g), command palette (ctrl+p) and pickers are\n    painted over the transcript, so the marker of the previous turn is still\n    on the pane behind them -- which is what used to make wait report a\n    blocked pane as Completed. sessionStatusReason is opencode_modal_overlay\n    and Escape closes all of them.\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 interrupt <worktree-id>\n  Interrupt the turn an agent is generating (the GUI's interrupt button).\n  Not 'stop' -- that stops the CommandMate server.\n\n  commandmate interrupt <id>                    # Every running session of the worktree\n  commandmate interrupt <id> --instance codex-2 # Only that instance\n  commandmate interrupt <id> --json             # { success, message, interrupted[] }\n\n  Omitting --instance is a broadcast, not \"the primary instance\": the route\n  interrupts every session that is running. There is no --agent (wait's rule:\n  a tool name does not say which session).\n\n  Exit codes:\n    0  - At least one session was interrupted\n    30 - The worktree exists but nothing was running (nothing was interrupted)\n    99 - No such worktree\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  30  NO_ACTIVE_SESSIONS - interrupt found no running session to interrupt\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    commandmate status                 # Confirm 'ls' and 'status' report the same Port\n                                       # (with several servers running, an exported CM_PORT\n                                       #  points 'ls' at a different one)\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,stkBA+VlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,klJAmIpC,CAAC"}
+{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,0goBAiYlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,klJAmIpC,CAAC"}

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

@@ -149,6 +149,22 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
     needs the dwell: a capture taken mid-repaint can raise the flag once.
     --on-prompt human keeps waiting for it, same as the other two.
 
+    On opencode the commonest cause has a name and a one-key fix. If its
+    sidebar is on -- ctrl+x b, or "Show sidebar" in its ctrl+p palette -- it
+    shares screen rows with the transcript, covers the marker that ends a
+    turn, and every frame after that reads running/unknown_frame. wait says
+    so on stderr (paneObstruction=opencode_sidebar) and capture --json
+    publishes the same field. Press ctrl+x b in the pane to close it; Escape
+    does not.
+
+    An opencode DIALOG is the other one, and it exits 10 as selection_list
+    rather than waiting out the dwell. Its session list (ctrl+x l), agent list
+    (ctrl+x a), timeline (ctrl+x g), command palette (ctrl+p) and pickers are
+    painted over the transcript, so the marker of the previous turn is still
+    on the pane behind them -- which is what used to make wait report a
+    blocked pane as Completed. sessionStatusReason is opencode_modal_overlay
+    and Escape closes all of them.
+
   --verify turns "the agent stopped" into "the work passes the repository's own
   checks". Verification only runs when completion was detected: a prompt (10) or
   a timeout (124) is reported as-is and never verified. With several worktrees,
@@ -221,6 +237,23 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
     0  - Response sent
     99 - Prompt already dismissed (prompt_no_longer_active)
 
+### commandmate interrupt <worktree-id>
+  Interrupt the turn an agent is generating (the GUI's interrupt button).
+  Not 'stop' -- that stops the CommandMate server.
+
+  commandmate interrupt <id>                    # Every running session of the worktree
+  commandmate interrupt <id> --instance codex-2 # Only that instance
+  commandmate interrupt <id> --json             # { success, message, interrupted[] }
+
+  Omitting --instance is a broadcast, not "the primary instance": the route
+  interrupts every session that is running. There is no --agent (wait's rule:
+  a tool name does not say which session).
+
+  Exit codes:
+    0  - At least one session was interrupted
+    30 - The worktree exists but nothing was running (nothing was interrupted)
+    99 - No such worktree
+
 ### commandmate capture <worktree-id>
   Get current terminal output.
 
@@ -338,6 +371,7 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
   10  PROMPT_DETECTED  - Prompt detected during wait
   20  VERIFY_FAILED    - A verification gate failed (verify, wait --verify)
   21  NOT_STARTED      - Nothing to verify: no commits, no uncommitted changes
+  30  NO_ACTIVE_SESSIONS - interrupt found no running session to interrupt
   99  UNEXPECTED_ERROR - Unexpected error / resource not found / no verdict
   124 TIMEOUT          - Wait or verification timeout exceeded
 

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

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

package/dist/cli/program.js

@@ -22,6 +22,8 @@ const sync_1 = require("./commands/sync");
 const send_1 = require("./commands/send");
 const wait_1 = require("./commands/wait");
 const respond_1 = require("./commands/respond");
+// Issue #2101: CLI face of POST /api/worktrees/:id/interrupt
+const interrupt_1 = require("./commands/interrupt");
 const capture_1 = require("./commands/capture");
 const auto_yes_1 = require("./commands/auto-yes");
 const verify_1 = require("./commands/verify");
@@ -207,6 +209,10 @@ function buildProgram() {
     program.addCommand((0, send_1.createSendCommand)());
     program.addCommand((0, wait_1.createWaitCommand)());
     program.addCommand((0, respond_1.createRespondCommand)());
+    // Issue #2101: stop the turn an agent is generating. Registered next to
+    // `respond` because the two are the pair that act on a LIVE turn; `stop`
+    // above stops the CommandMate server and is not related.
+    program.addCommand((0, interrupt_1.createInterruptCommand)());
     program.addCommand((0, capture_1.createCaptureCommand)());
     program.addCommand((0, auto_yes_1.createAutoYesCommand)());
     // Issue #1544: verification gates (.commandmate/verify.yaml)