docs(structure): record what clear-cooldown does to a lapsed window

[lidge-jun]

Summary

• Record in structure/providers/openai-tiers.md what fix(codex): let clear-cooldown lift an avoidance the cooldown outlived #4397 changed about the operator-facing clear-cooldown contract: because the cooldown is the shorter of the two durations, the state an operator usually finds is an expired cooldown with a live avoidance window, and that window alone now makes the operation succeed and report a clear. An account with neither still reports no change, which is what keeps the route from disclosing whether an account exists.

Verification

• Closes the documentation-ownership finding raised by review on fix(codex): let clear-cooldown lift an avoidance the cooldown outlived #4397. structure/INDEX.md maps src/codex/ to this document, and bun run structure:check runs in CI as part of gates.
• Documentation only; no source or test behaviour changes.
• Local tests, build, typecheck and install: NOT RUN under the standing restriction. Hosted CI is the gate.

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.

Summary by CodeRabbit

• Documentation
  • Clarified the behavior of the OpenAI provider cooldown-clear operation when an avoidance window remains active after cooldown expiry.
  • Documented outcomes for accounts with an active window and for accounts with neither state, including consistent “no change” reporting.

[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-12T11:47:52.712434Z	0819fd9	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.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[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: 810709d9-d51d-4019-b750-6b79ea39f974

📥 Commits

Reviewing files that changed from the base of the PR and between f2f1783 and 0819fd9.

📒 Files selected for processing (1)

• structure/providers/openai-tiers.md

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

---

📝 Walkthrough

Walkthrough

The provider contract now documents that cooldown clearing also handles live avoidance windows after cooldown expiry. It defines clear and no-change results without exposing whether an account exists.

Changes

OpenAI account-mode contract

Layer / File(s)	Summary
Cooldown-clear operation contract structure/providers/openai-tiers.md	Lines 107–112 document that a live avoidance window makes the clear operation succeed after cooldown expiry. They also document the no-change result when neither state exists.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 0819f

This documentation-only change clarifies existing clear-cooldown behavior without introducing runtime or deployment risk.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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 documentation change and accurately describes the clear-cooldown behavior for a lapsed avoidance window.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/260912-avoid-doc-clear

---

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]

리뷰 · 우선순위 56 / 80

이 PR은 방금 dev에 들어간 #4397의 문서 후속이다. #4397은 clearCodexAccountCooldown이 쿨다운이 이미 끝난 뒤에도 살아 있는 quotaAvoidUntil만으로 성공하도록 고쳤다. 쿨다운은 짧게(대략 최대 15분), 거절이 발표한 회피 창은 길게(대략 최대 6시간) 잡혀 있어서, 운영자가 대시보드나 ocx account clear-cooldown을 누르는 순간은 보통 “쿨다운은 없고 회피만 남음”이다. 그 계약을 코드만 고치고 structure/에 안 적으면, structure/INDEX.md가 src/codex/를 가리키는 SSOT와 실제 동작이 어긋난다. 이번 변경은 그 구멍을 메운다.

지금 dev의 structure/providers/openai-tiers.md에는 이미 “쿨다운 해제와 계정 지정이 회피 창을 같이 지운다”는 문장이 있다. 그런데 “쿨다운이 만료된 뒤 회피만 살아 있을 때도 해제 성공으로 보고한다”, “둘 다 없으면 변경 없음(계정 존재 여부를 알려주지 않음)”까지는 없었다. 이번 문단이 그 두 줄을 정확히 채운다. 코드 쪽은 src/codex/routing.ts의 clearCodexAccountCooldown이 liveCooldown || liveAvoidance일 때만 필드를 빼고, 둘 다 없으면 null이라 cleared: false를 유지하는 것과 한 줄로 맞는다. structure:check가 CI gates에 들어 있으니, 소유권 문서를 코드와 같이 맞추는 것이 이 저장소의 규칙이기도 하다.

범위는 문서만이다. 소스·테스트·제품 동작은 건드리지 않는다. #4396+#4397 기차가 연 쿼터 회피 탈출구를 운영자·후속 기여자가 읽을 수 있게 만드는 최소 보완이다. types.ts/config.ts 분리 캠페인, Hermes, remote-workspace 캐리와도 겹치지 않는다. #4397 리뷰에서 남긴 “문서 소유권” 지적을 닫는 PR로 보면 된다.

라인 107 근처 새 문단 - “쿨다운이 이미 끝난 창에 대한 관리 연산”이라는 설명이 #4397의 실제 운영 장면을 바로 가리킨다. 짧은 쿨다운·긴 회피라는 설계 이유까지 한 문장에 넣어서, 왜 그 상태가 흔한지 읽힌다.

라인 109~110 - “회피만 살아 있어도 성공·클리어 보고”, “둘 다 없으면 변경 없음 → 계정 존재 여부 비공개”가 코드의 cleared 계약과 같다. 존재 오라클을 막으려는 #4397의 안전 쪽 의도가 문서에도 남는다.

경로 structure/providers/openai-tiers.md - structure/INDEX.md가 src/codex/·src/config.ts를 이 문서로 매핑하므로, 여기 적는 것이 맞다. GUI 카피나 CLI 도움말 문구까지 손보지는 않았고, 이번 범위에서도 필수는 아니다.

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

• fix(codex): let clear-cooldown lift an avoidance the cooldown outlived #4397 직후 문서만 단독으로 바로 올릴지, 아니면 다음 작은 문서 묶음에 태울지
• 대시보드/CLI에 보이는 “쿨다운 해제” 문구를 “쿨다운·회피 해제”로 바꿀지(이름·카피는 후속)

너의 추천
CI(structure:check 포함) 초록이면 dev에 바로 머지한다. #4397이 고친 계약을 SSOT에 남기는 6줄짜리 문서 PR이고, 제품 리스크가 없다. GUI/CLI 문구 정리는 원하면 별도 이슈로 빼도 된다.

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

[lidge-jun]

Maintainer integration decision (dev only, per MAINTAINERS.md). Exact head 0819fd9c92c73b810829477d82833f9b916db091: all reported checks green; the heavy matrix is skipped by workflow path filters because this change is documentation only. Closes the ownership finding from #4397.