commandmate 0.49.3 → 0.50.0

package/dist/server/src/lib/verification/verify-config.js

@@ -8,8 +8,9 @@
  * Server-only: reads from disk, so import this from API routes / CLI only.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VerifyConfigError = exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
+exports.VerifyConfigError = exports.MAX_MUTEX_WAIT_SEC = exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
 exports.defaultPlannedGateIds = defaultPlannedGateIds;
+exports.mutexWaitBudgetSec = mutexWaitBudgetSec;
 exports.validateGateEntries = validateGateEntries;
 exports.loadVerifyConfig = loadVerifyConfig;
 const fs_1 = require("fs");
@@ -115,8 +116,18 @@ exports.MAX_RETRY_ON_FAIL = 1;
  * this long is already a repository papering over a machine it should fix.
  */
 exports.MAX_ENV_CLEAN_IGNORE_HOME_ENTRIES = 32;
+/**
+ * Longest `mutexWaitSec` a gate may declare (Issue #4162): above `timeoutSec`'s
+ * ceiling on purpose, because a queue of several slow gates is longer than any
+ * one of them. A day is past any queue worth waiting behind.
+ */
+exports.MAX_MUTEX_WAIT_SEC = 86400;
+/** The lock-wait budget of a gate, in seconds: `mutexWaitSec`, or `timeoutSec` when absent (Issue #4162). */
+function mutexWaitBudgetSec(gate) {
+    return gate.mutexWaitSec ?? gate.timeoutSec;
+}
 const TOP_LEVEL_KEYS = ['version', 'gates', 'options'];
-const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'retryOnFail', 'flakyIsPass'];
+const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'mutexWaitSec', 'retryOnFail', 'flakyIsPass'];
 const OPTION_KEYS = [
     'baseRef',
     'skipInPrimaryCheckout',
@@ -261,6 +272,23 @@ function validateGateEntry(entry, at, seenIds, gates, issues) {
             mutex = entry.mutex;
         }
     }
+    let mutexWaitSec;
+    if (entry.mutexWaitSec !== undefined) {
+        const parsed = asInteger(entry.mutexWaitSec);
+        if (parsed === null) {
+            issues.push(`${at}.mutexWaitSec: must be an integer (got ${describe(entry.mutexWaitSec)})`);
+        }
+        else if (parsed < MIN_TIMEOUT_SEC || parsed > exports.MAX_MUTEX_WAIT_SEC) {
+            issues.push(`${at}.mutexWaitSec: must be ${MIN_TIMEOUT_SEC}..${exports.MAX_MUTEX_WAIT_SEC} (got ${parsed})`);
+        }
+        else if (entry.mutex === undefined) {
+            // A knob that can never fire is a config bug, as with flakyIsPass below.
+            issues.push(`${at}.mutexWaitSec: requires mutex (without a lock there is no wait)`);
+        }
+        else {
+            mutexWaitSec = parsed;
+        }
+    }
     let retryOnFail;
     if (entry.retryOnFail !== undefined) {
         const parsed = asInteger(entry.retryOnFail);
@@ -304,6 +332,8 @@ function validateGateEntry(entry, at, seenIds, gates, issues) {
         // absence has to keep meaning "this gate runs exactly once".
         if (mutex !== undefined)
             gate.mutex = mutex;
+        if (mutexWaitSec !== undefined)
+            gate.mutexWaitSec = mutexWaitSec;
         if (retryOnFail !== undefined)
             gate.retryOnFail = retryOnFail;
         if (flakyIsPass !== undefined)

package/dist/server/src/types/agent-roles.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPECTED_ROLE_NAME_HEADER = exports.INSTANCE_CREATION_KEY_PATTERN = exports.INSTANCE_CREATION_KEY_HEADER = exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR = exports.AGENT_ROLE_CLI_TOOLS = exports.MAX_ROLE_NAME_LENGTH = exports.MAX_ROLE_BODY_BYTES = void 0;
+exports.isAgentRoleCliTool = isAgentRoleCliTool;
+exports.isAgentRoleAdapterEnabled = isAgentRoleAdapterEnabled;
+exports.agentRoleReplacesDefaultInstructions = agentRoleReplacesDefaultInstructions;
+/** Largest body, in UTF-8 bytes. Applied to the body, never to a composed artifact (§5). */
+exports.MAX_ROLE_BODY_BYTES = 16384;
+/** Longest role name, in UTF-16 code units. The name reaches no file name or command line. */
+exports.MAX_ROLE_NAME_LENGTH = 64;
+/** The tools a role can be given to (D3). Gemini and vibe-local are out of scope. */
+exports.AGENT_ROLE_CLI_TOOLS = [
+    'claude',
+    'codex',
+    'command-code',
+    'opencode',
+    'opencode-v2',
+    'copilot',
+    'antigravity',
+];
+function isAgentRoleCliTool(value) {
+    return typeof value === 'string' && exports.AGENT_ROLE_CLI_TOOLS.includes(value);
+}
+/** Turns Antigravity's adapter on, once its check under a dedicated OS user has passed (§6.6). */
+exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR = 'CM_AGENT_ROLE_ANTIGRAVITY_ENABLED';
+/**
+ * Whether a launch may apply a role through this tool's adapter yet. Antigravity
+ * can hold settings and its adapter is built, but stays off until the check under
+ * a dedicated OS user has passed (D3). A role resolved for a tool that is off
+ * refuses the launch; it never starts without it.
+ */
+function isAgentRoleAdapterEnabled(tool) {
+    if (tool !== 'antigravity')
+        return true;
+    return typeof process !== 'undefined' && process.env?.[exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR] === '1';
+}
+/**
+ * Whether a role through this tool replaces its default instructions instead of
+ * adding to them: OpenCode V2 overrides the agent's `system`, which removes the
+ * provider's base prompt (§7.2). The API says so, so a client can.
+ */
+function agentRoleReplacesDefaultInstructions(tool) {
+    return tool === 'opencode-v2';
+}
+/**
+ * Carries a key on a create or a roster PATCH (#4132): a client makes one per request. A
+ * condition about the request rather than part of what is written, so the body is the same
+ * with or without it.
+ */
+exports.INSTANCE_CREATION_KEY_HEADER = 'Idempotency-Key';
+exports.INSTANCE_CREATION_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+/**
+ * Carries the name a rename replaces (#4132), URI-encoded since a name need not be ASCII.
+ * A condition as well: the body of an edit stays only what the edit changes.
+ */
+exports.EXPECTED_ROLE_NAME_HEADER = 'X-Expected-Role-Name';

package/dist/types/agent-roles.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Roles: the vocabulary shared by the database, the resolver, the routes, the
+ * CLI (#4116) and the screen (#4117). Free of the database and of `fs`, so a
+ * client component and the launch path can both import it.
+ *
+ * Worked examples of every response: `tests/integration/fixtures/agent-roles-api-examples.ts`.
+ *
+ * Design: Epic #4112, `docs/design/agent-roles-adapters.md` §5 and §14.
+ *
+ * @module types/agent-roles
+ */
+import type { CLIToolType } from '../lib/cli-tools/types';
+/** Largest body, in UTF-8 bytes. Applied to the body, never to a composed artifact (§5). */
+export declare const MAX_ROLE_BODY_BYTES = 16384;
+/** Longest role name, in UTF-16 code units. The name reaches no file name or command line. */
+export declare const MAX_ROLE_NAME_LENGTH = 64;
+/** The tools a role can be given to (D3). Gemini and vibe-local are out of scope. */
+export declare const AGENT_ROLE_CLI_TOOLS: readonly ["claude", "codex", "command-code", "opencode", "opencode-v2", "copilot", "antigravity"];
+export type AgentRoleCliTool = (typeof AGENT_ROLE_CLI_TOOLS)[number];
+export declare function isAgentRoleCliTool(value: unknown): value is AgentRoleCliTool;
+/** Turns Antigravity's adapter on, once its check under a dedicated OS user has passed (§6.6). */
+export declare const AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR = "CM_AGENT_ROLE_ANTIGRAVITY_ENABLED";
+/**
+ * Whether a launch may apply a role through this tool's adapter yet. Antigravity
+ * can hold settings and its adapter is built, but stays off until the check under
+ * a dedicated OS user has passed (D3). A role resolved for a tool that is off
+ * refuses the launch; it never starts without it.
+ */
+export declare function isAgentRoleAdapterEnabled(tool: AgentRoleCliTool): boolean;
+/**
+ * Whether a role through this tool replaces its default instructions instead of
+ * adding to them: OpenCode V2 overrides the agent's `system`, which removes the
+ * provider's base prompt (§7.2). The API says so, so a client can.
+ */
+export declare function agentRoleReplacesDefaultInstructions(tool: string): boolean;
+/** What a client asks an instance or repository to hold. */
+export type RoleAssignmentInput = {
+    state: 'inherit';
+} | {
+    state: 'none';
+} | {
+    state: 'role';
+    roleId: string;
+};
+/**
+ * What an instance or repository holds. `inherit` is no row, `none` is a row
+ * with a NULL role, `role` is a row with one.
+ */
+export type StoredRoleState = {
+    state: 'inherit';
+} | {
+    state: 'none';
+} | {
+    state: 'role';
+    roleId: string;
+    roleName: string;
+};
+/** What the system level holds. It has no `none`: a missing row is the end of the chain. */
+export type StoredSystemRoleState = {
+    state: 'unset';
+} | {
+    state: 'role';
+    roleId: string;
+    roleName: string;
+};
+/** Everything pointing directly at a role. Inheritors of a default are not listed one by one. */
+export interface AgentRoleReferences {
+    instances: Array<{
+        worktreeId: string;
+        instanceId: string;
+    }>;
+    repositories: Array<{
+        repositoryId: string;
+        repositoryPath: string;
+        cliToolId: string;
+    }>;
+    system: Array<{
+        cliToolId: string;
+    }>;
+}
+/**
+ * The role a launch uses, taken once and never re-read. `bodyFingerprint` is the
+ * only fingerprint it can carry: the injection fingerprint depends on the user's
+ * settings at launch and comes from #4115's transform, the artifact fingerprint
+ * from the writer (§5).
+ */
+export interface ResolvedRole {
+    readonly id: string;
+    readonly name: string;
+    readonly bodyVersion: number;
+    readonly body: string;
+    readonly bodyFingerprint: string;
+}
+/** The level that decided. `unsupported` is the tool being outside D3. */
+export type RoleResolutionSource = 'instance' | 'repository' | 'system' | 'fallback' | 'unsupported';
+/** Why there is no role. */
+export type NoRoleReason = 'explicit-none' | 'no-default' | 'unsupported-tool';
+/**
+ * - `root-settings-differ`: the roots of one git repository hold different settings.
+ * - `membership-undetermined`: git could not say whether a root that would
+ *   disagree belongs to this repository.
+ */
+export type RoleAmbiguityReason = 'root-settings-differ' | 'membership-undetermined';
+export interface RoleAmbiguousRoot {
+    repositoryId: string;
+    path: string;
+    state: StoredRoleState;
+}
+interface RoleResolutionBase {
+    cliToolId: CLIToolType;
+    /**
+     * The registered root this answer is attributed to: the first by path among
+     * {@link repositoryIds}, so it does not depend on the scan order. Null when the
+     * worktree has no registered root.
+     */
+    repositoryId: string | null;
+    /** Every root the worktree belongs to. Settings are stored per root. */
+    repositoryIds: string[];
+}
+export type RoleResolution = (RoleResolutionBase & {
+    kind: 'role';
+    source: RoleResolutionSource;
+    role: ResolvedRole;
+}) | (RoleResolutionBase & {
+    kind: 'none';
+    source: RoleResolutionSource;
+    reason: NoRoleReason;
+}) | (RoleResolutionBase & {
+    kind: 'ambiguous';
+    source: 'repository';
+    reason: RoleAmbiguityReason;
+    roots: RoleAmbiguousRoot[];
+});
+/** A {@link ResolvedRole} safe to answer in a listing: no body. */
+export type EffectiveRoleSummary = Omit<ResolvedRole, 'body'>;
+/** A {@link RoleResolution} for an API response: the body is left out. */
+export type EffectiveRole = (RoleResolutionBase & {
+    kind: 'role';
+    source: RoleResolutionSource;
+    role: EffectiveRoleSummary;
+}) | (RoleResolutionBase & {
+    kind: 'none';
+    source: RoleResolutionSource;
+    reason: NoRoleReason;
+}) | (RoleResolutionBase & {
+    kind: 'ambiguous';
+    source: 'repository';
+    reason: RoleAmbiguityReason;
+    roots: RoleAmbiguousRoot[];
+});
+export type RoleLaunchPhase = 'requested' | 'launched';
+/**
+ * One line of evidence about a launch: what was resolved at that moment, not
+ * what the settings say now. Holds no body and no secret; a composition input is
+ * recorded only as a fingerprint. Written once.
+ */
+export interface RoleLaunchSnapshotInput {
+    worktreeId: string;
+    instanceId: string;
+    cliToolId: string;
+    phase: RoleLaunchPhase;
+    sessionGeneration: string;
+    source: RoleResolutionSource;
+    /** The root at that moment. Deliberately not a foreign key. */
+    repositoryId: string | null;
+    /** The role at that moment. Deliberately not a foreign key. */
+    roleId: string | null;
+    roleName: string | null;
+    bodyVersion: number | null;
+    bodyFingerprint: string | null;
+    injectionFingerprint: string | null;
+    artifactFingerprint: string | null;
+    adapterId: string | null;
+    adapterVersion: string | null;
+    wrapperVersion: string | null;
+    artifactPath: string | null;
+    /** OpenCode V2: the agent whose `system` was overridden. */
+    effectiveAgent: string | null;
+    /** Codex: the fingerprint of the `developer_instructions` it composed with. */
+    compositionSourceFingerprint: string | null;
+    noRoleReason: NoRoleReason | null;
+}
+export interface RoleLaunchRecord extends RoleLaunchSnapshotInput {
+    id: string;
+    recordedAt: number;
+}
+/**
+ * The application state of one instance. `effectiveNext` is what the next launch
+ * would use; `requested` and `launched` are snapshots of a launch, and are the role
+ * at startup, since a switch inside the TUI cannot be seen.
+ *
+ * `launched` is null until something confirms it (§14), and after a server restart:
+ * null is "not known", which is not "no role". A launch with no role has a record
+ * with a null fingerprint and a `noRoleReason`.
+ *
+ * `restartPending` compares injection fingerprints: another name or another level
+ * holding the same text is `no`; `unknown` when either side cannot be computed.
+ * `effectiveNext.injectionFingerprint` is null with no role, and when it could not
+ * be computed: the role is set and {@link RoleApplicationState.restartPending} is `unknown`.
+ */
+export interface RoleApplicationState {
+    effectiveNext: EffectiveRole & {
+        injectionFingerprint: string | null;
+    };
+    requested: RoleLaunchRecord | null;
+    launched: RoleLaunchRecord | null;
+    restartPending: 'yes' | 'no' | 'unknown';
+    /** Whether this tool's role replaces its default instructions. See {@link agentRoleReplacesDefaultInstructions}. */
+    replacesDefaultInstructions?: boolean;
+    /**
+     * OpenCode V1: the process continued a remembered conversation that had another
+     * role, whose replies are still in its history (§6.4). A new conversation is the
+     * `newConversation` of `POST /send`, at the next start.
+     */
+    resumedAcrossRole?: boolean;
+}
+export interface AgentRoleSummary {
+    id: string;
+    name: string;
+    bodyVersion: number;
+    bodyFingerprint: string;
+    bodyBytes: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface AgentRoleDetail extends AgentRoleSummary {
+    body: string;
+}
+export interface AgentRoleListResponse {
+    success: true;
+    roles: AgentRoleSummary[];
+}
+export interface AgentRoleDetailResponse {
+    success: true;
+    role: AgentRoleDetail;
+    references: AgentRoleReferences;
+}
+export interface AgentRoleEditResponse {
+    success: true;
+    before: AgentRoleDetail;
+    after: AgentRoleDetail;
+    bodyVersion: number;
+    affected: AgentRoleReferences;
+}
+export interface AgentRoleDeleteResponse {
+    success: true;
+    deleted: {
+        id: string;
+        name: string;
+    };
+    affected: AgentRoleReferences;
+}
+/** Every refusal. `error` is the stable code; `message` is for people. */
+export interface AgentRoleErrorResponse {
+    success: false;
+    error: 'invalid_request' | 'not_found' | 'name_conflict' | 'version_conflict' | 'name_changed' | 'role_in_use' | 'tool_not_supported' | 'instance_exists' | 'roster_changed' | 'idempotency_key_reused' | 'creation_cancelled' | 'internal_error';
+    message: string;
+    /** `version_conflict` only. */
+    currentBodyVersion?: number;
+}
+export interface AgentRoleDeleteConflictResponse extends AgentRoleErrorResponse {
+    error: 'role_in_use';
+    references: AgentRoleReferences;
+}
+export interface SystemRoleDefaultEntry {
+    cliToolId: AgentRoleCliTool;
+    adapterEnabled: boolean;
+    stored: StoredSystemRoleState;
+}
+export interface SystemRoleDefaultsResponse {
+    success: true;
+    defaults: SystemRoleDefaultEntry[];
+}
+export interface RepositoryRoleDefaultEntry {
+    cliToolId: AgentRoleCliTool;
+    adapterEnabled: boolean;
+    /** What this root holds. */
+    stored: StoredRoleState;
+    /** What a worktree of this root gets from the defaults, and from which level. */
+    effective: EffectiveRole;
+}
+export interface RepositoryRoleDefaultsResponse {
+    success: true;
+    repository: {
+        id: string;
+        name: string;
+        path: string;
+        enabled: boolean;
+    };
+    defaults: RepositoryRoleDefaultEntry[];
+}
+export interface InstanceRoleEntry {
+    instanceId: string;
+    cliToolId: CLIToolType;
+    alias: string;
+    /** False for a tool outside D3: it can hold no setting and always resolves to no role. */
+    supported: boolean;
+    adapterEnabled: boolean;
+    stored: StoredRoleState;
+    application: RoleApplicationState;
+}
+export interface WorktreeToolRoleDefault {
+    cliToolId: AgentRoleCliTool;
+    adapterEnabled: boolean;
+    /** What a new instance of this tool would get, before it exists. */
+    effective: EffectiveRole;
+}
+export interface InstanceRoleSettingsResponse {
+    success: true;
+    /** Hash of the roster as read. Hand it back as `expectedRosterRevision` to detect a change. */
+    rosterRevision: string;
+    /** False while the instances are derived primaries with no stored roster. */
+    rosterSaved: boolean;
+    instances: InstanceRoleEntry[];
+    toolDefaults: WorktreeToolRoleDefault[];
+}
+export interface InstanceRoleCreateResponse extends InstanceRoleSettingsResponse {
+    created: {
+        instanceId: string;
+    };
+    /** This `idempotencyKey` had already created it (#4132). Answered with 200 rather than 201. */
+    replayed?: true;
+}
+/**
+ * Carries a key on a create or a roster PATCH (#4132): a client makes one per request. A
+ * condition about the request rather than part of what is written, so the body is the same
+ * with or without it.
+ */
+export declare const INSTANCE_CREATION_KEY_HEADER = "Idempotency-Key";
+export declare const INSTANCE_CREATION_KEY_PATTERN: RegExp;
+/**
+ * Carries the name a rename replaces (#4132), URI-encoded since a name need not be ASCII.
+ * A condition as well: the body of an edit stays only what the edit changes.
+ */
+export declare const EXPECTED_ROLE_NAME_HEADER = "X-Expected-Role-Name";
+/**
+ * `POST .../instances/roles/settle`, for a write whose answer was lost (#4132).
+ * `cancelled`: the key made nothing and now never will, or the row it made has left the
+ * roster. A row with that id now is another's. `instanceId`: the row it added; a roster PATCH
+ * that added not exactly one has none.
+ */
+export type InstanceCreationSettleResponse = {
+    success: true;
+    outcome: 'committed';
+    instanceId?: string;
+} | {
+    success: true;
+    outcome: 'cancelled';
+};
+export {};
+//# sourceMappingURL=agent-roles.d.ts.map

package/dist/types/agent-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roles.d.ts","sourceRoot":"","sources":["../../src/types/agent-roles.ts"],"names":[],"mappings":"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"}

package/dist/types/agent-roles.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPECTED_ROLE_NAME_HEADER = exports.INSTANCE_CREATION_KEY_PATTERN = exports.INSTANCE_CREATION_KEY_HEADER = exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR = exports.AGENT_ROLE_CLI_TOOLS = exports.MAX_ROLE_NAME_LENGTH = exports.MAX_ROLE_BODY_BYTES = void 0;
+exports.isAgentRoleCliTool = isAgentRoleCliTool;
+exports.isAgentRoleAdapterEnabled = isAgentRoleAdapterEnabled;
+exports.agentRoleReplacesDefaultInstructions = agentRoleReplacesDefaultInstructions;
+/** Largest body, in UTF-8 bytes. Applied to the body, never to a composed artifact (§5). */
+exports.MAX_ROLE_BODY_BYTES = 16384;
+/** Longest role name, in UTF-16 code units. The name reaches no file name or command line. */
+exports.MAX_ROLE_NAME_LENGTH = 64;
+/** The tools a role can be given to (D3). Gemini and vibe-local are out of scope. */
+exports.AGENT_ROLE_CLI_TOOLS = [
+    'claude',
+    'codex',
+    'command-code',
+    'opencode',
+    'opencode-v2',
+    'copilot',
+    'antigravity',
+];
+function isAgentRoleCliTool(value) {
+    return typeof value === 'string' && exports.AGENT_ROLE_CLI_TOOLS.includes(value);
+}
+/** Turns Antigravity's adapter on, once its check under a dedicated OS user has passed (§6.6). */
+exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR = 'CM_AGENT_ROLE_ANTIGRAVITY_ENABLED';
+/**
+ * Whether a launch may apply a role through this tool's adapter yet. Antigravity
+ * can hold settings and its adapter is built, but stays off until the check under
+ * a dedicated OS user has passed (D3). A role resolved for a tool that is off
+ * refuses the launch; it never starts without it.
+ */
+function isAgentRoleAdapterEnabled(tool) {
+    if (tool !== 'antigravity')
+        return true;
+    return typeof process !== 'undefined' && process.env?.[exports.AGENT_ROLE_ANTIGRAVITY_ENABLED_ENV_VAR] === '1';
+}
+/**
+ * Whether a role through this tool replaces its default instructions instead of
+ * adding to them: OpenCode V2 overrides the agent's `system`, which removes the
+ * provider's base prompt (§7.2). The API says so, so a client can.
+ */
+function agentRoleReplacesDefaultInstructions(tool) {
+    return tool === 'opencode-v2';
+}
+/**
+ * Carries a key on a create or a roster PATCH (#4132): a client makes one per request. A
+ * condition about the request rather than part of what is written, so the body is the same
+ * with or without it.
+ */
+exports.INSTANCE_CREATION_KEY_HEADER = 'Idempotency-Key';
+exports.INSTANCE_CREATION_KEY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
+/**
+ * Carries the name a rename replaces (#4132), URI-encoded since a name need not be ASCII.
+ * A condition as well: the body of an edit stays only what the edit changes.
+ */
+exports.EXPECTED_ROLE_NAME_HEADER = 'X-Expected-Role-Name';

package/docs/en/user-guide/webapp-guide.md

@@ -445,6 +445,22 @@ Rename, reorder and delete in the **"Agent"** tool at the right of the header.
   [Approval Routes Differ by Agent](#approval-routes-differ-by-agent)
 - These sessions appear in the session field of the header ([current session][N more ▾])
 
+### Roles
+
+A role is the instructions given to a session when it starts. Create a name and a body, such as "Reviewer", then use it as a per-tool default or on one session. Roles apply to Claude, Codex, Command Code, OpenCode, OpenCode V2, Copilot and Antigravity (not Gemini or Vibe-Local; until Antigravity's check has passed, a start that resolves to a role is refused).
+
+- **Create, edit, delete, and the system defaults**: under General in the gear's settings dialog on PC, and `/more` on a phone. Deleting a role in use lists where it is used, and goes ahead only if you choose "Remove the settings and delete"
+- **Repository defaults**: **Roles** on each row of the Repositories screen, per tool: use the system default, none, or a role. Excluding a repository from scans keeps them, and they apply again when it is scanned again
+- **When adding**: choose "Default (role name)", none, or another role in the add form. The line below says where the default comes from, such as `Inherited: Reviewer [system]` or `Inherited: None [set on the repository]`
+- **Existing sessions**: open **Session roles** under Agents (the same on a phone). A session with no roster row yet can be changed too
+- **When it cannot be determined**: if the roots of one git repository hold different settings, for example, the reason is shown, and starts are refused until they agree or the session names a role
+
+**Changing a setting does not reach a running session.** The split header (on a phone, Session roles) keeps the start and the next apart, such as `At start: Reviewer / Next: PM / Pending`. When it cannot be confirmed, after a server restart for example, it reads `At start: Unknown`. **Restart** ends that session, and the next message starts a new one with the current settings.
+
+OpenCode's persona (build, plan, …) is not a role. A persona is the agent you switch inside OpenCode; a role is instructions CommandMate gives at startup. On OpenCode V2 a role replaces the agent's default instructions.
+
+So that nothing is overwritten from an older roster when several screens or the CLI change it at once, the screen's saves always carry the roster's revision (`expectedRosterRevision` on `PATCH /api/worktrees/:id`; a mismatch is a 409). The screen then reads the latest roster and saves again. When the current roster cannot be read, it does not save and says why. When a save went through but the latest state could not be read back, it says so, apart from a failure, and asks for a page reload.
+
 ### Ollama Model Selection (Vibe-Local)
 
 When Vibe-Local is selected, you can specify which Ollama model to use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.49.3",
+  "version": "0.50.0",
   "description": "No long blocks of time? Run an AI team from your phone. Git worktree sessions, task contracts and verification gates for Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity and Command Code.",
   "keywords": [
     "ai-agents",
@@ -115,6 +115,7 @@
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
     "safe-regex2": "^5.0.0",
+    "smol-toml": "1.9.1",
     "tailwind-merge": "^3.6.0",
     "unified": "^11.0.5",
     "uuid": "^13.0.0",