commandmate 0.49.3 → 0.50.0

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

@@ -9,7 +9,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';
+import { type RegisteredRelay, type RelayEndpointArg } 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;
@@ -31,7 +31,21 @@ export interface RegisterRelayForMessageInput {
      * "was the relay opened?" unanswered — the same reason `/send` is not cut.
      */
     resolveClient?: ApiClient;
+    /** Issue #4133: already resolved by {@link resolveRelayEndpoints}, so not resolved again. */
+    endpoints?: RelayEndpoints;
+    /** Issue #4133: runs when the relay could not be opened, before the command ends. */
+    onFailure?: () => Promise<void>;
+}
+/** The two ends of a relay, as the ledger stores them. */
+export interface RelayEndpoints {
+    from: RelayEndpointArg;
+    to: RelayEndpointArg;
 }
+/**
+ * Both ends of a `--reply-to`. Only reads. Exits 2 when either cannot be named, so a
+ * caller with something to clean up afterwards calls this before making it (Issue #4133).
+ */
+export declare function resolveRelayEndpoints(client: ApiClient, input: Pick<RegisterRelayForMessageInput, 'worktreeId' | 'replyTo' | 'instance' | 'agent'>): Promise<RelayEndpoints>;
 /** 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 {
@@ -40,13 +54,20 @@ export interface PostMessageOptions {
      * 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>;
+    /**
+     * Runs first when the post fails, before the relay is cancelled and before any
+     * exit. Issue #4116: told the failure, and a bound relay's outcome (null unbound).
+     */
+    onFailure?: (error: unknown, outcome: FailedSendOutcome | null) => 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 the send did, as far as a bound relay is concerned (Issue #3957). */
+type BoundSendOutcome = 'sent' | 'not_sent' | 'unknown' | 'conflict';
+/** A bound relay's outcome once the send is known to have failed. */
+export type FailedSendOutcome = Exclude<BoundSendOutcome, 'sent'>;
 /**
  * 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
@@ -67,4 +88,5 @@ export declare function describeFailedSendOutcome(error: unknown, worktreeId: st
  * @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>;
+export {};
 //# 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;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"}
+{"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;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,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;IAC1B,6FAA6F;IAC7F,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,EAAE,gBAAgB,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,IAAI,CAAC,4BAA4B,EAAE,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC,GACzF,OAAO,CAAC,cAAc,CAAC,CAIzB;AAED,yFAAyF;AACzF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,eAAe,CAAC,CAO1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,6EAA6E;AAC7E,KAAK,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAErE,qEAAqE;AACrE,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;AAqClE;;;;;;;;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,CAyDtB"}

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

@@ -9,12 +9,14 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROMPT_WAITING_CODE = void 0;
+exports.resolveRelayEndpoints = resolveRelayEndpoints;
 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 role_failure_1 = require("../utils/role-failure");
 const relays_1 = require("./relays");
 /**
  * Code the send API returns when the session is blocked on a prompt (Issue
@@ -23,15 +25,22 @@ const relays_1 = require("./relays");
  * tmux/detection graph in for one string.
  */
 exports.PROMPT_WAITING_CODE = 'PROMPT_WAITING';
+/**
+ * Both ends of a `--reply-to`. Only reads. Exits 2 when either cannot be named, so a
+ * caller with something to clean up afterwards calls this before making it (Issue #4133).
+ */
+async function resolveRelayEndpoints(client, input) {
+    const from = await (0, relays_1.resolveRelayEndpoint)(client, input.replyTo);
+    const to = await (0, relays_1.resolveEndpointForWorktree)(client, input.worktreeId, input.instance, input.agent);
+    return { from, to };
+}
 /** Resolve both endpoints and open the relay; returns its id and whether it is bound. */
 async function registerRelayForMessage(client, input) {
-    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);
+    const endpoints = input.endpoints ?? await resolveRelayEndpoints(input.resolveClient ?? client, input);
     return (0, relays_1.registerRelay)(client, {
-        from: replyEndpoint,
-        to: workerEndpoint,
+        ...endpoints,
         allowRelayChain: input.allowRelayChain,
+        onFailure: input.onFailure,
     });
 }
 function isSendOutcome(value) {
@@ -118,7 +127,7 @@ async function postMessage(client, worktreeId, sendBody, options) {
             return { worktreeId, role: 'user', content: '', sendOutcome: 'sent' };
         }
         if (options.onFailure) {
-            await options.onFailure();
+            await options.onFailure(error, outcome);
         }
         // A relay whose message never arrived can never be answered; leaving
         // it open would have the requester waiting 24h for a turn that was
@@ -131,6 +140,11 @@ async function postMessage(client, worktreeId, sendBody, options) {
             (0, relays_1.printRelayUnconfirmedNotice)(relayId, worktreeId, options.target);
         }
         const promptWaiting = error instanceof api_client_1.ApiError && error.apiCode === exports.PROMPT_WAITING_CODE;
+        // Issue #4116: a refusal with no role code of its own (a 400, a 503, a 500), after
+        // the role was saved. One with a role code says so in its own sentence.
+        if ((0, role_failure_1.roleSettingSavedBy)(error) && (0, role_failure_1.roleFailureFromApi)(error) === null) {
+            console.error(`Note: ${role_failure_1.ROLE_STAYED_SAVED}`);
+        }
         // 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.
@@ -150,6 +164,12 @@ async function postMessage(client, worktreeId, sendBody, options) {
             console.error(`Error: ${error.payload?.error ?? options.promptWaitingFallback}`);
             process.exit(types_1.ExitCode.CONFIG_ERROR);
         }
+        // Issue #4116: a refusal because of the role, whether or not this send named
+        // one (a default can refuse a start), with the server's sentence and its own
+        // exit code rather than "Unexpected HTTP status: 409".
+        const roleFailure = (0, role_failure_1.roleFailureFromApi)(error);
+        if (roleFailure)
+            throw roleFailure;
         throw error;
     }
 }

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

@@ -79,6 +79,11 @@ export interface RegisterRelayInput {
     /** The session being asked. */
     to: RelayEndpointArg;
     allowRelayChain?: boolean;
+    /**
+     * Runs when the relay could not be opened, refused or not, before the command ends
+     * (Issue #4133): a refusal exits right here, past any caller's own handling.
+     */
+    onFailure?: () => Promise<void>;
 }
 /** A relay {@link registerRelay} opened (Issue #3957). */
 export interface RegisteredRelay {

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;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,CAmB1B;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;AAoHD,wBAAgB,mBAAmB,IAAI,OAAO,CA4Q7C"}

package/dist/cli/commands/relays.js

@@ -168,6 +168,7 @@ async function registerRelay(client, input) {
         return { id: response.relay.id, bound };
     }
     catch (error) {
+        await input.onFailure?.();
         if (error instanceof api_client_1.ApiError && error.apiCode && exports.RELAY_REFUSAL_CODES.has(error.apiCode)) {
             console.error(`Error: ${error.payload?.error ?? error.apiCode}`);
             process.exit(types_1.ExitCode.CONFIG_ERROR);
@@ -239,6 +240,17 @@ function printRelayLine(relay) {
             fields.push(`reason=${delivery.reason}`);
         fields.push(`check=${delivery.checkCommand}`);
     }
+    // Issue #4105: the payload waiting in the slot, and what its last delivery
+    // attempt stopped for — an observation with its time, not a current state.
+    // Nothing is printed when the server did not observe one (or is older):
+    // that is "not known", never "deliverable".
+    if (relay.pendingKind && !delivery)
+        fields.push(`pending=${relay.pendingKind}`);
+    const block = relay.lastDeliveryBlock;
+    if (block && typeof block.reason === 'string') {
+        const at = typeof block.observedAt === 'number' ? `@${new Date(block.observedAt).toISOString()}` : '';
+        fields.push(`blocked=${block.reason}${at}`);
+    }
     console.log(fields.join('\t'));
 }
 /** `relays --id <id>`: one relay, whatever its state (Issue #3957). */
@@ -295,9 +307,25 @@ function createRelaysCommand() {
 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>]
+         [pending=<reply|prompt|expired>]  [blocked=<reason>@<iso>]
 
 States: pending (the worker has not finished), prompt (it stopped on a
-confirmation and the requester was told), delivered / expired / cancelled.
+confirmation at some point and a notice to the requester was queued -- not
+necessarily delivered yet; a record, not "still waiting": it stays after the
+confirmation is answered and pending=reply replaces the notice),
+delivered / expired / cancelled.
+
+pending= / blocked= (Issue #4105): pending= is the payload waiting to be
+typed into the requester's composer. blocked= is why the LAST delivery
+attempt of that payload stopped, and when it was observed: prompt_waiting
+(the requester's pane shows a confirmation dialog -- nothing is typed into
+it; answer it and the next pass, about every 15 s, delivers), generating,
+session_stopped, foreign_session. Left alone until the deadline, the payload
+is replaced by the expiry notice. Absent = no observation by this server
+process (after a restart, or before the first attempt), not "deliverable".
+A closed relay whose expiry notice is still stopped (Issue #4193) is listed
+under "# closed, notice not delivered yet" (state=expired, pending=expired,
+blocked=...) until the notice goes out; it is not counted as open.
 
 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
@@ -387,6 +415,14 @@ Withdraw one with \`commandmate relays cancel <relay-id>\`.
                 console.error(`# delivery in progress (${inProgress.length})`);
                 inProgress.forEach(printRelayLine);
             }
+            // Issue #4193: a closed relay whose payload to the requester (the
+            // expiry notice) is still stopped — listed apart from the open ones,
+            // and never counted in them. Absent on an older server.
+            const closedBlocked = response.closedBlocked ?? [];
+            if (closedBlocked.length > 0) {
+                console.error(`# closed, notice not delivered yet (${closedBlocked.length})`);
+                closedBlocked.forEach(printRelayLine);
+            }
             if (response.awaiting.length === 0 && response.owed.length === 0) {
                 console.error('No open relays.');
                 return;

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

@@ -0,0 +1,11 @@
+/**
+ * roles Command - define roles and set their defaults, without a screen (Issue #4116).
+ *
+ * A thin client over `/api/roles`, `/api/settings/agent-role-defaults` and
+ * `/api/repositories/:id/role-defaults`. The rules are the server's; what is here
+ * is naming things the way a person does (`utils/agent-roles.ts`) and saying what a
+ * change reaches.
+ */
+import { Command } from 'commander';
+export declare function createRolesCommand(): Command;
+//# sourceMappingURL=roles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2dpC,wBAAgB,kBAAkB,IAAI,OAAO,CA8D5C"}

package/dist/cli/commands/roles.js

@@ -0,0 +1,392 @@
+"use strict";
+/**
+ * roles Command - define roles and set their defaults, without a screen (Issue #4116).
+ *
+ * A thin client over `/api/roles`, `/api/settings/agent-role-defaults` and
+ * `/api/repositories/:id/role-defaults`. The rules are the server's; what is here
+ * is naming things the way a person does (`utils/agent-roles.ts`) and saying what a
+ * change reaches.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRolesCommand = createRolesCommand;
+const agent_roles_1 = require("../../types/agent-roles");
+const commander_1 = require("commander");
+const api_client_1 = require("../utils/api-client");
+const command_helpers_1 = require("../utils/command-helpers");
+const agent_roles_2 = require("../utils/agent-roles");
+const agent_roles_3 = require("../../types/agent-roles");
+/** Stated in `roles --help`, in `docs` and in the guide; the three say the same. */
+const ROLES_HELP = `
+Three different things (only the last touches a running session):
+  roles edit       changes the role's text. Every setting pointing at it follows,
+                   from the next start. Running sessions keep what they started with.
+  roles default    changes what a new start resolves to, per tool: for one repository
+                   (--repo) or for all that do not say otherwise. Schedules follow too.
+  instances <wt> set-role / send --role
+                   sets one instance. A role is fixed when the process starts: a running
+                   one keeps its role until stopped (instances <wt> kill <id>). Then send.
+
+<role> is an ID or a name; an exact match wins, then one ignoring case and Unicode form.
+Two answers is exit 2 with the candidates. Nothing is reserved: --none and --inherit are
+flags, so a role can be called "none".
+
+--repo is an ID, then a path, then a name:
+  - a value with a "/" or starting with "." is a path: a registered repository, or a
+    worktree of one, which answers for its repository (so --repo . works in a worktree)
+  - a bare word is a name, never a path
+See what is registered with: commandmate roles defaults
+Errors say which: unknown_repository, repository_not_registered (a directory with no
+row), ambiguous_repository. A repository with no setting for a tool is not an error:
+it reads stored: inherit, and effective says what it gets instead.
+
+Tools: ${agent_roles_3.AGENT_ROLE_CLI_TOOLS.join(', ')}. Any other is exit 2 (tool_not_supported).
+
+Exit codes:
+  0   done
+  1   the server is not running
+  2   bad arguments, a body that cannot be stored, unknown or ambiguous role or
+      repository, a tool outside the feature
+  31  a conflict; nothing changed: name_conflict, name_changed, version_conflict (--if-version),
+      role_in_use (roles rm without --force)
+  99  anything else
+
+--json goes to stdout:
+  list      { success, roles: [{ id, name, bodyVersion, bodyFingerprint, bodyBytes, createdAt, updatedAt }] }
+  show      { success, role: { ...those, body }, references: { instances, repositories, system } }
+  add       { success, role }
+  edit      { success, before, after, bodyVersion, affected, impact }
+  rm        { success, deleted: { id, name }, affected }
+  default   { success, level: system | repository, cliToolId, repository?, before, after, impact }
+              before / after: { stored, effective? }; impact: { repositories, schedules, runningSessions, message }
+  defaults  { success, system: [{ cliToolId, adapterEnabled, stored, effective }], repositories }
+            with --repo: { success, repository, defaults: [{ cliToolId, adapterEnabled, stored, effective }] }
+              stored.state: role | none | inherit (no row) | unset (system, no row)
+              effective.kind: role | none | ambiguous; effective.source: repository | system | fallback
+  failure   { success: false, error: <code>, message, candidates? | references? | currentBodyVersion? }
+            The same sentence goes to stderr. Failures with no role code of their own say
+            internal_error, request_failed, no_response (no server), role_api_unavailable
+            (a server older than roles) or unexpected_error, with the exit code above.
+            A change that got a 5xx or no answer also has saved: "unknown" and check, the
+            command that shows what it is now. A 4xx changed nothing.
+            A missing argument or unknown option is commander's: stderr only, exit 1.
+
+Example: define a reviewer and make it this repository's Codex default
+  commandmate roles add reviewer --file ./reviewer.md
+  commandmate roles default codex --repo . --role reviewer
+`;
+async function run(options, action) {
+    try {
+        await action(new api_client_1.ApiClient({ token: options.token }));
+    }
+    catch (error) {
+        (0, agent_roles_2.reportRoleFailure)(error, options.json);
+    }
+}
+function withCommon(command) {
+    return command
+        .option('--json', 'JSON output on stdout, failures included')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING);
+}
+function print(options, value, text) {
+    if (options.json)
+        console.log(JSON.stringify(value, null, 2));
+    else
+        console.log(text);
+}
+function formatTable(headers, rows) {
+    const widths = headers.map((header, i) => Math.max(header.length, ...rows.map((row) => row[i].length)));
+    const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd();
+    return [line(headers), widths.map((width) => '-'.repeat(width)).join('  '), ...rows.map(line)].join('\n');
+}
+function describeStored(stored) {
+    if (stored.state === 'role')
+        return stored.roleName;
+    return stored.state === 'inherit' ? 'inherit (no setting)' : stored.state === 'unset' ? 'unset' : 'none';
+}
+function describeEffective(effective) {
+    if (effective.kind === 'role')
+        return `${effective.role.name} (${effective.source})`;
+    if (effective.kind === 'none')
+        return `no role (${effective.source})`;
+    return 'ambiguous: the roots of this repository disagree';
+}
+function describeReferences(references) {
+    return [
+        ...references.instances.map(({ worktreeId, instanceId }) => `  instance ${instanceId} of ${worktreeId}`),
+        ...references.repositories.map(({ repositoryPath, cliToolId }) => `  ${cliToolId} default of ${repositoryPath}`),
+        ...references.system.map(({ cliToolId }) => `  ${cliToolId} system default`),
+    ];
+}
+// ---------------------------------------------------------------------------
+// Definitions
+// ---------------------------------------------------------------------------
+async function listRoles(client, options) {
+    const response = await client.get('/api/roles');
+    print(options, response, response.roles.length === 0
+        ? 'No roles. Define one with: commandmate roles add <name> --file <path>'
+        : formatTable(['ID', 'NAME', 'VERSION', 'BYTES'], response.roles.map((role) => [role.id, role.name, String(role.bodyVersion), String(role.bodyBytes)])));
+}
+async function showRole(client, selector, options) {
+    const { id } = await (0, agent_roles_2.resolveRole)(client, selector);
+    const response = await client.get(`/api/roles/${encodeURIComponent(id)}`);
+    const { role, references } = response;
+    const used = describeReferences(references);
+    print(options, response, [
+        `id: ${role.id}`,
+        `name: ${role.name}`,
+        `version: ${role.bodyVersion}`,
+        `used by: ${used.length === 0 ? 'nothing directly' : ''}`,
+        ...used,
+        '',
+        role.body,
+    ].join('\n'));
+}
+async function addRole(client, name, options) {
+    const body = await (0, agent_roles_2.readRoleBodyOption)(options);
+    if (body === undefined)
+        throw (0, agent_roles_2.usageError)('Give the body with --file <path> or --stdin.');
+    const response = await (0, agent_roles_2.roleWrite)('commandmate roles list', () => client.post('/api/roles', { name, body }));
+    print(options, response, `Role added: ${response.role.name} (${response.role.id})`);
+}
+/** Editing a role reaches everything resolving to it, from the next start. */
+const EDIT_IMPACT_MESSAGE = 'Every setting pointing at this role, and everything inheriting one, gets the new text from its next start, '
+    + 'Schedules included. Running sessions keep what they started with.';
+async function editRole(client, selector, options) {
+    let expectedBodyVersion;
+    if (options.ifVersion !== undefined) {
+        if (!/^[0-9]+$/.test(options.ifVersion))
+            throw (0, agent_roles_2.usageError)('--if-version must be a whole number.');
+        expectedBodyVersion = Number(options.ifVersion);
+    }
+    const body = await (0, agent_roles_2.readRoleBodyOption)(options);
+    if (options.name === undefined && body === undefined) {
+        throw (0, agent_roles_2.usageError)('Nothing to change: give --name, --file or --stdin.');
+    }
+    const { id, name: nameRead } = await (0, agent_roles_2.resolveRole)(client, selector);
+    const response = await (0, agent_roles_2.roleWrite)(`commandmate roles show ${id}`, () => client.put(`/api/roles/${encodeURIComponent(id)}`, {
+        ...(options.name !== undefined ? { name: options.name } : {}),
+        ...(body !== undefined ? { body } : {}),
+        ...(expectedBodyVersion !== undefined ? { expectedBodyVersion } : {}),
+        // Issue #4132: the rename replaces the name just read, not one set since.
+    }, options.name !== undefined ? { [agent_roles_1.EXPECTED_ROLE_NAME_HEADER]: encodeURIComponent(nameRead) } : undefined));
+    const { before, after, affected } = response;
+    const used = describeReferences(affected);
+    print(options, { ...response, impact: { schedules: true, runningSessions: false, message: EDIT_IMPACT_MESSAGE } }, [
+        `Role updated: ${before.name === after.name ? after.name : `${before.name} -> ${after.name}`} `
+            + `(version ${before.bodyVersion} -> ${after.bodyVersion})`,
+        `Points at it directly: ${used.length === 0 ? 'nothing' : ''}`,
+        ...used,
+        EDIT_IMPACT_MESSAGE,
+    ].join('\n'));
+}
+async function removeRole(client, selector, options) {
+    const { id } = await (0, agent_roles_2.resolveRole)(client, selector);
+    let response;
+    try {
+        response = await (0, agent_roles_2.roleWrite)('commandmate roles list', () => client.delete(`/api/roles/${encodeURIComponent(id)}${options.force ? '?force=true' : ''}`));
+    }
+    catch (error) {
+        // The sentence alone does not say what is in the way.
+        if (error instanceof api_client_1.ApiError && error.payload?.error === 'role_in_use' && error.payload.references && !options.json) {
+            const used = describeReferences(error.payload.references);
+            console.error(['In use by:', ...used, 'To remove it along with those settings: --force'].join('\n'));
+        }
+        throw error;
+    }
+    const dropped = describeReferences(response.affected);
+    print(options, response, [
+        `Role removed: ${response.deleted.name}`,
+        ...(dropped.length > 0 ? ['Settings that pointed at it now follow the defaults:', ...dropped] : []),
+    ].join('\n'));
+}
+function systemEffective(stored) {
+    return stored.state === 'role'
+        ? { kind: 'role', source: 'system', role: { id: stored.roleId, name: stored.roleName } }
+        : { kind: 'none', source: 'fallback', reason: 'no-default' };
+}
+function systemEntryOf(defaults, tool) {
+    const entry = defaults.find(({ cliToolId }) => cliToolId === tool);
+    if (!entry)
+        throw (0, agent_roles_2.usageError)(`The server has no default for ${tool}.`);
+    return entry;
+}
+function repositoryEntryOf(defaults, tool) {
+    const entry = defaults.find(({ cliToolId }) => cliToolId === tool);
+    if (!entry)
+        throw (0, agent_roles_2.usageError)(`The server has no default for ${tool}.`);
+    return entry;
+}
+function repositorySummary({ id, name, path, enabled }) {
+    return { id, name, path, ...(enabled !== undefined ? { enabled } : {}) };
+}
+/**
+ * The repositories a system default reaches: those holding no setting of their own
+ * for the tool. Null when that could not be read; the change has happened by then,
+ * and this only describes it.
+ */
+async function repositoriesInheriting(client, tool) {
+    try {
+        const repositories = await (0, agent_roles_2.listRepositories)(client);
+        const inheriting = await Promise.all(repositories.map(async (repository) => {
+            const { defaults } = await client.get(`/api/repositories/${encodeURIComponent(repository.id)}/role-defaults`);
+            return repositoryEntryOf(defaults, tool).stored.state === 'inherit';
+        }));
+        return repositories.filter((_, index) => inheriting[index]).map(repositorySummary);
+    }
+    catch {
+        return null;
+    }
+}
+function assertOneAssignment(options) {
+    const given = [options.role !== undefined, options.none === true, options.inherit === true].filter(Boolean).length;
+    if (given !== 1) {
+        throw (0, agent_roles_2.usageError)(options.repo === undefined
+            ? 'Give one of --role <role> or --none.'
+            : 'Give one of --role <role>, --none or --inherit.');
+    }
+    if (options.repo === undefined && options.inherit) {
+        throw (0, agent_roles_2.usageError)('--inherit needs --repo: the system level is the last one, and has nothing to inherit from.');
+    }
+}
+function warnAdapterDisabled(tool, enabled) {
+    if (!enabled) {
+        console.error(`Warning: roles are not enabled for ${tool} yet: a start that resolves to one is refused.`);
+    }
+}
+async function setSystemDefault(client, tool, options) {
+    const roleId = options.role !== undefined ? (await (0, agent_roles_2.resolveRole)(client, options.role)).id : null;
+    const before = systemEntryOf((await client.get('/api/settings/agent-role-defaults')).defaults, tool);
+    const { defaults } = await (0, agent_roles_2.roleWrite)('commandmate roles defaults', () => client.put('/api/settings/agent-role-defaults', { cliToolId: tool, roleId }));
+    const after = systemEntryOf(defaults, tool);
+    warnAdapterDisabled(tool, after.adapterEnabled);
+    const repositories = await repositoriesInheriting(client, tool);
+    const message = `From its next start, every ${tool} session with no setting of its own in a repository with none either `
+        + 'gets this, Schedules included. Running sessions keep what they started with.';
+    print(options, {
+        success: true,
+        level: 'system',
+        cliToolId: tool,
+        before: { stored: before.stored, effective: systemEffective(before.stored) },
+        after: { stored: after.stored, effective: systemEffective(after.stored) },
+        impact: { repositories, schedules: true, runningSessions: false, message },
+    }, [
+        `System default of ${tool}: ${describeStored(before.stored)} -> ${describeStored(after.stored)}`,
+        repositories === null
+            ? 'Could not read which repositories inherit it.'
+            : `Repositories inheriting it: ${repositories.map(({ name }) => name).join(', ') || 'none'}`,
+        message,
+    ].join('\n'));
+}
+async function setRepositoryDefault(client, tool, repo, options) {
+    const repository = await (0, agent_roles_2.resolveRepository)(client, repo);
+    const role = options.none
+        ? { state: 'none' }
+        : options.inherit
+            ? { state: 'inherit' }
+            : { state: 'role', roleId: (await (0, agent_roles_2.resolveRole)(client, options.role)).id };
+    const url = `/api/repositories/${encodeURIComponent(repository.id)}/role-defaults`;
+    const before = repositoryEntryOf((await client.get(url)).defaults, tool);
+    const response = await (0, agent_roles_2.roleWrite)(`commandmate roles defaults --repo ${repository.id}`, () => client.put(url, { cliToolId: tool, role }));
+    const after = repositoryEntryOf(response.defaults, tool);
+    warnAdapterDisabled(tool, after.adapterEnabled);
+    if (after.effective.kind === 'ambiguous') {
+        console.error('Warning: the registered roots of this repository now disagree, and a start there is refused until they agree:\n'
+            + after.effective.roots.map(({ path, state }) => `  - ${path}: ${describeStored(state)}`).join('\n'));
+    }
+    const message = `From its next start, every ${tool} session of this repository with no setting of its own gets this, `
+        + 'Schedules included. Running sessions keep what they started with.';
+    print(options, {
+        success: true,
+        level: 'repository',
+        cliToolId: tool,
+        repository: response.repository,
+        before: { stored: before.stored, effective: before.effective },
+        after: { stored: after.stored, effective: after.effective },
+        impact: {
+            repositories: [response.repository],
+            sharedRootIds: after.effective.repositoryIds,
+            schedules: true,
+            runningSessions: false,
+            message,
+        },
+    }, [
+        `Default of ${tool} in ${response.repository.name}: ${describeStored(before.stored)} -> ${describeStored(after.stored)}`,
+        `A new start there gets: ${describeEffective(after.effective)}`,
+        message,
+    ].join('\n'));
+}
+async function setDefault(client, tool, options) {
+    (0, agent_roles_2.assertRoleTool)(tool);
+    assertOneAssignment(options);
+    if (options.repo !== undefined)
+        await setRepositoryDefault(client, tool, options.repo, options);
+    else
+        await setSystemDefault(client, tool, options);
+}
+async function showDefaults(client, options) {
+    if (options.tool !== undefined)
+        (0, agent_roles_2.assertRoleTool)(options.tool);
+    const wanted = (entries) => options.tool === undefined ? entries : entries.filter(({ cliToolId }) => cliToolId === options.tool);
+    if (options.repo !== undefined) {
+        const repository = await (0, agent_roles_2.resolveRepository)(client, options.repo);
+        const response = await client.get(`/api/repositories/${encodeURIComponent(repository.id)}/role-defaults`);
+        const defaults = wanted(response.defaults);
+        print(options, { ...response, defaults }, [
+            `${response.repository.name}  ${response.repository.path}`,
+            formatTable(['TOOL', 'STORED', 'EFFECTIVE'], defaults.map(({ cliToolId, stored, effective }) => [cliToolId, describeStored(stored), describeEffective(effective)])),
+        ].join('\n'));
+        return;
+    }
+    const { defaults } = await client.get('/api/settings/agent-role-defaults');
+    const repositories = (await (0, agent_roles_2.listRepositories)(client)).map(repositorySummary);
+    const system = wanted(defaults).map((entry) => ({ ...entry, effective: systemEffective(entry.stored) }));
+    print(options, { success: true, system, repositories }, [
+        formatTable(['TOOL', 'SYSTEM_DEFAULT', 'EFFECTIVE'], system.map(({ cliToolId, stored, effective }) => [cliToolId, describeStored(stored), describeEffective(effective)])),
+        '',
+        'Registered repositories (for --repo):',
+        repositories.length === 0
+            ? '  none'
+            : formatTable(['ID', 'NAME', 'PATH'], repositories.map(({ id, name, path }) => [id, name, path])),
+    ].join('\n'));
+}
+function createRolesCommand() {
+    const cmd = new commander_1.Command('roles');
+    cmd.description('Define roles and set which one a new session gets, by tool and repository').addHelpText('after', ROLES_HELP);
+    withCommon(cmd.command('list').description('List the roles, without their bodies'))
+        .action((options) => run(options, (client) => listRoles(client, options)));
+    withCommon(cmd.command('show').description('Show one role, its body and what points at it').argument('<role>', 'Role ID or name'))
+        .action((role, options) => run(options, (client) => showRole(client, role, options)));
+    withCommon(cmd
+        .command('add')
+        .description('Define a role. The body comes from --file or stdin, byte for byte')
+        .argument('<name>', 'Role name')
+        .option('--file <path>', 'Read the body from this file')
+        .option('--stdin', 'Read the body from stdin')).action((name, options) => run(options, (client) => addRole(client, name, options)));
+    withCommon(cmd
+        .command('edit')
+        .description('Rename a role or change its body. Running sessions keep what they started with')
+        .argument('<role>', 'Role ID or name')
+        .option('--name <name>', 'New name')
+        .option('--file <path>', 'Read the new body from this file')
+        .option('--stdin', 'Read the new body from stdin')
+        .option('--if-version <n>', 'Refuse (exit 31) unless the body is still at this version')).action((role, options) => run(options, (client) => editRole(client, role, options)));
+    withCommon(cmd
+        .command('rm')
+        .description('Remove a role. Refused (exit 31) while something points at it')
+        .argument('<role>', 'Role ID or name')
+        .option('--force', 'Remove what points at it too; those settings then follow the defaults')).action((role, options) => run(options, (client) => removeRole(client, role, options)));
+    withCommon(cmd
+        .command('default')
+        .description('Set which role a new start of this tool gets, for one repository (--repo) or all that do not say otherwise')
+        .argument('<tool>', `One of: ${agent_roles_3.AGENT_ROLE_CLI_TOOLS.join(', ')}`)
+        .option('--repo <repository>', 'Repository ID, path or name. Omit for the system level')
+        .option('--role <role>', 'Role ID or name')
+        .option('--none', 'With --repo: explicitly no role. Without: remove the system default')
+        .option('--inherit', 'With --repo: drop the setting, and follow the system default')).action((tool, options) => run(options, (client) => setDefault(client, tool, options)));
+    withCommon(cmd
+        .command('defaults')
+        .description('Show the defaults and the registered repositories. Changes nothing')
+        .option('--repo <repository>', 'Repository ID, path or name: what it holds, and what a worktree of it gets')
+        .option('--tool <tool>', 'Only this tool')).action((options) => run(options, (client) => showDefaults(client, options)));
+    return cmd;
+}

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,CAmK3C"}
+{"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;AAkwBpC,wBAAgB,iBAAiB,IAAI,OAAO,CAqV3C"}