commandmate 0.31.3 → 0.32.0

package/dist/cli/commands/respond.js

@@ -127,7 +127,7 @@ function createRespondCommand() {
         .argument('<worktree-id>', 'Worktree ID')
         .argument('[answer]', 'Response answer (yes, no, number, or free text)')
         .option('--default', "Select the prompt's default option (mutually exclusive with <answer>)")
-        .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, answer, options) => {
@@ -142,9 +142,9 @@ function createRespondCommand() {
                 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 #1681: exactly one of <answer> / --default
@@ -162,17 +162,20 @@ function createRespondCommand() {
             // and falls back to the worktree default, so `--instance codex` alone
             // answered into a session that was never started. Resolve the tool the
             // instance is registered under first.
-            const agent = options.instance
-                ? await (0, instances_1.resolveInstanceCliTool)(client, worktreeId, options.instance, options.agent)
-                : options.agent;
+            const target = options.instance
+                ? await (0, instances_1.resolveInstanceTarget)(client, worktreeId, options.instance, options.agent)
+                : null;
+            const agent = target ? target.cliToolId : options.agent;
+            // Issue #2376: the resolved id. /prompt-response reads instance ids.
+            const instanceId = target?.instanceId;
             // [DR2-06] Use prompt-response API with cliTool (not cliToolId)
             const body = useDefault ? { useDefault: true } : { answer };
             if (agent) {
                 body.cliTool = agent;
             }
             // Issue #868: target a specific agent instance
-            if (options.instance) {
-                body.instanceId = options.instance;
+            if (instanceId) {
+                body.instanceId = instanceId;
             }
             // Issue #2040: for an agent that publishes per-decision ids (opencode
             // today, and only opencode), a bare `respond <worktree> 3` names the ONE
@@ -186,7 +189,7 @@ function createRespondCommand() {
             // the structured path refuses it (`answerStructuredDecision` says so in
             // as many words) — while Enter at a `keys` dialog is a real answer that
             // this command has always been able to give.
-            const structured = !useDefault && (await addressesDecisionsById(client, worktreeId, agent, options.instance));
+            const structured = !useDefault && (await addressesDecisionsById(client, worktreeId, agent, instanceId));
             let result = null;
             if (structured) {
                 const outcome = await answerSolePendingDecision(client, worktreeId, body);

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

@@ -1 +1 @@
-{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAqLpC,wBAAgB,iBAAiB,IAAI,OAAO,CA+L3C"}
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/send.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoMpC,wBAAgB,iBAAiB,IAAI,OAAO,CAkP3C"}

package/dist/cli/commands/send.js

@@ -15,6 +15,7 @@ const agent_target_options_1 = require("../config/agent-target-options");
 const model_validation_1 = require("../config/model-validation");
 const agent_instances_1 = require("../utils/agent-instances");
 const instances_1 = require("./instances");
+const relays_1 = require("./relays");
 /** Auto-yes duration used when --duration is omitted. */
 const DEFAULT_AUTO_YES_DURATION = '1h';
 /**
@@ -58,7 +59,7 @@ function resolveAutoYesDurationMs(duration) {
  * @param durationMs - Duration already validated by resolveAutoYesDurationMs()
  * @param agent - CLI tool resolved for --instance (Issue #1629), else --agent
  */
-async function enableAutoYes(client, worktreeId, options, durationMs, agent) {
+async function enableAutoYes(client, worktreeId, options, durationMs, agent, instanceId) {
     const autoYesBody = {
         enabled: true,
         duration: durationMs,
@@ -69,8 +70,8 @@ async function enableAutoYes(client, worktreeId, options, durationMs, agent) {
     // Issue #896: per-instance auto-yes. When --instance is given, the poller keys
     // on worktreeId:cliToolId:instanceId so the targeted instance is auto-answered
     // independently of other instances of the same agent.
-    if (options.instance) {
-        autoYesBody.instanceId = options.instance;
+    if (instanceId) {
+        autoYesBody.instanceId = instanceId;
     }
     if (options.stopPattern) {
         autoYesBody.stopPattern = options.stopPattern;
@@ -104,13 +105,13 @@ async function registerInstance(client, worktreeId, instanceId, cliTool) {
  * from that worktree's verify.yaml. Every violation the server found is printed
  * before exiting, so a broken contract is fixed in one pass (Issue #1545).
  */
-async function createContractTask(client, worktreeId, options, agent) {
+async function createContractTask(client, worktreeId, options, agent, instanceId) {
     const body = { contractPath: options.contract };
     if (agent) {
         body.cliToolId = agent;
     }
-    if (options.instance) {
-        body.instanceId = options.instance;
+    if (instanceId) {
+        body.instanceId = instanceId;
     }
     try {
         const response = await client.post(`/api/worktrees/${worktreeId}/tasks`, body);
@@ -149,7 +150,7 @@ function createSendCommand() {
         .description('Send a message to a worktree agent')
         .argument('<worktree-id>', 'Worktree ID')
         .argument('[message]', 'Message to send (omit when using --contract)')
-        .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('--register', 'Register the --instance session into the agent-instance roster (needs --agent unless the instance id is itself a CLI tool id)')
         .option('--model <model>', 'Specify AI model for Copilot or Antigravity agent')
@@ -158,7 +159,20 @@ function createSendCommand() {
         .option('--stop-pattern <pattern>', 'Auto-yes stop pattern (regex). Matched against terminal output; cannot block commands (use the task contract\'s autoYes.denyPatterns for that)')
         .option('--contract <path>', 'Execution contract path relative to the worktree root (e.g. .commandmate/tasks/my-task.yaml). Records a task and sends the contract preamble plus its goal.')
         .option('--ignore-structured-prompt', 'Send even if only the agent\'s hooks report an open dialog (Issue #1737). Use when the pane looks idle but sends are refused; a prompt visible in the terminal is still refused.')
+        .option('--reply-to <target>', relays_1.REPLY_TO_OPTION_DESCRIPTION)
+        .option('--allow-relay-chain', relays_1.ALLOW_RELAY_CHAIN_DESCRIPTION)
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .addHelpText('after', `
+--reply-to registers a relay: when the target session finishes this turn,
+CommandMate puts its answer into the named session's composer, prefixed with
+\`[from <alias> / <worktree>]\`. Nothing blocks — there is no wait to run and
+no pane to scrape. Watch it with \`commandmate relays\`, withdraw it with
+\`commandmate relays cancel <id>\`; it expires after 24h either way.
+
+Exit 2 when the relay is refused: you are answering a relayed message already
+(pass --allow-relay-chain), the chain would exceed 3 hops, or an open relay
+between these two sessions exists. Nothing is sent in that case.
+`)
         .action(async (worktreeId, message, options) => {
         try {
             // [SEC4-04] Validate worktree ID
@@ -181,9 +195,10 @@ function createSendCommand() {
                 console.error(`Error: Invalid agent. Must be one of: ${cli_tool_ids_1.CLI_TOOL_IDS.join(', ')}`);
                 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: Validate the instance SELECTOR if provided. An id
+            // or an alias — which of the two it is, only the roster knows.
+            if (options.instance && !(0, instances_1.isInstanceSelector)(options.instance)) {
+                console.error(instances_1.INSTANCE_SELECTOR_ERROR);
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
             // Issue #1000: --register requires --instance, and requires --agent
@@ -216,9 +231,14 @@ function createSendCommand() {
             // the roster is the only place that pairs the two. Resolve it once, up
             // front, so the task row, the send and auto-yes all name the same tool
             // as the session that actually starts.
-            const agent = options.instance
-                ? await (0, instances_1.resolveInstanceCliTool)(client, worktreeId, options.instance, options.agent)
-                : options.agent;
+            const target = options.instance
+                ? await (0, instances_1.resolveInstanceTarget)(client, worktreeId, options.instance, options.agent)
+                : null;
+            const agent = target ? target.cliToolId : options.agent;
+            // Issue #2376: the RESOLVED id, never the string the user typed.
+            // `--instance "Codex 2"` has to reach /send as `codex-2`; no route but
+            // /resolve-target knows how to read an alias.
+            const instanceId = target?.instanceId;
             // Issue #576/#588/#989: Validate --model option via shared validator (DR1-003).
             // Issue #1925: judged against the RESOLVED agent, not against --agent.
             // `--instance copilot-2 --model gpt-5` names a copilot session in the
@@ -246,7 +266,7 @@ function createSendCommand() {
             let taskId;
             let content = message;
             if (options.contract) {
-                const task = await createContractTask(client, worktreeId, options, agent);
+                const task = await createContractTask(client, worktreeId, options, agent, instanceId);
                 taskId = task.taskId;
                 content = task.message;
                 console.error(`Task created: ${taskId}`);
@@ -254,7 +274,27 @@ function createSendCommand() {
             }
             // --auto-yes: enable auto-yes first (unless --model is specified, then after send) [DR2-02]
             if (options.autoYes && !options.model) {
-                await enableAutoYes(client, worktreeId, options, autoYesDurationMs, agent);
+                await enableAutoYes(client, worktreeId, options, autoYesDurationMs, agent, instanceId);
+            }
+            // Issue #2377: the relay is registered BEFORE the message goes out, so a
+            // session that answers immediately cannot finish its turn in the window
+            // between the send and the ledger row — the completion trigger reads the
+            // ledger, and a row that does not exist yet is a reply nobody collects.
+            // A refusal exits 2 here, having sent nothing.
+            let relayId;
+            if (options.replyTo) {
+                const replyEndpoint = await (0, relays_1.resolveRelayEndpoint)(client, options.replyTo);
+                const workerEndpoint = await (0, relays_1.resolveEndpointForWorktree)(client, worktreeId, options.instance, options.agent);
+                relayId = await (0, relays_1.registerRelay)(client, {
+                    from: replyEndpoint,
+                    to: workerEndpoint,
+                    allowRelayChain: options.allowRelayChain,
+                });
+                // stderr, not stdout: `--contract` already owns this command's stdout
+                // (it prints the task id there), and two commands writing two ids to
+                // one stream is how a `$(…)` capture ends up with both. `ask --async`
+                // is the form that hands the relay id back on stdout.
+                console.error(`Relay registered: ${relayId}`);
             }
             // [DR2-05] Send API uses "content" not "message"
             const sendBody = { content };
@@ -262,8 +302,8 @@ function createSendCommand() {
                 sendBody.cliToolId = agent;
             }
             // Issue #868: Include instance ID in send body
-            if (options.instance) {
-                sendBody.instanceId = options.instance;
+            if (instanceId) {
+                sendBody.instanceId = instanceId;
             }
             // Issue #576: Include model in send body
             if (options.model) {
@@ -284,6 +324,12 @@ function createSendCommand() {
                 if (taskId) {
                     await reportTaskStatus(client, taskId, 'failed');
                 }
+                // A relay whose message never arrived can never be answered; leaving
+                // it open would have the requester waiting 24h for a turn that was
+                // never started.
+                if (relayId) {
+                    await (0, relays_1.cancelRelayQuietly)(client, relayId);
+                }
                 // Issue #1708: the session is sitting on a prompt, so the message
                 // would have been typed into the prompt's input line rather than
                 // reaching the agent. Reported on its own so an unattended runner sees
@@ -304,13 +350,13 @@ function createSendCommand() {
             }
             // Issue #1000: register the ad-hoc instance into the roster after the
             // session has started, so a follow-up `commandmate instances` lists it.
-            if (options.register && options.instance) {
-                await registerInstance(client, worktreeId, options.instance, options.agent ?? options.instance);
+            if (options.register && instanceId) {
+                await registerInstance(client, worktreeId, instanceId, options.agent ?? instanceId);
             }
             // Issue #576: Enable auto-yes AFTER send when --model is specified
             // This avoids auto-yes interfering with the /model command interaction
             if (options.autoYes && options.model) {
-                await enableAutoYes(client, worktreeId, options, autoYesDurationMs, agent);
+                await enableAutoYes(client, worktreeId, options, autoYesDurationMs, agent, instanceId);
             }
         }
         catch (error) {

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

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/task.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,wBAAgB,iBAAiB,IAAI,OAAO,CA4H3C"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/task.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2DpC,wBAAgB,iBAAiB,IAAI,OAAO,CAuI3C"}

package/dist/cli/commands/task.js

@@ -19,6 +19,28 @@ const TASK_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-
 function formatTimestamp(value) {
     return value ?? '-';
 }
+/**
+ * The relay counts for the session this task ran in, or null (Issue #2377).
+ *
+ * Scoped to the task's own worktree AND instance, because that is the session a
+ * relay would have been opened by or against — a worktree-wide count would put
+ * another agent's delegations on this task's page.
+ *
+ * Best effort: a daemon with no relay ledger is one that answers 404 here, which
+ * must not fail `task show`.
+ */
+async function readTaskRelayCounts(client, task) {
+    const query = new URLSearchParams({ worktree: task.worktreeId });
+    if (task.instanceId)
+        query.set('instance', task.instanceId);
+    try {
+        const response = await client.get(`/api/relays?${query.toString()}`);
+        return response.counts ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 function printTaskLine(task) {
     const gates = task.contract.verify.gates;
     console.log([
@@ -115,6 +137,14 @@ function createTaskCommand() {
             console.log(`CREATED:   ${task.createdAt}`);
             console.log(`STARTED:   ${formatTimestamp(task.startedAt)}`);
             console.log(`FINISHED:  ${formatTimestamp(task.finishedAt)}`);
+            // Issue #2377: what this session delegated, and what came back. Printed
+            // before the verification block because it is about the same session,
+            // whereas the run below is about one judgement of it.
+            const relays = await readTaskRelayCounts(client, task);
+            if (relays) {
+                console.log(`RELAYS:    ${relays.delivered} delivered / ${relays.prompt} prompt / `
+                    + `${relays.expired} expired  (${relays.pending} open)`);
+            }
             if (!lastVerificationRun) {
                 console.log('VERIFY:    (no verification run yet)');
                 return;

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

@@ -19,6 +19,9 @@
  * Infrastructure errors use ExitCode (1, 2, 99)
  */
 import { Command } from 'commander';
+import type { WaitOptions } from '../types';
+import type { WaitPromptOutput } from '../types/api-responses';
+import { ApiClient } from '../utils/api-client';
 /**
  * Structured event types that mean "a turn is under way" (Issue #1839).
  *
@@ -45,5 +48,22 @@ import { Command } from 'commander';
  * `"paths": {}`), so the test is the only thing holding the two together.
  */
 export declare const TURN_OPENING_EVENT_TYPES: ReadonlySet<string>;
+/**
+ * Poll a single worktree until completion, prompt, or timeout.
+ *
+ * Exported since Issue #2376 so `ask` can do the WAITING half of its round trip
+ * with this function rather than a second implementation of it. `ask` is
+ * `send` + `wait` + "read the reply", and a private copy of the turn-boundary
+ * rules here (#1839's `basis`, #1975's unanswered-prompt hold, #1708's
+ * unclassified dwell) is a copy that would drift into reporting a completion
+ * this one refuses.
+ *
+ * `options.instance` must already be a resolved instance ID — see
+ * {@link resolveWaitInstance}.
+ */
+export declare function pollWorktree(client: ApiClient, worktreeId: string, options: WaitOptions): Promise<{
+    exitCode: number;
+    output?: WaitPromptOutput;
+}>;
 export declare function createWaitCommand(): Command;
 //# sourceMappingURL=wait.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6DpC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AAk8BH,wBAAgB,iBAAiB,IAAI,OAAO,CAmJ3C"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAMV,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAA+B,MAAM,qBAAqB,CAAC;AAwD7E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AA2bH;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC,CA6X1D;AAwKD,wBAAgB,iBAAiB,IAAI,OAAO,CA2J3C"}

package/dist/cli/commands/wait.js

@@ -21,6 +21,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TURN_OPENING_EVENT_TYPES = void 0;
+exports.pollWorktree = pollWorktree;
 exports.createWaitCommand = createWaitCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -28,6 +29,7 @@ const api_client_1 = require("../utils/api-client");
 const command_helpers_1 = require("../utils/command-helpers");
 const verify_runner_1 = require("../utils/verify-runner");
 const agent_target_options_1 = require("../config/agent-target-options");
+const instances_1 = require("./instances");
 /** [IA3-02] Polling interval 5 seconds (matches tmux-capture-cache TTL=2s) */
 const POLL_INTERVAL_MS = 5000;
 /**
@@ -508,6 +510,16 @@ function outstandingPrompt(data, submittedAt) {
 }
 /**
  * Poll a single worktree until completion, prompt, or timeout.
+ *
+ * Exported since Issue #2376 so `ask` can do the WAITING half of its round trip
+ * with this function rather than a second implementation of it. `ask` is
+ * `send` + `wait` + "read the reply", and a private copy of the turn-boundary
+ * rules here (#1839's `basis`, #1975's unanswered-prompt hold, #1708's
+ * unclassified dwell) is a copy that would drift into reporting a completion
+ * this one refuses.
+ *
+ * `options.instance` must already be a resolved instance ID — see
+ * {@link resolveWaitInstance}.
  */
 async function pollWorktree(client, worktreeId, options) {
     const startTime = Date.now();
@@ -970,6 +982,38 @@ function mergeExitCode(current, candidate) {
     };
     return rank(candidate) < rank(current) ? candidate : current;
 }
+/**
+ * `options` with `--instance` resolved from a selector to an instance ID
+ * (Issue #2376).
+ *
+ * `wait` polls `/current-output?instance=`, which matches instance IDs and
+ * nothing else, so an alias that reached it would filter to no session and the
+ * wait would report on the worktree default instead — the exact silent
+ * wrong-session failure Issue #1638 catalogued for `--agent`.
+ *
+ * @param client - API client
+ * @param worktreeId - Worktree the selector is resolved against
+ * @param options - The options as given
+ */
+async function resolveWaitInstance(client, worktreeId, options) {
+    if (!options.instance)
+        return options;
+    try {
+        const target = await (0, instances_1.resolveInstanceTarget)(client, worktreeId, options.instance, undefined);
+        return { ...options, instance: target.instanceId ?? options.instance };
+    }
+    catch (error) {
+        // Degrade to the pre-#2376 behaviour rather than failing the wait. An
+        // instance ID needs no resolution to reach `/current-output?instance=` —
+        // resolution exists here so that an ALIAS can — so a resolver that cannot
+        // be reached costs alias support for this call and nothing else. Failing
+        // instead would turn a reachable session into a non-zero exit for an
+        // orchestrator that has been waiting on it correctly for two years.
+        console.error(`Warning: could not resolve --instance '${options.instance}' `
+            + `(${(0, types_1.getErrorMessage)(error)}); using it as an instance id.`);
+        return options;
+    }
+}
 function createWaitCommand() {
     const cmd = new commander_1.Command('wait');
     cmd
@@ -978,7 +1022,7 @@ function createWaitCommand() {
         .option('--timeout <seconds>', 'Maximum wait time in seconds', parseInt)
         .option('--on-prompt <mode>', 'Prompt handling: agent (default) exits 10 with a prompt JSON payload on stdout (read it before re-capturing); human keeps waiting for a human reply')
         .option('--stall-timeout <seconds>', 'Maximum time without output change', parseInt)
-        .option('--instance <id>', agent_target_options_1.WAIT_INSTANCE_OPTION_DESCRIPTION)
+        .option('--instance <id>', `${agent_target_options_1.WAIT_INSTANCE_OPTION_DESCRIPTION} ${instances_1.INSTANCE_ALIAS_HELP_SUFFIX}`)
         .option('--verify', 'After completion, run every verification gate; exit 20 when a gate fails, 21 when there is nothing to verify')
         .option('--require-work', 'After completion, run only the work-evidence gate; exit 21 when the worktree has no commits and no uncommitted changes')
         .option('--fail-on-upstream-fault', 'Exit 11 instead of 0 when the agent returns to its composer with an upstream API failure (529/limit/API Error) on the frame')
@@ -1030,13 +1074,18 @@ A prompt the agent has not answered yet (Issue #1975):
                     return;
                 }
             }
-            // 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);
                 return;
             }
             const client = new api_client_1.ApiClient({ token: options.token });
+            // Issue #2376: resolve the selector PER worktree. `wait a b --instance
+            // "Codex 2"` is one alias against two rosters, and the id behind it can
+            // legitimately differ — resolving once and reusing the answer would poll
+            // the wrong session on the second worktree.
+            const perWorktreeOptions = await Promise.all(worktreeIds.map(id => resolveWaitInstance(client, id, options)));
             // Issue #1620: resolved before any polling starts. Once the agent stops
             // there is no reliable way left to tell which contract this wait was
             // about — the agent's own verification may have closed it by then.
@@ -1045,7 +1094,7 @@ A prompt the agent has not answered yet (Issue #1975):
                 : worktreeIds.map(() => undefined);
             if (worktreeIds.length === 1) {
                 // Single worktree
-                const result = await pollWorktree(client, worktreeIds[0], options);
+                const result = await pollWorktree(client, worktreeIds[0], perWorktreeOptions[0]);
                 if (result.output) {
                     // stdout for result (JSON output)
                     console.log(JSON.stringify(result.output));
@@ -1059,7 +1108,7 @@ A prompt the agent has not answered yet (Issue #1975):
                 return;
             }
             // [DR1-07] Multiple worktrees: Promise.allSettled for error isolation
-            const results = await Promise.allSettled(worktreeIds.map(id => pollWorktree(client, id, options)));
+            const results = await Promise.allSettled(worktreeIds.map((id, index) => pollWorktree(client, id, perWorktreeOptions[index])));
             // Collect results
             const outputs = [];
             let finalExitCode = types_1.WaitExitCode.SUCCESS;

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

@@ -0,0 +1,109 @@
+/**
+ * whoami Command - which session am I? (Issue #2376)
+ *
+ *   commandmate whoami [--json]
+ *
+ * ## Why an agent cannot answer this for itself
+ *
+ * Every delegation command needs a worktree id and an instance id, and an agent
+ * running INSIDE one of those sessions had no way to produce either. `ls` lists
+ * every worktree on the machine without saying which row is the caller;
+ * `instances` needs the worktree id you are trying to find out. So the first
+ * step of "ask that other session something" was a human pasting two ids in.
+ *
+ * ## Where the answer comes from, in order
+ *
+ * 1. **The environment.** `CM_WORKTREE_ID` / `CM_INSTANCE_ID` / `CM_CLI_TOOL`
+ *    first, then the `CM_AGENT_*` correlation variables CommandMate already
+ *    puts on the launch line of every tool whose hooks ride there (codex,
+ *    copilot, gemini, antigravity, opencode, command-code — see
+ *    `AGENT_CORRELATION_ENV_VARS` in `lib/hooks/sources/launch-command.ts`).
+ *    Authoritative when present: the server wrote them when it started the
+ *    session.
+ * 2. **The tmux session name.** claude is configured through `--settings` and
+ *    carries no launch-line environment at all, so for the most common agent
+ *    of the lot the environment says nothing. `mcbd-<tool>-<worktree>[-<n>]` is
+ *    the name CommandMate gave the session (`lib/cli-tools/session-name.ts`),
+ *    and a shell inside the pane can read it back from tmux. Shelling out to
+ *    `tmux` rather than importing anything: the CLI build sets `paths: {}` and
+ *    an ESLint guard (Issue #1922) forbids `lib/tmux/**` outright — `attach`
+ *    already talks to the binary the same way.
+ *
+ * Neither one answering means this is not a CommandMate-started session, and
+ * that is {@link NOT_IN_SESSION} rather than a guess.
+ */
+import { Command } from 'commander';
+import type { AgentInstance } from '../types/api-responses';
+import { ApiClient } from '../utils/api-client';
+/**
+ * Exit code for "this shell is not inside a CommandMate agent session".
+ *
+ * 3 by the Issue's contract. It is the numeric slot `ExitCode.START_FAILED`
+ * occupies for the server-lifecycle commands, and it is spelled here as its own
+ * constant rather than reused from that enum because the two mean nothing alike:
+ * a caller branching on `whoami` exiting 3 is asking "am I inside a session",
+ * not "did a server fail to start". `src/cli/types/index.ts` is where the shared
+ * enum lives; adding a name to it is a separate change from this one.
+ */
+export declare const NOT_IN_SESSION = 3;
+/** How this identity was established. Reported so a wrong answer is traceable. */
+export type IdentitySource = 'env' | 'tmux-session';
+/** Who the caller is, as far as anything can say. */
+export interface SessionIdentity {
+    worktreeId: string;
+    /** Instance ID. The primary instance is `instanceId === cliToolId` (#868). */
+    instanceId: string;
+    cliToolId: string;
+    source: IdentitySource;
+    /** The tmux session, when the identity came from (or could be checked against) one. */
+    sessionName: string | null;
+}
+/**
+ * The tmux session this process is running inside, or null.
+ *
+ * `$TMUX` is checked first so a call from an ordinary shell costs no process
+ * spawn at all — `whoami` outside a session is the case that has to be cheap,
+ * because a script that probes for CommandMate runs it once per invocation.
+ *
+ * @param env - Environment to read
+ * @returns The session name, or null when there is no tmux to ask
+ */
+export declare function readTmuxSessionName(env?: Readonly<Record<string, string | undefined>>): string | null;
+/** A session name split into the parts {@link resolveSessionName} put there. */
+interface ParsedSessionName {
+    cliToolId: string;
+    /** Everything after `mcbd-<tool>-`: a worktree id, possibly plus `-<n>`. */
+    remainder: string;
+}
+/**
+ * Split `mcbd-<tool>-<rest>` into its tool and the rest.
+ *
+ * Matched against the tool ids longest-first, because two of them contain a
+ * hyphen (`vibe-local`, `command-code`) and a shortest-first scan would read
+ * `mcbd-command-code-wt` as the tool `command` — which is not a tool, but the
+ * scan does not know that until it has already split in the wrong place.
+ *
+ * @param sessionName - A tmux session name
+ * @returns The parts, or null when this is not a CommandMate session name
+ */
+export declare function parseSessionName(sessionName: string): ParsedSessionName | null;
+/**
+ * Work out which session this process is running inside.
+ *
+ * @param client - API client, used only to disambiguate a session name
+ * @param env - Environment to read
+ * @returns The identity, or null when nothing establishes one
+ */
+export declare function resolveSessionIdentity(client: ApiClient, env?: Readonly<Record<string, string | undefined>>): Promise<SessionIdentity | null>;
+/**
+ * The roster row for this identity, or null.
+ *
+ * Best effort: the alias is a nicety (it is what the GUI calls this session),
+ * and a worktree whose roster cannot be read still has a usable identity.
+ */
+export declare function readOwnRosterEntry(client: ApiClient, identity: SessionIdentity): Promise<AgentInstance | null>;
+/** The sentence printed when nothing establishes an identity. */
+export declare const NOT_IN_SESSION_MESSAGE: string;
+export declare function createWhoamiCommand(): Command;
+export {};
+//# sourceMappingURL=whoami.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/whoami.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAsC,MAAM,wBAAwB,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKhD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAUhC,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,cAAc,CAAC;AAEpD,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,uFAAuF;IACvF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAcD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,MAAM,GAAG,IAAI,CASf;AAED,gFAAgF;AAChF,UAAU,iBAAiB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAa9E;AAkDD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAoCjC;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAO/B;AAED,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,QAMmC,CAAC;AAEvE,wBAAgB,mBAAmB,IAAI,OAAO,CA0C7C"}