Skip to content

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

Open
luvs01 wants to merge 6 commits into
lidge-jun:devfrom
luvs01:agent/codex-cli-windows-deferred-reason-20260910
Open

luvs01 wants to merge 6 commits into
lidge-jun:devfrom
luvs01:agent/codex-cli-windows-deferred-reason-20260910

Conversation

@luvs01

@luvs01 luvs01 commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Summary

Report windows_inspection_deferred when Windows CLI inspection has no captured environment candidate, while retaining candidate_path_unavailable for ineligible captured paths and the existing POSIX result. This remains diagnostic-only and does not execute candidates or publish issue #2811 phase-two updater work.

Current author verification

  • Published head: f04973c3cc913f4775b7263e6e9ad154495fe17a.
  • Full ordinary CI run 34959335835 completed successfully on this exact published head; the run head SHA was verified. This is hosted execution, not a claim that the full matrix was repeated locally.
  • The branch remains within the repository's current allowed dev-drift window. No tip-only rebase was performed.
  • All known applicable inline and review-body findings have been addressed. Author implementation, current scoped validation and known review findings are complete. Maintainer approval and merge remain separate decisions.

Review readiness checklist

The validation checkbox refers to the explicit scope above. Historical run IDs and prior local results are not represented as new-head full-suite execution.

  • 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.

Summary by CodeRabbit

  • Documentation

    • Clarified ocx system codex-cli-update check behavior across supported languages.
    • Documented that Windows may report windows_inspection_deferred when no trusted candidate is available, while POSIX may report candidate_unavailable.
    • Documented that unsuitable Windows candidates, such as bare commands or remote paths, report candidate_path_unavailable.
    • Explained that Windows checks cannot confirm Codex CLI installation without an observed candidate.
  • Bug Fixes

    • Windows inspection results now accurately distinguish deferred inspection from an unavailable candidate.

@coderabbitai

coderabbitai Bot commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Review Change StackReview Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger 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 default and localized CLI documentation cover these platform-specific results and unsuitable Windows candidate paths.

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 for an unobserved candidate. Tests verify the Windows report fields, preserve candidate_unavailable for POSIX, and confirm zero filesystem calls.
CLI reference documentation
docs-site/src/content/docs/.../reference/cli.md, docs-site/src/content/docs/.../reference/cli/agents.md
The default and localized references document deferred Windows inspection, unchanged POSIX reporting, and candidate_path_unavailable for captured bare, remote, or device paths.

Priority: ⬇️ Low

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

Change: Bug fix

Merge Risk: 🔵 Low · up to f5602

The change has bounded impact, with remaining concerns limited to regression detection and documentation clarity rather than the runtime implementation.

🚥 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. (9 skipped: 9 …
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 a deferred result instead of treating the candidate as absent.
✨ 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

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

@github-actions github-actions Bot added the bug Something isn't working label Sep 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Deterministic PR hygiene checks passed.

@github-actions

github-actions Bot commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

✅ 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

Copy link
Copy Markdown
Owner

리뷰 · 우선순위 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
luvs01 force-pushed the agent/codex-cli-windows-deferred-reason-20260910 branch from 275f3f8 to 0002656 Compare September 10, 2026 04:51
@luvs01

luvs01 commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Sep 10, 2026

Copy link
Copy Markdown
Contributor
✅ 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.

@luvs01
luvs01 marked this pull request as ready for review September 10, 2026 05:22
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 10, 2026

Copy link
Copy Markdown

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-14T06:22:14.685763Z bc62253 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 Ingwannu left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@Ingwannu Ingwannu added the maintainer-sponsored Maintainer sponsors this change to an auth, workflow, release, or dependency surface label Sep 10, 2026
@luvs01
luvs01 force-pushed the agent/codex-cli-windows-deferred-reason-20260910 branch from 0002656 to a514091 Compare September 11, 2026 11:58
@github-actions
github-actions Bot marked this pull request as draft September 11, 2026 11:59
@luvs01

luvs01 commented Sep 11, 2026

Copy link
Copy Markdown
Contributor Author

Ready-for-review evidence

Rebased onto the current dev (f40e43234, package 2.52.0) and force-pushed with a lease on the previous head. The branch was behind the released v2.51.0 tag, so tests/ci-workflows/release-version-line.test.ts would have failed on any re-run; it is current now.

Local runbun test tests/codex-integration/codex-cli-install-provenance.test.ts: 7 pass / 0 fail.

No unresolved Codex or CodeRabbit findings on this PR.

@github-actions
github-actions Bot marked this pull request as ready for review September 11, 2026 12:54
@luvs01
luvs01 force-pushed the agent/codex-cli-windows-deferred-reason-20260910 branch from a514091 to 58ea8b6 Compare September 11, 2026 12:57
@github-actions
github-actions Bot marked this pull request as draft September 11, 2026 12:58

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 58ea8b6279

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread docs-site/src/content/docs/reference/cli/agents.md
@github-actions
github-actions Bot marked this pull request as ready for review September 11, 2026 13:06

@abhisheksharma2411 abhisheksharma2411 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The distinction is the right one — "I did not look" and "I looked and found nothing" are different answers, and #2811 is someone reading the second when the truth was the first. 17 pass / 2 skip / 0 fail on the head.

The thing I most wanted to check

windows_inspection_deferred is not a new reason — it is already emitted at cli-install-provenance.ts:632, on the path where a candidate was observed but deeper inspection is skipped. So after this change one reason string covers two states, and your description says consumers tell them apart via candidateAvailable / candidateSource.

That holds, and I traced it rather than assume: the only consumer of inspectCodexCliInstall is src/cli/codex-cli-update.ts:93, and it prints both fields adjacently:

candidate: ${report.candidateAvailable ? "yes" : "no"}
reason:    ${report.reason}

So the two deferrals surface as candidate: no / windows_inspection_deferred and candidate: yes / windows_inspection_deferred. Nothing in the tree switches on reason, so there is no branch to break — the overload is only a readability question, and the adjacent field answers it.

What I liked

The POSIX control is the part that makes this reviewable. Changing a reason string is exactly the kind of edit where the platform you did not touch quietly changes too, and a POSIX run with no observed candidate retains candidate_unavailable pins that it didn't. Asserting calls === 0 in both is the other half — the zero-I/O boundary is the premise of the whole argument, so a test that proved the new reason while silently reading a file would prove the wrong thing.

Widening the Windows assertions from two fields to nine is also worth it here: the claim is "everything else is unchanged", and previously only candidateAvailable and shim.status were holding that.

One small thing

The renamed test is now Windows reports a deferred inspection rather than an absent candidate, which describes the reason field — but the assertion that made the old name true (expect(calls).toBe(0), i.e. does not read persisted candidate state) is still in there and is still the load-bearing one. The old name is the invariant; the new name is this PR's symptom of it. Not worth a push, but if you touch it again, something like Windows defers without reading persisted candidate state keeps both.

LGTM.

@luvs01
luvs01 force-pushed the agent/codex-cli-windows-deferred-reason-20260910 branch from f560281 to b54013e Compare September 13, 2026 09:45
@github-actions
github-actions Bot marked this pull request as draft September 13, 2026 09:45
@luvs01
luvs01 marked this pull request as ready for review September 13, 2026 09:48

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b54013ee87

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/codex/cli-install-provenance.ts
@github-actions
github-actions Bot marked this pull request as draft September 13, 2026 12:29
@luvs01
luvs01 force-pushed the agent/codex-cli-windows-deferred-reason-20260910 branch from e1c3b67 to 6642ce7 Compare September 14, 2026 01:07
@github-actions
github-actions Bot marked this pull request as ready for review September 14, 2026 01:10
…sent candidate

On Windows the candidate-only provenance slice performs no candidate or
configuration filesystem I/O, so it never consults the persisted runtime
selection. When no proof-captured CODEX_CLI_PATH candidate is present it
nevertheless reported reason "candidate_unavailable", asserting that no Codex
CLI candidate exists even though availability was never observed. Operators
whose runtime resolves through persisted "configured" state therefore saw a
missing candidate while the runtime report showed a known version.

Report the deferral that actually occurred instead. The defined
"windows_inspection_deferred" reason already exists but was reachable only with
an environment candidate. POSIX does read persisted state, so its
absent-candidate answer is exact and stays unchanged.

No filesystem access is added: the Windows path still performs zero I/O, and
candidateAvailable, provenance, managed, selectionAttested, versionEvidence and
shim status are unchanged. This intentionally replaces the previous test
statement that pinned the "candidate_unavailable" wording on Windows.
Record the Windows inspection reason distinction in structure/runtime.md, which owns src/codex/, and qualify the direct-launch candidate_unavailable outcome as POSIX-only in all eight locale agent references.
@luvs01
luvs01 force-pushed the agent/codex-cli-windows-deferred-reason-20260910 branch from 6642ce7 to bc62253 Compare September 14, 2026 05:59
@github-actions
github-actions Bot marked this pull request as draft September 14, 2026 06:00
@luvs01
luvs01 marked this pull request as ready for review September 14, 2026 06:19
@github-actions
github-actions Bot marked this pull request as draft September 14, 2026 06:19
@github-actions
github-actions Bot marked this pull request as ready for review September 15, 2026 02:03
…78-author-followup-20260912

Co-authored-by: luvs01 <27862058+luvs01@users.noreply.github.com>
@lidge-jun
lidge-jun force-pushed the agent/codex-cli-windows-deferred-reason-20260910 branch from 39277bd to f04973c Compare September 15, 2026 10:41
@github-actions
github-actions Bot marked this pull request as draft September 15, 2026 10:42
@github-actions
github-actions Bot marked this pull request as ready for review September 15, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working maintainer-sponsored Maintainer sponsors this change to an auth, workflow, release, or dependency surface review-ready

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants