Release v1.2.0

[CBEPX]

v1.2.0

46 commits on release/v1.2.0 (plan: docs/superpowers/plans/2026-08-28-codex-plugin-cc-v1.2.0.md).

Highlights

• task --await [--await-timeout-ms], --prompt-stdin, result <id> [--wait --timeout-ms] — rescue/agent bodies are a single node … task --await --prompt-stdin <<'CODEX_PROMPT_…' call; allowed-tools back to Bash(node:*); exit codes 0/1/3 documented.
• Lifecycle: SessionEnd stops only its own foreground jobs, checks any active workspace job, asks the broker to shut down only if idle (newline-framed, id-matched, bounded handshake; unknown → skip); broker refuses broker/shutdown while another client is connected; idle self-terminate (fix(broker): self-terminate on idle to reap orphaned shared brokers (#450) openai/codex-plugin-cc#457) kept.
• Bounded turns (--turn-timeout-ms, CODEX_TURN_TIMEOUT_MS): interrupt → wait for terminal notification → structured failed; referenced ack timer; terminal record on transport exit; idempotent bounded close() (TERM → KILL).
• State integrity: cross-process replace-free ticket lock (Lamport bakery on uniquely named immutable files under state.lock.d/; abandonment: dead PID → now, unreadable → 2 s, unusable PID → 30 s, live → never; fails closed on listing errors; 5 s bound naming the blocker); atomic writes; pid sidecar; file-first reaper reconcile; dead workers → failed with payload removal.
• Secrets: all --config values redacted in job records and every output path; raw request only in a 0600 payload file; legacy v1.1.1 records migrated (queued jobs get a payload file before redaction).

Review trail

Codex adversarial review ×11 + Claude (opus) review ×8 over 11 fix waves; ledger and all review reports in .superpowers/sdd/2026-08-28-codex-plugin-cc-v1.2.0/ (not committed). Final gate: 230/230, 0 leaked processes, npm run build, check-version, claude plugin validate . --strict.

CHANGELOG

1.2.0 — 2026-08-28

Merged from upstream pull requests

• fix: keep background jobs alive across SessionEnd openai/codex-plugin-cc#355 SessionEnd now terminates only the ending session's own foreground jobs; a workspace with any active job keeps its shared broker alive across SessionEnd instead of tearing it down out from under the worker, and the hook only clears its own broker-session record when the endpoint still matches (a replacement broker's record survives).
• fix: reap ghost jobs whose worker died without recording a result openai/codex-plugin-cc#425 a PID-liveness reaper marks a queued/running job failed ("worker exited before completing") once its worker process is confirmed dead (kill(pid, 0) reports ESRCH), deletes the job's private one-shot request payload, and clears requestFile; a queued job with no recorded PID yet gets a 30 s grace window before it is reaped, covering a worker that died between spawn and the PID being recorded.

Fork changes

• task --await [--await-timeout-ms <ms>] launches the same tracked job record as --background, then waits for it: exit 0 when the job completed, 1 when it failed or was cancelled, 3 when the default 540000 ms wait elapses while the job is still queued or running (prints a Re-run: node "<abs>" result <id> --wait --timeout-ms 540000 hint).
• --prompt-stdin takes the prompt as raw stdin, stripping exactly one trailing newline and nothing else; the mutual exclusion against --args-stdin, --prompt-file, and a positional prompt is checked on the raw argv before any stdin is read, so a bad combination fails fast instead of blocking on stdin.
• result <id> [--wait [--timeout-ms <ms>]] exits 0 for any terminal job record — completed, failed, or cancelled alike, since this is retrieval, not a pass/fail signal — and exits 3 with the same resumable hint when the job is still active and --wait was not given; --json returns { job, storedJob }.
• Fixed upstream result <id> on a queued/running job reports "No job found" — the still-running message is unreachable when a reference is given openai/codex-plugin-cc#498/codex-companion: workspace-keyed job registry returns 'No job found' for completed jobs when cwd drifts into a git repo openai/codex-plugin-cc#524: result <id> on a still-queued/running job used to throw "No job found for <id>"; it now reports the job's real status plus the result … --wait hint, exit 3.
• --await-timeout-ms and result --timeout-ms are validated as finite positive integers (rejects 0, negatives, fractional, and non-numeric values).
• Worker-survival caveat: the detached worker outlives the companion only when the companion returns on its own via exit 3 — a host process-tree kill (e.g. Claude Code's Bash tool timeout) kills the worker too, so keep --await-timeout-ms below the host's own timeout.
• The worker's PID is now recorded right after spawn (updateJobPid), so a cancel issued while a job is still queued has a process to signal; cancel also releases the job's private one-shot request payload itself, since a cancelled job is terminal and the reaper never revisits it. The parent never rewrites the job JSON after the spawn — that read-modify-write could put a queued snapshot over a record the worker had already completed, losing its result, threadId and turnId while the state index already said terminal. The PID goes into an atomic jobs/<id>.pid sidecar (write + rename) plus the existing pid-only index patch; readers (cancel, the reaper, SessionEnd cleanup) take job.pid ?? sidecar and never read a sidecar for a terminal job, and the sidecar is deleted with the job's terminal write, reap, cancel or prune.
• SessionEnd now reaps dead background workers before deciding whether an active background job should keep the broker alive, so a hard-killed (e.g. OOM/SIGKILL) worker can no longer pin a broker and its job's private payload alive indefinitely.
• /codex:rescue and the codex-rescue agent are now a single node … task --await --prompt-stdin <flags> <<'CODEX_PROMPT_<random>' call each, replacing the old two-Bash-call mktemp/trap/status --wait-poll-loop dance; the per-call random delimiter suffix now only has one heredoc to protect (the request prose) since flags travel on the command line and there is no second --args-stdin heredoc anymore; on exit 3 the only allowed follow-up is re-running the printed Re-run: hint for that same job.
• The resume decision (task-resume-candidate --json + one AskUserQuestion) is now made once, before the synchronous/--background split, so both paths get the same explicit --resume-last/--fresh flag; a --background handoff never resumes silently — the agent runs fresh unless it is handed an explicit --resume-last from that shared decision.
• rescue.md's allowed-tools is back to Bash(node:*), AskUserQuestion, Agent (widened to bare Bash in 1.1.0 only to support the removed two-Bash-call flow).
• --turn-timeout-ms <ms> (or CODEX_TURN_TIMEOUT_MS) on task, review, and adversarial-review bounds a single Codex turn: on expiry it sends turn/interrupt and returns a structured failed result ("turn timed out after <ms> ms") instead of hanging or throwing; default is 0 (unbounded, unchanged behavior); the budget is persisted into --background/--await job requests so detached workers run under the same limit; the timeout now waits up to 10 s for the turn's terminal notification after turn/interrupt instead of declaring the turn dead the moment the RPC answers, and an unacknowledged interrupt is reported as such ("interrupt not acknowledged — the turn may still be running in the shared runtime, check status or cancel") — on a non-broker transport the app-server it owns is closed so the runaway turn dies with the process.
• Documented: with CODEX_COMPANION_BROKER_IDLE_TIMEOUT_MS=0, a broker kept alive by an active background job across SessionEnd never exits on its own — the idle self-terminate safety net from fix(broker): self-terminate on idle to reap orphaned shared brokers (#450) openai/codex-plugin-cc#457 is disabled in that configuration.
• Known limitations: kill(pid, 0) reads a zombie process as alive and cannot detect PID reuse, so the reaper can occasionally misjudge a dead worker's liveness (documented in lib/tracked-jobs.mjs); a turn/start call that never answers is still unbounded — --turn-timeout-ms only covers the window after turn/start resolves.
• task --await jobs are recorded as background jobs (they survive SessionEnd and keep the broker while active, bounded by the reaper and the idle timeout).
• The legacy-request move is limited to queued records, and every terminal write releases the job's private payload. A worker consumes its request before runTrackedJob flips the record to running, so staging a payload for a running legacy job would have written plaintext --config values that nothing reads and nothing deletes; runTrackedJob now drops the payload file alongside the PID sidecar on both its terminal paths, so a payload the worker never consumed cannot outlive the job either.
• Migrating a 1.1.1 record moves its raw request into a fresh 0600 jobs/<id>.request.json before the record loses it, for jobs that are still queued. 1.1.1 wrote no private payload, so the record was the only copy — and it is exactly what a worker falls back to, which would have started Codex with "[redacted]" in place of real --config values (auth headers included). No record is left unredacted on disk any more.
• Records written by 1.1.1 are redacted too: --config values are stripped at the read boundary every status/result output crosses (loadState and the job-file reader), and the same read rewrites the index and the job file once so the values stop living in long-lived state. Redaction now has a single implementation, redactConfigValues in lib/state.mjs.
• A tracked job record never stores --config values any more: it keeps the keys and writes every value as [redacted], because classifying secrets by key name (/key|token|secret|auth|password/i) missed real credentials such as a http_headers.Cookie override, which then reached state.json, the job file, status --json and result --json. The real values still reach Codex — they live only in the private 0600 jobs/<id>.request.json the worker consumes.
• SessionEnd no longer shuts the shared broker down while any job in the workspace is still queued/running — the check used to count only jobs flagged background: true, so another Claude session's foreground run (which survives this session's own-jobs-only cleanup) had its runtime pulled out from under it. The check runs on the state left behind by that cleanup and, as before, reaps dead workers first so a killed worker cannot pin the broker.
• state.json, job files and the private request payload are now written atomically (sibling temp file + rename). A reader that caught a plain writeFileSync mid-flight parsed a truncated — often zero-byte — file, and since loadState answers a parse failure with an empty job list, that read looked exactly like an idle workspace: a SessionEnd landing in that window could shut the shared broker down under a live job (and the reaper/cancel paths could miss active jobs the same way).
• The reaper now reconciles a terminal job file back into the state index instead of returning it to the current caller only: a worker that died between its terminal writeJobFile and its upsertJob left an active index entry that assertThreadIsFree (which now also reads the reaped list) saw as a phantom running job, blocking every later resume of that thread.
• close() on a direct app-server is idempotent as well as bounded: the deadline used to apply to the first call only, and every later call awaited process exit with no bound at all. The turn timeout closes twice by design (once to kill the runaway turn, once on the way out of the run), so the single case the deadline exists for was the one that still hung.
• A bounded turn now always ends in a terminal job record. The acknowledgement window after turn/interrupt is a referenced timer raced against the transport's own exit, so an app-server that answers the interrupt and dies can no longer let the companion exit with the job still running (and no longer costs the full 10 s wait), and closing a directly owned app-server escalates stdin EOF → SIGTERM → SIGKILL with a hard 5 s deadline instead of awaiting process exit forever.
• Documented: partial output on a timed-out turn is best-effort — only items Codex had already completed are kept, so a turn interrupted mid-message reports less text than Codex produced.
• The reaper reads the authoritative job file before it looks at PID liveness, for every active index entry: kill(pid, 0) reads a zombie as alive and cannot see a recycled PID, so a job whose file was already terminal could keep a phantom running index entry — blocking resume on its thread and keeping SessionEnd from ever releasing the broker — for as long as anything held that PID. Liveness is now only consulted for jobs whose own file still says they are active.
• review/adversarial-review now persist --background on the job record, so a review dispatched to outlive its session (nohup … --background &) keeps its record — and with it /codex:status and /codex:result — after that session ends.
• Shutdown-if-idle counts every connected client, not only those that have already sent a message: a client is a client from the moment it is accepted, and CodexAppServerClient connects before it writes initialize, so a shutdown landing in that gap killed the broker under it. The readiness probe now closes its connection fully before reporting the broker up (an open probe would otherwise read as a phantom client), and a client whose broker connection is dropped before initialize is answered falls back to its own app-server instead of failing the run.
• The broker/shutdown handshake is framed by newline and matched by request id, and it is bounded (5 s). A socket carries bytes, not messages, so a {"busy":true} reply split across two data events used to fail to parse and be read as "not busy" — tearing down a broker in the middle of another session's turn — while a peer that connected and stayed silent blocked SessionEnd forever. An unanswered or unparsable handshake is now reported as unknown, and SessionEnd treats anything but a confirmed "not busy" as a reason to leave the broker (and its record, pid file and endpoint) alone.
• The broker itself now refuses broker/shutdown while any other client is connected (replying { "busy": true } and continuing to serve), and SessionEnd treats that refusal as "leave everything alone". The hook's active-job check is only a snapshot: another session could enqueue a job and connect in the gap before the shutdown RPC, and the broker used to shut down regardless, killing that turn. A broker kept alive this way is reaped by its own idle timeout — except with CODEX_COMPANION_BROKER_IDLE_TIMEOUT_MS=0, where a client that stays connected keeps the broker alive until the operator stops it.
• The ticket lock fails closed: a directory listing that fails (permissions, I/O) aborts the acquisition instead of being read as an empty queue, the waiter takes only its own entries back out and the callback never runs; and the bounded wait is checked first on every pass, so a blocker that is judged abandoned but cannot be unlinked ends in the timeout error rather than a hot loop.
• The workspace state lock is a Lamport bakery on files (state.lock.d/): an acquirer creates choosing.<token>, takes a number one above the highest ticket on display, creates <n>.<token>.ticket, drops its choosing file, and holds the lock once no foreign choosing file remains and no ticket sorts before its own (by number, ties by token). Releasing is one unlink of its own ticket. Nothing shared is ever replaced or removed: every name is unique to one acquisition and every file's content is immutable, so a verdict about a file cannot go stale before it is acted on — which is what every previous design (mkdir + holder file, rename-aside takeover, tombstone fences) could not guarantee, since POSIX has no conditional replace. Only entries whose owner is provably gone are cleared, on the unchanged contract: dead PID → at once; unreadable entry → after 2 s; unusable PID → after 30 s; live PID → never, with the wait error naming that PID and its exact ticket file. A pre-1.2.0 state.lock directory is left untouched.
• Every read-modify-write of state.json now runs under a cross-process workspace lock (the ticket lock above; 25 ms polling and a 5 s bound). Atomic writes only stopped torn reads: two processes could still read the same file, and the one that wrote last would treat every job the other had added as deleted — pruning that job's file, private payload, PID sidecar and log. updateState, upsertJob, updateJobPid, saveState (whose prune is a diff of the snapshot it read), the reaper's reconciliation, cancel and the SessionEnd cleanup all re-read inside the lock; readers (status, result, listJobs) stay lock-free.

🤖 Generated with Claude Code