commandmate 0.49.1 → 0.49.3

package/dist/cli/commands/attach.js

@@ -44,6 +44,8 @@ const cli_tool_ids_1 = require("../config/cli-tool-ids");
 const agent_target_options_1 = require("../config/agent-target-options");
 const session_target_1 = require("../utils/session-target");
 const agent_instances_1 = require("../utils/agent-instances");
+const follow_up_command_1 = require("../utils/follow-up-command");
+const command_target_1 = require("./command-target");
 const session_name_1 = require("../../lib/cli-tools/session-name");
 const validation_1 = require("../../lib/cli-tools/validation");
 const tmux_session_surface_1 = require("../../lib/session/tmux-session-surface");
@@ -71,9 +73,14 @@ async function resolveTarget(client, worktreeId, options) {
         console.error(`Error: ${(0, session_target_1.describeSessionTargetConflict)(target.conflict)}`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
+    const cliToolId = target.cliToolId ?? options.agent ?? cli_tool_ids_1.DEFAULT_CLI_TOOL_ID;
+    const instanceId = target.instanceId ?? options.instance;
     return {
-        cliToolId: target.cliToolId ?? options.agent ?? cli_tool_ids_1.DEFAULT_CLI_TOOL_ID,
-        instanceId: target.instanceId ?? options.instance,
+        cliToolId,
+        instanceId,
+        // Issue #3982: what the hints name — the instance only when one was asked
+        // for (the server echoes the default instance otherwise), as `resolveCommandTarget`.
+        commandTarget: (0, command_target_1.commandTargetOf)(options.instance ? { cliToolId, instanceId } : null, options.agent),
     };
 }
 /**
@@ -233,18 +240,22 @@ function planGuardedAttach(ownership, sessionName, options) {
  * @param cliToolId - Resolved CLI tool
  * @param worktreeId - Worktree id, so the hint's commands are copy-pasteable
  * @param sessionName - Resolved tmux session name
- * @param options - The flags as given
+ * @param options - The flags as given; `target` is the resolved target the
+ *   `capture` hints name (Issue #3982), none when absent
  */
 function buildAttachHints(cliToolId, worktreeId, sessionName, options) {
+    const capture = (flags) => options.target
+        ? (0, follow_up_command_1.followUpCommand)('capture', worktreeId, options.target, undefined, flags)
+        : `commandmate capture ${worktreeId} ${flags}`;
     const hints = [`Attaching to ${sessionName} (${cliToolId}). Detach with Ctrl+b then d.`];
     if ((0, tmux_session_surface_1.usesAltScreen)(cliToolId) && !options.live) {
-        hints.push(`${cliToolId} draws its transcript at the top of a 200x1000 canvas and its composer at the`, 'bottom, and tmux follows the cursor — so this attach shows the composer and blank rows,', 'not the conversation. To read it:', `  prefix + g                                     popup, in this terminal`, `  commandmate capture ${worktreeId} --pane --tail 60   without attaching`, `  commandmate capture ${worktreeId} --pane --follow    live, without attaching`);
+        hints.push(`${cliToolId} draws its transcript at the top of a 200x1000 canvas and its composer at the`, 'bottom, and tmux follows the cursor — so this attach shows the composer and blank rows,', 'not the conversation. To read it:', `  prefix + g                                     popup, in this terminal`, `  ${capture('--pane --tail 60')}   without attaching`, `  ${capture('--pane --follow')}    live, without attaching`);
         if ((0, tmux_session_surface_1.isLiveAttachSupported)(cliToolId)) {
             hints.push(`  commandmate attach ${worktreeId} --live               re-lay-out to this terminal`);
         }
     }
     if (options.readOnly) {
-        hints.push('Read-only attach: tmux delivers no keys but the detach one, so prefix + g does NOT open', 'the popup here. Read with `commandmate capture <id> --pane --follow` in another terminal.');
+        hints.push('Read-only attach: tmux delivers no keys but the detach one, so prefix + g does NOT open', `the popup here. Read with \`${capture('--pane --follow')}\` in another terminal.`);
     }
     if (options.live) {
         hints.push('Live attach: this session follows THIS terminal until you detach, then goes back to', '200x1000. The web terminal shows the smaller frame while you are attached.');
@@ -322,11 +333,11 @@ function createAttachCommand() {
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
             const client = new api_client_1.ApiClient({ token: options.token });
-            const { cliToolId, instanceId } = await resolveTarget(client, worktreeId, options);
+            const { cliToolId, instanceId, commandTarget } = await resolveTarget(client, worktreeId, options);
             if (options.live && !(0, tmux_session_surface_1.isLiveAttachSupported)(cliToolId)) {
                 console.error(`Error: --live is not supported for ${cliToolId}. It is claude-only until each other `
                     + "agent's detection rules are re-measured at a terminal-sized pane (Issue #2317). "
-                    + `Attach without it, or read with: commandmate capture ${worktreeId} --pane --follow`);
+                    + `Attach without it, or read with: ${(0, follow_up_command_1.followUpCommand)('capture', worktreeId, commandTarget, undefined, '--pane --follow')}`);
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
             const target = await resolveAttachSessionName(client, worktreeId, cliToolId, instanceId);
@@ -357,6 +368,7 @@ function createAttachCommand() {
             for (const line of buildAttachHints(cliToolId, worktreeId, sessionName, {
                 readOnly,
                 live: options.live,
+                target: commandTarget,
             })) {
                 console.error(line);
             }

package/dist/cli/commands/command-target.d.ts

@@ -20,4 +20,11 @@ export interface CommandTarget {
  * @param mode - Passed on only when given, so the call shape stays as it was
  */
 export declare function resolveCommandTarget(client: ApiClient, worktreeId: string, selector: string | undefined, requestedAgent: string | undefined, mode?: InstanceConflictMode): Promise<CommandTarget>;
+/**
+ * The {@link CommandTarget} for a target resolved some other way (Issue #3982:
+ * `attach` and `wait` resolve their own), by the same rule as above.
+ *
+ * @param target - The resolved instance, or null when no selector was given
+ */
+export declare function commandTargetOf(target: ResolvedInstanceTarget | null, requestedAgent: string | undefined): CommandTarget;
 //# sourceMappingURL=command-target.d.ts.map

package/dist/cli/commands/command-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-target.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/command-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,aAAa,CAAC,CASxB"}
+{"version":3,"file":"command-target.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/command-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,sBAAsB,GAAG,IAAI,EACrC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,aAAa,CAIf"}

package/dist/cli/commands/command-target.js

@@ -8,6 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveCommandTarget = resolveCommandTarget;
+exports.commandTargetOf = commandTargetOf;
 const instances_1 = require("./instances");
 /**
  * @param selector - Falsy means "no instance": nothing is requested of the server
@@ -19,6 +20,15 @@ async function resolveCommandTarget(client, worktreeId, selector, requestedAgent
             ? await (0, instances_1.resolveInstanceTarget)(client, worktreeId, selector, requestedAgent)
             : await (0, instances_1.resolveInstanceTarget)(client, worktreeId, selector, requestedAgent, mode)
         : null;
+    return commandTargetOf(target, requestedAgent);
+}
+/**
+ * The {@link CommandTarget} for a target resolved some other way (Issue #3982:
+ * `attach` and `wait` resolve their own), by the same rule as above.
+ *
+ * @param target - The resolved instance, or null when no selector was given
+ */
+function commandTargetOf(target, requestedAgent) {
     const agent = target ? target.cliToolId : requestedAgent;
     const instanceId = target?.instanceId;
     return { target, agent, instanceId };

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

@@ -1 +1 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAkD,MAAM,qBAAqB,CAAC;AAsKhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAE6D,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,QAE0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAmCjC;AAqUD,wBAAgB,sBAAsB,IAAI,OAAO,CAgFhD"}
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAkD,MAAM,qBAAqB,CAAC;AA4KhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAE6D,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,QAE0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAmCjC;AAsWD,wBAAgB,sBAAsB,IAAI,OAAO,CAgFhD"}

package/dist/cli/commands/instances.js

@@ -26,6 +26,9 @@ const session_target_1 = require("../utils/session-target");
 // "the worktree id is wrong", and only the session's own identity can tell them
 // apart.
 const whoami_1 = require("./whoami");
+// Issue #3993: each kill is recorded so the env-clean gate can tell a sibling
+// session the orchestrator stopped from one a worker killed.
+const session_kill_ledger_1 = require("../../lib/verification/session-kill-ledger");
 // Issue #2317: the tmux session name each instance runs in, so `commandmate
 // attach` / `tmux attach` need no hand-assembly of `mcbd-<tool>-<wt>[-<suffix>]`.
 const session_name_1 = require("../../lib/cli-tools/session-name");
@@ -388,6 +391,37 @@ async function addInstance(client, worktreeId, options) {
         console.log(JSON.stringify(next, null, 2));
     }
 }
+/**
+ * Record a successful kill in the session-kill ledger (Issue #3993): which
+ * worktree and instance, the tmux sessions the server says it stopped
+ * (`killedSessions` of the kill-session response), and who asked — this
+ * process's cwd and tmux session. A response without `killedSessions` (an
+ * older server) records no session, which excuses nothing.
+ * Best effort: the ledger never fails the command, the kill already happened.
+ */
+function recordSessionKill(worktreeId, instanceId, response) {
+    let callerCwd;
+    try {
+        callerCwd = process.cwd();
+    }
+    catch {
+        callerCwd = null;
+    }
+    const killed = response?.killedSessions;
+    (0, session_kill_ledger_1.appendSessionKillRecord)({
+        version: session_kill_ledger_1.SESSION_KILL_LEDGER_VERSION,
+        at: Date.now(),
+        api: 'kill-session',
+        origin: 'cli',
+        worktreeId,
+        instanceId,
+        sessionNames: Array.isArray(killed)
+            ? killed.filter((name) => typeof name === 'string')
+            : [],
+        callerCwd,
+        callerSession: (0, whoami_1.readTmuxSessionName)(),
+    });
+}
 /**
  * Remove action: drop an instance from the roster. Kills the session first
  * (when --kill) so the server can still resolve its CLI tool from the roster.
@@ -408,7 +442,8 @@ async function removeInstance(client, worktreeId, instanceId, options) {
     }
     if (options.kill) {
         try {
-            await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+            const killResponse = await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+            recordSessionKill(worktreeId, instanceId, killResponse);
             console.error(`Session killed: ${instanceId}`);
         }
         catch (killError) {
@@ -451,7 +486,8 @@ async function killInstance(client, worktreeId, instanceId) {
         console.error('Error: Invalid instance id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+    const killResponse = await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+    recordSessionKill(worktreeId, instanceId, killResponse);
     console.error(`Session killed: ${instanceId}`);
 }
 /**

package/dist/cli/commands/message-dispatch.d.ts

@@ -8,6 +8,7 @@
  */
 import type { ChatMessage } from '../types/api-responses';
 import { ApiClient } from '../utils/api-client';
+import type { CommandTarget } from './command-target';
 import { type RegisteredRelay } from './relays';
 /**
  * Code the send API returns when the session is blocked on a prompt (Issue
@@ -23,6 +24,13 @@ export interface RegisterRelayForMessageInput {
     instance?: string;
     agent?: string;
     allowRelayChain?: boolean;
+    /**
+     * Issue #3983: the client the two endpoints are resolved with (`ask` passes
+     * its `--timeout`-bounded one). Defaults to `client`. The relay POST itself
+     * always goes through `client`: it creates state, and cutting it would leave
+     * "was the relay opened?" unanswered — the same reason `/send` is not cut.
+     */
+    resolveClient?: ApiClient;
 }
 /** Resolve both endpoints and open the relay; returns its id and whether it is bound. */
 export declare function registerRelayForMessage(client: ApiClient, input: RegisterRelayForMessageInput): Promise<RegisteredRelay>;
@@ -36,13 +44,19 @@ export interface PostMessageOptions {
     onFailure?: () => Promise<void>;
     /** Printed (after `Error: `) when PROMPT_WAITING carried no message body. */
     promptWaitingFallback: string;
+    /** The resolved target the send addressed; the hints name it (Issue #3982). */
+    target: CommandTarget;
 }
 /**
  * What to tell the sender about resending a failed send, from the server's
- * `sendOutcome` on the error (Issue #3992). Null when the error carries none
- * (a send that named no bound relay, an older server) or says `sent`.
+ * `sendOutcome` on the error (Issue #3992). Issue #4011: the route puts it on
+ * every failure recorded as the send's attempt, bound relay or not. Null when
+ * the error carries none (a 400, an older server) or says `sent`.
+ *
+ * @param target - The resolved target, so the `capture` reads the pane the
+ *   message went to (Issue #3982); omitted, the hint names no target
  */
-export declare function describeFailedSendOutcome(error: unknown, worktreeId: string): string | null;
+export declare function describeFailedSendOutcome(error: unknown, worktreeId: string, target?: CommandTarget): string | null;
 /**
  * Post the message; on failure cancel the relay and report PROMPT_WAITING.
  *

package/dist/cli/commands/message-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-dispatch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/message-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAY,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,yFAAyF;AACzF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAwCD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3F;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CA+CtB"}
+{"version":3,"file":"message-dispatch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/message-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAY,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED,yFAAyF;AACzF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,eAAe,CAAC,CAc1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,aAAa,CAAC;CACvB;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAcnH;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CA+CtB"}

package/dist/cli/commands/message-dispatch.js

@@ -14,6 +14,7 @@ exports.describeFailedSendOutcome = describeFailedSendOutcome;
 exports.postMessage = postMessage;
 const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
+const follow_up_command_1 = require("../utils/follow-up-command");
 const relays_1 = require("./relays");
 /**
  * Code the send API returns when the session is blocked on a prompt (Issue
@@ -24,8 +25,9 @@ const relays_1 = require("./relays");
 exports.PROMPT_WAITING_CODE = 'PROMPT_WAITING';
 /** Resolve both endpoints and open the relay; returns its id and whether it is bound. */
 async function registerRelayForMessage(client, input) {
-    const replyEndpoint = await (0, relays_1.resolveRelayEndpoint)(client, input.replyTo);
-    const workerEndpoint = await (0, relays_1.resolveEndpointForWorktree)(client, input.worktreeId, input.instance, input.agent);
+    const resolveClient = input.resolveClient ?? client;
+    const replyEndpoint = await (0, relays_1.resolveRelayEndpoint)(resolveClient, input.replyTo);
+    const workerEndpoint = await (0, relays_1.resolveEndpointForWorktree)(resolveClient, input.worktreeId, input.instance, input.agent);
     return (0, relays_1.registerRelay)(client, {
         from: replyEndpoint,
         to: workerEndpoint,
@@ -69,10 +71,14 @@ async function resolveBoundSendOutcome(client, relayId, error) {
 }
 /**
  * What to tell the sender about resending a failed send, from the server's
- * `sendOutcome` on the error (Issue #3992). Null when the error carries none
- * (a send that named no bound relay, an older server) or says `sent`.
+ * `sendOutcome` on the error (Issue #3992). Issue #4011: the route puts it on
+ * every failure recorded as the send's attempt, bound relay or not. Null when
+ * the error carries none (a 400, an older server) or says `sent`.
+ *
+ * @param target - The resolved target, so the `capture` reads the pane the
+ *   message went to (Issue #3982); omitted, the hint names no target
  */
-function describeFailedSendOutcome(error, worktreeId) {
+function describeFailedSendOutcome(error, worktreeId, target) {
     if (!(error instanceof api_client_1.ApiError))
         return null;
     const outcome = error.payload?.sendOutcome;
@@ -81,7 +87,7 @@ function describeFailedSendOutcome(error, worktreeId) {
     }
     if (outcome === 'unknown') {
         return ('Note: whether the message was sent is not known (sendOutcome=unknown); '
-            + `check the pane first (\`commandmate capture ${worktreeId} --pane\`) and do not resend before that, `
+            + `check the pane first (\`${(0, follow_up_command_1.paneCaptureCommand)(worktreeId, target)}\`) and do not resend before that, `
             + 'or it may arrive twice.');
     }
     return null;
@@ -122,14 +128,14 @@ async function postMessage(client, worktreeId, sendBody, options) {
         }
         else if (relayId && outcome === 'unknown') {
             // Issue #3992: the relay notice carries the "look before resending" hint.
-            (0, relays_1.printRelayUnconfirmedNotice)(relayId, worktreeId);
+            (0, relays_1.printRelayUnconfirmedNotice)(relayId, worktreeId, options.target);
         }
         const promptWaiting = error instanceof api_client_1.ApiError && error.apiCode === exports.PROMPT_WAITING_CODE;
         // Issue #3992: whether it may be sent again, as the server said — not on
         // PROMPT_WAITING, whose own line says to answer the prompt first, and not
         // when the relay notice above already said it.
         if (!promptWaiting && !(relayId && outcome === 'unknown')) {
-            const resendNote = describeFailedSendOutcome(error, worktreeId);
+            const resendNote = describeFailedSendOutcome(error, worktreeId, options.target);
             if (resendNote !== null)
                 console.error(resendNote);
         }

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

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAgB5E;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAW9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAU/G;AA0ED,kDAAkD;AAClD,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAkBxG;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CA8E7C"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAgB5E;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAW9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAU/G;AA0ED,kDAAkD;AAClD,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAkBxG;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CA+E7C"}

package/dist/cli/commands/prompt.js

@@ -184,7 +184,8 @@ lastSend says how the last send to the instance ended: not-sent (no key of the
 message was typed, e.g. prompt not ready), sent, or indeterminate (part of it
 may have been typed). Nothing is resent automatically: resend a not-sent
 message yourself, and do not resend an indeterminate one before checking
-\`capture --pane\`.
+\`capture --pane\`. With overlapping sends it follows the input lock's grant
+order, so it may be another request's outcome, not yours (Issue #4065).
 
 To answer the screen only if it is still this one (Issue #3756):
   commandmate respond <worktree-id> --instance <id> --expect-screen <kind> \\

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

@@ -4,6 +4,8 @@
  *   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>
+ *   commandmate relays resolve <relay-id> --payload <id> --attempt <id> --confirm|--retry|--discard
+ *     (Issue #4082: settle a delivery held as uncertain)
  *
  * ## Why a command and not a flag on `ls`
  *
@@ -27,6 +29,7 @@
  */
 import { Command } from 'commander';
 import { ApiClient } from '../utils/api-client';
+import type { CommandTarget } from './command-target';
 /**
  * The codes `POST /api/relays` refuses with.
  *
@@ -110,6 +113,6 @@ export declare function cancelRelayQuietly(client: ApiClient, relayId: string):
  * 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.
  */
-export declare function printRelayUnconfirmedNotice(relayId: string, worktreeId?: string): void;
+export declare function printRelayUnconfirmedNotice(relayId: string, worktreeId?: string, target?: CommandTarget): void;
 export declare function createRelaysCommand(): Command;
 //# sourceMappingURL=relays.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"relays.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/relays.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,OAAO,EAAE,SAAS,EAA+B,MAAM,qBAAqB,CAAC;AAgB7E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,aAM9B,CAAC;AAEH,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,QAEiD,CAAC;AAE1F,yDAAyD;AACzD,eAAO,MAAM,6BAA6B,QAER,CAAC;AAEnC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAyB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,IAAI,EAAE,gBAAgB,CAAC;IACvB,+BAA+B;IAC/B,EAAE,EAAE,gBAAgB,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,QAEkD,CAAC;AAEnF;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,eAAe,CAAC,CAkB1B;AAED,+EAA+E;AAC/E,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1F;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAWtF;AAwCD,wBAAgB,mBAAmB,IAAI,OAAO,CAuJ7C"}
+{"version":3,"file":"relays.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/relays.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,OAAO,EAAE,SAAS,EAA+B,MAAM,qBAAqB,CAAC;AAI7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AActD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,aAM9B,CAAC;AAEH,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,QAEiD,CAAC;AAE1F,yDAAyD;AACzD,eAAO,MAAM,6BAA6B,QAER,CAAC;AAEnC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAyB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,IAAI,EAAE,gBAAgB,CAAC;IACvB,+BAA+B;IAC/B,EAAE,EAAE,gBAAgB,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,QAEkD,CAAC;AAEnF;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,eAAe,CAAC,CAkB1B;AAED,+EAA+E;AAC/E,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1F;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAW9G;AA0GD,wBAAgB,mBAAmB,IAAI,OAAO,CAoP7C"}

package/dist/cli/commands/relays.js

@@ -5,6 +5,8 @@
  *   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>
+ *   commandmate relays resolve <relay-id> --payload <id> --attempt <id> --confirm|--retry|--discard
+ *     (Issue #4082: settle a delivery held as uncertain)
  *
  * ## Why a command and not a flag on `ls`
  *
@@ -39,6 +41,7 @@ const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const session_target_1 = require("../utils/session-target");
+const follow_up_command_1 = require("../utils/follow-up-command");
 const instances_1 = require("./instances");
 const whoami_1 = require("./whoami");
 /** crypto.randomUUID() output; mirrors RELAY_ID_PATTERN in the API route. */
@@ -193,12 +196,12 @@ async function cancelRelayQuietly(client, relayId) {
  * 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) {
+function printRelayUnconfirmedNotice(relayId, worktreeId, target) {
     // Issue #3992: a failed send names the pane to look at before any resend, in
-    // the same line rather than a second notice.
+    // the same line rather than a second notice. Issue #3982: the target's pane.
     const resend = worktreeId === undefined
         ? ''
-        : ` Do not resend before checking the pane (\`commandmate capture ${worktreeId} --pane\`), or it may arrive twice.`;
+        : ` Do not resend before checking the pane (\`${(0, follow_up_command_1.paneCaptureCommand)(worktreeId, target)}\`), 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}`);
@@ -222,9 +225,36 @@ function printRelayLine(relay) {
         fields.push(`overlap=${relay.overlap}`);
     if (relay.holdReason)
         fields.push(`hold=${relay.holdReason}`);
+    // Issue #4064: a payload whose delivery may have reached the requester. It
+    // is never resent automatically; the pane named is where to look.
+    const delivery = relay.deliveryHold;
+    if (delivery) {
+        fields.push(`delivery=${delivery.state}`);
+        if (delivery.kind)
+            fields.push(`payload=${delivery.kind}:${delivery.payloadId ?? '-'}`);
+        // Issue #4082: what `relays resolve --attempt` names. Absent on an older server.
+        if (delivery.attemptId)
+            fields.push(`attempt=${delivery.attemptId}`);
+        if (delivery.reason)
+            fields.push(`reason=${delivery.reason}`);
+        fields.push(`check=${delivery.checkCommand}`);
+    }
     console.log(fields.join('\t'));
 }
 /** `relays --id <id>`: one relay, whatever its state (Issue #3957). */
+/**
+ * `--json` / `--token` of a `relays` subcommand, the parent's included.
+ *
+ * The parent `relays` declares both options too, and commander gives an
+ * option the parent knows to the parent — `relays --token T resolve …`, and
+ * `relays resolve … --json` likewise — so the subcommand's own `options` never
+ * see it and a token would fall back to `CM_AUTH_TOKEN`. The subcommand's own
+ * value wins when both are given.
+ */
+function subcommandGlobals(options, command) {
+    const all = command.optsWithGlobals();
+    return { json: options.json === true || all.json === true, token: options.token ?? all.token };
+}
 async function showOneRelay(client, relayId, json) {
     const response = await client.get(`/api/relays/${relayId}`);
     if (json) {
@@ -233,6 +263,25 @@ async function showOneRelay(client, relayId, json) {
     }
     printRelayLine(response.relay);
 }
+/** The codes `POST /api/relays/:id/resolve` refuses with (409). Mirrors the route. */
+const RELAY_HOLD_REFUSAL_CODES = new Set([
+    'RELAY_HOLD_NOT_FOUND',
+    'RELAY_HOLD_ATTEMPTING',
+    'RELAY_HOLD_STALE',
+    'RELAY_HOLD_NOT_ALLOWED',
+]);
+/** The one action given, or null when none or more than one was. */
+function resolveAction(options) {
+    const given = ['confirm', 'retry', 'discard'].filter((action) => options[action] === true);
+    return given.length === 1 ? given[0] : null;
+}
+/** What each action prints. `retry` says queued, never delivered. */
+const RESOLVED_MESSAGES = {
+    confirm: (relayId, response) => `Relay ${relayId}: the held payload is recorded as delivered (relay is ${response.relay.state}).`,
+    retry: (relayId) => `Relay ${relayId}: the held payload is queued for delivery again (not delivered yet). `
+        + `Follow it with \`commandmate relays --id ${relayId}\`.`,
+    discard: (relayId, response) => `Relay ${relayId}: the held payload was discarded without sending (relay is ${response.relay.state}).`,
+};
 function createRelaysCommand() {
     const cmd = new commander_1.Command('relays');
     cmd
@@ -245,6 +294,7 @@ function createRelaysCommand() {
         .addHelpText('after', `
 Columns: <relay-id>  <state>  <requester> <- <worker>  hops=<n>  expires=<iso>
          [send=<state>]  [overlap=<none|later|earlier|both|unknown>]  [hold=<reason>]
+         [delivery=<attempting|uncertain>  payload=<kind>:<id>  attempt=<id>  reason=<r>  check=<cmd>]
 
 States: pending (the worker has not finished), prompt (it stopped on a
 confirmation and the requester was told), delivered / expired / cancelled.
@@ -256,6 +306,18 @@ 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.
 
+delivery= (Issue #4064) marks a payload whose delivery to the requester may
+have happened (uncertain: indeterminate, failed after it was sent, or the
+server restarted mid-send). It is NOT resent automatically and the relay's
+later payloads wait behind it. Look at the pane check= names first. Cancelling
+the relay stops later deliveries; it cannot take back what may already be in
+the requester's composer.
+
+Settle an uncertain hold (Issue #4082) after looking at that pane:
+  commandmate relays resolve <relay-id> --payload <id> --attempt <id> --confirm
+  (it arrived), --retry (it did not: queue it again, sent once when the
+  requester can take it), or --discard (drop it, send nothing).
+
 Withdraw one with \`commandmate relays cancel <relay-id>\`.
 `)
         .action(async (options) => {
@@ -303,8 +365,28 @@ Withdraw one with \`commandmate relays cancel <relay-id>\`.
                     + 'printing counts only.');
             }
             const { counts } = response;
+            // Issue #4082: `held=` is its own axis (uncertain now, open or closed),
+            // not one of the states. Left out — never printed as 0 — when an older
+            // server did not answer it.
+            const held = typeof response.heldCount === 'number' ? ` held=${response.heldCount}` : '';
             console.error(`relays: pending=${counts.pending} prompt=${counts.prompt} `
-                + `delivered=${counts.delivered} expired=${counts.expired} cancelled=${counts.cancelled}`);
+                + `delivered=${counts.delivered} expired=${counts.expired} cancelled=${counts.cancelled}${held}`);
+            // Issue #4064: listed even when no relay is open — a held payload's
+            // relay may have expired or been cancelled since.
+            // Issue #4082: the API's `held` also carries deliveries being typed
+            // right now (`attempting`). Only `uncertain` ones are the holds to
+            // settle — the same set `held=` counts — so the two are listed apart.
+            const heldRelays = response.held ?? [];
+            const uncertain = heldRelays.filter((relay) => relay.deliveryHold?.state === 'uncertain');
+            const inProgress = heldRelays.filter((relay) => relay.deliveryHold?.state !== 'uncertain');
+            if (uncertain.length > 0) {
+                console.error(`# delivery not confirmed, not resent (${uncertain.length})`);
+                uncertain.forEach(printRelayLine);
+            }
+            if (inProgress.length > 0) {
+                console.error(`# delivery in progress (${inProgress.length})`);
+                inProgress.forEach(printRelayLine);
+            }
             if (response.awaiting.length === 0 && response.owed.length === 0) {
                 console.error('No open relays.');
                 return;
@@ -324,20 +406,21 @@ Withdraw one with \`commandmate relays cancel <relay-id>\`.
     });
     cmd
         .command('cancel')
-        .description('Withdraw an open relay so its reply is never delivered')
+        .description('Withdraw an open relay and stop its later deliveries (a delivery already held as uncertain may have reached you)')
         .argument('<relay-id>', 'Relay ID')
         .option('--json', 'JSON output')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
-        .action(async (relayId, options) => {
+        .action(async (relayId, options, command) => {
         try {
+            const { json, token } = subcommandGlobals(options, command);
             if (!RELAY_ID_PATTERN.test(relayId)) {
                 console.error('Error: Invalid relay ID format.');
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
-            const client = new api_client_1.ApiClient({ token: options.token });
+            const client = new api_client_1.ApiClient({ token });
             try {
                 const response = await client.post(`/api/relays/${relayId}/cancel`);
-                if (options.json) {
+                if (json) {
                     console.log(JSON.stringify(response, null, 2));
                 }
                 else {
@@ -365,5 +448,60 @@ Withdraw one with \`commandmate relays cancel <relay-id>\`.
             (0, command_helpers_1.handleCommandError)(error);
         }
     });
+    cmd
+        .command('resolve')
+        .description('Settle a delivery held as uncertain (look at the requester\'s pane first): confirm, retry or discard it')
+        .argument('<relay-id>', 'Relay ID')
+        .requiredOption('--payload <id>', 'The held payload id (payload=<kind>:<id> in `relays --id`)')
+        .requiredOption('--attempt <id>', 'The held attempt id (attempt=<id> in `relays --id`)')
+        .option('--confirm', 'It reached the requester: record it as delivered (types nothing)')
+        .option('--retry', 'It did not: queue it again; sent once when the requester can take it')
+        .option('--discard', 'Drop it without sending (types nothing)')
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (relayId, options, command) => {
+        try {
+            const { json, token } = subcommandGlobals(options, command);
+            if (!RELAY_ID_PATTERN.test(relayId)) {
+                console.error('Error: Invalid relay ID format.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            const action = resolveAction(options);
+            if (action === null) {
+                console.error('Error: give exactly one of --confirm, --retry or --discard.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            const client = new api_client_1.ApiClient({ token });
+            try {
+                const response = await client.post(`/api/relays/${relayId}/resolve`, { payloadId: options.payload, attemptId: options.attempt, action });
+                if (json) {
+                    console.log(JSON.stringify(response, null, 2));
+                }
+                else {
+                    console.error(RESOLVED_MESSAGES[action](relayId, response));
+                    if (response.promoted) {
+                        console.error('  The reply that waited behind it is queued for delivery.');
+                    }
+                    // Issue #4082: a closed relay delivers nothing more.
+                    if (response.replyDiscarded) {
+                        console.error('  The reply that waited behind it was discarded: the relay is closed, so it is not delivered.');
+                    }
+                }
+            }
+            catch (error) {
+                // A stale, in-progress or not-allowed hold: nothing was changed, and
+                // re-reading the relay is what the operator does next.
+                if (error instanceof api_client_1.ApiError && error.apiCode && RELAY_HOLD_REFUSAL_CODES.has(error.apiCode)) {
+                    console.error(`Error: ${error.payload?.error ?? error.apiCode}`);
+                    console.error(`  Nothing was changed. Read it again with \`commandmate relays --id ${relayId}\`.`);
+                    process.exit(types_1.ExitCode.CONFIG_ERROR);
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
     return cmd;
 }

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

@@ -5,7 +5,12 @@
  */
 import { Command } from 'commander';
 import type { RelayCountsResponse } from '../types/api-responses';
-/** The relay line, in the same shape as the four above it. */
-export declare function formatRelayCounts(counts: RelayCountsResponse): string;
+/**
+ * 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
+ */
+export declare function formatRelayCounts(counts: RelayCountsResponse, held?: number | null): string;
 export declare function createReportCommand(): Command;
 //# sourceMappingURL=report.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/report.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,KAAK,EAGV,mBAAmB,EAKpB,MAAM,wBAAwB,CAAC;AA+EhC,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAKrE;AAmBD,wBAAgB,mBAAmB,IAAI,OAAO,CAiL7C"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/report.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,KAAK,EAGV,mBAAmB,EAKpB,MAAM,wBAAwB,CAAC;AAqFhC;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,CAMjG;AAmBD,wBAAgB,mBAAmB,IAAI,OAAO,CAuL7C"}