commandmate 0.31.3 → 0.32.1

package/dist/cli/commands/relays.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * relays Command - the standing delegations this machine is holding (#2377)
+ *
+ *   commandmate relays [--worktree <id>] [--instance <id|alias>] [--json]
+ *   commandmate relays cancel <relay-id>
+ *
+ * ## Why a command and not a flag on `ls`
+ *
+ * A relay is the one piece of state in CommandMate that belongs to TWO sessions
+ * at once: session A is owed an answer, session B owes one, and neither
+ * worktree's own listing can show that without inventing a column for the other
+ * side. So the listing is its own thing, and it prints the pair — `from` and
+ * `to`, `→` between them — rather than a status word per row.
+ *
+ * With no `--worktree` it asks the session it is running inside (`whoami`'s
+ * resolution) and prints that session's two sides. That is the shape an agent
+ * uses: "what am I waiting for, and what do I owe?" is a question about the
+ * caller, and making the caller name itself is what #2376 exists to stop.
+ *
+ * ## What this module exports besides the command
+ *
+ * The `--reply-to` plumbing, because `send` and `ask` both take that flag and
+ * both have to turn one string into the two ids the ledger stores. Keeping
+ * {@link resolveRelayEndpoint} here rather than in `send.ts` is what stops the
+ * two commands from resolving `self` two different ways.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOW_RELAY_CHAIN_DESCRIPTION = exports.REPLY_TO_OPTION_DESCRIPTION = exports.RELAY_REFUSAL_CODES = void 0;
+exports.resolveRelayEndpoint = resolveRelayEndpoint;
+exports.resolveEndpointForWorktree = resolveEndpointForWorktree;
+exports.registerRelay = registerRelay;
+exports.cancelRelayQuietly = cancelRelayQuietly;
+exports.createRelaysCommand = createRelaysCommand;
+const commander_1 = require("commander");
+const types_1 = require("../types");
+const api_client_1 = require("../utils/api-client");
+const command_helpers_1 = require("../utils/command-helpers");
+const session_target_1 = require("../utils/session-target");
+const instances_1 = require("./instances");
+const whoami_1 = require("./whoami");
+/** crypto.randomUUID() output; mirrors RELAY_ID_PATTERN in the API route. */
+const RELAY_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The `--reply-to` values that mean "the session running this command". */
+const SELF_SELECTORS = new Set(['self', 'me']);
+/**
+ * The codes `POST /api/relays` refuses with.
+ *
+ * Mirrors `RelayRefusalCode` in `lib/relay/relay-policy` plus the route's own
+ * not-found; duplicated rather than imported so the CLI bundle does not pull the
+ * server's database graph in for four strings.
+ */
+exports.RELAY_REFUSAL_CODES = new Set([
+    'RELAY_CHAIN_BLOCKED',
+    'RELAY_HOPS_EXCEEDED',
+    'RELAY_DUPLICATE_PENDING',
+    'RELAY_SELF_TARGET',
+    'RELAY_WORKTREE_NOT_FOUND',
+]);
+/** The text `--reply-to` is documented with, shared by `send` and `ask`. */
+exports.REPLY_TO_OPTION_DESCRIPTION = 'Deliver the target\'s reply to this session when it finishes: '
+    + '<worktree-id>[@<instance-id|alias>], or `self` for the session running this command';
+/** The text `--allow-relay-chain` is documented with. */
+exports.ALLOW_RELAY_CHAIN_DESCRIPTION = 'Permit a relay opened while answering a relayed message (refused by default; '
+    + 'chains still stop at 3 hops)';
+/**
+ * Turn one `--reply-to` value into the two ids the ledger stores.
+ *
+ * Exits 2 rather than throwing: every failure here is a bad option value or a
+ * shell that is not inside a CommandMate session, and both are things the
+ * operator fixes on the command line.
+ *
+ * @param client - API client
+ * @param spec - The raw `--reply-to` value
+ */
+async function resolveRelayEndpoint(client, spec) {
+    if (SELF_SELECTORS.has(spec.trim().toLowerCase())) {
+        const identity = await (0, whoami_1.resolveSessionIdentity)(client);
+        if (!identity) {
+            console.error(whoami_1.NOT_IN_SESSION_MESSAGE);
+            console.error('  --reply-to self needs an identity; name the session explicitly instead.');
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        return { worktreeId: identity.worktreeId, instanceId: identity.instanceId };
+    }
+    const at = spec.indexOf('@');
+    const worktreeId = at === -1 ? spec : spec.slice(0, at);
+    const selector = at === -1 ? undefined : spec.slice(at + 1);
+    if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
+        console.error('Error: --reply-to must start with a valid worktree ID.');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    if (selector !== undefined && !(0, instances_1.isInstanceSelector)(selector)) {
+        console.error(`Error: --reply-to instance part: ${instances_1.INSTANCE_SELECTOR_ERROR}`);
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    return resolveEndpointForWorktree(client, worktreeId, selector);
+}
+/**
+ * The resolved endpoint for a worktree, with or without a named instance.
+ *
+ * Also what `send` / `ask` use for the relay's OTHER end — the session being
+ * asked — because the ledger stores a resolved id at both ends and the send's
+ * own `--instance` may have been omitted (meaning "the primary one", which only
+ * the server can name).
+ *
+ * @param client - API client
+ * @param worktreeId - Worktree ID
+ * @param selector - An instance id or roster alias, or undefined
+ * @param requestedAgent - The `--agent` value, if the caller gave one
+ */
+async function resolveEndpointForWorktree(client, worktreeId, selector, requestedAgent) {
+    if (selector !== undefined) {
+        const target = await (0, instances_1.resolveInstanceTarget)(client, worktreeId, selector, requestedAgent);
+        const instanceId = target.instanceId;
+        if (!instanceId) {
+            console.error(`Error: could not resolve instance '${selector}' in ${worktreeId}.`);
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        return { worktreeId, instanceId };
+    }
+    // No instance named: the server's own default for the worktree, which for a
+    // roster of one is that tool's primary instance. Asked rather than assumed —
+    // the CLI guessing `claude` is exactly the second authority #1925 removed.
+    const target = await (0, session_target_1.resolveSessionTarget)(client, worktreeId, {
+        requestedCliTool: requestedAgent,
+    });
+    const instanceId = target.instanceId ?? target.cliToolId;
+    if (!instanceId) {
+        console.error(`Error: ${worktreeId} declares no agent, so --reply-to cannot name one of its sessions. `
+            + 'Use <worktree-id>@<instance-id>.');
+        process.exit(types_1.ExitCode.CONFIG_ERROR);
+    }
+    return { worktreeId, instanceId };
+}
+/**
+ * Open a relay, printing the server's own refusal and exiting 2 on one.
+ *
+ * Exit 2 and not a bespoke code: every refusal is a decision the operator can
+ * change (drop the flag, cancel the other relay, stop forwarding), which is what
+ * `CONFIG_ERROR` means everywhere else in this CLI.
+ *
+ * @returns The relay id
+ */
+async function registerRelay(client, input) {
+    try {
+        const response = await client.post('/api/relays', {
+            from: input.from,
+            to: input.to,
+            allowRelayChain: input.allowRelayChain === true,
+        });
+        return response.relay.id;
+    }
+    catch (error) {
+        if (error instanceof api_client_1.ApiError && error.apiCode && exports.RELAY_REFUSAL_CODES.has(error.apiCode)) {
+            console.error(`Error: ${error.payload?.error ?? error.apiCode}`);
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        throw error;
+    }
+}
+/** Withdraw a relay, best effort. Used when the send it accompanied failed. */
+async function cancelRelayQuietly(client, relayId) {
+    try {
+        await client.post(`/api/relays/${relayId}/cancel`);
+    }
+    catch {
+        console.error(`Warning: could not withdraw relay ${relayId}; it will expire on its own.`);
+    }
+}
+function endpointLabel(endpoint) {
+    return `${endpoint.worktreeId}/${endpoint.instanceId}`;
+}
+function printRelayLine(relay) {
+    console.log([
+        relay.id,
+        relay.state,
+        `${endpointLabel(relay.from)} <- ${endpointLabel(relay.to)}`,
+        `hops=${relay.hops}`,
+        `expires=${new Date(relay.expiresAt).toISOString()}`,
+    ].join('\t'));
+}
+function createRelaysCommand() {
+    const cmd = new commander_1.Command('relays');
+    cmd
+        .description('List the open relays this session is waiting on and owes')
+        .option('--worktree <id>', 'Worktree to list (defaults to the session running this command)')
+        .option('--instance <id>', 'Agent instance inside --worktree (id or roster alias)')
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .addHelpText('after', `
+Columns: <relay-id>  <state>  <requester> <- <worker>  hops=<n>  expires=<iso>
+
+States: pending (the worker has not finished), prompt (it stopped on a
+confirmation and the requester was told), delivered / expired / cancelled.
+
+Withdraw one with \`commandmate relays cancel <relay-id>\`.
+`)
+        .action(async (options) => {
+        try {
+            if (options.worktree && !(0, api_client_1.isValidWorktreeId)(options.worktree)) {
+                console.error('Error: Invalid worktree ID format.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            if (options.instance && !(0, instances_1.isInstanceSelector)(options.instance)) {
+                console.error(instances_1.INSTANCE_SELECTOR_ERROR);
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            const client = new api_client_1.ApiClient({ token: options.token });
+            let endpoint = null;
+            if (options.worktree) {
+                endpoint = await resolveEndpointForWorktree(client, options.worktree, options.instance);
+            }
+            else {
+                const identity = await (0, whoami_1.resolveSessionIdentity)(client);
+                if (identity) {
+                    endpoint = { worktreeId: identity.worktreeId, instanceId: identity.instanceId };
+                }
+            }
+            const query = new URLSearchParams();
+            if (endpoint) {
+                query.set('worktree', endpoint.worktreeId);
+                query.set('instance', endpoint.instanceId);
+            }
+            const qs = query.toString();
+            const response = await client.get(`/api/relays${qs ? `?${qs}` : ''}`);
+            if (options.json) {
+                console.log(JSON.stringify(response, null, 2));
+                return;
+            }
+            if (!endpoint) {
+                console.error('Not inside a CommandMate agent session and no --worktree given; '
+                    + 'printing counts only.');
+            }
+            const { counts } = response;
+            console.error(`relays: pending=${counts.pending} prompt=${counts.prompt} `
+                + `delivered=${counts.delivered} expired=${counts.expired} cancelled=${counts.cancelled}`);
+            if (response.awaiting.length === 0 && response.owed.length === 0) {
+                console.error('No open relays.');
+                return;
+            }
+            if (response.awaiting.length > 0) {
+                console.error(`# waiting for (${response.awaiting.length})`);
+                response.awaiting.forEach(printRelayLine);
+            }
+            if (response.owed.length > 0) {
+                console.error(`# owed by me (${response.owed.length})`);
+                response.owed.forEach(printRelayLine);
+            }
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    cmd
+        .command('cancel')
+        .description('Withdraw an open relay so its reply is never delivered')
+        .argument('<relay-id>', 'Relay ID')
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (relayId, options) => {
+        try {
+            if (!RELAY_ID_PATTERN.test(relayId)) {
+                console.error('Error: Invalid relay ID format.');
+                process.exit(types_1.ExitCode.CONFIG_ERROR);
+            }
+            const client = new api_client_1.ApiClient({ token: options.token });
+            try {
+                const response = await client.post(`/api/relays/${relayId}/cancel`);
+                if (options.json) {
+                    console.log(JSON.stringify(response, null, 2));
+                }
+                else {
+                    console.error(`Relay ${relayId} cancelled.`);
+                }
+            }
+            catch (error) {
+                // A relay that already delivered is not a failure to report as one:
+                // saying "cancelled" would tell the caller they stopped a delivery
+                // that in fact happened.
+                if (error instanceof api_client_1.ApiError && error.apiCode === 'RELAY_ALREADY_CLOSED') {
+                    console.error(`Error: ${error.payload?.error ?? 'Relay is already closed.'}`);
+                    process.exit(types_1.ExitCode.CONFIG_ERROR);
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}

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

@@ -4,5 +4,8 @@
  * Issue #1551: report metrics (Eval metrics)
  */
 import { Command } from 'commander';
+import type { RelayCountsResponse } from '../types/api-responses';
+/** The relay line, in the same shape as the four above it. */
+export declare function formatRelayCounts(counts: RelayCountsResponse): string;
 export declare function createReportCommand(): Command;
 //# sourceMappingURL=report.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/report.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwFpC,wBAAgB,mBAAmB,IAAI,OAAO,CA6K7C"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/report.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,KAAK,EAGV,mBAAmB,EAKpB,MAAM,wBAAwB,CAAC;AA+EhC,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAKrE;AAmBD,wBAAgB,mBAAmB,IAAI,OAAO,CAiL7C"}

package/dist/cli/commands/report.js

@@ -5,6 +5,7 @@
  * Issue #1551: report metrics (Eval metrics)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatRelayCounts = formatRelayCounts;
 exports.createReportCommand = createReportCommand;
 const commander_1 = require("commander");
 const types_1 = require("../types");
@@ -59,6 +60,28 @@ const MAX_METRICS_DAYS = 90;
 function formatRate(value) {
     return value === null ? 'n/a' : `${(value * 100).toFixed(1)}%`;
 }
+/**
+ * Relay counts over the same window, or null when the daemon has no ledger.
+ *
+ * Best effort and separate from the vibe metrics on purpose: `/api/metrics/vibe`
+ * is computed from tasks and verification runs, and a relay is neither. A daemon
+ * that predates Issue #2377 answers 404 here, which is a reason to print the
+ * metrics without the relay line, not a reason to fail the command.
+ */
+async function readRelayCounts(client, days) {
+    try {
+        const response = await client.get(`/api/relays?days=${encodeURIComponent(String(days))}`);
+        return response.counts ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The relay line, in the same shape as the four above it. */
+function formatRelayCounts(counts) {
+    return (`Relays:       ${counts.delivered} delivered / ${counts.prompt} waiting on a prompt `
+        + `/ ${counts.expired} expired  (${counts.pending} still open, ${counts.cancelled} cancelled)`);
+}
 function formatVibeMetrics(m) {
     const { tasks, verification, intervention } = m;
     const topFails = verification.gateFailBreakdown
@@ -215,11 +238,16 @@ function createReportCommand() {
             }
             const client = new api_client_1.ApiClient({ token: options.token });
             const data = await client.get(`/api/metrics/vibe?days=${encodeURIComponent(String(days))}`);
+            // Issue #2377: delegation between sessions is work this harness did, and
+            // until now it was the only kind that left no mark on the metrics.
+            const relays = await readRelayCounts(client, days);
             if (options.json) {
-                console.log(JSON.stringify(data.metrics, null, 2));
+                console.log(JSON.stringify({ ...data.metrics, relays }, null, 2));
             }
             else {
                 console.log(formatVibeMetrics(data.metrics));
+                if (relays)
+                    console.log(formatRelayCounts(relays));
             }
         }
         catch (error) {

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

@@ -1 +1 @@
-{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsJpC,wBAAgB,oBAAoB,IAAI,OAAO,CAqK9C"}
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/respond.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2JpC,wBAAgB,oBAAoB,IAAI,OAAO,CAwK9C"}

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"}