parallel-codex-tui 0.3.2 → 0.4.1

package/README.md

@@ -6,7 +6,13 @@ 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.1` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.4.1) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.4.1). It adds a non-interactive Supervisor control plane: `--runs` lists persisted background runs, `--runs --json` provides versioned machine-readable status, and `--cancel-run [id]` cancels a selected or latest active run without opening the TUI. The status payload excludes requests, prompts, logs, command arguments, and environment values.
+
+Main and parallel executions 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 +39,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, process-owner crash recovery, and out-of-process status/cancellation commands. The deterministic repository suite contains 1,363 tests across 143 files: 1,362 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.
 
@@ -61,6 +67,9 @@ parallel-codex-tui --doctor --probe-agents
 parallel-codex-tui --doctor --probe-router
 parallel-codex-tui --diagnostics
 parallel-codex-tui --diagnostics ./support-bundle
+parallel-codex-tui --workspace /path/to/project --runs
+parallel-codex-tui --workspace /path/to/project --runs --json
+parallel-codex-tui --workspace /path/to/project --cancel-run
 parallel-codex-tui --workspace /path/to/project
 parallel-codex-tui --theme aurora --workspace /path/to/project
 parallel-codex-tui --theme studio --workspace /path/to/project
@@ -103,6 +112,10 @@ parallel-codex-tui --doctor --probe-agents
 parallel-codex-tui --doctor --probe-router
 parallel-codex-tui --diagnostics
 parallel-codex-tui --diagnostics ./support-bundle
+parallel-codex-tui --workspace /path/to/project --runs
+parallel-codex-tui --workspace /path/to/project --runs --json
+parallel-codex-tui --workspace /path/to/project --cancel-run
+parallel-codex-tui --workspace /path/to/project --cancel-run run-20260721T000000Z-deadbeef
 parallel-codex-tui --version
 ```
 
@@ -121,6 +134,27 @@ Without an explicit destination, the bundle is created under `.parallel-codex/di
 
 The bundle contains `manifest.json`, `report.md`, `report.json`, `doctor.txt`, `tasks.json`, `workers.json`, `router-audit.jsonl`, and bounded Worker log tails. It exports at most the latest 20 tasks, 200 Workers, 100 Router rows, and 200 lines or 64 KiB per Worker log. Workspace, app-root, and home paths are aliased; URL credentials and paths, authorization values, secret assignments, common token formats, and environment-variable values are redacted. Prompts, role instructions, command arguments, source files, and lifetime logs are excluded. Review the bundle before sharing it, because application output can still contain project-specific text that no automatic redactor can fully understand.
 
+## Background Runs
+
+Inspect a Workspace without opening the TUI:
+
+```bash
+parallel-codex-tui --workspace /path/to/project --runs
+parallel-codex-tui --workspace /path/to/project --runs --json
+```
+
+Runs are ordered newest first. Text and JSON output include the run and Task ids, operation kind, lifecycle status, control state, timestamps, Supervisor PID, process liveness, controller PID/liveness, and whether the terminal result has been acknowledged by a TUI. Control states distinguish `starting`, `controlled`, `detached`, `settled`, and `stale`. The JSON document is versioned as `1` and intentionally excludes the original request, prompts, Worker logs, command arguments, and environment values.
+
+Cancel the latest active run, or address one explicitly:
+
+```bash
+parallel-codex-tui --workspace /path/to/project --cancel-run
+parallel-codex-tui --workspace /path/to/project --cancel-run run-20260721T000000Z-deadbeef
+parallel-codex-tui --workspace /path/to/project --cancel-run run-20260721T000000Z-deadbeef --json
+```
+
+Cancellation appends a checked command to the run's existing Supervisor command stream. It does not signal Worker PIDs directly, so the normal orchestrator cancellation, process-tree cleanup, terminal state, chat persistence, and retry evidence remain authoritative. An explicit administrative cancellation can be sent while a TUI is observing or controlling the run. Missing, stale, and already-terminal targets fail without creating a new Workspace or changing historical run evidence.
+
 ## Quick Start
 
 Create a local config in the app root:
@@ -250,7 +284,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 +511,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 +531,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 +579,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.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.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.1` requires tag `v0.4.1`. Published tags such as `v0.2.10` are immutable and must not be moved or reused.
 
 ## Publishing Hygiene
 
@@ -558,6 +592,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-args.js

@@ -2,8 +2,29 @@ import { resolve } from "node:path";
 import { homedir } from "node:os";
 import { normalizeTuiThemeName, TUI_THEME_NAMES } from "./tui/theme.js";
 import { TaskIdSchema } from "./domain/schemas.js";
-const allowedValueOptions = new Set(["--app-root", "--workspace", "-w", "--task", "-t", "--theme", "--diagnostics"]);
-const allowedBooleanOptions = new Set(["--doctor", "--help", "-h", "--init", "--probe-agents", "--probe-router", "--themes", "--version", "-v"]);
+const allowedValueOptions = new Set([
+    "--app-root",
+    "--workspace",
+    "-w",
+    "--task",
+    "-t",
+    "--theme",
+    "--diagnostics",
+    "--cancel-run"
+]);
+const allowedBooleanOptions = new Set([
+    "--doctor",
+    "--help",
+    "-h",
+    "--init",
+    "--json",
+    "--probe-agents",
+    "--probe-router",
+    "--runs",
+    "--themes",
+    "--version",
+    "-v"
+]);
 export function parseCliArgs(args, cwd) {
     const optionArgs = argsBeforeTerminator(args);
     const appRootFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--app-root" || arg.startsWith("--app-root="));
@@ -11,12 +32,17 @@ export function parseCliArgs(args, cwd) {
     const taskFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--task" || arg.startsWith("--task=") || arg === "-t" || arg.startsWith("-t="));
     const themeFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--theme" || arg.startsWith("--theme="));
     const diagnosticsFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--diagnostics" || arg.startsWith("--diagnostics="));
+    const cancelRunFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--cancel-run" || arg.startsWith("--cancel-run="));
+    const cancelRun = cancelRunFlagIndex >= 0;
+    const cancelRunId = flagValue(optionArgs, cancelRunFlagIndex);
     const diagnostics = diagnosticsFlagIndex >= 0;
     const doctor = optionArgs.includes("--doctor");
     const help = optionArgs.includes("--help") || optionArgs.includes("-h");
     const init = optionArgs.includes("--init");
+    const json = optionArgs.includes("--json");
     const probeAgents = optionArgs.includes("--probe-agents");
     const probeRouter = optionArgs.includes("--probe-router");
+    const runs = optionArgs.includes("--runs");
     const themes = optionArgs.includes("--themes");
     const version = optionArgs.includes("--version") || optionArgs.includes("-v");
     const appRootValue = flagValue(optionArgs, appRootFlagIndex);
@@ -29,14 +55,18 @@ export function parseCliArgs(args, cwd) {
     const diagnosticsPath = diagnosticsValue ? resolvePathArg(cwd, diagnosticsValue) : null;
     return {
         appRoot,
+        cancelRun,
+        cancelRunId,
         diagnostics,
         diagnosticsPath,
         doctor,
         explicitWorkspace,
         help,
         init,
+        json,
         probeAgents,
         probeRouter,
+        runs,
         workspaceRoot,
         taskId,
         theme,
@@ -86,6 +116,19 @@ export function validateCliArgs(args) {
     if (optionArgs.includes("--probe-agents") && !optionArgs.includes("--doctor")) {
         errors.push("--probe-agents requires --doctor");
     }
+    const runs = optionArgs.includes("--runs");
+    const cancelRunFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--cancel-run" || arg.startsWith("--cancel-run="));
+    const cancelRun = cancelRunFlagIndex >= 0;
+    const cancelRunId = flagValue(optionArgs, cancelRunFlagIndex);
+    if (runs && cancelRun) {
+        errors.push("--runs and --cancel-run cannot be used together");
+    }
+    if (optionArgs.includes("--json") && !runs && !cancelRun) {
+        errors.push("--json requires --runs or --cancel-run");
+    }
+    if (cancelRunId && !/^run-[A-Za-z0-9._-]+$/.test(cancelRunId)) {
+        errors.push("Invalid --cancel-run: expected run- followed by letters, numbers, dot, underscore, or hyphen");
+    }
     return errors;
 }
 function argsBeforeTerminator(args) {

package/dist/cli-help.js

@@ -11,6 +11,9 @@ Options:
       --init              Write .parallel-codex/config.toml if missing
       --doctor            Check config, agent commands, and theme palette preview
       --diagnostics [dir] Export a sanitized support bundle; defaults inside the workspace
+      --runs              List persisted Supervisor runs without opening the TUI
+      --cancel-run [id]   Cancel a run by id, or the latest active run when omitted
+      --json              Emit machine-readable output with --runs or --cancel-run
       --probe-agents      With --doctor, run fresh + resume probes (uses model quota)
       --probe-router      With --doctor, run one live Codex Router request
   -v, --version           Print the current version

package/dist/cli.js

@@ -27,6 +27,9 @@ 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 { formatSupervisorCancellation, formatSupervisorRuns, inspectSupervisorRuns, requestSupervisorRunCancellation } from "./supervisor/operations.js";
+import { runSupervisorJob } from "./supervisor/runner.js";
 main().catch((error) => {
     if (error instanceof WorkspaceSelectionCancelledError) {
         return;
@@ -35,6 +38,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) {
@@ -91,6 +100,30 @@ async function main() {
             runtime.index.close();
         }
     }
+    else if (cliArgs.runs || cliArgs.cancelRun) {
+        const workspaceRoot = await selectWorkspaceForCli({
+            appRoot: cliArgs.appRoot,
+            cwd: process.cwd(),
+            explicitWorkspace: cliArgs.explicitWorkspace,
+            interactive: false
+        });
+        const config = await loadConfig(cliArgs.appRoot);
+        try {
+            if (cliArgs.runs) {
+                const report = await inspectSupervisorRuns(workspaceRoot, config.dataDir);
+                console.log(cliArgs.json ? JSON.stringify(report, null, 2) : formatSupervisorRuns(report));
+            }
+            else {
+                const result = await requestSupervisorRunCancellation(workspaceRoot, config.dataDir, cliArgs.cancelRunId);
+                console.log(cliArgs.json ? JSON.stringify(result, null, 2) : formatSupervisorCancellation(result));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Supervisor error: ${message}\n`);
+            process.exitCode = 1;
+        }
+    }
     else if (cliArgs.init) {
         if (await pathExists(localConfigPath)) {
             console.log(`Config already exists: ${localConfigPath}`);
@@ -119,7 +152,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 +245,7 @@ async function main() {
         finally {
             removeSigintHandler();
             restoreInteractiveTerminal();
+            closeInteractiveWorkspace(current);
             retryDeferredWorkspaceClosures(deferredWorkspaceClosures);
         }
     }
@@ -219,6 +253,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 +312,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 +335,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);