Update README with plugin reload and setup instructions - #2

fix: remove hardcoded timeouts from task and review

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.

…-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).

#2

Dogfood discovery (2026-05-18, local installation after the v2.0.0 split-train
landed in fork main): `codex login` from a normal shell writes
`~/.codex/auth.json`, but the v2.0.0 plugin's spawned codex looks in
`~/.codex/claude-code/auth.json` instead (PR-5.6 home isolation). As a result
`/codex:setup` keeps returning `loggedIn: false` even after a clean
`codex login`, and the user has no in-doc breadcrumb telling them to copy /
re-login into the plugin home.

Both v2.0.0 docs now spell out the migration step + opt-outs:

- MIGRATION_v2.0.md (BREAKING #2 section)
  - New callout under "BREAKING #2 — plugin sessions land in ..." with the
    three equivalent fixes (one-time `cp`, write-through
    `CODEX_HOME=... codex login`, opt-out via `CODEX_PLUGIN_USE_DEFAULT_HOME=1`)
    and the rotation reminder.
  - New checklist item under "Migration checklist / One-time" so the auth
    migration is treated on equal footing with the sessions migration that
    was already listed.

- TROUBLESHOOTING.md (new section #12)
  - "Plugin says `loggedIn: false` after a successful `codex login`
    (v2.0.0 home isolation)" added with Symptom / Cause / Fix (3 options) /
    Verify / Related cross-link to #9.
  - Symptom index extended with the matching row.
  - All internal anchors use the GFM-correct slugs (avoids the pre-existing
    `#9-...--login` broken anchor in the rest of the file, kept as-is to
    stay in scope).

No code, schemas, or test fixtures changed. Existing test suite stays green
(17/17 on commands + rescue-background-policy).

Closes the in-the-wild dogfood gap captured in the PR-3.3 verification
session. Refs PR-8.3 in docs/ultraplan/2026-05-16-130611-codex-plugin-cc-implementation-ultraplan.md.

chore(rename): opnd-io-codex marketplace identity + legal review (Apache 2.0 §6 / Lanham Act §43(a))

…ning 9 KST

plan §Phase 5.0 BLOCKING + §Phase 5 — scheduler_status decision tree +
machine TZ probe + KST 09:00 → local cron 변환 + cron fallback + opt-out.

## 신규 lib (pure, R2-L2)
- env-probe.mjs — SCHEDULER_STATUS enum (UTC_AWARE / LOCAL_TZ_ONLY /
  MCP_UNAVAILABLE / UNKNOWN) + decideSchedulerStatus decision tree +
  kstNineToLocalCron ((TARGET_UTC + offset) mod 1440 / minute fraction
  지원) + buildProbeResult + validateProbe + hasDstRisk (America/Europe/
  Pacific/Auckland true, Asia/Seoul false — DST 봄/가을 1h drift 위험 추적)

## 신규 orchestrator
- schedule-setup.mjs — probeMcpInstalled (`claude mcp list`) +
  probeCronTzSupport (Phase 5 PoC heuristic) + probeMachineTz
  (Intl.DateTimeFormat.resolvedOptions + getTimezoneOffset) +
  state/daily-evolve-env-probe.json lazy create + state-migrator 통합 +
  buildGuidance — scheduler_status 별 등록 명령 / DST 경고 / opt-out 안내
- cron-fallback.sh — install/uninstall/status. CODEX_PLUGIN_DAILY_EVOLVE_
  DISABLED opt-out guard 자동 포함. MCP_UNAVAILABLE 또는 사용자 결정 #2
  시 fallback primary

## companion 강화
- `CODEX_PLUGIN_DAILY_EVOLVE_DISABLED=1` opt-out (exit 0)
- `--probe` flag — env probe 단독 실행 (Phase 5.0 BLOCKING) + guidance stderr

## 검증
- 신규 17 unit tests (env-probe): decision tree 4 branch + cron 변환
  (KST/UTC/LA/India 30분/invalid) + validateProbe + buildProbeResult +
  hasDstRisk + enum
- daily-evolve unit tests 184 → 201/201 pass. 회귀 0

Phase 5 PoC = probe + guidance 까지. Actual MCP registration 은 사용자
manual (`claude mcp call scheduled-tasks create ...`) 또는 cron fallback
(`bash cron-fallback.sh install`).

Phase 6 (Self-Evolve Meta Loop) 대기.

…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]>

Repeated findings for things that are intentional (e.g. a placeholder
token kept on purpose) drown out new ones on every /codex:review and
/codex:adversarial-review run. Let a repo list { path, type, reason }
entries in .codex-review-ignore; matching findings are never dropped,
only collapsed into a <details> block with the reason so the finding
stays visible on demand and still lets the checker report an
unrelated new bug in the same file.

v1 matching is intentionally loose (case-insensitive substring match
of path + type): structured, since /codex:adversarial-review already
returns per-finding JSON; paragraph-level for /codex:review, which
only has freeform text to work with. Revisit once openai#2's tmpdir spike
findings (DECISIONS.md) settle whether structured output becomes the
default for native review too.

Co-Authored-By: Claude Sonnet 5 <[email protected]>