commandmate 0.49.3 → 0.50.0

package/dist/cli/utils/agent-roles.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * What `roles`, `instances` and `send` share about roles (Issue #4116): reading a
+ * role or repository the way a person names it, reading a body, and turning the
+ * role API's refusals into an exit code.
+ *
+ * ## Decisions
+ *
+ * - **A role is named by ID or name, and nothing is reserved.** "No role" and
+ *   "follow the defaults" are flags, so a role called `none` is just a role.
+ *   An exact match wins; failing that, a match ignoring case and Unicode form.
+ *   Two answers at the same step is an error listing them, never a pick.
+ * - **`--repo` is, in this order: an ID, a path, a name.** A value containing a `/`
+ *   or starting with `.` is a path; it may be a registered root, or a worktree of
+ *   one (which answers for its root). A bare word is never read as a path, so what
+ *   the current directory holds cannot change which repository a word means.
+ * - **Unknown, unregistered and ambiguous have their own codes**: `unknown_repository`,
+ *   `repository_not_registered` (a real directory with no row) and `ambiguous_repository`.
+ *   A root with no row for a tool is not an error: it reads `stored: inherit`.
+ *
+ * Type imports and {@link isAgentRoleCliTool} only from the shared types: the CLI
+ * does not load the server's role layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRoleBodyOption = exports.usageError = exports.roleFailureFromApi = exports.RoleCliError = void 0;
+exports.roleWrite = roleWrite;
+exports.reportRoleFailure = reportRoleFailure;
+exports.pickRole = pickRole;
+exports.resolveRole = resolveRole;
+exports.assertRoleTool = assertRoleTool;
+exports.watchRoleFlagConflict = watchRoleFlagConflict;
+exports.roleAssignmentFromFlag = roleAssignmentFromFlag;
+exports.listRepositories = listRepositories;
+exports.resolveRepository = resolveRepository;
+const types_1 = require("../types");
+const api_client_1 = require("./api-client");
+const command_helpers_1 = require("./command-helpers");
+const role_failure_1 = require("./role-failure");
+Object.defineProperty(exports, "RoleCliError", { enumerable: true, get: function () { return role_failure_1.RoleCliError; } });
+Object.defineProperty(exports, "roleFailureFromApi", { enumerable: true, get: function () { return role_failure_1.roleFailureFromApi; } });
+Object.defineProperty(exports, "usageError", { enumerable: true, get: function () { return role_failure_1.usageError; } });
+const role_input_1 = require("./role-input");
+const agent_roles_1 = require("../../types/agent-roles");
+var role_input_2 = require("./role-input");
+Object.defineProperty(exports, "readRoleBodyOption", { enumerable: true, get: function () { return role_input_2.readRoleBodyOption; } });
+/** The `--json` code of a failure no role route classified. Its exit code stays its own. */
+function unclassifiedFailureCode(error) {
+    if (!(error instanceof api_client_1.ApiError))
+        return 'unexpected_error';
+    const { payload } = error;
+    if (payload?.success === false && typeof payload.error === 'string')
+        return payload.error;
+    if (typeof payload?.code === 'string')
+        return payload.code;
+    return error.statusCode === undefined ? 'no_response' : 'request_failed';
+}
+function printJsonFailure(code, message, details = {}) {
+    console.log(JSON.stringify({ success: false, error: code, message, ...details }, null, 2));
+}
+/**
+ * Run a request that changes a role setting (Issue #4116). The routes write, then build
+ * their answer, so a 500 or a lost answer can follow a write that stayed. Only a 4xx is
+ * known to have changed nothing; anything else says that is not known, how to look, and
+ * with `--json` the same as `saved: "unknown"` and `check`. The code and exit code stay
+ * what the failure itself has.
+ *
+ * @param check - The command that shows what the setting is now
+ * @throws A 4xx as its role failure, or as it came when it is none
+ */
+async function roleWrite(check, write) {
+    try {
+        return await write();
+    }
+    catch (error) {
+        (0, api_client_1.rethrowIfDeadlineExceeded)(error);
+        if (error instanceof api_client_1.ApiError && error.statusCode !== undefined && error.statusCode < 500) {
+            throw (0, role_failure_1.roleFailureFromApi)(error) ?? error;
+        }
+        const known = error instanceof api_client_1.ApiError ? error : undefined;
+        throw new role_failure_1.RoleCliError(unclassifiedFailureCode(error), `${error instanceof Error ? error.message : String(error)} Whether the change was saved is not known. Check it with: ${check}`, known?.exitCode ?? types_1.ExitCode.UNEXPECTED_ERROR, { saved: 'unknown', check }, known?.statusCode, known?.payload);
+    }
+}
+/**
+ * End a role command on `error`: the sentence on stderr, and with `--json` the same
+ * thing as an object on stdout, whatever the failure was, so a caller parsing stdout
+ * gets an answer either way. A failure no route classified (a 500, no connection)
+ * keeps the sentence and exit code `handleCommandError` gives it.
+ */
+function reportRoleFailure(error, json) {
+    const failure = error instanceof role_failure_1.RoleCliError ? error : (0, role_failure_1.roleFailureFromApi)(error);
+    if (failure) {
+        if (json)
+            printJsonFailure(failure.code, failure.message, failure.details);
+        console.error(`Error: ${failure.message}`);
+        process.exit(failure.exitCode);
+        return;
+    }
+    if (error instanceof api_client_1.ApiError && error.statusCode === 404 && !error.payload) {
+        const message = 'the server has no such route. It may be older than this CLI: commandmate stop && commandmate start';
+        if (json)
+            printJsonFailure('role_api_unavailable', message);
+        console.error(`Error: ${message}`);
+        process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+        return;
+    }
+    if (json)
+        printJsonFailure(unclassifiedFailureCode(error), error instanceof Error ? error.message : String(error));
+    (0, command_helpers_1.handleCommandError)(error);
+}
+/** The role's ID and name, the way a candidate is listed. */
+function describeRole(role) {
+    return `${role.id}  ${role.name}`;
+}
+function foldName(value) {
+    return value.trim().normalize('NFC').toLowerCase();
+}
+function ambiguousRole(selector, matches) {
+    return new role_failure_1.RoleCliError('ambiguous_role', `'${selector}' could mean ${matches.length} roles. Name one by its ID (an ID that is also another role's name: rename that role):\n`
+        + matches.map((role) => `  - ${describeRole(role)}`).join('\n'), types_1.ExitCode.CONFIG_ERROR, { candidates: matches.map(({ id, name }) => ({ id, name })) });
+}
+/**
+ * The role `selector` names. The database keeps names unique ignoring ASCII case
+ * only, so Unicode forms and non-ASCII case can still answer twice, and a name can
+ * equal another role's ID.
+ */
+function pickRole(roles, selector) {
+    const exact = roles.filter((role) => role.id === selector || role.name === selector);
+    if (exact.length === 1)
+        return exact[0];
+    if (exact.length > 1)
+        throw ambiguousRole(selector, exact);
+    const folded = roles.filter((role) => foldName(role.name) === foldName(selector));
+    if (folded.length === 1)
+        return folded[0];
+    if (folded.length > 1)
+        throw ambiguousRole(selector, folded);
+    throw new role_failure_1.RoleCliError('unknown_role', `No role is called '${selector}'. List them with: commandmate roles list`, types_1.ExitCode.CONFIG_ERROR);
+}
+async function resolveRole(client, selector) {
+    const { roles } = await client.get('/api/roles');
+    return pickRole(roles, selector);
+}
+/** The tool a role command names, or the failure for one outside the role feature. */
+function assertRoleTool(tool) {
+    if ((0, agent_roles_1.isAgentRoleCliTool)(tool))
+        return tool;
+    throw new role_failure_1.RoleCliError('tool_not_supported', `Roles do not apply to '${tool}'. They apply to: ${agent_roles_1.AGENT_ROLE_CLI_TOOLS.join(', ')}`, types_1.ExitCode.CONFIG_ERROR);
+}
+// ---------------------------------------------------------------------------
+// Flags
+// ---------------------------------------------------------------------------
+/**
+ * `--role` and `--no-role` share one commander value, where the last one given wins.
+ * Asking for both is a contradiction, so the two are watched as they are parsed.
+ *
+ * @returns Whether both were given. Read after parsing.
+ */
+function watchRoleFlagConflict(command) {
+    let role = false;
+    let noRole = false;
+    command.on('option:role', () => {
+        role = true;
+    });
+    command.on('option:no-role', () => {
+        noRole = true;
+    });
+    return () => role && noRole;
+}
+/** `--role <role>` / `--no-role` as a setting, or undefined when neither was given. */
+async function roleAssignmentFromFlag(client, flag) {
+    if (flag === undefined)
+        return undefined;
+    if (flag === false)
+        return { state: 'none' };
+    const role = await resolveRole(client, flag);
+    return { state: 'role', roleId: role.id };
+}
+function isPathShaped(selector) {
+    return selector.includes('/') || selector.startsWith('.');
+}
+function describeRepository(repository) {
+    return `${repository.id}  ${repository.name}  ${repository.path}`;
+}
+function ambiguousRepository(selector, matches) {
+    return new role_failure_1.RoleCliError('ambiguous_repository', `'${selector}' could mean ${matches.length} repositories. Name one by its ID:\n`
+        + matches.map((repository) => `  - ${describeRepository(repository)}`).join('\n'), types_1.ExitCode.CONFIG_ERROR, { candidates: matches.map(({ id, name, path: repositoryPath }) => ({ id, name, path: repositoryPath })) });
+}
+async function listRepositories(client) {
+    const { repositories } = await client.get('/api/repositories');
+    return repositories;
+}
+/**
+ * The root a path-shaped `--repo` names: a registered root, or the root of the
+ * registered worktree at that path, which is what "this repository" is from inside one.
+ */
+async function repositoryAtPath(client, repositories, selector) {
+    const wanted = (0, role_input_1.canonicalPath)(selector);
+    const roots = repositories.filter((repository) => (0, role_input_1.canonicalPath)(repository.path) === wanted);
+    if (roots.length > 0)
+        return roots;
+    const { worktrees } = await client.get('/api/worktrees');
+    const worktree = (worktrees ?? []).find((row) => typeof row.path === 'string' && (0, role_input_1.canonicalPath)(row.path) === wanted);
+    if (typeof worktree?.repositoryPath !== 'string')
+        return [];
+    const root = (0, role_input_1.canonicalPath)(worktree.repositoryPath);
+    return repositories.filter((repository) => (0, role_input_1.canonicalPath)(repository.path) === root);
+}
+/** The registered repository `--repo` names. See the module's decisions for the order. */
+async function resolveRepository(client, selector) {
+    const repositories = await listRepositories(client);
+    const byId = repositories.filter((repository) => repository.id === selector);
+    if (byId.length === 1)
+        return byId[0];
+    if (isPathShaped(selector)) {
+        const matches = await repositoryAtPath(client, repositories, selector);
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1)
+            throw ambiguousRepository(selector, matches);
+        if ((0, role_input_1.isDirectory)(selector)) {
+            throw new role_failure_1.RoleCliError('repository_not_registered', `${selector} is a directory, but neither a registered repository nor a worktree of one. `
+                + 'See what is registered with: commandmate roles defaults', types_1.ExitCode.CONFIG_ERROR);
+        }
+    }
+    else {
+        const exact = repositories.filter((repository) => repository.name === selector);
+        if (exact.length === 1)
+            return exact[0];
+        if (exact.length > 1)
+            throw ambiguousRepository(selector, exact);
+        const folded = repositories.filter((repository) => foldName(repository.name) === foldName(selector));
+        if (folded.length === 1)
+            return folded[0];
+        if (folded.length > 1)
+            throw ambiguousRepository(selector, folded);
+    }
+    throw new role_failure_1.RoleCliError('unknown_repository', `No repository matches '${selector}'. See what is registered with: commandmate roles defaults`, types_1.ExitCode.CONFIG_ERROR);
+}

package/dist/cli/utils/api-client-errors.d.ts

@@ -41,6 +41,11 @@ export declare const FOREIGN_SESSION_ERROR_CODE = "session_owned_by_other_server
  * server's, this command therefore did nothing to it, and where to go instead.
  */
 export declare function foreignSessionMessage(payload?: ApiErrorPayload): string;
+/**
+ * The `code` of the 409 for a roster that moved since it was read (Issue #4132).
+ * Spelled out for the reason {@link FOREIGN_SESSION_ERROR_CODE} is: it comes from a route.
+ */
+export declare const ROSTER_CHANGED_ERROR_CODE = "ROSTER_CHANGED";
 /**
  * Classify API errors into user-friendly messages and exit codes.
  * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
@@ -50,7 +55,7 @@ export declare function foreignSessionMessage(payload?: ApiErrorPayload): string
  * @param payload - Parsed error body, when the response carried one (Issue #1637).
  *   Used for 5xx, and for the foreign-session 409 (Issue #3334): the other 4xx
  *   messages below are already specific, and are pinned by tests as the CLI's
- *   own wording.
+ *   own wording. Issue #4149: the roster 409 is told apart by its code too.
  * @param context - Which server answered, when the caller knows (Issue #2404).
  *   Read by the 404 branch only; the other messages do not send anyone looking
  *   in the wrong place.
@@ -88,6 +93,23 @@ export interface ApiErrorPayload {
      * src/lib/relay/relay-bind.ts RelaySendOutcome (and ChatMessage.sendOutcome).
      */
     sendOutcome?: 'sent' | 'not_sent' | 'unknown';
+    /**
+     * Issue #4116: the role routes answer `{ success: false, error: <code>, message }`,
+     * so there `error` is the stable code and `message` the sentence.
+     */
+    success?: boolean;
+    message?: string;
+    /** `role_in_use`: what points at the role. */
+    references?: unknown;
+    /** `version_conflict`: the version the role is at now. */
+    currentBodyVersion?: number;
+    /** Issue #4115: a send refused because of its role says whether the setting stayed saved. */
+    roleSettings?: {
+        saved?: boolean;
+        stored?: unknown;
+    };
+    /** Issue #4115: why a launch was refused because of its role. */
+    roleRefusal?: string;
 }
 /**
  * API Error with exit code for CLI process.exit()

package/dist/cli/utils/api-client-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client-errors.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0BD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAEhF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,kCAAkC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAYvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAyGhB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;CAC/C;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IACnC,gEAAgE;aAChD,OAAO,CAAC,EAAE,eAAe;IACzC;;;;OAIG;aACa,cAAc,CAAC,EAAE,OAAO;gBAVxC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,gEAAgE;IAChD,OAAO,CAAC,EAAE,eAAe,YAAA;IACzC;;;;OAIG;IACa,cAAc,CAAC,EAAE,OAAO,YAAA;IAM1C,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF"}
+{"version":3,"file":"api-client-errors.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0BD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAEhF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,kCAAkC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAYvE;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAgHhB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC9C;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6FAA6F;IAC7F,YAAY,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrD,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IACnC,gEAAgE;aAChD,OAAO,CAAC,EAAE,eAAe;IACzC;;;;OAIG;aACa,cAAc,CAAC,EAAE,OAAO;gBAVxC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,gEAAgE;IAChD,OAAO,CAAC,EAAE,eAAe,YAAA;IACzC;;;;OAIG;IACa,cAAc,CAAC,EAAE,OAAO,YAAA;IAM1C,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF"}

package/dist/cli/utils/api-client-errors.js

@@ -4,7 +4,7 @@
  * api-client.ts re-exports every exported name here; import from there.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiError = exports.FOREIGN_SESSION_ERROR_CODE = void 0;
+exports.ApiError = exports.ROSTER_CHANGED_ERROR_CODE = exports.FOREIGN_SESSION_ERROR_CODE = void 0;
 exports.withServerUrl = withServerUrl;
 exports.foreignSessionMessage = foreignSessionMessage;
 exports.handleApiError = handleApiError;
@@ -60,6 +60,11 @@ function foreignSessionMessage(payload) {
         'so nothing was sent to it, read from it or stopped. ' +
         'Use the CommandMate server that started it, or stop that session there first.');
 }
+/**
+ * The `code` of the 409 for a roster that moved since it was read (Issue #4132).
+ * Spelled out for the reason {@link FOREIGN_SESSION_ERROR_CODE} is: it comes from a route.
+ */
+exports.ROSTER_CHANGED_ERROR_CODE = 'ROSTER_CHANGED';
 /**
  * Classify API errors into user-friendly messages and exit codes.
  * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
@@ -69,7 +74,7 @@ function foreignSessionMessage(payload) {
  * @param payload - Parsed error body, when the response carried one (Issue #1637).
  *   Used for 5xx, and for the foreign-session 409 (Issue #3334): the other 4xx
  *   messages below are already specific, and are pinned by tests as the CLI's
- *   own wording.
+ *   own wording. Issue #4149: the roster 409 is told apart by its code too.
  * @param context - Which server answered, when the caller knows (Issue #2404).
  *   Read by the 404 branch only; the other messages do not send anyone looking
  *   in the wrong place.
@@ -122,6 +127,13 @@ function handleApiError(error, status, payload, context) {
                         exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
                     };
                 }
+                // Issue #4149: exit 31, what the `instances` help gives for `roster_changed`.
+                if (payload?.code === exports.ROSTER_CHANGED_ERROR_CODE) {
+                    return {
+                        message: 'The roster changed since it was read, so nothing was saved to it. Run the command again.',
+                        exitCode: types_1.RoleExitCode.CONFLICT,
+                    };
+                }
                 return {
                     message: `Unexpected HTTP status: ${status}`,
                     exitCode: types_1.ExitCode.UNEXPECTED_ERROR,

package/dist/cli/utils/api-client.d.ts

@@ -129,6 +129,14 @@ export declare class ApiClient {
      * [DR1-05] Generic type parameter specified at call site
      */
     patch<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * HTTP PUT request (Issue #4116: the role settings routes).
+     *
+     * @param headers - Added to this request: a condition, not part of the body (Issue #4132)
+     */
+    put<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    /** HTTP DELETE request (Issue #4116: `roles rm`). */
+    delete<T>(path: string): Promise<T>;
 }
 /**
  * Assert that a parsed API response contains the given required top-level fields

package/dist/cli/utils/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,EACL,QAAQ,EACR,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAK3C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAaD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjF;AAeD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,6EAA6E;IAC7E,OAAO,CAAC,UAAU,CAAC,CAAS;gBAEhB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IA2B1D;;;;;;;;;;OAUG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAYvD,8DAA8D;IAC9D,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAED;;;OAGG;IACH,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAwB1F;;;;;;;;OAQG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAiCvE;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAGzD;AA4LD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GACd,CAAC,CAiBH;AAOD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASvF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"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"}

package/dist/cli/utils/api-client.js

@@ -282,9 +282,21 @@ class ApiClient {
     async patch(path, body) {
         return sendWithBody(this.baseUrl, 'PATCH', this.getHeaders(), path, body, this.startDeadline());
     }
+    /**
+     * HTTP PUT request (Issue #4116: the role settings routes).
+     *
+     * @param headers - Added to this request: a condition, not part of the body (Issue #4132)
+     */
+    async put(path, body, headers) {
+        return sendWithBody(this.baseUrl, 'PUT', { ...this.getHeaders(), ...headers }, path, body, this.startDeadline());
+    }
+    /** HTTP DELETE request (Issue #4116: `roles rm`). */
+    async delete(path) {
+        return sendWithBody(this.baseUrl, 'DELETE', this.getHeaders(), path, undefined, this.startDeadline());
+    }
 }
 exports.ApiClient = ApiClient;
-/** POST / PATCH share everything but the method; an empty body (204) is `undefined`. */
+/** POST / PATCH / PUT / DELETE share everything but the method; an empty body (204) is `undefined`. */
 async function sendWithBody(baseUrl, method, headers, path, body, deadline) {
     try {
         const response = await bounded(deadline, fetch(`${baseUrl}${path}`, {

package/dist/cli/utils/role-failure.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The role API's refusals as an exit code (Issue #4116). On its own, free of the file
+ * system and of catches, because `message-dispatch.ts` reads it and that is on the
+ * paths `wait` / `ask` / `verify` hold to their deadline.
+ */
+import { ApiError, type ApiErrorPayload } from './api-client';
+/**
+ * A role command's failure, with the code `--json` reports. An {@link ApiError}, so
+ * `handleCommandError` prints it and exits with its code in a command that has no
+ * `--json` of its own.
+ */
+export declare class RoleCliError extends ApiError {
+    readonly code: string;
+    /** Extra keys of the `--json` failure, such as `candidates` or `references`. */
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, exitCode: number, 
+    /** Extra keys of the `--json` failure, such as `candidates` or `references`. */
+    details?: Record<string, unknown>, statusCode?: number, payload?: ApiErrorPayload);
+}
+/** Said on every refusal after a save, so nobody takes the old setting to be still there. */
+export declare const ROLE_STAYED_SAVED = "The role setting stayed saved, so after a restart the message can be sent again without --role.";
+/** Whether a send's refusal says its role was saved before it. */
+export declare function roleSettingSavedBy(error: unknown): boolean;
+/**
+ * The role failure an API error is, or null when it is not one. The management
+ * routes put their code in `error` and their sentence in `message`; the send and
+ * task routes put the code in `code` and the sentence in `error`.
+ */
+export declare function roleFailureFromApi(error: unknown): RoleCliError | null;
+export declare function usageError(message: string): RoleCliError;
+//# sourceMappingURL=role-failure.d.ts.map

package/dist/cli/utils/role-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-failure.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/role-failure.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,QAAQ;aAEtB,IAAI,EAAE,MAAM;IAG5B,gFAAgF;aAChE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAJhC,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM;IAChB,gFAAgF;IAChE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACrD,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,eAAe;CAK5B;AAED,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,oGACqE,CAAC;AAEpG,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAkBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CAqBtE;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAExD"}

package/dist/cli/utils/role-failure.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * The role API's refusals as an exit code (Issue #4116). On its own, free of the file
+ * system and of catches, because `message-dispatch.ts` reads it and that is on the
+ * paths `wait` / `ask` / `verify` hold to their deadline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_STAYED_SAVED = exports.RoleCliError = void 0;
+exports.roleSettingSavedBy = roleSettingSavedBy;
+exports.roleFailureFromApi = roleFailureFromApi;
+exports.usageError = usageError;
+const types_1 = require("../types");
+const api_client_1 = require("./api-client");
+/**
+ * A role command's failure, with the code `--json` reports. An {@link ApiError}, so
+ * `handleCommandError` prints it and exits with its code in a command that has no
+ * `--json` of its own.
+ */
+class RoleCliError extends api_client_1.ApiError {
+    code;
+    details;
+    constructor(code, message, exitCode, 
+    /** Extra keys of the `--json` failure, such as `candidates` or `references`. */
+    details = {}, statusCode, payload) {
+        super(message, exitCode, statusCode, payload);
+        this.code = code;
+        this.details = details;
+        this.name = 'RoleCliError';
+    }
+}
+exports.RoleCliError = RoleCliError;
+/** Said on every refusal after a save, so nobody takes the old setting to be still there. */
+exports.ROLE_STAYED_SAVED = 'The role setting stayed saved, so after a restart the message can be sent again without --role.';
+/** Whether a send's refusal says its role was saved before it. */
+function roleSettingSavedBy(error) {
+    return error instanceof api_client_1.ApiError && error.payload?.roleSettings?.saved === true;
+}
+const ROLE_ROUTE_EXITS = {
+    invalid_request: types_1.ExitCode.CONFIG_ERROR,
+    not_found: types_1.ExitCode.CONFIG_ERROR,
+    tool_not_supported: types_1.ExitCode.CONFIG_ERROR,
+    name_conflict: types_1.RoleExitCode.CONFLICT,
+    version_conflict: types_1.RoleExitCode.CONFLICT,
+    name_changed: types_1.RoleExitCode.CONFLICT,
+    role_in_use: types_1.RoleExitCode.CONFLICT,
+    instance_exists: types_1.RoleExitCode.CONFLICT,
+    roster_changed: types_1.RoleExitCode.CONFLICT,
+    // Mirror ROLE_CONDITION_UNMET_CODE and its neighbours in `lib/agent-roles/launch-errors`.
+    ROLE_CONDITION_UNMET: types_1.RoleExitCode.NOT_SENT,
+    ROLE_LAUNCH_REFUSED: types_1.RoleExitCode.NOT_SENT,
+    SESSION_LAUNCH_ROLE_MISMATCH: types_1.RoleExitCode.NOT_SENT,
+};
+/**
+ * The role failure an API error is, or null when it is not one. The management
+ * routes put their code in `error` and their sentence in `message`; the send and
+ * task routes put the code in `code` and the sentence in `error`.
+ */
+function roleFailureFromApi(error) {
+    if (!(error instanceof api_client_1.ApiError) || !error.payload)
+        return null;
+    const { payload } = error;
+    const managementShape = payload.success === false && typeof payload.message === 'string';
+    const code = managementShape ? payload.error : payload.code;
+    const sentence = managementShape ? payload.message : payload.error;
+    if (typeof code !== 'string' || typeof sentence !== 'string')
+        return null;
+    // A `not_found` from `/send` is the role's only when it says what became of the setting.
+    if (!managementShape && !payload.roleSettings && !code.startsWith('ROLE_') && !code.startsWith('SESSION_LAUNCH_ROLE')) {
+        return null;
+    }
+    const exitCode = ROLE_ROUTE_EXITS[code];
+    if (exitCode === undefined)
+        return null;
+    const details = {};
+    if (payload.references !== undefined)
+        details.references = payload.references;
+    if (payload.currentBodyVersion !== undefined)
+        details.currentBodyVersion = payload.currentBodyVersion;
+    if (payload.roleRefusal !== undefined)
+        details.roleRefusal = payload.roleRefusal;
+    if (payload.roleSettings !== undefined)
+        details.roleSettings = payload.roleSettings;
+    if (payload.sendOutcome !== undefined)
+        details.sendOutcome = payload.sendOutcome;
+    const saved = payload.roleSettings?.saved === true ? ` ${exports.ROLE_STAYED_SAVED}` : '';
+    return new RoleCliError(code, `${sentence}${saved}`, exitCode, details, error.statusCode, payload);
+}
+function usageError(message) {
+    return new RoleCliError('invalid_request', message, types_1.ExitCode.CONFIG_ERROR);
+}

package/dist/cli/utils/role-input.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a role command reads from this machine rather than the server (Issue #4116):
+ * a role's body, and how a path looks here. It makes no request, so nothing here can
+ * sit on a `--timeout`.
+ */
+export declare function canonicalPath(value: string): string;
+export declare function isDirectory(value: string): boolean;
+/**
+ * The body named by `--file` / `--stdin`, or undefined when neither was given.
+ * A terminal on stdin is refused rather than waited on: this is never interactive.
+ */
+export declare function readRoleBodyOption(options: {
+    file?: string;
+    stdin?: boolean;
+}): Promise<string | undefined>;
+//# sourceMappingURL=role-input.d.ts.map

package/dist/cli/utils/role-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-input.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/role-input.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMlD;AAuBD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgBjH"}

package/dist/cli/utils/role-input.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * What a role command reads from this machine rather than the server (Issue #4116):
+ * a role's body, and how a path looks here. It makes no request, so nothing here can
+ * sit on a `--timeout`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalPath = canonicalPath;
+exports.isDirectory = isDirectory;
+exports.readRoleBodyOption = readRoleBodyOption;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const agent_roles_1 = require("../../types/agent-roles");
+const role_failure_1 = require("./role-failure");
+function canonicalPath(value) {
+    const resolved = node_path_1.default.resolve(value);
+    try {
+        return node_fs_1.default.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function isDirectory(value) {
+    try {
+        return node_fs_1.default.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Keeps every byte, a BOM included: the body reaches the model as written. */
+function decodeRoleBody(bytes, source) {
+    if (bytes.byteLength > agent_roles_1.MAX_ROLE_BODY_BYTES) {
+        throw (0, role_failure_1.usageError)(`The body from ${source} is ${bytes.byteLength} bytes; a role holds at most ${agent_roles_1.MAX_ROLE_BODY_BYTES}.`);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw (0, role_failure_1.usageError)(`The body from ${source} is not valid UTF-8.`);
+    }
+}
+async function readAll(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        // Kept as bytes until the end: a character can be split across two chunks.
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * The body named by `--file` / `--stdin`, or undefined when neither was given.
+ * A terminal on stdin is refused rather than waited on: this is never interactive.
+ */
+async function readRoleBodyOption(options) {
+    if (options.file !== undefined && options.stdin)
+        throw (0, role_failure_1.usageError)('Give the body with --file or --stdin, not both.');
+    if (options.file !== undefined) {
+        let bytes;
+        try {
+            bytes = node_fs_1.default.readFileSync(options.file);
+        }
+        catch (error) {
+            throw (0, role_failure_1.usageError)(`Could not read ${options.file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return decodeRoleBody(bytes, options.file);
+    }
+    if (!options.stdin)
+        return undefined;
+    if (process.stdin.isTTY) {
+        throw (0, role_failure_1.usageError)('--stdin needs the body piped in; a terminal is not read. Use --file, or pipe it.');
+    }
+    return decodeRoleBody(await readAll(process.stdin), 'stdin');
+}

package/dist/cli/utils/security-logger.d.ts

@@ -16,6 +16,23 @@ export interface SecurityEvent {
     /** Additional details */
     details?: string;
 }
+/**
+ * Get security log file path
+ *
+ * Issue #4210: `CM_LOG_DIR` is judged the way `getLogDir()`
+ * (`config/log-config.ts`) judges it for every other log writer. A value inside
+ * `/proc`, `/sys` or `/dev` — literally, through a symlink, or as the absolute
+ * form of a relative value — is refused and the default file is used. A
+ * relative value is otherwise kept as given and so resolved against this
+ * process's cwd, which is also what `getLogDir()` does: the file is only ever
+ * opened by the process that resolved it, so nothing else has to agree on it.
+ *
+ * The default stays `~/.commandmate-security.log` rather than `getLogDir()`'s
+ * `<cwd>/data/logs`: a CLI run from an arbitrary directory has no `data/logs`.
+ *
+ * @returns The file security events are appended to
+ */
+export declare function getSecurityLogPath(): string;
 /**
  * Log a security event
  * Silently fails if file operations fail (non-critical)

package/dist/cli/utils/security-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security-logger.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/security-logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAU3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAY/E"}
+{"version":3,"file":"security-logger.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/security-logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC1C,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAqBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAU3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAY/E"}