parallel-codex-tui 0.4.0 → 0.4.2

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.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.
 
 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, 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.
 
@@ -65,6 +67,11 @@ 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 --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
@@ -107,6 +114,12 @@ 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 --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
 ```
 
@@ -125,6 +138,39 @@ 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.
+
+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:
@@ -549,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.0
+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.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.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

@@ -2,8 +2,31 @@ 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",
+    "--wait-run",
+    "--wait-timeout"
+]);
+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 +34,25 @@ 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 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");
     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 +65,21 @@ 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,
+        waitRun,
+        waitRunId,
+        waitTimeoutMs,
         workspaceRoot,
         taskId,
         theme,
@@ -86,6 +129,37 @@ 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);
+    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") && 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

@@ -11,6 +11,11 @@ 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
+      --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,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, formatSupervisorWait, inspectSupervisorRuns, requestSupervisorRunCancellation, supervisorWaitExitCode, waitForSupervisorRun } from "./supervisor/operations.js";
 import { runSupervisorJob } from "./supervisor/runner.js";
 main().catch((error) => {
     if (error instanceof WorkspaceSelectionCancelledError) {
@@ -99,6 +100,35 @@ async function main() {
             runtime.index.close();
         }
     }
+    else if (cliArgs.runs || cliArgs.cancelRun || cliArgs.waitRun) {
+        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 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);
+            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,201 @@
+import { randomUUID } from "node:crypto";
+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);
+    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 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}.`;
+    }
+    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}`;
+}
+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([
+        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";
+}
+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/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.2";

package/package.json

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