commandmate 0.31.3 → 0.32.0

package/dist/cli/commands/peers.js

@@ -0,0 +1,196 @@
+"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);
+            if (options.json) {
+                console.log(JSON.stringify({
+                    self: {
+                        worktreeId: identity.worktreeId,
+                        instanceId: identity.instanceId,
+                        cliToolId: identity.cliToolId,
+                    },
+                    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"}

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