parallel-codex-tui 0.3.2 → 0.4.0

package/README.md

@@ -6,7 +6,11 @@ Built with Codex-assisted development.
 
 ## Current Release
 
-`v0.3.2` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.3.2) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.3.2). In the Task session center, `Ctrl+F` now searches durable evidence across Tasks and Turns, Feature names, roles, Providers, models, Worker states, summaries, and native session ids. Filters such as `turn:"中文输入" role:actor provider:codex state:done` can be combined with ordinary Unicode text; live async results reject stale responses, Enter keeps the filter, Esc restores the previously applied query, and `X` clears it.
+`v0.4.0` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.4.0) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.4.0). Main and parallel executions now run in a detached, per-request Supervisor after the Router resolves in the foreground. `Ctrl+C` closes the outer TUI without stopping an attached run, reopening the same workspace restores its live events or terminal result, and `Esc` remains the explicit cancellation command. One TUI owns the control lease while additional TUIs observe the same run; an observer takes control automatically after the prior controller detaches or exits.
+
+Supervisor requests, state, events, commands, controller ownership, acknowledgements, and diagnostic output are retained under `.parallel-codex/supervisor/runs/<run-id>/`. The Supervisor writes the final chat result itself, so completion survives a closed terminal without duplicate history when the TUI is reopened. Unexpected Supervisor exit is converted into a durable failed state instead of leaving an indefinitely running UI.
+
+In the Task session center, `Ctrl+F` searches durable evidence across Tasks and Turns, Feature names, roles, Providers, models, Worker states, summaries, and native session ids. Filters such as `turn:"中文输入" role:actor provider:codex state:done` can be combined with ordinary Unicode text; live async results reject stale responses, Enter keeps the filter, Esc restores the previously applied query, and `X` clears it.
 
 Every Task export now includes human-readable `report.md` and structured `report.json` beside the complete raw `session/` snapshot. Reports preserve each Turn request and route, Judge requirements/plans/acceptance criteria, supervisor summaries, Feature assignments and latest review evidence, Wave verification results, Worker Provider/model/state, active native session metadata, completion contracts, and final acceptance evidence. Integrated changed paths are compared with the current workspace as `match`, `drift`, `missing`, `unexpected`, or `unavailable`; the newest integrated wave for each path is authoritative, deleted paths are represented correctly, and unsafe or symlink-traversing paths are never read.
 
@@ -33,7 +37,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,349 tests across 138 files: 1,348 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. Supervisor PTY coverage proves detached Main and complex execution, restart recovery, controller/observer takeover, explicit cancellation, and process-owner crash recovery. The deterministic repository suite contains 1,357 tests across 141 files: 1,356 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.
 
@@ -250,7 +254,7 @@ The doctor output includes `preview:` and `semantic:` ANSI swatch rows so you ca
 - `Ctrl+N` leaves the active complex Task and all Worker logs intact on disk, clears only the live selection and retry state, starts a new Main `conversation_id`, and retires the old Main native session. It works from ordinary chat too, so the next request cannot inherit an unrelated native or file-backed conversation; the next complex request creates an independent Task from turn `0001`.
 - Single-feature follow-ups reuse the same Actor/Critic native sessions when available while moving them to the new turn's isolated workspace. File-backed prompt memory keeps the root Turn and the latest 19 previous Turn summaries within a 12,000-character ceiling; longer histories retain an inline count and path to every immutable Turn summary on disk. A failed follow-up retry reuses a complete saved Judge plan, or restores Judge first when the earlier Judge run never produced one.
 - Automated Judge, Actor, Critic, Wave Actor, and Wave Critic runs enforce process-level isolation: Codex is clamped to root-level `-a never` plus `workspace-write`, and Claude is clamped to non-interactive `auto`, even when private command arguments request manual approval or contain a broader bypass mode. Native attach remains an explicit interactive path.
-- Pressing `Esc` while a request is running stops the router or active worker and records an interrupted complex task as `cancelled`; exiting the outer TUI also terminates the active run.
+- Routing remains in the foreground so fallback choices stay interactive. After a route resolves, Main or parallel execution moves into a detached per-run Supervisor. Pressing `Esc` as the controller cancels the active run and records an interrupted complex task as `cancelled`; pressing `Ctrl+C` detaches and exits the outer TUI while execution continues. Reopening the workspace follows persisted events and restores the final result. A second TUI observes the run and automatically acquires the control lease after the previous controller detaches or exits.
 - Failed and cancelled tasks expose `Ctrl+R` retry. Retry keeps the same task and turn, reuses recorded native worker sessions, preserves prior output behind a retry separator, does not route the request again, and reuses the persisted feature dependency plan. A complete Judge snapshot and fully integrated waves are skipped; an unchanged in-progress wave reuses successful Actor and Critic checkpoints and runs only unfinished workers. If the live workspace no longer matches the saved baseline, the stale wave checkpoint is rejected and rebuilt from the current project before workers continue.
 - The shared Main chat holds its own `sessions/main/run-owner.json` lease across prompt initialization, native-session reuse, and Worker completion. A second TUI is rejected before it can clear or overwrite the active Main prompt, log, status, or native session, and startup native-session reconciliation skips a Main session owned by another live TUI. After a hard exit, startup atomically claims the stale Main lease, terminates every verifiable orphan process group, marks active Main Workers `cancelled`, preserves native session ids, and records recovery before exposing the runtime. An unverifiable or still-running Main process blocks startup without changing its status or checkpoints.
 - Task and Main runs use the same lease finalizer, so a successful run cannot report success until its lease is released. If both the run and lease release fail, the top-level error preserves both causes in an `AggregateError` instead of replacing the original Worker failure.
@@ -477,7 +481,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+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.
+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 cancel it or `Ctrl+C` to close the TUI and leave the Supervisor running. 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.
 
@@ -497,7 +501,7 @@ The Task detail view reads authoritative task files and presents `Project -> Tas
 
 In a Worker log, `Ctrl+F` searches the final rendered Worker log rather than raw file offsets. Type Unicode text normally; Enter moves to the next match and Up/Down moves backward or forward. `Esc` closes search. The current match is marked with `>` without shifting Diff or source line-number columns. With search closed, press `E` to cycle rendered error lines or `D` to cycle Diff files and hunks.
 
-In chat or worker-log views, press `Ctrl+O` to attach to the selected worker's native session inside `parallel-codex-tui`. Native attach runs through a PTY, so full-screen CLIs such as `codex resume {sessionId}` receive a real terminal instead of pipe stdin. Native attach follows outer terminal resize, updating both the rendered screen and child PTY so Codex or Claude reflows at the current dimensions. Input is forwarded to the configured interactive command and output is shown in the native attach panel. When a Codex feature session needs its recorded worker, turn, or feature directories and the interactive command does not already choose a sandbox, native attach adds `--sandbox workspace-write` before its `--add-dir` arguments; an explicitly configured native sandbox remains unchanged. A non-zero native exit recognizes read-only sandbox/add-dir conflicts, untrusted directories, misplaced `--skip-git-repo-check`, missing PTY input, and host permission failures, then appends the exact configuration or terminal action before the exit line scrolls away. Overlapping attach preparations keep only the latest request. Press `Ctrl+]` to return to worker logs; this and closing the outer App terminate the active PTY. An attach preparation that finishes after App shutdown is discarded instead of starting a detached agent. `Ctrl+C` is forwarded to the native agent while attached. In chat and worker-log views, press `Ctrl+C` to exit the outer TUI. An operating-system SIGINT first asks the App to abort its Router or Worker and clean up any PTY; a second SIGINT restores terminal modes and forces exit.
+In chat or worker-log views, press `Ctrl+O` to attach to the selected worker's native session inside `parallel-codex-tui`. Native attach runs through a PTY, so full-screen CLIs such as `codex resume {sessionId}` receive a real terminal instead of pipe stdin. Native attach follows outer terminal resize, updating both the rendered screen and child PTY so Codex or Claude reflows at the current dimensions. Input is forwarded to the configured interactive command and output is shown in the native attach panel. When a Codex feature session needs its recorded worker, turn, or feature directories and the interactive command does not already choose a sandbox, native attach adds `--sandbox workspace-write` before its `--add-dir` arguments; an explicitly configured native sandbox remains unchanged. A non-zero native exit recognizes read-only sandbox/add-dir conflicts, untrusted directories, misplaced `--skip-git-repo-check`, missing PTY input, and host permission failures, then appends the exact configuration or terminal action before the exit line scrolls away. Overlapping attach preparations keep only the latest request. Press `Ctrl+]` to return to worker logs; this and closing the outer App terminate the active PTY. An attach preparation that finishes after App shutdown is discarded instead of starting a detached agent. `Ctrl+C` is forwarded to the native agent while attached. In chat and worker-log views, `Ctrl+C` detaches an active Supervisor run and exits the outer TUI; during foreground routing it cancels classification before exiting. A second operating-system SIGINT restores terminal modes and forces exit.
 
 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. A valid retirement tombstone is also a cross-turn inheritance barrier: a retry or later turn cannot resurrect the same session from an older worker copy, while a newer replacement session remains reusable. A `process-cleanup-error` or `process-ownership-error` always blocks native-session fallback, even when the CLI output also mentions a full context window, so a fresh Worker cannot overlap an untracked or still-running resume process.
 
@@ -545,12 +549,12 @@ 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.3.2
+VERSION=0.4.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.3.2` requires tag `v0.3.2`. Published tags such as `v0.2.10` 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.4.0` requires tag `v0.4.0`. Published tags such as `v0.2.10` are immutable and must not be moved or reused.
 
 ## Publishing Hygiene
 
@@ -558,6 +562,7 @@ You can also run the Release workflow manually and enter the same tag value. The
 - `.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/supervisor/` contains detached-run requests, lifecycle state, control commands, event streams, controller leases, acknowledgements, and Supervisor diagnostics; it is local evidence 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.
 - `.parallel-codex/diagnostics/` contains redacted support bundles and is ignored; review a bundle before sharing it.
 - `.parallel-codex/probes/` contains failed live Agent probe evidence and is ignored.

package/dist/cli.js

@@ -27,6 +27,8 @@ import { formatTuiThemeCatalog } from "./tui/theme-preview.js";
 import { configureTuiTheme } from "./tui/theme.js";
 import { routerDiagnosticsPolicy } from "./tui/RouterDiagnosticsView.js";
 import { version } from "./version.js";
+import { SupervisorOrchestrator } from "./supervisor/client.js";
+import { runSupervisorJob } from "./supervisor/runner.js";
 main().catch((error) => {
     if (error instanceof WorkspaceSelectionCancelledError) {
         return;
@@ -35,6 +37,12 @@ main().catch((error) => {
     process.exit(1);
 });
 async function main() {
+    const supervisorRunDir = process.env.PCT_SUPERVISOR_RUN_DIR;
+    if (supervisorRunDir) {
+        delete process.env.PCT_SUPERVISOR_RUN_DIR;
+        await runSupervisorJob(supervisorRunDir);
+        return;
+    }
     const rawArgs = process.argv.slice(2);
     const cliArgErrors = validateCliArgs(rawArgs);
     if (cliArgErrors.length > 0) {
@@ -119,7 +127,7 @@ async function main() {
         let instance = null;
         const shutdownController = new AbortController();
         const deferredWorkspaceClosures = new Set();
-        const appElement = (state) => (_jsx(App, { config: withUiThemeOverride(state.runtime.config, cliArgs.theme), orchestrator: state.runtime.orchestrator, cwd: state.runtime.workspaceRoot, initialTaskId: state.initialTaskId, initialRoute: state.initialRoute, initialWorkers: state.initialWorkers, initialCanRetryTask: state.initialCanRetryTask, initialMessages: state.initialMessages, workspaceChoices: state.workspaceChoices, shutdownSignal: shutdownController.signal, loadRouterDiagnostics: async () => {
+        const appElement = (state) => (_jsx(App, { config: withUiThemeOverride(state.runtime.config, cliArgs.theme), orchestrator: state.supervisor, cwd: state.runtime.workspaceRoot, initialTaskId: state.initialTaskId, initialRoute: state.initialRoute, initialWorkers: state.initialWorkers, initialCanRetryTask: state.initialCanRetryTask, initialMessages: state.initialMessages, workspaceChoices: state.workspaceChoices, shutdownSignal: shutdownController.signal, loadRouterDiagnostics: async () => {
                 const [records, latestConfig] = await Promise.all([
                     readRouterAudit(join(state.runtime.routerCwd, "routes.jsonl"), 100),
                     loadConfig(cliArgs.appRoot)
@@ -212,6 +220,7 @@ async function main() {
         finally {
             removeSigintHandler();
             restoreInteractiveTerminal();
+            closeInteractiveWorkspace(current);
             retryDeferredWorkspaceClosures(deferredWorkspaceClosures);
         }
     }
@@ -219,6 +228,13 @@ async function main() {
 async function loadInteractiveWorkspace(appRoot, workspaceRoot, requestedTaskId) {
     const runtime = await createRuntime(appRoot, workspaceRoot);
     try {
+        const supervisor = await SupervisorOrchestrator.open({
+            delegate: runtime.orchestrator,
+            sessions: runtime.sessions,
+            appRoot,
+            workspaceRoot: runtime.workspaceRoot,
+            dataDir: runtime.config.dataDir
+        });
         const preflightPromise = runRuntimePreflight(runtime.config, runtime.workspaceRoot, process.env).catch((error) => ({
             ok: false,
             lines: [`preflight: failed (${error instanceof Error ? error.message : String(error)})`]
@@ -271,6 +287,7 @@ async function loadInteractiveWorkspace(appRoot, workspaceRoot, requestedTaskId)
         const recoveryMessages = startupRecoveryMessages(runtime.recoveredTasks, initialTaskId, runtime.pendingTaskCreations, runtime.index.recovery);
         return {
             runtime,
+            supervisor,
             initialTaskId,
             initialRoute,
             initialWorkers,
@@ -293,6 +310,7 @@ async function loadInteractiveWorkspace(appRoot, workspaceRoot, requestedTaskId)
     }
 }
 function closeInteractiveWorkspace(state) {
+    state.supervisor.detachBackgroundRuns();
     state.runtime.index.close();
 }
 function retryDeferredWorkspaceClosures(states) {

package/dist/orchestrator/orchestrator.js

@@ -75,10 +75,17 @@ export class Orchestrator {
     }
     async handleRequest(input) {
         throwIfCancelled(input.signal);
-        const routed = await this.routeRequest(input.request, input.cwd, input.signal, "initial", input.onRouteStart, input.onRouteFallback, input.onRouteProgress);
-        const roleSelection = input.roleSelection ?? await this.roleConfiguration.selectionForRequest();
-        const route = routeWithRoleSelection(routed, roleSelection);
-        input.onRoute?.(route);
+        let roleSelection;
+        let route;
+        if (input.route) {
+            roleSelection = input.roleSelection ?? await this.roleConfiguration.selectionForRequest();
+            route = routeWithRoleSelection(input.route, roleSelection);
+        }
+        else {
+            const routed = await this.routeInitialRequest(input);
+            roleSelection = routed.roleSelection;
+            route = routed.route;
+        }
         throwIfCancelled(input.signal);
         const workers = [];
         const executionInput = { ...input, roleSelection };
@@ -115,6 +122,21 @@ export class Orchestrator {
         await this.roleConfiguration.writeTurnSelection(turn.dir, roleSelectionWithEngines(route, roleSelection));
         return this.withTaskRunLease(task, () => this.runInitialTask(executionInput, task, route, turn, workers));
     }
+    async routeInitialRequest(input) {
+        throwIfCancelled(input.signal);
+        const routed = await this.routeRequest(input.request, input.cwd, input.signal, "initial", input.onRouteStart, input.onRouteFallback, input.onRouteProgress);
+        const roleSelection = input.roleSelection ?? await this.roleConfiguration.selectionForRequest();
+        const route = routeWithRoleSelection(routed, roleSelection);
+        input.onRoute?.(route);
+        throwIfCancelled(input.signal);
+        return {
+            mode: route.mode,
+            taskId: null,
+            reason: route.reason,
+            route,
+            roleSelection
+        };
+    }
     async handleTaskTurn(input) {
         throwIfCancelled(input.signal);
         const task = this.sessions.taskFromId(input.taskId);

package/dist/supervisor/client.js

@@ -0,0 +1,442 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { asSupervisorRunResult, supervisorEventPayload } from "./protocol.js";
+import { acknowledgeSupervisorRun, appendSupervisorCommand, claimSupervisorController, createSupervisorRun, createSupervisorRunId, listSupervisorRuns, readSupervisorEvents, readSupervisorRunState, supervisorRunIsAcknowledged, supervisorRunIsTerminal, supervisorRunProcessIsActive, writeSupervisorRunState } from "./store.js";
+const RUN_POLL_MS = 100;
+const QUEUED_START_GRACE_MS = 3000;
+export class SupervisorDetachedError extends Error {
+    constructor(message = "Background run detached") {
+        super(message);
+        this.name = "SupervisorDetachedError";
+    }
+}
+export function isSupervisorDetachedError(error) {
+    return error instanceof Error && error.name === "SupervisorDetachedError";
+}
+export class SupervisorOrchestrator {
+    options;
+    persistsRunResults = true;
+    launch;
+    now;
+    recoverableRun = null;
+    currentRun = null;
+    settledRun = null;
+    detaching = false;
+    backgroundRunListeners = new Set();
+    constructor(options) {
+        this.options = options;
+        this.launch = options.launch ?? launchSupervisorProcess;
+        this.now = options.now ?? (() => new Date());
+    }
+    static async open(options) {
+        const client = new SupervisorOrchestrator(options);
+        client.recoverableRun = await client.findRecoverableRun();
+        return client;
+    }
+    async handleRequest(input) {
+        const routed = await this.options.delegate.routeInitialRequest(input);
+        return this.startRun({
+            kind: "handle-request",
+            request: input.request,
+            cwd: input.cwd,
+            route: routed.route,
+            role_selection: routed.roleSelection
+        }, input);
+    }
+    async handleTaskTurn(input) {
+        return this.startRun({
+            kind: "handle-task-turn",
+            request: input.request,
+            cwd: input.cwd,
+            task_id: input.taskId,
+            ...(input.route ? { route: input.route } : {}),
+            ...(input.roleSelection ? { role_selection: input.roleSelection } : {})
+        }, input);
+    }
+    async answerTaskQuestion(input) {
+        return this.startRun({
+            kind: "answer-task-question",
+            request: input.request,
+            cwd: input.cwd,
+            task_id: input.taskId,
+            ...(input.route ? { route: input.route } : {}),
+            ...(input.roleSelection ? { role_selection: input.roleSelection } : {})
+        }, input);
+    }
+    async retryTask(input) {
+        return this.startRun({
+            kind: "retry-task",
+            cwd: input.cwd,
+            task_id: input.taskId
+        }, input);
+    }
+    async resumeFeature(input) {
+        return this.startRun({
+            kind: "resume-feature",
+            cwd: input.cwd,
+            task_id: input.taskId,
+            feature_id: input.featureId
+        }, input);
+    }
+    async restorePendingRun(input) {
+        this.detaching = input.signal?.aborted ? this.detaching : false;
+        const pending = this.recoverableRun ?? await this.findRecoverableRun();
+        this.recoverableRun = null;
+        if (!pending) {
+            return null;
+        }
+        const controller = await claimSupervisorController(pending.files);
+        return this.watchRun({
+            files: pending.files,
+            controller,
+            detached: this.detaching,
+            cancelSent: false
+        }, input);
+    }
+    detachBackgroundRuns() {
+        this.detaching = true;
+        const current = this.currentRun;
+        if (!current) {
+            return;
+        }
+        current.detached = true;
+        void current.controller?.release();
+        current.controller = null;
+        this.notifyBackgroundRunState();
+    }
+    backgroundRunAttached() {
+        return this.currentRun !== null;
+    }
+    backgroundRunControllable() {
+        return this.currentRun?.controller !== null && this.currentRun?.controller !== undefined;
+    }
+    subscribeBackgroundRunState(listener) {
+        this.backgroundRunListeners.add(listener);
+        return () => this.backgroundRunListeners.delete(listener);
+    }
+    async acknowledgeBackgroundRun() {
+        if (!this.settledRun) {
+            return;
+        }
+        const files = this.settledRun;
+        this.settledRun = null;
+        await acknowledgeSupervisorRun(files);
+    }
+    async cancelFeature(taskId, featureId) {
+        if (!this.currentRun) {
+            return this.options.delegate.cancelFeature(taskId, featureId);
+        }
+        if (!this.currentRun.controller) {
+            return { requested: false, featureId };
+        }
+        await appendSupervisorCommand(this.currentRun.files, {
+            version: 1,
+            id: randomUUID(),
+            at: this.now().toISOString(),
+            type: "cancel-feature",
+            task_id: taskId,
+            feature_id: featureId
+        });
+        return { requested: true, featureId };
+    }
+    async pauseFeature(taskId, featureId) {
+        if (!this.currentRun) {
+            return this.options.delegate.pauseFeature(taskId, featureId);
+        }
+        if (!this.currentRun.controller) {
+            return { requested: false, featureId };
+        }
+        await appendSupervisorCommand(this.currentRun.files, {
+            version: 1,
+            id: randomUUID(),
+            at: this.now().toISOString(),
+            type: "pause-feature",
+            task_id: taskId,
+            feature_id: featureId
+        });
+        return { requested: true, featureId };
+    }
+    routeTaskFollowUp(input) {
+        return this.options.delegate.routeTaskFollowUp(input);
+    }
+    canRetryTask(taskId) {
+        return this.options.delegate.canRetryTask(taskId);
+    }
+    listTaskWorkers(taskId) {
+        return this.options.delegate.listTaskWorkers(taskId);
+    }
+    reassignFeature(input) {
+        return this.options.delegate.reassignFeature(input);
+    }
+    roleConfigurationSnapshot(taskId) {
+        return this.options.delegate.roleConfigurationSnapshot(taskId);
+    }
+    updateRoleConfiguration(input) {
+        return this.options.delegate.updateRoleConfiguration(input);
+    }
+    clearRoleConfiguration(scope, taskId) {
+        return this.options.delegate.clearRoleConfiguration(scope, taskId);
+    }
+    validateRoleConfiguration(roles) {
+        return this.options.delegate.validateRoleConfiguration(roles);
+    }
+    async startRun(input, callbacks) {
+        this.detaching = callbacks.signal?.aborted ? this.detaching : false;
+        if (this.currentRun) {
+            throw new Error("A Supervisor run is already attached in this TUI.");
+        }
+        const active = (await this.reconcileRuns()).filter(({ state }) => !supervisorRunIsTerminal(state));
+        if (active.length > 0) {
+            throw new Error("A background run is already active in this workspace. Reopen the TUI to attach to it.");
+        }
+        const createdAt = this.now().toISOString();
+        const request = {
+            ...input,
+            version: 1,
+            run_id: createSupervisorRunId(this.now()),
+            app_root: this.options.appRoot,
+            workspace_root: this.options.workspaceRoot,
+            data_dir: this.options.dataDir,
+            created_at: createdAt
+        };
+        const files = await createSupervisorRun(this.options.workspaceRoot, this.options.dataDir, request);
+        const controller = await claimSupervisorController(files);
+        if (!controller) {
+            throw new Error("The new Supervisor run was claimed by another TUI before it could start.");
+        }
+        const watched = {
+            files,
+            controller,
+            detached: this.detaching,
+            cancelSent: false
+        };
+        this.currentRun = watched;
+        this.notifyBackgroundRunState();
+        try {
+            await this.launch(files, request);
+        }
+        catch (error) {
+            if (this.currentRun === watched) {
+                this.currentRun = null;
+                this.notifyBackgroundRunState();
+            }
+            await controller.release();
+            const message = error instanceof Error ? error.message : String(error);
+            const failedAt = this.now().toISOString();
+            const state = await readSupervisorRunState(files);
+            await writeSupervisorRunState(files, {
+                ...state,
+                status: "failed",
+                updated_at: failedAt,
+                finished_at: failedAt,
+                error: message
+            });
+            await this.options.sessions.appendChatMessage({ from: "system", text: message });
+            this.settledRun = files;
+            throw error;
+        }
+        return this.watchRun(watched, callbacks);
+    }
+    async watchRun(watched, callbacks) {
+        this.currentRun = watched;
+        this.notifyBackgroundRunState();
+        let nextEventSequence = 0;
+        try {
+            while (true) {
+                if (watched.detached) {
+                    throw new SupervisorDetachedError();
+                }
+                if (!watched.controller) {
+                    watched.controller = await claimSupervisorController(watched.files);
+                    if (watched.controller) {
+                        this.notifyBackgroundRunState();
+                    }
+                }
+                const events = await readSupervisorEvents(watched.files);
+                for (const event of events) {
+                    if (event.sequence < nextEventSequence) {
+                        continue;
+                    }
+                    nextEventSequence = event.sequence + 1;
+                    dispatchSupervisorEvent(event, callbacks);
+                }
+                const state = await readSupervisorRunState(watched.files);
+                if (supervisorRunIsTerminal(state)) {
+                    this.settledRun = watched.files;
+                    if (state.status === "completed" && state.result) {
+                        return asSupervisorRunResult(state.result);
+                    }
+                    const error = new Error(state.error || `Supervisor run ${state.status}`);
+                    if (state.status === "cancelled") {
+                        error.name = "AbortError";
+                    }
+                    throw error;
+                }
+                if (watched.controller && !(await supervisorRunProcessIsActive(state))) {
+                    const ageMs = this.now().getTime() - Date.parse(state.created_at);
+                    if (state.status !== "queued" || ageMs >= QUEUED_START_GRACE_MS) {
+                        const failedAt = this.now().toISOString();
+                        const summary = `Supervisor exited unexpectedly while ${state.kind} was running.`;
+                        await writeSupervisorRunState(watched.files, {
+                            ...state,
+                            status: "failed",
+                            updated_at: failedAt,
+                            finished_at: failedAt,
+                            error: summary
+                        });
+                        await this.options.sessions.appendChatMessage({
+                            from: "system",
+                            text: summary,
+                            taskId: state.task_id ?? undefined
+                        });
+                        continue;
+                    }
+                }
+                if (callbacks.signal?.aborted && !watched.cancelSent) {
+                    if (!watched.controller) {
+                        throw new SupervisorDetachedError("Observer detached; the background run is still active");
+                    }
+                    watched.cancelSent = true;
+                    await appendSupervisorCommand(watched.files, {
+                        version: 1,
+                        id: randomUUID(),
+                        at: this.now().toISOString(),
+                        type: "cancel-run"
+                    });
+                }
+                await delay(RUN_POLL_MS);
+            }
+        }
+        finally {
+            if (this.currentRun === watched) {
+                this.currentRun = null;
+            }
+            await watched.controller?.release();
+            watched.controller = null;
+            this.notifyBackgroundRunState();
+        }
+    }
+    notifyBackgroundRunState() {
+        for (const listener of this.backgroundRunListeners) {
+            listener();
+        }
+    }
+    async findRecoverableRun() {
+        const runs = await this.reconcileRuns();
+        const active = runs.filter(({ state }) => !supervisorRunIsTerminal(state));
+        if (active.length > 0) {
+            return active.at(-1) ?? null;
+        }
+        const unacknowledged = [];
+        for (const run of runs) {
+            if (supervisorRunIsTerminal(run.state) && !(await supervisorRunIsAcknowledged(run.files))) {
+                unacknowledged.push(run);
+            }
+        }
+        return unacknowledged.at(-1) ?? null;
+    }
+    async reconcileRuns() {
+        const runs = await listSupervisorRuns(this.options.workspaceRoot, this.options.dataDir);
+        for (const run of runs) {
+            if (supervisorRunIsTerminal(run.state) || await supervisorRunProcessIsActive(run.state)) {
+                continue;
+            }
+            const ageMs = this.now().getTime() - Date.parse(run.state.created_at);
+            if (run.state.status === "queued" && ageMs < QUEUED_START_GRACE_MS) {
+                continue;
+            }
+            const failedAt = this.now().toISOString();
+            const summary = `Supervisor exited unexpectedly while ${run.state.kind} was running.`;
+            run.state = {
+                ...run.state,
+                status: "failed",
+                updated_at: failedAt,
+                finished_at: failedAt,
+                error: summary
+            };
+            await writeSupervisorRunState(run.files, run.state);
+            await this.options.sessions.appendChatMessage({
+                from: "system",
+                text: summary,
+                taskId: run.state.task_id ?? undefined
+            });
+        }
+        return runs;
+    }
+}
+function dispatchSupervisorEvent(event, callbacks) {
+    const payload = supervisorEventPayload(event);
+    switch (event.type) {
+        case "route-start":
+            callbacks.onRouteStart?.(payload);
+            break;
+        case "route-progress":
+            callbacks.onRouteProgress?.(payload);
+            break;
+        case "route":
+            callbacks.onRoute?.(payload);
+            break;
+        case "status":
+            callbacks.onStatus?.(payload);
+            break;
+        case "worker":
+            callbacks.onWorker?.(payload);
+            break;
+    }
+}
+async function launchSupervisorProcess(files, request) {
+    const entrypoint = process.argv[1] ? resolve(process.argv[1]) : "";
+    if (!entrypoint) {
+        throw new Error("Cannot locate the parallel-codex-tui CLI entrypoint for Supervisor launch.");
+    }
+    const errorLog = openSync(join(files.dir, "supervisor.log"), "a");
+    const child = spawn(process.execPath, [...process.execArgv, entrypoint], {
+        cwd: process.cwd(),
+        detached: true,
+        env: {
+            ...process.env,
+            PCT_SUPERVISOR_RUN_DIR: files.dir
+        },
+        stdio: ["ignore", "ignore", errorLog]
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", reject);
+        });
+    }
+    finally {
+        closeSync(errorLog);
+    }
+    let exitCode;
+    const onExit = (code) => {
+        exitCode = code;
+    };
+    child.once("exit", onExit);
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        const state = await readSupervisorRunState(files);
+        if (state.status !== "queued") {
+            child.off("exit", onExit);
+            child.unref();
+            return;
+        }
+        if (exitCode !== undefined) {
+            throw new Error(`Supervisor process exited before startup (code ${exitCode ?? "signal"}).`);
+        }
+        await delay(25);
+    }
+    child.off("exit", onExit);
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        // The startup failure below remains the useful error when the child already exited.
+    }
+    throw new Error("Supervisor process did not publish startup state within 5s.");
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}