parallel-codex-tui 0.2.10 → 0.3.1

package/README.md

@@ -6,13 +6,17 @@ Built with Codex-assisted development.
 
 ## Current Release
 
-`v0.2.10` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.2.10) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.2.10). `Ctrl+T`, then `C`, opens every persisted Main conversation and now 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` still creates an explicit, durable Main conversation boundary without deleting chat, Tasks, or Worker logs.
+`v0.3.1` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.3.1) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.3.1). `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. Saving now validates every selected Provider before it writes configuration, and concurrent TUI instances atomically consume a one-shot matrix exactly once.
+
+Feature assignment now controls both Provider and model. From a retryable Feature, press `M`, use `A`/`C` to cycle the Actor/Critic Provider, and use `1`/`2` to edit the Actor/Critic model. A model change starts a distinct Worker identity, keeps all earlier logs and native sessions, and remains an explicit Feature override when Task defaults change. Status details show separate `actual`, `next`, and `future` role matrices alongside the selected historical Worker's persisted model.
+
+`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.
 
 Complex task memory now retains the root Turn plus the latest 19 previous Turn summaries within a 12,000-character budget. When a longer task omits intermediate summaries inline, the prompt points the Worker to the complete immutable Turn history on disk. Main chat still extracts only the final Codex answer while retaining the complete CLI transcript in `output.log`; legacy transcript-shaped chat records are cleaned when displayed without rewriting their file-backed evidence. Workspace integration ignores known host metadata such as `.DS_Store` and AppleDouble files while continuing to reject real concurrent project edits.
 
-The default role map is Main/Judge/Actor on Codex and Critic on Claude. Status details show the complete active role map separately from each historical Worker's persisted Provider/model. Config monitoring labels Router-only edits as active on the next request and marks role, Worker, model, permission, or UI changes as requiring restart. Claude text/JSON print runs are recognized as buffered work, use the total deadline instead of a false first-output deadline, and run safe isolated tools through non-interactive `auto` permissions. The `v0.2.4` non-interactive Codex permission placement remains included. The release keeps terminal scrolling and copying available at the same time without requiring Shift and preserves the embedded native Agent scrollback across status-detail round trips and real PTY resizes.
+The default role map is Main/Judge/Actor on Codex and Critic on Claude. Status details show the actual, next, and future role maps separately from each historical Worker's persisted Provider/model. Config monitoring labels Router-only edits as active on the next request and marks role, Worker, model, permission, or UI changes as requiring restart. Claude text/JSON print runs are recognized as buffered work, use the total deadline instead of a false first-output deadline, and run safe isolated tools through non-interactive `auto` permissions. The `v0.2.4` non-interactive Codex permission placement remains included. The release keeps terminal scrolling and copying available at the same time without requiring Shift and preserves the embedded native Agent scrollback across status-detail round trips and real PTY resizes.
 
 Highlights:
 
@@ -25,7 +29,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,311 tests across 130 files: 1,310 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,338 tests across 136 files: 1,337 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 +418,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 validate every selected CLI, environment, capability contract, and proxy before saving the complete matrix. `X` clears the saved override and inherits its parent scope, `R` discards unsaved edits, and `Esc` or `Ctrl+E` returns. `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 one routed request atomically claims it. Concurrent TUI instances cannot both consume it.
+- `current task` is stored beside that Task's `meta.json`, applies to retries and same-Task follow-ups, and updates inherited unfinished Feature assignments without deleting earlier Workers or logs. Explicit Feature overrides remain unchanged.
+- `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 actual Turn, next-request, and future-default matrices 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,13 +473,13 @@ 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.
 
 From Worker overview, press `F` to open the file-backed Feature board. It summarizes every planned feature by turn, state, blocked dependencies and open Critic findings while preserving descriptions and Actor replies from the same collaboration files. Use Up/Down, PageUp/PageDown, the mouse wheel, or `Tab` to select a feature; Enter opens the selected feature's collaboration timeline; `R` refreshes immediately; and `Esc` returns to Worker overview. When a timeline was opened from this board, `Esc` returns to the Feature board instead of skipping back to Workers. While the selected feature is running, press `P` twice to pause only its active Actor or Critic process, or press `X` twice to cancel it; the first press opens a confirmation and `Esc` keeps it running. A paused feature preserves completed peers and same-wave checkpoints; select it and press `Ctrl+R` to resume the same task, turn, and native Worker session. After cancellation, already-running peers finish, queued workers stop, and integration remains blocked, so a partial wave never reaches the live workspace. Once the task settles as cancelled, `Ctrl+R` retries the cancelled task with persisted worker sessions; completed peers are loaded from their same-wave checkpoints instead of running again. Checkpoint load, reuse, and recovery events appear in the collaboration timeline.
 
-For a failed, cancelled, or paused task, select an unfinished Feature and press `M` to edit its Provider assignment. `A` cycles that Feature's Actor through every `assignable` Worker Provider, `C` cycles its Critic, and `M` or `Esc` closes the assignment prompt. The choice is persisted in `features/<turn>-<feature>/assignment.json`, appears on the Feature board and collaboration artifacts, and takes effect on the next `Ctrl+R` retry. A changed role starts a new Provider-specific Worker while every previous Worker log and native-session record remains available. Assignment writes hold the same task lease as execution, so another live TUI cannot change a Feature while it is resuming.
+For a failed, cancelled, or paused task, select an unfinished Feature and press `M` to edit its assignment. `A` cycles that Feature's Actor through every `assignable` Worker Provider, `C` cycles its Critic, `1` edits the Actor model, `2` edits the Critic model, and `M` or `Esc` closes the prompt. The choice is persisted in `features/<turn>-<feature>/assignment.json`, appears on the Feature board and collaboration artifacts, and takes effect on the next `Ctrl+R` retry. A changed Provider or model starts a distinct Worker while every previous Worker log and native-session record remains available. Feature overrides survive later Task-default changes. Assignment writes hold the same task lease as execution, so another live TUI cannot change a Feature while it is resuming.
 
 From Worker overview, press `C` to open the file-backed Actor/Critic collaboration timeline. It merges `dialogue/actor-critic.jsonl`, feature status, Critic findings, Actor replies, finding resolution, and Wave events into one chronological view. The timeline follows new file evidence automatically and shows verified `fixed`/`open` counts when resolution evidence exists. Up/Down selects a collaboration event; `Enter` opens its complete event detail, including artifact paths from dialogue, status, Critic findings, Actor replies, and finding resolution; `U` filters to unresolved feature evidence; `Tab` cycles all features and each individual feature; `R` refreshes immediately; the mouse wheel or PageUp/PageDown scrolls history; and `Esc` returns to Worker overview.
 
@@ -523,16 +539,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.10
+VERSION=0.3.1
 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.10` requires tag `v0.2.10`. Published tags such as `v0.2.9` 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.1` requires tag `v0.3.1`. 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";
@@ -191,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/collaboration-timeline.js

@@ -133,7 +133,9 @@ async function readCollaborationFeatures(taskDir) {
             updatedAt: status.updated_at,
             ...(assignment ? {
                 actorEngine: assignment.actor_engine,
-                criticEngine: assignment.critic_engine
+                criticEngine: assignment.critic_engine,
+                actorModel: assignment.actor_model,
+                criticModel: assignment.critic_model
             } : {}),
             findings: findingEvidence.count,
             replies: replyEvidence.count,

package/dist/core/role-configuration.js

@@ -0,0 +1,277 @@
+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 { claimTaskRunLease, TaskRunLeaseConflictError } from "./process-ownership.js";
+import { EngineNameSchema, WorkerModelNameSchema } from "../domain/schemas.js";
+export const CONFIGURABLE_ROLES = ["main", "judge", "actor", "critic"];
+const RoleExecutionTargetSchema = z.object({
+    engine: EngineNameSchema,
+    model: WorkerModelNameSchema
+}).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 this.withNextConfigurationLease(() => 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 this.withNextConfigurationLease(() => 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);
+        return this.withNextConfigurationLease(async () => {
+            const next = await readRoleConfigurationIfValid(this.nextPath(), this.config);
+            if (!next) {
+                return taskSelection;
+            }
+            await removeIfExists(this.nextPath());
+            return next;
+        });
+    }
+    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);
+    }
+    validate(roles) {
+        return parseRoleSelection(roles, this.config);
+    }
+    workspaceRootPath() {
+        return this.workspaceRoot;
+    }
+    futurePath() {
+        return roleFutureConfigurationPath(this.appRoot, this.config.dataDir);
+    }
+    nextPath() {
+        return roleNextConfigurationPath(this.workspaceRoot, this.config.dataDir);
+    }
+    nextLeaseDir() {
+        return join(this.workspaceRoot, this.config.dataDir, ".role-configuration-next-lock");
+    }
+    async withNextConfigurationLease(run) {
+        let lease = null;
+        for (let attempt = 0; attempt < 80; attempt += 1) {
+            try {
+                lease = await claimTaskRunLease(this.nextLeaseDir());
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof TaskRunLeaseConflictError) || attempt === 79) {
+                    throw error;
+                }
+                await delay(25);
+            }
+        }
+        if (!lease) {
+            throw new Error("Timed out waiting to update the next-request role configuration.");
+        }
+        try {
+            return await run();
+        }
+        finally {
+            await lease.release();
+        }
+    }
+    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;
+    }
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/domain/schemas.js

@@ -170,10 +170,19 @@ export const FeatureStatusSchema = z.object({
     state: FeatureStateSchema,
     updated_at: z.string().datetime()
 });
+export const WorkerModelNameSchema = z.string()
+    .max(200)
+    .refine((value) => !/[\u0000-\u001f\u007f]/.test(value), {
+    message: "Model name cannot contain control characters"
+});
 export const FeatureAssignmentSchema = z.object({
     version: z.literal(1),
     actor_engine: EngineNameSchema,
     critic_engine: EngineNameSchema,
+    actor_model: WorkerModelNameSchema.default(""),
+    critic_model: WorkerModelNameSchema.default(""),
+    actor_override: z.boolean().default(false),
+    critic_override: z.boolean().default(false),
     updated_at: z.string().datetime()
 });
 export const TurnMetaSchema = z.object({

package/dist/orchestrator/collaboration-channel.js

@@ -70,7 +70,7 @@ export async function createFeatureChannel(input) {
     await writeText(channel.actorRepliesPath, "");
     await writeText(channel.criticFindingsPath, "");
     if (input.actorEngine && input.criticEngine) {
-        await writeFeatureAssignment(channel, input.actorEngine, input.criticEngine);
+        await writeFeatureAssignment(channel, input.actorEngine, input.criticEngine, input.actorModel, input.criticModel);
     }
     await updateFeatureStatus(channel, "created");
     await appendFeatureDialogue(channel, "feature.created", "actor", "Feature mailbox created for the current turn.");
@@ -89,7 +89,7 @@ async function ensureFeatureChannelFiles(input, channel, refreshDefinition) {
         }
     }
     if (!(await pathExists(channel.assignmentPath)) && input.actorEngine && input.criticEngine) {
-        await writeFeatureAssignment(channel, input.actorEngine, input.criticEngine);
+        await writeFeatureAssignment(channel, input.actorEngine, input.criticEngine, input.actorModel, input.criticModel);
     }
 }
 export async function readFeatureAssignment(channel, fallback) {
@@ -101,15 +101,23 @@ export async function readFeatureAssignment(channel, fallback) {
             version: 1,
             actor_engine: fallback.actor,
             critic_engine: fallback.critic,
+            actor_model: "",
+            critic_model: "",
+            actor_override: false,
+            critic_override: false,
             updated_at: new Date(0).toISOString()
         });
     }
 }
-export async function writeFeatureAssignment(channel, actorEngine, criticEngine) {
+export async function writeFeatureAssignment(channel, actorEngine, criticEngine, actorModel = "", criticModel = "", options = {}) {
     const assignment = FeatureAssignmentSchema.parse({
         version: 1,
         actor_engine: actorEngine,
         critic_engine: criticEngine,
+        actor_model: actorModel,
+        critic_model: criticModel,
+        actor_override: options.actorOverride ?? false,
+        critic_override: options.criticOverride ?? false,
         updated_at: new Date().toISOString()
     });
     await writeJson(channel.assignmentPath, assignment);