commandmate 0.49.1 → 0.49.3

package/dist/cli/commands/report.js

@@ -71,16 +71,29 @@ function formatRate(value) {
 async function readRelayCounts(client, days) {
     try {
         const response = await client.get(`/api/relays?days=${encodeURIComponent(String(days))}`);
-        return response.counts ?? null;
+        if (!response.counts)
+            return null;
+        // Issue #4082: the held count is "now", not the window's; null (never 0)
+        // when the server did not answer it.
+        return {
+            counts: response.counts,
+            held: typeof response.heldCount === 'number' ? response.heldCount : null,
+        };
     }
     catch {
         return null;
     }
 }
-/** The relay line, in the same shape as the four above it. */
-function formatRelayCounts(counts) {
+/**
+ * The relay line, in the same shape as the four above it.
+ *
+ * @param held - Issue #4082: payloads held as `uncertain` NOW (not narrowed by
+ *   the window, not one of the states); omitted from the line when null/absent
+ */
+function formatRelayCounts(counts, held = null) {
+    const heldPart = held === null ? '' : `, ${held} held now`;
     return (`Relays:       ${counts.delivered} delivered / ${counts.prompt} waiting on a prompt `
-        + `/ ${counts.expired} expired  (${counts.pending} still open, ${counts.cancelled} cancelled)`);
+        + `/ ${counts.expired} expired  (${counts.pending} still open, ${counts.cancelled} cancelled${heldPart})`);
 }
 function formatVibeMetrics(m) {
     const { tasks, verification, intervention } = m;
@@ -242,12 +255,12 @@ function createReportCommand() {
             // until now it was the only kind that left no mark on the metrics.
             const relays = await readRelayCounts(client, days);
             if (options.json) {
-                console.log(JSON.stringify({ ...data.metrics, relays }, null, 2));
+                console.log(JSON.stringify({ ...data.metrics, relays: relays?.counts ?? null, relaysHeld: relays?.held ?? null }, null, 2));
             }
             else {
                 console.log(formatVibeMetrics(data.metrics));
                 if (relays)
-                    console.log(formatRelayCounts(relays));
+                    console.log(formatRelayCounts(relays.counts, relays.held));
             }
         }
         catch (error) {

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

@@ -1 +1 @@
-{"version":3,"file":"respond-strict.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond-strict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAe/C,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAOhE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CA2B7G;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAMhG;AA0CD,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,CAS/D;AAuED,kDAAkD;AAClD,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAyCf"}
+{"version":3,"file":"respond-strict.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond-strict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAgB/C,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAOhE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CA2B7G;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAMhG;AA0CD,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,CAS/D;AAsGD,kDAAkD;AAClD,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/cli/commands/respond-strict.js

@@ -25,6 +25,7 @@ const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const kinds_1 = require("../../lib/prompt-observation/kinds");
 const command_target_1 = require("./command-target");
+const follow_up_command_1 = require("../utils/follow-up-command");
 /** Mirrors the server's check. */
 const OPERATION_ID_PATTERN = /^[A-Za-z0-9_-]{8,64}$/;
 const ANSWERED_BY_PATTERN = /^[A-Za-z0-9_:/.@-]{1,160}$/;
@@ -143,7 +144,29 @@ function verdictOfApiError(error, options, operationId) {
     return localResult(options, operationId, 41, 'response_unknown', `The server's answer was lost (${error.message}); keys may have been sent. Do not answer again blindly: ` +
         `re-run with --operation-id ${operationId} to read the result of this one.`);
 }
-function printResult(result, options) {
+/**
+ * The commands the strict respond's failure hints name (Issue #4031), aimed at
+ * the target the request resolved to (#3982's `followUpCommand`). A request
+ * that named no target keeps the hints as they were.
+ *
+ * Issue #4049: `prompt` takes no `--agent`, so an `--agent`-only request names
+ * the tool's primary instance, whose id is the tool id (#868). The server
+ * resolves `--instance <tool>` to the same session as `--agent <tool>` alone
+ * (`resolveSessionTarget`: 'primary' without a roster row, the row's own tool
+ * with one).
+ */
+function strictRespondHints(worktreeId, target) {
+    if ((0, follow_up_command_1.targetFlags)(target) === '') {
+        return { prompt: '`commandmate prompt`', look: '`commandmate prompt` / `capture --pane`' };
+    }
+    // `prompt` takes `--instance` only; `capture` takes either flag.
+    const promptInstance = target.instanceId ?? target.agent;
+    const prompt = promptInstance
+        ? `\`commandmate prompt ${worktreeId} --instance ${promptInstance}\``
+        : `\`commandmate prompt ${worktreeId}\``;
+    return { prompt, look: `${prompt} / \`${(0, follow_up_command_1.paneCaptureCommand)(worktreeId, target)}\`` };
+}
+function printResult(result, options, worktreeId, commandTarget) {
     if (options.json) {
         console.log(JSON.stringify(result));
         return;
@@ -157,12 +180,12 @@ function printResult(result, options) {
     const target = result.observedTarget === null ? '' : ` Observed target: ${result.observedTarget}.`;
     if (result.code === types_1.StrictRespondExitCode.NOT_SENT) {
         console.error(`Error: Answer was not sent. Reason: ${result.reason} — ${result.message}${observed}${target}`);
-        console.error('Observe the screen again with `commandmate prompt` before answering.');
+        console.error(`Observe the screen again with ${strictRespondHints(worktreeId, commandTarget).prompt} before answering.`);
     }
     else {
         console.error(`Error: Keys were sent (${result.keysSent}, delivery ${result.delivery}) and the answer is not confirmed. ` +
             `Reason: ${result.reason} — ${result.message}${observed}`);
-        console.error('Do not send it again: look at the pane (`commandmate prompt` / `capture --pane`) first.');
+        console.error(`Do not send it again: look at the pane (${strictRespondHints(worktreeId, commandTarget).look}) first.`);
     }
 }
 /** Run the strict respond; sets the exit code. */
@@ -175,7 +198,8 @@ async function runStrictRespond(worktreeId, answer, options) {
     }
     const operationId = options.operationId ?? (0, crypto_1.randomUUID)();
     const client = new api_client_1.ApiClient({ token: options.token });
-    const { agent, instanceId } = await (0, command_target_1.resolveCommandTarget)(client, worktreeId, options.instance, options.agent);
+    const commandTarget = await (0, command_target_1.resolveCommandTarget)(client, worktreeId, options.instance, options.agent);
+    const { agent, instanceId } = commandTarget;
     const body = {
         expectScreen: options.expectScreen,
         observation: options.observation,
@@ -208,7 +232,7 @@ async function runStrictRespond(worktreeId, answer, options) {
         // Not this endpoint's answer: whatever served it, nothing says what happened.
         result = localResult(options, operationId, 41, 'response_unknown', 'The server answered with something that is not a strict respond result.');
     }
-    printResult(result, options);
+    printResult(result, options, worktreeId, commandTarget);
     if (result.code !== types_1.StrictRespondExitCode.SUCCESS)
         process.exit(result.code);
 }

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

@@ -13,8 +13,8 @@ import { Command } from 'commander';
 export declare const ANSWER_NOT_DELIVERED = "answer_not_delivered";
 /**
  * Issue #3975: the answer was stopped part-way — some of its keys may be on
- * the pane. `/prompt-response` answers it as a 500 whose `error` carries this
- * code. Restated from `src/lib/prompt-answer-errors.ts` (`ANSWER_INPUT_LOST_REASON`).
+ * the pane. Both routes answer it as a 500 with this `reason` (Issue #3982).
+ * Restated from `src/lib/prompt-answer-errors.ts` (`ANSWER_INPUT_LOST_REASON`).
  */
 export declare const ANSWER_INPUT_LOST = "answer_input_lost";
 export declare function createRespondCommand(): Command;

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

@@ -1 +1 @@
-{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgKpC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAoUrD,wBAAgB,oBAAoB,IAAI,OAAO,CA2I9C"}
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkKpC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AA0TrD,wBAAgB,oBAAoB,IAAI,OAAO,CA6I9C"}

package/dist/cli/commands/respond.js

@@ -16,6 +16,8 @@ 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 command_target_1 = require("./command-target");
+const follow_up_command_1 = require("../utils/follow-up-command");
+const server_capabilities_1 = require("../utils/server-capabilities");
 const respond_strict_1 = require("./respond-strict");
 const kinds_1 = require("../../lib/prompt-observation/kinds");
 /**
@@ -134,37 +136,41 @@ const PROMPT_NO_LONGER_ACTIVE = 'prompt_no_longer_active';
 exports.ANSWER_NOT_DELIVERED = 'answer_not_delivered';
 /**
  * Issue #3975: the answer was stopped part-way — some of its keys may be on
- * the pane. `/prompt-response` answers it as a 500 whose `error` carries this
- * code. Restated from `src/lib/prompt-answer-errors.ts` (`ANSWER_INPUT_LOST_REASON`).
+ * the pane. Both routes answer it as a 500 with this `reason` (Issue #3982).
+ * Restated from `src/lib/prompt-answer-errors.ts` (`ANSWER_INPUT_LOST_REASON`).
  */
 exports.ANSWER_INPUT_LOST = 'answer_input_lost';
-/** Whether a failed `/prompt-response` request is the answer stopped part-way (Issue #3975). */
-function isAnswerInputLost(error) {
+/**
+ * Whether a failed `/prompt-response` request is the answer stopped part-way
+ * (Issue #3975).
+ *
+ * Issue #3982: by `reason` alone on a server that declares
+ * `prompt-answer-reason`. The 500's `error` text can quote the answer (a tmux
+ * failure does), so a reason code found there is not evidence of anything. Only
+ * a server without the token — which put this reason nowhere but that text —
+ * is still read the old way. The probe is the memo `resolveCommandTarget`
+ * filled for this client; nothing is asked unless the request already failed.
+ */
+async function isAnswerInputLost(error, client) {
     if (!(error instanceof api_client_1.ApiError) || (error.statusCode ?? 0) < 500)
         return false;
     const payload = error.payload;
     if (payload?.reason === exports.ANSWER_INPUT_LOST)
         return true;
-    return typeof payload?.error === 'string' && payload.error.includes(exports.ANSWER_INPUT_LOST);
+    if (typeof payload?.error !== 'string' || !payload.error.includes(exports.ANSWER_INPUT_LOST))
+        return false;
+    return !(await (0, server_capabilities_1.serverReportsPromptAnswerReason)(client));
 }
 /**
- * The `capture` that reads the pane the answer was typed at (Issue #3975
- * review P2-2): the target the answer resolved to, never the worktree default,
- * and `--pane`, since the stored reply is not what was partly typed.
+ * Reports an answer stopped part-way (Issue #3975) and sets the exit code. The
+ * `capture` reads the pane the answer was typed at (review P2-2): the target
+ * the answer resolved to, never the worktree default, and `--pane`, since the
+ * stored reply is not what was partly typed.
  */
-function answeredPaneCaptureCommand(worktreeId, target) {
-    const selector = target.instanceId
-        ? ` --instance ${target.instanceId}`
-        : target.agent
-            ? ` --agent ${target.agent}`
-            : '';
-    return `commandmate capture ${worktreeId}${selector} --pane --tail 40`;
-}
-/** Reports an answer stopped part-way (Issue #3975) and sets the exit code. */
 function reportAnswerInputLost(worktreeId, target) {
     console.error(`Warning: The answer may have been only partly typed (reason: ${exports.ANSWER_INPUT_LOST}): the session was ` +
         'replaced part-way, so some of its keys may have reached the agent and the rest did not. ' +
-        `Check the screen with \`${answeredPaneCaptureCommand(worktreeId, target)}\` before answering again.`);
+        `Check the screen with \`${(0, follow_up_command_1.dialogCaptureCommand)(worktreeId, target)}\` before answering again.`);
     // The exit code `decision_not_delivered` uses (Issue #3975: no new code).
     process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
 }
@@ -177,10 +183,6 @@ const PLAN_REVIEW_ACTIONS = ['comment', 'submit', 'approve', 'cancel'];
 function isPlanReviewRefusal(reason) {
     return reason.startsWith('plan_review_');
 }
-/** ` --instance <id>` as the caller spelled it, or nothing. */
-function instanceFlag(instance) {
-    return instance ? ` --instance ${instance}` : '';
-}
 /**
  * `textFollowUp` from a `/prompt-response` success (Issue #3093), read
  * defensively: an older server omits it, and the route's mirror type is not
@@ -264,7 +266,7 @@ function buildPromptResponseBody(useDefault, answer, agent, instanceId, planRevi
     return body;
 }
 /** Reports a `success: false` result and sets the exit code. */
-function reportFailedResponse(result, worktreeId, answer, useDefault, options) {
+function reportFailedResponse(result, worktreeId, answer, useDefault, target) {
     // [DR2-06] Check reason for failure
     const reason = result.reason || 'unknown';
     // Issue #1681 / #1726: these mean the server refused BEFORE sending,
@@ -308,9 +310,9 @@ function reportFailedResponse(result, worktreeId, answer, useDefault, options) {
         // be mapped onto a choice", and only when the answer was not already
         // a number (where the number itself is what was wrong).
         if (reason === 'unresolvable_answer' && answer !== undefined && !/^\d+$/.test(answer.trim())) {
-            const target = options.instance ? ` --instance ${options.instance}` : '';
-            console.error(`Hint: answer with the option number — \`commandmate respond ${worktreeId} <number>${target}\` ` +
-                `(\`commandmate capture ${worktreeId}${target}\` prints the dialog and its numbers).`);
+            // Issue #3982: the resolved target, and the pane — where the numbers are.
+            console.error(`Hint: answer with the option number — \`${(0, follow_up_command_1.followUpCommand)('respond', worktreeId, target, '<number>')}\` ` +
+                `(\`${(0, follow_up_command_1.dialogCaptureCommand)(worktreeId, target)}\` prints the dialog and its numbers).`);
         }
     }
     else {
@@ -322,7 +324,7 @@ function reportFailedResponse(result, worktreeId, answer, useDefault, options) {
         if (reason === PROMPT_NO_LONGER_ACTIVE && !useDefault && answer !== undefined && !/^\d+$/.test(answer.trim())) {
             console.error('Hint: no dialog is open, so this text was not delivered. If you just chose an option that asks ' +
                 'for text (e.g. "No, tell … what to do differently"), the agent is waiting for it in its input box — ' +
-                `send it with \`commandmate send ${worktreeId} "<text>"${instanceFlag(options.instance)}\`.`);
+                `send it with \`${(0, follow_up_command_1.followUpCommand)('send', worktreeId, target, '"<text>"')}\`.`);
         }
     }
     // Issue #1726: an option number the agent's own payload does not offer
@@ -334,15 +336,14 @@ function reportFailedResponse(result, worktreeId, answer, useDefault, options) {
  * What was done on Command Code's plan review (Issue #3125), and the next step:
  * a pinned comment is not delivered to the agent until the review is submitted.
  */
-function printPlanReviewOutcome(result, worktreeId, options) {
+function printPlanReviewOutcome(result, worktreeId, target) {
     const planReview = result.planReview;
     if (!planReview)
         return;
-    const target = instanceFlag(options.instance);
     switch (planReview.action) {
         case 'comment':
             console.log(`Plan review: pinned comment "${planReview.comment ?? ''}".`);
-            console.error(`Next: send the review with \`commandmate respond ${worktreeId} --plan-review submit${target}\` ` +
+            console.error(`Next: send the review with \`${(0, follow_up_command_1.followUpCommand)('respond', worktreeId, target, '--plan-review submit')}\` ` +
                 `(ctrl+r), or approve with \`--plan-review approve\` (comments go along as notes).`);
             break;
         case 'submit':
@@ -358,7 +359,7 @@ function printPlanReviewOutcome(result, worktreeId, options) {
                 console.log('Plan review: approved the plan (ctrl+a).');
                 if (planReview.pendingCommentsBefore > 0) {
                     console.error('Note: with pending comments Command Code may ask how to approve — confirm with ' +
-                        `\`commandmate respond ${worktreeId} --plan-review approve${target}\` again, or go back with \`--plan-review cancel\`.`);
+                        `\`${(0, follow_up_command_1.followUpCommand)('respond', worktreeId, target, '--plan-review approve')}\` again, or go back with \`--plan-review cancel\`.`);
                 }
             }
             break;
@@ -465,8 +466,10 @@ Strict respond (--expect-screen <kind> --observation <token> <label>):
             // and falls back to the worktree default, so `--instance codex` alone
             // answered into a session that was never started. Resolve the tool the
             // instance is registered under first.
-            const { agent, instanceId } = await (0, command_target_1.resolveCommandTarget)(client, worktreeId, options.instance, options.agent);
+            const commandTarget = await (0, command_target_1.resolveCommandTarget)(client, worktreeId, options.instance, options.agent);
+            const { agent, instanceId } = commandTarget;
             // Issue #2376: the resolved id. /prompt-response reads instance ids.
+            // Issue #3982: every hint below names `commandTarget`, never `options.instance`.
             const body = buildPromptResponseBody(useDefault, answer, agent, instanceId, options.planReview);
             // Issue #2040: for an agent that publishes per-decision ids (opencode
             // today, and only opencode), a bare `respond <worktree> 3` names the ONE
@@ -503,18 +506,18 @@ Strict respond (--expect-screen <kind> --observation <token> <label>):
                 catch (error) {
                     // Issue #3975: stopped part-way is not "the server failed" — some
                     // keys may be on the pane, and the operator has to look first.
-                    if (!isAnswerInputLost(error))
+                    if (!(await isAnswerInputLost(error, client)))
                         throw error;
-                    reportAnswerInputLost(worktreeId, { agent, instanceId });
+                    reportAnswerInputLost(worktreeId, commandTarget);
                     return;
                 }
             }
             if (result && !result.success) {
-                reportFailedResponse(result, worktreeId, answer, useDefault, options);
+                reportFailedResponse(result, worktreeId, answer, useDefault, commandTarget);
             }
             printResolvedAudit(result, answer);
             if (result && 'planReview' in result)
-                printPlanReviewOutcome(result, worktreeId, options);
+                printPlanReviewOutcome(result, worktreeId, commandTarget);
             console.error('Response sent.');
             // Issue #3093: the option just chosen continues as typed text, which the
             // dialog no longer takes — name the command that does deliver it.
@@ -522,7 +525,7 @@ Strict respond (--expect-screen <kind> --observation <token> <label>):
             if (followUp) {
                 console.error(`Next: option ${followUp.optionNumber} ("${followUp.optionLabel}") asks for your text, and the dialog ` +
                     'is closed now, so `respond` cannot deliver it — send it with ' +
-                    `\`commandmate send ${worktreeId} "<text>"${instanceFlag(options.instance)}\`.`);
+                    `\`${(0, follow_up_command_1.followUpCommand)('send', worktreeId, commandTarget, '"<text>"')}\`.`);
             }
         }
         catch (error) {

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

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

package/dist/cli/commands/send.js

@@ -16,6 +16,7 @@ const model_validation_1 = require("../config/model-validation");
 const agent_instances_1 = require("../utils/agent-instances");
 const instances_1 = require("./instances");
 const command_target_1 = require("./command-target");
+const follow_up_command_1 = require("../utils/follow-up-command");
 const auto_yes_1 = require("./auto-yes");
 const relays_1 = require("./relays");
 const message_dispatch_1 = require("./message-dispatch");
@@ -34,9 +35,10 @@ const SEND_VERIFIED_MAX_LINES = 240;
  * older daemon, or a truncated body. The code is the contract; the sentence is
  * a courtesy, and the CLI must still say what to do without it.
  */
-function promptWaitingFallback(worktreeId) {
+function promptWaitingFallback(worktreeId, target) {
     return (`${worktreeId} is waiting on a prompt; the message was not sent. ` +
-        `Answer it first: \`commandmate respond ${worktreeId} <answer>\`.`);
+        // Issue #3982: the prompt is the resolved target's, not the worktree default's.
+        `Answer it first: \`${(0, follow_up_command_1.followUpCommand)('respond', worktreeId, target, '<answer>')}\`.`);
 }
 /**
  * Resolve --duration to milliseconds, exiting on an invalid value.
@@ -349,7 +351,8 @@ worktree and send a short message that tells the agent to read that file.
             // the roster is the only place that pairs the two. Resolve it once, up
             // front, so the task row, the send and auto-yes all name the same tool
             // as the session that actually starts.
-            const { agent, instanceId } = await (0, command_target_1.resolveCommandTarget)(client, worktreeId, options.instance, options.agent);
+            const commandTarget = await (0, command_target_1.resolveCommandTarget)(client, worktreeId, options.instance, options.agent);
+            const { agent, instanceId } = commandTarget;
             // Issue #2376: the RESOLVED id, never the string the user typed.
             // `--instance "Codex 2"` has to reach /send as `codex-2`; no route but
             // /resolve-target knows how to read an alias.
@@ -426,7 +429,8 @@ worktree and send a short message that tells the agent to read that file.
             await (0, message_dispatch_1.postMessage)(client, worktreeId, sendBody, {
                 relay,
                 onFailure: failTask,
-                promptWaitingFallback: promptWaitingFallback(worktreeId),
+                promptWaitingFallback: promptWaitingFallback(worktreeId, commandTarget),
+                target: commandTarget,
             });
             console.error('Message sent.');
             if (taskId) {

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

@@ -7,5 +7,27 @@
  * exist only inside the message text.
  */
 import { Command } from 'commander';
+import type { RelayCountsResponse } from '../types/api-responses';
+/**
+ * The relay counts for the session this task ran in, or null (Issue #2377).
+ *
+ * Scoped to the task's own worktree AND instance, because that is the session a
+ * relay would have been opened by or against — a worktree-wide count would put
+ * another agent's delegations on this task's page.
+ *
+ * Best effort: a daemon with no relay ledger is one that answers 404 here, which
+ * must not fail `task show`.
+ */
+/**
+ * What {@link readTaskRelayCounts} answers (Issue #4082): the per-state counts
+ * and, apart from them, the payloads held as `uncertain` now. `held` is null
+ * when the server did not say (older than #4082) — never 0 then.
+ */
+export interface TaskRelaySummary {
+    counts: RelayCountsResponse;
+    held: number | null;
+}
+/** The `RELAYS:` line of `task show` (Issue #2377; held count Issue #4082). */
+export declare function formatTaskRelayLine(summary: TaskRelaySummary): string;
 export declare function createTaskCommand(): Command;
 //# sourceMappingURL=task.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/task.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2DpC,wBAAgB,iBAAiB,IAAI,OAAO,CAuI3C"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/task.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,KAAK,EACV,mBAAmB,EAKpB,MAAM,wBAAwB,CAAC;AAahC;;;;;;;;;GASG;AACH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAoBD,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAOrE;AAeD,wBAAgB,iBAAiB,IAAI,OAAO,CA4I3C"}

package/dist/cli/commands/task.js

@@ -8,6 +8,7 @@
  * exist only inside the message text.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTaskRelayLine = formatTaskRelayLine;
 exports.createTaskCommand = createTaskCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -19,28 +20,30 @@ const TASK_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-
 function formatTimestamp(value) {
     return value ?? '-';
 }
-/**
- * The relay counts for the session this task ran in, or null (Issue #2377).
- *
- * Scoped to the task's own worktree AND instance, because that is the session a
- * relay would have been opened by or against — a worktree-wide count would put
- * another agent's delegations on this task's page.
- *
- * Best effort: a daemon with no relay ledger is one that answers 404 here, which
- * must not fail `task show`.
- */
 async function readTaskRelayCounts(client, task) {
     const query = new URLSearchParams({ worktree: task.worktreeId });
     if (task.instanceId)
         query.set('instance', task.instanceId);
     try {
         const response = await client.get(`/api/relays?${query.toString()}`);
-        return response.counts ?? null;
+        if (!response.counts)
+            return null;
+        return {
+            counts: response.counts,
+            held: typeof response.heldCount === 'number' ? response.heldCount : null,
+        };
     }
     catch {
         return null;
     }
 }
+/** The `RELAYS:` line of `task show` (Issue #2377; held count Issue #4082). */
+function formatTaskRelayLine(summary) {
+    const { counts, held } = summary;
+    const heldPart = held === null ? '' : `, ${held} held`;
+    return (`RELAYS:    ${counts.delivered} delivered / ${counts.prompt} prompt / `
+        + `${counts.expired} expired  (${counts.pending} open${heldPart})`);
+}
 function printTaskLine(task) {
     const gates = task.contract.verify.gates;
     console.log([
@@ -110,11 +113,19 @@ function createTaskCommand() {
             const client = new api_client_1.ApiClient({ token: options.token });
             const response = await client.get(`/api/tasks/${taskId}`);
             const detail = (0, api_client_1.assertResponseShape)(response, ['task', 'lastVerificationRun'], 'GET /api/tasks/:taskId');
+            const { task, lastVerificationRun } = detail;
+            // Issue #2377 / #4082: read before either output, so the JSON carries
+            // the same relay counts (and held count) the text prints. `null` when
+            // the daemon has no ledger; `relaysHeld: null` when it did not say.
+            const relays = await readTaskRelayCounts(client, task);
             if (options.json) {
-                console.log(JSON.stringify(detail));
+                console.log(JSON.stringify({
+                    ...detail,
+                    relays: relays?.counts ?? null,
+                    relaysHeld: relays?.held ?? null,
+                }));
                 return;
             }
-            const { task, lastVerificationRun } = detail;
             console.log(`ID:        ${task.id}`);
             console.log(`STATUS:    ${task.status}`);
             console.log(`WORKTREE:  ${task.worktreeId}`);
@@ -140,11 +151,8 @@ function createTaskCommand() {
             // Issue #2377: what this session delegated, and what came back. Printed
             // before the verification block because it is about the same session,
             // whereas the run below is about one judgement of it.
-            const relays = await readTaskRelayCounts(client, task);
-            if (relays) {
-                console.log(`RELAYS:    ${relays.delivered} delivered / ${relays.prompt} prompt / `
-                    + `${relays.expired} expired  (${relays.pending} open)`);
-            }
+            if (relays)
+                console.log(formatTaskRelayLine(relays));
             if (!lastVerificationRun) {
                 console.log('VERIFY:    (no verification run yet)');
                 return;

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

@@ -3,7 +3,8 @@
  * Issue #3964: split out of wait.ts.
  */
 import type { WaitOptions } from '../types';
-import type { ApiClient } from '../utils/api-client';
+import { type ApiClient } from '../utils/api-client';
+import { type CommandTarget } from './command-target';
 /**
  * `options` with `--instance` resolved from a selector to an instance ID
  * (Issue #2376).
@@ -18,4 +19,11 @@ import type { ApiClient } from '../utils/api-client';
  * @param options - The options as given
  */
 export declare function resolveWaitInstance<T extends WaitOptions>(client: ApiClient, worktreeId: string, options: T): Promise<T>;
+/**
+ * The target `wait`'s hints name (Issue #3982): the `--instance` that
+ * {@link resolveWaitInstance} resolved, or none. `wait` has no `--agent`.
+ *
+ * @param options - Options already passed through {@link resolveWaitInstance}
+ */
+export declare function waitCommandTarget(options: Pick<WaitOptions, 'instance'>): CommandTarget;
 //# sourceMappingURL=wait-instance.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"wait-instance.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-instance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGrD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,WAAW,EAC7D,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,CAAC,CAAC,CAkBZ"}
+{"version":3,"file":"wait-instance.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-instance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,WAAW,EAC7D,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,CAAC,CAAC,CAqBZ;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,GAAG,aAAa,CAKvF"}

package/dist/cli/commands/wait-instance.js

@@ -5,8 +5,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveWaitInstance = resolveWaitInstance;
+exports.waitCommandTarget = waitCommandTarget;
 const types_1 = require("../types");
+const api_client_1 = require("../utils/api-client");
 const instances_1 = require("./instances");
+const command_target_1 = require("./command-target");
 /**
  * `options` with `--instance` resolved from a selector to an instance ID
  * (Issue #2376).
@@ -28,6 +31,9 @@ async function resolveWaitInstance(client, worktreeId, options) {
         return { ...options, instance: target.instanceId ?? options.instance };
     }
     catch (error) {
+        // Issue #3983: `--timeout` ran out while resolving. Exit 124 rather than
+        // degrade: carrying on with the selector would wait past the deadline.
+        (0, api_client_1.rethrowIfDeadlineExceeded)(error);
         // Degrade to the pre-#2376 behaviour rather than failing the wait. An
         // instance ID needs no resolution to reach `/current-output?instance=` —
         // resolution exists here so that an ALIAS can — so a resolver that cannot
@@ -39,3 +45,12 @@ async function resolveWaitInstance(client, worktreeId, options) {
         return options;
     }
 }
+/**
+ * The target `wait`'s hints name (Issue #3982): the `--instance` that
+ * {@link resolveWaitInstance} resolved, or none. `wait` has no `--agent`.
+ *
+ * @param options - Options already passed through {@link resolveWaitInstance}
+ */
+function waitCommandTarget(options) {
+    return (0, command_target_1.commandTargetOf)(options.instance ? { cliToolId: undefined, instanceId: options.instance } : null, undefined);
+}

package/dist/cli/commands/wait-poll-state.d.ts

@@ -39,6 +39,14 @@ export interface PollWorktreeOptions extends WaitOptions {
      * record, read only: nothing `wait` decides depends on it.
      */
     onTurnRecord?: (openedAt: number | null, closedAt: number | null) => void;
+    /**
+     * Epoch ms the command started, from which `--timeout` counts (Issue #3983).
+     *
+     * `--timeout` is the deadline of the whole command, so the reads before the
+     * poll (`--instance` resolution, the task ledger, `ask`'s send) are inside it
+     * rather than in front of it. Absent means the poll's own start, as before.
+     */
+    timeoutStartedAt?: number;
 }
 /**
  * What {@link pollWorktree} carries from one poll to the next: every variable its
@@ -111,7 +119,17 @@ export interface PollContext {
     client: ApiClient;
     worktreeId: string;
     options: PollWorktreeOptions;
+    /**
+     * Where `--timeout` counts from: {@link PollWorktreeOptions.timeoutStartedAt}
+     * when given, else {@link pollStartedAt} (Issue #3983).
+     */
     startTime: number;
+    /**
+     * When this poll began. The turn window (turn adoption, #1975's pending-prompt
+     * hold) is about the poll, not about the command, and stays here so that a
+     * slow send before an `ask`'s poll does not shift it (Issue #3983).
+     */
+    pollStartedAt: number;
     autoYesGraceSeconds: number;
     autoYesGraceMs: number;
 }

package/dist/cli/commands/wait-poll-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait-poll-state.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-poll-state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9E;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;OAGG;IACH,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,cAAc,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,cAAc,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"wait-poll-state.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-poll-state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9E;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC1E;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;OAGG;IACH,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,qFAAqF;IACrF,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,cAAc,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,cAAc,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,mBAAmB,CAAC;IAC7B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;CACxB"}

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

@@ -28,7 +28,8 @@ export declare function shouldVerify(exitCode: number, options: WaitOptions): bo
  * run that follows is judged against the contract it was supposed to judge.
  *
  * Never throws: an unreadable ledger costs the attribution, and refusing to
- * verify over it would cost every gate.
+ * verify over it would cost every gate. The one exception is a client deadline
+ * (`--timeout`, Issue #3983), which is rethrown as the exit 124 it is.
  *
  * @returns the task id, or undefined to leave resolution to the server
  */

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

@@ -1 +1 @@
-{"version":3,"file":"wait-verify.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-verify.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAY,MAAM,qBAAqB,CAAC;AAG1D,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAG5E;AAgBD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC,MAAM,CAAC,CAyBjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CASxE"}
+{"version":3,"file":"wait-verify.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-verify.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAuC,MAAM,qBAAqB,CAAC;AAGrF,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAG5E;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB7B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC,MAAM,CAAC,CAyBjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CASxE"}