commandmate 0.49.0 → 0.49.2

package/dist/cli/commands/respond.js

@@ -6,6 +6,7 @@
  * Uses prompt-response API (not respond API) [DR2-06]
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANSWER_INPUT_LOST = exports.ANSWER_NOT_DELIVERED = void 0;
 exports.createRespondCommand = createRespondCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -15,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");
 /**
@@ -125,6 +128,52 @@ async function answerSolePendingDecision(client, worktreeId, body) {
 }
 /** Reason `/prompt-response` gives when no dialog is on screen any more. */
 const PROMPT_NO_LONGER_ACTIVE = 'prompt_no_longer_active';
+/**
+ * Issue #3975: the answer waited for another input and was then not typed —
+ * nothing reached the pane. Restated from `src/lib/prompt-answer-errors.ts`
+ * (`ANSWER_NOT_DELIVERED_REASON`); a unit test keeps the two equal.
+ */
+exports.ANSWER_NOT_DELIVERED = 'answer_not_delivered';
+/**
+ * Issue #3975: the answer was stopped part-way — some of its keys may be on
+ * 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).
+ *
+ * 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;
+    if (typeof payload?.error !== 'string' || !payload.error.includes(exports.ANSWER_INPUT_LOST))
+        return false;
+    return !(await (0, server_capabilities_1.serverReportsPromptAnswerReason)(client));
+}
+/**
+ * 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 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 \`${(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);
+}
 /**
  * Issue #3125: what `--plan-review` takes. Restated rather than imported from
  * `src/lib` (the CLI build does not reach it); the server validates the same set.
@@ -134,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
@@ -221,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,
@@ -244,6 +289,15 @@ function reportFailedResponse(result, worktreeId, answer, useDefault, options) {
             'The dialog is still open; answer it in the terminal.');
         process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
     }
+    // Issue #3975: the answer waited for another input on the session and was
+    // then not typed. Nothing reached the pane, so — unlike the "may not have
+    // been applied" reasons below — trying again is safe.
+    if (reason === exports.ANSWER_NOT_DELIVERED) {
+        console.error(`Error: Answer was not sent. Reason: ${reason}${result.message ? ` (${result.message})` : ''}. ` +
+            'Nothing was typed, so it is safe to run respond again.');
+        process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+        return;
+    }
     if (refusedBeforeSending) {
         console.error(`Error: Answer was not sent. Reason: ${reason}${result.message ? ` (${result.message})` : ''}`);
         // Issue #2583: the operator who lands here typed WORDS at a dialog
@@ -256,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 {
@@ -270,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
@@ -282,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':
@@ -306,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;
@@ -413,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
@@ -445,14 +500,24 @@ Strict respond (--expect-screen <kind> --observation <token> <label>):
                     result = outcome;
             }
             if (result === null) {
-                result = await client.post(`/api/worktrees/${worktreeId}/prompt-response`, body);
+                try {
+                    result = await client.post(`/api/worktrees/${worktreeId}/prompt-response`, body);
+                }
+                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 (!(await isAnswerInputLost(error, client)))
+                        throw error;
+                    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.
@@ -460,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;AAyXpC,wBAAgB,iBAAiB,IAAI,OAAO,CA+J3C"}
+{"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.
@@ -405,9 +408,9 @@ worktree and send a short message that tells the agent to read that file.
             // between the send and the ledger row — the completion trigger reads the
             // ledger, and a row that does not exist yet is a reply nobody collects.
             // A refusal exits 2 here, having sent nothing.
-            let relayId;
+            let relay;
             if (options.replyTo) {
-                relayId = await (0, message_dispatch_1.registerRelayForMessage)(client, {
+                relay = await (0, message_dispatch_1.registerRelayForMessage)(client, {
                     worktreeId,
                     replyTo: options.replyTo,
                     instance: options.instance,
@@ -418,13 +421,16 @@ worktree and send a short message that tells the agent to read that file.
                 // (it prints the task id there), and two commands writing two ids to
                 // one stream is how a `$(…)` capture ends up with both. `ask --async`
                 // is the form that hands the relay id back on stdout.
-                console.error(`Relay registered: ${relayId}`);
+                console.error(`Relay registered: ${relay.id}`);
             }
             const sendBody = buildSendBody(content, agent, instanceId, options);
+            // Issue #3957: a bound relay's id rides on the send, which reserves it
+            // and records where the body went in.
             await (0, message_dispatch_1.postMessage)(client, worktreeId, sendBody, {
-                relayId,
+                relay,
                 onFailure: failTask,
-                promptWaitingFallback: promptWaitingFallback(worktreeId),
+                promptWaitingFallback: promptWaitingFallback(worktreeId, commandTarget),
+                target: commandTarget,
             });
             console.error('Message sent.');
             if (taskId) {

package/dist/cli/commands/wait-hook-stop-settle.d.ts

@@ -0,0 +1,66 @@
+/**
+ * wait Command - re-reading the pane after a hook_stop (Issue #3956)
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+import type { CurrentOutputResponse } from '../types/api-responses';
+import type { PollContext, PollState } from './wait-poll-state';
+/**
+ * Interval between the re-reads of the pane after a `hook_stop`, under
+ * `--fail-on-upstream-fault` (Issue #3956). See {@link settleAfterHookStop}.
+ */
+export declare const HOOK_STOP_SETTLE_INTERVAL_MS = 500;
+/**
+ * Longest `wait` re-reads the pane after a `hook_stop` before judging the last
+ * frame it read (Issue #3956). See {@link settleAfterHookStop}.
+ */
+export declare const HOOK_STOP_SETTLE_MAX_MS = 5000;
+/**
+ * The path {@link settleAfterHookStop} re-reads the pane on (Issue #3956):
+ * `?fresh=1` past the server's capture cache, whose 5 s TTL would otherwise
+ * answer two reads 500 ms apart with the same capture and read a pane still
+ * drawing as settled. A server older than the parameter ignores it and answers
+ * as before, from the cache.
+ */
+export declare function settleCurrentOutputPath(worktreeId: string, instanceId?: string): string;
+/**
+ * The frame a `hook_stop` completion is judged on, once the pane has settled
+ * (Issue #3956).
+ *
+ * The agent's `Stop` can land before its reply is drawn. Measured 2026-10-27 on
+ * codex-cli 0.164.0: `ask` returned on `basis=hook_stop` with the pane ending at
+ * row 441–445 of 480, and the last rows were drawn ~3 s later. An upstream fault
+ * printed at the end of the turn is in those rows, so the frame of the `Stop`
+ * poll can carry no `upstreamFault` while the turn did fail.
+ *
+ * So the pane is read again every {@link HOOK_STOP_SETTLE_INTERVAL_MS} until two
+ * reads in a row carry the same frame, and that frame is the one judged — by
+ * every stage of a poll, not by the fault alone: {@link pollWorktree} judges it
+ * as the next poll, so a prompt or a new turn drawn meanwhile is read as one.
+ * The bound is {@link HOOK_STOP_SETTLE_MAX_MS}: no re-read starts after it, and
+ * a pane still drawing then is judged on the last frame read rather than held.
+ * The re-reads ask for a fresh capture ({@link settleCurrentOutputPath}); the
+ * poll that saw the `Stop` does not.
+ *
+ * `--timeout` / `--stall-timeout` bound it too: no interval is slept that the
+ * next re-read could not finish within, and each re-read is aborted at the
+ * earliest of one interval, the bound and those deadlines — so the verdict
+ * comes at most {@link HOOK_STOP_SETTLE_MAX_MS} after the `Stop` poll. The bound
+ * is `settleDeadline`, set by {@link readyStage} when it reads the `Stop` poll and
+ * shared with the ledger read of {@link faultFrameHasStop}, so time spent there
+ * is not given again here. A re-read that is aborted or
+ * fails ends the settle on the frame before it (an `ApiError` that is not an
+ * abort still ends the wait, as on any poll). Frames that change count as
+ * activity for `--stall-timeout`, as on any poll.
+ */
+export declare function settleAfterHookStop<T extends CurrentOutputResponse>(poll: PollContext, state: PollState, data: T, settleDeadline: number): Promise<T>;
+/**
+ * Whether the agent has reported the end of the turn on a frame that carries an
+ * upstream fault, so that frame is judged once settled (Issue #3956).
+ *
+ * The same two records {@link readyCompletionBasis} reads as `hook_stop`: a
+ * `Stop` at or after the adopted turn, or — with no turn adopted — a `Stop`
+ * after the newest prompt in the chat ledger. Neither is #1839's case (back at
+ * the composer with no `Stop`), whose fault is reported on the spot as before.
+ */
+export declare function faultFrameHasStop(poll: PollContext, state: PollState, data: CurrentOutputResponse, settleDeadline: number): Promise<boolean>;
+//# sourceMappingURL=wait-hook-stop-settle.d.ts.map

package/dist/cli/commands/wait-hook-stop-settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-hook-stop-settle.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait-hook-stop-settle.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAGpE,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAUhE;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,qBAAqB,EACvE,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,CAAC,EACP,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,CAAC,CAAC,CAyDZ;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,qBAAqB,EAC3B,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,OAAO,CAAC,CAuBlB"}

package/dist/cli/commands/wait-hook-stop-settle.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * wait Command - re-reading the pane after a hook_stop (Issue #3956)
+ * Issue #3964: split out of wait.ts; wait.ts re-exports what it exported.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_STOP_SETTLE_MAX_MS = exports.HOOK_STOP_SETTLE_INTERVAL_MS = void 0;
+exports.settleCurrentOutputPath = settleCurrentOutputPath;
+exports.settleAfterHookStop = settleAfterHookStop;
+exports.faultFrameHasStop = faultFrameHasStop;
+const api_client_1 = require("../utils/api-client");
+const prompt_1 = require("./prompt");
+const wait_timing_1 = require("./wait-timing");
+const wait_turn_boundary_1 = require("./wait-turn-boundary");
+/**
+ * Interval between the re-reads of the pane after a `hook_stop`, under
+ * `--fail-on-upstream-fault` (Issue #3956). See {@link settleAfterHookStop}.
+ */
+exports.HOOK_STOP_SETTLE_INTERVAL_MS = 500;
+/**
+ * Longest `wait` re-reads the pane after a `hook_stop` before judging the last
+ * frame it read (Issue #3956). See {@link settleAfterHookStop}.
+ */
+exports.HOOK_STOP_SETTLE_MAX_MS = 5000;
+/**
+ * The path {@link settleAfterHookStop} re-reads the pane on (Issue #3956):
+ * `?fresh=1` past the server's capture cache, whose 5 s TTL would otherwise
+ * answer two reads 500 ms apart with the same capture and read a pane still
+ * drawing as settled. A server older than the parameter ignores it and answers
+ * as before, from the cache.
+ */
+function settleCurrentOutputPath(worktreeId, instanceId) {
+    return `${(0, prompt_1.observedCurrentOutputPath)(worktreeId, instanceId)}&fresh=1`;
+}
+/**
+ * The frame a `hook_stop` completion is judged on, once the pane has settled
+ * (Issue #3956).
+ *
+ * The agent's `Stop` can land before its reply is drawn. Measured 2026-10-27 on
+ * codex-cli 0.164.0: `ask` returned on `basis=hook_stop` with the pane ending at
+ * row 441–445 of 480, and the last rows were drawn ~3 s later. An upstream fault
+ * printed at the end of the turn is in those rows, so the frame of the `Stop`
+ * poll can carry no `upstreamFault` while the turn did fail.
+ *
+ * So the pane is read again every {@link HOOK_STOP_SETTLE_INTERVAL_MS} until two
+ * reads in a row carry the same frame, and that frame is the one judged — by
+ * every stage of a poll, not by the fault alone: {@link pollWorktree} judges it
+ * as the next poll, so a prompt or a new turn drawn meanwhile is read as one.
+ * The bound is {@link HOOK_STOP_SETTLE_MAX_MS}: no re-read starts after it, and
+ * a pane still drawing then is judged on the last frame read rather than held.
+ * The re-reads ask for a fresh capture ({@link settleCurrentOutputPath}); the
+ * poll that saw the `Stop` does not.
+ *
+ * `--timeout` / `--stall-timeout` bound it too: no interval is slept that the
+ * next re-read could not finish within, and each re-read is aborted at the
+ * earliest of one interval, the bound and those deadlines — so the verdict
+ * comes at most {@link HOOK_STOP_SETTLE_MAX_MS} after the `Stop` poll. The bound
+ * is `settleDeadline`, set by {@link readyStage} when it reads the `Stop` poll and
+ * shared with the ledger read of {@link faultFrameHasStop}, so time spent there
+ * is not given again here. A re-read that is aborted or
+ * fails ends the settle on the frame before it (an `ApiError` that is not an
+ * abort still ends the wait, as on any poll). Frames that change count as
+ * activity for `--stall-timeout`, as on any poll.
+ */
+async function settleAfterHookStop(poll, state, data, settleDeadline) {
+    const { client, worktreeId, options, startTime } = poll;
+    const frameOf = (d) => d.fullOutput ?? d.content;
+    let latest = data;
+    while (Date.now() + exports.HOOK_STOP_SETTLE_INTERVAL_MS <= settleDeadline) {
+        if ((0, wait_timing_1.msBeforeDeadlines)(options, startTime, state.lastActivityTime, Date.now()) <= exports.HOOK_STOP_SETTLE_INTERVAL_MS) {
+            console.error(`Note: re-reading ${worktreeId} after its stop would pass --timeout/--stall-timeout; ` +
+                'judging the last frame read.');
+            return latest;
+        }
+        await (0, wait_timing_1.sleep)(exports.HOOK_STOP_SETTLE_INTERVAL_MS);
+        const readBudgetMs = Math.min(exports.HOOK_STOP_SETTLE_INTERVAL_MS, settleDeadline - Date.now(), (0, wait_timing_1.msBeforeDeadlines)(options, startTime, state.lastActivityTime, Date.now()));
+        // Past the bound already (a late timer): no read is started.
+        if (readBudgetMs < 0)
+            break;
+        const controller = new AbortController();
+        const abortTimer = setTimeout(() => controller.abort(), readBudgetMs);
+        let next;
+        try {
+            next = await client.get(settleCurrentOutputPath(worktreeId, options.instance), {
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (controller.signal.aborted) {
+                console.error(`Note: ${worktreeId} did not answer a re-read after its stop within ${readBudgetMs}ms; ` +
+                    'judging the last frame read.');
+                return latest;
+            }
+            if (error instanceof api_client_1.ApiError)
+                throw error;
+            console.error(`Note: could not re-read ${worktreeId} after its stop ` +
+                `(${error instanceof Error ? error.message : String(error)}); judging the last frame read.`);
+            return latest;
+        }
+        finally {
+            clearTimeout(abortTimer);
+        }
+        if (next.content !== state.lastContent) {
+            state.lastContent = next.content;
+            state.lastActivityTime = Date.now();
+        }
+        const settled = frameOf(next) === frameOf(latest);
+        latest = next;
+        if (settled)
+            return latest;
+    }
+    console.error(`Note: ${worktreeId} was still drawing ${exports.HOOK_STOP_SETTLE_MAX_MS / 1000}s after its stop; ` +
+        'judging the last frame read.');
+    return latest;
+}
+/**
+ * Whether the agent has reported the end of the turn on a frame that carries an
+ * upstream fault, so that frame is judged once settled (Issue #3956).
+ *
+ * The same two records {@link readyCompletionBasis} reads as `hook_stop`: a
+ * `Stop` at or after the adopted turn, or — with no turn adopted — a `Stop`
+ * after the newest prompt in the chat ledger. Neither is #1839's case (back at
+ * the composer with no `Stop`), whose fault is reported on the spot as before.
+ */
+async function faultFrameHasStop(poll, state, data, settleDeadline) {
+    if (state.turnStartedAt !== null)
+        return (0, wait_turn_boundary_1.turnSettled)(data, state.turnStartedAt);
+    // No `Stop` on record at all: nothing the ledger says could make one, so it
+    // is not asked and the fault is reported on the spot.
+    if (data.lastStopEventAt == null)
+        return false;
+    if (!state.promptLedgerReadable || !(0, wait_turn_boundary_1.reportsTurnBoundaries)(data))
+        return false;
+    // Bounded like the settle it decides on: a ledger that does not answer must
+    // not hold an exit 11 past --timeout, nor without one past the settle's bound.
+    const budgetMs = Math.min(settleDeadline - Date.now(), (0, wait_timing_1.msBeforeDeadlines)(poll.options, poll.startTime, state.lastActivityTime, Date.now()));
+    if (budgetMs <= 0)
+        return false;
+    const controller = new AbortController();
+    const abortTimer = setTimeout(() => controller.abort(), budgetMs);
+    let ledger;
+    try {
+        ledger = await (0, wait_turn_boundary_1.readNewestPromptAt)(poll.client, poll.worktreeId, poll.options, data, controller.signal);
+    }
+    finally {
+        clearTimeout(abortTimer);
+    }
+    state.promptLedgerReadable = ledger.readable;
+    return ledger.readable && ledger.submittedAt !== null && !(0, wait_turn_boundary_1.outstandingPrompt)(data, ledger.submittedAt);
+}

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

@@ -0,0 +1,29 @@
+/**
+ * wait Command - resolving --instance per worktree (Issue #2376)
+ * Issue #3964: split out of wait.ts.
+ */
+import type { WaitOptions } from '../types';
+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).
+ *
+ * `wait` polls `/current-output?instance=`, which matches instance IDs and
+ * nothing else, so an alias that reached it would filter to no session and the
+ * wait would report on the worktree default instead — the exact silent
+ * wrong-session failure Issue #1638 catalogued for `--agent`.
+ *
+ * @param client - API client
+ * @param worktreeId - Worktree the selector is resolved against
+ * @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

@@ -0,0 +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,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

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * wait Command - resolving --instance per worktree (Issue #2376)
+ * Issue #3964: split out of wait.ts.
+ */
+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).
+ *
+ * `wait` polls `/current-output?instance=`, which matches instance IDs and
+ * nothing else, so an alias that reached it would filter to no session and the
+ * wait would report on the worktree default instead — the exact silent
+ * wrong-session failure Issue #1638 catalogued for `--agent`.
+ *
+ * @param client - API client
+ * @param worktreeId - Worktree the selector is resolved against
+ * @param options - The options as given
+ */
+async function resolveWaitInstance(client, worktreeId, options) {
+    if (!options.instance)
+        return options;
+    try {
+        const target = await (0, instances_1.resolveInstanceTarget)(client, worktreeId, options.instance, undefined);
+        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
+        // be reached costs alias support for this call and nothing else. Failing
+        // instead would turn a reachable session into a non-zero exit for an
+        // orchestrator that has been waiting on it correctly for two years.
+        console.error(`Warning: could not resolve --instance '${options.instance}' `
+            + `(${(0, types_1.getErrorMessage)(error)}); using it as an instance id.`);
+        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);
+}