commandmate 0.49.0 → 0.49.2

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

@@ -6,7 +6,10 @@
  * Kept in its own module (not in send.ts / ask.ts) because tests mock those
  * modules' internals; what differs per command is passed in as arguments.
  */
+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
  * #1708). Mirrors PROMPT_WAITING_CODE in src/lib/session/prompt-waiting-guard.ts;
@@ -21,16 +24,47 @@ 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 the relay id. */
-export declare function registerRelayForMessage(client: ApiClient, input: RegisterRelayForMessageInput): Promise<string>;
+/** 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>;
 export interface PostMessageOptions {
-    relayId?: string;
+    /**
+     * The relay this message opened. When it is bound, its id is put on the
+     * send (`relayId`) and it is withdrawn only on a confirmed `not_sent`.
+     */
+    relay?: RegisteredRelay;
     /** Runs first when the post fails, before the relay is cancelled. */
     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;
 }
-/** Post the message; on failure cancel the relay and report PROMPT_WAITING. */
-export declare function postMessage(client: ApiClient, worktreeId: string, sendBody: Record<string, unknown>, options: PostMessageOptions): Promise<void>;
+/**
+ * What to tell the sender about resending a failed send, from the server's
+ * `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, target?: CommandTarget): string | null;
+/**
+ * Post the message; on failure cancel the relay and report PROMPT_WAITING.
+ *
+ * Issue #3957: a bound relay is withdrawn only when nothing reached the worker
+ * (`not_sent`). When that cannot be said the relay is left open, the message
+ * is NOT resent, and stderr names the relay and how to look it up.
+ *
+ * @returns The send API's body (Issue #3957: `ask` reads `turnOpenAtSend`)
+ */
+export declare function postMessage(client: ApiClient, worktreeId: string, sendBody: Record<string, unknown>, options: PostMessageOptions): Promise<ChatMessage>;
 //# sourceMappingURL=message-dispatch.d.ts.map

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;AAIH,OAAO,EAAE,SAAS,EAAY,MAAM,qBAAqB,CAAC;AAQ1D;;;;;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,uEAAuE;AACvE,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,MAAM,CAAC,CAajB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,+EAA+E;AAC/E,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,IAAI,CAAC,CA2Bf"}
+{"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

@@ -10,9 +10,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROMPT_WAITING_CODE = void 0;
 exports.registerRelayForMessage = registerRelayForMessage;
+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
@@ -21,37 +23,127 @@ const relays_1 = require("./relays");
  * tmux/detection graph in for one string.
  */
 exports.PROMPT_WAITING_CODE = 'PROMPT_WAITING';
-/** Resolve both endpoints and open the relay; returns the relay id. */
+/** 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,
         allowRelayChain: input.allowRelayChain,
     });
 }
-/** Post the message; on failure cancel the relay and report PROMPT_WAITING. */
+function isSendOutcome(value) {
+    return value === 'sent' || value === 'not_sent' || value === 'unknown';
+}
+/**
+ * Work out what a failed send did to a bound relay (Issue #3957).
+ *
+ * The server's own `sendOutcome` when the answer carries one. A 409
+ * `RELAY_BIND_CONFLICT` is another attempt's relay — never withdrawn from
+ * here. A 4xx without one was refused before the relay was reserved: nothing
+ * was sent. No answer at all (a dropped connection, a 5xx from in between) is
+ * asked of `GET /api/relays/:id`; only `sent` and `failed` are taken from it,
+ * because a send still waiting for the input lock reads `awaiting` too.
+ */
+async function resolveBoundSendOutcome(client, relayId, error) {
+    if (error instanceof api_client_1.ApiError && error.statusCode !== undefined) {
+        if (error.apiCode === 'RELAY_BIND_CONFLICT')
+            return 'conflict';
+        const reported = error.payload?.sendOutcome;
+        if (isSendOutcome(reported))
+            return reported;
+        if (error.statusCode < 500)
+            return 'not_sent';
+    }
+    try {
+        const { relay } = await client.get(`/api/relays/${relayId}`);
+        if (relay.sendState === 'sent')
+            return 'sent';
+        if (relay.sendState === 'failed')
+            return 'not_sent';
+    }
+    catch {
+        // Not answerable either: the relay is left as it is.
+    }
+    return 'unknown';
+}
+/**
+ * What to tell the sender about resending a failed send, from the server's
+ * `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, target) {
+    if (!(error instanceof api_client_1.ApiError))
+        return null;
+    const outcome = error.payload?.sendOutcome;
+    if (outcome === 'not_sent') {
+        return 'Note: the message was not sent (sendOutcome=not_sent); it is safe to send it again.';
+    }
+    if (outcome === 'unknown') {
+        return ('Note: whether the message was sent is not known (sendOutcome=unknown); '
+            + `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;
+}
+/**
+ * Post the message; on failure cancel the relay and report PROMPT_WAITING.
+ *
+ * Issue #3957: a bound relay is withdrawn only when nothing reached the worker
+ * (`not_sent`). When that cannot be said the relay is left open, the message
+ * is NOT resent, and stderr names the relay and how to look it up.
+ *
+ * @returns The send API's body (Issue #3957: `ask` reads `turnOpenAtSend`)
+ */
 async function postMessage(client, worktreeId, sendBody, options) {
-    const { relayId } = options;
+    const { relay } = options;
+    const relayId = relay?.id;
+    const body = relay?.bound ? { ...sendBody, relayId: relay.id } : sendBody;
     try {
-        await client.post(`/api/worktrees/${worktreeId}/send`, sendBody);
+        const sent = await client.post(`/api/worktrees/${worktreeId}/send`, body);
+        if (relay?.bound && sent?.sendOutcome === 'unknown')
+            (0, relays_1.printRelayUnconfirmedNotice)(relay.id);
+        return sent;
     }
     catch (error) {
+        const outcome = relay?.bound ? await resolveBoundSendOutcome(client, relay.id, error) : null;
+        // The answer was lost on the way back, and the server says it went out.
+        if (outcome === 'sent') {
+            return { worktreeId, role: 'user', content: '', sendOutcome: 'sent' };
+        }
         if (options.onFailure) {
             await options.onFailure();
         }
         // A relay whose message never arrived can never be answered; leaving
         // it open would have the requester waiting 24h for a turn that was
         // never started.
-        if (relayId) {
+        if (relayId && (outcome === null || outcome === 'not_sent')) {
             await (0, relays_1.cancelRelayQuietly)(client, relayId);
         }
+        else if (relayId && outcome === 'unknown') {
+            // Issue #3992: the relay notice carries the "look before resending" hint.
+            (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, options.target);
+            if (resendNote !== null)
+                console.error(resendNote);
+        }
         // Issue #1708: the session is sitting on a prompt, so the message
         // would have been typed into the prompt's input line rather than
         // reaching the agent. Reported on its own so an unattended runner sees
         // "answer the prompt", not a generic HTTP failure.
-        if (error instanceof api_client_1.ApiError && error.apiCode === exports.PROMPT_WAITING_CODE) {
+        if (promptWaiting && error instanceof api_client_1.ApiError) {
             // The server's own sentence, not error.message: handleApiError maps a
             // bare 409 to "Unexpected HTTP status: 409", which says nothing about
             // what to do next.

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

@@ -2,6 +2,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,6 +27,7 @@
  */
 import { Command } from 'commander';
 import { ApiClient } from '../utils/api-client';
+import type { CommandTarget } from './command-target';
 /**
  * The codes `POST /api/relays` refuses with.
  *
@@ -76,6 +78,17 @@ export interface RegisterRelayInput {
     to: RelayEndpointArg;
     allowRelayChain?: boolean;
 }
+/** A relay {@link registerRelay} opened (Issue #3957). */
+export interface RegisteredRelay {
+    id: string;
+    /**
+     * The server confirmed `bindMode: 'bound'`: the relay id goes on the send,
+     * and only that send's reply is delivered. False on an older server.
+     */
+    bound: boolean;
+}
+/** The one line an older server's relay gets on stderr (Issue #3957). */
+export declare const LEGACY_RELAY_NOTICE: string;
 /**
  * Open a relay, printing the server's own refusal and exiting 2 on one.
  *
@@ -83,10 +96,21 @@ export interface RegisterRelayInput {
  * 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
  */
-export declare function registerRelay(client: ApiClient, input: RegisterRelayInput): Promise<string>;
+export declare function registerRelay(client: ApiClient, input: RegisterRelayInput): Promise<RegisteredRelay>;
 /** Withdraw a relay, best effort. Used when the send it accompanied failed. */
 export declare function cancelRelayQuietly(client: ApiClient, relayId: string): Promise<void>;
+/**
+ * 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.
+ */
+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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,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;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,+EAA+E;AAC/E,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY1F;AAyBD,wBAAgB,mBAAmB,IAAI,OAAO,CAsI7C"}
+{"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;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;AAwCD,wBAAgB,mBAAmB,IAAI,OAAO,CAuJ7C"}

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,17 +27,19 @@
  * 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");
 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. */
@@ -133,6 +136,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 +146,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 +158,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 +188,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, target) {
+    // Issue #3992: a failed send names the pane to look at before any resend, in
+    // 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 (\`${(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}`);
+}
 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 +240,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-strict.d.ts.map

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

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

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

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

@@ -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. Both routes answer it as a 500 with this `reason` (Issue #3982).
+ * Restated from `src/lib/prompt-answer-errors.ts` (`ANSWER_INPUT_LOST_REASON`).
+ */
+export declare const ANSWER_INPUT_LOST = "answer_input_lost";
 export declare function createRespondCommand(): Command;
 //# 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;AAkKpC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AA0TrD,wBAAgB,oBAAoB,IAAI,OAAO,CA6I9C"}