taskchef 7.27.2 → 7.28.1

package/src/dashboard/react/App.test.tsx

@@ -1,4 +1,4 @@
-import { act, cleanup, render, screen } from "@testing-library/react";
+import { act, cleanup, render, screen, within } from "@testing-library/react";
 import type { ElementType, ReactNode } from "react";
 import { afterEach, beforeEach, expect, test, vi } from "vitest";
 import { DashboardApp } from "./App";
@@ -21,6 +21,8 @@ vi.mock("@tabler/icons-react", async () => {
   const { createElement } = await vi.importActual<typeof import("react")>("react");
   const Icon = (props: Record<string, unknown>) => createElement("svg", props);
   return {
+    IconArrowLeft: Icon,
+    IconSettings: Icon,
     IconAlertTriangle: Icon,
     IconCircleFilled: Icon,
     IconMoon: Icon,
@@ -112,6 +114,7 @@ vi.mock("@mantine/core", async () => {
     Alert: primitive("div"),
     AppShell,
     Box: primitive("div"),
+    Button: primitive("button"),
     CloseButton: primitive("button"),
     Container: primitive("div"),
     Group: primitive("div"),
@@ -168,6 +171,13 @@ test("places the filtered task count below the toolbar and updates it from live
       initialTasks={tasks}
     />,
   );
+  const headerActions = document.querySelector<HTMLElement>(".taskchef-header-actions")!;
+  const headerIconRow = within(headerActions).getByRole("link", { name: "Settings" }).parentElement?.parentElement;
+  expect(headerActions.firstElementChild).toBe(within(headerActions).getByRole("status"));
+  expect(headerActions.lastElementChild).toHaveClass("taskchef-header-icon-row");
+  expect(headerIconRow).toBe(headerActions.lastElementChild);
+  expect(within(headerActions).getByRole("link", { name: "Settings" })).toHaveClass("taskchef-icon-button");
+  expect(within(headerActions).getByRole("button", { name: "Use dark theme" })).toHaveClass("taskchef-icon-button");
   const projectFilter = screen.getByRole("combobox", { name: "Project" });
   const dateFilter = screen.getByRole("combobox", { name: "Updated" });
   const toolbar = document.querySelector<HTMLElement>(".taskchef-toolbar");

package/src/dashboard/react/App.tsx

@@ -1,8 +1,10 @@
+import { ModelSettings } from "./components/ModelSettings";
 import {
   Alert,
   ActionIcon,
   AppShell,
   Box,
+  Button,
   CloseButton,
   Container,
   Group,
@@ -18,7 +20,7 @@ import {
   useComputedColorScheme,
   useMantineColorScheme,
 } from "@mantine/core";
-import { IconAlertTriangle, IconCircleFilled, IconMoon, IconSun } from "@tabler/icons-react";
+import { IconArrowLeft, IconSettings, IconAlertTriangle, IconCircleFilled, IconMoon, IconSun } from "@tabler/icons-react";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   dismissNotification,
@@ -100,6 +102,12 @@ export function DashboardApp({
   initialFilters?: { date?: string; project?: string; status?: string };
   initialTasks?: Task[];
 }) {
+  const [settings, setSettings] = useState(() => window.location.hash === '#settings');
+  useEffect(() => {
+    const update = () => setSettings(window.location.hash === '#settings');
+    window.addEventListener('hashchange', update);
+    return () => window.removeEventListener('hashchange', update);
+  }, []);
   const [tasks, setTasks] = useState<Task[]>(initialTasks);
   const [connected, setConnected] = useState(false);
   const [message, setMessage] = useState<string | null>(null);
@@ -307,13 +315,17 @@ export function DashboardApp({
                 <IconCircleFilled aria-hidden color={connected ? "var(--mantine-color-teal-6)" : "var(--mantine-color-yellow-6)"} size={9} />
                 <Text c="dimmed" size="xs">{connected ? "Live" : connect ? "Connecting…" : "Fixture preview"}</Text>
               </Group>
-              <ThemeToggle />
+              <Group className="taskchef-header-icon-row" gap={2} justify="flex-end" wrap="nowrap">
+                <Tooltip label="Settings"><ActionIcon className="taskchef-icon-button" component="a" href="#settings" aria-label="Settings" aria-current={settings ? 'page' : undefined} variant="subtle" color="gray" size="lg"><IconSettings size={18} stroke={1.8} /></ActionIcon></Tooltip>
+                <ThemeToggle />
+              </Group>
             </Stack>
           </Group>
         </Container>
 
         <AppShell.Main>
           <Container className="taskchef-main" pb={80} size={1080}>
+            {settings ? <Stack gap="md"><Button component="a" href="#" variant="subtle" size="sm" leftSection={<IconArrowLeft size={16} />} style={{ alignSelf: 'flex-start' }}>Back to tasks</Button><ModelSettings /></Stack> : <>
             <Paper className="taskchef-toolbar" p="sm" radius="md" withBorder>
               <Stack gap="sm">
                 <Group align="end" gap="sm">
@@ -356,6 +368,7 @@ export function DashboardApp({
                 </Paper>
               )}
             </Stack>
+            </>}
           </Container>
         </AppShell.Main>
       </AppShell>
@@ -437,12 +450,13 @@ function ThemeToggle() {
     <Tooltip label={`Use ${next} theme`}>
       <ActionIcon
         aria-label={`Use ${next} theme`}
+        className="taskchef-icon-button"
         color="gray"
         onClick={() => setColorScheme(next)}
         size="lg"
         variant="subtle"
       >
-        {colorScheme === "dark" ? <IconSun aria-hidden size={18} /> : <IconMoon aria-hidden size={18} />}
+        {colorScheme === "dark" ? <IconSun aria-hidden size={18} stroke={1.8} /> : <IconMoon aria-hidden size={18} stroke={1.8} />}
       </ActionIcon>
     </Tooltip>
   );

package/src/dashboard/react/api.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, expect, test, vi } from "vitest";
 import { fixtureTask } from "./fixtures";
-import { manualTransition } from "./api";
+import { manualTransition, updateModelRole } from "./api";
 
 afterEach(() => {
   vi.useRealTimers();
@@ -22,3 +22,19 @@ test("times out a stalled manual transition and returns a retryable error", asyn
     message: "Task state change timed out. Try again.",
   });
 });
+
+test("updates a personal model role with an exact JSON request", async () => {
+  const fetchMock = vi.fn().mockResolvedValue({
+    ok: true,
+    json: async () => ({ profile: { id: "personal" } }),
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  await expect(updateModelRole("planner", "gpt-fixture", "high")).resolves.toEqual({
+    profile: { id: "personal" },
+  });
+  expect(fetchMock).toHaveBeenCalledWith("/api/settings/planner", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ schemaVersion: 1, model: "gpt-fixture", effort: "high" }),
+  });
+});

package/src/dashboard/react/api.ts

@@ -39,6 +39,14 @@ export async function dashboardVersion(): Promise<string> {
   return health.taskchefVersion;
 }
 
+export async function updateModelRole(role: string, model: string, effort: string) {
+  return jsonRequest<{ profile: unknown }>(`/api/settings/${encodeURIComponent(role)}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ schemaVersion: 1, model, effort }),
+  });
+}
+
 export async function taskDetail(taskId: string): Promise<Task> {
   return (await jsonRequest<{ task: Task }>(`/api/tasks/${encodeURIComponent(taskId)}`)).task;
 }

package/src/dashboard/react/components/ModelSettings.test.tsx

@@ -0,0 +1,100 @@
+import { MantineProvider } from '@mantine/core';
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, expect, test, vi } from 'vitest';
+import { ModelSettings } from './ModelSettings';
+
+const apiMocks = vi.hoisted(() => ({ updateModelRole: vi.fn() }));
+vi.mock('../api', () => apiMocks);
+
+vi.mock('@mantine/core', async () => {
+  const { createElement } = await import('react');
+  const block = ({ children }: { children?: import('react').ReactNode }) => createElement('div', null, children);
+  return {
+    MantineProvider: block, Tooltip: block, Badge: block, Group: block, Paper: block, SimpleGrid: block, Stack: block, Text: block, Title: block,
+    Select: ({ 'aria-busy': busy, 'aria-label': label, data = [], disabled, onChange, readOnly, value }: { 'aria-busy'?: boolean; 'aria-label': string; data?: Array<string | { value: string; label: string }>; disabled?: boolean; onChange: (value: string | null) => void; readOnly?: boolean; value: string | null }) => createElement('select', { 'aria-busy': busy, 'aria-label': label, disabled, 'aria-readonly': readOnly, value: value ?? '', onChange: (event: { currentTarget: { value: string } }) => onChange(event.currentTarget.value) }, [createElement('option', { key: '', value: '' }), ...data.map((item) => typeof item === 'string' ? createElement('option', { key: item, value: item }, item) : createElement('option', { key: item.value, value: item.value }, item.label))]),
+    Alert: ({ children }: { children?: import('react').ReactNode }) => createElement('div', { role: 'alert' }, children),
+    ActionIcon: ({ children, loading, onClick, 'aria-label': label, ...props }: { children?: import('react').ReactNode; loading?: boolean; onClick: () => void; 'aria-label': string; className?: string }) => createElement('button', { ...props, disabled: loading, onClick, 'aria-label': label }, children),
+  };
+});
+
+afterEach(() => { cleanup(); vi.unstubAllGlobals(); vi.clearAllMocks(); });
+
+test('refresh shows configuration failures and does not label them honored', async () => {
+  const role = { role: 'reviewer', source: '/fixture/reviewer.toml', effectiveSource: '/fixture/reviewer.toml', model: 'fixture', effort: 'low', status: 'configured', availability: 'not checked', fallback: 'inherit parent settings', problems: [] as string[] };
+  const profile = { id: 'personal', project: 'Personal', roles: [role], problems: [], catalogSource: null };
+  const fetchMock = vi.fn().mockResolvedValueOnce({ ok: true, json: async () => ({ profiles: [profile] }) })
+    .mockResolvedValueOnce({ ok: true, json: async () => ({ profiles: [{ ...profile, roles: [{ ...role, status: 'invalid', problems: ['Unsupported effort'] }] }] }) });
+  vi.stubGlobal('fetch', fetchMock);
+  render(<MantineProvider><ModelSettings /></MantineProvider>);
+  expect(await screen.findByText('configured')).toBeInTheDocument();
+  const refresh = screen.getByRole('button', { name: 'Refresh' });
+  expect(refresh).toHaveClass('taskchef-icon-button');
+  await waitFor(() => expect(refresh).toBeEnabled());
+  await act(async () => { fireEvent.click(refresh); });
+  expect(await screen.findByText('Unsupported effort')).toBeInTheDocument();
+  expect(screen.queryByText(/Requested effective settings/)).not.toBeInTheDocument();
+});
+
+test('request failure remains visible and can be retried', async () => {
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce({ ok: false }).mockResolvedValueOnce({ ok: true, json: async () => ({ profiles: [] }) }));
+  render(<MantineProvider><ModelSettings /></MantineProvider>);
+  expect(await screen.findByRole('alert')).toHaveTextContent('could not be loaded');
+  const refresh = screen.getByRole('button', { name: 'Refresh' });
+  await waitFor(() => expect(refresh).toBeEnabled());
+  await act(async () => { fireEvent.click(refresh); });
+  await waitFor(() => expect(screen.queryByRole('alert')).not.toBeInTheDocument());
+});
+
+
+test('non-string TOML values show diagnostics without crashing settings', async () => {
+  const role = { role: 'reviewer', source: '/fixture/reviewer.toml', model: { slug: 'bad' }, effort: ['bad'], status: 'invalid', availability: 'not checked', fallback: 'inherit parent settings', problems: ['model must be a nonempty string'] };
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, json: async () => ({ profiles: [{ id: 'personal', project: 'Personal', roles: [role], problems: [], catalogSource: null }] }) }));
+  render(<MantineProvider><ModelSettings /></MantineProvider>);
+  expect(await screen.findByText('model must be a nonempty string')).toBeInTheDocument();
+  expect(screen.getByRole('combobox', { name: 'reviewer model' })).toHaveValue('');
+  expect(screen.getByRole('combobox', { name: 'reviewer reasoning effort' })).toBeDisabled();
+});
+
+test('saves dropdown changes and displays a home-relative agent source', async () => {
+  const role = { role: 'planner', source: '/Users/example/.codex/agents/planner.toml', displaySource: '~/.codex/agents/planner.toml', model: 'gpt-one', effort: 'low', status: 'configured', problems: [] as string[] };
+  const profile = { id: 'personal', roles: [role], problems: [], modelOptions: [
+    { value: 'gpt-one', label: 'GPT One', efforts: ['low', 'high'] },
+    { value: 'gpt-two', label: 'GPT Two', efforts: ['medium'] },
+  ] };
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, json: async () => ({ profiles: [profile] }) }));
+  apiMocks.updateModelRole.mockResolvedValue({ profile: { ...profile, roles: [{ ...role, model: 'gpt-two', effort: 'medium' }] } });
+  render(<MantineProvider><ModelSettings /></MantineProvider>);
+  const model = await screen.findByRole('combobox', { name: 'planner model' });
+  fireEvent.change(model, { target: { value: 'gpt-two' } });
+  expect(model).toHaveValue('gpt-two');
+  expect(model).toHaveAttribute('aria-readonly', 'true');
+  expect(screen.queryByText('Saving…')).not.toBeInTheDocument();
+  await waitFor(() => expect(apiMocks.updateModelRole).toHaveBeenCalledWith('planner', 'gpt-two', 'medium'));
+  expect(await screen.findByText('Source: ~/.codex/agents/planner.toml')).toBeInTheDocument();
+});
+
+test('serializes role saves so an older response cannot replace a newer selection', async () => {
+  const planner = { role: 'planner', source: null, model: 'gpt-one', effort: 'low', status: 'configured', problems: [] as string[] };
+  const reviewer = { ...planner, role: 'reviewer' };
+  const profile = { id: 'personal', roles: [planner, reviewer], problems: [], modelOptions: [
+    { value: 'gpt-one', label: 'GPT One', efforts: ['low'] },
+    { value: 'gpt-two', label: 'GPT Two', efforts: ['medium'] },
+  ] };
+  let resolveFirst!: (value: { profile: typeof profile }) => void;
+  apiMocks.updateModelRole.mockReturnValueOnce(new Promise((resolve) => { resolveFirst = resolve; }));
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: true, json: async () => ({ profiles: [profile] }) }));
+  render(<MantineProvider><ModelSettings /></MantineProvider>);
+  const plannerModel = await screen.findByRole('combobox', { name: 'planner model' });
+  const reviewerModel = screen.getByRole('combobox', { name: 'reviewer model' });
+  fireEvent.change(plannerModel, { target: { value: 'gpt-two' } });
+  fireEvent.change(reviewerModel, { target: { value: 'gpt-two' } });
+  fireEvent.click(screen.getByRole('button', { name: 'Refresh' }));
+  expect(apiMocks.updateModelRole).toHaveBeenCalledTimes(1);
+  expect(apiMocks.updateModelRole).toHaveBeenCalledWith('planner', 'gpt-two', 'medium');
+  expect(fetch).toHaveBeenCalledTimes(1);
+  await act(async () => resolveFirst({ profile: { ...profile, roles: [{ ...planner, model: 'gpt-two', effort: 'medium' }, reviewer] } }));
+  await waitFor(() => expect(reviewerModel).toHaveAttribute('aria-readonly', 'false'));
+  apiMocks.updateModelRole.mockResolvedValueOnce({ profile: { ...profile, roles: [{ ...planner, model: 'gpt-two', effort: 'medium' }, { ...reviewer, model: 'gpt-two', effort: 'medium' }] } });
+  fireEvent.change(reviewerModel, { target: { value: 'gpt-two' } });
+  await waitFor(() => expect(apiMocks.updateModelRole).toHaveBeenCalledTimes(2));
+});

package/src/dashboard/react/components/ModelSettings.tsx

@@ -0,0 +1,91 @@
+import { ActionIcon, Alert, Badge, Group, Paper, Select, SimpleGrid, Stack, Text, Title } from '@mantine/core';
+import { IconRefresh } from '@tabler/icons-react';
+import { useEffect, useState } from 'react';
+import { updateModelRole } from '../api';
+
+type ModelOption = { value: string; label: string; efforts: string[] };
+type Role = { role: string; source: string | null; displaySource?: string | null; model: unknown; effort: unknown; status: string; problems: string[] };
+type Profile = { id: string; roles: Role[]; problems: string[]; modelOptions?: ModelOption[] };
+
+export function ModelSettings() {
+  const [profiles, setProfiles] = useState<Profile[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState<string | null>(null);
+  const [showSaving, setShowSaving] = useState<string | null>(null);
+  const [revision, setRevision] = useState(0);
+  useEffect(() => {
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    fetch('/api/settings', { signal: controller.signal }).then(async (response) => {
+      if (!response.ok) throw new Error('Settings preview could not be loaded.');
+      const data = await response.json() as { profiles: Profile[] };
+      setProfiles(data.profiles);
+    }).catch((failure: Error) => {
+      if (!controller.signal.aborted) setError(failure.message);
+    }).finally(() => { if (!controller.signal.aborted) setLoading(false); });
+    return () => controller.abort();
+  }, [revision]);
+  useEffect(() => {
+    setShowSaving(null);
+    if (!saving) return;
+    const timeout = window.setTimeout(() => setShowSaving(saving), 400);
+    return () => window.clearTimeout(timeout);
+  }, [saving]);
+  const profile = profiles.find((item) => item.id === 'personal');
+  const save = async (role: Role, model: string, effort: string) => {
+    setSaving(role.role);
+    setError(null);
+    setProfiles((current) => current.map((item) => item.id !== 'personal' ? item : {
+      ...item,
+      roles: item.roles.map((candidate) => candidate.role === role.role ? { ...candidate, model, effort } : candidate),
+    }));
+    try {
+      const result = await updateModelRole(role.role, model, effort) as { profile: Profile };
+      setProfiles([result.profile]);
+    } catch (failure) {
+      setProfiles((current) => current.map((item) => item.id !== 'personal' ? item : {
+        ...item,
+        roles: item.roles.map((candidate) => candidate.role === role.role ? role : candidate),
+      }));
+      setError(failure instanceof Error ? failure.message : 'Model role could not be saved.');
+    } finally {
+      setSaving(null);
+    }
+  };
+  return <Stack gap="md" aria-label="Model settings">
+    <Group justify="space-between">
+      <Title order={2} size="h3">Model roles</Title>
+      <ActionIcon aria-label="Refresh" aria-busy={loading} aria-disabled={loading || saving !== null} className="taskchef-icon-button" color="gray" variant="subtle" size="lg" onClick={() => {
+        if (loading || saving) return;
+        setLoading(true);
+        setRevision((value) => value + 1);
+      }}><IconRefresh className={loading ? 'taskchef-refresh-spinning' : undefined} size={18} stroke={1.8} /></ActionIcon>
+    </Group>
+    <Text c="dimmed" size="sm">Your models for planning, implementation, and review.</Text>
+    {error && <Alert color="red" role="alert">{error}</Alert>}
+    {profile && <>
+      {profile.problems.map((problem) => <Alert color="yellow" key={problem}>{problem}</Alert>)}
+      {profile.roles.map((role) => <Paper key={role.role} withBorder p="md">
+        <Stack gap="xs">
+          <Group justify="space-between"><Title order={3} size="h4" tt="capitalize">{role.role}</Title><Badge color={['invalid', 'unavailable'].includes(role.status) ? 'red' : role.status === 'missing' ? 'gray' : 'teal'}>{role.status}</Badge></Group>
+          <SimpleGrid cols={{ base: 1, sm: 2 }}>
+            <Select label="Model" aria-label={`${role.role} model`} aria-busy={loading || saving !== null} data={profile.modelOptions ?? []} value={typeof role.model === 'string' ? role.model : null} readOnly={loading || saving !== null} allowDeselect={false} searchable onChange={(model) => {
+              if (loading || saving || !model) return;
+              const option = profile.modelOptions?.find((candidate) => candidate.value === model);
+              const effort = typeof role.effort === 'string' && option?.efforts.includes(role.effort) ? role.effort : option?.efforts[0];
+              if (effort) void save(role, model, effort);
+            }} />
+            <Select label="Reasoning effort" aria-label={`${role.role} reasoning effort`} aria-busy={loading || saving !== null} data={(profile.modelOptions?.find((option) => option.value === role.model)?.efforts ?? []).map((value) => ({ value, label: value }))} value={typeof role.effort === 'string' ? role.effort : null} disabled={typeof role.model !== 'string'} readOnly={loading || saving !== null} allowDeselect={false} onChange={(effort) => {
+              if (!loading && !saving && effort && typeof role.model === 'string') void save(role, role.model, effort);
+            }} />
+          </SimpleGrid>
+          <Text size="sm" style={{ overflowWrap: 'anywhere' }}>Source: {role.displaySource ?? role.source ?? 'No role file'}</Text>
+          {showSaving === role.role && <Text c="dimmed" size="sm" role="status">Saving…</Text>}
+          {role.problems.map((problem) => <Alert key={problem} color="red">{problem}</Alert>)}
+        </Stack>
+      </Paper>)}
+    </>}
+  </Stack>;
+}

package/src/dashboard/react/styles.css

@@ -21,6 +21,8 @@ body {
 .taskchef-header-copy { min-width: 0; }
 .taskchef-header-actions { align-self: stretch; flex: none; }
 .taskchef-connection { align-self: flex-end; }
+.taskchef-header-icon-row { justify-content: flex-end; }
+.taskchef-icon-button { flex: none; }
 .taskchef-version { margin-inline-start: 0.45rem; color: var(--taskchef-muted); font-weight: 600; letter-spacing: 0; text-transform: none; }
 .taskchef-brand-icon, .taskchef-brand-icon img { display: block; width: 42px; height: 42px; }
 .taskchef-main { padding-top: var(--mantine-spacing-md); }
@@ -140,3 +142,16 @@ body {
   .taskchef-task-usage { text-align: left; }
   .taskchef-card-footer { align-items: flex-start; flex-direction: column; }
 }
+
+.taskchef-refresh-spinning {
+  animation: taskchef-refresh-spin 800ms linear infinite;
+  transform-origin: center;
+}
+
+@keyframes taskchef-refresh-spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .taskchef-refresh-spinning { animation: none; }
+}

package/src/dashboard.js

@@ -1,3 +1,4 @@
+import { resolveModelRoles, updateModelRole } from "./model-roles.js";
 import { EventEmitter } from "node:events";
 import { randomBytes } from "node:crypto";
 import { constants, watch } from "node:fs";
@@ -803,6 +804,8 @@ export async function createDashboardServer({
   serverVersion = DASHBOARD_SERVER_VERSION,
   usageTracker = null,
   usageSummaryMonitor = null,
+  resolveRoles = resolveModelRoles,
+  updateRole = updateModelRole,
   control = null,
   controlReplayCache = createDashboardControlReplayCache(),
 } = {}) {
@@ -1178,6 +1181,43 @@ export async function createDashboardServer({
       return;
     }
 
+    if (url.pathname === "/api/settings" && method === "GET") {
+      const profiles = [{ id: "personal", project: "Personal", ...await resolveRoles({ includeCatalog: true }) }];
+      sendJson(response, 200, { profiles });
+      return;
+    }
+
+    const settingsMatch = url.pathname.match(/^\/api\/settings\/(planner|implementer|reviewer)$/);
+    if (settingsMatch && method === "POST") {
+      if (request.headers.origin !== allowedOrigin) {
+        sendJson(response, 403, { code: "invalid_origin", message: "Dashboard origin validation failed." });
+        return;
+      }
+      try {
+        const body = await readBoundedJsonBody(request);
+        const fields = Object.keys(body);
+        if (fields.length !== 3 || body.schemaVersion !== 1
+            || typeof body.model !== "string" || typeof body.effort !== "string") {
+          const error = new Error("Model role update has an invalid shape.");
+          error.code = "invalid_request";
+          throw error;
+        }
+        const profile = await updateRole(settingsMatch[1], body.model, body.effort);
+        sendJson(response, 200, { profile: { id: "personal", project: "Personal", ...profile } });
+      } catch (error) {
+        const status = error?.code === "invalid_request" ? 400
+          : error?.code === "unsupported_media_type" ? 415
+            : error?.code === "body_too_large" ? 413 : 409;
+        sendJson(response, status, {
+          code: error?.code ?? "role_update_failed",
+          message: error?.code === "invalid_request"
+            ? "Model role update is invalid."
+            : "Model role could not be saved. Review the profile and try again.",
+        });
+      }
+      return;
+    }
+
     if (url.pathname === "/api/snapshot" && (method === "GET" || method === "HEAD")) {
       if (method === "HEAD") {
         response.writeHead(200, securityHeaders("application/json; charset=utf-8"));

package/src/mcp.js

@@ -102,6 +102,7 @@ const preparationSchema = z.object({
   taskId: z.string(),
   preparedAt: z.string(),
   marker: z.string(),
+  modelRoles: z.record(z.string(), z.unknown()).optional(),
   projectCount: z.number(),
   projects: z.array(projectSchema),
 });

package/src/model-roles.js

@@ -0,0 +1,70 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { readdir } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCallback);
+const resolver = fileURLToPath(new URL('../scripts/roles/resolve_roles.py', import.meta.url));
+
+async function hasAgentFiles(directory) {
+  try { return (await readdir(directory)).some((name) => name.endsWith('.toml')); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+function missingRoles() {
+  return {
+    roles: ['planner', 'implementer', 'reviewer'].map((role) => ({
+      role, source: null, effectiveSource: null, model: null, effort: null,
+      status: 'missing', availability: 'No role files', problems: [],
+      taskOverrides: {}, subagentOverrides: {},
+      fallback: role === 'reviewer' ? 'inherit parent settings' : 'native new-task default (not guaranteed dispatcher inheritance)',
+    })),
+    problems: [], catalogSource: null, modelOptions: [],
+    precedence: 'explicit user model (and its explicit effort) > personal role > native defaults; explicit effort alone overrides role effort',
+    scope: 'Model and effort only; agent instructions, tools, permissions, and other TOML keys are not applied by this adapter.',
+  };
+}
+
+export async function resolveModelRoles({ run = execFile, env = process.env, includeCatalog = false } = {}) {
+  try {
+    const home = env.HOME || os.homedir();
+    const codexHome = (env.CODEX_HOME || path.join(home, '.codex')).replace(/^~(?=\/|$)/, home);
+    const agentsDirectory = path.join(codexHome, 'agents');
+    if (!await hasAgentFiles(agentsDirectory) && !includeCatalog) return missingRoles();
+    const { stdout } = await run('python3', [resolver], {
+      env, timeout: 5000, maxBuffer: 128 * 1024,
+    });
+    const result = JSON.parse(stdout);
+    result.roles = result.roles.map((role) => ({
+      ...role,
+      displaySource: typeof role.source === 'string'
+        ? `~/.codex/agents/${path.basename(role.source)}`
+        : role.source,
+    }));
+    return result;
+  } catch {
+    return { roles: [], problems: ['Model role preview unavailable. Python 3.11+ and readable agent configuration are required when agent files exist; configured roles have not been honored.'], catalogSource: null };
+  }
+}
+
+export async function updateModelRole(role, model, effort, { run = execFile, env = process.env } = {}) {
+  const allowedRoles = new Set(['planner', 'implementer', 'reviewer']);
+  if (!allowedRoles.has(role) || typeof model !== 'string' || typeof effort !== 'string') {
+    const error = new Error('Invalid model role update.');
+    error.code = 'invalid_request';
+    throw error;
+  }
+  try {
+    await run('python3', [resolver, '--update', '--role', role, '--model', model, '--effort', effort], {
+      env, timeout: 5000, maxBuffer: 128 * 1024,
+    });
+    return resolveModelRoles({ run, env, includeCatalog: true });
+  } catch (error) {
+    if (error.code === 'invalid_request') throw error;
+    const failure = new Error('Model role could not be saved.');
+    failure.code = 'role_update_failed';
+    throw failure;
+  }
+}

package/src/workspace.js

@@ -1,3 +1,4 @@
+import { resolveModelRoles } from "./model-roles.js";
 import { execFile as execFileCallback } from "node:child_process";
 import {
   access,
@@ -704,6 +705,7 @@ export async function prepareDispatch(workspaceRoot, {
     marker,
     projectCount: projects.length,
     projects,
+    modelRoles: await resolveModelRoles(),
   };
 }