commandmate 0.31.3 → 0.32.0

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

package/dist/lib/detection/status-reason.d.ts

@@ -61,6 +61,34 @@ export declare const STATUS_REASON: {
      * `Type to search models...` box.
      */
     readonly COMMAND_CODE_SELECTION_LIST: "command_code_selection_list";
+    /**
+     * Issue #2369: a Command Code overlay that only Esc leaves.
+     *
+     * `/usage` opens a read-only panel — a plan header, two usage meters, a
+     * breakdown URL — whose last row is `Press Esc to close`. There is no
+     * highlight to move, no numbered option and no confirm key; the ONE thing the
+     * screen accepts is the dismiss.
+     *
+     * Distinct from {@link STATUS_REASON.COMMAND_CODE_SELECTION_LIST} because the
+     * two screens want different controls, and that is the whole of this Issue:
+     * before it, this panel matched no rule at all, reached the `default` floor
+     * and so raised `isUnclassifiedActive` — which the chat surface answers with
+     * `TerminalEscapeHatch` plus `PromptAnswerKeys`, eighteen buttons (arrows,
+     * Enter, Esc, `1`-`9`, `y`, `n`) of which exactly one does anything. Reporting
+     * the selection-list token instead would put the arrow pad on the card and
+     * tell an operator reading `capture --json` that a moving highlight had been
+     * read off a panel that has none.
+     *
+     * Deliberately NOT a member of `SELECTION_LIST_REASONS`
+     * (`lib/detection/status-detector.ts`): that set is what `isSelectionListActive`
+     * — and therefore the arrow pad — is derived from. The flag this one feeds is
+     * `isDismissablePanelActive`, published beside it.
+     *
+     * The vocabulary is Command Code's alone for now (方針書 §4 D2's tool-by-tool
+     * rule): the SHAPE "an overlay whose footer offers only a dismiss" is general,
+     * the sentence that identifies it was measured on one tool.
+     */
+    readonly COMMAND_CODE_DISMISSABLE_PANEL: "command_code_dismissable_panel";
     readonly COPILOT_SELECTION_LIST: "copilot_selection_list";
     readonly CODEX_SELECTION_LIST: "codex_selection_list";
     /** Issue #1017: Codex pager / edit-previous (transcript) mode. */

package/dist/lib/detection/status-reason.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status-reason.d.ts","sourceRoot":"","sources":["../../../src/lib/detection/status-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;IAKxB;;;;;;;;;;;;;;;;;;OAkBG;;IAEH,6EAA6E;;;IAG7E;;;;;;;;;;;;;;;;OAgBG;;;;IAIH,kEAAkE;;IAElE,6EAA6E;;;;;;IAM7E;;;;;;;;;;;;;;;OAeG;;IAEH;;;;;;;;;;;;;;;OAeG;;;CAGK,CAAC"}
+{"version":3,"file":"status-reason.d.ts","sourceRoot":"","sources":["../../../src/lib/detection/status-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;IAKxB;;;;;;;;;;;;;;;;;;OAkBG;;IAEH,6EAA6E;;;IAG7E;;;;;;;;;;;;;;;;OAgBG;;IAEH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;;;IAIH,kEAAkE;;IAElE,6EAA6E;;;;;;IAM7E;;;;;;;;;;;;;;;OAeG;;IAEH;;;;;;;;;;;;;;;OAeG;;;CAGK,CAAC"}

package/dist/lib/detection/status-reason.js

@@ -64,6 +64,34 @@ exports.STATUS_REASON = {
      * `Type to search models...` box.
      */
     COMMAND_CODE_SELECTION_LIST: 'command_code_selection_list',
+    /**
+     * Issue #2369: a Command Code overlay that only Esc leaves.
+     *
+     * `/usage` opens a read-only panel — a plan header, two usage meters, a
+     * breakdown URL — whose last row is `Press Esc to close`. There is no
+     * highlight to move, no numbered option and no confirm key; the ONE thing the
+     * screen accepts is the dismiss.
+     *
+     * Distinct from {@link STATUS_REASON.COMMAND_CODE_SELECTION_LIST} because the
+     * two screens want different controls, and that is the whole of this Issue:
+     * before it, this panel matched no rule at all, reached the `default` floor
+     * and so raised `isUnclassifiedActive` — which the chat surface answers with
+     * `TerminalEscapeHatch` plus `PromptAnswerKeys`, eighteen buttons (arrows,
+     * Enter, Esc, `1`-`9`, `y`, `n`) of which exactly one does anything. Reporting
+     * the selection-list token instead would put the arrow pad on the card and
+     * tell an operator reading `capture --json` that a moving highlight had been
+     * read off a panel that has none.
+     *
+     * Deliberately NOT a member of `SELECTION_LIST_REASONS`
+     * (`lib/detection/status-detector.ts`): that set is what `isSelectionListActive`
+     * — and therefore the arrow pad — is derived from. The flag this one feeds is
+     * `isDismissablePanelActive`, published beside it.
+     *
+     * The vocabulary is Command Code's alone for now (方針書 §4 D2's tool-by-tool
+     * rule): the SHAPE "an overlay whose footer offers only a dismiss" is general,
+     * the sentence that identifies it was measured on one tool.
+     */
+    COMMAND_CODE_DISMISSABLE_PANEL: 'command_code_dismissable_panel',
     COPILOT_SELECTION_LIST: 'copilot_selection_list',
     CODEX_SELECTION_LIST: 'codex_selection_list',
     /** Issue #1017: Codex pager / edit-previous (transcript) mode. */

package/dist/server/locales/en/worktree.json

@@ -459,6 +459,7 @@
         "bannerLabel": "You can act on this here",
         "reasonPager": "A pager is open. Scroll it and quit it from here, with the screen below in view.",
         "reasonSelectionList": "A selection list is open. Move and confirm from here, with the screen below in view.",
+        "reasonDismissablePanel": "This screen only closes. Press Esc here, with it in view below.",
         "reasonUnclassified": "Chat can't tell what this screen is. It is shown as-is below, so you can drive it with the keys here.",
         "reasonPromptUnreadable": "Waiting for an answer, and the options couldn't be read. Read the screen below and answer with a number or y/n.",
         "openTerminal": "Open terminal",
@@ -919,6 +920,11 @@
         "toolbarLabel": "Dialog answer keys",
         "caption": "Answer"
     },
+    "dismissPanelKeys": {
+        "toolbarLabel": "Close this screen",
+        "close": "Close (Esc)",
+        "closeAria": "Close this screen (Esc)"
+    },
     "selectionKeys": {
         "numbersToolbarLabel": "Option number keys",
         "numbersCaption": "Pick",
@@ -1018,6 +1024,23 @@
         "degradedTitle": "Structured events are not arriving",
         "healthyTitle": "Receiving structured events"
     },
+    "relay": {
+        "badgeOwed": "Reply due to {alias}",
+        "badgeOwedMany": "Replies due ({count})",
+        "badgeAwaiting": "Waiting on {alias}",
+        "badgeAwaitingMany": "Waiting on {count} replies",
+        "badgePrompt": "Confirmation reported",
+        "owedTitle": "This session owes a delegated reply. It is delivered automatically when the turn ends.",
+        "awaitingTitle": "This session is waiting for a delegated reply. It arrives in the composer as a relay message.",
+        "promptTitle": "The other session stopped on a confirmation; the requester has been told.",
+        "stripAwaiting": "Delegated to {alias}; waiting for the reply.",
+        "stripAwaitingMany": "Waiting for {count} delegated replies.",
+        "stripPrompt": "{alias} is waiting for a confirmation.",
+        "stripOwed": "Owed to {alias}: this session's reply is delivered when the turn ends.",
+        "historyBadge": "relay",
+        "historyBadgeTitle": "Delivered by another agent session (Issue #2377 relay).",
+        "historyCount": "{count} relayed message(s) in view"
+    },
     "agentModel": {
         "label": "Model",
         "modelLabel": "Model: {model}",