rate-limit-proxy Phase 2：依真實 budget 主動排程（delay / 佇列 / block）

[kiki830621]

Priority: P3（backlog — 探索性，非本週；先讓 v1.7.0 的 Phase 1 觀測資料累積後再評估）

Problem

rate-limit-proxy.py（v1.5.0 交付）目前是 Phase 1 純觀測：透明轉發 + 擷取真實 anthropic-ratelimit-* header、token usage、請求 model 寫進 rate-state.jsonl，但不做任何主動干預。所有 guard 仍是風險降低（pacing-guard 的 deny/sleep 只看 launch 次數 heuristic、nudge 只提醒）——沒有任何機制依真實 budget 在請求送出前主動 delay / 佇列 / 擋下。

本 issue 是 #1（Phase 1，已交付 v1.5.0）明確 defer 的 Phase 2：把 proxy 從被動觀測升級成主動排程，讓「保證不撞牆」從 heuristic 逼近真正可達成。

Type

feature（大型、探索性）。很可能是 Spectra 級——新增主動排程是對外行為改變、有死鎖/公平性/正確性的長期維護意涵，diagnose 階段應據此評估 Complexity，並可能拆成多個子問題。

Expected

proxy 在轉發請求「之前」讀最近一筆同桶的 rate-state.jsonl 快照，依真實 remaining/reset 做主動排程，理想能力（diagnose 階段再定案優先序）：

1. Budget-aware delay：某桶 remaining 逼近 0 且 reset 還有 N 秒 → 主動延遲送出到 budget 回填，而非讓請求撞 429 再由 Claude Code retry。
2. 佇列/序列化：同桶並發請求（尤其一個 Workflow 內部 fan-out 的數十個 subagent）排隊而非同時打，攤平 burst。
3. Hard block（最後手段）：budget 真的乾了 → 擋下並回一個明確錯誤/等待，而非讓它撞牆。

Actual（現狀 — Phase 1 邊界）

• proxy 只轉發 + 觀測；rate-state.jsonl 資料寫了但只被 pacing-guard 的 heat-nudge 讀來「提醒」，沒有任何主動排程消費它。
• v1.7.0 已讓 rate-state.jsonl 帶 model、rate_state_heat() 依家族桶（model_bucket()）過濾（rate-limit-proxy 的 rate-state.jsonl 也缺 model 欄位（sister concern from #2） #4 per-model 分桶用 exact model-id 相等，非 rate-limit bucket 相等（同族變體互不計入） #6）——Phase 2 排程可直接複用這套分桶，per-bucket 各自排程。
• proxy 是常駐 daemon（vs. hook 是每次 tool call 才 spawn 的短命 subprocess），有狀態、能跨請求協調——這正是 Phase 2 排程需要的執行模型，Phase 1 已把 daemon 骨架建好。

Impact / 待 diagnose 釐清的關鍵風險

• 死鎖：proxy 若在請求路徑上同步等待 budget 回填，可能卡住整個 Claude Code 主迴圈（proxy 是所有 API 流量的必經點）。需要 timeout / 逃生閥設計。
• 不公平排程：多個並發 session 共用同一 account bucket（使用者本機常 3-4 並發），proxy 如何在它們之間公平分配 budget？先到先服務 vs. 加權？
• 正確性 vs. fail-open：Phase 1 的鐵律是 fail-open（proxy 掛掉不影響轉發）。Phase 2 主動 delay/block 與 fail-open 天生張力——排程邏輯出錯不能把使用者鎖死。預設應可一鍵退回純觀測（如 env flag RATE_LIMIT_PROXY_SCHEDULE=0）。
• 前提驗證（gating precondition）：Phase 1 defer Phase 2 的理由是「先靠 Phase 1 資料驗證『真實 header 可見度』本身有沒有用」。diagnose 第一步應先看 v1.7.0 累積的 rate-state.jsonl——真實 header 是否夠即時/準確到足以支撐主動排程決策；若 header 落後現實太多，Phase 2 的前提就不成立。
• 範疇：只涵蓋「經過 proxy 的流量」——claude.ai 網頁版等其他管道仍在視野外，Phase 2 一樣不保證帳號級絕對不撞牆（誠實邊界不變）。

References

• Parent / Phase 1：真正防撞牆：即時 rate-limit header + 精確 token 追蹤 + 請求排程管控 #1（已交付 v1.5.0）
• 分桶基礎：per-model 分桶用 exact model-id 相等，非 rate-limit bucket 相等（同族變體互不計入） #6 model_bucket()、rate-limit-proxy 的 rate-state.jsonl 也缺 model 欄位（sister concern from #2） #4 rate-state 帶 model（已交付 v1.7.0）
• 設計邊界原文：plugins/claude-hot-limit/CLAUDE.md →「Proxy 誠實邊界（Phase 1）」段落「明確排除 Phase 2 主動排程」

Current Status

Phase: needs-fix（v1 hold 條件經 31 天 live 證據證偽；disposition 待定）
Last updated: 2026-08-17 by idd-comment → idd-update

Key Decisions

• 2026-08-17：v1 rejected-aware hold 已證偽。31 天 / 410,716 筆 record，sched_held_ms > 0 為 0 筆；同期 1,194 筆 rejected 快照（68 個窗）全部落在 90s cap 之外（reset − now 最小值 3.9 min）。非樣本不足，是結構上不可達。
• 2026-08-17：根因為「兩個時鐘」—— rl_unified_reset 是 5h/7d 配額窗邊界、不是 retry-after；rejected 窗靠 utilization 衰退解除，不靠 reset 到達。窗長的原始經驗判斷（1–10 min）是對的，錯的是 hold 綁的欄位。
• 2026-08-17：retry-after 從未被 proxy 擷取，且尚未證實 Anthropic 429 會回傳它 —— 不得當成已知替代方案。
• 2026-07-16：live gating 啟用（daemon 帶 RATE_LIMIT_PROXY_SCHEDULE=1 + settings.json env 持久化）。
• 2026-07-12：re-diagnosis —— 舊 blocker 全解除、gating precondition PASS 帶範疇轉折（帳號級訊號非桶級）；Complexity=Spectra。spectra change rejected-aware-admission-hold 已 apply 並歸檔。

Scope Changes

• v1 的「有界 hold」機制不再是可行的交付路徑；resolve_sched_hold_cap() 的 240s 設計上限與實測 reset − now 分佈（p5 = 42.8 min）差距數量級，調參無法補救。

Blocking

• 等待使用者對 disposition 拍板，三選一：(1) 先做 retry-after 擷取的前置調查 (2) 保留 gate 但更換觸發訊號 (3) 移除 v1 hold、把 rate-limit-proxy Phase 2：依真實 budget 主動排程（delay / 佇列 / block） #7 收斂到已交付的觀測面。無外部依賴。

Commits

• 5a5b437 docs: archive spectra change rejected-aware-admission-hold + spec sync
• 2b2df37 docs: daily changelog append rate-limit-proxy Phase 2：依真實 budget 主動排程（delay / 佇列 / block） #7 Phase 2 v1
• 46e7e46 feat: rejected-aware admission hold — Phase 2 v1 opt-in scheduling

[kiki830621]

Diagnosis

Type

feature（大型、探索性）——但 diagnose 的第一產出是一個 blocker 發現，見下。

Analysis（需求分析 + gating-precondition 調查）

本 issue 的 body 明寫 gating precondition：「先靠 v1.7.0 累積的 rate-state.jsonl 驗證真實 header 可見度足以支撐排程決策」。diagnose 第一步就去查這份資料——結果是決定性的：

rate-state.jsonl 不存在。Phase 1（v1.5.0 proxy）程式碼寫好了，但從未部署進請求路徑。

實測（2026-07-02，本機 ~/.cache/claude-hot-limit/）：

• rate-state.jsonl 不存在（只有 launches.jsonl / trips-raw.jsonl / calibration-log.md——都是兩個 hook 寫的，與 proxy 無關）。
• ANTHROPIC_BASE_URL unset（沒導流到 proxy）。
• 無 rate-limit-proxy process 在跑。
• hooks/hooks.json 只啟動 pacing-guard.py + trip-recorder.py，沒有任何 hook / wrapper / launcher 啟動 proxy；proxy/ 目錄只有 rate-limit-proxy.py（無 README、無 start script）。唯一提到 proxy 部署的地方是 CLAUDE.md（文件，不是啟動器）。

結論：#7 的 gating precondition 現在無法評估——不是「資料還不夠」，是根本沒有資料、也沒有產生資料的機制。Phase 1 是「code-complete 但 zero-deployment」：要有資料，使用者得手動 python3 rate-limit-proxy.py 並手動 export ANTHROPIC_BASE_URL=http://127.0.0.1:8787，至今沒人做過。

Feasibility（真做 Phase 2 需要的條件，先記著）：

• 執行模型 OK：proxy 是常駐 daemon（vs. hook 是短命 subprocess），有狀態、能跨請求協調——這正是主動排程需要的，Phase 1 已把 daemon 骨架 + streaming 轉發 + header/usage/model 擷取建好。
• header 新鮮度理論上 OK：proxy 是所有流量必經點，可在轉發前同步讀「最近一筆同桶快照」——但這條必須用真實資料驗證，而真實資料就是現在缺的東西。
• 缺的是 bootstrapping：daemon 沒有任何東西會自動啟動它。

Impact

• rate-limit-proxy Phase 2：依真實 budget 主動排程（delay / 佇列 / block） #7 被一個未被追蹤的前置條件擋住：Phase 1 的實際部署（launcher + ANTHROPIC_BASE_URL 導流 + 一段觀測期讓 rate-state.jsonl 長出資料）。
• 在那之前設計 Phase 2 排程，等於在不存在的資料上建架構——正是本 issue body 自己警告要避免的。

Strategy

• 前置（blocker）：部署 Phase 1——加一個 proxy launcher（wrapper script 或 SessionStart hook 起 daemon）+ 文件化 ANTHROPIC_BASE_URL 導流 + 跑一段觀測期。已 surface 成獨立 issue（見 Sister Concerns）。
• 驗證 gating precondition：觀測期後讀 rate-state.jsonl——真實 header 是否夠即時/準確到能支撐「轉發前決策 delay/block」。若 header 落後現實太多 → Phase 2 前提不成立，記錄並收攤。
• 僅在資料驗證通過後：進 Spectra 設計 Phase 2 排程（budget-aware delay / 佇列 / hard block），處理死鎖 / 多 session 公平性 / fail-open 張力。

Conflict Class

D_diagnose_first — Phase 2 的 scope 在 Phase 1 資料存在前無法定案；必須先部署 + 蒐集資料才能重新框定。不可在此之前當作可平行的 feature 開工。

Complexity

Spectra（但目前 BLOCKED，不 route 進 Spectra flow）。

• Layer 2（necessary）命中：主動排程改變 proxy 對「所有經過它的請求」的 observable behavior——這是對外行為契約改變（delay/block 的語意、逃生閥 flag），該寫成 documented spec 給未來維護者。
• Layer 3 命中：死鎖 / 公平排程 / fail-open-vs-active-block 是 architectural decision with long-term maintenance implications，非 method-level choice。
• 但 routing 暫緩：Spectra flow 的前提（可設計的具體 scope）不成立，直到 blocker 解除。

Risks

• 在不存在的資料上設計（本 issue 最大風險，已由此 diagnose 攔下）。
• 死鎖：proxy 在請求路徑同步等 budget 回填 → 卡住主迴圈（proxy 是必經點）。需 timeout / 逃生閥。
• 多 session 公平性：本機常 3-4 並發 session 共用 account bucket，排程如何公平分配。
• fail-open 張力：Phase 1 鐵律是 proxy 掛掉不影響轉發；Phase 2 主動 block 與此天生衝突，需可一鍵退回純觀測。

Residue

保證不撞牆 的意圖有一部分天生無法 operationalize：account-level bucket 也被 claude.ai 網頁版等 proxy 視野外的管道消耗，proxy 再精確排程也不保證帳號級絕對不撞牆（承自 #1 誠實邊界）。這不是能靠寫更多 code 消除的殘留，而是方案的固有邊界，明確標記不靜默丟棄。

Vagueness Pre-check

• V1 (vague WHAT): 3 — 目標明確（主動排程），三個候選能力（delay / 佇列 / block）已列舉，sub-scoping 刻意 defer 給 diagnose；不是白紙。
• V4 (vague ACCEPTANCE): 3 — Phase 2 整體「完成」定義本會偏模糊，但 diagnose 已把當前 actionable step 重新框定為「部署 Phase 1 + 驗證 header 可見度」，該步的 acceptance 是明確的（rate-state.jsonl 有無資料、header 夠不夠新鮮）。
• Triggered: no — both axes ≤ 3。diagnose 產出決定性結論（blocked on 部署 Phase 1 rate-limit-proxy：launcher + ANTHROPIC_BASE_URL 導流 + 觀測期（blocks #7；sister concern from #7） #8），非「模糊到無法 route」。

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

• 部署 Phase 1 rate-limit-proxy：launcher + ANTHROPIC_BASE_URL 導流 + 觀測期（blocks #7；sister concern from #7） #8 — 部署 Phase 1 rate-limit-proxy（launcher + ANTHROPIC_BASE_URL 導流 + 觀測期）。blocks rate-limit-proxy Phase 2：依真實 budget 主動排程（delay / 佇列 / block） #7：rate-limit-proxy Phase 2：依真實 budget 主動排程（delay / 佇列 / block） #7 的 gating precondition 需要 rate-state.jsonl 累積資料，而該檔案不存在、也無產生機制。這是 diagnose 攔下的關鍵前置，file-by-default 開成獨立 issue。