fix(catalog): refresh Codex 0.151 shell contract

[lidge-jun]

Summary

• Refresh only the five Codex 0.151 catalog contract properties in the pinned native snapshot: canonical unified_exec, both node flags, plugin instructions, and app instructions.
• Canonicalize legacy default, local, and shell_command rows at the strict catalog boundary while preserving disabled, and materialize serde-compatible boolean defaults without overwriting explicit per-model booleans.
• Accept authentic unified_exec native rows during observed account-bound retention while keeping legacy shell_command rows accepted.
• Reference [Bug][Windows][Codex App] Generated catalog keeps the pre-0.151 schema: shell_type pinned to shell_command, four 0.151 fields never emitted #2896. The reported parser failure and app-server crash were not reproducible and the reporter withdrew that causal claim. Codex 0.151 accepts legacy shell_command as an alias, so this PR does not claim to fix parsing or a crash. It fixes the rejected authentic unified_exec row shape and restores the normal native include_plugin_usage_instructions: true behavior.

Verification

• bun test tests/codex-catalog.test.ts tests/native-model-toggle.test.ts tests/codex-tool-mode.test.ts — 265 pass, 0 fail.
• bun x tsc --noEmit — pass.
• bun run privacy:scan — pass.
• Mutation checks: shell canonicalization, disabled preservation, each boolean default, explicit include_apps_usage_instructions: false preservation, both accepted native shell spellings, and each pinned 0.151 snapshot property all went red when their implementation was mutated and returned green after restoration.
• Exact fallback-literal reversion note: reverting only the synthetic seed from unified_exec to legacy shell_command remains green because ensureStrictCatalogFields immediately canonicalizes that alias. The output assertions are therefore intentionally unable to distinguish those equivalent pre-normalization spellings; the final seed is still canonical.
• Not run by task constraint: repository-wide bun run test and bun run typecheck. The allowed direct TypeScript check above was run instead.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. No docs change is needed for an internal catalog normalization correction.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. This change touches no auth or secret path, and privacy:scan passes.

Summary by CodeRabbit

• New Features
  • Updated catalog entries to support the unified_exec shell type.
  • Added default support for Node REPL, plugin usage instructions, and app usage instructions.
  • Preserved compatibility with legacy shell configurations.
• Bug Fixes
  • Improved recognition and normalization of native catalog entries.
  • Ensured explicit per-model settings take precedence over defaults.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[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-08-29T13:26:19.260082Z	97addf3	PR opened

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: be738e2c-4901-43fb-b577-0b0ca290d1f3

📥 Commits

Reviewing files that changed from the base of the PR and between 8df7051 and 97addf3.

📒 Files selected for processing (7)

• src/codex/catalog/metadata.ts
• src/codex/catalog/parsing.ts
• src/codex/catalog/sync.ts
• src/codex/data/upstream-models.json
• tests/codex-catalog.test.ts
• tests/codex-tool-mode.test.ts
• tests/native-model-toggle.test.ts

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

---

📝 Walkthrough

Walkthrough

The catalog now canonicalizes shell entries to unified_exec, accepts legacy shell_command rows, applies Codex 0.151 field defaults, and updates upstream model records. Regression tests cover native, fallback, parsing, tool-mode, and toggle behavior.

Changes

Catalog contract and model configuration

Layer / File(s)	Summary
Normalize and expose catalog fields src/codex/catalog/metadata.ts, src/codex/catalog/parsing.ts, src/codex/catalog/sync.ts	ensureStrictCatalogFields normalizes legacy shell types and applies usage-field defaults. Native-row validation accepts unified_exec and shell_command. Fallback entries use unified_exec.
Update upstream model records src/codex/data/upstream-models.json	Listed models use unified_exec and define Node REPL, plugin usage-instruction, and app usage-instruction fields.
Validate catalog behavior tests/codex-catalog.test.ts, tests/codex-tool-mode.test.ts, tests/native-model-toggle.test.ts	Tests cover native and fallback entries, field normalization, explicit boolean overrides, tool modes, and acceptance of both shell types.

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

Merge Risk: ⚪ Minimal · up to 97add

This localized catalog compatibility update normalizes recognized shell types and preserves explicit model settings without introducing a concrete correctness, security, or availability risk. No actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: ingwannu

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 6 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the catalog fix and the Codex 0.151 shell contract refresh. This matches the primary changes to shell types, catalog normalization, and related contract fields.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 6 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/catalog-0151-shell-type

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 97addf3203

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

[chatgpt-codex-connector]

Keep the emitted shell type compatible with older Codex clients

When a user runs Codex 0.150 or earlier, rewriting every legacy shell_type to the newly introduced unified_exec value makes the generated catalog incompatible with that client's closed enum, so a subsequent ocx sync can cause Codex to reject the catalog rather than merely disable the affected model. Since Codex 0.151 still accepts shell_command as an alias, preserve that wire value or select the spelling based on the detected client version instead of unconditionally canonicalizing all rows.

AGENTS.md reference: src/AGENTS.md:L10-L10

Useful? React with 👍 / 👎.

[lidge-jun]

리뷰 · 우선순위 70 / 80

이 PR은 지금 dev HEAD 8df705120 (fix(cursor): name the invocation inside a replayed tool result (#2900)) 위에 올라탄 독립 카탈로그 버그픽스다.
merge-base가 그 커밋 그대로라 #2900 범위와 섞이지 않았다.
패키지는 2.36.0 라인이다.

지금 HEAD의 네이티브 스냅샷과 생성기는 아직 Codex 0.151 이전 모양이다.
src/codex/data/upstream-models.json 여덟 행이 전부 shell_type: "shell_command" 이고, src/codex/catalog/sync.ts 378행 폴백 시드도 같다.
src/codex/catalog/metadata.ts 551행 hasNativeCatalogRowShape 는 entry.shell_type === "shell_command" 를 요구한다.
그래서 Codex 0.151이 자기 models_cache.json 에 적어 둔 진짜 unified_exec 행은, 필드가 맞아도 네이티브 관측으로 안 남는다.
라우티드 자격 메타를 지우는 #2862 (routedCatalogEligibilitySanitized / findSupportedNativeTemplate / ensureStrictCatalogFields) 와는 축이 다르다. 이 PR은 셸 계약과 0.151 필드 네 개를 맞춘다.

#2896 이 그 불일치를 처음 적었다. 작성자는 나중에 크래시 인과를 철회했다. 프록시를 끈 뒤에도 app-server가 죽었고, 원인은 openai/codex#21761 쪽에 가깝다고 했다.
그래도 스키마 차이는 그대로다. 0.151 캐시는 unified_exec 이고, OpenCodex가 쓰는 카탈로그는 shell_command 이며 node_repl_disabled / node_repl_auto_review_required / include_plugin_usage_instructions / include_apps_usage_instructions 네 키가 없다.
0.151은 옛 shell_command 를 별칭으로 받는다. 이 PR은 파서/크래시를 고친다고 하지 않는다. 거절되던 진짜 unified_exec 행 모양을 통과시키고, 네이티브 스냅샷의 include_plugin_usage_instructions: true 를 되돌린다.

고치는 곳은 세 층이다.
첫째, 핀된 스냅샷 여덟 행에 0.151 계약 다섯 값을 넣는다. shell_type 은 unified_exec , 노드 REPL 두 플래그는 false, 플러그인 안내는 true, 앱 안내는 true.
gpt-5.6-sol/terra/luna 는 upstreamNativeEntry → finishUpstreamNativeEntry 로 그대로 나간다.
둘째, 모든 행이 지나가는 ensureStrictCatalogFields (src/codex/catalog/parsing.ts 434-440행) 에서 옛 default / local / shell_command 를 unified_exec 로 바꾸고, disabled 는 그대로 둔다.
빠진 불리언은 serde 기본값으로 채운다. 이미 boolean 인 값은 덮지 않는다. 머지 끝의 sync.ts 1092행도 이 함수를 다시 부르므로, 디스크에 남은 옛 행도 쓸 때 정규화된다.
셋째, 관측 유지 게이트 hasNativeCatalogRowShape 는 unified_exec 와 옛 shell_command 둘 다 받는다. 이 검사는 캐시 원본을 보므로, 정규화보다 앞선다. 둘 다 안 받으면 0.151 캐시가 다시 버려진다.
폴백 시드 (sync.ts 378행) 도 unified_exec 로 맞춘다.

테스트는 말한 돌연변이를 실제로 잡는다. 별칭 정규화, disabled 보존, 불리언 기본값, 명시 false 보존, 관측 철자 둘, 핀된 5.6 계약.
시드만 shell_command 로 되돌리면 경계가 다시 고쳐서 초록으로 남는다는 점도 PR이 적어 두었다.
types.ts/config.ts 분할 캠페인과는 무관하다. 이미 src/codex/catalog.ts 파사드 아래 catalog/* 모듈이다. close-don't-rebase 대상이 아니다.
리눅스 테스트 1/4~4/4, gates, hygiene 는 이 헤드에서 초록이다. macos 샤드만 아직 돌아가는 중이다.

라인 434 - default/local/shell_command 만 unified_exec 로 바꾼다. 빈 문자열이나 오타 같은 다른 값은 그대로 나간다. 같은 파일의 input_modalities 주석이 이미 말한다. 닫힌 enum 값 하나가 틀리면 Codex가 카탈로그 전체를 거절한다. shell_type 이 그 종류면 이 경계가 막지 못한다.
라인 439 - include_plugin_usage_instructions 의 serde 기본값은 false 다. 네이티브 스냅샷은 true 다. deriveEntry 가 네이티브 템플릿을 복제하면 라우티드 행이 true 를 물려받고, 템플릿이 null 인 폴백만 false 가 된다. 새 테스트는 buildCatalogEntries(null, ...) 폴백만 본다. 실제 동기화는 findSupportedNativeTemplate 를 쓴다.
라인 551 - hasNativeCatalogRowShape 는 unified_exec 와 shell_command 만 통과시킨다. 관측 캐시가 아직 default 나 local 이면, 정규화 전에 네이티브로 안 남는다. disabled 도 여기서 탈락한다.
tests/codex-catalog.test.ts 0.151 계약 루프 - 스냅샷 8행 중 gpt-5.6-sol/terra/luna 만 단언한다. gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.2, codex-auto-review 는 JSON만 바뀌고, upstreamNativeEntry 는 gpt-5.6 계열만 반환한다. 그 다섯 행은 런타임 교체 경로가 아니다.
경로 sync.ts:378 - 폴백 시드를 unified_exec 로 바꿔도, 그 한 줄만 되돌리면 ensureStrictCatalogFields 가 다시 고쳐서 테스트가 초록으로 남는다. PR이 적어 둔 그대로다. 시드 자체는 돌연변이로 안 잡힌다.

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

• macos 샤드가 이 헤드에서 초록이 된 뒤 바로 머지할지
• 쓴 카탈로그를 항상 unified_exec 로 통일할지, 옛 CLI(보고자는 ocx status 에 0.146)를 위해 shell_command 별칭을 버전 게이트로 남길지. 0.151 은 옛 철자를 받는다. 옛 클라이언트가 새 철자를 받는지는 이 PR이 증명하지 않는다
• 라우티드 행의 include_plugin_usage_instructions 를 네이티브 true 로 둘지, serde false 로 맞출지. 지금 템플릿 복제와 폴백이 갈린다
• [Bug][Windows][Codex App] Generated catalog keeps the pre-0.151 schema: shell_type pinned to shell_command, four 0.151 fields never emitted #2896 을 이 PR 머지와 함께 닫을지. 남은 주장은 스키마 불일치뿐이고 크래시는 철회됐다. Desktop 런타임과 핀된 CLI 세대가 어긋나는 문제는 이 PR 범위 밖이다

너의 추천
macos 가 이 헤드에서 초록이면 dev 로 머지하세요. #2896 에 남아 있던 스키마 구멍을 실제로 막는 독립 버그픽스다. 스냅샷만 고친 종이 변경이 아니다. 모양 가드, 엄격 필드 경계, 관측 유지가 같이 움직인다. 더러운 재포함도 없고 close-don't-rebase 대상도 아니다. 지금 보이는 원본은 이 PR 자체다. 머지 후 #2896 은 스키마가 맞았고 크래시는 철회됐으니 완료로 닫으면 된다. 원본이 따로 있으면 Landed via #2907 at <commit> 하고 landed-via-maintainer 로 닫으면 된다.

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