parallel-codex-tui 0.4.1 → 0.4.2

package/README.md

@@ -6,7 +6,7 @@ Built with Codex-assisted development.
 
 ## Current Release
 
-`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.
+`v0.4.2` is available from [npm](https://www.npmjs.com/package/parallel-codex-tui/v/0.4.2) and as a [GitHub Release](https://github.com/allendred/parallel-codex-tui/releases/tag/v0.4.2). It extends the non-interactive Supervisor control plane with `--wait-run [id]` and `--wait-timeout <seconds>`. A second terminal or automation can now wait for a detached run, receive a versioned JSON result, and distinguish completion, failure, cancellation, stale ownership, and local wait timeout without taking the TUI control lease or cancelling the underlying task.
 
 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.
 
@@ -39,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, 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`.
+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, out-of-process status/cancellation, and detached wait/timeout commands. The deterministic repository suite contains 1,368 tests across 143 files: 1,367 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.
 
@@ -70,6 +70,8 @@ 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 --wait-run
+parallel-codex-tui --workspace /path/to/project --wait-run --wait-timeout 600 --json
 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
@@ -116,6 +118,8 @@ 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 --workspace /path/to/project --wait-run
+parallel-codex-tui --workspace /path/to/project --wait-run run-20260721T000000Z-deadbeef --wait-timeout 600 --json
 parallel-codex-tui --version
 ```
 
@@ -155,6 +159,18 @@ parallel-codex-tui --workspace /path/to/project --cancel-run run-20260721T000000
 
 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.
 
+Wait for the latest unfinished run, or address one explicitly:
+
+```bash
+parallel-codex-tui --workspace /path/to/project --wait-run
+parallel-codex-tui --workspace /path/to/project --wait-run run-20260721T000000Z-deadbeef
+parallel-codex-tui --workspace /path/to/project --wait-run run-20260721T000000Z-deadbeef --wait-timeout 600 --json
+```
+
+When no unfinished run exists, `--wait-run` returns the newest persisted terminal run immediately. The waiter is read-only: it does not claim `controller.json`, append to `commands.jsonl`, acknowledge the result, read the original request, or inspect Worker output. `--wait-timeout` accepts positive decimal seconds and stops only the waiting CLI; the Supervisor and Workers continue normally. `Ctrl+C` likewise exits the waiter without cancelling the run.
+
+Wait results use exit code `0` for `completed`, `1` for `failed`, `2` for `cancelled`, `3` for `stale`, and `4` for `timeout`. Text and JSON results contain only the same bounded lifecycle metadata as `--runs`; JSON uses schema version `1`. This makes shell automation able to distinguish task outcomes while keeping requests, prompts, logs, command arguments, and environment values out of its output.
+
 ## Quick Start
 
 Create a local config in the app root:
@@ -579,12 +595,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.1
+VERSION=0.4.2
 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.1` requires tag `v0.4.1`. 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.2` requires tag `v0.4.2`. Published tags such as `v0.2.10` are immutable and must not be moved or reused.
 
 ## Publishing Hygiene
 

package/dist/cli-args.js

@@ -10,7 +10,9 @@ const allowedValueOptions = new Set([
     "-t",
     "--theme",
     "--diagnostics",
-    "--cancel-run"
+    "--cancel-run",
+    "--wait-run",
+    "--wait-timeout"
 ]);
 const allowedBooleanOptions = new Set([
     "--doctor",
@@ -35,6 +37,14 @@ export function parseCliArgs(args, cwd) {
     const cancelRunFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--cancel-run" || arg.startsWith("--cancel-run="));
     const cancelRun = cancelRunFlagIndex >= 0;
     const cancelRunId = flagValue(optionArgs, cancelRunFlagIndex);
+    const waitRunFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--wait-run" || arg.startsWith("--wait-run="));
+    const waitTimeoutFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--wait-timeout" || arg.startsWith("--wait-timeout="));
+    const waitRun = waitRunFlagIndex >= 0;
+    const waitRunId = flagValue(optionArgs, waitRunFlagIndex);
+    const waitTimeoutSeconds = Number(flagValue(optionArgs, waitTimeoutFlagIndex));
+    const waitTimeoutMs = waitTimeoutFlagIndex >= 0 && Number.isFinite(waitTimeoutSeconds)
+        ? waitTimeoutSeconds * 1000
+        : null;
     const diagnostics = diagnosticsFlagIndex >= 0;
     const doctor = optionArgs.includes("--doctor");
     const help = optionArgs.includes("--help") || optionArgs.includes("-h");
@@ -67,6 +77,9 @@ export function parseCliArgs(args, cwd) {
         probeAgents,
         probeRouter,
         runs,
+        waitRun,
+        waitRunId,
+        waitTimeoutMs,
         workspaceRoot,
         taskId,
         theme,
@@ -120,15 +133,33 @@ export function validateCliArgs(args) {
     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");
+    const waitRunFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--wait-run" || arg.startsWith("--wait-run="));
+    const waitRun = waitRunFlagIndex >= 0;
+    const waitRunId = flagValue(optionArgs, waitRunFlagIndex);
+    const supervisorCommandCount = [runs, cancelRun, waitRun].filter(Boolean).length;
+    if (supervisorCommandCount > 1) {
+        errors.push("Only one of --runs, --cancel-run, or --wait-run may be used");
     }
-    if (optionArgs.includes("--json") && !runs && !cancelRun) {
-        errors.push("--json requires --runs or --cancel-run");
+    if (optionArgs.includes("--json") && supervisorCommandCount === 0) {
+        errors.push("--json requires --runs, --cancel-run, or --wait-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");
     }
+    if (waitRunId && !/^run-[A-Za-z0-9._-]+$/.test(waitRunId)) {
+        errors.push("Invalid --wait-run: expected run- followed by letters, numbers, dot, underscore, or hyphen");
+    }
+    const waitTimeoutFlagIndex = lastFlagIndex(optionArgs, (arg) => arg === "--wait-timeout" || arg.startsWith("--wait-timeout="));
+    if (waitTimeoutFlagIndex >= 0) {
+        const rawWaitTimeout = flagValue(optionArgs, waitTimeoutFlagIndex);
+        const waitTimeoutSeconds = Number(rawWaitTimeout);
+        if (!rawWaitTimeout || !Number.isFinite(waitTimeoutSeconds) || waitTimeoutSeconds <= 0) {
+            errors.push("Invalid --wait-timeout: expected a positive number of seconds");
+        }
+        if (!waitRun) {
+            errors.push("--wait-timeout requires --wait-run");
+        }
+    }
     return errors;
 }
 function argsBeforeTerminator(args) {

package/dist/cli-help.js

@@ -13,7 +13,9 @@ Options:
       --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
+      --wait-run [id]     Wait for a run by id, or the latest unfinished run
+      --wait-timeout <s>  Stop waiting after this many seconds; never cancels the run
+      --json              Emit machine-readable Supervisor command output
       --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,7 +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 { formatSupervisorCancellation, formatSupervisorRuns, formatSupervisorWait, inspectSupervisorRuns, requestSupervisorRunCancellation, supervisorWaitExitCode, waitForSupervisorRun } from "./supervisor/operations.js";
 import { runSupervisorJob } from "./supervisor/runner.js";
 main().catch((error) => {
     if (error instanceof WorkspaceSelectionCancelledError) {
@@ -100,7 +100,7 @@ async function main() {
             runtime.index.close();
         }
     }
-    else if (cliArgs.runs || cliArgs.cancelRun) {
+    else if (cliArgs.runs || cliArgs.cancelRun || cliArgs.waitRun) {
         const workspaceRoot = await selectWorkspaceForCli({
             appRoot: cliArgs.appRoot,
             cwd: process.cwd(),
@@ -113,10 +113,15 @@ async function main() {
                 const report = await inspectSupervisorRuns(workspaceRoot, config.dataDir);
                 console.log(cliArgs.json ? JSON.stringify(report, null, 2) : formatSupervisorRuns(report));
             }
-            else {
+            else if (cliArgs.cancelRun) {
                 const result = await requestSupervisorRunCancellation(workspaceRoot, config.dataDir, cliArgs.cancelRunId);
                 console.log(cliArgs.json ? JSON.stringify(result, null, 2) : formatSupervisorCancellation(result));
             }
+            else {
+                const result = await waitForSupervisorRun(workspaceRoot, config.dataDir, cliArgs.waitRunId, { timeoutMs: cliArgs.waitTimeoutMs });
+                console.log(cliArgs.json ? JSON.stringify(result, null, 2) : formatSupervisorWait(result));
+                process.exitCode = supervisorWaitExitCode(result.outcome);
+            }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/supervisor/operations.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { appendSupervisorCommand, listSupervisorRuns, readSupervisorController, supervisorControllerIsActive, supervisorRunIsAcknowledged, supervisorRunIsTerminal, supervisorRunProcessIsActive } from "./store.js";
+import { appendSupervisorCommand, listSupervisorRuns, readSupervisorController, readSupervisorRunState, 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);
@@ -52,6 +52,64 @@ export async function requestSupervisorRunCancellation(workspaceRoot, dataDir, r
         run: selected.view
     };
 }
+export async function waitForSupervisorRun(workspaceRoot, dataDir, runId, options = {}) {
+    const startedAt = Date.now();
+    const now = options.now ?? (() => new Date());
+    const requestedPollIntervalMs = options.pollIntervalMs ?? 100;
+    if (!Number.isFinite(requestedPollIntervalMs) || requestedPollIntervalMs <= 0) {
+        throw new Error("Supervisor wait poll interval must be a positive number of milliseconds");
+    }
+    const pollIntervalMs = Math.max(10, requestedPollIntervalMs);
+    const timeoutMs = options.timeoutMs ?? null;
+    if (timeoutMs !== null && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        throw new Error("Supervisor wait timeout must be a positive number of milliseconds");
+    }
+    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)) ?? newestFirst[0];
+    if (!selected) {
+        throw new Error(runId
+            ? `Supervisor run not found: ${runId}`
+            : `No Supervisor runs in workspace ${workspaceRoot}`);
+    }
+    while (true) {
+        const view = await inspectSupervisorRun(selected.record, now());
+        const waitedMs = Math.max(0, Date.now() - startedAt);
+        if (isTerminalStatus(view.status)) {
+            return {
+                version: 1,
+                outcome: view.status,
+                waited_ms: waitedMs,
+                run: view
+            };
+        }
+        if (view.control === "stale") {
+            return {
+                version: 1,
+                outcome: "stale",
+                waited_ms: waitedMs,
+                run: view
+            };
+        }
+        if (timeoutMs !== null && waitedMs >= timeoutMs) {
+            return {
+                version: 1,
+                outcome: "timeout",
+                waited_ms: waitedMs,
+                run: view
+            };
+        }
+        const remainingTimeoutMs = timeoutMs === null ? pollIntervalMs : Math.max(1, timeoutMs - waitedMs);
+        await delay(Math.min(pollIntervalMs, remainingTimeoutMs));
+        selected.record.state = await readSupervisorRunState(selected.record.files);
+    }
+}
 export function formatSupervisorRuns(report) {
     if (report.runs.length === 0) {
         return `No Supervisor runs in ${report.workspace_root}.`;
@@ -72,6 +130,24 @@ 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}`;
 }
+export function formatSupervisorWait(result) {
+    const target = result.run.task_id ? `task ${result.run.task_id}` : result.run.kind;
+    return `Run ${result.outcome} · ${result.run.run_id} · ${target} · waited ${formatDuration(result.waited_ms)}`;
+}
+export function supervisorWaitExitCode(outcome) {
+    switch (outcome) {
+        case "completed":
+            return 0;
+        case "failed":
+            return 1;
+        case "cancelled":
+            return 2;
+        case "stale":
+            return 3;
+        case "timeout":
+            return 4;
+    }
+}
 async function inspectSupervisorRun(record, now) {
     const controller = await readSupervisorController(record.files);
     const [processActive, controllerActive, acknowledged] = await Promise.all([
@@ -114,3 +190,12 @@ function controlState(record, processActive, controllerActive, now) {
 function isTerminalStatus(status) {
     return status === "completed" || status === "failed" || status === "cancelled";
 }
+function formatDuration(milliseconds) {
+    if (milliseconds < 1000) {
+        return `${milliseconds}ms`;
+    }
+    return `${(milliseconds / 1000).toFixed(milliseconds < 10000 ? 1 : 0)}s`;
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/version.js

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

package/package.json

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