conductor-remote 1.96.2 → 1.96.3

package/dist-node/src/mcp-tools.js

@@ -31,7 +31,7 @@ import { HIT_CLOSE, HIT_OPEN, isToolResult, timestampMs, workspaceTitle } from "
 /** Versions we know how to speak. The client's choice wins when we know it. */
 export const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 export const SERVER_INFO = { name: 'conductor-remote', version: '1' };
-export const INSTRUCTIONS = 'Drives local Conductor agents through the conductor-remote relay. search_chats and read_chat reach archived workspaces, which is where most finished work lives. create_workspace opens its workspace link without direct UI control; requested agent settings and the first prompt are applied later through Conductor’s UI. plan_usage, dismiss_prompt, keep_awake and relay_logs touch no UI. send_prompt, split_chat, stop_turn, close_chat, set_agent_options, set_default_model, a live list_models call, set_workspace_status and archive_workspace drive the real Mac UI and steal focus for a few seconds — confirm with the user before using them on a chat they did not name. archive_workspace also deletes the worktree and stops whatever is running there.';
+export const INSTRUCTIONS = 'Drives local Conductor agents through the conductor-remote relay. search_chats and read_chat reach archived workspaces, which is where most finished work lives. delegate_task later drives the real Mac UI and launches another agent through a persisted cross-provider queue; use it only when the user explicitly asked for delegation. It never uses Conductor Plan mode. create_workspace opens its workspace link without direct UI control; requested agent settings and the first prompt are applied later through Conductor’s UI. Its workflow option is itself an explicit delegation request: the configured planning role owns the root chat and may use delegate_task, still in ordinary chat mode and never Plan mode. plan_usage, dismiss_prompt, keep_awake and relay_logs touch no UI. send_prompt, split_chat, stop_turn, close_chat, set_agent_options, set_default_model, a live list_models call, set_workspace_status and archive_workspace drive the real Mac UI and steal focus for a few seconds — confirm with the user before using them on a chat they did not name. archive_workspace also deletes the worktree and stops whatever is running there.';
 /** Reads are quick; a UI write is measured in tens of seconds (writes.ts ▸ SEND_ATTEMPT_MS). */
 export const READ_TIMEOUT_MS = 10_000;
 export const WRITE_TIMEOUT_MS = 75_000;
@@ -282,9 +282,10 @@ export function createTools(call) {
                     return status ? `no workspace is ${status}` : 'no live workspaces';
                 return shown
                     .map(w => {
+                    const assigned = w.active_session_id ? w.session_roles?.[w.active_session_id] : undefined;
                     const lines = [
                         `${w.session_status === 'working' ? '▶' : '·'} ${workspaceTitle(w)}`,
-                        `    ${[w.repo_name, w.branch, w.model, w.pr_number ? `PR #${w.pr_number} ${w.pr_status ?? ''}`.trim() : null].filter(Boolean).join(' · ')}`,
+                        `    ${[w.repo_name, w.branch, w.model, assigned ? `role ${assigned.role}` : null, w.pr_number ? `PR #${w.pr_number} ${w.pr_status ?? ''}`.trim() : null].filter(Boolean).join(' · ')}`,
                         `    workspace_id: ${w.id}${w.active_session_id ? `  session_id: ${w.active_session_id}` : ''}`
                     ];
                     // An undelivered prompt is invisible from the DB — it lives in the relay's own
@@ -297,6 +298,11 @@ export function createTools(call) {
                     for (const p of w.parked_prompts ?? []) {
                         lines.push(`    ! prompt ${p.status} for session ${p.sessionId} (${p.reason}): ${clip(unmark(p.text), 120)}`);
                     }
+                    for (const job of w.delegations ?? []) {
+                        lines.push(`    ${job.status === 'failed' ? '!' : '→'} delegation ${job.role}: ${job.status} (${job.id})${job.failure ? ` — ${job.failure.message}` : ''}`);
+                    }
+                    if (w.delegation_warning)
+                        lines.push(`    ! delegation state: ${w.delegation_warning}`);
                     return lines.join('\n');
                 })
                     .join('\n');
@@ -327,11 +333,164 @@ export function createTools(call) {
                     // second prompt into the wait.
                     const waiting = (s.background_tasks ?? []).map(t => `\n    waiting for task: ${t.description} (${Math.max(0, Math.round((Date.now() - timestampMs(t.since)) / 60_000))}m so far)`);
                     const glyph = s.status === 'working' ? '▶' : waiting.length ? '⧗' : '·';
-                    return `${glyph} ${s.title ?? '(untitled)'} — ${s.status ?? '?'} · ${s.model ?? '?'}${ctx}\n    session_id: ${s.id}${waiting.join('')}`;
+                    const role = data.session_roles?.[s.id];
+                    return `${glyph} ${s.title ?? '(untitled)'} — ${s.status ?? '?'} · ${s.model ?? '?'}${role ? ` · role ${role.role}` : ''}${ctx}\n    session_id: ${s.id}${waiting.join('')}`;
+                })
+                    .join('\n');
+            }
+        },
+        {
+            name: 'list_roles',
+            description: 'List the relay’s picker-backed cross-provider roles. A role marked invalid cannot be delegated until its exact model is selected. Delegated roles never enable Conductor Plan mode.',
+            inputSchema: { type: 'object', properties: {} },
+            run: async () => {
+                const data = await call(routes.roles.path());
+                const issueByRole = new Map(data.issues.map(issue => [issue.role, issue.error]));
+                const lines = Object.entries(data.roles).map(([name, role]) => {
+                    const settings = [role.model, role.effort, role.fast ? 'fast' : null].filter(Boolean).join(' · ');
+                    const issue = issueByRole.get(name);
+                    return `${issue ? '!' : '·'} ${name}: ${settings}${issue ? ` — ${issue.code}: ${issue.message}` : ''}`;
+                });
+                if (data.warning)
+                    lines.unshift(`! ${data.warning}`);
+                return lines.join('\n') || 'no delegated roles are configured';
+            }
+        },
+        {
+            name: 'set_role',
+            description: 'Set one cross-provider delegated role using an exact label from list_models. This changes relay config only and does not drive Conductor. Plan mode is intentionally not a role option.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    role: { type: 'string', description: 'Lowercase role name, for example exploration.' },
+                    model: { type: 'string', description: 'Exact picker label from list_models.' },
+                    effort: {
+                        type: 'string',
+                        enum: ['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode']
+                    },
+                    fast: { type: 'boolean' },
+                    preamble: { type: 'string', description: 'Optional instructions prepended to each delegated task.' }
+                },
+                required: ['role', 'model']
+            },
+            run: async (args) => {
+                const name = need(args, 'role');
+                const model = need(args, 'model');
+                const effort = str(args.effort);
+                const efforts = ['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode'];
+                if (effort && !efforts.includes(effort))
+                    throw new Error('effort is invalid');
+                const current = await call(routes.roles.path());
+                const prior = current.roles[name];
+                const role = {
+                    model,
+                    ...(effort ? { effort: effort } : prior?.effort ? { effort: prior.effort } : {}),
+                    ...(typeof args.fast === 'boolean'
+                        ? { fast: args.fast }
+                        : prior?.fast !== undefined
+                            ? { fast: prior.fast }
+                            : {}),
+                    ...(typeof args.preamble === 'string'
+                        ? { preamble: args.preamble }
+                        : prior?.preamble !== undefined
+                            ? { preamble: prior.preamble }
+                            : {})
+                };
+                const config = { version: 1, roles: { ...current.roles, [name]: role } };
+                const result = await call(routes.updateRoles.path(), {
+                    method: routes.updateRoles.method,
+                    body: config
+                });
+                if (!result.ok)
+                    throw new Error(`${result.error.code}: ${result.error.message}`);
+                return `${name}: ${[role.model, role.effort, role.fast ? 'fast' : null].filter(Boolean).join(' · ')}`;
+            }
+        },
+        {
+            name: 'delegate_task',
+            description: 'Queue work in a real sibling Conductor chat using a configured role on a different provider. The relay attaches this chat’s transcript, configures the child without Plan mode, sends the task, waits for a stable answer, and returns its Baton here. Returns immediately with a delegation id; use list_delegations to observe it. Only use it when the user asked for cross-provider delegation because the queue launches a real agent and drives the Mac UI after this call returns.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    session_id: { type: 'string', description: 'Parent chat that receives the eventual Baton.' },
+                    workspace_id: { type: 'string', description: 'Optional assertion for the parent workspace.' },
+                    role: { type: 'string', description: 'Exact role name from list_roles.' },
+                    prompt: { type: 'string' },
+                    through: { type: 'string', description: 'Optional cursor from read_chat; later rows are omitted.' },
+                    include_thinking: { type: 'boolean', description: 'Include parent reasoning in the handoff (default true).' },
+                    return_mode: {
+                        type: 'string',
+                        enum: ['queue', 'steer'],
+                        description: 'Queue a new parent turn by default; steer explicitly injects into a running turn.'
+                    }
+                },
+                required: ['session_id', 'role', 'prompt']
+            },
+            run: async (args) => {
+                const sessionId = need(args, 'session_id');
+                const through = str(args.through);
+                const throughRowid = through ? parseChatCursor(through) : undefined;
+                if (through && throughRowid === null)
+                    throw new Error('through must be a cursor returned by read_chat');
+                const returnMode = str(args.return_mode);
+                if (returnMode && returnMode !== 'queue' && returnMode !== 'steer')
+                    throw new Error('return_mode is invalid');
+                const result = await call(routes.delegateTask.path(sessionId), {
+                    method: routes.delegateTask.method,
+                    body: {
+                        role: need(args, 'role'),
+                        prompt: need(args, 'prompt'),
+                        workspaceId: str(args.workspace_id),
+                        throughRowid,
+                        includeThinking: args.include_thinking === undefined ? undefined : args.include_thinking === true,
+                        returnMode
+                    }
+                });
+                if (!result.ok)
+                    throw new Error(`${result.error.code}: ${result.error.message}`);
+                return `delegation ${result.delegationId} queued · ${result.role} · ${result.model}`;
+            }
+        },
+        {
+            name: 'list_delegations',
+            description: 'List active and failed delegated jobs. Successful jobs leave their chats and role chips, not a second history log.',
+            inputSchema: {
+                type: 'object',
+                properties: { workspace_id: { type: 'string', description: 'Optional workspace filter.' } }
+            },
+            run: async (args) => {
+                const workspaceId = str(args.workspace_id);
+                const suffix = workspaceId ? `?workspaceId=${encodeURIComponent(workspaceId)}` : '';
+                const data = await call(`${routes.delegations.path()}${suffix}`);
+                if (!data.delegations.length)
+                    return 'no active or failed delegations';
+                return data.delegations
+                    .map(job => {
+                    const child = job.childSessionId ? ` · child ${job.childSessionId}` : '';
+                    const failure = job.failure ? ` · ${job.failure.code}: ${job.failure.message}` : '';
+                    return `${job.status} · ${job.role} · ${job.resolvedRole.model} · ${job.id}${child}${failure}`;
                 })
                     .join('\n');
             }
         },
+        {
+            name: 'dismiss_delegation',
+            description: 'Dismiss one failed delegation job. Its parent/child chats and role identity remain.',
+            inputSchema: {
+                type: 'object',
+                properties: { delegation_id: { type: 'string' } },
+                required: ['delegation_id']
+            },
+            run: async (args) => {
+                const id = need(args, 'delegation_id');
+                const result = await call(routes.dismissDelegation.path(id), {
+                    method: routes.dismissDelegation.method
+                });
+                if (!result.ok)
+                    throw new Error(`${result.error.code}: ${result.error.message}`);
+                return `dismissed delegation ${result.delegationId}`;
+            }
+        },
         {
             name: 'workspace_diff',
             description: 'The git diff of a live workspace against its target branch, untracked files included.',
@@ -381,7 +540,7 @@ export function createTools(call) {
         },
         {
             name: 'create_workspace',
-            description: 'Start a new Conductor workspace in a repo, optionally with a first prompt and agent settings. The workspace starts from a Conductor deep link, so creation itself needs no Accessibility. The relay applies requested model, effort, plan, and fast settings through Conductor’s UI after it creates the first chat and before it delivers the prompt. Returns as soon as the workspace row exists (~2s), before the worktree is built.',
+            description: 'Start a new Conductor workspace in a repo, optionally with a first prompt and agent settings. The workspace starts from a Conductor deep link, so creation itself needs no Accessibility. The relay applies requested model, effort, plan, and fast settings through Conductor’s UI after it creates the first chat and before it delivers the prompt. Workflow mode instead configures the root from the planning role and explicitly authorizes cross-provider delegate_task calls; it never enables Conductor Plan mode. Returns as soon as the workspace row exists (~2s), before the worktree is built.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -393,11 +552,15 @@ export function createTools(call) {
                     },
                     effort: {
                         type: 'string',
-                        enum: ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'],
+                        enum: ['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode'],
                         description: 'Reasoning effort applied before the first prompt.'
                     },
                     plan: { type: 'boolean', description: 'Start the first chat in Conductor’s Plan mode.' },
                     fast: { type: 'boolean', description: 'Set Fast mode before the first prompt.' },
+                    workflow: {
+                        type: 'boolean',
+                        description: 'Start the first prompt as a delegated workflow rooted in the configured planning role. Requires a prompt and cannot be combined with model, effort, plan, or fast. Uses ordinary chat mode, never Conductor Plan mode.'
+                    },
                     wait_for_send: {
                         type: 'boolean',
                         description: 'Block until the first prompt is actually delivered (tens of seconds, and longer behind other queued sends). Default false.'
@@ -416,19 +579,30 @@ export function createTools(call) {
                 const effort = str(args.effort);
                 const plan = typeof args.plan === 'boolean' ? args.plan : undefined;
                 const fast = typeof args.fast === 'boolean' ? args.fast : undefined;
-                const configured = model !== undefined || effort !== undefined || plan !== undefined || fast !== undefined;
+                const workflow = args.workflow === true;
+                const explicitAgent = model !== undefined || effort !== undefined || plan !== undefined || fast !== undefined;
+                if (workflow && explicitAgent) {
+                    throw new Error('workflow cannot be combined with model, effort, plan, or fast');
+                }
+                if (workflow && !prompt)
+                    throw new Error('workflow needs a first prompt');
+                const configured = workflow || explicitAgent;
                 const send = args.wait_for_send === true;
                 // Default on, matching the relay: an omitted flag must never mean "wait".
                 const sendImmediately = args.send_immediately !== false;
                 const data = await call(routes.createWorkspace.path(), {
                     method: routes.createWorkspace.method,
-                    body: { repo, prompt, model, effort, plan, fast, send, sendImmediately },
+                    body: workflow
+                        ? { repo, prompt, workflow: true, send, sendImmediately }
+                        : { repo, prompt, model, effort, plan, fast, send, sendImmediately },
                     timeoutMs: send ? WRITE_TIMEOUT_MS : 30_000
                 });
                 const lines = [
                     `created ${data.workspace ? workspaceTitle(data.workspace) : data.workspaceId}`,
                     `workspace_id: ${data.workspaceId}`
                 ];
+                if (data.workflow)
+                    lines.push(`workflow root: ${data.workflow.role} · ${data.workflow.model}`);
                 if (data.warning)
                     lines.push(`! ${data.warning}`);
                 else if (data.pendingPrompt && !data.sent)
@@ -695,7 +869,7 @@ export function createTools(call) {
                         description: 'Strongly recommended: it is what the relay asserts against before pressing anything.'
                     },
                     model: { type: 'string', description: 'A label from list_models. An unambiguous prefix is enough.' },
-                    effort: { type: 'string', enum: ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'] },
+                    effort: { type: 'string', enum: ['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode'] },
                     plan: { type: 'boolean', description: 'Conductor’s Plan checkbox.' },
                     fast: {
                         type: 'boolean',

package/dist-node/src/notify.js

@@ -31,8 +31,6 @@ import path from 'node:path';
 import { stateDir } from "./config.js";
 import { generateVapidKeys, MAX_PAYLOAD_BYTES, sendPush } from "./webpush.js";
 const STORE_VERSION = 1;
-/** Poll cadence for status transitions. Matches the phone's own list poll — a local SQLite read is cheap. */
-const TICK_MS = 3000;
 /**
  * How long a push service should hold a notification for a phone that's offline.
  * An hour: long enough to survive a tunnel/airplane-mode blip, short enough that
@@ -415,12 +413,12 @@ export class TurnWatcher {
     }
 }
 const watcher = new TurnWatcher();
-function tick(reads) {
+function tick(reads, states) {
     if (deviceCount() === 0) {
         watcher.reset();
         return;
     }
-    for (const due of watcher.step(reads.listSessionStates()))
+    for (const due of watcher.step(states))
         void fire(reads, due.state.sessionId, due.kind, due.state);
 }
 async function fire(reads, sessionId, kind, state) {
@@ -448,23 +446,20 @@ async function fire(reads, sessionId, kind, state) {
         console.info(`[push] ${kind} in ${where} → ${sent} device${sent === 1 ? '' : 's'}`);
 }
 /**
- * Start watching for turn endings. Safe to call unconditionally — with no
- * subscribed devices this is one small local query every few seconds, and
- * `PUSH_NOTIFY=off` skips it entirely.
+ * Subscribe notification decisions to the shared session clock. Push settings
+ * gate only this listener; the poller itself still runs for delegation progress.
  */
-export function startNotifier(reads) {
+export function startNotifier(reads, poller) {
     if (!notificationsEnabled()) {
         console.info('[push] notifications disabled (PUSH_NOTIFY=off)');
-        return;
+        return () => undefined;
     }
-    const timer = setInterval(() => {
+    return poller.subscribe(states => {
         try {
-            tick(reads);
+            tick(reads, states);
         }
         catch (err) {
-            // A transient DB read failure must not kill the interval.
             console.warn(`[push] watcher tick failed: ${err instanceof Error ? err.message : err}`);
         }
-    }, TICK_MS);
-    timer.unref();
+    });
 }

package/dist-node/src/reads.js

@@ -8,9 +8,12 @@ import { parseMessage, parseOutboxMessage, toolImageAt } from "./transcript.js";
 /** Keep the stable wire field in sync with whichever provider owns the chat. */
 function toSessionRow(row, background_tasks) {
     const { codex_thinking_level, ...session } = row;
+    const effort = row.agent_type === 'codex' ? codex_thinking_level : row.claude_effort_level;
     return {
         ...session,
-        claude_effort_level: row.agent_type === 'codex' ? codex_thinking_level : row.claude_effort_level,
+        // Codex calls its top level `ultra`; the relay's long-lived wire value is
+        // `ultracode`, which is also Claude's stored spelling and the phone's key.
+        claude_effort_level: effort === 'ultra' ? 'ultracode' : effort,
         background_tasks
     };
 }
@@ -346,6 +349,23 @@ export class Reads {
             return toSessionRow(row, started === undefined ? [] : this.openBackgroundTasks(row.id, started));
         });
     }
+    /** One delegated child, including its provider-specific open-task guard. */
+    getSession(sessionId) {
+        const rows = this.db.query(`SELECT s.id, s.status, s.title, s.model, s.permission_mode,
+			        s.claude_effort_level, s.codex_thinking_level, s.fast_mode, s.agent_type,
+			        s.context_used_percent, s.unread_count,
+			        s.created_at, s.updated_at, s.last_user_message_at,
+			        (SELECT MAX(m.sent_at) FROM session_messages m
+			          WHERE m.session_id = s.id AND m.queue_order IS NOT NULL AND m.sent_at IS NOT NULL) AS turn_started_at
+			 FROM sessions s
+			 WHERE s.id = ? AND COALESCE(s.is_hidden, 0) = 0
+			 LIMIT 1`, [sessionId]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        const started = this.liveAgents().get(row.id);
+        return toSessionRow(row, started === undefined ? [] : this.openBackgroundTasks(row.id, started));
+    }
     /**
      * The background tasks a chat is still waiting on (src/background-tasks.ts).
      *

package/dist-node/src/roles.js

@@ -0,0 +1,195 @@
+/**
+ * Global delegated-role definitions.
+ *
+ * Roles are relay preferences, not Conductor state, and therefore live beside the
+ * relay's other private JSON files. The decoder is strict on purpose: silently
+ * ignoring a hand-written `plan` field would make a role appear safe while still
+ * inviting callers to depend on Conductor's currently unreliable Plan mode.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir } from "./config.js";
+import { modelAgentType, modelCatalogIncludes, modelPickerLabel } from "./shared.js";
+const EFFORTS = new Set(['none', 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode']);
+const ROLE_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+const MAX_ROLES = 32;
+const MAX_MODEL_LENGTH = 256;
+const MAX_PREAMBLE_LENGTH = 50_000;
+const ROLE_FIELDS = new Set(['model', 'effort', 'fast', 'preamble']);
+const batonPreamble = (role) => `You are the ${role} agent for this workspace. End your final answer with a \`## Baton\` section: Decision, Evidence, Files changed, Risks, Suggested next role.`;
+export const DEFAULT_ROLES = {
+    version: 1,
+    roles: {
+        planning: { model: 'Fable 5', effort: 'max', fast: false, preamble: batonPreamble('planning') },
+        // Conductor currently offers two distinct Muse Spark rows. This descriptive
+        // placeholder intentionally matches neither, so the user must choose exactly.
+        exploration: { model: 'Muse Spark', effort: 'high', fast: false, preamble: batonPreamble('exploration') },
+        implementation: { model: '5.6 Sol', effort: 'xhigh', fast: false, preamble: batonPreamble('implementation') }
+    }
+};
+function object(raw) {
+    return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : null;
+}
+function cloneRole(role) {
+    return { ...role };
+}
+function cloneConfig(config) {
+    return {
+        version: 1,
+        roles: Object.fromEntries(Object.entries(config.roles).map(([name, role]) => [name, cloneRole(role)]))
+    };
+}
+function decodeRole(name, raw) {
+    if (!ROLE_NAME.test(name))
+        throw new Error(`invalid role name ${name}`);
+    const value = object(raw);
+    if (!value)
+        throw new Error(`role ${name} must be an object`);
+    const unknown = Object.keys(value).find(field => !ROLE_FIELDS.has(field));
+    if (unknown)
+        throw new Error(`role ${name} has unknown field ${unknown}`);
+    if (typeof value.model !== 'string' || !value.model.trim() || value.model.length > MAX_MODEL_LENGTH) {
+        throw new Error(`role ${name} needs a picker model label`);
+    }
+    const role = { model: modelPickerLabel(value.model.trim()) };
+    if (value.effort !== undefined) {
+        if (typeof value.effort !== 'string' || !EFFORTS.has(value.effort)) {
+            throw new Error(`role ${name} has an invalid effort`);
+        }
+        role.effort = value.effort;
+    }
+    if (value.fast !== undefined) {
+        if (typeof value.fast !== 'boolean')
+            throw new Error(`role ${name} has an invalid fast value`);
+        role.fast = value.fast;
+    }
+    if (value.preamble !== undefined) {
+        if (typeof value.preamble !== 'string' || value.preamble.length > MAX_PREAMBLE_LENGTH) {
+            throw new Error(`role ${name} has an invalid preamble`);
+        }
+        role.preamble = value.preamble;
+    }
+    return role;
+}
+export function decodeRoles(raw) {
+    const value = object(raw);
+    if (!value)
+        throw new Error('roles document must be an object');
+    if (value.version !== 1)
+        throw new Error(`unsupported roles version ${String(value.version)}`);
+    const roles = object(value.roles);
+    if (!roles)
+        throw new Error('roles must be an object');
+    const entries = Object.entries(roles);
+    if (!entries.length || entries.length > MAX_ROLES)
+        throw new Error(`roles must contain 1-${MAX_ROLES} entries`);
+    return { version: 1, roles: Object.fromEntries(entries.map(([name, role]) => [name, decodeRole(name, role)])) };
+}
+function issue(code, message) {
+    return { code, message, retryable: false };
+}
+function effortIssue(name, role, agentType) {
+    return role.effort === 'none' && agentType !== 'codex'
+        ? issue('invalid_request', `Role ${name} can use None effort only with a Codex model.`)
+        : null;
+}
+/** Picker validation stays separate from shape decoding so a vanished model remains editable. */
+export function roleModelIssues(config, groups) {
+    const issues = [];
+    for (const [name, role] of Object.entries(config.roles)) {
+        if (!modelCatalogIncludes(role.model, groups)) {
+            issues.push({
+                role: name,
+                error: issue('model_missing', `Role ${name} needs an exact model from Conductor's current picker.`)
+            });
+            continue;
+        }
+        const agentType = modelAgentType(role.model);
+        if (!agentType) {
+            issues.push({
+                role: name,
+                error: issue('provider_unknown', `Role ${name}'s model label does not identify a supported provider.`)
+            });
+            continue;
+        }
+        const invalidEffort = effortIssue(name, role, agentType);
+        if (invalidEffort)
+            issues.push({ role: name, error: invalidEffort });
+    }
+    return issues;
+}
+/** Resolve and freeze the provider encoded by an exact cached picker label. */
+export function resolveRole(config, name, groups) {
+    const role = config.roles[name];
+    if (!role)
+        return { ok: false, error: issue('role_not_found', `Unknown delegated role ${name}.`) };
+    if (!modelCatalogIncludes(role.model, groups)) {
+        return {
+            ok: false,
+            error: issue('model_missing', `Role ${name} needs an exact model from Conductor's current picker.`)
+        };
+    }
+    const agentType = modelAgentType(role.model);
+    if (!agentType) {
+        return {
+            ok: false,
+            error: issue('provider_unknown', `Role ${name}'s model label does not identify a supported provider.`)
+        };
+    }
+    const invalidEffort = effortIssue(name, role, agentType);
+    if (invalidEffort)
+        return { ok: false, error: invalidEffort };
+    return { ok: true, role: { ...cloneRole(role), agentType } };
+}
+/** Cached, process-local store. A rejected write leaves both memory and disk untouched. */
+export class RoleStore {
+    file;
+    cache = null;
+    constructor(file = path.join(stateDir(), 'roles.json')) {
+        this.file = file;
+    }
+    read() {
+        if (this.cache)
+            return { ...this.cache, config: cloneConfig(this.cache.config) };
+        try {
+            this.cache = { config: decodeRoles(JSON.parse(fs.readFileSync(this.file, 'utf8'))) };
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                this.cache = { config: cloneConfig(DEFAULT_ROLES) };
+            else {
+                this.cache = {
+                    config: cloneConfig(DEFAULT_ROLES),
+                    warning: `Could not read roles.json: ${err instanceof Error ? err.message : String(err)}`
+                };
+            }
+        }
+        return { ...this.cache, config: cloneConfig(this.cache.config) };
+    }
+    write(raw) {
+        let config;
+        try {
+            config = decodeRoles(raw);
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+        const directory = path.dirname(this.file);
+        const temporary = `${this.file}.${process.pid}.tmp`;
+        try {
+            fs.mkdirSync(directory, { recursive: true });
+            fs.writeFileSync(temporary, `${JSON.stringify(config, null, '\t')}\n`, { mode: 0o600 });
+            fs.chmodSync(temporary, 0o600);
+            fs.renameSync(temporary, this.file);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch { }
+            return { ok: false, error: `could not persist roles: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        this.cache = { config };
+        return { ok: true, config: cloneConfig(config) };
+    }
+}

package/dist-node/src/routes.js

@@ -86,6 +86,13 @@ export const routes = {
     pushSubscribe: flat('POST', '/api/push/subscribe'),
     pushUnsubscribe: flat('POST', '/api/push/unsubscribe'),
     pushTest: flat('POST', '/api/push/test'),
+    /** Global picker-backed delegated-role definitions. */
+    roles: flat('GET', '/api/roles'),
+    updateRoles: flat('PATCH', '/api/roles'),
+    /** Active and failed jobs; optionally filtered with `?workspaceId=`. */
+    delegations: flat('GET', '/api/delegations'),
+    /** Dismiss one failed job without touching its chats or session-role identity. */
+    dismissDelegation: param('DELETE', '/api/delegations/:delegationId'),
     // ── workspaces ──
     createWorkspace: flat('POST', '/api/workspaces'),
     /** One workspace by id, archived included — what `/api/state` deliberately leaves out. */
@@ -121,6 +128,8 @@ export const routes = {
     uploadAttachment: param('POST', '/api/sessions/:sessionId/attachments'),
     /** Copy a chat into a fresh tab beside it, as a Conductor attachment (src/attachments.ts). */
     splitChat: param('POST', '/api/sessions/:sessionId/split'),
+    /** Accept a persisted cross-provider job and return before its UI stages run. */
+    delegateTask: param('POST', '/api/sessions/:sessionId/delegate'),
     /** Dismiss a prompt parked behind the lock screen (src/parked.ts). */
     dismissParkedPrompt: param('DELETE', '/api/sessions/:sessionId/prompt')
 };