fix(cli): preserve existing config during setup

[lidge-jun]

Summary

• Wire ocx init and its setup alias to exclusive initial configuration publication. Existing valid files are preserved before prompting; invalid or concurrently created files stop setup without overwriting them.
• Preserve a created config on later cancellation or partial failure. Carry cancellation through the existing Codex native-write commit guard so a queued injection cannot write after Ctrl+C; handle wrapped failures without printing false success.
• Add real CLI, collision, EOF/SIGINT and synchronized queued-lock regressions. Update the setup documentation. This completes the real consumer of the feat(config): add exclusive initialize-if-missing primitive #3632 carry; no overwrite flag or ordinary saver behavior is changed.

Track 3 manual stack, layer 6 and cumulative validation head. Depends on #3796. Earlier layers: #3786 -> #3788 -> #3789 -> #3790 -> #3796. The final branch incorporates dev through eff908e0 before validation. This is an ordinary branch chain, not a registered native stack.

Verification

• Independent Astra high C4 code/security review: PASS after fixing queued-injection cancellation. Separate integration audit: PASS after creating the fixture's explicit Codex home before CLI imports. Neither review claims runtime execution.
• git diff --cached --check passed. No local tests, typecheck, builds or suites were run, as explicitly requested by the maintainer.
• Final cumulative source and successful remote validation are recorded below.
• Lower automatic test runs are deferred with [skip ci] under the maintainer's explicit final-head-first policy. Missing/pending lower tests are not passing evidence. Only an actual failed final run triggers lower-ref isolation.
• Existing global CLI shim preflight and config-ownership metadata policy remain unchanged. No whole-process zero-write or future-uninstall ownership guarantee is claimed. Windows terminal SIGINT and actual Docker container recreation remain outside the written runtime proof.

Cumulative tested source: 9ea896737bd17085ebb8a69b3320c9cace61889e, based on dev eff908e0fb9452d5ff2952af1c5dafc1c4c35dd9.

• Cross-platform CI: all 25 jobs successful. Attempt 1 failed only the existing Windows cli-models first-child 15-second watchdog. One unchanged-head rerun of that shard completed 3,489 cases (3,465 pass, 24 skip, 0 fail); the first models case took 943 ms. The initial failure is retained; the slow phase remains unproven and no flakiness fix is claimed.
• Service lifecycle: Linux, macOS and Windows passed on the same source head.
• Documentation build: passed after checking out and asserting that exact source. Its isolated workflow-definition commit is different and is not part of this stack; no deployment occurred.
• Independent scoped code/security and integration reviews: PASS. The two earlier Windows fixture-budget changes retain production behavior and original assertions, backed by readiness controls and quota restart controls. Diagnostic workflows, instrumentation and mutations are excluded from delivery.

The maintainer explicitly authorizes dev admin integration and final-head-first validation for this manual chain: #3786 → #3788 → #3789 → #3790 → #3796 → #3802. Lower automatic tests are deferred with [skip ci], not represented as passing. No local tests, typecheck, builds or suites were run; pushes used --no-verify. Merge commits preserve source ancestry and suppress duplicate lower CI; fresh head/base/actor/review checks and resulting tree checks accompany each merge.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Co-authored-by: SB Yoon 44089734+yansigit@users.noreply.github.com
Co-authored-by: Yumi automation@sbyoon.com

Landing confirmed: merged into dev as f89b815090020f52089801b50f569a777bdfdc0a. The final chain merge is f89b815090020f52089801b50f569a777bdfdc0a; its tree 846b8ffc383fc0ba99486917bdfb820a0fa432ba equals the tested cumulative source. Source ancestry and every merge were verified after fetching dev.

Summary by CodeRabbit

• New Features

  • ocx init now creates configuration only when no configuration exists.
  • Initialization safely preserves existing, invalid, unreadable, or concurrently created configuration files.
  • Setup can be canceled with EOF or Ctrl+C, with clear status and error reporting.

• Bug Fixes

  • Improved handling of configuration publication failures, interruptions, and concurrent changes without overwriting user data.

• Documentation

  • Updated setup and local-state guides to explain initialization behavior, cancellation, and troubleshooting.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: ab44ef53-ef18-47a5-9a63-0393fd8b1ab9

📥 Commits

Reviewing files that changed from the base of the PR and between c2b4dc0 and 9ea8967.

📒 Files selected for processing (11)

• docs-site/src/content/docs/getting-started/for-agents.md
• docs-site/src/content/docs/getting-started/quickstart.md
• src/cli/init.ts
• src/config.ts
• src/config/initialize.ts
• structure/00_overview.md
• structure/02_config-and-codex-home.md
• tests/codex-integration/main-quota-provenance.test.ts
• tests/codex-integration/native-profile-manager.test.ts
• tests/config/config-mutation-lock.test.ts
• tests/service/init-eof.test.ts

---

📝 Walkthrough

Walkthrough

Changes

Config initialization and ocx init

Layer / File(s)	Summary
Atomic initial publication src/config/initialize.ts	Adds private temporary-file hardening, complete writes, no-replace hard-link publication, identity checks, safe cleanup, and typed publication errors.
Config state and persistence src/config.ts, tests/config/config-mutation-lock.test.ts	Adds initial-state observation and locked create-only persistence. Tests cover collisions, invalid paths, cleanup, permissions, lock handling, and byte preservation.
CLI preflight and cancellation src/cli/init.ts, tests/service/init-eof.test.ts	ocx init preserves existing or invalid configs, handles concurrent creation, supports EOF and SIGINT cancellation, and reports publication and lock failures. Integration tests cover these paths and later-write cancellation.
Initialization documentation docs-site/src/content/docs/getting-started/*, structure/*.md	Documents create-only initialization, no-replace publication, cancellation, failure behavior, and replacement-write semantics.
Integration test timing tests/codex-integration/main-quota-provenance.test.ts, tests/codex-integration/native-profile-manager.test.ts	Uses platform-specific spawn and readiness budgets for Windows and non-Windows tests.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant InitCLI
  participant ConfigInitializer
  participant FileSystem
  participant CodexIntegration
  User->>InitCLI: start ocx init
  InitCLI->>ConfigInitializer: observe config state
  ConfigInitializer->>FileSystem: inspect config path
  FileSystem-->>ConfigInitializer: missing, existing, or invalid
  ConfigInitializer-->>InitCLI: initial state
  InitCLI->>User: collect setup answers
  User-->>InitCLI: answers or cancellation
  InitCLI->>ConfigInitializer: initialize config if missing
  ConfigInitializer->>FileSystem: publish through no-replace hard link
  FileSystem-->>ConfigInitializer: created or publication failure
  ConfigInitializer-->>InitCLI: initialization outcome
  InitCLI->>CodexIntegration: inject config and install shim
  CodexIntegration-->>InitCLI: completion or cancellation

Loading

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/track3-init-cli-a4b0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 74 / 80

이전 층 #3796이 “없을 때만 hard-link로 처음 게시”하는 원시 연산이라면, 이 PR은 그 소비자를 ocx init에 꽂습니다. 지금 dev의 src/cli/init.ts는 위자드가 끝난 뒤 saveConfig(config)를 호출합니다. 이미 config.json이 있어도 원자 교체로 덮어쓸 수 있는 경로입니다. 이 변경은 시작 시 observeInitialConfigState()로 exists면 보관하고 종료, invalid(깨진 JSON·디렉터리·심볼릭 링크 등)면 파일을 건드리지 않고 에러로 멈춥니다. 위자드가 만든 후보만 initializePersistedConfigIfMissing으로 게시하고, 중간에 다른 프로세스가 파일을 만들면 created가 아니므로 즉시 중단합니다. Ctrl+C/EOF 취소를 InitCancelledError로 통일하고, 게시 전 취소는 파일을 안 남기며, 게시 후 취소는 만든 config를 지우지 않습니다. Codex inject 경로에도 beforeClientWrite 취소 가드를 넣었습니다. quickstart/for-agents·structure 문서에 “force/overwrite 없음, hard-link 실패 시 덮어쓰기 fallback 없음”을 적었습니다.

경로 확인: 실질 변경은 src/cli/init.ts, docs-site getting-started 두 문서, structure/00_overview.md·02_config-and-codex-home.md, tests/service/init-eof.test.ts입니다. CREDITS.md diff는 스택 헤드가 현재 dev(#3787 credits, 24c761a05)를 merge하면서 생긴 소음으로 보이며, dev의 CREDITS와 헤드가 동일합니다. 이 PR 고유 크레딧 작업이 아닙니다. base는 #3796 브랜치라 dev가 아닙니다. Track 3 꼭대기(#3786 → … → #3802)이고 아래 층이 모두 OPEN DRAFT라 바닥 누락은 없습니다. #3632 소비자 완성 층입니다. types/config 분할 무효 대상 아님.

src/cli/init.ts runInit early observeInitialConfigState - 기존/invalid을 덮지 않고 끝낸다. HEAD의 무조건 saveConfig 위험을 끊는다.
src/cli/init.ts initializePersistedConfigIfMissing 결과 - created만 진행. 경쟁 생성 시 setup stop.
src/cli/init.ts InitCancelledError / throwIfCancelled - 게시 전후 취소 의미가 문서와 같다. inject beforeClientWrite까지 이어진다.
src/cli/init.ts 에러 메시지 - InitialConfigPublicationError·lock·잔여 temp를 사용자에게 과장 없이 안내. 경로 redact.
docs quickstart/for-agents - force 플래스 없음·invalid 보존·hard-link 필수 한계가 코드와 맞다.
tests/service/init-eof.test.ts - 실 CLI·큐드 lock·stdout drain 회귀. Response가 consumed stdout을 거절하던 CI 실패 수리가 포함됨.
CREDITS.md - dev merge 소음. 랜딩 시 no-op이어야 한다.
Track 3 - base≠dev. 스택 완전. #3632 종결 소비자.

메인테이너의 판단이 필요한 지점

• Track 3 전체를 헤드 CI 통과 후 한 번에 올릴지, #3796+#3802만 먼저 dev에 올려 #3632를 해소할지
• feat(config): add exclusive initialize-if-missing primitive #3632 닫을 때 landing 코멘트/landed-via-maintainer 패턴을 이 꼭대기 머지에 묶을지
• CREDITS.md가 스택 diff에 끼어 있는 것을 squash/rebase 전에 정리할지(내용은 이미 dev와 동일)
• Windows Desktop lifecycle(fix: unblock Windows lifecycle tests and reduce Cursor blob admission cost #3771)과 init 보존이 같은 릴리스 노트에 같이 나갈지

너의 추천
Track 3 꼭대기로 #3796 직후 머지. 사용자에게 보이는 “init이 기존 config를 지운다” 사고를 막는 완성 층이다. #3632는 #3796+#3802 랜딩과 함께 superseded로 닫아라. 로컬 스위트 미실행이니 스택 헤드 Cross-platform CI를 게이트로 두면 된다. types/config 분할로 닫을 PR이 아니다.

이 댓글은 grok-bot이 작성했습니다

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T20:22:49.747685Z	9ea8967	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.