fix(codex): report a deferred Windows CLI inspection instead of an absent candidate

[luvs01]

Summary

On Windows, ocx system codex-cli-update check now reports windows_inspection_deferred when it obtains no environment candidate. The inspection deliberately does not read Windows candidate or configuration files, so it cannot establish installation absence. This addresses the confusing diagnostic reported in #2811; the wider updater request remains open.

The Windows zero-I/O boundary and all other report fields remain unchanged. candidateAvailable: false means this inspection obtained no candidate evidence. Consumers distinguish deferred reports with and without an observed candidate using candidateAvailable and candidateSource. POSIX retains its existing no-candidate result.

Verification

• Head 0002656fdbd9f3697cf71b591a07b11015fb1868, rebased onto dev 386b6a0d9a8acef818b9c40ebd472e4974750199.
• Windows regression failed on the unchanged base and passes after the reason correction. It asserts report fields and zero filesystem calls. The POSIX control rejects a relative configuration path before I/O and verifies that its existing reason is preserved; it does not prove persisted-state inspection.
• Five focused provenance, CLI, launcher and zero-effect suites on this head: 33 passed, 12 POSIX-only skips, 242 assertions. Typecheck and privacy scan passed.
• Documentation build: 425 pages; all eight generated CLI reference pages contain the updated reason. Rebase changed no authored documentation or build inputs.
• Current-head author cross-platform CI run 34438801853: 26/26 jobs passed, bound to 0002656fdbd9f3697cf71b591a07b11015fb1868. The checklist CI attestation refers to this completed matrix; local focused results are listed separately.
• Independent source review found no runtime blocker. Its comments about unobserved POSIX evidence were corrected; CodeRabbit completed the current-head review with no actionable finding.

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; no filesystem capability or credential handling is added.

Review readiness checklist

• All CI tests are green on my local testing.
• I pushed my PR to the latest dev commit.
• I resolved all correct Codex and CodeRabbit findings.
• My PR is ready for review.

Readiness base check: 7 commits behind current dev; within the repository allowance of ten.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 1e957fa6-4b9f-4bda-8911-fb17da357438

📥 Commits

Reviewing files that changed from the base of the PR and between 27836a0 and 0002656.

📒 Files selected for processing (10)

• docs-site/src/content/docs/fr/reference/cli/agents.md
• docs-site/src/content/docs/ja/reference/cli/agents.md
• docs-site/src/content/docs/ko/reference/cli/agents.md
• docs-site/src/content/docs/reference/cli/agents.md
• docs-site/src/content/docs/ru/reference/cli/agents.md
• docs-site/src/content/docs/tr/reference/cli/agents.md
• docs-site/src/content/docs/zh-cn/reference/cli/agents.md
• docs-site/src/content/docs/zh-tw/reference/cli/agents.md
• src/codex/cli-install-provenance.ts
• tests/codex-integration/codex-cli-install-provenance.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

The Windows Codex CLI inspection path now reports windows_inspection_deferred when no candidate is observed. POSIX continues to report candidate_unavailable. Tests and CLI documentation reflect the platform-specific behavior.

Codex CLI inspection reporting

Layer / File(s)	Summary
Platform-specific inspection result src/codex/cli-install-provenance.ts, tests/codex-integration/codex-cli-install-provenance.test.ts	The Windows branch returns windows_inspection_deferred. Tests verify the Windows report fields and preserve candidate_unavailable for POSIX.
CLI reference documentation docs-site/src/content/docs/.../reference/cli/agents.md	The default and localized CLI references document the Windows deferred-inspection result and the lack of persisted-state inspection.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: lidge-j

Merge Risk: ⚪ Minimal · up to 00026

Windows no-candidate checks now accurately report deferred inspection rather than implying the CLI is absent, without changing POSIX behavior or the no-I/O inspection boundary.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (8 skipped: 8 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: Windows CLI inspection now reports windows_inspection_deferred instead of candidate_unavailable when no candidate is observed.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request is already Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently.
Maintainers: @lidge-jun @Ingwannu

[lidge-jun]

리뷰 · 우선순위 52 / 80

설명

이 PR은 Windows에서 ocx system codex-cli-update check가 말하는 이유를 더 정직하게 바꾸는 작은 수정이다. 지금 dev HEAD(2b1146eee, #4156 free-model pricing 필터가 막 들어온 상태)의 src/codex/cli-install-provenance.ts를 보면, Windows 첫 조각은 후보·설정 경로를 파일시스템으로 읽지 않는다. 그래서 환경에 증명된 CODEX_CLI_PATH 후보가 없을 때 “후보가 없다”(candidate_unavailable)고 말하는 것은, 실제로는 “아직 안 봐서 모른다”인데도 더 센 말을 한 셈이다. 같은 설치에서 ocx status --json은 저장된 configured 경로로 버전을 보여 주는데, check만 “후보 없음”이라고 하면 Windows 사용자에게는 설치가 빠진 것처럼 보인다. 그 불일치가 #2811 캡처에서 나온 문제다.

고치는 방법은 새 기능을 넣는 게 아니다. 타입 CodexCliInstallReason에 이미 있는 windows_inspection_deferred를, 후보가 아예 관측되지 않은 Windows 분기에도 쓰도록 한 줄만 바꾼다. POSIX는 저장된 선택을 실제로 읽으므로 candidate_unavailable을 그대로 둔다. candidateAvailable, provenance, managed, shim 상태 같은 다른 필드는 건드리지 않고, Windows 경로의 파일시스템 I/O도 여전히 0이다. 테스트는 예전 “Windows는 persisted를 안 읽는다” 단언을 “deferred를 보고한다”로 바꾸고, POSIX 대조 테스트를 새로 넣어 Windows 전용 문구가 새어 나가지 않게 잠근다. 문서도 영문·한글 포함 8개 locale의 reference/cli/agents에 같은 설명을 맞춘다.

지금 dev가 최적화하는 방향은 Lane B(#3666 방금 착지 → 다음 #4075 Gemini setup UX → #1711 → #4038)와 Lane A 서비스 가드 쪽이다. 이 PR은 카탈로그/가격 분류와 파일 겹침이 없고, types.ts/config.ts 분할에도 걸리지 않는다. 베이스는 c15a98caa라 #4156 한 커밋 뒤지만 건드리는 파일(cli-install-provenance.ts + 테스트 + docs-site agents)과 #4156(catalog/GUI Free 필터)은 겹치지 않아 충돌 가능성은 낮다. 다만 작성자 체크리스트에 “ready for review”가 비어 있고 draft라서, 머지 큐에 바로 넣기보다는 준비 완료 표시와 CI 확인이 먼저다.

라인 591 - 현재 dev HEAD는 후보 없을 때 Windows도 아직 candidate_unavailable이다. 이 PR이 여기만 windows_inspection_deferred로 바꾼다. 의도는 맞지만, 이미 후보가 있을 때 나오는 windows_inspection_deferred(대략 632 근처)와 “후보 자체를 못 본 경우”가 같은 reason 문자열을 쓰므로, 나중에 로그/스크립트가 reason만으로 원인을 가를 수 없다.

tests/codex-integration/codex-cli-install-provenance.test.ts - Windows 테스트가 reason뿐 아니라 전체 report shape와 calls === 0을 같이 잠근 점은 좋다. POSIX 대조 테스트도 Windows 문구가 넓어지지 않게 막아 준다.

docs-site/.../reference/cli/agents.md (8 locale) - 설명 문장이 길어져 읽기 부담이 늘었지만, 동작과 문서가 같이 움직이는 쪽이라 범위는 맞다. 번역 품질은 기계적으로 맞춰 둔 수준으로 보이며, 의미 어긋남은 눈에 띄지 않는다.

PR 베이스 - c15a98caa 기준이고 tip dev는 #4156(2b1146eee)이다. 파일 겹침은 없어 보이지만, draft를 ready로 올리기 전에 dev에 리베이스(또는 merge)해 CI를 다시 돌리는 편이 안전하다.

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

• Feature: provenance-aware Codex CLI update manager #2811(provenance-aware Codex CLI update manager) 전체 중 이번 조각만 먼저 받을지, 핸들 바인딩 검사 레이어가 올 때까지 reason 문구 수정만으로 충분한지
• windows_inspection_deferred를 “후보 없음”과 “후보 있으나 깊이 검사 연기”에 같이 쓰는 게 괜찮은지, 나중에 reason을 쪼갤지
• draft + checklist 미완료 상태에서 리뷰만 남기고 기다릴지, 작성자에게 ready 전환을 요청할지

너의 추천
draft를 ready로 올리고 dev(현재 2b1146eee)에 리베이스한 뒤 CI가 초록이면, Lane B와 독립이니 작은 honesty 수정으로 병합해도 된다. #2811은 이 PR만으로 닫지 말고, Windows 검사 I/O가 실제로 가능해지는 후속 조각이 올 때까지 열어 둔다. types/config 분할과 무관하니 close-don't-rebase 대상은 아니다.

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

[luvs01]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[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-10T05:25:20.020920Z	0002656	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.

[Ingwannu]

Reviewed head 0002656. The production change is the reason on the no-observed-candidate Windows return. It does not add filesystem inspection, candidate execution, configuration writes, shim repair, or process control. The Windows regression observes the full unknown/unmanaged report and zero filesystem calls; the POSIX relative-config control preserves its existing reason but is not evidence about persisted POSIX state. Candidate-present lexical classification is unchanged. I independently verified author CI 34438801853 succeeded at this exact head. No new blocker found in this bounded diagnostic correction; sponsoring it for repository gates, not waiving those gates or approving the wider updater. #2811 should remain open. No local product execution was used.