feat(codex): start idle 5-hour windows on real requests without synthetic warmup

[codingbooo]

Summary

Fixes #5833 by adding an opt-in codexPool.startIdleWindows setting. When enabled, brand-new unbound conversation requests are routed to an eligible pool account whose 5-hour window has not started yet (0% usage with reset timestamp sliding ~5 hours ahead of observation time), starting its reset clock via real user traffic rather than synthetic warmup probes.

Changes

• Configuration: Added startIdleWindows: z.boolean().optional() under codexPoolSchema in src/config/schema/leaf-validators.ts and src/types/config.ts.
• Idle Window Detection & Steering: Added src/codex/routing/idle-window.ts to detect idle accounts and steer initial requests.
• Routing Invariants:
  • Bound conversations (thread affinity, family affinity, model detour) are never diverted.
  • Manual pins and unspent manual preferences take precedence.
  • Accounts are steered at most once per window (deduplicated per window boundary).
  • Inactive/paused/drained accounts are ineligible; fails closed to ordinary selection strategy.
• Testing: Added tests/codex-integration/codex-idle-window.test.ts covering 26 regression scenarios (all passing).

Validation

• bun x tsc --noEmit: 0 errors
• bun test tests/codex-integration/codex-idle-window.test.ts: 26 passed, 0 failed
• bun test tests/config/config-load-degrade.test.ts: passed

Review readiness checklist

• Required local validation passed; commands, results, and any full-suite exception are documented.
• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• I resolved all correct Codex and CodeRabbit findings.
• My PR is ready for review.

Review readiness checklist

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

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features
  • Added the optional codexPool.startIdleWindows setting, disabled by default. When enabled, eligible new requests may be routed to an account with a verified, unused five-hour quota window. Existing conversation and account preferences take precedence, and requests continue through normal routing when no account qualifies.
• Documentation
  • Documented the setting, account eligibility requirements, and routing behavior.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

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

Review readiness checklist

• ✅ Required local validation passed; commands, results, and any full-suite exception are documented.
• ✅ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ✅ 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

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 5f775988-2945-41f1-b457-4df86ab173dd

📥 Commits

Reviewing files that changed from the base of the PR and between 7ea48b9 and a3ebe2c.

📒 Files selected for processing (11)

• docs-site/src/content/docs/guides/codex-integration.md
• scripts/test-layout/layout.json
• src/codex/routing.ts
• src/codex/routing/idle-window.ts
• src/config/schema/leaf-validators.ts
• src/types/config.ts
• structure/config.md
• structure/providers/openai-accounts.md
• tests/codex-integration/codex-idle-window.test.ts
• tests/config/config-load-degrade.test.ts
• tests/fixtures/test-layout-expected.json

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds opt-in Codex idle-window steering. Eligible unbound requests can select an account with a fresh observation of an idle five-hour quota window. Routing preserves affinity and account preferences, and ordinary routing applies when no account qualifies.

Changes

Idle-Window Steering

Layer / File(s)	Summary
Setting and steering contract src/types/config.ts, src/config/schema/leaf-validators.ts, structure/config.md, structure/providers/openai-accounts.md, docs-site/src/content/docs/guides/codex-integration.md	Adds the optional codexPool.startIdleWindows boolean and documents its default, eligibility conditions, precedence, and reservation behavior.
Idle-window selection and routing src/codex/routing/idle-window.ts, src/codex/routing.ts	Adds idle-account eligibility checks and process-local reservations. Preview and detailed routing try selection when affinity and release conditions allow. Health reset clears steering state.
Steering validation and test registration tests/codex-integration/codex-idle-window.test.ts, tests/config/config-load-degrade.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json	Tests cover setting validation, routing, eligibility, precedence, and reservation behavior. The test-layout configuration and fixture include the new integration test.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CodexRequest
  participant CodexRouting
  participant IdleWindowSelector
  participant AccountPool
  CodexRequest->>CodexRouting: Submit unbound request
  CodexRouting->>IdleWindowSelector: Try selection when affinity conditions allow
  IdleWindowSelector->>AccountPool: Check eligibility and reserve matching account
  AccountPool-->>IdleWindowSelector: Return eligible account or no match
  IdleWindowSelector-->>CodexRouting: Return selected account or null
  CodexRouting-->>CodexRequest: Return selected account or continue ordinary routing

Loading

Merge Risk: ⚪ Minimal · up to a3ebe

No actionable idle-window steering issue remains. The reviewed change is mergeable after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to a3ebe

The feature is off by default and preserves existing account bindings and ordinary routing fallback. No introduced security vulnerability was established. The remaining uncertainty is whether the reservation behavior works as intended across all deployed instances.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — With the option enabled, an unbound request can influence which eligible configured pool account receives its traffic and when that account’s idle quota window starts. The demonstrated scope is account placement within the configured pool, not a new request-controlled configuration field.

Trust Boundaries and Controls

• observed — The setting is consumed from configuration and requires true; established affinity and release state are checked before the idle-placement branch. The available source does not establish who may mutate the runtime configuration instance.

Resilience and Maintainability Implications

• observed — Invalid or stale window evidence is rejected, and an idle-selection miss falls through to ordinary routing. The committed reservation is local to the routing process.

Hardening Proposals

• proposed — If production routes one pool through multiple processes, establish whether at-most-once steering is required globally and, if so, coordinate reservations across those processes. Confirm that only trusted configuration owners can enable the setting.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue [#5833] has coding requirements, and the reviewed changes implement them. src/config/schema/leaf-validators.ts and src/types/config.ts add the opt-in codexPool.startIdleWindows setting. `s…
Out of Scope Changes check	✅ Passed	The changes stay within issue [#5833]. The schema and type updates expose the requested opt-in setting. The routing helper and src/codex/routing.ts changes implement idle-window selection without sy…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: opt-in starting of idle five-hour Codex windows through real requests without synthetic warmup.

Full details: Docstring Coverage

Explanation

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

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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

[lidge-jun]

리뷰 · 우선순위 55 / 80

이 PR은 계정 풀에서 5시간 창이 아직 시작되지 않은 계정을, 가짜 요청 없이 깨우는 스위치입니다. 이름은 codexPool.startIdleWindows이고, 기본값은 꺼짐입니다. 켜 두면, 아직 어느 계정에도 묶이지 않은 진짜 요청 하나를 골라 그 계정으로 보냅니다. 조건은 짧습니다. 짧은 창 사용량이 0%이고, 창 길이가 5시간(18,000초)으로 적혀 있고, 관측이 5분 안이며, 리셋 시각이 관측 시각에서 5시간 뒤와 1분 안으로 맞아야 합니다. 그 요청이 그 계정의 시계를 시작합니다. 그다음 요청부터는 원래 고르기 방식으로 돌아갑니다. 이미 묶인 대화, 고정한 계정, 사람이 방금 고른 계정은 건드리지 않습니다. 같은 계정은 그 창에서 한 번만 고릅니다. 맞는 계정이 없으면 예전처럼 고릅니다. 스물여섯 가지 경우가 테스트로 덮여 있습니다.

src/types/config.ts - 주석이 동작을 반대로 적습니다. "풀이 초기화될 때 창을 시작한다"고 되어 있는데, 코드는 풀을 켤 때 아무것도 보내지 않습니다. 스위치가 켜져 있을 때, 묶이지 않은 새 요청만 놀고 있는 계정으로 보냅니다.

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

• 같은 이슈 #5833을 다루는 PR #5834가 초안으로 아직 열려 있습니다. 둘 다 src/types/config.ts와 설정 스키마에 startIdleWindows를 넣습니다. 둘 다 머지하면 같은 설정이 두 번 들어옵니다.
• 이슈에 적힌 대로, "0%이고 리셋이 관측 시각에서 5시간 뒤"라는 신호는 실제로 놀고 있는 계정의 응답으로 아직 확인되지 않았습니다. 1분 여유와, 안 맞으면 기존 방식으로 돌아가는 처리는 그 빈칸을 감싸 둔 것입니다.
• 한 번만 고른 기록은 이 프로세스 메모리에만 있습니다. 프록시를 다시 띄우면 기록이 사라지고, 같은 창을 다시 고를 수 있습니다.

너의 추천
#5949를 남기고 #5834는 닫는 쪽을 권합니다. #5949가 전용 테스트와 안내 문서를 갖췄고, 기준 브랜치도 dev입니다. 머지 전에 src/types/config.ts 주석만 실제 동작에 맞게 고치면 됩니다. 라이브 응답 확인이 없어도 머지를 막을 결함으로 보지는 않습니다. 스위치는 기본이 꺼져 있고, 신호가 안 맞으면 기존 계정 선택으로 돌아갑니다.

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

[lidge-jun]

Thanks! This landed on dev through enhancement merge train batch 10A, #5988 (merge 1972cdb). Your change is one commit on dev with you as the author and a Co-authored-by trailer. Closing since the content is now on dev.