commandmate 0.31.3 → 0.32.1

package/dist/cli/utils/api-client.d.ts

@@ -38,6 +38,22 @@ export interface ApiErrorResult {
     message: string;
     exitCode: number;
 }
+/**
+ * What this function knows about the request, beyond its status (Issue #2404).
+ *
+ * `handleApiError` is a pure classifier over `(status, payload)` and has no way
+ * to know which server answered — which is exactly the fact a 404 needs. The
+ * caller's `Resource not found. Check the worktree ID.` sent an agent looking
+ * for a typo in an id that was correct: the CLI was dialling a *different*
+ * CommandMate server than the one that had started its session, and the id it
+ * was asking about lived on the other one. Optional so the two callers that
+ * classify without a client ({@link ApiClient} aside, `server-capabilities.ts`)
+ * keep compiling and keep their wording.
+ */
+export interface ApiErrorContext {
+    /** The base URL the failing request was actually sent to. */
+    serverUrl?: string;
+}
 /**
  * Classify API errors into user-friendly messages and exit codes.
  * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
@@ -47,9 +63,12 @@ export interface ApiErrorResult {
  * @param payload - Parsed error body, when the response carried one (Issue #1637).
  *   Used for 5xx only: the 4xx messages below are already specific, and are
  *   pinned by tests as the CLI's own wording.
+ * @param context - Which server answered, when the caller knows (Issue #2404).
+ *   Read by the 404 branch only; the other messages do not send anyone looking
+ *   in the wrong place.
  * @returns User-friendly error message and exit code
  */
-export declare function handleApiError(error: unknown, status?: number, payload?: ApiErrorPayload): ApiErrorResult;
+export declare function handleApiError(error: unknown, status?: number, payload?: ApiErrorPayload, context?: ApiErrorContext): ApiErrorResult;
 /**
  * API Client for CLI HTTP communication.
  * Uses Node.js built-in fetch. Handles auth headers and error mapping.
@@ -61,6 +80,16 @@ export declare class ApiClient {
         baseUrl?: string;
         token?: string;
     });
+    /**
+     * The base URL this client actually dials (Issue #2404).
+     *
+     * Resolved once in the constructor through the precedence in
+     * `loadClientEnv()` (`--base-url` > exported `CM_PORT` > `~/.commandmate/.env`
+     * > 3000), which is why it is read from here rather than re-derived by each
+     * caller: a second derivation is a second answer, and "which server did this
+     * command talk to" only helps if it is the one the request went to.
+     */
+    get serverUrl(): string;
     private getHeaders;
     /**
      * GET without any status handling, for callers that must read the raw response.

package/dist/cli/utils/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"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"}

package/dist/cli/utils/api-client.js

@@ -87,6 +87,10 @@ function serverErrorDetail(payload) {
         ? `${detail.slice(0, MAX_SERVER_ERROR_DETAIL)}…`
         : detail;
 }
+/** Append `(server: <url>)` when the caller named one. */
+function withServerUrl(message, context) {
+    return context?.serverUrl ? `${message} (server: ${context.serverUrl})` : message;
+}
 /**
  * Classify API errors into user-friendly messages and exit codes.
  * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
@@ -96,9 +100,12 @@ function serverErrorDetail(payload) {
  * @param payload - Parsed error body, when the response carried one (Issue #1637).
  *   Used for 5xx only: the 4xx messages below are already specific, and are
  *   pinned by tests as the CLI's own wording.
+ * @param context - Which server answered, when the caller knows (Issue #2404).
+ *   Read by the 404 branch only; the other messages do not send anyone looking
+ *   in the wrong place.
  * @returns User-friendly error message and exit code
  */
-function handleApiError(error, status, payload) {
+function handleApiError(error, status, payload, context) {
     // HTTP status-based errors
     if (status !== undefined) {
         switch (status) {
@@ -114,8 +121,12 @@ function handleApiError(error, status, payload) {
                     exitCode: types_1.ExitCode.CONFIG_ERROR,
                 };
             case 404:
+                // Issue #2404: the sentence stays, so everything matching on it keeps
+                // matching; the URL is appended because "check the worktree ID" is
+                // advice about the wrong thing whenever the id is fine and the SERVER
+                // is the one that is wrong.
                 return {
-                    message: 'Resource not found. Check the worktree ID.',
+                    message: withServerUrl('Resource not found. Check the worktree ID.', context),
                     exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
                 };
             case 429:
@@ -205,6 +216,18 @@ class ApiClient {
             console.error('Warning: Connecting to remote server over HTTP. Auth token will be sent in plaintext. Use HTTPS for non-localhost connections.');
         }
     }
+    /**
+     * The base URL this client actually dials (Issue #2404).
+     *
+     * Resolved once in the constructor through the precedence in
+     * `loadClientEnv()` (`--base-url` > exported `CM_PORT` > `~/.commandmate/.env`
+     * > 3000), which is why it is read from here rather than re-derived by each
+     * caller: a second derivation is a second answer, and "which server did this
+     * command talk to" only helps if it is the one the request went to.
+     */
+    get serverUrl() {
+        return this.baseUrl;
+    }
     getHeaders() {
         const headers = {
             'Content-Type': 'application/json',
@@ -250,7 +273,7 @@ class ApiClient {
                 // Issue #1637: read the body first — handleApiError needs it to surface
                 // the server's reason for a 5xx instead of "check the logs".
                 const payload = await readErrorPayload(response);
-                const errResult = handleApiError(null, response.status, payload);
+                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
                 throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             return (await response.json());
@@ -277,7 +300,7 @@ class ApiClient {
                 // Issue #1637: read the body first — handleApiError needs it to surface
                 // the server's reason for a 5xx instead of "check the logs".
                 const payload = await readErrorPayload(response);
-                const errResult = handleApiError(null, response.status, payload);
+                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
                 throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             // Handle 204 No Content
@@ -309,7 +332,7 @@ class ApiClient {
                 // Issue #1637: read the body first — handleApiError needs it to surface
                 // the server's reason for a 5xx instead of "check the logs".
                 const payload = await readErrorPayload(response);
-                const errResult = handleApiError(null, response.status, payload);
+                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
                 throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             const text = await response.text();

package/dist/lib/cli/command-reference.d.ts

@@ -0,0 +1,179 @@
+/**
+ * How a CommandMate CLI command is spelled — the single source both the
+ * assistant context and the GUI read (Issue #2120).
+ *
+ * ## Why this file exists
+ *
+ * `resolveCommandMateBinary()` used to be a module-private function inside
+ * `src/lib/assistant/context-builder.ts`, where only the assistant prompt could
+ * see it. Issue #2120 puts the same four commands on screen in the roster pane,
+ * and a second copy of the `commandmate` / `commandmatedev` rule would be a
+ * second authority on the one thing the operator pastes into a shell: a
+ * development checkout would keep telling the assistant `commandmatedev` while
+ * telling the human `commandmate`, and the human's copy would simply not be on
+ * their PATH. So the rule moved here and both callers import it.
+ *
+ * ## Isomorphic on purpose
+ *
+ * {@link buildInstanceCliCommands} and {@link buildDelegationBrief} are pure
+ * functions of strings so the browser can call them.
+ * {@link resolveCommandMateBinary} reads an environment and is meant for the
+ * server — a client component cannot read `CM_LAUNCHED_BY` (Next.js inlines
+ * only `NEXT_PUBLIC_*` into the browser bundle), which is why
+ * `GET /api/worktrees/:id/cli-reference` exists to hand the answer down.
+ *
+ * Nothing here touches a DOM, and that is load-bearing rather than incidental:
+ * `commandmate peers` imports {@link resolveCommandMateBinary} from this file,
+ * and the CLI build (`tsconfig.cli.json`) has no DOM lib at all. The delegation
+ * brief's delivery into a composer therefore lives with the components that
+ * deliver it — see `insertIntoVisibleComposer` in
+ * `src/components/common/CommandPalette.tsx` (Issue #2376).
+ */
+/** The binary name a globally installed CommandMate puts on PATH. */
+export declare const COMMANDMATE_GLOBAL_BINARY = "commandmate";
+/**
+ * The binary name a repository checkout puts on PATH (`npm link` in this repo).
+ *
+ * Not a fallback in the "we could not tell" sense: `commandmate start` sets
+ * `CM_LAUNCHED_BY=commandmate-cli` on itself and on the server child it spawns
+ * (`src/cli/commands/start.ts`), so a server that was NOT started that way was
+ * started from a checkout, and `commandmatedev` is the command that exists.
+ */
+export declare const COMMANDMATE_DEV_BINARY = "commandmatedev";
+/** The marker `commandmate start` stamps on the server process it launches. */
+export declare const COMMANDMATE_CLI_LAUNCH_MARKER = "commandmate-cli";
+/**
+ * The port a copied command does not have to name.
+ *
+ * `src/lib/env.ts` keeps its own private `DEFAULT_PORT` for the server's own
+ * binding; this constant answers a different question — "must the pasted line
+ * carry a `CM_PORT=` prefix?" — and is exported because the API route that
+ * decides it and the builder that renders it are in different layers.
+ */
+export declare const DEFAULT_SERVER_PORT = 3000;
+/** The binary name to spell CommandMate commands with. */
+export type CommandMateBinary = typeof COMMANDMATE_GLOBAL_BINARY | typeof COMMANDMATE_DEV_BINARY;
+/**
+ * Which binary name the CLI commands aimed at THIS server should use.
+ *
+ * @param env - The environment to read; defaults to the server's own
+ * @returns `commandmate` when the server was started by the installed CLI,
+ *   `commandmatedev` otherwise
+ */
+export declare function resolveCommandMateBinary(env?: Readonly<Record<string, string | undefined>>): CommandMateBinary;
+/** The four session-targeting commands the roster pane offers, in display order. */
+export declare const INSTANCE_CLI_COMMAND_IDS: readonly ["send", "wait", "capture", "respond"];
+export type InstanceCliCommandId = (typeof INSTANCE_CLI_COMMAND_IDS)[number];
+/**
+ * The answer `respond` is shown with.
+ *
+ * A NUMBER, never `yes`. `respond` hands its argument to the pane as keystrokes
+ * and does not resolve it semantically, so `yes` on a multiple-choice dialog is
+ * typed, ignored, and followed by Enter — which picks whatever the DEFAULT
+ * option happens to be. The number is the only form that selects what the
+ * operator meant. The note beside the command says so; this constant is what
+ * keeps the example itself from teaching the wrong habit.
+ */
+export declare const RESPOND_ANSWER_EXAMPLE = "1";
+export interface InstanceCliCommandInput {
+    /** From {@link resolveCommandMateBinary}, never hardcoded by the caller. */
+    binary: string;
+    /** The worktree id as the CLI must be given it. */
+    worktreeId: string;
+    /**
+     * The instance id **as the server resolved it**
+     * (`GET /api/worktrees/:id/resolve-target`). Never a roster row read directly:
+     * Issue #1925 is the record of what two authorities answering this question
+     * cost.
+     */
+    instanceId: string;
+    /**
+     * The port to name in a `CM_PORT=` prefix, or null when this server is on
+     * {@link DEFAULT_SERVER_PORT} and the prefix would be noise.
+     *
+     * There is deliberately no `--port` flag here: `send` / `wait` / `capture` /
+     * `respond` do not define one (only `start` / `stop` / `status` do), so a
+     * pasted `--port 3135` would be rejected by commander as an unknown option.
+     * `CM_PORT=<n> commandmate ls` is the documented way to aim one invocation at
+     * a non-default server (see `loadClientEnv()` in `src/cli/utils/server-url.ts`).
+     */
+    portPrefix?: number | null;
+    /** Localized stand-in for the message body, e.g. `メッセージ`. */
+    messagePlaceholder: string;
+}
+/**
+ * Render the four commands that address one agent instance.
+ *
+ * The message body stays a PLACEHOLDER. Quoting a real body correctly in the
+ * browser means getting Japanese text, newlines and embedded quotes past a
+ * shell whose dialect this code cannot see, and a near-miss does not fail
+ * loudly — it sends a truncated prompt to a live agent.
+ *
+ * `worktreeId` and `instanceId` need no quoting of their own: both are
+ * validated before they can reach a roster row or this route
+ * (`isValidWorktreeId` / `isValidInstanceId` allow no shell metacharacter).
+ *
+ * @param input - Binary, target and presentation details
+ * @returns One shell line per command id
+ */
+export declare function buildInstanceCliCommands(input: InstanceCliCommandInput): Record<InstanceCliCommandId, string>;
+/**
+ * `--timeout` the brief tells session A to use, in seconds.
+ *
+ * 30 minutes. Long enough that an ordinary implementation request is not cut
+ * off mid-turn, short enough that a session which died in its pane surfaces as
+ * an exit 124 in the same sitting rather than at the end of the day. A caller
+ * who wants a different one edits the line — it is a brief, not a config.
+ */
+export declare const DELEGATION_ASK_TIMEOUT_SECONDS = 1800;
+/** The locales the brief is written in. Anything else falls back to English. */
+export type DelegationBriefLocale = 'ja' | 'en';
+export interface DelegationBriefInput {
+    /** From {@link resolveCommandMateBinary}, never hardcoded by the caller. */
+    binary: string;
+    /** The worktree id as the CLI must be given it. */
+    worktreeId: string;
+    /**
+     * The instance id **as the server resolved it**
+     * (`GET /api/worktrees/:id/resolve-target`) — the same rule
+     * {@link InstanceCliCommandInput.instanceId} states, for the same reason.
+     */
+    instanceId: string;
+    /** The roster alias of the target instance, e.g. `Codex 2`. */
+    instanceLabel: string;
+    /** Display name of the CLI tool behind the instance, e.g. `Codex`. */
+    toolLabel: string;
+    /** As {@link InstanceCliCommandInput.portPrefix}. */
+    portPrefix?: number | null;
+    /** UI locale. Anything but `ja` is written in English. */
+    locale: string;
+}
+/**
+ * The paragraph one agent session pastes to another agent session's operator —
+ * "here is how you delegate to that session" — in the UI's own language.
+ *
+ * ## Why it lives beside {@link buildInstanceCliCommands}
+ *
+ * Both answer the same question (how is a CommandMate command aimed at ONE
+ * instance spelled?) from the same two server reads, and Issue #2120 already
+ * paid for learning that a second copy of the binary-name rule is a copy that
+ * tells the human one thing and the assistant another. The panel and the brief
+ * therefore share this module, and neither composes a command from what the
+ * browser happens to know.
+ *
+ * ## Why the text is here rather than in `locales/`
+ *
+ * It is a PROMPT, not a label. The whole value of it is that the four exit
+ * codes, the "do not answer their prompt" rule and the command spellings arrive
+ * together and unedited; a translator moving a line between keys, or a key
+ * resolving to its own name because the namespace was renamed, produces a brief
+ * that still looks like a brief and quietly drops the one clause that stops
+ * session A from answering session B's permission dialog. The two languages are
+ * written out in full, side by side, so a change to one is visibly a change to
+ * the other.
+ *
+ * @param input - Binary, target and locale
+ * @returns The brief, ready to be inserted into a composer
+ */
+export declare function buildDelegationBrief(input: DelegationBriefInput): string;
+//# sourceMappingURL=command-reference.d.ts.map

package/dist/lib/cli/command-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-reference.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/command-reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,oBAAoB,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GACzB,OAAO,yBAAyB,GAChC,OAAO,sBAAsB,CAAC;AAElC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,iBAAiB,CAInB;AAED,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,iDAAkD,CAAC;AAExF,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,6DAA6D;IAC7D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,uBAAuB,GAC7B,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAmBtC;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAUnD,gFAAgF;AAChF,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAqDxE"}

package/dist/lib/cli/command-reference.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * How a CommandMate CLI command is spelled — the single source both the
+ * assistant context and the GUI read (Issue #2120).
+ *
+ * ## Why this file exists
+ *
+ * `resolveCommandMateBinary()` used to be a module-private function inside
+ * `src/lib/assistant/context-builder.ts`, where only the assistant prompt could
+ * see it. Issue #2120 puts the same four commands on screen in the roster pane,
+ * and a second copy of the `commandmate` / `commandmatedev` rule would be a
+ * second authority on the one thing the operator pastes into a shell: a
+ * development checkout would keep telling the assistant `commandmatedev` while
+ * telling the human `commandmate`, and the human's copy would simply not be on
+ * their PATH. So the rule moved here and both callers import it.
+ *
+ * ## Isomorphic on purpose
+ *
+ * {@link buildInstanceCliCommands} and {@link buildDelegationBrief} are pure
+ * functions of strings so the browser can call them.
+ * {@link resolveCommandMateBinary} reads an environment and is meant for the
+ * server — a client component cannot read `CM_LAUNCHED_BY` (Next.js inlines
+ * only `NEXT_PUBLIC_*` into the browser bundle), which is why
+ * `GET /api/worktrees/:id/cli-reference` exists to hand the answer down.
+ *
+ * Nothing here touches a DOM, and that is load-bearing rather than incidental:
+ * `commandmate peers` imports {@link resolveCommandMateBinary} from this file,
+ * and the CLI build (`tsconfig.cli.json`) has no DOM lib at all. The delegation
+ * brief's delivery into a composer therefore lives with the components that
+ * deliver it — see `insertIntoVisibleComposer` in
+ * `src/components/common/CommandPalette.tsx` (Issue #2376).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELEGATION_ASK_TIMEOUT_SECONDS = exports.RESPOND_ANSWER_EXAMPLE = exports.INSTANCE_CLI_COMMAND_IDS = exports.DEFAULT_SERVER_PORT = exports.COMMANDMATE_CLI_LAUNCH_MARKER = exports.COMMANDMATE_DEV_BINARY = exports.COMMANDMATE_GLOBAL_BINARY = void 0;
+exports.resolveCommandMateBinary = resolveCommandMateBinary;
+exports.buildInstanceCliCommands = buildInstanceCliCommands;
+exports.buildDelegationBrief = buildDelegationBrief;
+/** The binary name a globally installed CommandMate puts on PATH. */
+exports.COMMANDMATE_GLOBAL_BINARY = 'commandmate';
+/**
+ * The binary name a repository checkout puts on PATH (`npm link` in this repo).
+ *
+ * Not a fallback in the "we could not tell" sense: `commandmate start` sets
+ * `CM_LAUNCHED_BY=commandmate-cli` on itself and on the server child it spawns
+ * (`src/cli/commands/start.ts`), so a server that was NOT started that way was
+ * started from a checkout, and `commandmatedev` is the command that exists.
+ */
+exports.COMMANDMATE_DEV_BINARY = 'commandmatedev';
+/** The marker `commandmate start` stamps on the server process it launches. */
+exports.COMMANDMATE_CLI_LAUNCH_MARKER = 'commandmate-cli';
+/**
+ * The port a copied command does not have to name.
+ *
+ * `src/lib/env.ts` keeps its own private `DEFAULT_PORT` for the server's own
+ * binding; this constant answers a different question — "must the pasted line
+ * carry a `CM_PORT=` prefix?" — and is exported because the API route that
+ * decides it and the builder that renders it are in different layers.
+ */
+exports.DEFAULT_SERVER_PORT = 3000;
+/**
+ * Which binary name the CLI commands aimed at THIS server should use.
+ *
+ * @param env - The environment to read; defaults to the server's own
+ * @returns `commandmate` when the server was started by the installed CLI,
+ *   `commandmatedev` otherwise
+ */
+function resolveCommandMateBinary(env = process.env) {
+    return env.CM_LAUNCHED_BY === exports.COMMANDMATE_CLI_LAUNCH_MARKER
+        ? exports.COMMANDMATE_GLOBAL_BINARY
+        : exports.COMMANDMATE_DEV_BINARY;
+}
+/** The four session-targeting commands the roster pane offers, in display order. */
+exports.INSTANCE_CLI_COMMAND_IDS = ['send', 'wait', 'capture', 'respond'];
+/**
+ * The answer `respond` is shown with.
+ *
+ * A NUMBER, never `yes`. `respond` hands its argument to the pane as keystrokes
+ * and does not resolve it semantically, so `yes` on a multiple-choice dialog is
+ * typed, ignored, and followed by Enter — which picks whatever the DEFAULT
+ * option happens to be. The number is the only form that selects what the
+ * operator meant. The note beside the command says so; this constant is what
+ * keeps the example itself from teaching the wrong habit.
+ */
+exports.RESPOND_ANSWER_EXAMPLE = '1';
+/**
+ * Render the four commands that address one agent instance.
+ *
+ * The message body stays a PLACEHOLDER. Quoting a real body correctly in the
+ * browser means getting Japanese text, newlines and embedded quotes past a
+ * shell whose dialect this code cannot see, and a near-miss does not fail
+ * loudly — it sends a truncated prompt to a live agent.
+ *
+ * `worktreeId` and `instanceId` need no quoting of their own: both are
+ * validated before they can reach a roster row or this route
+ * (`isValidWorktreeId` / `isValidInstanceId` allow no shell metacharacter).
+ *
+ * @param input - Binary, target and presentation details
+ * @returns One shell line per command id
+ */
+function buildInstanceCliCommands(input) {
+    const { binary, worktreeId, instanceId, messagePlaceholder } = input;
+    const prefix = input.portPrefix != null && input.portPrefix !== exports.DEFAULT_SERVER_PORT
+        ? `CM_PORT=${input.portPrefix} `
+        : '';
+    const target = `--instance ${instanceId}`;
+    const head = `${prefix}${binary}`;
+    return {
+        send: `${head} send ${worktreeId} "${messagePlaceholder}" ${target}`,
+        // `--on-prompt human` is part of the copied line, not an afterthought: the
+        // default (`agent`) exits 10 the moment a prompt appears, which is right
+        // for a script polling in a loop and useless for the operator who just
+        // pasted a wait into their own terminal.
+        wait: `${head} wait ${worktreeId} ${target} --on-prompt human`,
+        capture: `${head} capture ${worktreeId} ${target}`,
+        respond: `${head} respond ${worktreeId} "${exports.RESPOND_ANSWER_EXAMPLE}" ${target}`,
+    };
+}
+// ===========================================================================
+// Delegation brief (Issue #2376)
+// ===========================================================================
+/**
+ * `--timeout` the brief tells session A to use, in seconds.
+ *
+ * 30 minutes. Long enough that an ordinary implementation request is not cut
+ * off mid-turn, short enough that a session which died in its pane surfaces as
+ * an exit 124 in the same sitting rather than at the end of the day. A caller
+ * who wants a different one edits the line — it is a brief, not a config.
+ */
+exports.DELEGATION_ASK_TIMEOUT_SECONDS = 1800;
+/**
+ * Rows of pane transcript the brief's progress-check line asks for.
+ *
+ * Matches what `capture --pane --tail 60` shows a human: enough to see what the
+ * other session is doing, short enough to paste into a report.
+ */
+const DELEGATION_CAPTURE_TAIL = 60;
+/**
+ * The paragraph one agent session pastes to another agent session's operator —
+ * "here is how you delegate to that session" — in the UI's own language.
+ *
+ * ## Why it lives beside {@link buildInstanceCliCommands}
+ *
+ * Both answer the same question (how is a CommandMate command aimed at ONE
+ * instance spelled?) from the same two server reads, and Issue #2120 already
+ * paid for learning that a second copy of the binary-name rule is a copy that
+ * tells the human one thing and the assistant another. The panel and the brief
+ * therefore share this module, and neither composes a command from what the
+ * browser happens to know.
+ *
+ * ## Why the text is here rather than in `locales/`
+ *
+ * It is a PROMPT, not a label. The whole value of it is that the four exit
+ * codes, the "do not answer their prompt" rule and the command spellings arrive
+ * together and unedited; a translator moving a line between keys, or a key
+ * resolving to its own name because the namespace was renamed, produces a brief
+ * that still looks like a brief and quietly drops the one clause that stops
+ * session A from answering session B's permission dialog. The two languages are
+ * written out in full, side by side, so a change to one is visibly a change to
+ * the other.
+ *
+ * @param input - Binary, target and locale
+ * @returns The brief, ready to be inserted into a composer
+ */
+function buildDelegationBrief(input) {
+    const { binary, worktreeId, instanceId, instanceLabel, toolLabel } = input;
+    const prefix = input.portPrefix != null && input.portPrefix !== exports.DEFAULT_SERVER_PORT
+        ? `CM_PORT=${input.portPrefix} `
+        : '';
+    const head = `${prefix}${binary}`;
+    const target = `--instance ${instanceId}`;
+    const locale = input.locale === 'ja' ? 'ja' : 'en';
+    const capture = `${head} capture ${worktreeId} ${target} --pane --tail ${DELEGATION_CAPTURE_TAIL}`;
+    // Issue #2377: the same delegation without the block. Offered as the SECOND
+    // line rather than as a replacement because the two are different jobs: `ask`
+    // is right when the answer is the next thing you need, `--async` is right when
+    // it is not — and a brief that only taught the asynchronous form would have
+    // agents registering relays for questions they are about to sit and wait for
+    // anyway.
+    const asyncAsk = `${head} ask ${worktreeId} ${target} "<request>" --async`;
+    if (locale === 'ja') {
+        const ask = `${head} ask ${worktreeId} ${target} "<依頼文>" --timeout ${exports.DELEGATION_ASK_TIMEOUT_SECONDS}`;
+        return [
+            `## 別セッション「${instanceLabel}」への委任`,
+            `- 宛先: worktree \`${worktreeId}\` / instance \`${instanceId}\`（${toolLabel}）`,
+            `- 依頼: ${ask}`,
+            '  - exit 0: 標準出力が返答本文',
+            '  - exit 10: 相手が確認待ち。標準出力のprompt JSONを私に報告して止まる（自分で答えない）',
+            '  - exit 124: タイムアウト。captureで状況を見て報告',
+            `- 待たない依頼: ${asyncAsk}`,
+            '  - 即座に relay id を返して exit 0。完了時に `[from ...]` 付きで返答が私のコンポーザーに届く',
+            `  - 状況確認: ${head} relays / 取り消し: ${head} relays cancel <relay-id>`,
+            `- 進捗確認: ${capture}`,
+            '- 禁止: respondで相手のプロンプトに答える / auto-yesを有効化する',
+        ].join('\n');
+    }
+    const ask = `${head} ask ${worktreeId} ${target} "<request>" --timeout ${exports.DELEGATION_ASK_TIMEOUT_SECONDS}`;
+    return [
+        `## Delegating to session "${instanceLabel}"`,
+        `- Target: worktree \`${worktreeId}\` / instance \`${instanceId}\` (${toolLabel})`,
+        `- Ask: ${ask}`,
+        '  - exit 0: stdout is the reply body',
+        '  - exit 10: they are waiting on a confirmation. Report the prompt JSON on stdout back to me and stop (do not answer it yourself)',
+        '  - exit 124: timed out. Look with capture and report what you see',
+        `- Ask without waiting: ${asyncAsk}`,
+        '  - exits 0 with a relay id on stdout; the reply lands in my composer prefixed `[from ...]` when the turn ends',
+        `  - Outstanding: ${head} relays / withdraw: ${head} relays cancel <relay-id>`,
+        `- Progress: ${capture}`,
+        '- Do not: answer their prompt with respond / turn auto-yes on',
+    ].join('\n');
+}

package/dist/lib/detection/ansi.d.ts

@@ -10,16 +10,29 @@
  * Covers:
  * - SGR sequences: ESC[Nm (colors, bold, underline, etc.)
  * - OSC sequences: ESC]...BEL and ESC]...ST (ESC \\) - window title, and the
- *   OSC 8 hyperlinks that claude/codex/copilot emit (Issue #1912)
+ *   OSC 8 hyperlinks that claude/codex/copilot emit (Issue #1912). Also
+ *   available on its own as {@link stripOsc} (Issue #2369), for a consumer that
+ *   renders SGR and must not render OSC.
  * - CSI sequences: ESC[...letter (cursor movement, erase, etc.)
  *
  * Known limitations (SEC-002): 8-bit CSI (0x9B), DEC private modes (ESC[?25h),
  * character-set switching (ESC(0), and some RGB color forms may not match. In
  * practice tmux capture-pane output rarely contains these.
  */
+/** {@link OSC_SOURCE} as a reusable global pattern. */
+export declare const OSC_PATTERN: RegExp;
 export declare const ANSI_PATTERN: RegExp;
 /** Remove all ANSI escape sequences from a string. */
 export declare function stripAnsi(str: string): string;
+/**
+ * Remove OSC sequences only, leaving SGR (colour) and CSI untouched.
+ *
+ * For OSC 8 hyperlinks — `ESC ] 8 ; ; <url> ST <label> ESC ] 8 ; ; ST` — this
+ * drops both halves of the pair and keeps `<label>`, which is the text the
+ * terminal itself shows. See {@link OSC_PATTERN} for who needs this and why
+ * `stripAnsi` is not the answer for them.
+ */
+export declare function stripOsc(str: string): string;
 /**
  * Extract the ANSI escape sequences from a string, in order, discarding all
  * other characters. Reuses the same tested pattern as {@link stripAnsi} so the

package/dist/lib/detection/ansi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ansi.d.ts","sourceRoot":"","sources":["../../../src/lib/detection/ansi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,YAAY,QAC8C,CAAC;AAExE,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGxD"}
+{"version":3,"file":"ansi.d.ts","sourceRoot":"","sources":["../../../src/lib/detection/ansi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAwBH,uDAAuD;AACvD,eAAO,MAAM,WAAW,QAA8B,CAAC;AAEvD,eAAO,MAAM,YAAY,QAGxB,CAAC;AAEF,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/lib/detection/ansi.js

@@ -11,7 +11,9 @@
  * Covers:
  * - SGR sequences: ESC[Nm (colors, bold, underline, etc.)
  * - OSC sequences: ESC]...BEL and ESC]...ST (ESC \\) - window title, and the
- *   OSC 8 hyperlinks that claude/codex/copilot emit (Issue #1912)
+ *   OSC 8 hyperlinks that claude/codex/copilot emit (Issue #1912). Also
+ *   available on its own as {@link stripOsc} (Issue #2369), for a consumer that
+ *   renders SGR and must not render OSC.
  * - CSI sequences: ESC[...letter (cursor movement, erase, etc.)
  *
  * Known limitations (SEC-002): 8-bit CSI (0x9B), DEC private modes (ESC[?25h),
@@ -19,14 +21,49 @@
  * practice tmux capture-pane output rarely contains these.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ANSI_PATTERN = void 0;
+exports.ANSI_PATTERN = exports.OSC_PATTERN = void 0;
 exports.stripAnsi = stripAnsi;
+exports.stripOsc = stripOsc;
 exports.extractAnsiSequences = extractAnsiSequences;
-exports.ANSI_PATTERN = /\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\[[0-9;]*m/g;
+/**
+ * One OSC sequence: `ESC ]`, a payload, and either terminator (BEL or ST).
+ *
+ * Split out of {@link ANSI_PATTERN} by Issue #2369 so a second consumer can
+ * strip OSC **without** stripping SGR. `sanitizeTerminalOutput`
+ * (`lib/security/sanitize.ts`) is that consumer: it hands the frame to
+ * `ansi-to-html`, which turns SGR into colour and does not know OSC at all — so
+ * before this split, Command Code's `/usage` panel rendered its breakdown link
+ * as the literal text `]8;;https://commandcode.ai/…\` beside the label. Calling
+ * `stripAnsi` there would have thrown the colour away with it.
+ *
+ * The payload class excludes ESC as well as BEL (Issue #1912) so a sequence
+ * ended by ST cannot run on to a BEL later in the buffer and swallow the visible
+ * link text between them. An OSC with no terminator at all matches nothing and
+ * is left in place, which is the safe answer: eating the rest of the frame is
+ * worse than showing one stray escape.
+ *
+ * The source is shared with {@link ANSI_PATTERN} rather than restated, so the
+ * two cannot drift about which terminators exist.
+ */
+const OSC_SOURCE = '\\x1b\\][^\\x07\\x1b]*(?:\\x07|\\x1b\\\\)';
+/** {@link OSC_SOURCE} as a reusable global pattern. */
+exports.OSC_PATTERN = new RegExp(OSC_SOURCE, 'g');
+exports.ANSI_PATTERN = new RegExp(`\\x1b\\[[0-9;]*[a-zA-Z]|${OSC_SOURCE}|\\[[0-9;]*m`, 'g');
 /** Remove all ANSI escape sequences from a string. */
 function stripAnsi(str) {
     return str.replace(exports.ANSI_PATTERN, '');
 }
+/**
+ * Remove OSC sequences only, leaving SGR (colour) and CSI untouched.
+ *
+ * For OSC 8 hyperlinks — `ESC ] 8 ; ; <url> ST <label> ESC ] 8 ; ; ST` — this
+ * drops both halves of the pair and keeps `<label>`, which is the text the
+ * terminal itself shows. See {@link OSC_PATTERN} for who needs this and why
+ * `stripAnsi` is not the answer for them.
+ */
+function stripOsc(str) {
+    return str.replace(exports.OSC_PATTERN, '');
+}
 /**
  * Extract the ANSI escape sequences from a string, in order, discarding all
  * other characters. Reuses the same tested pattern as {@link stripAnsi} so the