commandmate 0.31.2 → 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/lib/detection/tools/verified-against.d.ts

@@ -71,35 +71,35 @@ export declare const OPENCODE_VERIFIED_AGAINST: {
     readonly paneGeometry: "80x200";
 };
 /**
- * agy these rules were read off (#988 / #995 footer + selection rules, re-read
- * against the #2270 live panes).
+ * agy these rules were read off (#988 / #995 footer + selection rules, #2270's
+ * numbered-dialog carve-out, re-measured and re-captured by #2364).
  *
- * Bumped from `0.4.x` / `2026-07-30` / `inline` because the frames were
- * RE-CAPTURED, not because the binary moved: #2270 drove agy 1.1.25 on a private
- * tmux socket at the production geometry and kept both panes inline in
- * `tests/unit/status-detector-selection.test.ts`
- * (`AGY_1125_PERMISSION_PANE`, `AGY_1125_SWITCH_MODEL_PANE`) under the banner
- * `Antigravity CLI 1.1.25`, trailing pane padding included. The
- * `Do you want to proceed?` + `N. label` rules were measured off those frames,
- * and `ANTIGRAVITY_SELECTION_LIST_PATTERN` (#995 / #997) was re-checked against
- * them and left unchanged.
+ * Bumped from 1.1.25 because the frames were RE-CAPTURED and the rules CHANGED:
+ * #2364 drove agy 1.1.27 on a private tmux socket at the production geometry and
+ * kept the frames in `tests/fixtures/antigravity-live-2364/` — the file-creation
+ * menu (`Allow creation of this file?`, two options), the Bash approval whose
+ * option labels wrap onto three rows each, the one-row Bash approval #2270 had
+ * measured on 1.1.25, the `/model` picker, the folder-trust screen, the
+ * slash-command popup, and the first live IDLE agy frame. The numbered-dialog
+ * discriminator (`isAntigravityNumberedDialog`) was rewritten off those frames
+ * from a question-line match to the footer + numbered-row structure, and the
+ * dialogs are now read by `tools/antigravity/dialog.ts` rather than by the
+ * generic multiple-choice parser. `ANTIGRAVITY_SELECTION_LIST_PATTERN`
+ * (#995 / #997) was re-checked against every frame and left unchanged.
  *
- * `paneGeometry` leaves `inline` because the 1.1.25 permission dialog draws no
- * composer row at all — it reproduces only at the 200x1000 pane the server
- * captures, and a fixture without the ~970 blank padding rows exercises a
- * different `lastLines` slice than production does. That is a statement about
- * the capture condition, not about agy: the scrollback-retained rendering the
- * `afterThinking` footer rules rest on (#988) is unchanged, and the 1.1.25
- * dialog still ends on `esc to cancel`.
+ * The #2270 1.1.25 panes stay where they are
+ * (`tests/unit/status-detector-selection.test.ts`) and the rules still answer
+ * for both builds.
  *
- * What this stamp does NOT claim: #2270 captured `waiting` frames only, so the
- * idle (`? for shortcuts`) and generating (spinner) branches are carried over
- * from the 0.4 captures rather than re-measured. A live IDLE 1.1.25 frame is
- * still uncaptured — see the `readIdleEvidence` note in `antigravity/detect.ts`.
+ * What this stamp does NOT claim: the generating (spinner) branch is still
+ * carried over from the 0.4 captures rather than re-measured, and the
+ * post-answer survey (`[1] Good … [0] Skip`) was seen once on the production
+ * server and reconstructed from its cleaned rows — the raw frame is not in the
+ * fixture directory (see its README).
  */
 export declare const ANTIGRAVITY_VERIFIED_AGAINST: {
-    readonly version: "1.1.25";
-    readonly capturedAt: "2026-09-04";
+    readonly version: "1.1.27";
+    readonly capturedAt: "2026-09-06";
     readonly paneGeometry: "200x1000";
 };
 /**