parallel-codex-tui 0.1.0 → 0.1.3

package/README.md

@@ -2,9 +2,11 @@
 
 A standalone TypeScript TUI wrapper for routed parallel coding workflows. It keeps a main chat open while Codex routes larger tasks into Judge, Actor, and Critic workers that can write prompts, logs, session metadata, and outputs to disk.
 
+Built with Codex-assisted development.
+
 ## Requirements
 
-- Node.js 22.5+.
+- Node.js 26+.
 - Codex CLI available as `codex` for Codex routing and Codex workers.
 - Claude CLI available as `claude` only when you configure Claude workers.
 - A project workspace you are comfortable letting configured workers edit.
@@ -24,6 +26,15 @@ parallel-codex-tui --doctor
 parallel-codex-tui --workspace /path/to/project
 ```
 
+Startup resolves the worker project before routing:
+
+- `--workspace <path>` opens that project when it already exists.
+- If `--workspace <path>` does not exist in an interactive terminal, the CLI shows remembered projects from `.parallel-codex/workspaces.json`; press Enter to create the requested folder, pick a remembered project, or enter another path.
+- If `--workspace <path>` points to an existing file, the CLI reports that it is not a directory and will not use that file path as the default folder to create.
+- Without `--workspace`, an interactive terminal shows remembered projects from `.parallel-codex/workspaces.json`; choose a number or enter `n <path>` to create/open another folder.
+- In non-interactive startup, the CLI reuses the last remembered workspace, falls back to the current directory if none was saved, and creates an explicit `--workspace` path if needed.
+- The selected workspace is prepared before any router or worker process starts.
+
 From a source checkout, install dependencies and link the local binary:
 
 ```bash
@@ -38,6 +49,8 @@ For development without linking, run:
 npm run dev -- --workspace /path/to/project
 ```
 
+CLI options with values can also be passed as `--workspace=/path/to/project`, `--app-root=/path/to/app`, `--task=task-id`, `-w=/path/to/project`, and `-t=task-id`.
+
 Check available flags or the installed version without starting the TUI:
 
 ```bash
@@ -46,6 +59,8 @@ parallel-codex-tui --doctor
 parallel-codex-tui --version
 ```
 
+`--doctor` checks the configured commands and any `{env:NAME}` references in active worker model environment settings before workers start.
+
 ## Quick Start
 
 Create a local config in the app root:
@@ -79,6 +94,7 @@ parallel-codex-tui --workspace /path/to/project
 ## Behavior
 
 - Requests are routed by Codex by default, with a configured simple/complex fallback if the router process fails.
+- Router classification only receives the user request; workspace selection and session files are kept out of the router prompt.
 - Simple requests stay in the main TUI flow and do not create Judge, Actor, or Critic workers.
 - Complex requests create a session under `.parallel-codex/sessions/`.
 - Complex requests run Judge -> Actor -> Critic.
@@ -122,6 +138,14 @@ Configure Codex and Claude commands in `.parallel-codex/config.toml`:
 command = "codex"
 args = ["exec", "--skip-git-repo-check", "--sandbox", "workspace-write", "--color", "never", "-"]
 
+[workers.codex.model]
+name = "gpt-5"
+provider = "openai"
+args = ["--model", "{model}"]
+
+[workers.codex.model.env]
+OPENAI_API_KEY = "{env:OPENAI_API_KEY}"
+
 [workers.codex.interactive]
 command = "codex"
 args = ["resume", "{sessionId}"]
@@ -143,8 +167,22 @@ While viewing a worker log, press `Ctrl+O` to attach to the worker's native sess
 
 If a native resume fails because the underlying CLI reports that its context window is full, configure `fallback = "new"` under `[workers.<engine>.nativeSession]`. The old native session is archived as `native-session.retired.json`, removed from active use, and the worker is retried once with the normal fresh-session command.
 
+## Release
+
+GitHub Actions runs CI on pushes and pull requests to `main`.
+
+Configure npm Trusted Publishing for this GitHub Actions workflow with organization/user `allendred`, repository `parallel-codex-tui`, and workflow filename `release.yml`. The release job installs npm `^11.5.1`, which is required for trusted publishing. Alternatively, add an `NPM_TOKEN` repository secret with npm publish permission; it must be an npm automation token so CI can publish without an interactive one-time password. If npm returns `EOTP`, replace the secret with an automation token or remove the secret and use Trusted Publishing. To publish a release, update `package.json` and `src/version.ts` to the same version, then push a matching tag:
+
+```bash
+git tag v0.1.3
+git push origin v0.1.3
+```
+
+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.1.3` requires tag `v0.1.3`.
+
 ## Publishing Hygiene
 
 - `.parallel-codex/config.toml` is local-only and ignored.
+- `.parallel-codex/last-workspace` and `.parallel-codex/workspaces.json` are local workspace-selection state and are ignored.
 - `.parallel-codex/sessions/` contains task prompts, logs, native session ids, and worker output; never commit it.
 - `docs/superpowers/` contains internal planning notes and is ignored for public releases.

package/dist/bootstrap.js

@@ -1,22 +1,34 @@
-import { loadConfig } from "./core/config.js";
+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 { SessionIndex } from "./core/session-index.js";
 import { SessionManager } from "./core/session-manager.js";
+import { prepareWorkspace } from "./core/workspace.js";
 import { Orchestrator } from "./orchestrator/orchestrator.js";
 import { createWorkerRegistry } from "./workers/registry.js";
 export async function createRuntime(appRoot, workspaceRoot = appRoot) {
+    await prepareAppRoot(appRoot);
+    if (!(await pathExists(configPath(appRoot)))) {
+        await writeDefaultConfig(appRoot);
+    }
     const config = await loadConfig(appRoot);
-    const index = await SessionIndex.open(workspaceRoot, config.dataDir);
+    const routerCwd = routerRuntimeDir(appRoot, config.dataDir);
+    await ensureDir(routerCwd);
+    const preparedWorkspace = await prepareWorkspace(appRoot, workspaceRoot);
+    const index = await SessionIndex.open(preparedWorkspace, config.dataDir);
     await index.rebuildFromFiles();
     const sessions = new SessionManager({
-        projectRoot: workspaceRoot,
+        projectRoot: preparedWorkspace,
         dataDir: config.dataDir,
         index
     });
     const workers = createWorkerRegistry(config);
-    const orchestrator = new Orchestrator(config, sessions, workers);
+    const orchestrator = new Orchestrator(config, sessions, workers, undefined, routerCwd);
     return {
         config,
-        workspaceRoot,
+        workspaceRoot: preparedWorkspace,
+        routerCwd,
         index,
         sessions,
         workers,

package/dist/cli-args.js

@@ -1,22 +1,25 @@
 import { resolve } from "node:path";
+import { homedir } from "node:os";
+const allowedValueOptions = new Set(["--app-root", "--workspace", "-w", "--task", "-t"]);
+const allowedBooleanOptions = new Set(["--doctor", "--help", "-h", "--init", "--version", "-v"]);
 export function parseCliArgs(args, cwd) {
-    const appRootFlagIndex = args.findIndex((arg) => arg === "--app-root");
-    const workspaceFlagIndex = args.findIndex((arg) => arg === "--workspace" || arg === "-w");
-    const taskFlagIndex = args.findIndex((arg) => arg === "--task" || arg === "-t");
-    const doctor = args.includes("--doctor");
-    const help = args.includes("--help") || args.includes("-h");
-    const init = args.includes("--init");
-    const version = args.includes("--version") || args.includes("-v");
-    const appRoot = appRootFlagIndex >= 0 && args[appRootFlagIndex + 1]
-        ? resolve(cwd, args[appRootFlagIndex + 1])
-        : cwd;
-    const workspaceRoot = workspaceFlagIndex >= 0 && args[workspaceFlagIndex + 1]
-        ? resolve(cwd, args[workspaceFlagIndex + 1])
-        : cwd;
-    const taskId = taskFlagIndex >= 0 && args[taskFlagIndex + 1] ? args[taskFlagIndex + 1] : null;
+    const optionArgs = argsBeforeTerminator(args);
+    const appRootFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--app-root" || arg.startsWith("--app-root="));
+    const workspaceFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--workspace" || arg.startsWith("--workspace=") || arg === "-w" || arg.startsWith("-w="));
+    const taskFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--task" || arg.startsWith("--task=") || arg === "-t" || arg.startsWith("-t="));
+    const doctor = optionArgs.includes("--doctor");
+    const help = optionArgs.includes("--help") || optionArgs.includes("-h");
+    const init = optionArgs.includes("--init");
+    const version = optionArgs.includes("--version") || optionArgs.includes("-v");
+    const appRootValue = flagValue(optionArgs, appRootFlagIndex);
+    const appRoot = appRootValue ? resolvePathArg(cwd, appRootValue) : cwd;
+    const explicitWorkspace = flagValue(optionArgs, workspaceFlagIndex);
+    const workspaceRoot = explicitWorkspace ? resolvePathArg(cwd, explicitWorkspace) : cwd;
+    const taskId = flagValue(optionArgs, taskFlagIndex);
     return {
         appRoot,
         doctor,
+        explicitWorkspace,
         help,
         init,
         workspaceRoot,
@@ -24,3 +27,51 @@ export function parseCliArgs(args, cwd) {
         version
     };
 }
+function resolvePathArg(cwd, value) {
+    if (value === "~") {
+        return homedir();
+    }
+    if (value.startsWith("~/")) {
+        return resolve(homedir(), value.slice(2));
+    }
+    return resolve(cwd, value);
+}
+export function validateCliArgs(args) {
+    const errors = [];
+    for (const arg of argsBeforeTerminator(args)) {
+        if (!arg.startsWith("-") || arg === "-") {
+            continue;
+        }
+        if (allowedBooleanOptions.has(arg) || allowedValueOptions.has(arg)) {
+            continue;
+        }
+        const equalsIndex = arg.indexOf("=");
+        const optionName = equalsIndex >= 0 ? arg.slice(0, equalsIndex) : arg;
+        if (allowedValueOptions.has(optionName)) {
+            continue;
+        }
+        errors.push(`Unknown option: ${arg}`);
+    }
+    return errors;
+}
+function argsBeforeTerminator(args) {
+    const terminatorIndex = args.indexOf("--");
+    return terminatorIndex >= 0 ? args.slice(0, terminatorIndex) : args;
+}
+function lastFlagIndex(args, predicate) {
+    for (let index = args.length - 1; index >= 0; index -= 1) {
+        if (predicate(args[index] ?? "")) {
+            return index;
+        }
+    }
+    return -1;
+}
+function flagValue(args, flagIndex) {
+    const flag = flagIndex >= 0 ? args[flagIndex] : null;
+    const inlineMatch = flag?.match(/^-{1,2}[^=]+=(.*)$/);
+    if (inlineMatch) {
+        return inlineMatch[1] || null;
+    }
+    const value = flagIndex >= 0 ? args[flagIndex + 1] : null;
+    return value && !value.startsWith("-") ? value : null;
+}

package/dist/cli-workspace.js

@@ -0,0 +1,104 @@
+import { createInterface } from "node:readline/promises";
+import { basename } from "node:path";
+import { pathExists, pathIsDirectory } from "./core/file-store.js";
+import { listWorkspaceChoices, resolveWorkspacePath, resolveWorkspaceSelection } from "./core/workspace.js";
+export async function selectWorkspaceForCli(input) {
+    if (input.explicitWorkspace?.trim()) {
+        const explicit = resolveWorkspacePath(input.cwd, input.explicitWorkspace);
+        const stdin = input.stdin ?? process.stdin;
+        const stdout = input.stdout ?? process.stdout;
+        const explicitExists = await pathExists(explicit);
+        const explicitIsDirectory = explicitExists && (await pathIsDirectory(explicit));
+        if (!explicitIsDirectory && input.interactive !== false && shouldPromptForWorkspace(stdin, stdout)) {
+            return promptForWorkspace({
+                cwd: input.cwd,
+                choices: await listWorkspaceChoices(input.appRoot),
+                invalidExplicitWorkspace: {
+                    path: explicit,
+                    reason: explicitExists ? "file" : "missing"
+                },
+                stdin: stdin,
+                stdout: stdout
+            });
+        }
+        return resolveWorkspaceSelection(input);
+    }
+    const stdin = input.stdin ?? process.stdin;
+    const stdout = input.stdout ?? process.stdout;
+    const choices = await listWorkspaceChoices(input.appRoot);
+    if (input.interactive === false || !shouldPromptForWorkspace(stdin, stdout)) {
+        return resolveWorkspaceSelection(input);
+    }
+    return promptForWorkspace({
+        cwd: input.cwd,
+        choices,
+        stdin: stdin,
+        stdout: stdout
+    });
+}
+function shouldPromptForWorkspace(stdin, stdout) {
+    return Boolean(stdin.isTTY && stdout.isTTY);
+}
+async function promptForWorkspace(input) {
+    if (input.invalidExplicitWorkspace?.reason === "missing") {
+        input.stdout.write(`Workspace does not exist: ${input.invalidExplicitWorkspace.path}\n`);
+    }
+    else if (input.invalidExplicitWorkspace?.reason === "file") {
+        input.stdout.write(`Workspace is not a directory: ${input.invalidExplicitWorkspace.path}\n`);
+    }
+    if (input.choices.length === 0) {
+        input.stdout.write("No workspace selected yet.\n");
+    }
+    else {
+        input.stdout.write("Select workspace:\n");
+        for (const [index, choice] of input.choices.entries()) {
+            input.stdout.write(`  ${index + 1}. ${workspaceLabel(choice)}\n`);
+        }
+        input.stdout.write("  n. Create/open another folder\n");
+    }
+    const rl = createInterface({ input: input.stdin, output: input.stdout });
+    try {
+        const defaultWorkspace = createableDefaultWorkspace(input.invalidExplicitWorkspace);
+        if (input.choices.length === 0) {
+            return await promptForNewWorkspace(rl, input.cwd, defaultWorkspace);
+        }
+        const defaultLabel = defaultWorkspace ? `${defaultWorkspace}, ` : "";
+        const answer = (await rl.question(`Workspace [${defaultLabel}1/${input.choices.length}, n]: `)).trim();
+        if (!answer && defaultWorkspace) {
+            return defaultWorkspace;
+        }
+        if (!answer || answer === "1") {
+            return input.choices[0]?.path ?? input.cwd;
+        }
+        const newWorkspaceMatch = answer.match(/^n(?:ew)?\s+(.+)$/i);
+        if (newWorkspaceMatch?.[1]?.trim()) {
+            return resolveWorkspacePath(input.cwd, newWorkspaceMatch[1].trim());
+        }
+        if (/^n(?:ew)?$/i.test(answer)) {
+            return await promptForNewWorkspace(rl, input.cwd, defaultWorkspace);
+        }
+        const index = Number.parseInt(answer, 10);
+        if (Number.isInteger(index) && index >= 1 && index <= input.choices.length) {
+            return input.choices[index - 1]?.path ?? input.cwd;
+        }
+        return resolveWorkspacePath(input.cwd, answer);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptForNewWorkspace(rl, cwd, defaultWorkspace) {
+    const prompt = defaultWorkspace ? `Workspace path [${defaultWorkspace}]: ` : "Workspace path: ";
+    const answer = (await rl.question(prompt)).trim();
+    if (answer) {
+        return resolveWorkspacePath(cwd, answer);
+    }
+    return defaultWorkspace ?? cwd;
+}
+function createableDefaultWorkspace(invalidExplicitWorkspace) {
+    return invalidExplicitWorkspace?.reason === "missing" ? invalidExplicitWorkspace.path : undefined;
+}
+function workspaceLabel(choice) {
+    const marker = choice.exists ? "" : " (will create)";
+    return `${basename(choice.path) || choice.path}  ${choice.path}${marker}`;
+}

package/dist/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import { jsx as _jsx } from "react/jsx-runtime";
 import { render } from "ink";
-import { parseCliArgs } from "./cli-args.js";
+import { ZodError } from "zod";
+import { parseCliArgs, validateCliArgs } from "./cli-args.js";
+import { selectWorkspaceForCli } from "./cli-workspace.js";
 import { createRuntime } from "./bootstrap.js";
+import { prepareAppRoot } from "./core/app-root.js";
 import { configPath, writeDefaultConfig } from "./core/config.js";
 import { pathExists } from "./core/file-store.js";
 import { runDoctor } from "./doctor.js";
@@ -17,32 +20,87 @@ Options:
       --init              Write .parallel-codex/config.toml if missing
       --doctor            Check local configuration and agent commands
   -v, --version           Print the current version
-  -h, --help              Print this help message`;
-const cliArgs = parseCliArgs(process.argv.slice(2), process.cwd());
-const localConfigPath = configPath(cliArgs.appRoot);
-if (cliArgs.help) {
-    console.log(helpText);
+  -h, --help              Print this help message
+
+Options with values also accept --name=value and -x=value forms.`;
+main().catch((error) => {
+    process.stderr.write(`${formatStartupError(error)}\n`);
+    process.exit(1);
+});
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    const cliArgErrors = validateCliArgs(rawArgs);
+    if (cliArgErrors.length > 0) {
+        process.stderr.write(`${cliArgErrors.join("\n")}\n`);
+        process.exit(1);
+    }
+    const cliArgs = parseCliArgs(rawArgs, process.cwd());
+    if (!cliArgs.help && !cliArgs.version) {
+        await prepareAppRoot(cliArgs.appRoot);
+    }
+    const localConfigPath = configPath(cliArgs.appRoot);
+    if (cliArgs.help) {
+        console.log(helpText);
+    }
+    else if (cliArgs.version) {
+        console.log(`parallel-codex-tui ${version}`);
+    }
+    else if (cliArgs.doctor) {
+        const workspaceRoot = await selectWorkspaceForCli({
+            appRoot: cliArgs.appRoot,
+            cwd: process.cwd(),
+            explicitWorkspace: cliArgs.explicitWorkspace,
+            interactive: false
+        });
+        const result = await runDoctor(cliArgs.appRoot, workspaceRoot);
+        process.stdout.write(result.text);
+        process.exitCode = result.ok ? 0 : 1;
+    }
+    else if (cliArgs.init) {
+        if (await pathExists(localConfigPath)) {
+            console.log(`Config already exists: ${localConfigPath}`);
+        }
+        else {
+            await writeDefaultConfig(cliArgs.appRoot);
+            console.log(`Wrote ${localConfigPath}`);
+        }
+    }
+    else {
+        const workspaceRoot = await selectWorkspaceForCli({
+            appRoot: cliArgs.appRoot,
+            cwd: process.cwd(),
+            explicitWorkspace: cliArgs.explicitWorkspace
+        });
+        const runtime = await createRuntime(cliArgs.appRoot, workspaceRoot);
+        if (cliArgs.taskId && !(await runtime.sessions.hasTask(cliArgs.taskId))) {
+            throw new Error(`Task session not found in workspace ${runtime.workspaceRoot}: ${cliArgs.taskId}`);
+        }
+        if (!canRenderInteractiveTui()) {
+            throw new Error("parallel-codex-tui requires an interactive terminal. Use --help, --version, --init, or --doctor for non-interactive command modes.");
+        }
+        const latestTask = await runtime.sessions.latestTask();
+        const initialTaskId = cliArgs.taskId ?? latestTask?.id ?? null;
+        render(_jsx(App, { config: runtime.config, orchestrator: runtime.orchestrator, cwd: runtime.workspaceRoot, initialTaskId: initialTaskId }), { exitOnCtrlC: false });
+    }
 }
-else if (cliArgs.version) {
-    console.log(`parallel-codex-tui ${version}`);
+function canRenderInteractiveTui() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
-else if (cliArgs.doctor) {
-    const result = await runDoctor(cliArgs.appRoot, cliArgs.workspaceRoot);
-    process.stdout.write(result.text);
-    process.exitCode = result.ok ? 0 : 1;
+function formatStartupError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (isConfigStartupError(error)) {
+        return `Config error: ${message}\nRun parallel-codex-tui --doctor for details.`;
+    }
+    return `Startup error: ${message}`;
 }
-else if (cliArgs.init) {
-    if (await pathExists(localConfigPath)) {
-        console.log(`Config already exists: ${localConfigPath}`);
+function isConfigStartupError(error) {
+    if (error instanceof ZodError) {
+        return true;
     }
-    else {
-        await writeDefaultConfig(cliArgs.appRoot);
-        console.log(`Wrote ${localConfigPath}`);
+    if (!(error instanceof Error)) {
+        return false;
     }
-}
-else {
-    const runtime = await createRuntime(cliArgs.appRoot, cliArgs.workspaceRoot);
-    const latestTask = await runtime.sessions.latestTask();
-    const initialTaskId = cliArgs.taskId ?? latestTask?.id ?? null;
-    render(_jsx(App, { config: runtime.config, orchestrator: runtime.orchestrator, cwd: runtime.workspaceRoot, initialTaskId: initialTaskId }), { exitOnCtrlC: false });
+    return (error.message.startsWith("Invalid config section ") ||
+        error.name.toLowerCase().includes("toml") ||
+        error.message.toLowerCase().includes("toml"));
 }

package/dist/core/app-root.js

@@ -0,0 +1,8 @@
+import { ensureDir, pathExists, pathIsDirectory } from "./file-store.js";
+export async function prepareAppRoot(appRoot) {
+    if ((await pathExists(appRoot)) && !(await pathIsDirectory(appRoot))) {
+        throw new Error(`App root path exists but is not a directory: ${appRoot}`);
+    }
+    await ensureDir(appRoot);
+    return appRoot;
+}

package/dist/core/config.js

@@ -188,6 +188,7 @@ export async function loadConfig(projectRoot) {
         return base;
     }
     const parsed = parse(await readTextIfExists(file));
+    assertObjectSections(parsed);
     const merged = {
         ...base,
         ...parsed,
@@ -291,6 +292,43 @@ export async function loadConfig(projectRoot) {
     };
     return AppConfigSchema.parse(merged);
 }
+function assertObjectSections(parsed) {
+    const sections = [
+        ["router", parsed.router],
+        ["router.codex", parsed.router?.codex],
+        ["workers", parsed.workers],
+        ["workers.codex", parsed.workers?.codex],
+        ["workers.codex.model", parsed.workers?.codex?.model],
+        ["workers.codex.model.env", parsed.workers?.codex?.model?.env],
+        ["workers.codex.nativeSession", parsed.workers?.codex?.nativeSession],
+        ["workers.codex.interactive", parsed.workers?.codex?.interactive],
+        ["workers.claude", parsed.workers?.claude],
+        ["workers.claude.model", parsed.workers?.claude?.model],
+        ["workers.claude.model.env", parsed.workers?.claude?.model?.env],
+        ["workers.claude.nativeSession", parsed.workers?.claude?.nativeSession],
+        ["workers.claude.interactive", parsed.workers?.claude?.interactive],
+        ["workers.mock", parsed.workers?.mock],
+        ["workers.mock.model", parsed.workers?.mock?.model],
+        ["workers.mock.model.env", parsed.workers?.mock?.model?.env],
+        ["workers.mock.nativeSession", parsed.workers?.mock?.nativeSession],
+        ["workers.mock.interactive", parsed.workers?.mock?.interactive],
+        ["pairing", parsed.pairing],
+        ["roles", parsed.roles],
+        ["roles.main", parsed.roles?.main],
+        ["roles.judge", parsed.roles?.judge],
+        ["roles.actor", parsed.roles?.actor],
+        ["roles.critic", parsed.roles?.critic],
+        ["ui", parsed.ui]
+    ];
+    for (const [path, value] of sections) {
+        if (value !== undefined && !isPlainObject(value)) {
+            throw new Error(`Invalid config section [${path}]: expected a table`);
+        }
+    }
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 export async function writeDefaultConfig(projectRoot) {
     const config = defaultConfig(projectRoot);
     const tomlText = stringify({

package/dist/core/file-store.js

@@ -15,6 +15,17 @@ export async function pathExists(path) {
         throw error;
     }
 }
+export async function pathIsDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
 export async function writeJson(path, value) {
     const dir = dirname(path);
     const tempPath = join(dir, `.${basename(path)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);

package/dist/core/paths.js

@@ -12,6 +12,9 @@ export function formatTaskTimestamp(date) {
 export function sessionsRoot(projectRoot, dataDir) {
     return join(projectRoot, dataDir, "sessions");
 }
+export function routerRuntimeDir(appRoot, dataDir) {
+    return join(appRoot, dataDir, "router");
+}
 export function taskDir(projectRoot, dataDir, taskId) {
     return join(sessionsRoot(projectRoot, dataDir), taskId);
 }

package/dist/core/router.js

@@ -16,7 +16,7 @@ export async function routeRequestWithCodex(request, config, runner = runCodexRo
         const fallback = fallbackRoute(config);
         return {
             ...fallback,
-            reason: `Codex router failed: ${error instanceof Error ? error.message : String(error)}. ${fallback.reason}`
+            reason: `Codex router failed: ${summarizeRouterError(error)}. ${fallback.reason}`
         };
     }
 }
@@ -86,11 +86,7 @@ function buildCodexRouterPrompt(request, config) {
         "JSON schema:",
         JSON.stringify({
             mode: "simple|complex",
-            reason: "short explanation",
-            suggested_roles: ["judge", "actor", "critic"],
-            judge_engine: config.pairing.judge,
-            actor_engine: config.pairing.actor,
-            critic_engine: config.pairing.critic
+            reason: "short explanation"
         }),
         "",
         "User request:",
@@ -104,9 +100,9 @@ function parseCodexRoute(output, config) {
         mode: parsed.mode === "complex" ? "complex" : "simple",
         reason: parsed.reason || "Codex router decision.",
         suggested_roles: parsed.mode === "complex" ? ["judge", "actor", "critic"] : [],
-        judge_engine: parsed.judge_engine ?? config.pairing.judge,
-        actor_engine: parsed.actor_engine ?? config.pairing.actor,
-        critic_engine: parsed.critic_engine ?? config.pairing.critic
+        judge_engine: config.pairing.judge,
+        actor_engine: config.pairing.actor,
+        critic_engine: config.pairing.critic
     };
 }
 function extractJsonObject(output) {
@@ -129,6 +125,14 @@ function fallbackRoute(config) {
     }
     return complexRoute("Codex router fallback forced complex.", config);
 }
+function summarizeRouterError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const meaningful = raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line && !line.toLowerCase().startsWith("tip:") && !line.toLowerCase().startsWith("usage:"));
+    return (meaningful || "unknown router error").replace(/[.。]+$/u, "");
+}
 function simpleRoute(reason, config) {
     return {
         mode: "simple",