commandmate 0.44.0 → 0.44.2

package/README.md

@@ -11,12 +11,29 @@
 
 **[commandmate website →](https://kewton.github.io/CommandMate/)**
 
-> **No long blocks of time? Run an AI team from your phone.**
+> **Run multiple coding agents in parallel — even away from your desk.**
 
-- 10+ PRs a day, solo
-- $110–$210 a month: Claude Max + Command Code Goat
-- ~80% of my instructions sent from a phone (my estimate)
-- 689 PRs merged in September 2026, across my repositories
+CommandMate puts the coding agents you already use in one place on your own machine, so you can run them side by side, hand them work one issue at a time, and let your own checks decide when the work is done.
+
+| Level | What CommandMate does | Your role |
+|-------|-----------------------|-----------|
+| 1 — Parallel | Runs several coding agents side by side, from one place | Operator: you answer each agent |
+| 2 — Delegate | Takes work one issue at a time, and decides it is done by your own checks (lint, tests), not by what the agent says | Product / tech lead: you write the task and accept the result |
+| 3 — Manage | A PM agent plans, assigns and checks the work; you talk to the PM and approve | Owner: you set the direction and approve |
+| Next — Learn | Not built yet. The direction: use the record of past work to improve how the work is done | — |
+
+**Anywhere:** at every level you can answer and approve from your phone's browser, so the work does not stop when you leave the desk.
+
+Most people need only Level 2. Stop at the level that fits you; nothing here asks you to climb.
+
+One recorded run (PM → dev lead → workers):
+
+- 4 issues, 4 workers (Command Code), PM and dev lead on Claude Code
+- 2 messages and 3 taps from a phone-width web UI
+- 4/4 checks passed, PRs merged with CI green, UAT 4/4 GO
+- 9 min 48 s from request to report
+
+As observed: one run, recorded on 2026-10-02. Not a benchmark.
 
 <p align="center">
   <img src="./docs/images/demo-hero.en.gif" width="560" alt="A list of four open issues, one message typed into the lead session, four worktree sessions in the sidebar, a worker writing a test file, and a final report with a phase-by-phase table" />
@@ -34,22 +51,38 @@ Open source (MIT) · runs on your machine · macOS / Linux / Windows (WSL2) · n
 
 ---
 
-## Three levels
+## The levels
+
+### Level 1 — Parallel
+
+Run Claude Code, Codex, Gemini CLI, Copilot, OpenCode (1.x and V2), Antigravity, Command Code or local models side by side. Each task gets its own session in its own Git worktree — a separate working copy of your repository — so two agents never edit the same files. CommandMate tells you which agent is waiting on you, as a badge or a push notification, and you answer it like a chat.
+
+Your role: the operator. You read each agent's question and answer it.
+
+### Level 2 — Delegate
+
+Hand over an issue, not a chat message. Each issue goes out as a task contract: a short file in your repository that says the goal, which files the agent may change, and which checks must pass. When the agent stops, CommandMate runs your own checks — lint, type check, tests — and their result, not the agent's summary, says whether the work passed.
+
+```text
+Issues → Task contracts → Worktrees → Agents × N → Checks → PR
+```
 
-### Level 1 — Many agents, one place, in your pocket
+Your role: the product or tech lead. You decide what to build and accept what passed. You can also send a session's work to another agent for review. How a result is reported is in the [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md#commandmate-verify).
 
-Every task gets its own Git worktree and session, on whichever agent fits: Claude Code, Codex, Gemini CLI, Copilot, OpenCode (1.x and V2), Antigravity, Command Code or local models. Waiting is read from the agents' own hooks, not guessed from the screen, and reaches your phone as a badge or a push notification. You answer from the browser.
+### Level 3 — Manage
 
-### Level 2 — Work like a team, not a chat
+Talk to one PM agent instead of to every agent. Send it one message: it plans the issues, hands each one to an agent as in Level 2, and only work that passed the checks becomes a PR. Every step that changes something waits for your approval, and the PM can also start at the times you set while you are away.[^author]
 
-A task goes out with a contract — the goal, the files it may change, the gates — and comes back with a verdict: the gates' exit code (`0` passed, `20` failed, `21` no evidence of work), not the agent's summary. A session can also hand its work to another agent for review.
+Your role: the owner. You set the direction, answer the PM, and approve.
 
-### Level 3 — An AI team that builds and maintains
+### Next — Learn
 
-One message to a lead session: it plans several issues, hands each one to a worker under a contract, and only what passed the gates becomes a PR. Schedules keep work running while you are away. The author's daily auto-fix loop is the author's own operation built from these parts, not a switch in the product.
+Not built yet, and only a direction: use the record each piece of work leaves behind to improve how the next one is done.
 
 More on each level on the [website](https://kewton.github.io/CommandMate/), and the long form in [How CommandMate works](./docs/en/user-guide/how-it-works.md).
 
+[^author]: The author runs a daily round of automatic fixes built from these parts and a scheduled start. That is the author's own setup, not a switch in the product.
+
 ---
 
 ## Set up with your agent
@@ -70,12 +103,16 @@ commandmate init
 commandmate start --daemon
 ```
 
-- Open http://127.0.0.1:3000. CommandMate binds `127.0.0.1` by default, and `localhost` can resolve to `::1` (IPv6) first — an address CommandMate does not listen on, and another process may.
+- Open http://127.0.0.1:3000 — `127.0.0.1`, not `localhost`. The [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md#accessing-via-browser) explains why.
 - To try it without installing, run `npx commandmate@latest` (always with `@latest`). The [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) covers why, plus WSL2, updating and building from source.
-- Phone notifications stay off until `commandmate init` has written `CM_VAPID_PUBLIC_KEY` / `CM_VAPID_PRIVATE_KEY` / `CM_VAPID_SUBJECT` into `.env`. See [Web App Guide → Phone Notifications](./docs/en/user-guide/webapp-guide.md#phone-notifications-web-push).
+- Phone notifications are set up by `commandmate init`. If they do not arrive, see [Web App Guide → Phone Notifications](./docs/en/user-guide/webapp-guide.md#phone-notifications-web-push).
 - To reach it from your phone, run `commandmate remote`: it publishes the server through Tailscale or Cloudflare (asking before anything goes on the public internet) and prints a QR code to pair with.
 
-First commands, for you or for your agent:
+### First commands
+
+For you or for your agent, by level.
+
+**Level 1 — Parallel**
 
 | Command | What it does |
 |---------|--------------|
@@ -83,12 +120,22 @@ First commands, for you or for your agent:
 | `commandmate remote` | Pair your phone with a QR code |
 | `commandmate ls` | Every worktree and the state of its session |
 | `commandmate send <id> "Implement Issue #101" --instance codex` | Send a message to one agent's session |
-| `commandmate send <id> --contract .commandmate/tasks/issue-101.yaml --instance codex` | Hand over a task contract |
-| `commandmate wait <id> --instance codex --verify` | Wait for the agent, then run the gates: exit `0` / `20` / `21` |
 | `commandmate capture <id>` | Read the session's current output |
 | `commandmate respond <id> "yes"` | Answer the prompt the agent is waiting on |
-| `commandmate skill list` | The official Catalog Skills you can install per worktree |
 | `commandmate update` | Update a global install and restart the server |
+
+**Level 2 — Delegate**
+
+| Command | What it does |
+|---------|--------------|
+| `commandmate send <id> --contract .commandmate/tasks/issue-101.yaml --instance codex` | Hand over a task contract |
+| `commandmate wait <id> --instance codex --verify` | Wait for the agent, then run your checks and report pass or fail |
+
+**Level 3 — Manage**
+
+| Command | What it does |
+|---------|--------------|
+| `commandmate skill list` | The official Catalog Skills you can install per worktree, including the one a PM agent runs on |
 | `commandmate docs --section agent-operations` | The full command guide, for your agent to read |
 
 Every command and flag is in the [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md); `commandmate --help` lists the options.
@@ -97,9 +144,9 @@ Every command and flag is in the [CLI Operations Guide](./docs/en/user-guide/cli
 
 ## What it does not do
 
-- It is a run, not a resident agent. Nothing loops forever, and nothing mutates without an explicit approve.
-- It does not read the code for you. Gates catch what your tests and checks catch.
-- Review by another agent is a step you add, not something the runner does for you.
+- It does not keep running in the background on its own. Each piece of work starts and ends, and nothing in your repository changes until you approve it.
+- It does not read the code for you. Your checks catch what your tests and linters catch, and nothing more.
+- Review by another agent is a step you add, not something CommandMate does for you.
 - Approvals still come to a person. Auto Yes is opt-in, time-boxed, and stops on the patterns you set.
 - It does not replace tmux, Git worktrees, your terminal, or your agent CLI. An OS reboot ends the processes; what survives is the record.
 
@@ -109,11 +156,11 @@ Every command and flag is in the [CLI Operations Guide](./docs/en/user-guide/cli
 
 | Document | Description |
 |----------|-------------|
-| [How CommandMate works](./docs/en/user-guide/how-it-works.md) | The long form: measured runs, feature tables, use cases, supported agents, security, the Vibe Engineering workflow |
-| [Tutorial](./docs/en/user-guide/tutorial.md) | Fork a sample repository and go from contract to verified result in about fifteen minutes |
-| [Quick Start](./docs/en/user-guide/quick-start.md) | The minimum contract-and-verify loop on any agent, then a five-minute development flow |
+| [How CommandMate works](./docs/en/user-guide/how-it-works.md) | The long form, level by level: Parallel, Delegate (contracts, gates, Skills), Manage, Next; then Anywhere, supported agents, security, measured runs |
+| [Tutorial](./docs/en/user-guide/tutorial.md) | Fork a sample repository and go from a task contract to a result that passed its checks in about fifteen minutes |
+| [Quick Start](./docs/en/user-guide/quick-start.md) | The smallest hand-over-and-check flow on any agent, then a five-minute development flow |
 | [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) | Installation, `npx`, initial setup, updating, building from source |
-| [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) | Driving sessions from the CLI: execution contracts, verification gates, Skills, agent instances |
+| [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) | Driving sessions from the CLI: task contracts, checks (verification gates), Skills, agent instances |
 | [Web App Guide](./docs/en/user-guide/webapp-guide.md) | The web UI, phone access, app install (PWA), push notifications, supported browsers |
 | [Troubleshooting & FAQ](./docs/en/user-guide/troubleshooting.md) | Stuck sessions, an empty-looking `tmux attach`, port conflicts, phone and remote access |
 | [Skills Guide](./docs/en/user-guide/skills.md) | Installing official Catalog Skills into a worktree |

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;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,OAAO,EAAE,SAAS,EAAqB,MAAM,qBAAqB,CAAC;AAwVnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB;AA2ED,wBAAgB,oBAAoB,IAAI,OAAO,CAoI9C"}
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/capture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,OAAO,EAAE,SAAS,EAAqB,MAAM,qBAAqB,CAAC;AAsVnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAexB;AA2ED,wBAAgB,oBAAoB,IAAI,OAAO,CAoI9C"}

package/dist/cli/commands/capture.js

@@ -18,6 +18,7 @@ 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");
+const prompt_view_1 = require("../../lib/session/prompt-view");
 /**
  * Rows of pane history the `--pane` viewer asks for.
  *
@@ -39,13 +40,6 @@ const DEFAULT_FOLLOW_INTERVAL_MS = 2000;
 /** Floor and ceiling for `--interval`. */
 const MIN_FOLLOW_INTERVAL_MS = 250;
 const MAX_FOLLOW_INTERVAL_MS = 60_000;
-/**
- * `promptData.type` the server writes for a frame the detection layer could not
- * classify (Issue #1708). Mirrors UNCLASSIFIED_PROMPT_TYPE in
- * src/types/models.ts; duplicated rather than imported because the CLI bundle
- * keeps its own copy of the API shapes (see api-responses.ts).
- */
-const UNCLASSIFIED_FRAME_TYPE = 'unclassified';
 /** Shown by the default text mode when there is no transcript to print (Issue #3128). */
 const EMPTY_TRANSCRIPT_HINT = 'No transcript yet. A prompt (e.g. "Trust this folder?") may be waiting on screen; '
     + 'read it with `commandmate capture <worktree-id> --instance <instance> --pane --tail 40`.';
@@ -219,7 +213,12 @@ async function capturePrompts(worktreeId, options) {
         // Issue #1708: a row recording that detection FAILED must not read as a
         // prompt that was seen and is merely unanswered — that reading is what would
         // send an operator looking for an answer path that never existed.
-        const unclassified = p.type === UNCLASSIFIED_FRAME_TYPE;
+        //
+        // Issue #3184: "a row nobody can answer" is the shared view's `unreadable`
+        // — every history record of type `unclassified` is one, since neither
+        // degraded record carries a decision id. Read through `derivePromptView`
+        // rather than a restated copy of the sentinel.
+        const unclassified = (0, prompt_view_1.derivePromptView)(p)?.kind === 'unreadable';
         // Issue #1725: the same row type now has two origins, and they mean
         // opposite things about coverage. `detection-failed` is "nothing saw this";
         // `hook-<source>` is "the agent told us, and the scraper still did not see

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

@@ -289,6 +289,16 @@ export declare function derivePairingState(handoffPresent: boolean, pairingExpir
  * @returns e.g. `in 6h 12m`, or `expired`
  */
 export declare function formatRemaining(ms: number): string;
+/**
+ * The human-facing pairing expiry line shared by `remote` and `remote pair`
+ * (Issue #3156): local clock time, time left, and the single-use reminder, so
+ * whoever hands the link on can say when it stops working.
+ *
+ * @param expiresAt - Epoch ms the pairing code dies at
+ * @param now - Epoch ms, injectable for tests
+ * @returns e.g. `Pairing expires: 14:16 (in 9m), works once (2026-10-04T05:16:00.000Z)`
+ */
+export declare function formatPairingExpiryLine(expiresAt: number, now?: number): string;
 /**
  * Run the `status` flow (§5.4).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/remote.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/remote.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/remote.js

@@ -60,6 +60,7 @@ exports.runRemoteUp = runRemoteUp;
 exports.buildPairingUrl = buildPairingUrl;
 exports.derivePairingState = derivePairingState;
 exports.formatRemaining = formatRemaining;
+exports.formatPairingExpiryLine = formatPairingExpiryLine;
 exports.runRemoteStatus = runRemoteStatus;
 exports.runRemotePair = runRemotePair;
 exports.runRemoteStop = runRemoteStop;
@@ -706,6 +707,7 @@ async function runRemoteUp(options) {
     const pairingUrl = buildPairingUrl(handle.url, pairing.code);
     if (!options.json) {
         announcePairing(pairingUrl);
+        logger.info(formatPairingExpiryLine(state.pairing.expiresAt, now));
     }
     (0, security_logger_1.logSecurityEvent)({
         timestamp: new Date().toISOString(),
@@ -833,6 +835,20 @@ function formatRemaining(ms) {
         return `in ${minutes}m`;
     return `in ${hours}h ${minutes % 60}m`;
 }
+/**
+ * The human-facing pairing expiry line shared by `remote` and `remote pair`
+ * (Issue #3156): local clock time, time left, and the single-use reminder, so
+ * whoever hands the link on can say when it stops working.
+ *
+ * @param expiresAt - Epoch ms the pairing code dies at
+ * @param now - Epoch ms, injectable for tests
+ * @returns e.g. `Pairing expires: 14:16 (in 9m), works once (2026-10-04T05:16:00.000Z)`
+ */
+function formatPairingExpiryLine(expiresAt, now = Date.now()) {
+    const d = new Date(expiresAt);
+    const hhmm = `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+    return `Pairing expires: ${hhmm} (${formatRemaining(expiresAt - now)}), works once (${d.toISOString()})`;
+}
 /**
  * Close the outside door for a recorded session.
  *
@@ -1072,7 +1088,7 @@ async function runRemotePair(options) {
     }
     else {
         announcePairing(pairingUrl, true);
-        logger.info(`Pairing expires: ${expiresAt} (${formatRemaining(reissued.expiresAt - now)})`);
+        logger.info(formatPairingExpiryLine(reissued.expiresAt, now));
         logger.info(exports.PAIRING_LINK_NOTICE);
     }
     return types_1.ExitCode.SUCCESS;

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;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAMV,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAA+B,MAAM,qBAAqB,CAAC;AAwD7E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AA2WH;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AA2JlD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,6EAA6E;IAC7E,aAAa,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,CAAC,CA2gBD;AAwKD,wBAAgB,iBAAiB,IAAI,OAAO,CAqM3C"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAMV,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAA+B,MAAM,qBAAqB,CAAC;AA6E7E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AA2WH;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AA2JlD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,6EAA6E;IAC7E,aAAa,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD,CAAC,CAuiBD;AAwKD,wBAAgB,iBAAiB,IAAI,OAAO,CAqM3C"}

package/dist/cli/commands/wait.js

@@ -31,6 +31,7 @@ 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");
+const prompt_view_1 = require("../../lib/session/prompt-view");
 const instances_1 = require("./instances");
 /** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
 const POLL_INTERVAL_MS = 5000;
@@ -53,7 +54,24 @@ const SELECTION_LIST_PROMPT_TYPE = 'selection_list';
  * among them) keeps working and simply meets a kind it does not recognise,
  * whereas a new exit code reads as an infrastructure error to all of them.
  */
-const UNCLASSIFIED_PROMPT_TYPE = 'unclassified';
+//
+// Issue #3184: the value comes from `lib/session/prompt-view` rather than a copy
+// here — that module has no imports, so the CLI build compiles it.
+const UNCLASSIFIED_PROMPT_TYPE = prompt_view_1.UNCLASSIFIED_PROMPT_VIEW_TYPE;
+/**
+ * How the prompt reported on exit 10 is answered (Issue #3184): `screen` = the
+ * option number or y/n typed at the pane (`respond`), `api` = a decision
+ * delivered over the agent's own API (`respond <id> <number>`, no keys sent),
+ * `terminal` = nothing to offer, a human answers at the pane. Read off the
+ * shared view so `wait` and the browser cannot reach different conclusions.
+ */
+function waitAnswerVia(view) {
+    if (view?.kind === 'screen-choices')
+        return 'screen';
+    if (view?.kind === 'api-choices')
+        return 'api';
+    return 'terminal';
+}
 /**
  * Why `wait` decided the agent was done, printed on the completion line
  * (Issue #1839).
@@ -765,6 +783,17 @@ async function pollWorktree(client, worktreeId, options) {
             if (data.isRunning) {
                 everRunning = true;
             }
+            // Issue #3179: the agent is still launching. Work in progress, so keep
+            // polling: no prompt or selection list is read off the launch's frame,
+            // the unclassified dwell does not run, and a pane that does not exist yet
+            // is not "never started". `everRunning` is deliberately left alone — a
+            // launch that then fails leaves no session, which is NOT_STARTED, not a
+            // completion. The server bounds the launch, so this cannot hold forever.
+            if (typeof data.startingSince === 'number') {
+                unclassifiedSince = null;
+                await sleep(POLL_INTERVAL_MS);
+                continue;
+            }
             // Issue #1839: done before any exit path so the turn is adopted even on a
             // poll that ends in a prompt — the same turn is still open when the human
             // answers and `--on-prompt human` resumes polling.
@@ -837,9 +866,23 @@ async function pollWorktree(client, worktreeId, options) {
                 // an empty list there told the caller a dialog was open and gave it
                 // nothing to do about it, which is the whole of #1898-3 seen from the
                 // pipeline's side.
+                //
+                // Issue #3184: and a QUESTION answered by decision id (OpenCode V2,
+                // #2100) carries neither — its choices are `askUserQuestion.labels`,
+                // numbered by position. The panel offered them as buttons while this
+                // reported `[]`. Which of these applies is the shared view's call
+                // (`readPromptView`), not a third reading of the raw fields here.
+                const promptView = (0, prompt_view_1.readPromptView)(data);
                 const promptOptions = data.promptData.options?.length
                     ? data.promptData.options
-                    : (data.promptData.decisionOptions ?? []);
+                    : data.promptData.decisionOptions?.length
+                        ? data.promptData.decisionOptions
+                        : promptView?.apiTarget === 'question'
+                            ? promptView.choices.map((choice) => ({
+                                number: Number(choice.answer),
+                                label: choice.label,
+                            }))
+                            : [];
                 const promptOutput = {
                     worktreeId,
                     cliToolId: data.cliToolId || 'claude',
@@ -847,6 +890,7 @@ async function pollWorktree(client, worktreeId, options) {
                     question: data.promptData.question || '',
                     options: promptOptions,
                     status: data.promptData.status || 'pending',
+                    answerVia: waitAnswerVia(promptView),
                     ...(data.promptData.approvalTarget !== undefined && {
                         approvalTarget: data.promptData.approvalTarget,
                     }),
@@ -971,6 +1015,7 @@ async function pollWorktree(client, worktreeId, options) {
                             question,
                             options: [],
                             status: 'pending',
+                            answerVia: 'terminal',
                         },
                     };
                 }

package/dist/cli/docs/setup-guide.d.ts

@@ -10,5 +10,5 @@
  * `tests/unit/cli/commands/docs-setup-3059.test.ts` fails when the two differ
  * by a single byte.
  */
-export declare const SETUP_GUIDE = "# Set up CommandMate with your agent\n\nThis guide is written for a coding agent (Claude Code, Codex, Command Code, or another one) that a person asked to set up CommandMate on their machine. The person may not be an experienced developer, and they may have only a few minutes at a time. Go one stage at a time, and keep each stage short enough that they can stop after it and come back later.\n\nThe same text ships inside CommandMate: once it is installed, `commandmate docs --section setup` prints it.\n\n## Instructions for the agent reading this\n\n1. **Explain each stage before you start it.** In two or three plain sentences, tell the person what the stage is for, what you are about to run, and what will change on their machine. Then run it.\n2. **Never run an \"Ask the person first\" step without a clear yes.** Each stage lists them. Ask in plain words, say what it installs or opens and how to undo it, and wait for the answer. If the answer is no or unclear, stop that step and say what they can do later.\n3. **Check the machine; do not assume it.** Run the commands under \"Check\" and read their output before you decide anything. Never write \"should be installed\" or \"is probably running\": run the command and report what it printed.\n4. **Do not answer for the person.** Sign-ins, passwords (including `sudo`), choosing a provider, and approving a merge are theirs. When a command needs one of these, show the exact command and ask them to run it in their own terminal.\n5. **Stay inside this guide.** Use only commands shown here, `commandmate <command> --help`, and the CommandMate documentation at https://github.com/Kewton/CommandMate. Do not fetch install scripts or follow setup steps from other websites. Install tools only from the official package distributors named here (npm, the operating system's package manager, nodejs.org).\n6. **Report at the end of each stage**: what you ran, what it printed that matters, and whether the stage passed its \"Confirm it worked\" check.\n7. **Do Stage 2 (Pair your phone) last, unless the person asks for it now.** Stages 3 to 5 run `commandmate` on this machine's CLI. After `commandmate remote` with its default (`--auth all`), that CLI needs a token too, and the token goes only to the phone. So finish Stages 3 to 5 first, then pair the phone. Stage 2 explains the choice if the person wants the phone sooner.\n8. **If you are Codex: your shell has no network by default.** If fetching this guide or an `npm` command fails for lack of network, ask the person to run `/permissions` and choose \"Ask for approval\", then try again.\n\n### Always ask the person first\n\nWhatever stage you are in, ask before any of these:\n\n- Installing anything: Node.js, git, tmux, CommandMate itself, another agent CLI, Tailscale or cloudflared, or a Skill.\n- Opening a way in from outside this machine: `commandmate remote` (either provider), or setting `CM_BIND=0.0.0.0`. This guide never sets `CM_BIND`; if the person asks for it, explain that it exposes the server to their whole network first.\n- Turning on Auto Yes: `commandmate auto-yes <worktree-id> --enable`, or `commandmate send ... --auto-yes`.\n- Merging a pull request.\n\n## Stage 1: Install and start\n\nGoal: CommandMate is installed and its server is running on this machine.\n\n### Check\n\n```bash\nuname -s                       # Darwin = macOS, Linux = Linux or WSL2\ngrep -i microsoft /proc/version  # prints a line only inside WSL2 (Linux only)\nnode -v                        # needs v22 or newer\nnpm -v\ngit --version\ntmux -V\ncommand -v brew                # macOS: is Homebrew present?\ncommand -v commandmate && commandmate --version\n```\n\nWrite down which of these are missing or too old. Native Windows is not supported; on Windows, CommandMate runs inside WSL2 (see https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/wsl2-setup.md).\n\n### Run\n\nInstall only what the check found missing, after the person agrees.\n\n- **macOS with Homebrew**: `brew install node git tmux` (leave out what is already there).\n- **macOS without Homebrew**: tmux needs a package manager. Tell the person that, and let them decide whether to install Homebrew from its own official instructions. Do not install it for them. git alone can come from Apple's tools: `xcode-select --install`.\n- **Linux / WSL2 (Debian or Ubuntu)**: `sudo apt update && sudo apt install -y git tmux`. The `sudo` password is the person's to type. If `node -v` is missing or older than v22, the distribution's package is usually too old: tell the person and use the official Node.js download (https://nodejs.org/en/download) in the way they choose.\n\nThen install and start CommandMate:\n\n```bash\nnpm install -g commandmate     # the global install: for daily use\ncommandmate --version\ncommandmate init --defaults    # writes ~/.commandmate/.env; repositories go under ~/repos\ncommandmate start --daemon\n```\n\n**`npx commandmate@latest` versus the global install.** `npx commandmate@latest` is the one-line way for a person to try CommandMate in their own terminal: it asks its setup questions and opens the browser. It needs an interactive terminal, so when you run it from your tool it only prints help. Use the global install above when you are the one running the commands, and for anything the person will keep using.\n\n### Ask the person first\n\n- Each tool you are about to install (Node.js, git, tmux), and the exact command.\n- `npm install -g commandmate`.\n- If `~/.commandmate/.env` already exists, `commandmate init --defaults` stops with \".env file already exists\": CommandMate is already configured, so skip `init`. Do not add `--force` without asking: it replaces their settings.\n\n### Confirm it worked\n\n```bash\ncommandmate status             # reports the server as running, with its URL\n```\n\nTell the person to open the URL it prints (by default http://localhost:3000) in their browser.\n\n### If it fails\n\n- `commandmate: command not found` after `npm install -g`: npm's global bin directory is not on `PATH`. Run `npm prefix -g` and show the person; the fix is in https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-setup-guide.md#command-not-found-error.\n- `EACCES` during `npm install -g`: do not retry with `sudo`. Show the person the \"Permission Error (EACCES)\" section of the same setup guide.\n- The port is already in use: `commandmate start --daemon --port 3001`, then `commandmate status`.\n- The server does not start: `commandmate status`, then `commandmate stop --force` and `commandmate start --daemon` again. Read what it prints rather than retrying blindly.\n\n## Stage 2: Pair your phone\n\nGoal: the person scans a QR code with their phone and sees CommandMate there.\n\n`commandmate remote` makes this server reachable from outside the machine through a provider, and prints a QR code that pairs one phone. There are two providers, and **the person chooses which one**:\n\n| | Tailscale (`--provider tailscale`) | Cloudflare (`--provider cloudflare`) |\n|---|---|---|\n| Who can reach it | Only devices signed in to the person's own Tailscale network (tailnet) | Anyone with the URL: it is a public address on the internet |\n| What protects it | The tailnet, plus CommandMate's token login | A one-time pairing code (single use, expires in 10 minutes by default), plus CommandMate's token login |\n| Needs | The Tailscale app on this machine and on the phone, both signed in to the same account, with HTTPS (Serve) available | `cloudflared` installed on this machine; no account |\n| Approval | No public-tunnel approval | A public tunnel: `--yes` only after the person agrees |\n\nExplain both in plain words and ask which one they want. If they cannot decide, Tailscale keeps the server off the public internet; Cloudflare needs fewer accounts.\n\n**When to do this stage.** By default (`--auth all`), once `commandmate remote` runs, the `commandmate` CLI on this machine also needs a token, and the token goes only to the phone. Stages 3 to 5 run on that CLI, so they stop working. Ask the person which they want:\n\n- **Pair the phone last (recommended).** Skip to Stage 3 now, and come back to this stage after Stage 5.\n- **Pair the phone now, and keep the CLI on this machine.** Add `--auth remote-only` to the `commandmate remote` command below. Only the phone's route then needs the token: every process on this machine, agents included, can operate CommandMate without logging in. Say that plainly before they choose it.\n\n### Check\n\n```bash\ncommandmate status             # is the server running, and with authentication?\ncommandmate remote status      # is a remote session already recorded?\ntailscale status               # Tailscale: installed and signed in?\ncloudflared --version          # Cloudflare: installed?\n```\n\n### Run\n\n1. Install the chosen provider if the check found it missing, after the person agrees:\n   - **Cloudflare**: on macOS `brew install cloudflared`; on Linux, from Cloudflare's official package repository for their distribution.\n   - **Tailscale**: the person installs the Tailscale app from Tailscale's official distribution on this machine and on their phone, and signs in themselves. Signing in is theirs to do.\n2. If `commandmate status` showed the server running, stop it first, so `remote` can start it again with authentication: `commandmate stop`.\n3. Publish and pair:\n\n```bash\ncommandmate remote --provider tailscale\n# or, only after the person agreed to a public URL:\ncommandmate remote --provider cloudflare --yes\n```\n\n`remote` starts the server itself, publishes it, and prints the QR code. Show the person the QR code and tell them to scan it with the phone's camera. If the output is too narrow for a QR code, it prints a URL instead: that URL contains the pairing code, so give it only to the person and do not save it to a file or a log.\n\nIf the QR code cannot be read, or scanning it does not get the person in, have them copy the pairing URL and paste it into the address bar of the phone's browser. Pasting the link into the address bar is the way that worked in the hands-on check; do not save the link to a file.\n\nTo get the link as text again without reopening the tunnel, run `commandmate remote pair` (or `commandmate remote pair --json` and read `pairingUrl`). The URL stays the same, and it works only while the code is unused.\n\n### Ask the person first\n\n- Which provider: Tailscale or Cloudflare.\n- Installing that provider.\n- Running `commandmate remote` at all: it opens a way in from outside this machine.\n- Pairing now or after Stage 5, and, if now, whether to add `--auth remote-only`.\n- `--yes`: only after they agreed to the public Cloudflare URL. Never add `--yes` to get past a question they have not answered.\n\n### Confirm it worked\n\n- The person says the phone opened CommandMate.\n- `commandmate remote status` shows `Pairing: consumed`.\n\nTo close the way in later: `commandmate remote stop`. The server keeps running.\n\n### If it fails\n\n- Exit 1, \"no provider is usable\": read the reason it prints. For Tailscale it is usually \"not connected\" (the person has not signed in) or \"no MagicDNS name\". Do not switch to Cloudflare without asking: that changes who can reach the machine.\n- Exit 2 without a terminal: Cloudflare needs `--yes`, or a server is running that `remote` has to restart. Ask the person, then run `commandmate stop` and try again.\n- Exit 2, \"a server with authentication is already running\": `commandmate stop`, then `commandmate remote` again.\n- The QR code is cut off in the agent's chat pane, or the person lost it, and it has not been used yet: run `commandmate remote pair`. The public URL stays the same and the earlier link stops working. The new code keeps the original expiry time.\n- The code expired or was already used: run `commandmate remote stop`, then `commandmate remote` again for a new QR code (`remote pair` prints nothing for a used or expired code). `--pairing-expires 30m` gives a slower person more time.\n- After pairing, the browser on this machine asks for a login and the CLI stops answering: that is the default `--auth all`. Do not look for a way to give the token to the CLI. Ask the person to choose: run `commandmate remote stop` and finish Stages 3 to 5 on this machine first, or pair again with `--auth remote-only` (every process on this machine can then operate CommandMate without logging in).\n\n## Stage 3: Add a second agent\n\nGoal: a second agent CLI, for example Command Code or Codex, can work in one of the person's repositories through CommandMate.\n\nBefore Stages 3 to 5: CommandMate needs at least one of the person's repositories registered. The CLI cannot register one; the person does it in the browser, under **Repositories \u2192 Add Repository**.\n\n### Check\n\n```bash\nclaude --version\ncodex --version\ncommandcode --version          # Command Code\ncommandmate ls                 # the worktrees CommandMate knows about\n```\n\nIf `commandmate ls` lists nothing, the person has not registered a repository yet. CommandMate only manages repositories under `~/repos` (the `CM_ROOT_DIR` that `init` set). Ask the person to open **Repositories \u2192 Add Repository** in the browser and add one, or to tell you where their repository is so you can check whether it is under that directory. Then run `commandmate sync` and `commandmate ls` again.\n\n### Run\n\nInstall the CLI the person picked, after they agree:\n\n```bash\nnpm install -g command-code    # Command Code; CommandMate runs it as `commandcode`\nnpm install -g @openai/codex   # Codex\n```\n\nSigning in to the CLI is the person's: ask them to run `commandcode` (or `codex`) once in their own terminal and finish its sign-in. Then add it to a worktree and give it a first, small message:\n\n```bash\ncommandmate instances <worktree-id> add --agent command-code\ncommandmate instances <worktree-id>\ncommandmate send <worktree-id> \"Read the README and summarize this repository in three lines.\" --instance command-code\ncommandmate wait <worktree-id> --instance command-code --timeout 600\ncommandmate reply <worktree-id> --instance command-code\n```\n\nFor Codex, use `--agent codex` and `--instance codex`.\n\nThe first time Codex starts in a worktree it shows two confirmation screens. Show them to the person with `commandmate capture <worktree-id> --instance codex`; do not answer them yourself.\n\n- `Trust this folder?`: whether Codex may work in this folder.\n- `Hooks need review (5 hooks are new or changed)`: these hooks are not from the repository. CommandMate wrote them into `~/.codex/hooks.json` itself, marked with `# commandmate:agent-hooks`, and they only send Codex's events to CommandMate on localhost. Check this with `grep -n 'commandmate:agent-hooks' ~/.codex/hooks.json` before you say where they came from. If the person does not trust them, Codex still works, but CommandMate cannot receive Codex's state as events, so `wait` and the status shown in the browser are less accurate.\n\n### Ask the person first\n\n- Which CLI to add, and installing it.\n- The sign-in, which they do themselves.\n- Do not turn on Auto Yes (`--auto-yes`, `commandmate auto-yes --enable`) to get past the CLI's own confirmations. If it stops on a question, show the person with `commandmate capture <worktree-id> --instance command-code` and let them answer.\n\n### Confirm it worked\n\n- `commandmate instances <worktree-id>` lists the new instance.\n- `commandmate reply <worktree-id> --instance command-code` prints its answer.\n\n### If it fails\n\n- \"is not installed or not in PATH\": the message names the install command. Run `commandcode --version` to check, and ask before installing.\n- `wait` exits 10: the agent is waiting on a question (often its own sign-in or a permission). Show the person `commandmate capture <worktree-id> --instance command-code`.\n- `wait` exits 124: it timed out. Check `commandmate capture` before waiting again.\n- \"Worktree ID not found\": run `commandmate sync`, then `commandmate ls`, and copy the ID exactly.\n\n## Stage 4: Give your team a PM\n\nGoal: one session plans the work and hands tasks to the others. That session is the lead (the \"PM\"). Skills from CommandMate's official Catalog teach it the method.\n\n### Check\n\n```bash\ncommandmate skill list                                         # what the Catalog offers\ncommandmate skill info cmate-orchestrate                       # versions, risk, compatibility\ncommandmate skill status cmate-orchestrate --worktree <worktree-id>\n```\n\n### Run\n\nPick the exact version from `skill info`, show the person the plan, and install after they agree:\n\n```bash\ncommandmate skill install cmate-orchestrate --worktree <worktree-id> --version <version> --dry-run\ncommandmate skill install cmate-orchestrate --worktree <worktree-id> --version <version> --yes --ack-risk cmate-orchestrate@<version>\n```\n\n`cmate-orchestrate` is a high-risk Skill: it needs `--ack-risk <skill-id>@<version>` in addition to `--yes`. A Skill that is not high-risk needs only `--yes`. The Skill lands in `.agents/skills/` and `.claude/skills/` of that worktree.\n\nAn agent reads its Skills when its session starts, so the lead session has to start again. Ask the person whether to restart it from the worktree screen; if they prefer the CLI, `commandmate instances <worktree-id> kill <instance-id>` stops it and the next `commandmate send` starts it again.\n\nThen ask the lead in plain words. For example, sent to the lead session (in Claude Code the Skill is also available as `/cmate-orchestrate`):\n\n```bash\ncommandmate send <worktree-id> \"Use the cmate-orchestrate skill to plan issues #12 and #13. Show me the plan; do not run anything that changes the repository yet.\" --instance claude\n```\n\nThe plan step changes nothing. Steps that change something run only when the person approves them.\n\nCommand Code's plan mode (Command Code only; this workaround can be removed once #3125 is fixed): if the lead enters plan mode, it stops on a REVIEW screen and CommandMate cannot send a comment to it from the CLI. When you only want a plan, ask in plain words as above and do not have the lead enter plan mode.\n\n### Ask the person first\n\n- Installing each Skill, after showing the `--dry-run` plan. Say plainly that `cmate-orchestrate` is marked high-risk and what `--ack-risk` acknowledges.\n- Restarting the lead session.\n- Every approval the lead asks for, and every merge. You never approve or merge on the person's behalf.\n\n### Confirm it worked\n\n- `commandmate skill status cmate-orchestrate --worktree <worktree-id>` reports it as installed.\n- The lead's reply (`commandmate reply <worktree-id> --instance claude`) shows a plan.\n\n### If it fails\n\n- `skill install` exits 2: `--version` is missing or does not exist. Copy it from `skill info`.\n- Exit 12: the install was not confirmed: no `--yes`, or a high-risk Skill without `--ack-risk`. Ask again rather than adding flags on your own.\n- Exit 11: the worktree has local changes in the way. Show the person `git status` in that worktree.\n- Exit 1: the server or the Catalog could not be reached. Check `commandmate status`.\n- The agent does not know the Skill: its session started before the install. Restart it.\n\n## Stage 5: Let checks decide what's done\n\nGoal: \"done\" means the repository's own checks passed, not that an agent said so.\n\n### Check\n\n```bash\nls .commandmate/verify.yaml                    # in the repository: are gates declared?\ncommandmate skill status cmate-verify --worktree <worktree-id>\n```\n\n### Run\n\n1. Declare the gates. Either install the `cmate-verify` Skill (as in Stage 4, after the person agrees) and ask the lead to write `.commandmate/verify.yaml` with it, or draft it from the repository's CI definitions:\n\n```bash\ncommandmate verify init --cwd <repository-path> --dry-run   # print the draft, write nothing\ncommandmate verify init --cwd <repository-path>             # write it (never overwrites)\n```\n\nShow the person the gates (lint, type check, tests and so on) and change them only with their agreement.\n\nBefore handing over a task that commits, check that git knows who is committing: `git config user.name` and `git config user.email` in the repository (a worker's commit fails when they are empty). If they are empty, ask the person for their name and email, and set them only with their answer. Do not let a worker invent a bot name. The person may also choose to have the worker leave the changes uncommitted.\n\n2. Run the gates once on the worktree as it is:\n\n```bash\ncommandmate verify <worktree-id>\n```\n\n3. Hand a task over under a contract, and let the gates judge it. A contract is a YAML file in the repository, `.commandmate/tasks/<name>.yaml`, that states the goal, the files the agent may change, and the checks that decide when it is done:\n\n```yaml\nversion: 1\ntitle: \"Issue #12: <one-line summary>\"\ngoal: |\n  Implement issue #12. Commit when the work is done.\nscope:\n  allow:\n    - \"src/**\"\n    - \"tests/**\"\nverify:\n  gates: [lint, unit]        # gate ids from .commandmate/verify.yaml\nsuccess:\n  requireWorkEvidence: true\n  requireScopeClean: true\n```\n\n```bash\ncommandmate send <worktree-id> --contract .commandmate/tasks/issue-12.yaml --instance command-code\ncommandmate wait <worktree-id> --instance command-code --verify\n```\n\n`wait --verify` exits **0** when every gate passed, **20** when a gate failed, and **21** when there is no work to judge (no commits and no changes).\n\n### Ask the person first\n\n- Installing `cmate-verify`, and writing `.commandmate/verify.yaml` into their repository.\n- Which gates to declare, and any later change to them.\n- Merging the result. A passed gate means the checks passed; whether to merge is still the person's decision.\n\n### Confirm it worked\n\n- `commandmate verify <worktree-id>` ends with exit 0, or with a gate failure the person recognizes as real.\n- `commandmate verify history` lists the run.\n\n### If it fails\n\n- `verify` exits 21 right away: the worktree has no work yet. That is expected before a task.\n- Exit 20: a gate failed. `commandmate verify show <run-id>` shows which one and the end of its log. Report it; do not weaken the gate to make it pass.\n- The contract is rejected (exit 2): it prints every problem, for example a gate id that is not in `verify.yaml`. Fix the contract, not the gates.\n\n## Where to read more\n\n- CommandMate on GitHub: https://github.com/Kewton/CommandMate\n- CLI operations guide, every flag and exit code: https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-operations-guide.md\n- The project site: https://kewton.github.io/CommandMate/\n";
+export declare const SETUP_GUIDE = "# Set up CommandMate with your agent\n\nThis guide is written for a coding agent (Claude Code, Codex, Command Code, or another one) that a person asked to set up CommandMate on their machine. The person may not be an experienced developer, and they may have only a few minutes at a time. Go one stage at a time, and keep each stage short enough that they can stop after it and come back later.\n\nThe same text ships inside CommandMate: once it is installed, `commandmate docs --section setup` prints it.\n\n## Instructions for the agent reading this\n\n1. **Explain each stage before you start it.** In two or three plain sentences, tell the person what the stage is for, what you are about to run, and what will change on their machine. Then run it.\n2. **Never run an \"Ask the person first\" step without a clear yes.** Each stage lists them. Ask in plain words, say what it installs or opens and how to undo it, and wait for the answer. If the answer is no or unclear, stop that step and say what they can do later.\n3. **Check the machine; do not assume it.** Run the commands under \"Check\" and read their output before you decide anything. Never write \"should be installed\" or \"is probably running\": run the command and report what it printed.\n4. **Do not answer for the person.** Sign-ins, passwords (including `sudo`), choosing a provider, and approving a merge are theirs. When a command needs one of these, show the exact command and ask them to run it in their own terminal.\n5. **Stay inside this guide.** Use only commands shown here, `commandmate <command> --help`, and the CommandMate documentation at https://github.com/Kewton/CommandMate. Do not fetch install scripts or follow setup steps from other websites. Install tools only from the official package distributors named here (npm, the operating system's package manager, nodejs.org).\n6. **Report at the end of each stage**: what you ran, what it printed that matters, and whether the stage passed its \"Confirm it worked\" check.\n7. **Do Stage 2 (Pair your phone) last, unless the person asks for it now.** Stages 3 to 5 run `commandmate` on this machine's CLI. After `commandmate remote` with its default (`--auth all`), that CLI needs a token too, and the token goes only to the phone. So finish Stages 3 to 5 first, then pair the phone. Stage 2 explains the choice if the person wants the phone sooner.\n8. **If you are Codex: your shell has no network by default.** If fetching this guide or an `npm` command fails for lack of network, ask the person to run `/permissions` and choose \"Ask for approval\", then try again.\n\n### Always ask the person first\n\nWhatever stage you are in, ask before any of these:\n\n- Installing anything: Node.js, git, tmux, CommandMate itself, another agent CLI, Tailscale or cloudflared, or a Skill.\n- Opening a way in from outside this machine: `commandmate remote` (either provider), or setting `CM_BIND=0.0.0.0`. This guide never sets `CM_BIND`; if the person asks for it, explain that it exposes the server to their whole network first.\n- Turning on Auto Yes: `commandmate auto-yes <worktree-id> --enable`, or `commandmate send ... --auto-yes`.\n- Merging a pull request.\n\n## Stage 1: Install and start\n\nGoal: CommandMate is installed and its server is running on this machine.\n\n### Check\n\n```bash\nuname -s                       # Darwin = macOS, Linux = Linux or WSL2\ngrep -i microsoft /proc/version  # prints a line only inside WSL2 (Linux only)\nnode -v                        # needs v22 or newer\nnpm -v\ngit --version\ntmux -V\ncommand -v brew                # macOS: is Homebrew present?\ncommand -v commandmate && commandmate --version\n```\n\nWrite down which of these are missing or too old. Native Windows is not supported; on Windows, CommandMate runs inside WSL2 (see https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/wsl2-setup.md).\n\n### Run\n\nInstall only what the check found missing, after the person agrees.\n\n- **macOS with Homebrew**: `brew install node git tmux` (leave out what is already there).\n- **macOS without Homebrew**: tmux needs a package manager. Tell the person that, and let them decide whether to install Homebrew from its own official instructions. Do not install it for them. git alone can come from Apple's tools: `xcode-select --install`.\n- **Linux / WSL2 (Debian or Ubuntu)**: `sudo apt update && sudo apt install -y git tmux`. The `sudo` password is the person's to type. If `node -v` is missing or older than v22, the distribution's package is usually too old: tell the person and use the official Node.js download (https://nodejs.org/en/download) in the way they choose.\n\nThen install and start CommandMate:\n\n```bash\nnpm install -g commandmate     # the global install: for daily use\ncommandmate --version\ncommandmate init --defaults    # writes ~/.commandmate/.env; repositories go under ~/repos\ncommandmate start --daemon\n```\n\n**`npx commandmate@latest` versus the global install.** `npx commandmate@latest` is the one-line way for a person to try CommandMate in their own terminal: it asks its setup questions and opens the browser. It needs an interactive terminal, so when you run it from your tool it only prints help. Use the global install above when you are the one running the commands, and for anything the person will keep using.\n\n### Ask the person first\n\n- Each tool you are about to install (Node.js, git, tmux), and the exact command.\n- `npm install -g commandmate`.\n- If `~/.commandmate/.env` already exists, `commandmate init --defaults` stops with \".env file already exists\": CommandMate is already configured, so skip `init`. Do not add `--force` without asking: it replaces their settings.\n\n### Confirm it worked\n\n```bash\ncommandmate status             # reports the server as running, with its URL\n```\n\nTell the person to open the URL it prints (by default http://localhost:3000) in their browser.\n\n### If it fails\n\n- `commandmate: command not found` after `npm install -g`: npm's global bin directory is not on `PATH`. Run `npm prefix -g` and show the person; the fix is in https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-setup-guide.md#command-not-found-error.\n- `EACCES` during `npm install -g`: do not retry with `sudo`. Show the person the \"Permission Error (EACCES)\" section of the same setup guide.\n- The port is already in use: `commandmate start --daemon --port 3001`, then `commandmate status`.\n- The server does not start: `commandmate status`, then `commandmate stop --force` and `commandmate start --daemon` again. Read what it prints rather than retrying blindly.\n\n## Stage 2: Pair your phone\n\nGoal: the person scans a QR code with their phone and sees CommandMate there.\n\n`commandmate remote` makes this server reachable from outside the machine through a provider, and prints a QR code that pairs one phone. There are two providers, and **the person chooses which one**:\n\n| | Tailscale (`--provider tailscale`) | Cloudflare (`--provider cloudflare`) |\n|---|---|---|\n| Who can reach it | Only devices signed in to the person's own Tailscale network (tailnet) | Anyone with the URL: it is a public address on the internet |\n| What protects it | The tailnet, plus CommandMate's token login | A one-time pairing code (single use, expires in 10 minutes by default), plus CommandMate's token login |\n| Needs | The Tailscale app on this machine and on the phone, both signed in to the same account, with HTTPS (Serve) available | `cloudflared` installed on this machine; no account |\n| Approval | No public-tunnel approval | A public tunnel: `--yes` only after the person agrees |\n\nExplain both in plain words and ask which one they want. If they cannot decide, Tailscale keeps the server off the public internet; Cloudflare needs fewer accounts.\n\n**When to do this stage.** By default (`--auth all`), once `commandmate remote` runs, the `commandmate` CLI on this machine also needs a token, and the token goes only to the phone. Stages 3 to 5 run on that CLI, so they stop working. Ask the person which they want:\n\n- **Pair the phone last (recommended).** Skip to Stage 3 now, and come back to this stage after Stage 5.\n- **Pair the phone now, and keep the CLI on this machine.** Add `--auth remote-only` to the `commandmate remote` command below. Only the phone's route then needs the token: every process on this machine, agents included, can operate CommandMate without logging in. Say that plainly before they choose it.\n\n### Check\n\n```bash\ncommandmate status             # is the server running, and with authentication?\ncommandmate remote status      # is a remote session already recorded?\ntailscale status               # Tailscale: installed and signed in?\ncloudflared --version          # Cloudflare: installed?\n```\n\n### Run\n\n1. Install the chosen provider if the check found it missing, after the person agrees:\n   - **Cloudflare**: on macOS `brew install cloudflared`; on Linux, from Cloudflare's official package repository for their distribution.\n   - **Tailscale**: the person installs the Tailscale app from Tailscale's official distribution on this machine and on their phone, and signs in themselves. Signing in is theirs to do.\n2. If `commandmate status` showed the server running, stop it first, so `remote` can start it again with authentication: `commandmate stop`.\n3. Publish and pair:\n\n```bash\ncommandmate remote --provider tailscale\n# or, only after the person agreed to a public URL:\ncommandmate remote --provider cloudflare --yes\n```\n\n`remote` starts the server itself, publishes it, and prints the QR code. Show the person the QR code and tell them to scan it with the phone's camera. If the output is too narrow for a QR code, it prints a URL instead: that URL contains the pairing code, so give it only to the person and do not save it to a file or a log.\n\nIf the QR code cannot be read, or scanning it does not get the person in, have them copy the pairing URL and paste it into the address bar of the phone's browser. Pasting the link into the address bar is the way that worked in the hands-on check; do not save the link to a file.\n\nWhen you hand the link or QR to the person, also tell them the time it expires: `remote` and `remote pair` print a `Pairing expires: HH:MM (in N m), works once` line, and `pairing.expiresAt` in `--json` is the same time. If it has passed, run `commandmate remote pair` (only works while the code is unused), otherwise `commandmate remote stop` and then `commandmate remote`.\n\nTo get the link as text again without reopening the tunnel, run `commandmate remote pair` (or `commandmate remote pair --json` and read `pairingUrl`). The URL stays the same, and it works only while the code is unused.\n\n### Ask the person first\n\n- Which provider: Tailscale or Cloudflare.\n- Installing that provider.\n- Running `commandmate remote` at all: it opens a way in from outside this machine.\n- Pairing now or after Stage 5, and, if now, whether to add `--auth remote-only`.\n- `--yes`: only after they agreed to the public Cloudflare URL. Never add `--yes` to get past a question they have not answered.\n\n### Confirm it worked\n\n- The person says the phone opened CommandMate.\n- `commandmate remote status` shows `Pairing: consumed`.\n\nTo close the way in later: `commandmate remote stop`. The server keeps running.\n\n### If it fails\n\n- Exit 1, \"no provider is usable\": read the reason it prints. For Tailscale it is usually \"not connected\" (the person has not signed in) or \"no MagicDNS name\". Do not switch to Cloudflare without asking: that changes who can reach the machine.\n- Exit 2 without a terminal: Cloudflare needs `--yes`, or a server is running that `remote` has to restart. Ask the person, then run `commandmate stop` and try again.\n- Exit 2, \"a server with authentication is already running\": `commandmate stop`, then `commandmate remote` again.\n- The QR code is cut off in the agent's chat pane, or the person lost it, and it has not been used yet: run `commandmate remote pair`. The public URL stays the same and the earlier link stops working. The new code keeps the original expiry time.\n- The code expired or was already used: run `commandmate remote stop`, then `commandmate remote` again for a new QR code (`remote pair` prints nothing for a used or expired code). `--pairing-expires 30m` gives a slower person more time.\n- After pairing, the browser on this machine asks for a login and the CLI stops answering: that is the default `--auth all`. Do not look for a way to give the token to the CLI. Ask the person to choose: run `commandmate remote stop` and finish Stages 3 to 5 on this machine first, or pair again with `--auth remote-only` (every process on this machine can then operate CommandMate without logging in).\n\n## Stage 3: Add a second agent\n\nGoal: a second agent CLI, for example Command Code or Codex, can work in one of the person's repositories through CommandMate.\n\nBefore Stages 3 to 5: CommandMate needs at least one of the person's repositories registered. The CLI cannot register one; the person does it in the browser, under **Repositories \u2192 Add Repository**.\n\n### Check\n\n```bash\nclaude --version\ncodex --version\ncommandcode --version          # Command Code\ncommandmate ls                 # the worktrees CommandMate knows about\n```\n\nIf `commandmate ls` lists nothing, the person has not registered a repository yet. CommandMate only manages repositories under `~/repos` (the `CM_ROOT_DIR` that `init` set). Ask the person to open **Repositories \u2192 Add Repository** in the browser and add one, or to tell you where their repository is so you can check whether it is under that directory. Then run `commandmate sync` and `commandmate ls` again.\n\n### Run\n\nInstall the CLI the person picked, after they agree:\n\n```bash\nnpm install -g command-code    # Command Code; CommandMate runs it as `commandcode`\nnpm install -g @openai/codex   # Codex\n```\n\nSigning in to the CLI is the person's: ask them to run `commandcode` (or `codex`) once in their own terminal and finish its sign-in. Then add it to a worktree and give it a first, small message:\n\n```bash\ncommandmate instances <worktree-id> add --agent command-code\ncommandmate instances <worktree-id>\ncommandmate send <worktree-id> \"Read the README and summarize this repository in three lines.\" --instance command-code\ncommandmate wait <worktree-id> --instance command-code --timeout 600\ncommandmate reply <worktree-id> --instance command-code\n```\n\nFor Codex, use `--agent codex` and `--instance codex`.\n\nThe first time Codex starts in a worktree it shows two confirmation screens. Show them to the person with `commandmate capture <worktree-id> --instance codex`; do not answer them yourself.\n\n- `Trust this folder?`: whether Codex may work in this folder.\n- `Hooks need review (5 hooks are new or changed)`: these hooks are not from the repository. CommandMate wrote them into `~/.codex/hooks.json` itself, marked with `# commandmate:agent-hooks`, and they only send Codex's events to CommandMate on localhost. Check this with `grep -n 'commandmate:agent-hooks' ~/.codex/hooks.json` before you say where they came from. If the person does not trust them, Codex still works, but CommandMate cannot receive Codex's state as events, so `wait` and the status shown in the browser are less accurate.\n\n### Ask the person first\n\n- Which CLI to add, and installing it.\n- The sign-in, which they do themselves.\n- Do not turn on Auto Yes (`--auto-yes`, `commandmate auto-yes --enable`) to get past the CLI's own confirmations. If it stops on a question, show the person with `commandmate capture <worktree-id> --instance command-code` and let them answer.\n\n### Confirm it worked\n\n- `commandmate instances <worktree-id>` lists the new instance.\n- `commandmate reply <worktree-id> --instance command-code` prints its answer.\n\n### If it fails\n\n- \"is not installed or not in PATH\": the message names the install command. Run `commandcode --version` to check, and ask before installing.\n- `wait` exits 10: the agent is waiting on a question (often its own sign-in or a permission). Show the person `commandmate capture <worktree-id> --instance command-code`.\n- `wait` exits 124: it timed out. Check `commandmate capture` before waiting again.\n- \"Worktree ID not found\": run `commandmate sync`, then `commandmate ls`, and copy the ID exactly.\n\n## Stage 4: Give your team a PM\n\nGoal: one session plans the work and hands tasks to the others. That session is the lead (the \"PM\"). Skills from CommandMate's official Catalog teach it the method.\n\n### Check\n\n```bash\ncommandmate skill list                                         # what the Catalog offers\ncommandmate skill info cmate-orchestrate                       # versions, risk, compatibility\ncommandmate skill status cmate-orchestrate --worktree <worktree-id>\n```\n\n### Run\n\nPick the exact version from `skill info`, show the person the plan, and install after they agree:\n\n```bash\ncommandmate skill install cmate-orchestrate --worktree <worktree-id> --version <version> --dry-run\ncommandmate skill install cmate-orchestrate --worktree <worktree-id> --version <version> --yes --ack-risk cmate-orchestrate@<version>\n```\n\n`cmate-orchestrate` is a high-risk Skill: it needs `--ack-risk <skill-id>@<version>` in addition to `--yes`. A Skill that is not high-risk needs only `--yes`. The Skill lands in `.agents/skills/` and `.claude/skills/` of that worktree.\n\nAn agent reads its Skills when its session starts, so the lead session has to start again. Ask the person whether to restart it from the worktree screen; if they prefer the CLI, `commandmate instances <worktree-id> kill <instance-id>` stops it and the next `commandmate send` starts it again.\n\nThen ask the lead in plain words. For example, sent to the lead session (in Claude Code the Skill is also available as `/cmate-orchestrate`):\n\n```bash\ncommandmate send <worktree-id> \"Use the cmate-orchestrate skill to plan issues #12 and #13. Show me the plan; do not run anything that changes the repository yet.\" --instance claude\n```\n\nThe plan step changes nothing. Steps that change something run only when the person approves them.\n\nCommand Code's plan mode (Command Code only; this workaround can be removed once #3125 is fixed): if the lead enters plan mode, it stops on a REVIEW screen and CommandMate cannot send a comment to it from the CLI. When you only want a plan, ask in plain words as above and do not have the lead enter plan mode.\n\n### Ask the person first\n\n- Installing each Skill, after showing the `--dry-run` plan. Say plainly that `cmate-orchestrate` is marked high-risk and what `--ack-risk` acknowledges.\n- Restarting the lead session.\n- Every approval the lead asks for, and every merge. You never approve or merge on the person's behalf.\n\n### Confirm it worked\n\n- `commandmate skill status cmate-orchestrate --worktree <worktree-id>` reports it as installed.\n- The lead's reply (`commandmate reply <worktree-id> --instance claude`) shows a plan.\n\n### If it fails\n\n- `skill install` exits 2: `--version` is missing or does not exist. Copy it from `skill info`.\n- Exit 12: the install was not confirmed: no `--yes`, or a high-risk Skill without `--ack-risk`. Ask again rather than adding flags on your own.\n- Exit 11: the worktree has local changes in the way. Show the person `git status` in that worktree.\n- Exit 1: the server or the Catalog could not be reached. Check `commandmate status`.\n- The agent does not know the Skill: its session started before the install. Restart it.\n\n## Stage 5: Let checks decide what's done\n\nGoal: \"done\" means the repository's own checks passed, not that an agent said so.\n\n### Check\n\n```bash\nls .commandmate/verify.yaml                    # in the repository: are gates declared?\ncommandmate skill status cmate-verify --worktree <worktree-id>\n```\n\n### Run\n\n1. Declare the gates. Either install the `cmate-verify` Skill (as in Stage 4, after the person agrees) and ask the lead to write `.commandmate/verify.yaml` with it, or draft it from the repository's CI definitions:\n\n```bash\ncommandmate verify init --cwd <repository-path> --dry-run   # print the draft, write nothing\ncommandmate verify init --cwd <repository-path>             # write it (never overwrites)\n```\n\nShow the person the gates (lint, type check, tests and so on) and change them only with their agreement.\n\nBefore handing over a task that commits, check that git knows who is committing: `git config user.name` and `git config user.email` in the repository (a worker's commit fails when they are empty). If they are empty, ask the person for their name and email, and set them only with their answer. Do not let a worker invent a bot name. The person may also choose to have the worker leave the changes uncommitted.\n\n2. Run the gates once on the worktree as it is:\n\n```bash\ncommandmate verify <worktree-id>\n```\n\n3. Hand a task over under a contract, and let the gates judge it. A contract is a YAML file in the repository, `.commandmate/tasks/<name>.yaml`, that states the goal, the files the agent may change, and the checks that decide when it is done:\n\n```yaml\nversion: 1\ntitle: \"Issue #12: <one-line summary>\"\ngoal: |\n  Implement issue #12. Commit when the work is done.\nscope:\n  allow:\n    - \"src/**\"\n    - \"tests/**\"\nverify:\n  gates: [lint, unit]        # gate ids from .commandmate/verify.yaml\nsuccess:\n  requireWorkEvidence: true\n  requireScopeClean: true\n```\n\n```bash\ncommandmate send <worktree-id> --contract .commandmate/tasks/issue-12.yaml --instance command-code\ncommandmate wait <worktree-id> --instance command-code --verify\n```\n\n`wait --verify` exits **0** when every gate passed, **20** when a gate failed, and **21** when there is no work to judge (no commits and no changes).\n\n### Ask the person first\n\n- Installing `cmate-verify`, and writing `.commandmate/verify.yaml` into their repository.\n- Which gates to declare, and any later change to them.\n- Merging the result. A passed gate means the checks passed; whether to merge is still the person's decision.\n\n### Confirm it worked\n\n- `commandmate verify <worktree-id>` ends with exit 0, or with a gate failure the person recognizes as real.\n- `commandmate verify history` lists the run.\n\n### If it fails\n\n- `verify` exits 21 right away: the worktree has no work yet. That is expected before a task.\n- Exit 20: a gate failed. `commandmate verify show <run-id>` shows which one and the end of its log. Report it; do not weaken the gate to make it pass.\n- The contract is rejected (exit 2): it prints every problem, for example a gate id that is not in `verify.yaml`. Fix the contract, not the gates.\n\n## Where to read more\n\n- CommandMate on GitHub: https://github.com/Kewton/CommandMate\n- CLI operations guide, every flag and exit code: https://github.com/Kewton/CommandMate/blob/main/docs/en/user-guide/cli-operations-guide.md\n- The project site: https://kewton.github.io/CommandMate/\n";
 //# sourceMappingURL=setup-guide.d.ts.map

package/dist/cli/docs/setup-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-guide.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/setup-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,wzsBA8VvB,CAAC"}
+{"version":3,"file":"setup-guide.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/setup-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,WAAW,krtBAgWvB,CAAC"}

package/dist/cli/docs/setup-guide.js

@@ -145,6 +145,8 @@ commandmate remote --provider cloudflare --yes
 
 If the QR code cannot be read, or scanning it does not get the person in, have them copy the pairing URL and paste it into the address bar of the phone's browser. Pasting the link into the address bar is the way that worked in the hands-on check; do not save the link to a file.
 
+When you hand the link or QR to the person, also tell them the time it expires: \`remote\` and \`remote pair\` print a \`Pairing expires: HH:MM (in N m), works once\` line, and \`pairing.expiresAt\` in \`--json\` is the same time. If it has passed, run \`commandmate remote pair\` (only works while the code is unused), otherwise \`commandmate remote stop\` and then \`commandmate remote\`.
+
 To get the link as text again without reopening the tunnel, run \`commandmate remote pair\` (or \`commandmate remote pair --json\` and read \`pairingUrl\`). The URL stays the same, and it works only while the code is unused.
 
 ### Ask the person first

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

@@ -5,6 +5,7 @@
  * These types mirror server-side response shapes. Phase 2 will migrate to
  * shared types in src/types/api-contracts.ts.
  */
+import type { PromptView } from '../../lib/session/prompt-view';
 export interface WorktreeListResponse {
     worktrees: WorktreeItem[];
     repositories: unknown[];
@@ -175,6 +176,14 @@ export interface CurrentOutputResponse {
      * structured (hook / degraded) forms.
      */
     promptAnswerable?: boolean;
+    /**
+     * How `promptData` is shown and answered (Issue #3184). Absent from a server
+     * older than #3184; read it through `readPromptView`, which derives the same
+     * value from `promptData` then. Imported (by relative path) rather than
+     * restated: `lib/session/prompt-view` has no imports, so the CLI build can
+     * compile it, and a copy here would be a second definition to drift.
+     */
+    promptView?: PromptView | null;
     autoYes: {
         enabled: boolean;
         expiresAt: number | null;
@@ -248,6 +257,16 @@ export interface CurrentOutputResponse {
      * questions, and the frames on which their answers cross, over there.
      */
     isUnclassifiedActive?: boolean;
+    /**
+     * Epoch ms the agent's launch began, while it is still starting, else null
+     * (Issue #3179). Absent on a server that predates the field.
+     *
+     * While it is a number the session is published as `running` / `starting`
+     * with every dialog flag false, and `wait` keeps polling — the launch is work
+     * in progress, not a frame a human has to drive (exit 10) and not a session
+     * that never started (exit 21) even when its pane does not exist yet.
+     */
+    startingSince?: number | null;
     /**
      * Whether {@link sessionStatus} rests on something positive, or only on
      * nothing having matched (Issue #1926, design §4 D1 決定 2 / §7).
@@ -1158,6 +1177,12 @@ export interface WaitPromptOutput {
     question: string;
     options: unknown[];
     status: string;
+    /**
+     * How the prompt is answered (Issue #3184), from the shared prompt view:
+     * `screen` (keys at the pane), `api` (a decision over the agent's API) or
+     * `terminal` (nothing to offer). Added beside `type`, which keeps its meaning.
+     */
+    answerVia?: 'screen' | 'api' | 'terminal';
     /**
      * What the prompt asks approval for, when the detector could attribute a block
      * to it (Issue #1699). Present so a caller that reads only this payload can