docs(devlog): plan the L3 retry, admission and combo-recovery unit

[lidge-jun]

Summary

• Record the L3 integration unit that reviews four open retry/recovery pull requests (fix(adapters): charge adapter-owned retry sends to the request send budget #4865, fix(retry): extend transient-5xx replay budget to openai-responses passthrough #4800, fix(combo): fail over zero-output SSE errors #4817, fix(combos): allow single-target combo with waitForCooldownMs to retry after cooling #4824) under one principle: a retry is acceptable when cost, waiting and duplicate execution stay bounded, not when it merely succeeds more often.
• Document why fix(combo): fail over zero-output SSE errors #4817 and fix(combos): allow single-target combo with waitForCooldownMs to retry after cooling #4824 are not a stack. Both are described as combo failover, but fix(combo): fail over zero-output SSE errors #4817 edits combo-stream-preflight.ts (how a streamed attempt is classified before output commits) and fix(combos): allow single-target combo with waitForCooldownMs to retry after cooling #4824 edits core-combo.ts (what the target loop does after a failure is classified). The change sets are disjoint, so the three follow-on PRs are verified independently instead of being serialised.
• Capture the completed static audit of fix(adapters): charge adapter-owned retry sends to the request send budget #4865's admission helper, including the one defect it found: mimo-free's 401 replay drains the first response after refreshing the JWT, so a throwing getMimoJwt leaks that body where the pre-change code did not.
• Capture the completed termination analysis for fix(combos): allow single-target combo with waitForCooldownMs to retry after cooling #4824 — the local dispatch bound, maxAlternateTargetSends, and the waitForCooldownMs ceiling are three independent bounds — and state the open questions for fix(retry): extend transient-5xx replay budget to openai-responses passthrough #4800 and fix(combo): fail over zero-output SSE errors #4817.

Documentation only. No file outside devlog/_plan/ is touched, and nothing in the build, typecheck or test path reads from devlog/.

Verification

• git diff --stat origin/dev shows three added files, all under devlog/_plan/260917_l3_retry_budget_admission/.
• No runtime, test, script, workflow or structure/ path is in the change set, so the ownership and invariant-binding gate has nothing to bind and the file-size ratchet has no source file to measure.
• Cross-platform CI at the exact head is the evidence of record; its changes job scopes the expensive legs out for a docs-only diff and still publishes the aggregate check.
• No security-sensitive material is recorded here. The unit contains no pre-disclosure analysis; per AGENTS.md that would belong in scratch space rather than in devlog/.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. This PR is itself the documentation; no user-facing surface changed, so docs-site/ is unaffected.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. No credential, token, workflow or release path is touched.

Summary by CodeRabbit

• Documentation
  • Added planning and review documentation for retry handling, send-budget accounting, and cancellation behavior.
  • Documented recovery scenarios for transient server errors, streaming errors, and cooldown-based retries.
  • Clarified response preservation and error-handling expectations across supported provider and routing scenarios.

[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-17T08:51:31.690969Z	7db5d3e	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 hygiene checks failed.

• empty_catch — An empty catch block was added. Handle, report, or deliberately propagate the error. Paths: devlog/_plan/260917_l3_retry_budget_admission/010_admission_audit.md.

[github-actions]

✅ READY

• all PR quality gates passed.

Hygiene

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ae08b95c-a921-4107-9544-22aacb64e466

📥 Commits

Reviewing files that changed from the base of the PR and between f1dfda8 and a1f8322.

📒 Files selected for processing (3)

• devlog/_plan/260917_l3_retry_budget_admission/000_roadmap.md
• devlog/_plan/260917_l3_retry_budget_admission/010_admission_audit.md
• devlog/_plan/260917_l3_retry_budget_admission/020_independent_review.md

---

📝 Walkthrough

Walkthrough

The pull request adds three L3 planning and review documents. They define retry invariants, audit adapter send-budget admission, record response-handling findings, and scope reviews for three recovery-widening pull requests.

Changes

Retry admission and recovery review

Layer / File(s)	Summary
Verification roadmap devlog/_plan/260917_l3_retry_budget_admission/000_roadmap.md	Defines the L3 purpose, three retry invariants, four reviewed pull requests, work packages, evidence requirements, and hosted-CI constraints.
Adapter admission audit devlog/_plan/260917_l3_retry_budget_admission/010_admission_audit.md	Documents send-budget reservation and refund behavior, refusal visibility, observation-only accounting, the MIMO response-drain defect, and two recorded non-defects.
Recovery-widening reviews devlog/_plan/260917_l3_retry_budget_admission/020_independent_review.md	Defines review checks for transient 5xx replay, zero-output SSE errors, and single-target combo cooldown retries.

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

Change: Other

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/l3-retry-budget-lane-plan-20260917

---

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: 7db5d3e72c

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

Move the unreleased defect analysis out of the public devlog

Because #4865 is explicitly described as an open pull request, this section publishes an unreleased defect together with the concrete patch ordering in the tracked devlog/_plan/ tree before the fix has shipped. Move this analysis to .tmp/ and only publish the outcome under _fin/ after the fix is public.

AGENTS.md reference: AGENTS.md:L142-L146

Useful? React with 👍 / 👎.

[lidge-jun]

리뷰 · 우선순위 75 / 80

이 PR은 구현이 아니라 문서만 추가한다. devlog/_plan/260917_l3_retry_budget_admission/ 아래에 000_roadmap.md · 010_admission_audit.md · 020_independent_review.md 세 파일을 새로 넣어서, 지금 열려 있는 재시도·복구 계열 PR 네 개(#4865, #4800, #4817, #4824)를 한 통합 원칙으로 묶는 L3 레인을 연다. 현재 dev HEAD는 f1dfda8e4(패키지 2.58.0, tip #4876 — Windows CI 배치 다리에 OCX_TEST_NO_QUEUE=1)이고, 이 브랜치 codex/l3-retry-budget-lane-plan-20260917의 merge-base도 그 tip이라 리베이스가 필요 없다. 변경은 전부 devlog/_plan/ 안이고, 빌드·타입체크·테스트 경로가 devlog/를 읽지 않으므로 런타임 회귀 표면은 없다.

통합 원칙이 핵심이다. “재시도가 더 잘 되게”가 아니라, 재시도가 성공하더라도 비용·대기·중복 실행이 항상 유한해야 한다는 것이다. 문서가 못 박은 세 속성은 (1) 물리 업스트림 전송은 정확히 한 번 청구, (2) 대기는 유한하고 취소 가능, (3) 이미 관측 가능해진 턴(툴 실행·클라이언트 커밋)은 다른 곳으로 조용히 재전송하지 말 것. 네 PR 표에 적힌 head SHA(#4865 22130fbed5, #4800 af985d3d13, #4817 7b0d51bafe, #4824 2744efb6be)는 지금 GitHub 상태와 일치한다. 그리고 #4817과 #4824를 스택으로 묶지 말라는 판단이 코드 경로와 맞다. #4817은 combo-stream-preflight.ts(출력 커밋 전 분류), #4824는 core-combo.ts(분류 뒤 타깃 루프)라 파일 집합이 겹치지 않는다. 현재 dev에도 두 파일이 따로 있고, 같은 merge 체인에 직렬화할 이유가 없다.

작업 순서도 현재 dev 사실과 맞는다. wp1을 #4865로 둔 이유는 닫힌 #4621의 budget core(adapterDispatchBudget · pendingHopPermit · permit.assumeCharge)가 이미 dev에 있고, 남은 것은 mimo-free 401 JWT 재전송 · command-code reasoning-effort 수리 · google-http transient 루프처럼 아직 bare fetch를 내는 사다리 세 개를 ctx.sendBudget으로 들이는 일이기 때문이다. 010_admission_audit.md가 말하는 createAdapterPhysicalSend(src/adapters/physical-send.ts)는 현재 dev tip에는 없고 #4865 변경 집합에만 있다 — 플랜이 “이미 있는 헬퍼”가 아니라 “그 PR이 넣는 헬퍼”로 읽는 한 맞다. 예약 시점에 청구하고, 미사용이면 finally에서 release, SendBudgetExhaustedError는 마지막 실응답을 돌려 adapter-dispatch.ts가 429/SEND_BUDGET_EXHAUSTED_CODE로 답한다는 계약 서술도 현재 dev의 budget·dispatch 방향과 같다. 문서가 찾은 한 결함(mimo-free가 JWT refresh 뒤에 401 body를 drain해서 getMimoJwt가 throw하면 누수가 난다)도 순서 복원으로 고치라는 처방이 분명하다.

wp2 세 PR의 독립 질문도 타당하다. #4800은 containment(openai-responses + key-auth만, OAuth/forward/local 금지)와 docs-site 8로케일 미갱신 갭. #4817은 SSE 청크 경계에서도 first-committed-output / error / terminal 판정이 안정한지, 이미 커밋·툴 실행된 뒤 재분류로 다른 프로바이더에 재전송되면 블로커. #4824는 종료 분석이 이미 닫혔다고 보고한다 — 로컬 분기 comboTargetsDispatched<=1→2, 예산 maxAlternateTargetSends:1, 대기 waitForCooldownMs 천장(타입 검증 상한 600000, 기본 COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS=0). 현재 dev의 src/combos/types.ts에 그 기본값과 0..600000 검증이 그대로 있다. 남은 잔여 질문(같은 타깃 재전송이 classifier가 hop이라고 부르는 모든 상태에 맞는지)을 종료와 분리해 둔 것도 좋다. 운영 제약(로컬 스위트 금지, flake로 빨강→초록 금지, fork PR은 maintainer 승인 전 action_required)은 이 레인이 “증거 = 소스 인용 또는 named SHA의 hosted CI”만 쓰겠다는 선언과 맞다.

다만 이 PR 자체는 Draft이고 intake: hygiene-blocked다. 원인은 010_admission_audit.md 안 코드 인용에 빈 catch { } 모양이 들어가서 deterministic empty_catch 게이트가 문서를 소스로 오인한 것이다. 구현 결함이 아니라 문서 인용 표기 문제다. types.ts/config.ts 분할과 무관하고, 네 대상 PR의 중복 통합 문서도 아니다. 문서만이라 Cross-platform CI의 비싼 다리는 changes가 스킵하고 aggregate만 남는다. 방향은 메인테이너 로드맵(재시도 예산·관측 가능 재전송 금지)과 잘 맞고, L4 플랜(#4880)과 같은 종류의 레인 계약서다.

devlog/_plan/260917_l3_retry_budget_admission/000_roadmap.md - 네 PR을 스택이 아니라 독립 검증으로 두고, wp1=#4865 → wp2 병렬 → wp3 exact-head 증거 순서를 고정한다. tip f1dfda8e4에 정확히 올라 있다.
010_admission_audit.md (createAdapterPhysicalSend / mimo-free 401 drain) - 헬퍼 경로는 현재 dev에 없고 #4865에만 있다. 문서가 그 PR을 감사하는 문맥이면 맞고, 빈 catch { } 인용은 hygiene empty_catch 오탐의 직접 원인이다.
020_independent_review.md (#4800 / #4817 / #4824) - 각 PR에 한 질문·한 exact-head 증거를 요구한다. #4824 종료 삼중 경계와 COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS=0 주장은 현재 dev 타입과 일치한다.
#4865 · #4800 · #4817 · #4824 head SHA 표 - survey 시점 SHA가 지금 GitHub head와 같다. 플랜 머지 후에도 그 네 헤드가 tip에 리베이스되기 전에는 wp3 증거를 닫지 않는 편이 안전하다.
#4817 vs #4824 “스택 아님” - combo-stream-preflight.ts와 core-combo.ts는 현재 dev에서도 분리돼 있고 변경 집합이 겹치지 않는다는 주장과 맞다.
intake: hygiene-blocked / Draft - 문서 인용 표기만 고치면 게이트가 풀릴 가능성이 크다. 라벨을 손으로 바꾸지 말고 인용 형태를 고친 뒤 hygiene이 다시 돌게 하라.

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

• 이 L3 플랜을 먼저 dev에 올린 뒤 #4865부터 증거 레인으로 갈지, 플랜과 #4865를 같은 세션에서 묶어 볼지
• hygiene empty_catch를 문서 fence/인용 표기만 바꿔 풀지, devlog 경로를 empty_catch 스캔에서 제외하는 쪽이 맞는지
• fix(retry): extend transient-5xx replay budget to openai-responses passthrough #4800(Ready·review-ready)을 wp2에서 먼저 증거 닫을지, wp1(fix(adapters): charge adapter-owned retry sends to the request send budget #4865 Draft) 완료를 반드시 앞에 둘지 — 플랜은 예산을 먼저 깔라고 함
• fix(combo): fail over zero-output SSE errors #4817/#4824를 정말 완전 병렬로 둘지, “관측 가능 재전송 금지” 블로커 기준만 공유한 채 독립 머지할지

너의 추천
KEEP Draft. tip f1dfda8e4 기준이라 리베이스는 필요 없다. 먼저 010_admission_audit.md의 빈 catch { } 인용을 hygiene가 소스 코드로 오인하지 않게 바꿔(예: 한 줄 설명으로 바꾸거나 의도적 no-op임을 주석과 함께 표기) intake: hygiene-blocked를 풀어라. 그다음 exact-head CI(docs라 대부분 skip) 확인 후 Ready·머지. 머지 뒤에는 플랜대로 wp1=#4865를 먼저 닫고, #4800/#4817/#4824는 스택하지 말고 각자 exact-head 증거로 독립 검증하라. 이 PR에서 구현·테스트·라벨 교체는 하지 말 것.

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