fix(codex): invalidate app-server observations at catalog boundaries

[yansigit]

Summary

Reset cached app-server observations after catalog/cache publication and before model sync, including no-op refreshes. A recent not-running observation must not mask a newly visible process after these boundaries. The new tests exercise the upstream asynchronous cached API; injected synchronous process IO bypasses its cache.

Updated the Codex App models guide. This observes process state without adding a restart.

Verification

bun run typecheck passed. bun test tests/codex-integration/codex-models-cache-invalidate.test.ts: 11 passed. Both new cache regressions fail when the reset calls are removed. Documentation frozen install and build passed.

All runtime checks used a fresh temporary OPENCODEX_HOME and alternate port; production config fingerprint and backup inventory remained unchanged. Full root-suite and review-readiness gates have not been completed for this head; this is intentionally a draft.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Added/updated regression coverage or verified existing coverage for the affected behavior.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness

• Local CI green.
• Branch on the latest dev commit.
• All correct Codex and CodeRabbit findings fixed.
• Ready-for-review confirmation.

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

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

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

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

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.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

Hygiene

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 66 / 80

이 PR은 Codex app-server 관측 캐시를 카탈로그/모델캐시 게시와 sync 경계에서 비웁니다. 지금 dev HEAD c15662855에는 이미 src/codex/app-server-processes.ts의 resetCodexAppServerCatalogStateCache / collectCodexAppServerCatalogStateForRequest가 있습니다. 주석도 “카탈로그 write마다 reset을 호출한다”고 가정하지만, src/codex/internal/catalog-writer.ts의 replaceActiveCodexCatalog / replaceCodexModelsCache와 src/codex/sync.ts syncModelsToCodex 성공 admission 직후에는 실제로 reset을 안 부르고 있었습니다. 그래서 최근 not_running 관측이 TTL 안에 남아 있으면, 카탈로그를 새로 쓴 뒤 프로세스가 떠도 native-default guidance가 옛 관측을 믿을 수 있습니다. 이 PR은 그 세 지점에 reset을 넣고, 비동기 cached API를 쓰는 회귀 두 개를 tests/codex-integration/codex-models-cache-invalidate.test.ts에 추가하며, docs-site/.../codex-app-models.md에 “재시작 없이 다음 요청이 process freshness를 다시 본다”고 적습니다. types/config 분할과 무관합니다.

라인 src/codex/internal/catalog-writer.ts · replaceActiveCodexCatalog / replaceCodexModelsCache - atomic write 직후 resetCodexAppServerCatalogStateCache()를 호출합니다. 카탈로그 바이트가 바뀌는 경계와 관측 세대가 맞춰집니다.
라인 src/codex/sync.ts · syncModelsToCodex - catalog no-op이어도 config injection 후 reset합니다. “내용은 같은데 프로세스가 새로 보임” 구멍을 막는 부분입니다.
라인 tests/.../codex-models-cache-invalidate.test.ts - 캐시에 not_running을 데운 뒤 invalidate/sync가 stale/재조회로 이어지는지 확인합니다. 동기 injected IO는 캐시를 우회한다는 점도 명시합니다.
경로 docs-site/.../codex-app-models.md - 운영자 문서가 코드와 같이 움직입니다. 재시작 API가 아니라고 못 박은 점이 좋습니다.
경로 draft - typecheck·포커스 11 tests 통과를 보고했지만 root-suite·readiness는 미완입니다.

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

• reset 호출을 writer/sync에만 둘지, refresh/다른 catalog 진입점에도 같은 invariant를 정적 검사로 잠글지
• Windows/Linux에서 app-server 스냅샷 IO 비용이 reset 빈도와 겹치는지
• Model catalog changes are not reflected in running Codex app-server until it is restarted #476/fix(codex): warn or restart stale app-server after sync #518 invalidate 게이트 이슈와 문구를 이 PR Closes로 묶을지, 문서만 교차참조할지

너의 추천
실사용자 증상(옛 not_running이 새 프로세스를 가림)을 정면으로 고칩니다. 포커스 테스트가 이미 실패/복구로 증명했다고 하니, CI 초록이면 draft 해제 후 머지하세요. HEAD에 이미 있는 reset API를 호출만 잇는 최소 랜딩이라 위험이 작습니다.

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

[lidge-jun]

Landed on dev in 9587750 via #4051, which carried seven reviewed contributor fixes as one sequential integration branch. Your commit is preserved in the squash body with a Co-authored-by trailer, so the contribution stays attributed to you.

Verification at the merged head 1e32dee6e: Cross-platform CI run 34259247029 finished with 19 jobs successful and 0 failures, bun x tsc --noEmit exit 0, and 657 focused tests passing across the twelve affected files. An independent review confirmed the stacked tree is byte-identical to the union of the seven PR diffs.

Closing this PR because the change is already on dev. Thank you.

[lidge-jun]

Landed via #4051 at 9587750