commandmate 0.42.2 → 0.43.0

package/README.md

@@ -118,7 +118,7 @@ Works on desktop and mobile — monitor and steer sessions from any browser, inc
 | **cmate-orchestrate Skill** | Plans several issues at once and hands each one out with its own contract: `plan` → `dispatch` → `merge` → `uat` | Nothing mutates without `--approve`, and a failed gate stops the run |
 | **Delegation between sessions** | `commandmate ask` puts a question to another session and brings the answer back; `ask --async` with `commandmate relays` when you would rather not wait, `commandmate peers` to see who is reachable, and the `cmate-delegate` Skill for the pattern | One session can hand work to another, and it works across agent CLIs |
 | **Git Worktree Sessions** | One session per worktree, parallel execution | Multiple issues progress simultaneously without interference |
-| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, Command Code or local models per worktree | Pick the right agent for each task |
+| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini CLI, Copilot, OpenCode (1.x and V2), Antigravity, Command Code or local models per worktree | Pick the right agent for each task |
 | **Auto Yes Mode** | Agent runs without stopping for confirmations | Optional unattended mode for trusted workflows — review the Security section before enabling |
 
 ### Verified, not vibe-checked
@@ -159,7 +159,7 @@ Works on desktop and mobile — monitor and steer sessions from any browser, inc
 All eight are first-class. Each one gets the same treatment inside CommandMate — its own launch path, its own hook source and its own status detection — so the worktree session, the task contract, the verification gates and the evidence trail behave the same way whichever agent you pick.
 
 - **Claude Code**, **Codex**, **Gemini CLI**, **Copilot**, **Antigravity** — choose per worktree, per task.
-- **OpenCode** — the open-source terminal agent, driven through the same contract-and-gate path as the rest.
+- **OpenCode (1.x and V2)** — the open-source terminal agent, driven through the same contract-and-gate path as the rest. OpenCode V2 (`opencode2`) is counted with 1.x as one agent and can run next to it; see the [OpenCode V2 guide](./docs/en/user-guide/opencode-v2.md).
 - **Command Code** — driven the same way, its hooks and its transcript included.
 - **Local models** (`vibe-local`) — the same worktree session, contract and gates, against a model you host yourself.
 
@@ -594,7 +594,7 @@ The comparison that matters is not against other products; it is against the way
 | Evidence | A chat transcript | Commits, gate logs, `verify history`, `report metrics` |
 | Parallel work | Terminal tabs | One worktree and one contract per task |
 | When it stops | You notice, eventually | Waiting is surfaced: badge, toast, tab title, push |
-| Which agent | Locked to one | Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, Command Code, local models |
+| Which agent | Locked to one | Claude Code, Codex, Gemini CLI, Copilot, OpenCode (1.x and V2), Antigravity, Command Code, local models |
 
 </details>
 

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

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsVpC,wBAAgB,gBAAgB,IAAI,OAAO,CA6N1C"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/ask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4LpC,wBAAgB,gBAAgB,IAAI,OAAO,CA0O1C"}

package/dist/cli/commands/ask.js

@@ -36,6 +36,7 @@ const commander_1 = require("commander");
 const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
+const reply_ledger_1 = require("../utils/reply-ledger");
 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");
@@ -52,60 +53,8 @@ const relays_1 = require("./relays");
 const PROMPT_WAITING_CODE = 'PROMPT_WAITING';
 /** Default `--timeout`, in seconds. Matches the GUI's delegation brief. */
 const DEFAULT_ASK_TIMEOUT_SECONDS = 1800;
-/**
- * Chat rows read back after the turn.
- *
- * Bounded because only the tail matters and an unbounded read of a long-running
- * worktree's history is a large response for one line of answer. Generous
- * enough that a turn which wrote several assistant rows (a tool-use narration
- * followed by the summary) still has its last one inside the window.
- */
-const REPLY_LOOKBACK_MESSAGES = 30;
 /** Squeezed pane lines kept for the fallback reply. */
 const PANE_FALLBACK_TAIL = 80;
-/**
- * The `request_id` namespace every transcript reader mints for a turn.
- *
- * `codex-turn:<turn_id>`, `claude-turn:<uuid>`, `antigravity-turn:<id>`,
- * `command-code-turn:<id>` and opencode's `oc-turn:<msg id>` — mirrored here as
- * a shape rather than imported, for the reason {@link PROMPT_WAITING_CODE}
- * gives: the CLI bundle keeps its own copies of API strings instead of pulling
- * `src/types/agent-transcript.ts` and its dependents into `build:cli`. Matching
- * the shape rather than a list of five literals is also what stops the sixth
- * reader from silently landing outside the filter.
- *
- * A `:` cannot appear in any of the ids themselves, so this cannot match a row
- * that merely CONTAINS the text.
- */
-const TURN_REQUEST_ID_PATTERN = /-turn:/;
-/**
- * Request-id namespaces CommandMate writes about a session, not for it.
- *
- * `chat_messages` has no `system` role, so "the model changed" (Issue #2357)
- * and "reply from X" (Issue #2377) are both stored as ASSISTANT rows and told
- * apart by their request id. Neither is anything the other session said, and
- * delivering the relay notice back as an answer is the smallest possible loop —
- * `findWorkerReply` steps over the same rows for the same reason.
- */
-const SYSTEM_ROW_REQUEST_ID_PREFIXES = ['relay-sys:', 'model-changed:'];
-/**
- * Tools whose reply CommandMate reads out of a transcript rather than a screen.
- *
- * For these five the ledger is authoritative and a row with no turn marker is
- * by definition not the answer, so `ask` may hold out for a marked one. For
- * every other tool (copilot / gemini / vibe-local) the scraper's row is the
- * only record there will ever be, and demanding a marker would throw away a
- * cleaned reply in favour of the raw pane.
- *
- * Mirrors the five readers that live under `src/lib/hooks/sources/`.
- */
-const TRANSCRIPT_READER_TOOLS = new Set([
-    'claude',
-    'codex',
-    'antigravity',
-    'command-code',
-    'opencode',
-]);
 /**
  * How long `ask` will hold out for the turn row after the turn ends.
  *
@@ -123,90 +72,10 @@ const TRANSCRIPT_READER_TOOLS = new Set([
 const REPLY_TURN_ROW_GRACE_MS = 15_000;
 /** How often the grace above re-reads the ledger. */
 const REPLY_TURN_ROW_POLL_MS = 1_000;
-/**
- * ANSI escape sequences, as a pattern built from escapes rather than literals.
- *
- * `scripts/check-control-chars.mjs` fails the build on a raw C0 byte in `src/`
- * (Issue #1432), and a raw ESC here would be one.
- */
-const ANSI_ESCAPE_PATTERN = /[\u001B\u009B][[\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-PR-TZcf-nqry=><]/g;
-/** Remaining C0/C1 control bytes, once the sequences above are gone. */
-const CONTROL_CHAR_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
 /** Sleep, for the grace window above. */
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/**
- * A reply body fit to print, or `''` if nothing survived.
- *
- * Issue #2386 asked for this as a belt to the braces: the row the junk came
- * from held RAW ANSI, and a caller that pipes `ask` into a report or a commit
- * message should never have to strip escape codes out of an agent's sentence.
- * Applied to the pane fallback as well as to the ledger, because the pane is
- * the more likely of the two to carry them.
- *
- * @param raw - Reply text as it arrived
- */
-function sanitizeReply(raw) {
-    return raw.replace(ANSI_ESCAPE_PATTERN, '').replace(CONTROL_CHAR_PATTERN, '').trim();
-}
-/** Whether a row's `request_id` says a transcript reader wrote it. */
-function isTurnRow(requestId) {
-    return typeof requestId === 'string' && TURN_REQUEST_ID_PATTERN.test(requestId);
-}
-/** Whether a row is CommandMate's own furniture rather than the agent's words. */
-function isSystemRow(requestId) {
-    return typeof requestId === 'string'
-        && SYSTEM_ROW_REQUEST_ID_PREFIXES.some((prefix) => requestId.startsWith(prefix));
-}
-/**
- * The rows that could be this turn's reply, oldest first.
- *
- * @param messages - Rows as the messages route serialized them
- * @param since - Epoch ms taken immediately before the send
- */
-function replyCandidates(messages, since) {
-    const candidates = [];
-    for (const m of messages) {
-        if (m.role !== 'assistant')
-            continue;
-        if (m.messageType === 'prompt')
-            continue;
-        if (typeof m.content !== 'string')
-            continue;
-        if (!(Date.parse(m.timestamp) >= since))
-            continue;
-        if (isSystemRow(m.requestId))
-            continue;
-        const content = sanitizeReply(m.content);
-        if (content === '')
-            continue;
-        candidates.push({ content, fromTranscript: isTurnRow(m.requestId) });
-    }
-    return candidates;
-}
-/**
- * The recent chat rows for this instance, or null if they cannot be read.
- *
- * @param client - API client
- * @param worktreeId - Worktree ID
- * @param instanceId - Resolved instance ID
- */
-async function fetchRecentMessages(client, worktreeId, instanceId) {
-    const query = new URLSearchParams({ limit: String(REPLY_LOOKBACK_MESSAGES) });
-    if (instanceId)
-        query.set('instance', instanceId);
-    try {
-        // PromptMessageResponse is the CLI's mirror of a serialized chat row; the
-        // `messageType: 'prompt'` filter is the caller's, not the type's, so it is
-        // the right shape for reading normal rows too.
-        const messages = await client.get(`/api/worktrees/${worktreeId}/messages?${query.toString()}`);
-        return Array.isArray(messages) ? messages : null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Parse and validate `--timeout <seconds>`.
  *
@@ -265,24 +134,16 @@ function parseTimeout(raw) {
  * @param cliToolId - Resolved CLI tool, when one is known
  */
 async function readLatestReply(client, worktreeId, instanceId, since, cliToolId) {
-    const requireTurnRow = cliToolId !== undefined && TRANSCRIPT_READER_TOOLS.has(cliToolId);
+    const requireTurnRow = cliToolId !== undefined && reply_ledger_1.TRANSCRIPT_READER_TOOLS.has(cliToolId);
     const deadline = Date.now() + (requireTurnRow ? REPLY_TURN_ROW_GRACE_MS : 0);
     for (;;) {
-        const messages = await fetchRecentMessages(client, worktreeId, instanceId);
-        const candidates = replyCandidates(messages ?? [], since);
-        // Newest first among the rows a reader wrote. A turn that emitted several
-        // assistant rows (a narration then the summary) still ends on its summary.
-        for (let i = candidates.length - 1; i >= 0; i -= 1) {
-            if (candidates[i].fromTranscript)
-                return candidates[i].content;
-        }
-        if (!requireTurnRow) {
-            // Unchanged behaviour for a tool with no transcript: the newest row after
-            // the send, marker or not.
-            const newest = candidates[candidates.length - 1];
-            return newest ? newest.content : null;
-        }
-        if (Date.now() >= deadline)
+        const messages = await (0, reply_ledger_1.fetchRecentMessages)(client, worktreeId, instanceId);
+        // The rules are `reply`'s too (Issue #3039). A tool with no transcript
+        // takes the newest row after the send, marker or not, with no wait.
+        const reply = (0, reply_ledger_1.pickLatestReply)((0, reply_ledger_1.replyCandidates)(messages ?? [], since), requireTurnRow);
+        if (reply)
+            return reply.content;
+        if (!requireTurnRow || Date.now() >= deadline)
             return null;
         await sleep(REPLY_TURN_ROW_POLL_MS);
     }
@@ -332,6 +193,9 @@ Exit codes (wait's, unchanged; --async always exits 0 once the relay exists):
        (same shape as \`wait --on-prompt agent\`). Report it; do NOT answer it
        with \`respond\` on the other session's behalf — the number that resolves
        a dialog is the dialog's own, and a wrong one picks the default (#1681).
+  11   the turn never ran: an upstream fault is on the screen. stderr and --json
+       name it (id=...). id=context-limit: the conversation is over the model's
+       limit; \`instances <id> kill <instance>\` and ask again in a fresh session
   21   nothing was running to ask
   124  timed out. Look with \`capture <id> --instance <id> --pane --tail 60\`
 
@@ -453,6 +317,8 @@ a decision about that session's guard rails, not part of asking it a question.
                 timeout,
                 instance: instanceId,
                 token: options.token,
+                // Always on (Issue #3011): a turn that never ran must not read as a reply.
+                failOnUpstreamFault: true,
             });
             if (result.exitCode !== types_1.WaitExitCode.SUCCESS) {
                 // Same stdout contract as `wait`: the prompt payload, and nothing
@@ -460,6 +326,14 @@ a decision about that session's guard rails, not part of asking it a question.
                 if (result.output) {
                     console.log(JSON.stringify(result.output));
                 }
+                if (result.upstreamFault && options.json) {
+                    console.log(JSON.stringify({
+                        worktreeId,
+                        instanceId: instanceId ?? null,
+                        cliToolId: agent ?? null,
+                        upstreamFault: result.upstreamFault,
+                    }, null, 2));
+                }
                 process.exit(result.exitCode);
                 return;
             }
@@ -468,7 +342,7 @@ a decision about that session's guard rails, not part of asking it a question.
             if (reply === null && agent) {
                 source = 'pane';
                 const pane = await readPaneTail(client, worktreeId, agent, instanceId);
-                const cleaned = pane === null ? '' : sanitizeReply(pane);
+                const cleaned = pane === null ? '' : (0, reply_ledger_1.sanitizeReply)(pane);
                 reply = cleaned === '' ? null : cleaned;
             }
             if (reply === null) {

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

@@ -0,0 +1,40 @@
+/**
+ * reply Command - read an agent session's latest reply (Issue #3039)
+ *
+ *   commandmate reply <worktree-id> [--instance <id|alias>] [--agent <tool>]
+ *                     [--since <iso8601>] [--json]
+ *
+ * ## Why this exists next to ask / capture
+ *
+ * `ask` reads the reply to the turn IT sent. A supervisor that nudged a worker
+ * with a plain `send` ("stop and report") had no way to read the answer short
+ * of opening the tool's transcript file itself — which works for Claude, whose
+ * path is computable from the cwd, and not for Command Code, whose project slug
+ * is not. `capture` is no substitute: the pane also holds the nudge's own echo,
+ * and a pane line cannot be attributed to a turn.
+ *
+ * The server already has the reply: the transcript readers write each turn into
+ * the chat ledger keyed `<tool>-turn:<id>`, and `ask` reads it from there. This
+ * command is that read on its own, through the same shared rules
+ * (`utils/reply-ledger`), so the two can never disagree about what a reply is.
+ *
+ * ## What it deliberately does not do
+ *
+ * - No pane fallback. A row off the screen is exactly what cannot be attributed
+ *   to a turn; returning it would re-introduce the problem this command solves.
+ *   Only transcript-reader rows count, for every tool.
+ * - No wait. It is one read; "no reply yet" is an answer (exit 0, empty stdout,
+ *   `reply: null`), not an error, so a caller can poll or give up on its terms.
+ */
+import { Command } from 'commander';
+/** The `--json` payload. `reply` is null when there is no reply yet. */
+export interface ReplyJsonPayload {
+    worktreeId: string;
+    instanceId: string | null;
+    cliToolId: string | null;
+    reply: string | null;
+    requestId: string | null;
+    at: string | null;
+}
+export declare function createReplyCommand(): Command;
+//# sourceMappingURL=reply.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reply.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBpC,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAuBD,wBAAgB,kBAAkB,IAAI,OAAO,CA8E5C"}

package/dist/cli/commands/reply.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * reply Command - read an agent session's latest reply (Issue #3039)
+ *
+ *   commandmate reply <worktree-id> [--instance <id|alias>] [--agent <tool>]
+ *                     [--since <iso8601>] [--json]
+ *
+ * ## Why this exists next to ask / capture
+ *
+ * `ask` reads the reply to the turn IT sent. A supervisor that nudged a worker
+ * with a plain `send` ("stop and report") had no way to read the answer short
+ * of opening the tool's transcript file itself — which works for Claude, whose
+ * path is computable from the cwd, and not for Command Code, whose project slug
+ * is not. `capture` is no substitute: the pane also holds the nudge's own echo,
+ * and a pane line cannot be attributed to a turn.
+ *
+ * The server already has the reply: the transcript readers write each turn into
+ * the chat ledger keyed `<tool>-turn:<id>`, and `ask` reads it from there. This
+ * command is that read on its own, through the same shared rules
+ * (`utils/reply-ledger`), so the two can never disagree about what a reply is.
+ *
+ * ## What it deliberately does not do
+ *
+ * - No pane fallback. A row off the screen is exactly what cannot be attributed
+ *   to a turn; returning it would re-introduce the problem this command solves.
+ *   Only transcript-reader rows count, for every tool.
+ * - No wait. It is one read; "no reply yet" is an answer (exit 0, empty stdout,
+ *   `reply: null`), not an error, so a caller can poll or give up on its terms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReplyCommand = createReplyCommand;
+const commander_1 = require("commander");
+const types_1 = require("../types");
+const api_client_1 = require("../utils/api-client");
+const command_helpers_1 = require("../utils/command-helpers");
+const cli_tool_ids_1 = require("../config/cli-tool-ids");
+const agent_target_options_1 = require("../config/agent-target-options");
+const instances_1 = require("./instances");
+const reply_ledger_1 = require("../utils/reply-ledger");
+/**
+ * A date-time that starts with a calendar date. Date.parse alone would also
+ * take "1" or "Sep 30", which is a typo more often than an intent.
+ */
+const ISO_DATE_PREFIX = /^\d{4}-\d{2}-\d{2}/;
+/**
+ * Parse `--since <iso8601>` into epoch ms. No value means "any time".
+ *
+ * @param raw - Raw option value, if the user passed one
+ */
+function parseSince(raw) {
+    if (raw === undefined)
+        return Number.NEGATIVE_INFINITY;
+    const value = Date.parse(raw);
+    if (!ISO_DATE_PREFIX.test(raw) || !Number.isFinite(value)) {
+        console.error('Error: --since must be an ISO 8601 date-time (e.g. 2026-09-30T12:00:00Z).');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    return value;
+}
+function createReplyCommand() {
+    const cmd = new commander_1.Command('reply');
+    cmd
+        .description('Print the latest reply an agent session wrote (from its transcript; '
+        + 'exit 0 with empty stdout when there is none yet)')
+        .argument('<worktree-id>', 'Worktree ID')
+        .option('--instance <id>', `${agent_target_options_1.INSTANCE_OPTION_DESCRIPTION} ${instances_1.INSTANCE_ALIAS_HELP_SUFFIX}`)
+        .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
+        .option('--since <iso8601>', 'Only a reply written at or after this time')
+        .option('--json', 'Print { worktreeId, instanceId, cliToolId, reply, requestId, at }')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .addHelpText('after', `
+Only rows a transcript reader wrote (<tool>-turn:<id>) count as a reply, the
+same rule \`ask\` uses; the pane is never read. Tools with a transcript reader:
+claude, codex, antigravity, command-code, opencode.
+
+No reply yet (or none after --since) is not an error: stdout is empty, stderr
+says so in one line, and the exit code is 0. --json prints "reply": null.
+`)
+        .action(async (worktreeId, options) => {
+        try {
+            if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
+                console.error('Error: Invalid worktree ID format.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            if (options.agent && !(0, cli_tool_ids_1.isCliToolId)(options.agent)) {
+                console.error(`Error: Invalid agent. Must be one of: ${cli_tool_ids_1.CLI_TOOL_IDS.join(', ')}`);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            if (options.instance && !(0, instances_1.isInstanceSelector)(options.instance)) {
+                console.error(instances_1.INSTANCE_SELECTOR_ERROR);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            const since = parseSince(options.since);
+            const client = new api_client_1.ApiClient({ token: options.token });
+            // Resolved exactly as `ask` resolves it: `--agent` alone names that
+            // tool's primary instance (Issue #2479).
+            const selector = options.instance ?? options.agent;
+            const target = selector
+                ? await (0, instances_1.resolveInstanceTarget)(client, worktreeId, selector, options.agent)
+                : null;
+            const cliToolId = target ? target.cliToolId : options.agent;
+            const instanceId = target?.instanceId;
+            // Unlike `ask`, a failed read is not swallowed: there is no turn this
+            // command completed that a fallback would be protecting.
+            const messages = await (0, reply_ledger_1.requestRecentMessages)(client, worktreeId, instanceId);
+            const latest = (0, reply_ledger_1.pickLatestReply)((0, reply_ledger_1.replyCandidates)(messages, since), true);
+            if (options.json) {
+                const payload = {
+                    worktreeId,
+                    instanceId: instanceId ?? null,
+                    cliToolId: cliToolId ?? null,
+                    reply: latest?.content ?? null,
+                    requestId: latest?.requestId ?? null,
+                    at: latest?.at ?? null,
+                };
+                console.log(JSON.stringify(payload, null, 2));
+            }
+            else if (latest) {
+                console.log(latest.content);
+            }
+            if (!latest) {
+                console.error(options.since
+                    ? `No reply since ${options.since} (no transcript row yet).`
+                    : 'No reply yet (no transcript row yet).');
+            }
+            process.exit(types_1.ExitCode.SUCCESS);
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}

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

@@ -124,6 +124,11 @@ export interface PollWorktreeOptions extends WaitOptions {
 export declare function pollWorktree(client: ApiClient, worktreeId: string, options: PollWorktreeOptions): Promise<{
     exitCode: number;
     output?: WaitPromptOutput;
+    /** Set with exit 11: which upstream fault was on the frame (Issue #3011). */
+    upstreamFault?: {
+        id: string;
+        matchedText: string;
+    };
 }>;
 export declare function createWaitCommand(): Command;
 //# sourceMappingURL=wait.d.ts.map

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;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAggB1D;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;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"}

package/dist/cli/commands/wait.js

@@ -1019,7 +1019,16 @@ async function pollWorktree(client, worktreeId, options) {
                     console.error(`Upstream fault on ${worktreeId}: id=${fault.id} — the agent is back at its ` +
                         'composer with an upstream API failure on screen, so this turn did not run. ' +
                         `Matched: ${JSON.stringify(fault.matchedText)}`);
-                    return { exitCode: types_1.WaitExitCode.UPSTREAM_FAULT };
+                    if (fault.id === 'context-limit') {
+                        // A retry into the same session hits the same wall (Issue #3011).
+                        console.error('The session\'s conversation is over the model\'s context limit. Start a fresh ' +
+                            `session and send again: commandmate instances ${worktreeId} kill ` +
+                            `${options.instance ?? '<instance>'}`);
+                    }
+                    return {
+                        exitCode: types_1.WaitExitCode.UPSTREAM_FAULT,
+                        upstreamFault: { id: fault.id, matchedText: fault.matchedText },
+                    };
                 }
                 // Issue #1839: `ready` off the terminal frame is the agent's composer,
                 // not the agent's verdict. Measured 2026-08-20 against a stub upstream