commandmate 0.31.3 → 0.32.0

package/dist/cli/commands/capture.js

@@ -6,6 +6,7 @@
  * Issue #1685: `--prompts` lists the resolved-prompt audit trail
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSqueezedPaneTail = readSqueezedPaneTail;
 exports.createCaptureCommand = createCaptureCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -15,7 +16,6 @@ const command_helpers_1 = require("../utils/command-helpers");
 const cli_tool_ids_1 = require("../config/cli-tool-ids");
 const agent_target_options_1 = require("../config/agent-target-options");
 const instances_1 = require("./instances");
-const session_target_1 = require("../utils/session-target");
 const pager_1 = require("../utils/pager");
 const transcript_squeeze_1 = require("../../lib/tmux/transcript-squeeze");
 /**
@@ -80,7 +80,7 @@ function parseTail(raw) {
  *
  * POST /capture demands an explicit `cliToolId`, so unlike GET /current-output
  * this path cannot leave the choice to the server. Issue #1925 moved the choice
- * itself to the server anyway — `resolveSessionTarget` asks
+ * itself to the server anyway — `resolveInstanceTarget` asks
  * `/resolve-target`, which applies the same precedence every other route now
  * uses, so bare `capture <id> --pane` reads the session the rest of the CLI
  * addresses instead of a locally-guessed one.
@@ -93,25 +93,35 @@ function parseTail(raw) {
  * The tail of this function only runs against a server too old to resolve, the
  * one case where the CLI still has to name a default itself.
  *
+ * Issue #2376 widened the return to the resolved INSTANCE as well as the tool:
+ * `--instance` now accepts an alias, and `POST /capture` reads instance ids.
+ * The NAME is deliberately unchanged — the design doc
+ * `docs/design/multi-agent-state-architecture.md` names this function in five
+ * places, and `tests/unit/docs/design-doc-identifier-audit.test.ts` fails when
+ * a name the design doc uses is no longer in the tree.
+ *
  * @param client - API client
  * @param worktreeId - Worktree ID
  * @param agent - Value of `--agent`, already validated
  * @param instance - Value of `--instance`, already validated
- * @returns CLI tool ID to capture
+ * @returns The CLI tool to capture, and the resolved instance id when there is one
  */
 async function resolvePaneCliTool(client, worktreeId, agent, instance) {
-    const target = await (0, session_target_1.resolveSessionTarget)(client, worktreeId, {
-        instanceId: instance,
-        requestedCliTool: agent,
-    });
-    if (target.conflict) {
-        console.error(`Warning: ${(0, session_target_1.describeSessionTargetConflict)(target.conflict)} `
-            + `Reading ${target.conflict.rosterCliTool}.`);
+    // Issue #2376: through the shared resolver so `--instance "Codex 2"` names
+    // the same session here as it does on `send`, and so an alias two rows answer
+    // to stops with the candidates listed rather than reading one of them.
+    // Called with or WITHOUT a selector, exactly as before: `capture --pane` with
+    // no `--instance` has asked the server since #1925, and skipping the request
+    // when nothing was named would be the CLI resolving for itself again.
+    const target = await (0, instances_1.resolveInstanceTarget)(client, worktreeId, instance, agent, 'read-only');
+    if (target.cliToolId) {
+        return { cliToolId: target.cliToolId, instanceId: target.instanceId };
     }
-    if (target.cliToolId)
-        return target.cliToolId;
     const worktree = await client.get(`/api/worktrees/${worktreeId}`);
-    return worktree.cliToolId || cli_tool_ids_1.DEFAULT_CLI_TOOL_ID;
+    return {
+        cliToolId: worktree.cliToolId || cli_tool_ids_1.DEFAULT_CLI_TOOL_ID,
+        instanceId: target.instanceId,
+    };
 }
 /** Default number of prompts `--prompts` lists (Issue #1685). */
 const DEFAULT_PROMPTS_LIMIT = 20;
@@ -155,11 +165,17 @@ function formatPromptOption(option) {
 async function capturePrompts(worktreeId, options) {
     const client = new api_client_1.ApiClient({ token: options.token });
     const limit = parsePromptsLimit(options.limit);
+    // Issue #2376: /messages filters by instance ID, so an alias has to be
+    // resolved before it gets there — otherwise `--instance "Codex 2"` silently
+    // matches nothing and the audit trail comes back empty.
+    const target = options.instance
+        ? await (0, instances_1.resolveInstanceTarget)(client, worktreeId, options.instance, options.agent, 'read-only')
+        : null;
     const query = new URLSearchParams({ messageType: 'prompt', limit: String(limit) });
     if (options.agent)
         query.set('cliTool', options.agent);
-    if (options.instance)
-        query.set('instance', options.instance);
+    if (target?.instanceId)
+        query.set('instance', target.instanceId);
     const messages = await client.get(`/api/worktrees/${worktreeId}/messages?${query.toString()}`);
     // Defensive: the endpoint already filters, but promptData-less rows would
     // render as empty entries.
@@ -235,11 +251,11 @@ async function capturePrompts(worktreeId, options) {
 async function capturePane(worktreeId, options) {
     const client = new api_client_1.ApiClient({ token: options.token });
     const tail = parseTail(options.tail);
-    const cliToolId = await resolvePaneCliTool(client, worktreeId, options.agent, options.instance);
+    const { cliToolId, instanceId } = await resolvePaneCliTool(client, worktreeId, options.agent, options.instance);
     const data = await client.post(`/api/worktrees/${worktreeId}/capture`, {
         cliToolId,
         lines: PANE_CAPTURE_LINES,
-        ...(options.instance ? { instanceId: options.instance } : {}),
+        ...(instanceId ? { instanceId } : {}),
     });
     const raw = data.output ?? '';
     const squeezed = (0, transcript_squeeze_1.squeezeTranscript)(raw, { tail });
@@ -247,7 +263,7 @@ async function capturePane(worktreeId, options) {
     if (options.json) {
         console.log(JSON.stringify({
             cliToolId,
-            instanceId: options.instance ?? null,
+            instanceId: instanceId ?? null,
             output: text,
             lines: options.raw ? squeezed.rawLines : squeezed.lines,
             rawLines: squeezed.rawLines,
@@ -276,6 +292,38 @@ function parseFollowInterval(raw) {
     }
     return value;
 }
+/**
+ * Read one instance's pane and return its squeezed tail, or null.
+ *
+ * Exported for `ask` (Issue #2376), which needs the same read for the tools
+ * that keep no transcript — and which must not import
+ * `lib/tmux/transcript-squeeze` itself: Issue #1922's import guard names this
+ * module in its allowlist as baseline debt that "may only shrink", so the
+ * squeeze stays behind the command that already owns it.
+ *
+ * Null on any failure. Both callers treat an unreadable pane as "no reply to
+ * show", never as an error of their own.
+ *
+ * @param client - API client
+ * @param worktreeId - Worktree ID
+ * @param cliToolId - Resolved CLI tool
+ * @param instanceId - Resolved instance ID, when there is one
+ * @param tail - Lines of squeezed transcript to keep
+ */
+async function readSqueezedPaneTail(client, worktreeId, cliToolId, instanceId, tail) {
+    try {
+        const data = await client.post(`/api/worktrees/${worktreeId}/capture`, {
+            cliToolId,
+            lines: PANE_CAPTURE_LINES,
+            ...(instanceId ? { instanceId } : {}),
+        });
+        const text = (0, transcript_squeeze_1.squeezeTranscript)(data.output ?? '', { tail }).text.trim();
+        return text === '' ? null : text;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * `--pane --follow`: redraw the squeezed transcript on an interval (Issue #2317).
  *
@@ -307,7 +355,7 @@ async function capturePaneFollow(worktreeId, options) {
     const client = new api_client_1.ApiClient({ token: options.token });
     const tail = parseTail(options.tail);
     const intervalMs = parseFollowInterval(options.interval);
-    const cliToolId = await resolvePaneCliTool(client, worktreeId, options.agent, options.instance);
+    const { cliToolId, instanceId } = await resolvePaneCliTool(client, worktreeId, options.agent, options.instance);
     // Hide the cursor while redrawing, and put it back whatever ends the loop.
     process.stdout.write('\u001b[?25l');
     const restoreCursor = () => {
@@ -319,7 +367,7 @@ async function capturePaneFollow(worktreeId, options) {
             const data = await client.post(`/api/worktrees/${worktreeId}/capture`, {
                 cliToolId,
                 lines: PANE_CAPTURE_LINES,
-                ...(options.instance ? { instanceId: options.instance } : {}),
+                ...(instanceId ? { instanceId } : {}),
             });
             const squeezed = (0, transcript_squeeze_1.squeezeTranscript)(data.output ?? '', { tail });
             // The visible rows, minus one for the footer. Slicing HERE rather than
@@ -354,7 +402,7 @@ function createCaptureCommand() {
         // Issue #1685: audit trail of resolved prompts (question/options/answer/answeredBy)
         .option('--prompts', 'List recent prompts from chat history (including ones Auto-Yes already resolved)')
         .option('--limit <n>', `With --prompts: number of most recent prompts to list (default ${DEFAULT_PROMPTS_LIMIT})`)
-        .option('--instance <id>', agent_target_options_1.INSTANCE_OPTION_DESCRIPTION)
+        .option('--instance <id>', `${agent_target_options_1.INSTANCE_OPTION_DESCRIPTION} ${instances_1.INSTANCE_ALIAS_HELP_SUFFIX}`)
         .option('--agent <agent>', agent_target_options_1.AGENT_OPTION_DESCRIPTION)
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .action(async (worktreeId, options) => {
@@ -368,9 +416,9 @@ function createCaptureCommand() {
                 console.error('Error: Invalid agent.');
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
-            // Issue #868: Validate instance ID if provided
-            if (options.instance && !(0, api_client_1.isValidInstanceId)(options.instance)) {
-                console.error('Error: Invalid --instance. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
+            // Issue #868 / #2376: an instance id or a roster alias.
+            if (options.instance && !(0, instances_1.isInstanceSelector)(options.instance)) {
+                console.error(instances_1.INSTANCE_SELECTOR_ERROR);
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
             // Issue #1623: --tail / --raw only mean anything for the pane viewer.
@@ -424,16 +472,18 @@ function createCaptureCommand() {
             // alone captured the wrong (claude-named) session. Resolve the tool the
             // instance is registered under before asking. Issue #1925: 'read-only',
             // because capture looks rather than acts — see resolvePaneCliTool.
-            const agent = options.instance
-                ? await (0, instances_1.resolveInstanceCliTool)(client, worktreeId, options.instance, options.agent, 'read-only')
-                : options.agent;
-            // Build path with optional cliTool/instance query parameters
+            const target = options.instance
+                ? await (0, instances_1.resolveInstanceTarget)(client, worktreeId, options.instance, options.agent, 'read-only')
+                : null;
+            const agent = target ? target.cliToolId : options.agent;
+            // Build path with optional cliTool/instance query parameters. Issue
+            // #2376: the RESOLVED instance id — /current-output cannot read an alias.
             const query = new URLSearchParams();
             if (agent) {
                 query.set('cliTool', agent);
             }
-            if (options.instance) {
-                query.set('instance', options.instance);
+            if (target?.instanceId) {
+                query.set('instance', target.instanceId);
             }
             const qs = query.toString();
             const path = `/api/worktrees/${worktreeId}/current-output${qs ? `?${qs}` : ''}`;

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

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAwE3C"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiDpC;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CA8E3C"}

package/dist/cli/commands/docs.js

@@ -19,6 +19,44 @@ exports.createDocsCommand = createDocsCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
 const docs_reader_1 = require("../utils/docs-reader");
+const agent_operations_1 = require("../docs/agent-operations");
+/**
+ * Sections this command carries itself (Issue #2376).
+ *
+ * `docs-reader.ts` owns the section registry, and it is not in this Issue's
+ * change scope, so the delegation guide is registered here instead: the reader
+ * stays the authority on every section it already serves, and this one extra
+ * entry is resolved before the reader is consulted. Everything the reader does
+ * for a section — listing, reading, searching — is done for this one too, just
+ * a layer up.
+ *
+ * The next change to touch `docs-reader.ts` should fold this into
+ * `EMBEDDED_SECTIONS` and delete the three branches below.
+ */
+const LOCAL_SECTIONS = {
+    delegation: agent_operations_1.AGENT_DELEGATION_GUIDE,
+};
+/** Every section name, the reader's plus {@link LOCAL_SECTIONS}. */
+function allSectionNames() {
+    return [...(0, docs_reader_1.getAvailableSections)(), ...Object.keys(LOCAL_SECTIONS)];
+}
+/**
+ * Search {@link LOCAL_SECTIONS} the way `searchDocs` searches the reader's own:
+ * case-insensitive substring match, one entry per section with the matching
+ * lines.
+ *
+ * @param query - Search query, already length-checked by `searchDocs`
+ */
+function searchLocalSections(query) {
+    const lower = query.toLowerCase();
+    const results = [];
+    for (const [section, content] of Object.entries(LOCAL_SECTIONS)) {
+        const matches = content.split('\n').filter(line => line.toLowerCase().includes(lower));
+        if (matches.length > 0)
+            results.push({ section, matches });
+    }
+    return results;
+}
 /**
  * Create the docs command.
  * [MF-CONS-001] Returns a Command instance for program.addCommand().
@@ -31,7 +69,7 @@ function createDocsCommand() {
         .option('-a, --all', 'Show all available section names')
         .action((options) => {
         if (options.all) {
-            const sections = (0, docs_reader_1.getAvailableSections)();
+            const sections = allSectionNames();
             console.log('Available documentation sections:');
             console.log('');
             sections.forEach(s => console.log(`  - ${s}`));
@@ -40,11 +78,16 @@ function createDocsCommand() {
             process.exit(types_1.ExitCode.SUCCESS);
         }
         if (options.section) {
+            const local = LOCAL_SECTIONS[options.section];
+            if (local !== undefined) {
+                console.log(local);
+                process.exit(types_1.ExitCode.SUCCESS);
+            }
             if (!(0, docs_reader_1.isValidSection)(options.section)) {
                 console.error(`Unknown section: ${options.section}`);
                 console.error('');
                 console.error('Available sections:');
-                (0, docs_reader_1.getAvailableSections)().forEach(s => console.error(`  - ${s}`));
+                allSectionNames().forEach(s => console.error(`  - ${s}`));
                 process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
             }
             try {
@@ -59,7 +102,7 @@ function createDocsCommand() {
         }
         if (options.search) {
             try {
-                const results = (0, docs_reader_1.searchDocs)(options.search);
+                const results = [...(0, docs_reader_1.searchDocs)(options.search), ...searchLocalSections(options.search)];
                 if (results.length === 0) {
                     console.log(`No results found for: "${options.search}"`);
                 }
@@ -80,7 +123,7 @@ function createDocsCommand() {
             process.exit(types_1.ExitCode.SUCCESS);
         }
         // No option specified: show help
-        const sections = (0, docs_reader_1.getAvailableSections)();
+        const sections = allSectionNames();
         console.log('CommandMate Documentation');
         console.log('');
         console.log('Available sections:');

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

@@ -45,5 +45,72 @@ export type InstanceConflictMode = 'strict' | 'read-only';
  * @returns the CLI tool to send, or undefined to let an older server decide
  */
 export declare function resolveInstanceCliTool(client: ApiClient, worktreeId: string, instanceId: string, requestedAgent: string | undefined, mode?: InstanceConflictMode): Promise<string | undefined>;
+/**
+ * Whether `value` is something the server could resolve to an instance.
+ *
+ * An instance id, or an alias. Issue #2376 widened `--instance` to accept the
+ * second because it is the only name a human has for `codex-2`: the roster pane
+ * shows `Codex 2`, `commandmate instances <id>` prints it in the ALIAS column,
+ * and `--instance "Codex 2"` used to be rejected here — before any request —
+ * with "must be an alphanumeric identifier".
+ *
+ * The check is deliberately loose: an alias is free text (`レビュー担当`), and
+ * the authority on whether one EXISTS is the roster, which only the server has.
+ * All this rules out is a value no alias can be — empty, longer than the alias
+ * field allows, or carrying control characters.
+ *
+ * @param value - The `--instance` value as given
+ */
+export declare function isInstanceSelector(value: string): boolean;
+/**
+ * The sentence appended to every command's `--instance` help (Issue #2376).
+ *
+ * Kept beside the validator that accepts the form, not in
+ * `config/agent-target-options.ts`, so the help and the check cannot drift: the
+ * day the alias stage is removed, both go together.
+ */
+export declare const INSTANCE_ALIAS_HELP_SUFFIX: string;
+/** The sentence `--instance` is rejected with. One place, five commands. */
+export declare const INSTANCE_SELECTOR_ERROR: string;
+/** A resolved target: which agent, and which instance id to address it by. */
+export interface ResolvedInstanceTarget {
+    /** The agent to send as, or undefined to let an older server decide. */
+    cliToolId: string | undefined;
+    /**
+     * The instance id to put in the request, or undefined when the caller named
+     * no instance at all.
+     *
+     * **Not the value the user typed.** `--instance "Codex 2"` resolves here to
+     * `codex-2`, and every downstream body/query must carry the resolved id: the
+     * alias is a label the roster holds, and no other route knows how to read one.
+     *
+     * Undefined for a caller that passed no selector, even though the server
+     * answers with the worktree's default instance: a request that named no
+     * instance must keep not naming one, or `capture <id> --pane` would start
+     * pinning a session it was deliberately leaving to the server.
+     */
+    instanceId: string | undefined;
+}
+/**
+ * Resolve `--instance` — id or alias — to the agent and instance id to address.
+ *
+ * The one resolution path, as Issue #1925 established: the server answers,
+ * `resolveSessionTarget` asks, and this adds only what a CLI caller has to do
+ * with the two answers it can get back that a browser does not care about — a
+ * roster contradiction ({@link InstanceConflictMode}) and, since Issue #2376, an
+ * alias that names more than one row.
+ *
+ * The ambiguity is exit 2 with every candidate printed, never a pick: two rows
+ * called `Codex` are two different tmux sessions, and choosing one for the
+ * operator is how a message reaches the wrong agent silently.
+ *
+ * @param client - API client aimed at the server
+ * @param worktreeId - Worktree ID
+ * @param selector - The `--instance` value (an instance id or a roster alias),
+ *   or undefined for a caller that resolves only to learn the agent
+ * @param requestedAgent - The `--agent` value, if the user gave one
+ * @param mode - What a roster contradiction means for this caller
+ */
+export declare function resolveInstanceTarget(client: ApiClient, worktreeId: string, selector: string | undefined, requestedAgent: string | undefined, mode?: InstanceConflictMode): Promise<ResolvedInstanceTarget>;
 export declare function createInstancesCommand(): Command;
 //# sourceMappingURL=instances.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAwC,MAAM,qBAAqB,CAAC;AA8HtF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB7B;AA2ND,wBAAgB,sBAAsB,IAAI,OAAO,CAqEhD"}
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAkD,MAAM,qBAAqB,CAAC;AA8HhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAE6D,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,QAE0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAmCjC;AA2ND,wBAAgB,sBAAsB,IAAI,OAAO,CAqEhD"}

package/dist/cli/commands/instances.js

@@ -10,7 +10,10 @@
  *   commandmate instances <worktree-id> kill <instance-id>
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTANCE_SELECTOR_ERROR = exports.INSTANCE_ALIAS_HELP_SUFFIX = void 0;
 exports.resolveInstanceCliTool = resolveInstanceCliTool;
+exports.isInstanceSelector = isInstanceSelector;
+exports.resolveInstanceTarget = resolveInstanceTarget;
 exports.createInstancesCommand = createInstancesCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -103,20 +106,113 @@ function formatInstancesTable(rows) {
  * @returns the CLI tool to send, or undefined to let an older server decide
  */
 async function resolveInstanceCliTool(client, worktreeId, instanceId, requestedAgent, mode = 'strict') {
-    const target = await (0, session_target_1.resolveSessionTarget)(client, worktreeId, {
-        instanceId,
-        requestedCliTool: requestedAgent,
-    });
+    return (await resolveInstanceTarget(client, worktreeId, instanceId, requestedAgent, mode))
+        .cliToolId;
+}
+// ===========================================================================
+// Instance selectors: an id OR an alias (Issue #2376)
+// ===========================================================================
+/**
+ * The server's code for an `--instance` two roster rows answer to.
+ *
+ * Mirrors `AMBIGUOUS_INSTANCE_ALIAS` in
+ * `src/app/api/worktrees/[id]/resolve-target/route.ts`; duplicated rather than
+ * imported because a route module may export only the names Next.js accepts
+ * (`scripts/check-route-exports.mjs`, Issue #1946) — the same arrangement
+ * `send.ts` has with `PROMPT_WAITING`.
+ */
+const AMBIGUOUS_INSTANCE_ALIAS_CODE = 'ambiguous_instance_alias';
+/**
+ * Whether `value` is something the server could resolve to an instance.
+ *
+ * An instance id, or an alias. Issue #2376 widened `--instance` to accept the
+ * second because it is the only name a human has for `codex-2`: the roster pane
+ * shows `Codex 2`, `commandmate instances <id>` prints it in the ALIAS column,
+ * and `--instance "Codex 2"` used to be rejected here — before any request —
+ * with "must be an alphanumeric identifier".
+ *
+ * The check is deliberately loose: an alias is free text (`レビュー担当`), and
+ * the authority on whether one EXISTS is the roster, which only the server has.
+ * All this rules out is a value no alias can be — empty, longer than the alias
+ * field allows, or carrying control characters.
+ *
+ * @param value - The `--instance` value as given
+ */
+function isInstanceSelector(value) {
+    if ((0, api_client_1.isValidInstanceId)(value))
+        return true;
+    if (value.length === 0 || value.length > agent_instances_1.MAX_AGENT_ALIAS_LENGTH)
+        return false;
+    // eslint-disable-next-line no-control-regex
+    return !/[\u0000-\u001f\u007f]/.test(value);
+}
+/**
+ * The sentence appended to every command's `--instance` help (Issue #2376).
+ *
+ * Kept beside the validator that accepts the form, not in
+ * `config/agent-target-options.ts`, so the help and the check cannot drift: the
+ * day the alias stage is removed, both go together.
+ */
+exports.INSTANCE_ALIAS_HELP_SUFFIX = 'Also accepts a roster alias as shown by `commandmate instances <worktree-id>` '
+    + '(e.g. --instance "Codex 2"); an alias two rows answer to is exit 2 with the candidates listed.';
+/** The sentence `--instance` is rejected with. One place, five commands. */
+exports.INSTANCE_SELECTOR_ERROR = 'Error: Invalid --instance. Give an instance id (alphanumeric/underscore/hyphen, max 64 chars) '
+    + `or a roster alias (max ${agent_instances_1.MAX_AGENT_ALIAS_LENGTH} chars).`;
+/**
+ * Resolve `--instance` — id or alias — to the agent and instance id to address.
+ *
+ * The one resolution path, as Issue #1925 established: the server answers,
+ * `resolveSessionTarget` asks, and this adds only what a CLI caller has to do
+ * with the two answers it can get back that a browser does not care about — a
+ * roster contradiction ({@link InstanceConflictMode}) and, since Issue #2376, an
+ * alias that names more than one row.
+ *
+ * The ambiguity is exit 2 with every candidate printed, never a pick: two rows
+ * called `Codex` are two different tmux sessions, and choosing one for the
+ * operator is how a message reaches the wrong agent silently.
+ *
+ * @param client - API client aimed at the server
+ * @param worktreeId - Worktree ID
+ * @param selector - The `--instance` value (an instance id or a roster alias),
+ *   or undefined for a caller that resolves only to learn the agent
+ * @param requestedAgent - The `--agent` value, if the user gave one
+ * @param mode - What a roster contradiction means for this caller
+ */
+async function resolveInstanceTarget(client, worktreeId, selector, requestedAgent, mode = 'strict') {
+    let target;
+    try {
+        target = await (0, session_target_1.resolveSessionTarget)(client, worktreeId, {
+            instanceId: selector,
+            requestedCliTool: requestedAgent,
+        });
+    }
+    catch (error) {
+        if (error instanceof api_client_1.ApiError && error.apiCode === AMBIGUOUS_INSTANCE_ALIAS_CODE) {
+            console.error(`Error: ${error.payload?.error ?? `--instance '${selector}' is ambiguous.`}`);
+            for (const candidate of error.payload?.issues ?? []) {
+                console.error(`  - ${candidate}`);
+            }
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        throw error;
+    }
     if (target.conflict) {
         const detail = (0, session_target_1.describeSessionTargetConflict)(target.conflict);
         if (mode === 'strict') {
             console.error(`Error: ${detail}`);
             process.exit(types_1.ExitCode.CONFIG_ERROR);
-            return requestedAgent;
         }
-        console.error(`Warning: ${detail} Reading ${target.conflict.rosterCliTool}.`);
+        else {
+            console.error(`Warning: ${detail} Reading ${target.conflict.rosterCliTool}.`);
+        }
     }
-    return target.cliToolId;
+    return {
+        cliToolId: target.cliToolId,
+        // The server always echoes the effective instance; the fallback covers the
+        // `client-fallback` path against a daemon older than the endpoint, where the
+        // value the user typed is the only one there is.
+        instanceId: selector === undefined ? undefined : (target.instanceId ?? selector),
+    };
 }
 /**
  * The opencode session each instance will resume, keyed by instance id

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

@@ -0,0 +1,64 @@
+/**
+ * peers Command - the other agent sessions this one can talk to (Issue #2376)
+ *
+ *   commandmate peers [--json]
+ *
+ * ## Why `ls` + `instances` was not enough
+ *
+ * The two ids `ask` needs live in two different commands and neither one knows
+ * the caller. `ls` lists every worktree on the machine — including the dozen
+ * belonging to repositories this session has nothing to do with — and
+ * `instances` needs a worktree id per call. So working out "who can I ask?" was
+ * a fan-out plus a filter the agent had to invent, and inventing it is what
+ * produced the wrong `--instance` values this Issue exists to stop.
+ *
+ * This is that fan-out, done once, narrowed to the caller's own repository, with
+ * the caller's own row marked `(you)` and a ready-to-run `ask` line against
+ * every other row. The listing is the answer AND the example: the acceptance
+ * criterion for this command is that a line pasted out of it works.
+ *
+ * Scoped to the repository rather than to everything because that is the unit a
+ * delegation is about — sibling worktrees of one project, which is what
+ * `/worktree-setup` produces — and because a global listing is what `ls`
+ * already is.
+ */
+import { Command } from 'commander';
+import type { WorktreeItem } from '../types/api-responses';
+import { type SessionIdentity } from './whoami';
+/**
+ * The repository fields the list API sends and `WorktreeItem` does not declare.
+ *
+ * `src/cli/types/api-responses.ts` declares only the fields the CLI reads ("Only
+ * the fields the CLI reads are declared"), and until this command nothing read
+ * these two. Mirrored locally rather than widened there so the shared type keeps
+ * meaning what its header says it means; both are optional because a row written
+ * before the field existed, or by a non-sync path, carries neither.
+ */
+interface PeerWorktreeItem extends WorktreeItem {
+    repositoryPath?: string;
+    repositoryName?: string;
+}
+/** One session in the listing. */
+interface PeerRow {
+    worktreeId: string;
+    instanceId: string;
+    cliTool: string;
+    alias: string;
+    /** The worktree's aggregate STATUS word, as `commandmate ls` prints it. */
+    status: string;
+    /** True for the session running this command. */
+    isSelf: boolean;
+    /** The line to paste, or null for the caller's own row. */
+    ask: string | null;
+}
+/**
+ * Build the listing.
+ *
+ * @param worktrees - Every worktree the server knows
+ * @param identity - Who is asking
+ * @param binary - The command name to spell the examples with
+ */
+export declare function buildPeerRows(worktrees: PeerWorktreeItem[], identity: SessionIdentity, binary: string): PeerRow[];
+export declare function createPeersCommand(): Command;
+export {};
+//# sourceMappingURL=peers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"peers.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/peers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAiB,YAAY,EAAwB,MAAM,wBAAwB,CAAC;AAIhG,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAElB;;;;;;;;GAQG;AACH,UAAU,gBAAiB,SAAQ,YAAY;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,kCAAkC;AAClC,UAAU,OAAO;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAuED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,EAAE,CAuBX;AAoBD,wBAAgB,kBAAkB,IAAI,OAAO,CAkD5C"}