parallel-codex-tui 0.4.0 → 0.4.1

package/README.md

@@ -6,7 +6,9 @@ Built with Codex-assisted development.
 
 ## Current Release
 
-`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.
+`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.
 
@@ -37,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. 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`.
+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.
 
@@ -65,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
@@ -107,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
 ```
 
@@ -125,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:
@@ -549,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.4.0
+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.4.0` requires tag `v0.4.0`. 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
 

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

@@ -28,6 +28,7 @@ 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) {
@@ -99,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}`);

package/dist/supervisor/operations.js

@@ -0,0 +1,116 @@
+import { randomUUID } from "node:crypto";
+import { appendSupervisorCommand, listSupervisorRuns, readSupervisorController, supervisorControllerIsActive, supervisorRunIsAcknowledged, supervisorRunIsTerminal, supervisorRunProcessIsActive } from "./store.js";
+const QUEUED_START_GRACE_MS = 5000;
+export async function inspectSupervisorRuns(workspaceRoot, dataDir, now = new Date()) {
+    const records = await listSupervisorRuns(workspaceRoot, dataDir);
+    const runs = await Promise.all(records.map((record) => inspectSupervisorRun(record, now)));
+    return {
+        version: 1,
+        workspace_root: workspaceRoot,
+        generated_at: now.toISOString(),
+        runs: runs.reverse()
+    };
+}
+export async function requestSupervisorRunCancellation(workspaceRoot, dataDir, runId, now = new Date()) {
+    const records = await listSupervisorRuns(workspaceRoot, dataDir);
+    const inspected = await Promise.all(records.map(async (record) => ({
+        record,
+        view: await inspectSupervisorRun(record, now)
+    })));
+    const newestFirst = inspected.reverse();
+    const selected = runId
+        ? newestFirst.find(({ view }) => view.run_id === runId)
+        : newestFirst.find(({ view }) => !isTerminalStatus(view.status) && view.control !== "stale");
+    if (!selected) {
+        if (runId) {
+            throw new Error(`Supervisor run not found: ${runId}`);
+        }
+        const stale = newestFirst.find(({ view }) => !isTerminalStatus(view.status));
+        if (stale) {
+            throw new Error(`Supervisor run is not active: ${stale.view.run_id} (${stale.view.status})`);
+        }
+        throw new Error(`No active Supervisor run in workspace ${workspaceRoot}`);
+    }
+    if (isTerminalStatus(selected.view.status)) {
+        throw new Error(`Supervisor run is already ${selected.view.status}: ${selected.view.run_id}`);
+    }
+    if (selected.view.control === "stale") {
+        throw new Error(`Supervisor run is not active: ${selected.view.run_id} (${selected.view.status})`);
+    }
+    const requestedAt = now.toISOString();
+    const commandId = randomUUID();
+    await appendSupervisorCommand(selected.record.files, {
+        version: 1,
+        id: commandId,
+        at: requestedAt,
+        type: "cancel-run"
+    });
+    return {
+        version: 1,
+        command_id: commandId,
+        requested_at: requestedAt,
+        run: selected.view
+    };
+}
+export function formatSupervisorRuns(report) {
+    if (report.runs.length === 0) {
+        return `No Supervisor runs in ${report.workspace_root}.`;
+    }
+    const lines = [`Supervisor runs · ${report.workspace_root}`];
+    for (const run of report.runs) {
+        const acknowledgement = run.acknowledged ? "seen" : "unread";
+        lines.push(`${run.status} · ${run.control} · ${acknowledgement} · ${run.run_id}`);
+        lines.push([
+            run.task_id ? `task ${run.task_id}` : `kind ${run.kind}`,
+            `updated ${run.updated_at}`,
+            ...(run.pid ? [`pid ${run.pid}`] : [])
+        ].join(" · "));
+    }
+    return lines.join("\n");
+}
+export function formatSupervisorCancellation(result) {
+    const target = result.run.task_id ? `task ${result.run.task_id}` : result.run.kind;
+    return `Cancellation requested · ${result.run.run_id} · ${target}`;
+}
+async function inspectSupervisorRun(record, now) {
+    const controller = await readSupervisorController(record.files);
+    const [processActive, controllerActive, acknowledged] = await Promise.all([
+        supervisorRunProcessIsActive(record.state),
+        controller ? supervisorControllerIsActive(controller) : Promise.resolve(false),
+        supervisorRunIsAcknowledged(record.files)
+    ]);
+    return {
+        run_id: record.state.run_id,
+        kind: record.state.kind,
+        status: record.state.status,
+        control: controlState(record, processActive, controllerActive, now),
+        task_id: record.state.task_id ?? null,
+        created_at: record.state.created_at,
+        updated_at: record.state.updated_at,
+        finished_at: record.state.finished_at ?? null,
+        pid: record.state.pid ?? null,
+        process_active: processActive,
+        controller_pid: controller?.pid ?? null,
+        controller_active: controllerActive,
+        acknowledged
+    };
+}
+function controlState(record, processActive, controllerActive, now) {
+    if (supervisorRunIsTerminal(record.state)) {
+        return "settled";
+    }
+    if (controllerActive) {
+        return "controlled";
+    }
+    if (processActive) {
+        return "detached";
+    }
+    if (record.state.status === "queued"
+        && now.getTime() - Date.parse(record.state.updated_at) <= QUEUED_START_GRACE_MS) {
+        return "starting";
+    }
+    return "stale";
+}
+function isTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}

package/dist/supervisor/store.js

@@ -91,6 +91,9 @@ export async function acknowledgeSupervisorRun(files) {
 export async function supervisorRunIsAcknowledged(files) {
     return pathExists(files.acknowledgedPath);
 }
+export async function readSupervisorController(files) {
+    return readValidJson(files.controllerPath, SupervisorControllerSchema);
+}
 export async function listSupervisorRuns(workspaceRoot, dataDir) {
     const root = supervisorRunsRoot(workspaceRoot, dataDir);
     if (!(await pathExists(root))) {
@@ -158,7 +161,7 @@ async function removeControllerIfOwned(path, controllerId) {
     }
     await removeIfExists(path);
 }
-async function supervisorControllerIsActive(controller) {
+export async function supervisorControllerIsActive(controller) {
     if (!processIsAlive(controller.pid)) {
         return false;
     }

package/dist/version.js

@@ -1 +1 @@
-export const version = "0.4.0";
+export const version = "0.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parallel-codex-tui",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A TypeScript TUI wrapper for routed parallel coding with Codex and Claude workers.",
   "license": "MIT",
   "type": "module",