Add Gemini CLI extension commands - #1

feat: Gemini CLI plugin for Claude Code

Root cause
----------
`captureTurn` (plugins/codex/scripts/lib/codex.mjs) blocks on
`state.completion`. Two resolution paths existed:

  A. `turn/completed` notification from Codex app-server
  B. `finalAnswerSeen + scheduleInferredCompletion` (fires 250ms after an
     `agentMessage` with `phase === "final_answer"`)

Both assume the Codex CLI cooperates and emits a terminal signal before
disconnecting. When the CLI exits mid-turn — rate limit, OOM, internal
error, token limit — neither fires:

  * no `turn/completed` was sent;
  * the only `agentMessage` had `phase === "plan"`, so
    `finalAnswerSeen` stayed `false`.

`state.completion` hangs indefinitely. The node companion process itself
exits cleanly via IPC EOF, bypassing `runTrackedJob`'s try/catch — which
leaves a zombie job record (`status: "running"`) and no final verdict
written to stdout. Observed three times in the wild on 2026-04-18 while
running `/codex:adversarial-review` from Claude Code.

In broker mode (`app-server-broker.mjs`) the bug is worse: the broker
does not watch the upstream appClient, so when the Codex CLI dies the
broker keeps accepting the client socket connection. Clients get neither
`turn/completed` nor a socket EOF.

Why not the "obvious" small fixes
---------------------------------
  - Relax `finalAnswerSeen` to accept any `lifecycle === "completed"`
    agentMessage: changes semantics for well-behaved turns; can commit
    prematurely on intermediate plan-phase messages.
  - Add only a max-turn timeout: loses `lastAgentMessage` diagnostic and
    fires even on long-but-healthy turns.
  - Broker-side timeout alone: does not help direct-transport callers.

Fix (root cause, both transports)
---------------------------------
  1. `captureTurn` subscribes to `client.exitPromise`. When the client
     disconnects before `state.completed`, it records the exitError (if
     any) on `state.error`, emits a progress event, and forces completion
     with `finalTurn.status = "failed"` (so `buildResultStatus` returns
     non-zero). Existing resolution paths keep their precedence — the
     watchdog no-ops when the turn has already completed cleanly.

  2. `app-server-broker.mjs` subscribes to its upstream
     `appClient.exitPromise` and tears down the server when the Codex
     CLI dies. Connected clients receive a socket EOF and the fix in openai#1
     resolves `captureTurn` with an error. Broker exits with status 1
     so supervisors can restart it.

Test
----
New fake behavior `disconnect-before-completion` emits a `plan`-phase
agentMessage then `process.exit(0)` without ever sending
`turn/completed`. The new regression test in `runtime.test.mjs` drives
`adversarial-review` against this fake with a 10s `spawnSync` timeout;
before this patch it timed out (SIGTERM), after it exits non-zero
with a message mentioning the disconnect.

Upstream note
-------------
This fix is a defensive watchdog on the consumer side. A separate
investigation in `openai/codex` into why the CLI can exit mid-turn
without flushing `turn/completed` is orthogonal but welcome — the
watchdog here makes the companion resilient regardless.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Root cause
----------
`captureTurn` (plugins/codex/scripts/lib/codex.mjs) blocks on
`state.completion`. Two existing resolution paths both require server
cooperation:

  A. `turn/completed` notification from Codex app-server
  B. `finalAnswerSeen + scheduleInferredCompletion` (fires 250ms after
     an `agentMessage` with `phase === "final_answer"`)

When the Codex CLI exits mid-turn — rate limit, OOM, internal error,
token limit — neither fires: the only `agentMessage` had `phase ==
"plan"` so `finalAnswerSeen` stayed `false`, and no `turn/completed`
was ever sent. `state.completion` hangs indefinitely. The node
companion process itself exits cleanly via IPC EOF, bypassing
`runTrackedJob`'s try/catch, leaving a zombie job record
(`status: "running"`) and no final verdict. Observed three times in
the wild on 2026-04-18 while running `/codex:adversarial-review` from
Claude Code.

In broker mode (`app-server-broker.mjs`) the bug was worse: the broker
did not watch the upstream `appClient`, so when the Codex CLI died the
broker kept accepting socket connections. Clients got neither
`turn/completed` nor a socket EOF.

Fix (three coupled changes, one semantic unit)
-----------------------------------------------
1. `captureTurn` subscribes to `client.exitPromise` as a third
   resolution path. If a `final_answer` agentMessage has already been
   captured AND no subagent work is outstanding, honor the existing
   inferred-success semantics — call `completeTurn(state, null, {
   inferred: true })` without the 250ms debounce, which is meaningless
   on a dead socket. Only when no terminal signal was captured do we
   synthesize a `failed` turn so `buildResultStatus` returns non-zero.

2. `app-server-broker.mjs` subscribes to the upstream
   `appClient.exitPromise` and tears down the server when the Codex
   CLI dies. Connected clients receive socket EOF and the watchdog in
   openai#1 resolves their `captureTurn`. Broker exits with status 1 so
   supervisors can restart it.

3. The broker watchdog skips when `shuttingDown` is true. Without this
   guard, intentional teardown paths (`broker/shutdown`, `SIGTERM`,
   `SIGINT`) all call `shutdown(server)` → `appClient.close()` which
   resolves the same `exitPromise`, re-entering `shutdown()` and
   racing `process.exit(0)` with `process.exit(1)`.

Why the obvious small fixes were rejected
------------------------------------------
  - Relax `finalAnswerSeen` to any `lifecycle === "completed"`
    agentMessage: changes semantics for well-behaved turns; can commit
    prematurely on intermediate plan-phase messages.
  - Only a max-turn timeout: loses `lastAgentMessage` diagnostic, fires
    on legitimately long turns, and doesn't catch fast disconnects.
  - Broker-side timeout alone: doesn't help direct-transport callers.

Tests
-----
Three regression tests in `tests/runtime.test.mjs` against new fake
behaviors in `tests/fake-codex-fixture.mjs`:

  * `adversarial review resolves when app-server disconnects before
    turn/completed` — plan-phase agentMessage then disconnect; asserts
    non-zero exit + rendered output mentions the disconnect.
  * `adversarial review preserves final_answer when app-server exits
    before turn/completed` — final_answer agentMessage then
    disconnect; asserts exit 0 + structured findings survive.
  * `broker exits cleanly on broker/shutdown without tripping the
    upstream-exit watchdog` — sends `broker/shutdown` RPC to a
    non-detached broker, asserts exit 0.

Baseline suite: 88 tests, 82 pass, 6 fail pre-existing (status/result
caching in test state — unrelated). With this patch: 90 tests, 85 pass,
6 fail. +3 new passing tests, no regression.

Upstream pointer
----------------
Why the Codex CLI can exit mid-turn without flushing `turn/completed`
is orthogonal to this PR and belongs in `openai/codex`. The watchdog
here makes the companion resilient regardless.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Root cause
----------
`captureTurn` (plugins/codex/scripts/lib/codex.mjs) blocks on
`state.completion`. Two existing resolution paths both require server
cooperation:

  A. `turn/completed` notification from Codex app-server
  B. `finalAnswerSeen + scheduleInferredCompletion` (fires 250ms after
     an `agentMessage` with `phase === "final_answer"`)

When the Codex CLI exits mid-turn — rate limit, OOM, internal error,
token limit — neither fires: the only `agentMessage` had `phase ==
"plan"` so `finalAnswerSeen` stayed `false`, and no `turn/completed`
was ever sent. `state.completion` hangs indefinitely. The node
companion process itself exits cleanly via IPC EOF, bypassing
`runTrackedJob`'s try/catch, leaving a zombie job record
(`status: "running"`) and no final verdict. Observed three times in
the wild on 2026-04-18 while running `/codex:adversarial-review` from
Claude Code.

In broker mode (`app-server-broker.mjs`) the bug was worse: the broker
did not watch the upstream `appClient`, so when the Codex CLI died the
broker kept accepting socket connections. Clients got neither
`turn/completed` nor a socket EOF.

Fix (three coupled changes, one semantic unit)
-----------------------------------------------
1. `captureTurn` subscribes to `client.exitPromise` as a third
   resolution path. If a `final_answer` agentMessage has already been
   captured AND no subagent work is outstanding, honor the existing
   inferred-success semantics — call `completeTurn(state, null, {
   inferred: true })` without the 250ms debounce, which is meaningless
   on a dead socket. Only when no terminal signal was captured do we
   synthesize a `failed` turn so `buildResultStatus` returns non-zero.

2. `app-server-broker.mjs` subscribes to the upstream
   `appClient.exitPromise` and tears down the server when the Codex
   CLI dies. Connected clients receive socket EOF and the watchdog in
   openai#1 resolves their `captureTurn`. Broker exits with status 1 so
   supervisors can restart it.

3. The broker watchdog skips when `shuttingDown` is true. Without this
   guard, intentional teardown paths (`broker/shutdown`, `SIGTERM`,
   `SIGINT`) all call `shutdown(server)` → `appClient.close()` which
   resolves the same `exitPromise`, re-entering `shutdown()` and
   racing `process.exit(0)` with `process.exit(1)`.

Why the obvious small fixes were rejected
------------------------------------------
  - Relax `finalAnswerSeen` to any `lifecycle === "completed"`
    agentMessage: changes semantics for well-behaved turns; can commit
    prematurely on intermediate plan-phase messages.
  - Only a max-turn timeout: loses `lastAgentMessage` diagnostic, fires
    on legitimately long turns, and doesn't catch fast disconnects.
  - Broker-side timeout alone: doesn't help direct-transport callers.

Tests
-----
Three regression tests in `tests/runtime.test.mjs` against new fake
behaviors in `tests/fake-codex-fixture.mjs`:

  * `adversarial review resolves when app-server disconnects before
    turn/completed` — plan-phase agentMessage then disconnect; asserts
    non-zero exit + rendered output mentions the disconnect.
  * `adversarial review preserves final_answer when app-server exits
    before turn/completed` — final_answer agentMessage then
    disconnect; asserts exit 0 + structured findings survive.
  * `broker exits cleanly on broker/shutdown without tripping the
    upstream-exit watchdog` — sends `broker/shutdown` RPC to a
    non-detached broker, asserts exit 0.

Baseline suite: 88 tests, 82 pass, 6 fail pre-existing (status/result
caching in test state — unrelated). With this patch: 90 tests, 85 pass,
6 fail. +3 new passing tests, no regression.

Upstream pointer
----------------
Why the Codex CLI can exit mid-turn without flushing `turn/completed`
is orthogonal to this PR and belongs in `openai/codex`. The watchdog
here makes the companion resilient regardless.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Addresses findings from Codex review of the previous three commits.

Finding openai#1/openai#9 — Dual-writer race hardening:
  Introduce state.applyJobPatchIfActive(cwd, jobId, patchOrBuilder, predicate)
  as a single atomic read-check-write primitive for per-job transitions, and
  route reconcileDeadPidJobs, runTrackedJob's failure catch, and the progress
  updater through it. Because every fs operation inside the helper is
  synchronous, the read-check-write sequence cannot interleave with another
  async writer in the same process, so timeout/reconcile/progress updates
  can no longer clobber each other's metadata. Callers can supply a stricter
  predicate (reconcile still requires matching dead-pid identity).

Finding openai#4 — Late progress events after terminal state:
  createJobProgressUpdater now goes through the CAS helper. Once a job has
  been written to a terminal status (completed/failed/cancelled), any late
  progress event from a still-running runner is dropped instead of silently
  rewriting phase/updatedAt/turnId on top of the failed record.

Finding openai#9 — "aborted" language was misleading:
  The hard-timeout error message and the /codex:status renderer no longer
  claim the runner was aborted. Both now say "job marked failed; underlying
  runner may still be executing" so users know they may need to kill the
  worker manually.

Finding openai#8 — Regression coverage:
  tests/process.test.mjs: isProcessAlive edge cases (live pid, dead pid,
  malformed values, numeric-string pid).
  tests/state.test.mjs: applyJobPatchIfActive (applies on active, skips on
  terminal, honours PID-identity predicate, no-throw on missing file);
  listJobs reconciliation (happy path, live-pid no-op, both TOCTOU guards).
  tests/tracked-jobs.test.mjs (new): createJobProgressUpdater writes on
  active, drops on terminal (locks in the Finding openai#4 fix), no-ops on
  unchanged patch.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Follow-up to 42ed4e3 per second Codex review round.

Finding openai#2 — predicate API footgun (MEDIUM):
  applyJobPatchIfActive now ALWAYS enforces the built-in active-state
  gate (status == queued|running). Callers supply an `extraGuard` that is
  an additional AND check, not a replacement. Renames the parameter from
  `predicate` to `extraGuard` to make the composition explicit.
  reconcileDeadPidJobs loses the redundant defaultActivePredicate check it
  was manually composing into its own predicate.

Finding openai#7 — reconciler returned in-memory list missing updatedAt (LOW):
  Helper now stamps `updatedAt: nowIso()` onto every applied patch before
  persisting, and includes it in the returned `patch`. The reconciler's
  `applied.set(id, result.patch)` therefore automatically propagates the
  new timestamp to the in-memory job list callers iterate over.

Finding openai#5 — test coverage gaps (MEDIUM):
  tests/state.test.mjs: active-state gate is not bypassable by a liberal
  extraGuard; applied patch includes stamped updatedAt.
  tests/render.test.mjs: /codex:status output for timed-out jobs contains
  the corrected language and no longer says "runner watchdog aborted";
  autoReconciled jobs render with PID context.

Not addressed — Finding openai#1 (cross-process race):
  Deferred. Within a single companion process the CAS helper's synchronous
  read-check-write is tight. Crossing processes would require an OS-level
  lock (flock/tmpfile+rename/sqlite) that is out of scope for a personal
  fork given the practical blast radius is metadata clobbering rather than
  data loss.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

`/codex:adversarial-review` against commit 2b576cf flagged three real edge
cases in the W1 stability fixes. All resolved here in one commit since they
share a single concern (the original W1 only addressed happy-path failures)
and the fixes are surgical.

Fix #1 (high) — lib/broker-lifecycle.mjs sendBrokerShutdown socket cleanup
  Previously the 5 s timeout resolved without closing the net.Socket, so
  a referenced open socket could keep the SessionEnd hook process alive —
  defeating the timeout exactly when the broker is unresponsive (the case
  it was added to fix). Now finish() destroys the socket before resolving
  and carries a { timedOut } payload for caller telemetry.

Fix #2 (high) — lib/job-control.mjs crashed status persistence
  enrichJob set status='crashed' only on the in-memory copy. Stored jobs
  stayed 'running', so resolveResultJob refused crashed jobs via
  /codex:result, and resolveCancelableJob could still target a dead PID
  (false-positive kill risk under PID reuse). Now:
  - enrichJob persists the transition via upsertJob + per-job file write
  - resolveResultJob accepts 'crashed' as a finished state
  - resolveCancelableJob runs an enrichment pass first, then filters out
    jobs whose PID is already dead

Fix openai#3 (medium) — app-server-broker.mjs idle shutdown broker.json cleanup
  shutdown() removed only the unix socket and pid file; broker.json
  (persisted session) was left behind. Next /codex:setup or status would
  try to reuse the dead endpoint. Now clearBrokerSession(cwd) runs in
  shutdown() for both signal-driven and idle-timeout paths.

Verified locally: enrichJob + persist round-trip writes status=crashed,
pid=null, completedAt to state.json on dead PID; node --check on all
three modified files.

This commit demonstrates the fork's review-driven hardening pattern:
codex-companion adversarial-review → Codex finds gaps → Claude applies
fixes. Pattern continues for future review rounds.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

…th the release sprint

README updates:

- /codex:review surface lists --branch, --max-findings, --profile, --fast
  alongside the existing --base / --wait / --background flags
- /codex:rescue surface lists --profile, --resume-id, --context, --fast,
  --full-access / --dangerously-skip-permissions, --prompt-stdin /
  --prompt-file, with examples for each. Sandbox notes call out the v2.0.0
  default-inherit change and link to MIGRATION_v2.0.md

MIGRATION_v2.0.md (new):

- TL;DR env-var rollback (one paragraph for v1.x parity)
- BREAKING #1 sandbox default inherit — before/after table + opt-out env +
  per-command override + fix issue list (openai#240 / openai#167 / openai#304)
- BREAKING #2 Codex home isolation — before/after table + opt-out env +
  optional session migration (cp -r) + fix issue (openai#282)
- Per-environment migration checklist (Linux bwrap / macOS Seatbelt / CI /
  Windows Git Bash)
- New feature surface table (--profile / --resume-id / --context / --fast /
  --branch / --max-findings / --full-access / --prompt-stdin)
- All seven v2.0.0 env vars in one table (sandbox default, default home,
  skip auth, suppress notice, broker idle grace + interval, finalizing
  phase timeout)
- FAQ for the split-train rationale, behavior detection, per-project
  rollback, CI silent-break recovery, change-log index

TROUBLESHOOTING.md (new):

- Symptom index linking 11 known failure modes to fix references
- Each entry: symptom + root cause + v2.0.0 fix or pre-v2 workaround
- Covers rate-limit rewake loop (openai#306), large prompt rejection (openai#308),
  zombie running state (openai#222 / openai#264), 600s Bash limit (openai#122), Windows
  cross-drive MODULE_NOT_FOUND (openai#285), gpt-5.5 400 (openai#199 / openai#276 / openai#270),
  bwrap on VPS (openai#240 / openai#167), worktree+background hang (openai#198), stale
  auth cache (openai#281), identical default session names (openai#283), Codex
  Desktop history pollution (openai#282)
- Final section enumerates upstream investigations in progress (openai#295,
  openai#277, openai#310, openai#141) so users can match symptoms to known gaps before
  filing duplicates

No code changes.

…R-9.1, PR-9.2)

Phase 9 introduces a local-only append-only telemetry stream so operators
can stitch together every event for a single job lifecycle across the
broker / worker boundary without having to manually correlate log lines.

What lands in this PR
---------------------

- plugins/codex/scripts/lib/telemetry.mjs (NEW)
  - SCHEMA_VERSION = 1, EVENT_NAMES + ERROR_CLASSES frozen public arrays.
  - createTraceId() — 16-char (64-bit) hex correlation id.
  - emitEvent(event, fields, { env, now }) — append-only JSONL writer to
    ${CLAUDE_PLUGIN_DATA}/telemetry/events.jsonl. Failure-tolerant by
    construction: never throws, returns false on any I/O or schema error.
    Unknown fields go under `extras` so the schema can grow additively.
  - CODEX_PLUGIN_TELEMETRY_DISABLED env var short-circuits every entry
    point before any filesystem call (perf-safe).
  - CODEX_PLUGIN_TELEMETRY_DEBUG=1 surfaces swallowed write errors on
    stderr; off by default so production stays quiet.

- plugins/codex/scripts/lib/tracked-jobs.mjs
  - runTrackedJob now prefers job.traceId (propagated by upstream) and
    falls back to createTraceId() for foreground tasks that had no prior
    emit. Emits started / completed / failed at the three lifecycle
    transitions, with elapsedMs computed from startedAt.
  - markJobTerminated emits a `terminated` event with errorClass: "other"
    + the originating signal name.

- plugins/codex/scripts/codex-companion.mjs
  - enqueueBackgroundTask attaches a fresh traceId to the queued record
    AND the request payload (so the detached worker inherits it), writes
    `trace.id=<hex>` into the job log header for ad-hoc grep, and emits
    an `enqueued` event. The queued payload returned to the caller now
    carries traceId so /codex:rescue / /codex:review --background can
    echo it back to the user.
  - handleCancelCommand emits a `cancelled` event with the cancel-specific
    fields (turnInterruptAttempted, turnInterrupted).

- tests/telemetry.test.mjs (NEW, 22 cases)
  - createTraceId hex shape + 1k collision-free sample.
  - emitEvent schema (v1 fields, ts shape, append semantics, extras
    routing for unknown fields, undefined/null drop).
  - CODEX_PLUGIN_TELEMETRY_DISABLED truthy/falsy parsing + short-circuit
    proof (no file created when disabled).
  - emitEvent never throws on FS errors (path-as-file ENOTDIR repro).
  - Schema invariants: EVENT_NAMES + ERROR_CLASSES frozen, content
    matches the documented JSONL consumer contract.
  - Source-level: companion + tracked-jobs import the helpers and emit
    at every documented hook (enqueued / started / completed / failed /
    cancelled / terminated). Queued payload exposes traceId.

- docs/MIGRATION_v2.0.md — new "v2.1.0 env vars (observability)" section
  for CODEX_PLUGIN_TELEMETRY_DISABLED + CODEX_PLUGIN_TELEMETRY_DEBUG.
- docs/TROUBLESHOOTING.md — telemetry stream explainer + opt-out + debug
  + jq one-liner for grepping by traceId, plus updated "when to file an
  upstream issue" checklist.

Codex audit findings (5) — all addressed before commit
-------------------------------------------------------

A pre-commit `codex:codex-rescue` audit on the runtime diff surfaced 5
findings. All are addressed in this same commit:

- Finding 2 (HIGH/blocker) — runTrackedJob's pre-run state persistence
  (writeJobFile + upsertJob) was outside the try/catch, so a synchronous
  throw there would skip BOTH the `started` emit AND the throw-path
  `failed` emit, leaving the job invisible to telemetry. Now wrapped in
  a try/catch that emits `failed` with stage: "pre-run-state-persist"
  + the inherited traceId before re-throwing.
- Finding 3 (LOW) — handleCancelCommand fell through to undefined
  traceId for jobs cancelled before any earlier emit. Now falls through
  to createTraceId() so the event still satisfies the "every event has
  a traceId" invariant documented in TROUBLESHOOTING.md.
- Finding 1 (MEDIUM) — concurrent JSONL append on Windows has no
  documented WriteFile atomicity guarantee. Added an extensive module
  doc-comment naming PIPE_BUF on POSIX, the Windows caveat, the
  lib/state.mjs lock pattern as the fix if concurrency grows, and an
  anti-pattern warning against silently switching to async I/O (which
  would re-introduce the race without a visible diff).
- Finding 4 (LOW) — `extras` had no documented frozen-schema contract.
  Added a "field-name reservation" doc-comment: once a name appears
  inside extras for any event, it is reserved at that position;
  promoting it to top-level requires a SCHEMA_VERSION bump (and
  demoting is forbidden).
- Finding 5 (LOW) — v2.0.0 env var table accumulated v2.1.0 telemetry
  rows mid-train. Split into a clearly labeled "v2.1.0 env vars
  (observability)" section so doc labeling tracks the actual release
  that introduced each var.

Each finding has a dedicated regression test (audit #1–#5) so the next
maintainer cannot silently undo any of them.

Out of scope for this PR
------------------------

- No first-run stderr notice for v2.1.0 — telemetry is local-only and
  off-pollutes only the plugin data dir. Acceptable to leave silent.
- No automatic rotation. Single ever-growing events.jsonl. Operators
  who care can rotate manually; we will revisit once a real volume
  signal exists.
- runtime.test.mjs has 4 pre-existing failures on clean main `c449aa2`
  (Windows temp-dir / fake-codex shim issues): "review accepts
  --background while still running", "status shows phases", "status
  preserves adversarial review kind labels", "result returns the
  stored output for the latest finished job by default". Confirmed
  unrelated to this PR via `git stash` + re-run on main; documented
  for the next runtime-test sweep.

Refs PR-9.1 + PR-9.2 in
docs/ultraplan/2026-05-16-130611-codex-plugin-cc-implementation-ultraplan.md.

…-4.5, openai#310)

Upstream codex CLI's JSONL parser assumes a UTF-8 byte stream on its
stdio. On a host where LANG / LC_ALL points at Big5 / GBK / EUC-* /
plain `C`, codex panics with `invalid utf-8 sequence` mid-run — the
most cited reproducer is zh-TW (`LANG=zh_TW.Big5`), but every
non-UTF-8 locale is affected.

The real fix lives in the codex CLI itself. This PR adds the
plugin-side mitigation: when buildPluginCodexEnv composes the spawned
codex child's env, it walks the POSIX locale precedence ladder
(LC_ALL → LC_CTYPE → LANG) and, if the effective locale is not
UTF-8, overrides BOTH `LC_ALL` and `LANG` for the child only — the
user's own shell env is untouched. A one-shot stderr notice surfaces
on the first override per process so the user is not surprised by a
silent locale rewrite affecting codex output formatting.

What lands in this PR
---------------------

- plugins/codex/scripts/lib/app-server.mjs
  - New `applyUtf8LocaleOverride(target, base)` pure function. POSIX
    precedence via `effectiveLocaleIsUtf8(env)` so LC_ALL=C with
    LANG=en_US.UTF-8 correctly triggers the override (the EFFECTIVE
    locale codex sees is C, not en_US.UTF-8).
  - `looksUtf8Locale(value)` recognizer for `.utf-?8`, `C.UTF-8`,
    `POSIX.UTF-8` (case-insensitive, accepts trailing modifiers like
    `@iso14651_t1` and double extensions like `.UTF-8.iso88591`).
  - Override target is platform-aware: `C.UTF-8` on POSIX (glibc
    portable sentinel, no locale data files needed), `en_US.UTF-8` on
    Windows (the codex CLI's Windows runtime layer is friendlier to
    real locale strings than to the synthetic `C.UTF-8`).
  - `CODEX_PLUGIN_PRESERVE_LOCALE=1` opt-out for users who need
    localized codex output (translated messages, region-specific
    formats) at the cost of the openai#310 crash risk.
  - Module-level `localeOverrideNoticeEmitted` latch + first-call
    stderr notice naming both the detected host LANG/LC_ALL and the
    opt-out env var.
  - `__resetAppServerNoticeCache()` test helper exposed alongside
    the existing repo convention (double-underscore prefix — see
    tests/state.test.mjs callers in lib/state.mjs).
  - `buildPluginCodexEnv` reorganized to compose home-isolation +
    locale-override as independent transforms; opt-out of one does
    NOT opt out of the other.

- tests/locale-utf8-mitigation.test.mjs (NEW, 26 cases)
  - applyUtf8LocaleOverride pure-function contract (UTF-8 variants,
    Big5 / GBK / C / unset paths, opt-out, immutability).
  - buildPluginCodexEnv integration (home isolation + locale overlay
    independence, stderr notice firing, second-call dedup).
  - Source-level invariants (function/constant presence, openai#310
    cross-references).
  - Audit-finding regression guards (#1 POSIX precedence including
    empty LC_ALL fall-through to LC_CTYPE, #3 Windows en_US.UTF-8,
    #4 latch-before-write attempted-once design, #5 test-helper
    convention, #6 GFM slug correctness).

- docs/TROUBLESHOOTING.md
  - New section #13 with symptom / cause / mitigation / opt-out /
    verify. The two old "Known investigations" bullets for openai#310 are
    removed from the bottom list since the mitigation now ships.

- docs/MIGRATION_v2.0.md
  - New "v2.1.0 env vars" section row for
    CODEX_PLUGIN_PRESERVE_LOCALE with cross-doc link to the
    TROUBLESHOOTING #13 explainer.

Codex audit findings (6) — all addressed in this commit
-------------------------------------------------------

A pre-commit `codex:codex-rescue` audit on the runtime diff surfaced 6
findings. Every one is fixed inline or explicitly documented as a
deliberate trade-off, each with a dedicated audit-* regression test:

- Finding 1 (HIGH) — POSIX precedence violation: LC_ALL=C with
  LANG=en_US.UTF-8 used to short-circuit on LANG (UTF-8) and skip
  the override, even though the EFFECTIVE locale codex sees is C.
  Now walks the LC_ALL → LC_CTYPE → LANG ladder explicitly.
- Finding 2 (MEDIUM) — broker reuse freezes the locale env at broker
  start. Mid-session LANG / LC_ALL changes need a broker restart.
  Documented as a deliberate trade-off (the realistic case is "user
  fixes locale, then resumes" which already needs a restart).
- Finding 3 (LOW) — Windows uses `en_US.UTF-8` instead of the
  glibc-ism `C.UTF-8` so the override actually takes effect on the
  Windows codex runtime.
- Finding 4 (LOW) — latch flips BEFORE the stderr write to keep the
  "attempted-once" semantic on a broken stderr (otherwise a noisy
  retry loop would emerge). Documented with comment + regression
  test.
- Finding 5 (LOW) — `__resetAppServerNoticeCache` export is
  test-only by convention (double-underscore prefix). No NODE_ENV
  gate because the repo's normal `node --test` entrypoint does not
  set NODE_ENV.
- Finding 6 (LOW) — MIGRATION cross-doc anchor slug corrected to
  match GFM's single-hyphen-at-`+` rule + stripped `openai#310`
  parentheses.

Out of scope for this PR
------------------------

- The upstream codex CLI fix. This PR is the plugin-side workaround
  while the parser issue is open upstream.
- Auto broker restart on mid-session locale change (audit finding
  #2). The current restart-required behavior is documented; revisit
  if a real user hits this case repeatedly.
- A diagnostic helper that surfaces the effective locale codex sees
  via `/codex:setup --json`. Worth a follow-up but not bundled here.

Refs PR-4.5 in
docs/ultraplan/2026-05-16-130611-codex-plugin-cc-implementation-ultraplan.md.

…rkflow (openai#122)

PR-3.3 introduced a one-line "long-running" hint inside the rescue agent
prompt, but it left two structural problems behind:

1. The agent's "Response style: do not add commentary before or after the
   forwarded codex-companion output" rule was in direct contradiction with
   the new "surface a one-line hint before task" directive. An honest reader
   would have to pick one and ignore the other.
2. The hint pointed at /codex:status and /codex:result generically, without
   mentioning the --wait variants — exactly the commands a user re-issuing
   with --background actually needs to round-trip a long job without active
   polling.
3. The README's "Start Something Long-Running" workflow predated openai#324 and
   never named the 600 s ceiling that motivates --background in the first
   place. New users have no first-class breadcrumb from the README to the
   actual constraint.

This PR fixes all three on the docs / prompt side (no companion-script
behavior changes — runtime code is intentionally untouched):

- agents/codex-rescue.md
  - Rename "Response style" → "Codex output handling" and spell out that
    the long-running routing notice is the single Claude-side exception to
    the verbatim-only rule. The hint must go BEFORE Codex output and never
    after.
  - Rewrite the long-running hint under an explicit "Long-running hint
    (openai#122)" sub-heading. The hint now names both /codex:status <jobId>
    AND /codex:status --wait <jobId>, both /codex:result <jobId> AND
    /codex:result --wait <jobId>, and re-states the "do not switch modes
    on the user's behalf" invariant from openai#324.

- skills/codex-cli-runtime/SKILL.md
  - Section heading carries the openai#122 reference + a "long-running heuristic"
    qualifier so a future SKILL reader can find the rationale.
  - Numbered the four steps the hint must contain (600 s ceiling, re-issue
    suggestion, poll command list, foreground-anyway invariant).
  - Cross-references openai#324 explicitly: "this hint is intentionally not a
    hard --background auto-promote" — guards against the next refactor
    accidentally re-introducing the stub-return failure mode.

- README.md
  - "Start Something Long-Running" workflow rewritten: names the 600 s
    Bash tool ceiling, mentions the agent-side notice, walks through
    --background → status / status --wait → result / result --wait, and
    introduces --cancel as the bail-out path. Same content as the agent
    prompt + SKILL but written for end users instead of subagents.
  - New "## v2.0.0 Defaults & First-Run Setup" section (PR-8.1 first
    slice) summarizes BREAKING #1 (sandbox inheritance) + BREAKING #2
    (home isolation) with the three equivalent auth-migration fixes that
    surfaced from the in-the-wild PR-3.3 dogfood (Option A copy /
    Option B CODEX_HOME login / Option C opt out). Links out to
    MIGRATION_v2.0.md and TROUBLESHOOTING.md for the full walkthroughs.

Contract tests (tests/rescue-background-policy.test.mjs, +9 cases):

- agent + SKILL both carry the "(openai#122)" heading.
- Both name all four poll-command variants (status / status --wait /
  result / result --wait).
- Agent's "Codex output handling" section explicitly allows the hint as
  the documented exception, places it before the verbatim output, and the
  old "Response style:" heading is gone (regression guard).
- SKILL cross-references the openai#324 stub-return reason so the no-auto-promote
  invariant cannot drift silently.
- README's two new sections (Start Something Long-Running v2 + v2.0.0
  Defaults & First-Run Setup) covered by their own assertion blocks with
  explicit checks for the three auth-migration fix lines, both opt-out env
  vars, and the cross-doc links.

tests/commands.test.mjs PR-3.3 assertion on the literal "600 s Bash limit
applies to foreground rescues" string loosened to /~?600 ?s/i — the
regression-relevant invariant is "the 600 s ceiling is surfaced", not the
exact wording, and the wording itself was rewritten by this PR.

Refs PR-3.6 + PR-8.1 in
docs/ultraplan/2026-05-16-130611-codex-plugin-cc-implementation-ultraplan.md.
Continues from PR-3.3 (openai#324) and PR-8.3 (in-flight as PR #2).

`executeReviewWithModel` 의 `sandbox: "read-only"` 하드코딩이
`docs/MIGRATION_v2.0.md` BREAKING #1 row 1 (review / adversarial-review 가 sandbox 를
omit 하고 `~/.codex/config.toml` `sandbox_mode` 를 상속) contract 와 drift 됨.
`sandbox: options.sandbox` 로 교체해 sibling `runAppServerTurn` 의 task 경로와 동일하게
`resolveSandboxValue` 헬퍼를 경유하도록 조정. v1 호환은 기존
`CODEX_PLUGIN_SANDBOX_DEFAULT=read-only` env opt-out 으로 유지.

`__testHooks` 에 `resolveSandboxValue` + `buildThreadParams` 노출하고 신규 회귀 가드
3건 추가 — omit / env-override / explicit caller value 3 경로를 runtime 으로 검증.
이전 source-level grep 가드 (`executeReviewWithModel` 내부 리터럴 부재 확인) 의
false-pass 가능성 차단.

fix(audit-followups): v2.1.0 metadata pin + /codex:result --wait support (AH/AJ/R)

…opnd-io-codex marketplace identity + legal review report

Codex 5th-reviewer 와 협력한 legal review (docs/legal-review/2026-05-18-192759-rename-opnd-io-codex.md)
의 5 blocking actions 를 적용. 사용자가 marketplace 에 `opnd-io-codex` 로
publish 의도 명시.

Verdict (Codex + Claude main 합의): **safe-with-conditions**. Apache 2.0
copyright 측면 (LICENSE/NOTICE) 정합이나 현 marketplace metadata 의 OpenAI
publisher identity 가 Apache 2.0 §6 + Lanham Act §43(a) false-association
위반 위험 → blocking fix 필수.

본 commit 의 5 blocking change:

1. `.claude-plugin/marketplace.json`:
   - `name`: `openai-codex` -> `opnd-io-codex`
   - `owner.name`: `OpenAI` -> `opnd-io`
   - `plugins[0].author.name`: `OpenAI` -> `opnd-io`
   - description 에 unofficial + Apache 2.0 + non-affiliation 명시

2. `package.json`:
   - `name`: `@openai/codex-plugin-cc` -> `@opnd-io/codex-plugin-cc`
     (npm `@openai` scope publish 는 org permission 차단 + Lanham Act
     false-association 양쪽 risk)
   - `version`: `2.0.0` -> `2.1.0` (이전 PR #1 의 d196be6 commit 에서 누락된
     bump 복구 — disk write race 추정)

3. `README.md`:
   - Title 에 `(opnd-io fork)` 추가
   - 첫 blockquote 를 "Unofficial fork ... Not affiliated with, sponsored by,
     or endorsed by OpenAI or Anthropic" non-affiliation disclaimer 로 시작
   - Apache 2.0 source attribution + LICENSE/NOTICE 명시
   - Codex CLI 의 separate installation 의무 + OpenAI terms 의무 + 데이터 전송
     주의 명시 (개인정보/보안 expectation management)
   - `/plugin marketplace add openai/codex-plugin-cc` -> `opnd-io/...`
   - `/plugin install codex@openai-codex` -> `codex@opnd-io-codex`

4. NPM publish: `@openai` scope 사용 금지. 본 PR 은 `@opnd-io` 로 변경만 처리,
   `private: true` 유지 (publish 결정은 사용자 영역).

5. `docs/legal-review/2026-05-18-192759-rename-opnd-io-codex.md` 신규:
   600 line 분석 결과 (Apache 2.0 §4-a/b/c/d/§6 / NPM scope / GitHub naming /
   Anthropic marketplace policy / user disclaimer / 한국·미국 trademark /
   edge cases 7 항목 / verdict + required/recommended/optional actions /
   출처 6 link).

Lawyer review recommended before public marketplace publish.

…ision (1.0.9→1.0.12)

Implements the verified reliability gaps from docs/reliability-backlog.md, TDD
throughout, each batch adversarially verified by agent workflows. +56 tests
(290 total, all green); `npm run build` clean (tsc); version sites in lockstep
at 1.0.12; CHANGELOG documents every item.

Batch 1 — most-defensive, smallest, pure-backend (1.0.9):
- openai#2 robust stdout JSONL parsing: AppServerClientBase.handleLine strips ANSI and
  skips non-JSON noise instead of tearing down the connection (and killing the
  turn) on the first unparseable line. New lib/strings.mjs#stripAnsi.
- openai#5 hook stdin tolerates EAGAIN/EWOULDBLOCK pipe jitter (new lib/hook-input.mjs;
  both hooks share it; returns {} instead of crashing and dropping session_id).
- openai#1 captureTurn idle watchdog (CODEX_TURN_IDLE_TIMEOUT_MS, default 0/off because
  delta notifications are opted out; rejects with the thread/turn id).

Batch 2 — process / connection lifecycle (1.0.10):
- openai#3 terminateProcessTree POSIX descendant sweep (via ps) + ESRCH→direct-kill
  fallback; close() reaps the codex app-server subtree on every platform.
  Deliberately did NOT detach codex (would orphan its subtree on a watchdog
  broker-reap) — the tree-walk covers both the close and reap paths.
- openai#262 broker reuse gated on the recorded pid being alive (isSessionStale), not
  just the endpoint answering.
- openai#303 (stale broker after account switch) deferred — conflicts with the
  shared-broker safety rules and needs a fresh on-disk auth probe (account/read
  through the long-lived broker returns its own stale cached account).

Batch 3 — output & failure visibility (1.0.11):
- openai#4 adversarial-review prompt capped under the ~1 MB Codex input limit with
  UTF-8-safe truncation (truncateToByteBudget) + a truncation notice.
- main() failures also emit a {"status":"error",...} envelope on stdout so the
  codex-rescue subagent (stdout-only) sees the failure.
- non-retryable turn errors short-circuit to failed (authoritative willRetry===
  false signal; narrow permanent-auth regex fallback), gated to the root thread
  so a subagent-thread error does not fail the parent.

Batch 4 — UX / observability + the openai#355 design decision (1.0.12):
- Background jobs survive SessionEnd: background:true marking, cleanupSessionJobs
  skips+retains them, and the shared broker is kept alive while any background
  job is active (shouldTeardownBroker + hasActiveBackgroundJobs).
- /codex:attach: live log tail that exits at terminal status; bounded
  (maxConsecutiveNullStatus + finite maxPolls) and cross-workspace aware.
- openai#6 cross-workspace job lookup: findJobByIdAcrossWorkspaces as a read-only
  fallback for an explicit id; default (no id) stays workspace/session-scoped.
- dispatch sentinel [[codex-task status=dispatched id=...]]; and app-server type
  alignment (requestAttestation capability; drop removed experimentalRawEvents)
  for a clean tsc build.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Address self-run adversarial review findings:
- openai#1 Defect C test moved from the watchdog-less review/review-start path to
  the investigation/turn-start path with the idle watchdog armed.
- openai#2 Task 4 end-to-end repro now models a busy-thread turn/start as a HANG
  (never opens), matching the evidence, with delayCompletedMs 600 > the old
  250ms inference so the test fails on unfixed code. Drops the queue-and-drain
  machinery.
- openai#3 Task 3 gate test withholds the real turn/completed entirely so cue-based
  inference on unfixed code is observably wrong.
- openai#4/openai#5 spec gains rationale for keeping the subagent-gated fallback and notes
  on completionTimer naming and the now-unread finalAnswerSeen.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>