commandmate 0.49.3 → 0.50.0

package/.next/types/routes.d.ts

@@ -2,7 +2,7 @@
 // Do not edit this file manually
 
 type AppRoutes = "/" | "/login" | "/more" | "/offline" | "/repositories" | "/review" | "/sessions" | "/skills" | "/skills/[skillId]" | "/skills/installed" | "/worktrees/[id]" | "/worktrees/[id]/files/[...path]" | "/worktrees/[id]/terminal"
-type AppRouteHandlerRoutes = "/api/agents/update" | "/api/agents/versions" | "/api/app/release-notes" | "/api/app/update" | "/api/app/update-check" | "/api/auth/login" | "/api/auth/logout" | "/api/auth/status" | "/api/capabilities" | "/api/daily-summary" | "/api/daily-summary/status" | "/api/external-apps" | "/api/external-apps/[id]" | "/api/external-apps/[id]/health" | "/api/fs/browse" | "/api/fs/recent-paths" | "/api/hooks/agent-event" | "/api/hooks/claude-done" | "/api/hooks/permission-request" | "/api/metrics/vibe" | "/api/ollama/models" | "/api/push/escalation" | "/api/push/subscriptions" | "/api/push/vapid" | "/api/relays" | "/api/relays/[relayId]" | "/api/relays/[relayId]/cancel" | "/api/relays/[relayId]/resolve" | "/api/remote/pair" | "/api/repositories" | "/api/repositories/[id]" | "/api/repositories/clone" | "/api/repositories/clone/[jobId]" | "/api/repositories/excluded" | "/api/repositories/restore" | "/api/repositories/scan" | "/api/repositories/sync" | "/api/repositories/validate-path" | "/api/settings/default-agents" | "/api/settings/default-surface-mode" | "/api/sidebar/group-order" | "/api/skills" | "/api/skills/[id]" | "/api/skills/installations" | "/api/skills/operations" | "/api/skills/reindex" | "/api/slash-commands" | "/api/tasks/[taskId]" | "/api/tasks/[taskId]/cancel" | "/api/templates" | "/api/templates/[id]" | "/api/verification/runs" | "/api/verification/runs/[runId]" | "/api/worktrees" | "/api/worktrees/[id]" | "/api/worktrees/[id]/auto-yes" | "/api/worktrees/[id]/capture" | "/api/worktrees/[id]/clear-composer" | "/api/worktrees/[id]/cli-reference" | "/api/worktrees/[id]/cli-tool" | "/api/worktrees/[id]/cmate/schedules" | "/api/worktrees/[id]/current-output" | "/api/worktrees/[id]/direct-input" | "/api/worktrees/[id]/env" | "/api/worktrees/[id]/execution-logs" | "/api/worktrees/[id]/execution-logs/[logId]" | "/api/worktrees/[id]/files/[...path]" | "/api/worktrees/[id]/git/branch/create" | "/api/worktrees/[id]/git/branch/delete" | "/api/worktrees/[id]/git/branches" | "/api/worktrees/[id]/git/checkout" | "/api/worktrees/[id]/git/commit" | "/api/worktrees/[id]/git/diff" | "/api/worktrees/[id]/git/fetch" | "/api/worktrees/[id]/git/log" | "/api/worktrees/[id]/git/pull" | "/api/worktrees/[id]/git/push" | "/api/worktrees/[id]/git/reset" | "/api/worktrees/[id]/git/revert" | "/api/worktrees/[id]/git/show/[commitHash]" | "/api/worktrees/[id]/git/stage" | "/api/worktrees/[id]/git/staged" | "/api/worktrees/[id]/git/stash" | "/api/worktrees/[id]/git/stash/[index]" | "/api/worktrees/[id]/git/stash/apply" | "/api/worktrees/[id]/git/stash/pop" | "/api/worktrees/[id]/git/stash/push" | "/api/worktrees/[id]/git/status" | "/api/worktrees/[id]/git/unstage" | "/api/worktrees/[id]/git/working-diff" | "/api/worktrees/[id]/instances/notes" | "/api/worktrees/[id]/instances/opencode" | "/api/worktrees/[id]/interrupt" | "/api/worktrees/[id]/kill-session" | "/api/worktrees/[id]/logs" | "/api/worktrees/[id]/logs/[filename]" | "/api/worktrees/[id]/marp-render" | "/api/worktrees/[id]/memos" | "/api/worktrees/[id]/memos/[memoId]" | "/api/worktrees/[id]/messages" | "/api/worktrees/[id]/opencode/diff" | "/api/worktrees/[id]/opencode/session" | "/api/worktrees/[id]/opencode/share" | "/api/worktrees/[id]/prompt-response" | "/api/worktrees/[id]/prompt-response/strict" | "/api/worktrees/[id]/resolve-target" | "/api/worktrees/[id]/respond" | "/api/worktrees/[id]/schedules" | "/api/worktrees/[id]/schedules/[scheduleId]" | "/api/worktrees/[id]/schedules/active" | "/api/worktrees/[id]/search" | "/api/worktrees/[id]/send" | "/api/worktrees/[id]/skills" | "/api/worktrees/[id]/skills/[skillId]/git-workflow" | "/api/worktrees/[id]/skills/[skillId]/install" | "/api/worktrees/[id]/skills/[skillId]/plan" | "/api/worktrees/[id]/skills/[skillId]/uninstall" | "/api/worktrees/[id]/skills/[skillId]/uninstall-plan" | "/api/worktrees/[id]/skills/[skillId]/update" | "/api/worktrees/[id]/skills/[skillId]/update-plan" | "/api/worktrees/[id]/slash-commands" | "/api/worktrees/[id]/special-keys" | "/api/worktrees/[id]/tasks" | "/api/worktrees/[id]/terminal" | "/api/worktrees/[id]/timers" | "/api/worktrees/[id]/timers/history" | "/api/worktrees/[id]/todos" | "/api/worktrees/[id]/todos/[todoId]" | "/api/worktrees/[id]/tree" | "/api/worktrees/[id]/tree/[...path]" | "/api/worktrees/[id]/upload/[...path]" | "/api/worktrees/[id]/verify" | "/api/worktrees/[id]/verify/config" | "/api/worktrees/[id]/verify/runs" | "/api/worktrees/[id]/verify/runs/[runId]" | "/api/worktrees/[id]/verify/runs/[runId]/cancel" | "/api/worktrees/[id]/viewed" | "/api/worktrees/apply-default-agents" | "/proxy/[...path]"
+type AppRouteHandlerRoutes = "/api/agents/update" | "/api/agents/versions" | "/api/app/release-notes" | "/api/app/update" | "/api/app/update-check" | "/api/auth/login" | "/api/auth/logout" | "/api/auth/status" | "/api/capabilities" | "/api/daily-summary" | "/api/daily-summary/status" | "/api/external-apps" | "/api/external-apps/[id]" | "/api/external-apps/[id]/health" | "/api/fs/browse" | "/api/fs/recent-paths" | "/api/hooks/agent-event" | "/api/hooks/claude-done" | "/api/hooks/permission-request" | "/api/metrics/vibe" | "/api/ollama/models" | "/api/push/escalation" | "/api/push/subscriptions" | "/api/push/vapid" | "/api/relays" | "/api/relays/[relayId]" | "/api/relays/[relayId]/cancel" | "/api/relays/[relayId]/resolve" | "/api/remote/pair" | "/api/repositories" | "/api/repositories/[id]" | "/api/repositories/[id]/role-defaults" | "/api/repositories/clone" | "/api/repositories/clone/[jobId]" | "/api/repositories/excluded" | "/api/repositories/restore" | "/api/repositories/scan" | "/api/repositories/sync" | "/api/repositories/validate-path" | "/api/roles" | "/api/roles/[id]" | "/api/settings/agent-role-defaults" | "/api/settings/default-agents" | "/api/settings/default-surface-mode" | "/api/sidebar/group-order" | "/api/skills" | "/api/skills/[id]" | "/api/skills/installations" | "/api/skills/operations" | "/api/skills/reindex" | "/api/slash-commands" | "/api/tasks/[taskId]" | "/api/tasks/[taskId]/cancel" | "/api/templates" | "/api/templates/[id]" | "/api/verification/runs" | "/api/verification/runs/[runId]" | "/api/worktrees" | "/api/worktrees/[id]" | "/api/worktrees/[id]/auto-yes" | "/api/worktrees/[id]/capture" | "/api/worktrees/[id]/clear-composer" | "/api/worktrees/[id]/cli-reference" | "/api/worktrees/[id]/cli-tool" | "/api/worktrees/[id]/cmate/schedules" | "/api/worktrees/[id]/current-output" | "/api/worktrees/[id]/direct-input" | "/api/worktrees/[id]/env" | "/api/worktrees/[id]/execution-logs" | "/api/worktrees/[id]/execution-logs/[logId]" | "/api/worktrees/[id]/files/[...path]" | "/api/worktrees/[id]/git/branch/create" | "/api/worktrees/[id]/git/branch/delete" | "/api/worktrees/[id]/git/branches" | "/api/worktrees/[id]/git/checkout" | "/api/worktrees/[id]/git/commit" | "/api/worktrees/[id]/git/diff" | "/api/worktrees/[id]/git/fetch" | "/api/worktrees/[id]/git/log" | "/api/worktrees/[id]/git/pull" | "/api/worktrees/[id]/git/push" | "/api/worktrees/[id]/git/reset" | "/api/worktrees/[id]/git/revert" | "/api/worktrees/[id]/git/show/[commitHash]" | "/api/worktrees/[id]/git/stage" | "/api/worktrees/[id]/git/staged" | "/api/worktrees/[id]/git/stash" | "/api/worktrees/[id]/git/stash/[index]" | "/api/worktrees/[id]/git/stash/apply" | "/api/worktrees/[id]/git/stash/pop" | "/api/worktrees/[id]/git/stash/push" | "/api/worktrees/[id]/git/status" | "/api/worktrees/[id]/git/unstage" | "/api/worktrees/[id]/git/working-diff" | "/api/worktrees/[id]/instances/notes" | "/api/worktrees/[id]/instances/opencode" | "/api/worktrees/[id]/instances/roles" | "/api/worktrees/[id]/instances/roles/settle" | "/api/worktrees/[id]/interrupt" | "/api/worktrees/[id]/kill-session" | "/api/worktrees/[id]/logs" | "/api/worktrees/[id]/logs/[filename]" | "/api/worktrees/[id]/marp-render" | "/api/worktrees/[id]/memos" | "/api/worktrees/[id]/memos/[memoId]" | "/api/worktrees/[id]/messages" | "/api/worktrees/[id]/opencode/diff" | "/api/worktrees/[id]/opencode/session" | "/api/worktrees/[id]/opencode/share" | "/api/worktrees/[id]/prompt-response" | "/api/worktrees/[id]/prompt-response/strict" | "/api/worktrees/[id]/resolve-target" | "/api/worktrees/[id]/respond" | "/api/worktrees/[id]/schedules" | "/api/worktrees/[id]/schedules/[scheduleId]" | "/api/worktrees/[id]/schedules/active" | "/api/worktrees/[id]/search" | "/api/worktrees/[id]/send" | "/api/worktrees/[id]/skills" | "/api/worktrees/[id]/skills/[skillId]/git-workflow" | "/api/worktrees/[id]/skills/[skillId]/install" | "/api/worktrees/[id]/skills/[skillId]/plan" | "/api/worktrees/[id]/skills/[skillId]/uninstall" | "/api/worktrees/[id]/skills/[skillId]/uninstall-plan" | "/api/worktrees/[id]/skills/[skillId]/update" | "/api/worktrees/[id]/skills/[skillId]/update-plan" | "/api/worktrees/[id]/slash-commands" | "/api/worktrees/[id]/special-keys" | "/api/worktrees/[id]/tasks" | "/api/worktrees/[id]/terminal" | "/api/worktrees/[id]/timers" | "/api/worktrees/[id]/timers/history" | "/api/worktrees/[id]/todos" | "/api/worktrees/[id]/todos/[todoId]" | "/api/worktrees/[id]/tree" | "/api/worktrees/[id]/tree/[...path]" | "/api/worktrees/[id]/upload/[...path]" | "/api/worktrees/[id]/verify" | "/api/worktrees/[id]/verify/config" | "/api/worktrees/[id]/verify/runs" | "/api/worktrees/[id]/verify/runs/[runId]" | "/api/worktrees/[id]/verify/runs/[runId]/cancel" | "/api/worktrees/[id]/viewed" | "/api/worktrees/apply-default-agents" | "/proxy/[...path]"
 type PageRoutes = never
 type LayoutRoutes = "/" | "/worktrees/[id]"
 type RedirectRoutes = never
@@ -43,6 +43,7 @@ interface ParamMap {
   "/api/remote/pair": {}
   "/api/repositories": {}
   "/api/repositories/[id]": { "id": string; }
+  "/api/repositories/[id]/role-defaults": { "id": string; }
   "/api/repositories/clone": {}
   "/api/repositories/clone/[jobId]": { "jobId": string; }
   "/api/repositories/excluded": {}
@@ -50,6 +51,9 @@ interface ParamMap {
   "/api/repositories/scan": {}
   "/api/repositories/sync": {}
   "/api/repositories/validate-path": {}
+  "/api/roles": {}
+  "/api/roles/[id]": { "id": string; }
+  "/api/settings/agent-role-defaults": {}
   "/api/settings/default-agents": {}
   "/api/settings/default-surface-mode": {}
   "/api/sidebar/group-order": {}
@@ -104,6 +108,8 @@ interface ParamMap {
   "/api/worktrees/[id]/git/working-diff": { "id": string; }
   "/api/worktrees/[id]/instances/notes": { "id": string; }
   "/api/worktrees/[id]/instances/opencode": { "id": string; }
+  "/api/worktrees/[id]/instances/roles": { "id": string; }
+  "/api/worktrees/[id]/instances/roles/settle": { "id": string; }
   "/api/worktrees/[id]/interrupt": { "id": string; }
   "/api/worktrees/[id]/kill-session": { "id": string; }
   "/api/worktrees/[id]/logs": { "id": string; }

package/.next/types/validator.ts

@@ -425,6 +425,15 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   type __Unused = __Check
 }
 
+// Validate ../../src/app/api/repositories/[id]/role-defaults/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/repositories/[id]/role-defaults">> = Specific
+  const handler = {} as typeof import("../../src/app/api/repositories/[id]/role-defaults/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
 // Validate ../../src/app/api/repositories/[id]/route.ts
 {
   type __IsExpected<Specific extends RouteHandlerConfig<"/api/repositories/[id]">> = Specific
@@ -506,6 +515,33 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   type __Unused = __Check
 }
 
+// Validate ../../src/app/api/roles/[id]/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/roles/[id]">> = Specific
+  const handler = {} as typeof import("../../src/app/api/roles/[id]/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/roles/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/roles">> = Specific
+  const handler = {} as typeof import("../../src/app/api/roles/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/settings/agent-role-defaults/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/settings/agent-role-defaults">> = Specific
+  const handler = {} as typeof import("../../src/app/api/settings/agent-role-defaults/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
 // Validate ../../src/app/api/settings/default-agents/route.ts
 {
   type __IsExpected<Specific extends RouteHandlerConfig<"/api/settings/default-agents">> = Specific
@@ -974,6 +1010,24 @@ type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRou
   type __Unused = __Check
 }
 
+// Validate ../../src/app/api/worktrees/[id]/instances/roles/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/instances/roles">> = Specific
+  const handler = {} as typeof import("../../src/app/api/worktrees/[id]/instances/roles/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
+// Validate ../../src/app/api/worktrees/[id]/instances/roles/settle/route.ts
+{
+  type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/instances/roles/settle">> = Specific
+  const handler = {} as typeof import("../../src/app/api/worktrees/[id]/instances/roles/settle/route.js")
+  type __Check = __IsExpected<typeof handler>
+  // @ts-ignore
+  type __Unused = __Check
+}
+
 // Validate ../../src/app/api/worktrees/[id]/interrupt/route.ts
 {
   type __IsExpected<Specific extends RouteHandlerConfig<"/api/worktrees/[id]/interrupt">> = Specific

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

@@ -7,6 +7,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)
  */
 import { Command } from 'commander';
 import { ApiClient } from '../utils/api-client';

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

@@ -1 +1 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAkD,MAAM,qBAAqB,CAAC;AA4KhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAE6D,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,QAE0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAmCjC;AAsWD,wBAAgB,sBAAsB,IAAI,OAAO,CAgFhD"}
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAA6E,MAAM,qBAAqB,CAAC;AA2N3H;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAE6D,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,QAE0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAmCjC;AAkiBD,wBAAgB,sBAAsB,IAAI,OAAO,CA0IhD"}

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);
         }
     });