commandmate 0.31.3 → 0.32.1

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");
@@ -19,6 +22,10 @@ const command_helpers_1 = require("../utils/command-helpers");
 const cli_tool_ids_1 = require("../config/cli-tool-ids");
 const agent_instances_1 = require("../utils/agent-instances");
 const session_target_1 = require("../utils/session-target");
+// Issue #2404: "the worktree is not on this server" is a different failure from
+// "the worktree id is wrong", and only the session's own identity can tell them
+// apart.
+const whoami_1 = require("./whoami");
 // Issue #2317: the tmux session name each instance runs in, so `commandmate
 // attach` / `tmux attach` need no hand-assembly of `mcbd-<tool>-<wt>[-<suffix>]`.
 const session_name_1 = require("../../lib/cli-tools/session-name");
@@ -103,20 +110,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
@@ -147,8 +247,7 @@ async function fetchOpencodeSessions(client, worktreeId, instances) {
  * Probes GET .../current-output?cliTool=&instance= per instance (same
  * endpoint capture.ts uses) since the roster itself carries no session state.
  */
-async function listInstances(worktreeId, options) {
-    const client = new api_client_1.ApiClient({ token: options.token });
+async function listInstances(client, worktreeId, options) {
     const instances = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
     // Issue #2038: one extra request for the whole worktree, and only when there
     // is an opencode instance to ask about — the endpoint is opencode-only and a
@@ -190,7 +289,7 @@ async function listInstances(worktreeId, options) {
 /**
  * Add action: append a new instance to the roster (PATCH full replacement).
  */
-async function addInstance(worktreeId, options) {
+async function addInstance(client, worktreeId, options) {
     if (!options.agent) {
         console.error('Error: add requires --agent <tool>.');
         process.exit(types_1.ExitCode.CONFIG_ERROR);
@@ -207,7 +306,6 @@ async function addInstance(worktreeId, options) {
         console.error(`Error: --alias exceeds ${agent_instances_1.MAX_AGENT_ALIAS_LENGTH} characters.`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    const client = new api_client_1.ApiClient({ token: options.token });
     const existing = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
     if (existing.length >= agent_instances_1.MAX_AGENT_INSTANCES) {
         console.error(`Error: worktree already has the maximum of ${agent_instances_1.MAX_AGENT_INSTANCES} agent instances.`);
@@ -236,12 +334,11 @@ async function addInstance(worktreeId, options) {
  * Remove action: drop an instance from the roster. Kills the session first
  * (when --kill) so the server can still resolve its CLI tool from the roster.
  */
-async function removeInstance(worktreeId, instanceId, options) {
+async function removeInstance(client, worktreeId, instanceId, options) {
     if (!(0, api_client_1.isValidInstanceId)(instanceId)) {
         console.error('Error: Invalid instance id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    const client = new api_client_1.ApiClient({ token: options.token });
     const existing = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
     if (!existing.some(inst => inst.id === instanceId)) {
         console.error(`Error: instance '${instanceId}' not found in roster.`);
@@ -267,7 +364,7 @@ async function removeInstance(worktreeId, instanceId, options) {
 /**
  * Alias action: rename an existing instance's display label.
  */
-async function renameInstance(worktreeId, instanceId, alias, options) {
+async function renameInstance(client, worktreeId, instanceId, alias) {
     if (!(0, api_client_1.isValidInstanceId)(instanceId)) {
         console.error('Error: Invalid instance id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
         process.exit(types_1.ExitCode.CONFIG_ERROR);
@@ -276,7 +373,6 @@ async function renameInstance(worktreeId, instanceId, alias, options) {
         console.error(`Error: alias must be 1-${agent_instances_1.MAX_AGENT_ALIAS_LENGTH} characters.`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    const client = new api_client_1.ApiClient({ token: options.token });
     const existing = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
     const index = existing.findIndex(inst => inst.id === instanceId);
     if (index === -1) {
@@ -292,15 +388,33 @@ async function renameInstance(worktreeId, instanceId, alias, options) {
  * The server resolves the backing CLI tool from the roster via the `instance`
  * query param (kill-session/route.ts), so no extra lookup is needed here.
  */
-async function killInstance(worktreeId, instanceId, options) {
+async function killInstance(client, worktreeId, instanceId) {
     if (!(0, api_client_1.isValidInstanceId)(instanceId)) {
         console.error('Error: Invalid instance id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    const client = new api_client_1.ApiClient({ token: options.token });
     await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
     console.error(`Session killed: ${instanceId}`);
 }
+/**
+ * Print the "you are on another server" hint when that is what a 404 means
+ * (Issue #2404).
+ *
+ * Runs only on a failure path, so the extra `tmux display-message` +
+ * `GET /api/worktrees` it costs buys the difference between a correct diagnosis
+ * and a wrong one. Never throws: {@link describeServerMismatch} swallows its own
+ * failures, and a diagnosis must not replace the error being diagnosed.
+ *
+ * @param client - The client whose request failed
+ * @param error - The caught error, diagnosed only when it is a 404
+ */
+async function warnIfDifferentServer(client, error) {
+    if (!(error instanceof api_client_1.ApiError) || error.statusCode !== 404)
+        return;
+    const mismatch = await (0, whoami_1.describeServerMismatch)(client);
+    if (mismatch)
+        console.error((0, whoami_1.formatServerMismatchHint)(mismatch));
+}
 function createInstancesCommand() {
     const cmd = new commander_1.Command('instances');
     cmd
@@ -315,6 +429,10 @@ function createInstancesCommand() {
         .option('--kill', 'Also kill the running session when removing an instance')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
         .action(async (worktreeId, action, rest, options) => {
+        // One client for the whole invocation (Issue #2404): every action built
+        // its own identical one, and the failure path below has to report the URL
+        // the request actually went to — a second construction is a second answer.
+        const client = new api_client_1.ApiClient({ token: options.token });
         try {
             if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
                 console.error('Error: Invalid worktree ID format.');
@@ -322,10 +440,10 @@ function createInstancesCommand() {
             }
             switch (action ?? 'list') {
                 case 'list':
-                    await listInstances(worktreeId, options);
+                    await listInstances(client, worktreeId, options);
                     break;
                 case 'add':
-                    await addInstance(worktreeId, options);
+                    await addInstance(client, worktreeId, options);
                     break;
                 case 'remove': {
                     const [instanceId] = rest;
@@ -333,7 +451,7 @@ function createInstancesCommand() {
                         console.error('Error: remove requires an <instance-id> argument.');
                         process.exit(types_1.ExitCode.CONFIG_ERROR);
                     }
-                    await removeInstance(worktreeId, instanceId, options);
+                    await removeInstance(client, worktreeId, instanceId, options);
                     break;
                 }
                 case 'alias': {
@@ -343,7 +461,7 @@ function createInstancesCommand() {
                         console.error('Error: alias requires <instance-id> and <new-alias> arguments.');
                         process.exit(types_1.ExitCode.CONFIG_ERROR);
                     }
-                    await renameInstance(worktreeId, instanceId, alias, options);
+                    await renameInstance(client, worktreeId, instanceId, alias);
                     break;
                 }
                 case 'kill': {
@@ -352,7 +470,7 @@ function createInstancesCommand() {
                         console.error('Error: kill requires an <instance-id> argument.');
                         process.exit(types_1.ExitCode.CONFIG_ERROR);
                     }
-                    await killInstance(worktreeId, instanceId, options);
+                    await killInstance(client, worktreeId, instanceId);
                     break;
                 }
                 default:
@@ -361,6 +479,13 @@ function createInstancesCommand() {
             }
         }
         catch (error) {
+            // Issue #2404: a 404 here says "no such worktree ON THIS SERVER", and
+            // `Resource not found. Check the worktree ID.` reads as "you typed it
+            // wrong". When the caller's own session belongs to a worktree this
+            // server does not list, the id was never the problem — say so before
+            // handleCommandError() exits, so nobody re-checks a correct id and then
+            // delegates to whatever this server does have.
+            await warnIfDifferentServer(client, error);
             (0, command_helpers_1.handleCommandError)(error);
         }
     });

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,EAML,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,CAkE5C"}

package/dist/cli/commands/peers.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPeerRows = buildPeerRows;
+exports.createPeersCommand = createPeersCommand;
+const commander_1 = require("commander");
+const api_client_1 = require("../utils/api-client");
+const command_helpers_1 = require("../utils/command-helpers");
+const command_reference_1 = require("../../lib/cli/command-reference");
+const whoami_1 = require("./whoami");
+/**
+ * The four-word status vocabulary, derived exactly as `ls` derives it.
+ *
+ * Duplicated from `ls.ts` rather than shared: this is three lines of precedence
+ * over three booleans, and the alternative — exporting `deriveStatus` from a
+ * command module so another command module can import it — couples two
+ * commands to save nothing. The vocabulary itself is pinned by `ls`'s own tests.
+ */
+function deriveStatus(wt) {
+    if (wt.isWaitingForResponse)
+        return 'waiting';
+    if (wt.isProcessing)
+        return 'running';
+    if (wt.isSessionRunning)
+        return 'ready';
+    return 'idle';
+}
+/**
+ * Whether `wt` belongs to the same repository as `self`.
+ *
+ * `repositoryPath` is the identity — two checkouts of the same upstream have the
+ * same `repositoryName` and are not the same repository — and the name is the
+ * fallback for a row that predates the field. A row with neither is excluded
+ * rather than assumed: a listing that quietly widened to the whole machine
+ * would put a `--instance` for somebody else's project in front of an agent.
+ *
+ * @param wt - Candidate worktree
+ * @param self - The caller's own worktree row
+ */
+function sameRepository(wt, self) {
+    if (self.repositoryPath && wt.repositoryPath) {
+        return wt.repositoryPath === self.repositoryPath;
+    }
+    if (self.repositoryName && wt.repositoryName) {
+        return wt.repositoryName === self.repositoryName;
+    }
+    // Neither side declares one: the caller's own worktree is still a peer group
+    // of one, and nothing else can be shown to belong to it.
+    return wt.id === self.id;
+}
+/**
+ * The roster of a worktree as the list API sent it.
+ *
+ * A worktree with no roster still has its primary instance — that is what
+ * `--instance` resolves to with no roster row at all (#868) — so an empty
+ * roster is reported as the worktree's own CLI tool rather than as no sessions.
+ *
+ * A worktree that declares no CLI tool either contributes NO rows, rather than
+ * a row for the agent it is statistically most likely to be running. An `ask`
+ * line naming the wrong tool is a message typed into a session that was never
+ * started, and the whole point of this listing is that its lines run.
+ */
+function rosterOf(wt) {
+    if (wt.agentInstances && wt.agentInstances.length > 0)
+        return wt.agentInstances;
+    if (!wt.cliToolId)
+        return [];
+    return [{ id: wt.cliToolId, cliTool: wt.cliToolId, alias: wt.cliToolId, order: 0 }];
+}
+/**
+ * Quote an argument for the `ask` example when it needs it.
+ *
+ * Instance ids never do (`isValidInstanceId` allows no shell metacharacter) but
+ * this command prints ids, not aliases, precisely so the line is paste-safe.
+ * The guard is here so a future id shape cannot silently produce a line that
+ * means something else in a shell.
+ */
+function shellArg(value) {
+    return /^[A-Za-z0-9_.:@+-]+$/.test(value) ? value : JSON.stringify(value);
+}
+/**
+ * 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
+ */
+function buildPeerRows(worktrees, identity, binary) {
+    const self = worktrees.find((wt) => wt.id === identity.worktreeId);
+    const scoped = self ? worktrees.filter((wt) => sameRepository(wt, self)) : [];
+    const rows = [];
+    for (const wt of scoped) {
+        const status = deriveStatus(wt);
+        for (const inst of rosterOf(wt)) {
+            const isSelf = wt.id === identity.worktreeId && inst.id === identity.instanceId;
+            rows.push({
+                worktreeId: wt.id,
+                instanceId: inst.id,
+                cliTool: inst.cliTool,
+                alias: inst.alias,
+                status,
+                isSelf,
+                ask: isSelf
+                    ? null
+                    : `${binary} ask ${shellArg(wt.id)} --instance ${shellArg(inst.id)} "<request>"`,
+            });
+        }
+    }
+    return rows;
+}
+/** Render the listing for a terminal. */
+function formatPeers(rows) {
+    if (rows.length === 0)
+        return 'No peer sessions found.';
+    return rows
+        .map((row) => {
+        const head = `${row.worktreeId} / ${row.instanceId}`;
+        const marker = row.isSelf ? '  (you)' : '';
+        const lines = [
+            `${head}${marker}`,
+            `  alias: ${row.alias}   tool: ${row.cliTool}   status: ${row.status}`,
+        ];
+        if (row.ask)
+            lines.push(`  ${row.ask}`);
+        return lines.join('\n');
+    })
+        .join('\n');
+}
+function createPeersCommand() {
+    const cmd = new commander_1.Command('peers');
+    cmd
+        .description('List the other agent sessions in this repository, with a ready-to-run `ask` line each')
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (options) => {
+        try {
+            const client = new api_client_1.ApiClient({ token: options.token });
+            const identity = await (0, whoami_1.resolveSessionIdentity)(client);
+            if (!identity) {
+                console.error(whoami_1.NOT_IN_SESSION_MESSAGE);
+                process.exit(whoami_1.NOT_IN_SESSION);
+                return;
+            }
+            const response = await client.get('/api/worktrees');
+            const worktrees = (response.worktrees ?? []);
+            // The same rule the GUI's panel and brief use (Issue #2120), from the
+            // same function: `CM_LAUNCHED_BY` is stamped by `commandmate start` on
+            // the server it spawns, and an agent pane inherits it — so a session
+            // started by the installed CLI is told `commandmate` and one started
+            // from a checkout is told `commandmatedev`, which is the name that
+            // actually exists on that PATH. A literal here would be a second
+            // authority on the one string the caller pastes into a shell.
+            const binary = (0, command_reference_1.resolveCommandMateBinary)();
+            const rows = buildPeerRows(worktrees, identity, binary);
+            // Issue #2404: the listing above is empty precisely when the caller's own
+            // worktree is absent from `worktrees` — which is what "you are on another
+            // server" looks like from here, and which `No peer sessions found.` reads
+            // as "you have no siblings". The list is already in hand, so the check is
+            // free and applies whichever source named the worktree.
+            const mismatch = (0, whoami_1.detectServerMismatch)(identity, new Set(worktrees.map((wt) => wt.id)), client.serverUrl);
+            if (mismatch)
+                console.error((0, whoami_1.formatServerMismatchWarning)(mismatch));
+            if (options.json) {
+                console.log(JSON.stringify({
+                    // `self` is unchanged: it answers "who is asking", and the server is
+                    // not part of that. The connection target is its own top-level field.
+                    self: {
+                        worktreeId: identity.worktreeId,
+                        instanceId: identity.instanceId,
+                        cliToolId: identity.cliToolId,
+                    },
+                    serverUrl: client.serverUrl,
+                    ...(mismatch ? { serverMismatch: true } : {}),
+                    peers: rows,
+                }, null, 2));
+                return;
+            }
+            console.log(formatPeers(rows));
+        }
+        catch (error) {
+            (0, command_helpers_1.handleCommandError)(error);
+        }
+    });
+    return cmd;
+}

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

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+import { Command } from 'commander';
+import { ApiClient } from '../utils/api-client';
+/**
+ * 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.
+ */
+export declare const RELAY_REFUSAL_CODES: Set<string>;
+/** One end of a relay, as the API wants it. */
+export interface RelayEndpointArg {
+    worktreeId: string;
+    instanceId: string;
+}
+/** The text `--reply-to` is documented with, shared by `send` and `ask`. */
+export declare const REPLY_TO_OPTION_DESCRIPTION: string;
+/** The text `--allow-relay-chain` is documented with. */
+export declare const ALLOW_RELAY_CHAIN_DESCRIPTION: string;
+/**
+ * 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
+ */
+export declare function resolveRelayEndpoint(client: ApiClient, spec: string): Promise<RelayEndpointArg>;
+/**
+ * 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
+ */
+export declare function resolveEndpointForWorktree(client: ApiClient, worktreeId: string, selector: string | undefined, requestedAgent?: string): Promise<RelayEndpointArg>;
+/** What {@link registerRelay} needs. */
+export interface RegisterRelayInput {
+    /** The session that will receive the reply. */
+    from: RelayEndpointArg;
+    /** The session being asked. */
+    to: RelayEndpointArg;
+    allowRelayChain?: boolean;
+}
+/**
+ * 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
+ */
+export declare function registerRelay(client: ApiClient, input: RegisterRelayInput): Promise<string>;
+/** Withdraw a relay, best effort. Used when the send it accompanied failed. */
+export declare function cancelRelayQuietly(client: ApiClient, relayId: string): Promise<void>;
+export declare function createRelaysCommand(): Command;
+//# sourceMappingURL=relays.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relays.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/relays.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,EAAE,SAAS,EAA+B,MAAM,qBAAqB,CAAC;AAgB7E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,aAM9B,CAAC;AAEH,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4EAA4E;AAC5E,eAAO,MAAM,2BAA2B,QAEiD,CAAC;AAE1F,yDAAyD;AACzD,eAAO,MAAM,6BAA6B,QAER,CAAC;AAEnC;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,CAAC,CAyB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,IAAI,EAAE,gBAAgB,CAAC;IACvB,+BAA+B;IAC/B,EAAE,EAAE,gBAAgB,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,+EAA+E;AAC/E,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM1F;AAyBD,wBAAgB,mBAAmB,IAAI,OAAO,CA8H7C"}