commandmate 0.49.2 → 0.50.0

package/dist/cli/commands/instances.js

@@ -8,6 +8,7 @@
  *   commandmate instances <worktree-id> remove <instance-id> [--kill]
  *   commandmate instances <worktree-id> alias <instance-id> <new-alias>
  *   commandmate instances <worktree-id> kill <instance-id>
+ *   commandmate instances <worktree-id> set-role <instance-id> (--role <role> | --none | --inherit)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INSTANCE_SELECTOR_ERROR = exports.INSTANCE_ALIAS_HELP_SUFFIX = void 0;
@@ -33,6 +34,7 @@ const session_kill_ledger_1 = require("../../lib/verification/session-kill-ledge
 // attach` / `tmux attach` need no hand-assembly of `mcbd-<tool>-<wt>[-<suffix>]`.
 const session_name_1 = require("../../lib/cli-tools/session-name");
 const validation_1 = require("../../lib/cli-tools/validation");
+const agent_roles_1 = require("../utils/agent-roles");
 /**
  * The tmux session name for one roster row, or null.
  *
@@ -58,6 +60,18 @@ function deriveInstanceSession(worktreeId, inst) {
  * sentence. `--json` carries the full string; the table is a table.
  */
 const MAX_SESSION_TITLE_COLUMN = 40;
+function describeNextRole(next) {
+    if (next.kind === 'role')
+        return `${next.role.name}(${next.source})`;
+    return next.kind === 'none' ? `none(${next.source})` : 'ambiguous';
+}
+/** The three role columns of one row. `unknown` for a startup role is what the server knows. */
+function roleColumns(role) {
+    if (!role)
+        return ['', '', ''];
+    const atStart = role.launched === null ? 'unknown' : role.launched.roleName ?? 'none';
+    return [atStart, describeNextRole(role.effectiveNext), role.restartPending];
+}
 /**
  * Format instance rows as a table for terminal display.
  * [DR1-08 consistency] Mirrors ls.ts's formatTable().
@@ -68,11 +82,14 @@ const MAX_SESSION_TITLE_COLUMN = 40;
 function formatInstancesTable(rows) {
     if (rows.length === 0)
         return 'No agent instances found.';
+    // Issue #4116: appended, as #1785 and #2038 did, and only by a server that knows.
+    const showRoles = rows.some((r) => r.role !== undefined);
     const headers = [
         'INSTANCE_ID', 'ALIAS', 'CLI_TOOL', 'RUNNING', 'AUTO_YES', 'MODEL', 'EFFORT',
         // Issue #2038 appends, exactly as #1785 did, so anything reading this table
         // by column position keeps working. Issue #2317 appends for the same reason.
         'SESSION_ID', 'SESSION_TITLE', 'TMUX_SESSION',
+        ...(showRoles ? ['ROLE_AT_START', 'ROLE_NEXT', 'RESTART_PENDING'] : []),
     ];
     const dataRows = rows.map(r => [
         r.instanceId,
@@ -90,6 +107,7 @@ function formatInstancesTable(rows) {
         r.sessionId ?? '',
         (r.sessionTitle ?? '').slice(0, MAX_SESSION_TITLE_COLUMN),
         r.tmuxSession ?? '',
+        ...(showRoles ? roleColumns(r.role) : []),
     ]);
     const colWidths = headers.map((h, i) => Math.max(h.length, ...dataRows.map(r => r[i].length)));
     const headerLine = headers.map((h, i) => h.padEnd(colWidths[i])).join('  ');
@@ -275,6 +293,34 @@ async function fetchArmedAutoYes(client, worktreeId) {
         return null;
     }
 }
+/**
+ * Each instance's role, keyed by instance id, or null when the server does not say.
+ * Like the two reads above: a listing is never failed by a column.
+ */
+async function fetchInstanceRoles(client, worktreeId) {
+    try {
+        const { instances } = await client.get(`/api/worktrees/${worktreeId}/instances/roles`);
+        if (!Array.isArray(instances))
+            return null;
+        return new Map(instances.map(({ instanceId, stored, application }) => [instanceId, { stored, ...application }]));
+    }
+    catch (error) {
+        (0, api_client_1.rethrowIfDeadlineExceeded)(error);
+        return null;
+    }
+}
+/**
+ * `--require-roles`: for a caller that must not read "the roles could not be read" as
+ * "this server has none". Every failure is the command's; the route being missing is
+ * `role_api_unavailable`, through {@link reportRoleFailure}.
+ */
+async function readInstanceRolesStrict(client, worktreeId) {
+    const { instances } = await client.get(`/api/worktrees/${worktreeId}/instances/roles`);
+    if (!Array.isArray(instances)) {
+        throw new agent_roles_1.RoleCliError('role_read_failed', 'The server answered the role settings with no instances.', types_1.ExitCode.UNEXPECTED_ERROR);
+    }
+    return new Map(instances.map(({ instanceId, stored, application }) => [instanceId, { stored, ...application }]));
+}
 /**
  * List action: roster + live running/auto-yes status per instance.
  * Probes GET .../current-output?cliTool=&instance= per instance (same
@@ -326,7 +372,7 @@ async function listInstances(client, worktreeId, options) {
     // size, and none for an empty one. Asked after the probes above, so the
     // column is the latest of the readings this listing takes.
     const armed = instances.length > 0 ? await fetchArmedAutoYes(client, worktreeId) : null;
-    const rows = armed === null
+    const armedRows = armed === null
         ? sessionRows
         : sessionRows.map(({ autoYesAnswerMode: _sessionMode, ...row }) => {
             const entry = armed.get(row.instanceId);
@@ -341,52 +387,194 @@ async function listInstances(client, worktreeId, options) {
                 ...(entry?.releasedByRestart ? { autoYesStopReason: 'server-restart' } : {}),
             };
         });
+    // Issue #4116: after the others, and additive.
+    const roles = options.requireRoles
+        ? await readInstanceRolesStrict(client, worktreeId)
+        : instances.length > 0 ? await fetchInstanceRoles(client, worktreeId) : null;
+    const rows = armedRows.map((row) => {
+        const role = roles?.get(row.instanceId);
+        if (options.requireRoles && !role) {
+            throw new agent_roles_1.RoleCliError('role_read_failed', `The server said nothing about the role of ${row.instanceId}.`, types_1.ExitCode.UNEXPECTED_ERROR);
+        }
+        return role ? { ...row, role } : row;
+    });
     if (options.json) {
         console.log(JSON.stringify(rows, null, 2));
         return;
     }
     console.log(formatInstancesTable(rows));
 }
+/** One instance's entry in a settings answer, or the failure for a server that left it out. */
+function roleEntryOf(settings, instanceId) {
+    const entry = settings.instances.find((instance) => instance.instanceId === instanceId);
+    if (!entry)
+        throw new agent_roles_1.RoleCliError('roster_changed', `Instance '${instanceId}' is no longer in the roster.`, types_1.RoleExitCode.CONFLICT);
+    return entry;
+}
+/** The setting beside the process: what `set-role` and `add --role` answer with. */
+function roleChangeResult(settings, entry) {
+    return {
+        success: true,
+        instanceId: entry.instanceId,
+        cliToolId: entry.cliToolId,
+        adapterEnabled: entry.adapterEnabled,
+        stored: entry.stored,
+        effectiveNext: entry.application.effectiveNext,
+        launched: entry.application.launched,
+        requested: entry.application.requested,
+        restartPending: entry.application.restartPending,
+        // Only a difference is pending: `unknown` is not known to be one.
+        applyPending: entry.application.restartPending === 'yes',
+        ...(entry.application.replacesDefaultInstructions ? { replacesDefaultInstructions: true } : {}),
+        rosterRevision: settings.rosterRevision,
+    };
+}
+function printRoleChange(worktreeId, entry) {
+    const { effectiveNext, launched, restartPending } = entry.application;
+    console.error(`Next start: ${describeNextRole(effectiveNext)}`);
+    console.error(`Running process started with: ${launched === null ? 'not known' : launched.roleName ?? 'no role'}`);
+    if (restartPending === 'yes') {
+        console.error(`Pending: the running process keeps its role until it is stopped (commandmate instances ${worktreeId} kill ${entry.instanceId}).`);
+    }
+    else if (restartPending === 'unknown') {
+        console.error('Whether a restart is needed is not known: nothing is known about a running process, if there is one.');
+    }
+    if (!entry.adapterEnabled && effectiveNext.kind === 'role') {
+        console.error(`Warning: roles are not enabled for ${entry.cliToolId} yet: a start that resolves to one is refused.`);
+    }
+}
+/**
+ * set-role action: save an instance's role for its next start. A running session is
+ * not touched, and the answer compares the two.
+ */
+async function setInstanceRole(client, worktreeId, instanceId, options) {
+    if (!(0, api_client_1.isValidInstanceId)(instanceId)) {
+        throw (0, agent_roles_1.usageError)('Invalid instance id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
+    }
+    if (options.role === false)
+        throw (0, agent_roles_1.usageError)('set-role says "no role" with --none.');
+    const given = [options.role !== undefined, options.none === true, options.inherit === true].filter(Boolean).length;
+    if (given !== 1)
+        throw (0, agent_roles_1.usageError)('set-role needs one of --role <role>, --none or --inherit.');
+    const role = options.none
+        ? { state: 'none' }
+        : options.inherit
+            ? { state: 'inherit' }
+            : { state: 'role', roleId: (await (0, agent_roles_1.resolveRole)(client, options.role)).id };
+    const settings = await (0, agent_roles_1.roleWrite)(`commandmate instances ${worktreeId}`, () => client.put(`/api/worktrees/${worktreeId}/instances/roles`, { instanceId, role }));
+    const entry = roleEntryOf(settings, instanceId);
+    if (options.json) {
+        console.log(JSON.stringify(roleChangeResult(settings, entry), null, 2));
+        return;
+    }
+    const stored = entry.stored;
+    console.log(`Role saved for ${instanceId}: ${stored.state === 'role' ? stored.roleName : stored.state}`);
+    printRoleChange(worktreeId, entry);
+}
+/** The refusals a `--role` flag on another action gets. */
+function assertNoRoleFlags(action, options) {
+    const allowed = {
+        add: ['role'],
+        'set-role': ['role', 'none', 'inherit'],
+    };
+    for (const flag of ['role', 'none', 'inherit']) {
+        if (options[flag] !== undefined && !(allowed[action] ?? []).includes(flag)) {
+            throw (0, agent_roles_1.usageError)(`--${flag} does not apply to '${action}'.`);
+        }
+    }
+}
 /**
  * Add action: append a new instance to the roster (PATCH full replacement).
  */
 async function addInstance(client, worktreeId, options) {
-    if (!options.agent) {
-        console.error('Error: add requires --agent <tool>.');
+    // Issue #4116: with a role flag this is a role form, whose `--json` answers every
+    // failure on stdout. The exit code is the same either way.
+    const refuse = (message) => {
+        if (options.role !== undefined)
+            throw (0, agent_roles_1.usageError)(message);
+        console.error(`Error: ${message}`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
+    };
+    if (!options.agent) {
+        refuse('add requires --agent <tool>.');
+        return;
     }
     if (!(0, cli_tool_ids_1.isCliToolId)(options.agent)) {
-        console.error(`Error: Invalid --agent. Must be one of: ${cli_tool_ids_1.CLI_TOOL_IDS.join(', ')}`);
-        process.exit(types_1.ExitCode.CONFIG_ERROR);
+        refuse(`Invalid --agent. Must be one of: ${cli_tool_ids_1.CLI_TOOL_IDS.join(', ')}`);
     }
     if (options.id && !(0, api_client_1.isValidInstanceId)(options.id)) {
-        console.error('Error: Invalid --id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
-        process.exit(types_1.ExitCode.CONFIG_ERROR);
+        refuse('Invalid --id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
     }
     if (options.alias && options.alias.length > agent_instances_1.MAX_AGENT_ALIAS_LENGTH) {
-        console.error(`Error: --alias exceeds ${agent_instances_1.MAX_AGENT_ALIAS_LENGTH} characters.`);
-        process.exit(types_1.ExitCode.CONFIG_ERROR);
+        refuse(`--alias exceeds ${agent_instances_1.MAX_AGENT_ALIAS_LENGTH} characters.`);
     }
-    const existing = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
+    // Issue #4116: a role goes in with the instance, through the route that creates both
+    // in one transaction and refuses a roster changed since this read.
+    if (options.role !== undefined)
+        (0, agent_roles_1.assertRoleTool)(options.agent);
+    const roleAssignment = await (0, agent_roles_1.roleAssignmentFromFlag)(client, options.role);
+    const roleSettings = roleAssignment === undefined
+        ? null
+        : await client.get(`/api/worktrees/${worktreeId}/instances/roles`);
+    const roster = roleSettings === null ? await (0, agent_instances_1.fetchAgentRoster)(client, worktreeId) : null;
+    const existing = roster !== null
+        ? roster.instances
+        : roleSettings.instances.map((instance, order) => ({
+            id: instance.instanceId,
+            cliTool: instance.cliToolId,
+            alias: instance.alias,
+            order,
+        }));
     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.`);
-        process.exit(types_1.ExitCode.CONFIG_ERROR);
+        refuse(`worktree already has the maximum of ${agent_instances_1.MAX_AGENT_INSTANCES} agent instances.`);
     }
     const id = options.id ?? (0, agent_instances_1.nextInstanceId)(options.agent, existing);
     if (existing.some(inst => inst.id === id)) {
+        if (roleSettings !== null) {
+            throw new agent_roles_1.RoleCliError('instance_exists', `Instance '${id}' already exists. Set its role with: set-role ${id}`, types_1.RoleExitCode.CONFLICT);
+        }
         console.error(`Error: instance '${id}' already exists.`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
     // Primary-anchor consistency (mirrors validateAgentInstancesInput on the
     // server): an id equal to a CLI tool id must back that exact tool.
     if ((0, cli_tool_ids_1.isCliToolId)(id) && id !== options.agent) {
-        console.error(`Error: instance id '${id}' conflicts with --agent '${options.agent}'.`);
-        process.exit(types_1.ExitCode.CONFIG_ERROR);
+        refuse(`instance id '${id}' conflicts with --agent '${options.agent}'.`);
     }
     const alias = options.alias ?? (0, agent_instances_1.defaultAlias)(options.agent, id);
-    const next = [...existing, { id, cliTool: options.agent, alias, order: existing.length }];
-    await (0, agent_instances_1.saveAgentInstances)(client, worktreeId, next);
-    console.error(`Instance added: ${id} (${options.agent})`);
+    if (roleAssignment !== undefined && roleSettings !== null) {
+        const agent = options.agent;
+        const created = await (0, agent_roles_1.roleWrite)(`commandmate instances ${worktreeId}`, () => client.post(`/api/worktrees/${worktreeId}/instances/roles`, {
+            instance: { id, cliTool: agent, alias },
+            role: roleAssignment,
+            expectedRosterRevision: roleSettings.rosterRevision,
+        }));
+        const entry = roleEntryOf(created, created.created.instanceId);
+        console.error(`Instance added: ${id} (${options.agent})`);
+        if (options.json) {
+            console.log(JSON.stringify({ ...roleChangeResult(created, entry), created: created.created }, null, 2));
+        }
+        else {
+            printRoleChange(worktreeId, entry);
+        }
+        return;
+    }
+    // Issue #4132: built again if the roster moved after the read, so the checks above and
+    // the free id are asked again of what is really there.
+    const agent = options.agent;
+    let addedId = id;
+    const next = await (0, agent_instances_1.saveRosterChange)(client, worktreeId, roster ?? { instances: existing }, (base) => {
+        if (base.length >= agent_instances_1.MAX_AGENT_INSTANCES) {
+            refuse(`worktree already has the maximum of ${agent_instances_1.MAX_AGENT_INSTANCES} agent instances.`);
+        }
+        addedId = options.id ?? (0, agent_instances_1.nextInstanceId)(agent, base);
+        if (base.some((inst) => inst.id === addedId)) {
+            refuse(`instance '${addedId}' already exists.`);
+        }
+        const added = { id: addedId, cliTool: agent, alias: options.alias ?? (0, agent_instances_1.defaultAlias)(agent, addedId), order: base.length };
+        return [...base, added];
+    });
+    console.error(`Instance added: ${addedId} (${options.agent})`);
     if (options.json) {
         console.log(JSON.stringify(next, null, 2));
     }
@@ -431,7 +619,8 @@ async function removeInstance(client, worktreeId, instanceId, options) {
         console.error('Error: Invalid instance id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    const existing = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
+    const roster = await (0, agent_instances_1.fetchAgentRoster)(client, worktreeId);
+    const existing = roster.instances;
     if (!existing.some(inst => inst.id === instanceId)) {
         console.error(`Error: instance '${instanceId}' not found in roster.`);
         process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
@@ -450,8 +639,16 @@ async function removeInstance(client, worktreeId, instanceId, options) {
             console.error(`Warning: could not kill session for ${instanceId}: ${(0, types_1.getErrorMessage)(killError)}`);
         }
     }
-    const next = existing.filter(inst => inst.id !== instanceId);
-    await (0, agent_instances_1.saveAgentInstances)(client, worktreeId, next);
+    // Issue #4132: what the kill above did is not repeated when the roster moved; only this is.
+    await (0, agent_instances_1.saveRosterChange)(client, worktreeId, roster, (base) => {
+        if (!base.some(inst => inst.id === instanceId))
+            return null;
+        if (base.length <= agent_instances_1.MIN_AGENT_INSTANCES) {
+            console.error('Error: cannot remove the last remaining agent instance.');
+            process.exit(types_1.ExitCode.CONFIG_ERROR);
+        }
+        return base.filter(inst => inst.id !== instanceId);
+    });
     console.error(`Instance removed from roster: ${instanceId}`);
 }
 /**
@@ -466,14 +663,14 @@ async function renameInstance(client, worktreeId, instanceId, alias) {
         console.error(`Error: alias must be 1-${agent_instances_1.MAX_AGENT_ALIAS_LENGTH} characters.`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    const existing = await (0, agent_instances_1.fetchAgentInstances)(client, worktreeId);
-    const index = existing.findIndex(inst => inst.id === instanceId);
-    if (index === -1) {
-        console.error(`Error: instance '${instanceId}' not found in roster.`);
-        process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
-    }
-    const next = existing.map((inst, i) => (i === index ? { ...inst, alias } : inst));
-    await (0, agent_instances_1.saveAgentInstances)(client, worktreeId, next);
+    const roster = await (0, agent_instances_1.fetchAgentRoster)(client, worktreeId);
+    await (0, agent_instances_1.saveRosterChange)(client, worktreeId, roster, (base) => {
+        if (!base.some(inst => inst.id === instanceId)) {
+            console.error(`Error: instance '${instanceId}' not found in roster.`);
+            process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+        }
+        return base.map(inst => (inst.id === instanceId ? { ...inst, alias } : inst));
+    });
     console.error(`Instance alias updated: ${instanceId} -> "${alias}"`);
 }
 /**
@@ -511,27 +708,73 @@ async function warnIfDifferentServer(client, error) {
 }
 function createInstancesCommand() {
     const cmd = new commander_1.Command('instances');
+    const bothRoleFlags = (0, agent_roles_1.watchRoleFlagConflict)(cmd);
     cmd
         .description('Discover and manage agent instances (roster) for a worktree')
         .argument('<worktree-id>', 'Worktree ID')
-        .argument('[action]', 'list (default), add, remove, alias, or kill')
+        .argument('[action]', 'list (default), add, remove, alias, kill, or set-role')
         .argument('[rest...]', 'Action-specific arguments (instance-id, new alias)')
-        .option('--json', 'JSON output (list/add)')
+        .option('--json', 'JSON output (list/add/set-role)')
         .option('--agent <tool>', 'CLI tool for the add action (claude, codex, gemini, vibe-local, opencode, copilot, antigravity)')
         .option('--alias <name>', 'Display alias for the add action')
         .option('--id <instance-id>', 'Explicit instance ID for the add action (format: <agent> or <agent>-<n>, e.g. claude-2)')
         .option('--kill', 'Also kill the running session when removing an instance')
+        .option('--role <role>', 'add / set-role: role ID or name for this instance')
+        .option('--no-role', 'add: explicitly no role')
+        .option('--none', 'set-role: explicitly no role')
+        .option('--inherit', 'set-role: drop the setting, and follow the defaults')
+        .option('--require-roles', 'list --json: fail instead of leaving role out when it cannot be read; failures are JSON')
         .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .addHelpText('after', `
+set-role saves what this instance's NEXT start uses, running or not. A role is fixed
+when the process starts, so a running session is not touched. The answer compares the
+two: applyPending (--json) / "Pending:" only when they differ. restartPending: yes, no,
+or unknown (nothing known about the process: not started, or the server restarted).
+To change what a whole repository or tool gets instead: commandmate roles default.
+To change the role's text: commandmate roles edit. See: commandmate roles --help
+
+add --role / --no-role creates the instance and its role together, refused (exit 31)
+if the roster changed meanwhile. Without them the instance follows the defaults.
+
+add, remove and alias without those flags build their change again on a fresh read when
+the roster moved. If it kept changing through every attempt: exit 31 (roster_changed) and
+nothing was saved to it. What came before the save stands (remove --kill stopped the session).
+
+--json, list: every row carries role when the server has roles:
+  role: { stored, effectiveNext: { kind, source, role?, injectionFingerprint }, launched,
+          requested, restartPending }
+  launched / requested are launch records, with roleId, roleName, source and
+  injectionFingerprint. launched null means not known, which is not "no role".
+--json, set-role and add --role: { success, instanceId, cliToolId, adapterEnabled, stored,
+  effectiveNext, launched, requested, restartPending, applyPending, rosterRevision }
+--json failure of those two: { success: false, error, message } on stdout, whatever failed.
+  A 5xx or no answer may still have saved: it adds saved: "unknown" and check. A 4xx saved nothing.
+--require-roles makes list --json fail rather than leave role out, so a script can tell
+"could not be read" from a server older than roles (error: role_api_unavailable).
+
+Exit codes for the role forms: 0 done; 2 usage, unknown or ambiguous role, instance not
+on the roster, or a tool roles do not apply to; 31 instance_exists or roster_changed.
+`)
         .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 });
+        let client;
+        // Issue #4116: the forms whose `--json` promises an answer for every failure.
+        const roleForm = action === 'set-role' || (action === 'add' && options.role !== undefined) || options.requireRoles === true;
         try {
+            // Inside the try, as `roles` has it: the constructor can refuse (CM_UAT_ISOLATION
+            // with no CM_PORT), and that is a failure like any other.
+            client = new api_client_1.ApiClient({ token: options.token });
             if (!(0, api_client_1.isValidWorktreeId)(worktreeId)) {
+                if (roleForm)
+                    throw (0, agent_roles_1.usageError)('Invalid worktree ID format.');
                 console.error('Error: Invalid worktree ID format.');
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
+            if (bothRoleFlags())
+                throw (0, agent_roles_1.usageError)('Give --role or --no-role, not both.');
+            assertNoRoleFlags(action ?? 'list', options);
             switch (action ?? 'list') {
                 case 'list':
                     await listInstances(client, worktreeId, options);
@@ -567,8 +810,15 @@ function createInstancesCommand() {
                     await killInstance(client, worktreeId, instanceId);
                     break;
                 }
+                case 'set-role': {
+                    const [instanceId] = rest;
+                    if (!instanceId)
+                        throw (0, agent_roles_1.usageError)('set-role requires an <instance-id> argument.');
+                    await setInstanceRole(client, worktreeId, instanceId, options);
+                    break;
+                }
                 default:
-                    console.error(`Error: unknown action '${action}'. Valid actions: list, add, remove, alias, kill.`);
+                    console.error(`Error: unknown action '${action}'. Valid actions: list, add, remove, alias, kill, set-role.`);
                     process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
         }
@@ -579,7 +829,14 @@ function createInstancesCommand() {
             // 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);
+            if (client)
+                await warnIfDifferentServer(client, error);
+            // Issue #4116: a role refusal has its own sentence, code and `--json` answer,
+            // and so has any failure of a role form.
+            if (roleForm || error instanceof agent_roles_1.RoleCliError || (0, agent_roles_1.roleFailureFromApi)(error) !== null) {
+                (0, agent_roles_1.reportRoleFailure)(error, options.json);
+                return;
+            }
             (0, command_helpers_1.handleCommandError)(error);
         }
     });

package/dist/cli/commands/message-dispatch.d.ts

@@ -9,7 +9,7 @@
 import type { ChatMessage } from '../types/api-responses';
 import { ApiClient } from '../utils/api-client';
 import type { CommandTarget } from './command-target';
-import { type RegisteredRelay } from './relays';
+import { type RegisteredRelay, type RelayEndpointArg } from './relays';
 /**
  * Code the send API returns when the session is blocked on a prompt (Issue
  * #1708). Mirrors PROMPT_WAITING_CODE in src/lib/session/prompt-waiting-guard.ts;
@@ -31,7 +31,21 @@ export interface RegisterRelayForMessageInput {
      * "was the relay opened?" unanswered — the same reason `/send` is not cut.
      */
     resolveClient?: ApiClient;
+    /** Issue #4133: already resolved by {@link resolveRelayEndpoints}, so not resolved again. */
+    endpoints?: RelayEndpoints;
+    /** Issue #4133: runs when the relay could not be opened, before the command ends. */
+    onFailure?: () => Promise<void>;
+}
+/** The two ends of a relay, as the ledger stores them. */
+export interface RelayEndpoints {
+    from: RelayEndpointArg;
+    to: RelayEndpointArg;
 }
+/**
+ * Both ends of a `--reply-to`. Only reads. Exits 2 when either cannot be named, so a
+ * caller with something to clean up afterwards calls this before making it (Issue #4133).
+ */
+export declare function resolveRelayEndpoints(client: ApiClient, input: Pick<RegisterRelayForMessageInput, 'worktreeId' | 'replyTo' | 'instance' | 'agent'>): Promise<RelayEndpoints>;
 /** Resolve both endpoints and open the relay; returns its id and whether it is bound. */
 export declare function registerRelayForMessage(client: ApiClient, input: RegisterRelayForMessageInput): Promise<RegisteredRelay>;
 export interface PostMessageOptions {
@@ -40,13 +54,20 @@ export interface PostMessageOptions {
      * send (`relayId`) and it is withdrawn only on a confirmed `not_sent`.
      */
     relay?: RegisteredRelay;
-    /** Runs first when the post fails, before the relay is cancelled. */
-    onFailure?: () => Promise<void>;
+    /**
+     * Runs first when the post fails, before the relay is cancelled and before any
+     * exit. Issue #4116: told the failure, and a bound relay's outcome (null unbound).
+     */
+    onFailure?: (error: unknown, outcome: FailedSendOutcome | null) => Promise<void>;
     /** Printed (after `Error: `) when PROMPT_WAITING carried no message body. */
     promptWaitingFallback: string;
     /** The resolved target the send addressed; the hints name it (Issue #3982). */
     target: CommandTarget;
 }
+/** What the send did, as far as a bound relay is concerned (Issue #3957). */
+type BoundSendOutcome = 'sent' | 'not_sent' | 'unknown' | 'conflict';
+/** A bound relay's outcome once the send is known to have failed. */
+export type FailedSendOutcome = Exclude<BoundSendOutcome, 'sent'>;
 /**
  * What to tell the sender about resending a failed send, from the server's
  * `sendOutcome` on the error (Issue #3992). Issue #4011: the route puts it on
@@ -67,4 +88,5 @@ export declare function describeFailedSendOutcome(error: unknown, worktreeId: st
  * @returns The send API's body (Issue #3957: `ask` reads `turnOpenAtSend`)
  */
 export declare function postMessage(client: ApiClient, worktreeId: string, sendBody: Record<string, unknown>, options: PostMessageOptions): Promise<ChatMessage>;
+export {};
 //# sourceMappingURL=message-dispatch.d.ts.map

package/dist/cli/commands/message-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-dispatch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/message-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAY,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED,yFAAyF;AACzF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,eAAe,CAAC,CAc1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,aAAa,CAAC;CACvB;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAcnH;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CA+CtB"}
+{"version":3,"file":"message-dispatch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/message-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAY,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAEpD,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,6FAA6F;IAC7F,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,EAAE,gBAAgB,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,IAAI,CAAC,4BAA4B,EAAE,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC,GACzF,OAAO,CAAC,cAAc,CAAC,CAIzB;AAED,yFAAyF;AACzF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,eAAe,CAAC,CAO1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,6EAA6E;AAC7E,KAAK,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAErE,qEAAqE;AACrE,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;AAqClE;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAcnH;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAyDtB"}

package/dist/cli/commands/message-dispatch.js

@@ -9,12 +9,14 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROMPT_WAITING_CODE = void 0;
+exports.resolveRelayEndpoints = resolveRelayEndpoints;
 exports.registerRelayForMessage = registerRelayForMessage;
 exports.describeFailedSendOutcome = describeFailedSendOutcome;
 exports.postMessage = postMessage;
 const types_1 = require("../types");
 const api_client_1 = require("../utils/api-client");
 const follow_up_command_1 = require("../utils/follow-up-command");
+const role_failure_1 = require("../utils/role-failure");
 const relays_1 = require("./relays");
 /**
  * Code the send API returns when the session is blocked on a prompt (Issue
@@ -23,15 +25,22 @@ const relays_1 = require("./relays");
  * tmux/detection graph in for one string.
  */
 exports.PROMPT_WAITING_CODE = 'PROMPT_WAITING';
+/**
+ * Both ends of a `--reply-to`. Only reads. Exits 2 when either cannot be named, so a
+ * caller with something to clean up afterwards calls this before making it (Issue #4133).
+ */
+async function resolveRelayEndpoints(client, input) {
+    const from = await (0, relays_1.resolveRelayEndpoint)(client, input.replyTo);
+    const to = await (0, relays_1.resolveEndpointForWorktree)(client, input.worktreeId, input.instance, input.agent);
+    return { from, to };
+}
 /** Resolve both endpoints and open the relay; returns its id and whether it is bound. */
 async function registerRelayForMessage(client, input) {
-    const resolveClient = input.resolveClient ?? client;
-    const replyEndpoint = await (0, relays_1.resolveRelayEndpoint)(resolveClient, input.replyTo);
-    const workerEndpoint = await (0, relays_1.resolveEndpointForWorktree)(resolveClient, input.worktreeId, input.instance, input.agent);
+    const endpoints = input.endpoints ?? await resolveRelayEndpoints(input.resolveClient ?? client, input);
     return (0, relays_1.registerRelay)(client, {
-        from: replyEndpoint,
-        to: workerEndpoint,
+        ...endpoints,
         allowRelayChain: input.allowRelayChain,
+        onFailure: input.onFailure,
     });
 }
 function isSendOutcome(value) {
@@ -118,7 +127,7 @@ async function postMessage(client, worktreeId, sendBody, options) {
             return { worktreeId, role: 'user', content: '', sendOutcome: 'sent' };
         }
         if (options.onFailure) {
-            await options.onFailure();
+            await options.onFailure(error, outcome);
         }
         // A relay whose message never arrived can never be answered; leaving
         // it open would have the requester waiting 24h for a turn that was
@@ -131,6 +140,11 @@ async function postMessage(client, worktreeId, sendBody, options) {
             (0, relays_1.printRelayUnconfirmedNotice)(relayId, worktreeId, options.target);
         }
         const promptWaiting = error instanceof api_client_1.ApiError && error.apiCode === exports.PROMPT_WAITING_CODE;
+        // Issue #4116: a refusal with no role code of its own (a 400, a 503, a 500), after
+        // the role was saved. One with a role code says so in its own sentence.
+        if ((0, role_failure_1.roleSettingSavedBy)(error) && (0, role_failure_1.roleFailureFromApi)(error) === null) {
+            console.error(`Note: ${role_failure_1.ROLE_STAYED_SAVED}`);
+        }
         // Issue #3992: whether it may be sent again, as the server said — not on
         // PROMPT_WAITING, whose own line says to answer the prompt first, and not
         // when the relay notice above already said it.
@@ -150,6 +164,12 @@ async function postMessage(client, worktreeId, sendBody, options) {
             console.error(`Error: ${error.payload?.error ?? options.promptWaitingFallback}`);
             process.exit(types_1.ExitCode.CONFIG_ERROR);
         }
+        // Issue #4116: a refusal because of the role, whether or not this send named
+        // one (a default can refuse a start), with the server's sentence and its own
+        // exit code rather than "Unexpected HTTP status: 409".
+        const roleFailure = (0, role_failure_1.roleFailureFromApi)(error);
+        if (roleFailure)
+            throw roleFailure;
         throw error;
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAgB5E;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAW9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAU/G;AA0ED,kDAAkD;AAClD,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAkBxG;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CA8E7C"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAgB5E;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAW9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAU/G;AA0ED,kDAAkD;AAClD,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAkBxG;AAED,wBAAgB,mBAAmB,IAAI,OAAO,CA+E7C"}

package/dist/cli/commands/prompt.js

@@ -184,7 +184,8 @@ lastSend says how the last send to the instance ended: not-sent (no key of the
 message was typed, e.g. prompt not ready), sent, or indeterminate (part of it
 may have been typed). Nothing is resent automatically: resend a not-sent
 message yourself, and do not resend an indeterminate one before checking
-\`capture --pane\`.
+\`capture --pane\`. With overlapping sends it follows the input lock's grant
+order, so it may be another request's outcome, not yours (Issue #4065).
 
 To answer the screen only if it is still this one (Issue #3756):
   commandmate respond <worktree-id> --instance <id> --expect-screen <kind> \\