commandmate 0.48.0 → 0.49.1

package/dist/cli/commands/relays.js

@@ -3,6 +3,7 @@
  * relays Command - the standing delegations this machine is holding (#2377)
  *
  *   commandmate relays [--worktree <id>] [--instance <id|alias>] [--json]
+ *   commandmate relays --id <relay-id> [--json]   (Issue #3957: one relay, open or closed)
  *   commandmate relays cancel <relay-id>
  *
  * ## Why a command and not a flag on `ls`
@@ -26,11 +27,12 @@
  * two commands from resolving `self` two different ways.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALLOW_RELAY_CHAIN_DESCRIPTION = exports.REPLY_TO_OPTION_DESCRIPTION = exports.RELAY_REFUSAL_CODES = void 0;
+exports.LEGACY_RELAY_NOTICE = exports.ALLOW_RELAY_CHAIN_DESCRIPTION = exports.REPLY_TO_OPTION_DESCRIPTION = exports.RELAY_REFUSAL_CODES = void 0;
 exports.resolveRelayEndpoint = resolveRelayEndpoint;
 exports.resolveEndpointForWorktree = resolveEndpointForWorktree;
 exports.registerRelay = registerRelay;
 exports.cancelRelayQuietly = cancelRelayQuietly;
+exports.printRelayUnconfirmedNotice = printRelayUnconfirmedNotice;
 exports.createRelaysCommand = createRelaysCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -133,6 +135,9 @@ async function resolveEndpointForWorktree(client, worktreeId, selector, requeste
     }
     return { worktreeId, instanceId };
 }
+/** The one line an older server's relay gets on stderr (Issue #3957). */
+exports.LEGACY_RELAY_NOTICE = 'Note: this server does not tie a relay to its send (legacy handling); '
+    + 'the reply is taken from the first turn that ends after the relay was opened.';
 /**
  * Open a relay, printing the server's own refusal and exiting 2 on one.
  *
@@ -140,7 +145,11 @@ async function resolveEndpointForWorktree(client, worktreeId, selector, requeste
  * change (drop the flag, cancel the other relay, stop forwarding), which is what
  * `CONFIG_ERROR` means everywhere else in this CLI.
  *
- * @returns The relay id
+ * Issue #3957: asks for `bind: true` and believes it only when the answer says
+ * `bindMode: 'bound'`. A server that does not know the flag answers without
+ * the key; the relay is then the legacy kind and its id is not sent along.
+ *
+ * @returns The relay id, and whether it is bound
  */
 async function registerRelay(client, input) {
     try {
@@ -148,8 +157,12 @@ async function registerRelay(client, input) {
             from: input.from,
             to: input.to,
             allowRelayChain: input.allowRelayChain === true,
+            bind: true,
         });
-        return response.relay.id;
+        const bound = (response.bindMode ?? response.relay.bindMode) === 'bound';
+        if (!bound)
+            console.error(exports.LEGACY_RELAY_NOTICE);
+        return { id: response.relay.id, bound };
     }
     catch (error) {
         if (error instanceof api_client_1.ApiError && error.apiCode && exports.RELAY_REFUSAL_CODES.has(error.apiCode)) {
@@ -174,17 +187,51 @@ async function cancelRelayQuietly(client, relayId) {
         console.error(`Warning: could not withdraw relay ${relayId}; it will expire on its own.`);
     }
 }
+/**
+ * Print where a relay whose send could not be confirmed stands (Issue #3957).
+ *
+ * The relay is left open — withdrawing it would drop a reply that may well be
+ * on its way — and the message is not resent, which could make it arrive twice.
+ */
+function printRelayUnconfirmedNotice(relayId, worktreeId) {
+    // Issue #3992: a failed send names the pane to look at before any resend, in
+    // the same line rather than a second notice.
+    const resend = worktreeId === undefined
+        ? ''
+        : ` Do not resend before checking the pane (\`commandmate capture ${worktreeId} --pane\`), or it may arrive twice.`;
+    console.error(`Warning: whether the message reached the session is not known; relay ${relayId} was left open `
+        + 'and the message was not resent. '
+        + `Check it with \`commandmate relays --id ${relayId}\`.${resend}`);
+}
 function endpointLabel(endpoint) {
     return `${endpoint.worktreeId}/${endpoint.instanceId}`;
 }
 function printRelayLine(relay) {
-    console.log([
+    const fields = [
         relay.id,
         relay.state,
         `${endpointLabel(relay.from)} <- ${endpointLabel(relay.to)}`,
         `hops=${relay.hops}`,
         `expires=${new Date(relay.expiresAt).toISOString()}`,
-    ].join('\t'));
+    ];
+    // Issue #3957: a bound relay's send state, overlap and hold reason, when it
+    // has them. Absent on a legacy relay and on an older server.
+    if (relay.sendState)
+        fields.push(`send=${relay.sendState}`);
+    if (relay.overlap)
+        fields.push(`overlap=${relay.overlap}`);
+    if (relay.holdReason)
+        fields.push(`hold=${relay.holdReason}`);
+    console.log(fields.join('\t'));
+}
+/** `relays --id <id>`: one relay, whatever its state (Issue #3957). */
+async function showOneRelay(client, relayId, json) {
+    const response = await client.get(`/api/relays/${relayId}`);
+    if (json) {
+        console.log(JSON.stringify(response, null, 2));
+        return;
+    }
+    printRelayLine(response.relay);
 }
 function createRelaysCommand() {
     const cmd = new commander_1.Command('relays');
@@ -192,18 +239,35 @@ function createRelaysCommand() {
         .description('List the open relays this session is waiting on and owes')
         .option('--worktree <id>', 'Worktree to list (defaults to the session running this command)')
         .option('--instance <id>', 'Agent instance inside --worktree (id or roster alias)')
+        .option('--id <relay-id>', 'Show one relay, open or closed (its send state, overlap and hold reason)')
         .option('--json', 'JSON output')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .addHelpText('after', `
 Columns: <relay-id>  <state>  <requester> <- <worker>  hops=<n>  expires=<iso>
+         [send=<state>]  [overlap=<none|later|earlier|both|unknown>]  [hold=<reason>]
 
 States: pending (the worker has not finished), prompt (it stopped on a
 confirmation and the requester was told), delivered / expired / cancelled.
 
+send= / overlap= / hold= appear on a relay tied to its send (Issue #3957):
+send= is awaiting / input_started / sent / failed / unknown; hold= says why a
+relay is not being answered (send_unknown, dispatch_unknown, generation_changed,
+server_restarted, ...); overlap= says the reply may share a turn with another
+request (unknown is not "none"). \`--id <relay-id>\` shows one relay even after
+it closed.
+
 Withdraw one with \`commandmate relays cancel <relay-id>\`.
 `)
         .action(async (options) => {
         try {
+            if (options.id !== undefined) {
+                if (!RELAY_ID_PATTERN.test(options.id)) {
+                    console.error('Error: Invalid relay ID format.');
+                    process.exit(types_1.ExitCode.CONFIG_ERROR);
+                }
+                await showOneRelay(new api_client_1.ApiClient({ token: options.token }), options.id, options.json === true);
+                return;
+            }
             if (options.worktree && !(0, api_client_1.isValidWorktreeId)(options.worktree)) {
                 console.error('Error: Invalid worktree ID format.');
                 process.exit(types_1.ExitCode.CONFIG_ERROR);

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

@@ -5,5 +5,17 @@
  * Uses prompt-response API (not respond API) [DR2-06]
  */
 import { Command } from 'commander';
+/**
+ * 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.
+ */
+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`).
+ */
+export declare const ANSWER_INPUT_LOST = "answer_input_lost";
 export declare function createRespondCommand(): Command;
 //# sourceMappingURL=respond.d.ts.map

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;AAgbpC,wBAAgB,oBAAoB,IAAI,OAAO,CAmI9C"}
+{"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"}

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");
@@ -125,6 +126,48 @@ 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. `/prompt-response` answers it as a 500 whose `error` carries this
+ * code. 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) {
+    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);
+}
+/**
+ * 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.
+ */
+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.`);
+    // 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.
@@ -244,6 +287,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
@@ -445,7 +497,17 @@ 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 (!isAnswerInputLost(error))
+                        throw error;
+                    reportAnswerInputLost(worktreeId, { agent, instanceId });
+                    return;
+                }
             }
             if (result && !result.success) {
                 reportFailedResponse(result, worktreeId, answer, useDefault, options);

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;AA4XpC,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;AA0XpC,wBAAgB,iBAAiB,IAAI,OAAO,CAiK3C"}

package/dist/cli/commands/send.js

@@ -19,8 +19,6 @@ const command_target_1 = require("./command-target");
 const auto_yes_1 = require("./auto-yes");
 const relays_1 = require("./relays");
 const message_dispatch_1 = require("./message-dispatch");
-/** Auto-yes duration used when --duration is omitted. */
-const DEFAULT_AUTO_YES_DURATION = '1h';
 /**
  * The message length `send` is verified to deliver whole (Issue #2464): the
  * largest body sent through the paste path to claude, codex, command-code and
@@ -49,9 +47,9 @@ function promptWaitingFallback(worktreeId) {
  * behind for a message that was never sent.
  */
 function resolveAutoYesDurationMs(duration) {
-    const durationMs = (0, duration_constants_1.parseDurationToMs)(duration ?? DEFAULT_AUTO_YES_DURATION);
+    const durationMs = (0, duration_constants_1.parseDurationToMs)(duration ?? duration_constants_1.DEFAULT_DURATION_FLAG);
     if (durationMs === null) {
-        console.error(`Error: Invalid duration. Must be one of: ${duration_constants_1.ALLOWED_DURATIONS.join(', ')}`);
+        console.error(`Error: Invalid duration. Must be ${duration_constants_1.AUTO_YES_DURATION_FLAG_RANGE} (e.g. 5h).`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
     return durationMs;
@@ -244,7 +242,7 @@ function validateSendArgs(worktreeId, message, options) {
     // Issue #1608: every option that can be judged from its own value is
     // judged here, before the first side effect. --duration used to be the
     // exception: enableAutoYes() validated it, and that runs after
-    // --contract has already created the task row, so `--duration 2h` left
+    // --contract has already created the task row, so `--duration 25h` left
     // a `pending` task for a message that was never sent. Validated
     // unconditionally, like --stop-pattern and --model above: a value the
     // CLI cannot honour is an error whether or not --auto-yes accompanies it.
@@ -317,7 +315,7 @@ function createSendCommand() {
         + ' flag: it applies only when this send starts the session, and a running session answers 400')
         .option('--auto-yes', 'Enable auto-yes before sending (session-wide, no policy guard; for unattended runs prefer --contract with an autoYes policy)')
         .option('--auto-yes-answer-mode <mode>', `With --auto-yes: ${auto_yes_1.ANSWER_MODE_OPTION_DESCRIPTION}`)
-        .option('--duration <duration>', `Auto-yes duration (${duration_constants_1.ALLOWED_DURATIONS.join(', ')})`)
+        .option('--duration <duration>', `Auto-yes duration (${duration_constants_1.AUTO_YES_DURATION_FLAG_RANGE}, e.g. 1h, 3h, 8h; default ${duration_constants_1.DEFAULT_DURATION_FLAG})`)
         .option('--stop-pattern <pattern>', 'Auto-yes stop pattern (regex). Matched against terminal output; cannot block commands (use the task contract\'s autoYes.denyPatterns for that)')
         .option('--contract <path>', 'Execution contract path relative to the worktree root (e.g. .commandmate/tasks/my-task.yaml). Records a task and sends the contract preamble plus its goal.')
         .option('--ignore-structured-prompt', 'Send even if only the agent\'s hooks report an open dialog (Issue #1737). Use when the pane looks idle but sends are refused; a prompt visible in the terminal is still refused.')
@@ -407,9 +405,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,
@@ -420,11 +418,13 @@ 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),
             });

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

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,OAAO,KAAK,EAMV,uBAAuB,EAExB,MAAM,wBAAwB,CAAC;AAsChC;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,uBAAuB,GAAG,IAAI,CA8BrG;AAyED,wBAAgB,mBAAmB,IAAI,OAAO,CAsE7C"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,OAAO,KAAK,EAMV,uBAAuB,EAExB,MAAM,wBAAwB,CAAC;AAuChC;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,uBAAuB,GAAG,IAAI,CA8BrG;AAkFD,wBAAgB,mBAAmB,IAAI,OAAO,CAsE7C"}

package/dist/cli/commands/verify.js

@@ -156,13 +156,20 @@ function inheritedFlag(own, command, key) {
  * The run id leads the line even though it is not in the requested field list:
  * without it there is no way to reach `verify show`, which is the only reason
  * to read this listing in the first place.
+ *
+ * Gates that carry `timing` (#3884) are named after the verdict with their
+ * waits and execution apart (#3909), so "this run took 40 minutes" can be read
+ * as a queue, a lock or a slow suite without opening every run. A run none of
+ * whose gates waited keeps the line it always had.
  */
 function formatHistoryLine(run) {
     const failed = run.gates
         .filter((gate) => FAILED_GATE_STATUSES.has(gate.status))
         .map((gate) => gate.gateId);
     const suffix = failed.length > 0 ? `  failed: ${failed.join(',')}` : '';
-    return `#${run.id}  ${run.startedAt}  ${run.worktreeId}  ${run.trigger}  ${run.status}${suffix}`;
+    const timed = run.gates.flatMap((gate) => gate.timing ? [`${gate.gateId}(${(0, verify_runner_1.formatGateTiming)(gate.timing, ' ')})`] : []);
+    const timing = timed.length > 0 ? `  timing: ${timed.join(' ')}` : '';
+    return `#${run.id}  ${run.startedAt}  ${run.worktreeId}  ${run.trigger}  ${run.status}${suffix}${timing}`;
 }
 function createVerifyCommand() {
     const cmd = new commander_1.Command('verify');

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,21 @@
+/**
+ * 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';
+/**
+ * `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>;
+//# 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,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"}

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

@@ -0,0 +1,41 @@
+"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;
+const types_1 = require("../types");
+const instances_1 = require("./instances");
+/**
+ * `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) {
+        // 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;
+    }
+}