parallel-codex-tui 0.2.9 → 0.3.0

package/README.md

@@ -6,7 +6,9 @@ Built with Codex-assisted development.
 
 ## Current Release
 
-`v0.2.9` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.2.9) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.2.9). `Ctrl+T`, then `C`, now opens every persisted Main conversation in the workspace. Restoring one switches the exact `conversation_id`, reloads only that conversation's file-backed history, and restores its archived native Codex or Claude session ids when they are available. `Ctrl+N` still creates an explicit, durable Main conversation boundary without deleting chat, Tasks, or Worker logs.
+`v0.3.0` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.3.0) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.3.0). `Ctrl+E` opens runtime role/model control for Main, Judge, Actor, and Critic. The complete matrix can apply once to the next request, persist for retries and follow-ups in the current Task, or become the default for future requests. Provider changes reset to that profile's configured model, `M` accepts a model override, every complex Turn records the exact consumed matrix, and historical Worker/native-session identity remains unchanged.
+
+`Ctrl+T`, then `C`, opens every persisted Main conversation and provides the same durable management lifecycle as Task sessions: rename, archive, unarchive, scoped export, and confirmed deletion. Restoring one switches the exact `conversation_id`, reloads only that conversation's file-backed history, and restores its archived native Codex or Claude session ids when they are available. `Ctrl+N` creates an explicit, durable Main conversation boundary without deleting chat, Tasks, or Worker logs.
 
 A real Claude acceptance retires the first native session, inserts 16 newer records so the secret is absent from the inline transcript, then proves a fresh Claude session can read the scoped snapshot and recover it. The same live TUI presses `Ctrl+N`, verifies the replacement session is retired, starts another native session whose prompt and archive exclude the secret, and then switches between two isolated workspaces. The bounded rollover fallback remains included: every Main call rebuilds recent context from canonical `chat.jsonl`, so a fresh Agent still receives the latest dialogue inside its current scope.
 
@@ -25,7 +27,7 @@ Highlights:
 - Named Worker Providers support Codex-compatible, Claude-compatible, OpenAI-compatible, Anthropic-compatible, and custom generic commands with independent role, model, environment, permission, resume, and interactive settings.
 - Worker overview, Feature board, collaboration timeline, Task and Main conversation centers, status details, rendered Markdown/Diff/error logs, Unicode search, keyboard navigation, mouse scrolling, and configurable themes share one terminal UI system.
 
-Release acceptance includes a real three-Feature Tetris task with parallel Actor/Critic waves and final integration review. A clean `v0.2.5` task also ran Codex Judge and Actor, a buffered Claude Critic that independently executed `node --test` and `npm test`, atomic integration, and a resumed Codex Judge that independently passed all seven acceptance criteria. Real Codex and Claude probes both proved fresh and same-session resume calls; Codex fresh and resume runs executed workspace writes with root-level `-a never`, and Claude automated sessions executed safe Bash tools with `auto` permissions. The semantic Router completed a live classification, and one TUI completed Main calls in two workspaces before restoring the first workspace without leaking chat state. PTY coverage runs in Apple Terminal, tmux, and Zellij profiles at narrow and wide sizes, including status/log equivalence, preserving the native output tail across status-detail round trips, and proving both inline and on-demand file memory after native-session rollover. The deterministic repository suite contains 1,305 tests across 129 files: 1,304 pass by default, while one quota-consuming real-Agent test is skipped and passes through `npm run test:real-agents`.
+Release acceptance includes a real three-Feature Tetris task with parallel Actor/Critic waves and final integration review. A clean `v0.2.5` task also ran Codex Judge and Actor, a buffered Claude Critic that independently executed `node --test` and `npm test`, atomic integration, and a resumed Codex Judge that independently passed all seven acceptance criteria. Real Codex and Claude probes both proved fresh and same-session resume calls; Codex fresh and resume runs executed workspace writes with root-level `-a never`, and Claude automated sessions executed safe Bash tools with `auto` permissions. The semantic Router completed a live classification, and one TUI completed Main calls in two workspaces before restoring the first workspace without leaking chat state. PTY coverage runs in Apple Terminal, tmux, and Zellij profiles at narrow and wide sizes, including status/log equivalence, preserving the native output tail across status-detail round trips, and proving both inline and on-demand file memory after native-session rollover. The deterministic repository suite contains 1,334 tests across 136 files: 1,333 pass by default, while one quota-consuming real-Agent test is skipped and passes through `npm run test:real-agents`.
 
 Real Provider probes depend on valid local CLI credentials. In particular, authenticate the Claude CLI before selecting a Claude-compatible Worker, then run `parallel-codex-tui --doctor --probe-agents` to prove fresh and resumed calls on that machine.
 
@@ -414,7 +416,19 @@ actor = "openai_compat"
 critic = "anthropic_compat"
 ```
 
-`extends` inherits the complete command protocol, including capabilities, native-session behavior, watchdogs, and interactive arguments. Override both `command` and `interactive.command` when a wrapper replaces both executables. `assignable = true` exposes a profile to Feature-level Provider cycling; custom profiles default to true, while the reserved deterministic `mock` profile defaults to false. Pairing an unknown profile, unsafe profile IDs, and inheritance cycles fail config validation before startup.
+`extends` inherits the complete command protocol, including capabilities, native-session behavior, watchdogs, and interactive arguments. Override both `command` and `interactive.command` when a wrapper replaces both executables. `assignable = true` exposes a profile to runtime role and Feature-level Provider cycling; custom profiles default to true, while the reserved deterministic `mock` profile defaults to false. A role that is already configured with a nonassignable profile can still display it and cycle away from it. Pairing an unknown profile, unsafe profile IDs, and inheritance cycles fail config validation before startup.
+
+## Runtime Role Control
+
+While the TUI is idle, press `Ctrl+E` to configure Main, Judge, Actor, and Critic without editing TOML or restarting. Up/Down selects a role, Left/Right (or `[`/`]`) cycles its configured Worker Provider, `M` edits the model name with a Unicode-safe cursor, and `Tab` changes the persistence scope. Press Enter to apply the complete matrix, `X` to clear the saved override and inherit its parent scope, `R` to discard unsaved edits, and `Esc` or `Ctrl+E` to return. `Ctrl+Y` copies the visible matrix. A Provider switch resets that role to the Provider's configured default model; a blank model edit also means the Provider default.
+
+The three scopes are explicit:
+
+- `next request` is stored in the current workspace at `.parallel-codex/role-configuration.next.json`, overrides every role once, and is removed only when a routed request consumes it.
+- `current task` is stored beside that Task's `meta.json`, applies to retries and same-Task follow-ups, and updates unfinished Feature assignments without deleting earlier Workers or logs.
+- `future requests` is stored in the app root at `.parallel-codex/role-configuration.json` and becomes the default for new Main calls and Tasks across restarts.
+
+Every complex Turn writes the exact consumed matrix to `turns/<turn>/role-configuration.json`. Retries use that evidence instead of silently adopting a pending one-shot selection, native attach uses the selected Worker's persisted Provider/model, and status details show the active Turn matrix separately from historical Worker identity.
 
 For a third-party command with its own syntax, inherit `generic` so parallel-codex-tui does not inject `--sandbox`, `--permission-mode`, or other built-in-only flags:
 
@@ -457,7 +471,7 @@ Keep `[router.codex]` on `read-only`; routing only classifies requests and does
 
 The process adapter sends each role prompt to stdin and records stdout/stderr in `output.log`. Worker success is separate from the operating-system exit code: a total, first-output, idle, or stdin watchdog failure remains failed even when the terminated CLI handles `SIGTERM` and exits with code `0`, so the next role never starts from a timed-out checkpoint. `firstOutputTimeoutMs` owns silent startup, `idleTimeoutMs` starts only after real stdout/stderr activity, and `timeoutMs` remains the hard ceiling; equal or longer secondary watchdogs do not race the total deadline. Claude `--print` with `text` or `json` emits only its final result, so those launches display `working · buffered` and use `timeoutMs` without arming a separate first-output watchdog. Claude `stream-json` remains streaming and retains the configured first-output deadline.
 
-In chat, scroll long conversation history with the mouse wheel or PageUp/PageDown; sending a new message returns to the latest reply. A single Up/Down recalls persisted request history, and Ctrl+Up/Down remains an alternative. The outer TUI never enables application mouse tracking, so ordinary left-drag selection and system copy work without Shift while alternate-scroll keeps the wheel active in chat and Worker logs. `Ctrl+Y` also copies the current visible chat, rendered Worker log, native Agent screen, or structured overview without changing terminal modes. macOS uses `pbcopy`; Linux uses `wl-copy`, `xclip`, or `xsel` when available and falls back to OSC 52. After a complex task completes, use the same controls to move through its structured result and press `Ctrl+D` to toggle details. Press `Ctrl+N` to preserve all history and start a fresh conversation, `Ctrl+W` to open Worker logs, and `Tab` to cycle the selected Worker when Workers exist. `Ctrl+S` opens the same status detail view from chat, logs, Worker overview, or an embedded native session; it keeps the footer compact while exposing the complete route, reason, active Main/Judge/Actor/Critic Provider map, selected historical Provider/model, phase, activity timestamp, native session, and config effective/restart state. Press `Ctrl+S` or `Esc` to return without interrupting the underlying Worker. While a request is running, press `Esc` to stop it. After a failed or cancelled Task, press `Ctrl+R` to retry the same turn or `Ctrl+N` to start independently. In Worker-log views, scroll with the mouse wheel, Up/Down, or PageUp/PageDown, press `Tab` to cycle Workers, `Ctrl+N` to start a fresh conversation, and `Esc` to return to chat.
+In chat, scroll long conversation history with the mouse wheel or PageUp/PageDown; sending a new message returns to the latest reply. A single Up/Down recalls persisted request history, and Ctrl+Up/Down remains an alternative. The outer TUI never enables application mouse tracking, so ordinary left-drag selection and system copy work without Shift while alternate-scroll keeps the wheel active in chat and Worker logs. `Ctrl+Y` also copies the current visible chat, rendered Worker log, native Agent screen, or structured overview without changing terminal modes. macOS uses `pbcopy`; Linux uses `wl-copy`, `xclip`, or `xsel` when available and falls back to OSC 52. After a complex task completes, use the same controls to move through its structured result and press `Ctrl+D` to toggle details. Press `Ctrl+N` to preserve all history and start a fresh conversation, `Ctrl+E` to open runtime role/model control, `Ctrl+W` to open Worker logs, and `Tab` to cycle the selected Worker when Workers exist. `Ctrl+S` opens the same status detail view from chat, logs, Worker overview, or an embedded native session; it keeps the footer compact while exposing the complete route, reason, active Main/Judge/Actor/Critic Provider/model map, selected historical Provider/model, phase, activity timestamp, native session, and config effective/restart state. Press `Ctrl+S` or `Esc` to return without interrupting the underlying Worker. While a request is running, press `Esc` to stop it. After a failed or cancelled Task, press `Ctrl+R` to retry the same turn or `Ctrl+N` to start independently. In Worker-log views, scroll with the mouse wheel, Up/Down, or PageUp/PageDown, press `Tab` to cycle Workers, `Ctrl+N` to start a fresh conversation, and `Esc` to return to chat.
 
 `Ctrl+B` opens a live Worker overview without replacing the `Ctrl+W` log shortcut. It summarizes every Judge, Actor, and Critic by turn, role, named Provider, persisted model, state, phase, latest summary, and native-session availability. The selected active worker gets a live activity line showing its first-output deadline while starting and its idle deadline after output begins. The line stays muted while healthy, changes to warning for the final 20% and danger once overdue. Up/Down, PageUp/PageDown, the mouse wheel, or `Tab` changes the selected worker; Enter or `Ctrl+W` opens its rendered log, `Ctrl+O` attaches to its native session, and `Esc` returns to the originating chat or log view. Router diagnostics and the project picker also return to the overview when opened from there.
 
@@ -469,7 +483,7 @@ From Worker overview, press `C` to open the file-backed Actor/Critic collaborati
 
 `Ctrl+T` opens the workspace's persisted Task sessions without exiting the outer TUI. The list shows status, creation time, turn and Worker counts, plus the number of distinct native sessions after deduplicating reused `engine + session_id` bindings; `>` marks the selected row and `*` marks the active Task. Use Up/Down, PageUp/PageDown, the mouse wheel, or `Tab` to select, Enter to restore, `C` to open Main conversations, `I` to inspect the complete session hierarchy, `R` to rename with Unicode-safe cursor editing, `A` to archive or unarchive, `D` twice to confirm deletion, `E` to export, `H` to show or hide archived sessions, `Ctrl+N` to leave the active Task and start a fresh Main conversation, and `Esc` to return without losing the chat draft. Archived sessions are hidden by default, cannot be restored until unarchived, and are excluded from automatic startup selection. Archive, delete, and export require a terminal Task with no live task lease; the active Task cannot be archived or deleted. Exports are complete file-backed snapshots under `.parallel-codex/exports/<task>-<timestamp>/` with a versioned manifest and without transient lease files. Restoring a Task reloads its route, Workers, retry state, and recorded native session ids. The selected active Task is stored in `session-index.sqlite` and survives process and workspace switches; `Ctrl+N` persists an intentionally empty active-Task context instead of reopening an older Task on restart. SQLite schema changes run as ordered, transactional migrations. Existing catalogs receive a pre-migration snapshot, each successful startup/reindex refreshes a healthy backup, and an integrity failure restores that backup or rebuilds the catalog from authoritative Task files while preserving the corrupt copy for inspection. `meta.json` and the Worker files remain the rebuild authority.
 
-The Main conversation list shows each scoped title, message count, distinct native session count, last activity, current `*` marker, and selected `>` marker. Use the same Up/Down, PageUp/PageDown, mouse-wheel, or `Tab` navigation; Enter restores the selected conversation, `N` starts a new one, `T` returns to Tasks, and `Esc` returns to chat. Restoration preserves every Task and Worker log, switches `conversation.json`, and rebuilds Main history from records carrying only the selected `conversation_id` (or the pre-boundary legacy scope). Before switching, active Main native sessions are archived and retired; archived bindings for the selected conversation are then restored for best-effort native resume. A brand-new empty legacy scope is not added to the catalog.
+The Main conversation list shows each scoped title, message count, distinct native session count, last activity, current `*` marker, and selected `>` marker. Use the same Up/Down, PageUp/PageDown, mouse-wheel, or `Tab` navigation; Enter restores the selected conversation, `R` renames it with Unicode-safe cursor editing, `A` archives or unarchives it, `D` twice confirms deletion, `E` exports it, `H` shows or hides archived conversations, `N` starts a new one, `T` returns to Tasks, and `Esc` returns to chat. Archived conversations are hidden by default and cannot be restored until unarchived; the current Main conversation cannot be archived or deleted. A Main export is a versioned, conversation-scoped snapshot under `.parallel-codex/exports/<conversation>-<timestamp>/` containing only that conversation's chat rows and matching native sessions. Confirmed deletion streams the shared chat JSONL into an atomic replacement, preserves Task chat and malformed evidence, and restores the original chat and conversation archive if publication fails. Restoration preserves every Task and Worker log, switches `conversation.json`, and rebuilds Main history from records carrying only the selected `conversation_id` (or the pre-boundary legacy scope). Before switching, active Main native sessions are archived and retired; archived bindings for the selected conversation are then restored for best-effort native resume. A brand-new empty legacy scope is not added to the catalog.
 
 The Task detail view reads authoritative task files and presents `Project -> Task -> Turn -> Worker -> Native session`, including each request, role, engine, configured model, Worker state, native session id, working directory, and last activity time. Historical Workers from earlier turns remain selectable after same-task follow-ups. Use Up/Down or `Tab` to select a Worker, Enter to open its retained log, `C` or `Ctrl+O` to continue the original native session, `B` to ask the native CLI to fork it, `R` to refresh, and `Esc` to return to the Task list. Continue and fork restore the selected Worker's recorded cwd and writable roots while the outer TUI stays open. Codex and Claude have built-in fork commands; a generic CLI exposes `B` only when `interactive.forkArgs` is configured. The child fork is owned and persisted by the native CLI; the indexed parent session remains unchanged.
 
@@ -523,16 +537,17 @@ The release job installs npm `^11.5.1`, runs on Node `24.15.x`, publishes the pr
 To publish a release, update `package.json` and `src/version.ts` to the same version, then push a matching tag:
 
 ```bash
-VERSION=0.2.9
+VERSION=0.3.0
 git tag "v$VERSION"
 git push origin "v$VERSION"
 ```
 
-You can also run the Release workflow manually and enter the same tag value. The release tag must match `package.json`; for example, package version `0.2.9` requires tag `v0.2.9`. Published tags such as `v0.2.8` are immutable and must not be moved or reused.
+You can also run the Release workflow manually and enter the same tag value. The release tag must match `package.json`; for example, package version `0.3.0` requires tag `v0.3.0`. Published tags such as `v0.2.10` are immutable and must not be moved or reused.
 
 ## Publishing Hygiene
 
 - `.parallel-codex/config.toml` is local-only and ignored.
+- `.parallel-codex/role-configuration.json` and `.parallel-codex/role-configuration.next.json` are local runtime role/model selections and are ignored.
 - `.parallel-codex/last-workspace` and `.parallel-codex/workspaces.json` are local workspace-selection state and are ignored.
 - `.parallel-codex/router/` contains local request classification audit records and is ignored.
 - `.parallel-codex/sessions/` contains the workspace chat transcript, task prompts, logs, native session ids, isolated feature workspaces, and conflict evidence; never commit it.

package/dist/bootstrap.js

@@ -2,6 +2,7 @@ import { prepareAppRoot } from "./core/app-root.js";
 import { configPath, loadConfig, writeDefaultConfig } from "./core/config.js";
 import { ensureDir, pathExists } from "./core/file-store.js";
 import { routerRuntimeDir } from "./core/paths.js";
+import { RoleConfigurationManager } from "./core/role-configuration.js";
 import { SessionIndex } from "./core/session-index.js";
 import { SessionManager } from "./core/session-manager.js";
 import { prepareWorkspace } from "./core/workspace.js";
@@ -25,13 +26,18 @@ export async function createRuntime(appRoot, workspaceRoot = appRoot) {
             dataDir: config.dataDir,
             index
         });
+        const roleConfiguration = await RoleConfigurationManager.open({
+            config,
+            appRoot,
+            workspaceRoot: preparedWorkspace
+        });
         const pendingTaskCreations = await sessions.reconcilePendingTaskCreations();
         const workspaceCommitRecovery = await reconcileWorkspaceCommitIntents(preparedWorkspace, config.dataDir);
         await sessions.reconcileInterruptedMainSession();
         await sessions.reconcileNativeSessionState();
         const recoveredTasks = await sessions.reconcileInterruptedTasks();
         const workers = createWorkerRegistry(config);
-        const orchestrator = new Orchestrator(config, sessions, workers, undefined, routerCwd, async () => (await loadConfig(appRoot)).router);
+        const orchestrator = new Orchestrator(config, sessions, workers, undefined, routerCwd, async () => (await loadConfig(appRoot)).router, { roleConfiguration });
         return {
             config,
             workspaceRoot: preparedWorkspace,
@@ -40,6 +46,7 @@ export async function createRuntime(appRoot, workspaceRoot = appRoot) {
             sessions,
             workers,
             orchestrator,
+            roleConfiguration,
             pendingTaskCreations,
             workspaceCommitRecovery,
             recoveredTasks

package/dist/cli.js

@@ -16,6 +16,7 @@ import { configPath, loadConfig, withUiThemeOverride, writeDefaultConfig } from
 import { pathExists } from "./core/file-store.js";
 import { exportDiagnostics } from "./core/diagnostics.js";
 import { readRouterAudit } from "./core/router-audit.js";
+import { RoleConfigurationManager } from "./core/role-configuration.js";
 import { inheritMacSystemProxy } from "./core/system-proxy.js";
 import { loadTaskSessionDetails as loadPersistedTaskSessionDetails } from "./core/task-session-details.js";
 import { listWorkspaceChoices } from "./core/workspace.js";
@@ -127,11 +128,17 @@ async function main() {
                     records,
                     policy: routerDiagnosticsPolicy(latestConfig.router)
                 };
-            }, loadTaskSessions: (options) => state.runtime.index.listTasks(100, options), loadMainConversations: () => state.runtime.sessions.listMainConversations(100), activateMainConversation: async (conversationId) => {
+            }, loadTaskSessions: (options) => state.runtime.index.listTasks(100, options), loadMainConversations: (options) => state.runtime.sessions.listMainConversations(100, options), activateMainConversation: async (conversationId) => {
                 const restored = await state.runtime.sessions.activateMainConversation(conversationId);
                 await state.runtime.index.setActiveTaskId(null);
                 return restored;
-            }, loadTaskSessionDetails: (task) => loadPersistedTaskSessionDetails({
+            }, renameMainConversation: async (conversationId, title) => {
+                await state.runtime.sessions.renameMainConversation(conversationId, title);
+            }, setMainConversationArchived: async (conversationId, archived) => {
+                await state.runtime.sessions.setMainConversationArchived(conversationId, archived);
+            }, deleteMainConversation: async (conversationId) => {
+                await state.runtime.sessions.deleteMainConversation(conversationId);
+            }, exportMainConversation: async (conversationId) => (await state.runtime.sessions.exportMainConversation(conversationId)).path, loadTaskSessionDetails: (task) => loadPersistedTaskSessionDetails({
                 task,
                 taskDir: state.runtime.sessions.taskFromId(task.id).dir,
                 modelNames: Object.fromEntries(Object.entries(state.runtime.config.workers).map(([id, worker]) => [id, worker.model.name]))
@@ -185,7 +192,15 @@ async function main() {
             }, persistChatMessage: (message, taskId) => state.runtime.sessions.appendChatMessage({
                 ...message,
                 taskId
-            }), reloadConfig: async () => withUiThemeOverride(await loadConfig(cliArgs.appRoot), cliArgs.theme) }, state.runtime.workspaceRoot));
+            }), reloadConfig: async () => {
+                const latest = await loadConfig(cliArgs.appRoot);
+                await RoleConfigurationManager.open({
+                    config: latest,
+                    appRoot: cliArgs.appRoot,
+                    workspaceRoot: state.runtime.workspaceRoot
+                });
+                return withUiThemeOverride(latest, cliArgs.theme);
+            } }, state.runtime.workspaceRoot));
         const removeSigintHandler = installInteractiveSigintExitHandler(() => shutdownController.abort());
         enterInteractiveTerminal();
         try {

package/dist/core/role-configuration.js

@@ -0,0 +1,238 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { pathExists, readJson, removeIfExists, writeJson } from "./file-store.js";
+import { EngineNameSchema } from "../domain/schemas.js";
+export const CONFIGURABLE_ROLES = ["main", "judge", "actor", "critic"];
+const RoleExecutionTargetSchema = z.object({
+    engine: EngineNameSchema,
+    model: z.string().max(200)
+}).strict();
+const RoleExecutionSelectionSchema = z.object({
+    main: RoleExecutionTargetSchema,
+    judge: RoleExecutionTargetSchema,
+    actor: RoleExecutionTargetSchema,
+    critic: RoleExecutionTargetSchema
+}).strict();
+const RoleConfigurationFileSchema = z.object({
+    version: z.literal(1),
+    updated_at: z.string().datetime(),
+    roles: RoleExecutionSelectionSchema
+}).strict();
+export class RoleConfigurationManager {
+    config;
+    appRoot;
+    workspaceRoot;
+    baselineSelection;
+    futureSelection;
+    constructor(config, appRoot, workspaceRoot, baselineSelection, futureSelection) {
+        this.config = config;
+        this.appRoot = appRoot;
+        this.workspaceRoot = workspaceRoot;
+        this.baselineSelection = baselineSelection;
+        this.futureSelection = cloneRoleSelection(futureSelection);
+        applyRoleEngines(this.config, futureSelection);
+    }
+    static async open(input) {
+        const baseline = configuredRoleSelection(input.config);
+        const futurePath = roleFutureConfigurationPath(input.appRoot, input.config.dataDir);
+        const persisted = await readRoleConfigurationIfValid(futurePath, input.config);
+        return new RoleConfigurationManager(input.config, input.appRoot, input.workspaceRoot, baseline, persisted ?? baseline);
+    }
+    static transient(config) {
+        const baseline = configuredRoleSelection(config);
+        return new RoleConfigurationManager(config, config.projectRoot, config.projectRoot, baseline, baseline);
+    }
+    async snapshot(taskDir) {
+        const [next, task, activeTurn] = await Promise.all([
+            readRoleConfigurationIfValid(this.nextPath(), this.config),
+            taskDir ? readRoleConfigurationIfValid(roleTaskConfigurationPath(taskDir), this.config) : null,
+            taskDir ? this.readLatestTurnSelection(taskDir) : null
+        ]);
+        return {
+            baseline: cloneRoleSelection(this.baselineSelection),
+            future: cloneRoleSelection(this.futureSelection),
+            next,
+            task,
+            activeTurn,
+            providers: roleProviderOptions(this.config)
+        };
+    }
+    async apply(scope, roles, taskDir) {
+        const parsed = parseRoleSelection(roles, this.config);
+        if (scope === "future") {
+            await writeRoleConfiguration(this.futurePath(), parsed);
+            this.futureSelection = cloneRoleSelection(parsed);
+            applyRoleEngines(this.config, parsed);
+            return;
+        }
+        if (scope === "next") {
+            await writeRoleConfiguration(this.nextPath(), parsed);
+            return;
+        }
+        if (!taskDir) {
+            throw new Error("No active Task is available for a current-task role configuration.");
+        }
+        await writeRoleConfiguration(roleTaskConfigurationPath(taskDir), parsed);
+    }
+    async clear(scope, taskDir) {
+        if (scope === "future") {
+            await removeIfExists(this.futurePath());
+            this.futureSelection = cloneRoleSelection(this.baselineSelection);
+            applyRoleEngines(this.config, this.futureSelection);
+            return;
+        }
+        if (scope === "next") {
+            await removeIfExists(this.nextPath());
+            return;
+        }
+        if (!taskDir) {
+            throw new Error("No active Task is available for a current-task role configuration.");
+        }
+        await removeIfExists(roleTaskConfigurationPath(taskDir));
+    }
+    async selectionForRequest(taskDir) {
+        const taskSelection = await this.selectionForTask(taskDir);
+        const next = await readRoleConfigurationIfValid(this.nextPath(), this.config);
+        if (next) {
+            await removeIfExists(this.nextPath());
+            return next;
+        }
+        return taskSelection;
+    }
+    async selectionForTask(taskDir) {
+        const taskSelection = taskDir
+            ? await readRoleConfigurationIfValid(roleTaskConfigurationPath(taskDir), this.config)
+            : null;
+        return cloneRoleSelection(taskSelection ?? this.futureSelection);
+    }
+    async writeTurnSelection(turnDir, roles) {
+        await writeRoleConfiguration(roleTurnConfigurationPath(turnDir), parseRoleSelection(roles, this.config));
+    }
+    async readTurnSelection(turnDir) {
+        return readRoleConfigurationIfValid(roleTurnConfigurationPath(turnDir), this.config);
+    }
+    async modelForTurn(turnDir, role, engine) {
+        const selection = await this.readTurnSelection(turnDir);
+        const target = selection?.[role];
+        return roleModelConfiguration(this.config, target?.engine === engine ? target : { engine, model: "" });
+    }
+    modelForTarget(target) {
+        return roleModelConfiguration(this.config, target);
+    }
+    futureRoles() {
+        return cloneRoleSelection(this.futureSelection);
+    }
+    baselineRoles() {
+        return cloneRoleSelection(this.baselineSelection);
+    }
+    futurePath() {
+        return roleFutureConfigurationPath(this.appRoot, this.config.dataDir);
+    }
+    nextPath() {
+        return roleNextConfigurationPath(this.workspaceRoot, this.config.dataDir);
+    }
+    async readLatestTurnSelection(taskDir) {
+        const turnsDir = join(taskDir, "turns");
+        if (!(await pathExists(turnsDir))) {
+            return null;
+        }
+        const entries = await readdir(turnsDir, { withFileTypes: true });
+        const latest = entries
+            .filter((entry) => entry.isDirectory() && /^\d{4}$/.test(entry.name))
+            .map((entry) => entry.name)
+            .sort()
+            .at(-1);
+        return latest
+            ? readRoleConfigurationIfValid(roleTurnConfigurationPath(join(turnsDir, latest)), this.config)
+            : null;
+    }
+}
+export function configuredRoleSelection(config) {
+    return Object.fromEntries(CONFIGURABLE_ROLES.map((role) => {
+        const engine = config.pairing[role];
+        return [role, {
+                engine,
+                model: config.workers[engine]?.model.name ?? ""
+            }];
+    }));
+}
+export function roleSelectionWithEngines(route, roles) {
+    return {
+        ...cloneRoleSelection(roles),
+        judge: roleTargetForEngine(roles.judge, route.judge_engine),
+        actor: roleTargetForEngine(roles.actor, route.actor_engine),
+        critic: roleTargetForEngine(roles.critic, route.critic_engine)
+    };
+}
+export function roleTargetForEngine(target, engine) {
+    return target.engine === engine ? { ...target } : { engine, model: "" };
+}
+export function cloneRoleSelection(roles) {
+    return {
+        main: { ...roles.main },
+        judge: { ...roles.judge },
+        actor: { ...roles.actor },
+        critic: { ...roles.critic }
+    };
+}
+export function roleFutureConfigurationPath(appRoot, dataDir) {
+    return join(appRoot, dataDir, "role-configuration.json");
+}
+export function roleNextConfigurationPath(workspaceRoot, dataDir) {
+    return join(workspaceRoot, dataDir, "role-configuration.next.json");
+}
+export function roleTaskConfigurationPath(taskDir) {
+    return join(taskDir, "role-configuration.json");
+}
+export function roleTurnConfigurationPath(turnDir) {
+    return join(turnDir, "role-configuration.json");
+}
+async function readRoleConfigurationIfValid(path, config) {
+    if (!(await pathExists(path))) {
+        return null;
+    }
+    const parsed = await readJson(path, RoleConfigurationFileSchema);
+    return parseRoleSelection(parsed.roles, config);
+}
+async function writeRoleConfiguration(path, roles) {
+    await writeJson(path, RoleConfigurationFileSchema.parse({
+        version: 1,
+        updated_at: new Date().toISOString(),
+        roles
+    }));
+}
+function parseRoleSelection(roles, config) {
+    const parsed = RoleExecutionSelectionSchema.parse(roles);
+    for (const role of CONFIGURABLE_ROLES) {
+        if (!config.workers[parsed[role].engine]) {
+            throw new Error(`Worker provider is not configured: ${parsed[role].engine}`);
+        }
+    }
+    return cloneRoleSelection(parsed);
+}
+function roleProviderOptions(config) {
+    return Object.entries(config.workers)
+        .map(([id, provider]) => ({
+        id,
+        model: provider.model.name,
+        modelProvider: provider.model.provider,
+        assignable: provider.assignable
+    }))
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+function roleModelConfiguration(config, target) {
+    const worker = config.workers[target.engine];
+    if (!worker) {
+        throw new Error(`Worker provider is not configured: ${target.engine}`);
+    }
+    return {
+        ...worker.model,
+        name: target.model.trim() || worker.model.name
+    };
+}
+function applyRoleEngines(config, roles) {
+    for (const role of CONFIGURABLE_ROLES) {
+        config.pairing[role] = roles[role].engine;
+    }
+}