帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存

[kiki830621]

Problem

Original text:
「狀態條的設計要類似claude，從使用多少來看，現在狀態條的設計好像反了」
— Source: 使用者回報（2026-08-02，附 claude.ai Plan usage limits 頁截圖為參考設計）

用量 bar 應比照 Claude 官方 UI 的語意：填滿量 = 已使用比例。Logos 目前的帳號用量顯示是剩餘導向——用越多 bar 越空——與參考設計相反。

參考截圖描述（截圖含使用者方案/用量數據，依 public-repo 紀律不上傳，文字記錄）：claude.ai 設定頁「Plan usage limits」，每列一條水平 bar + 右側「N% used」標籤。填滿部分 = 已使用比例：16% used 只填一小段（藍）、87% used 填大半（琥珀）、93% used 幾乎全滿（紅）——顏色隨用量升高遞進。

Type

bug（UI 語意）

Expected

比照 Claude：bar 的填滿量代表已使用（0 used = 空、100% used = 滿），標籤顯示「N% used／已用」，顏色以已用比例遞進（低=綠或藍 → 高=紅）。app 內所有用量 bar 採同一慣例。

Actual

兩套相反的慣例並存：

位置	語意	與 Claude 對照
帳號用量視窗（Sources/LogosUsage/AccountRowView.swift 的 UsageBar）	剩餘導向：ProgressView(value: percentRemaining)，標籤「N% 剩餘」，barColor 以剩餘量判色（剩 <10% 紅）	反了——93% used 顯示為幾乎空的 bar，Claude 是幾乎滿的紅 bar
Status bar HUD（HUDProgressBar + PlanUsageStatusItem）	消耗導向：fraction = utilization/100（0=空、1=滿），<70% 綠 / 70–90% 黃 / ≥90% 紅	已同 Claude 慣例

資料層本身就是 used-based（UsageWindow.utilization = 已用 %；percentRemaining 是加工出來的 100 - utilization），所以修正是顯示層翻轉，不動資料模型。

Impact

• 同一 app 內兩個 surface 對「bar 快滿」給出相反的解讀（HUD 滿 = 危險；帳號用量視窗滿 = 安全），使用者要記兩套規則。
• 與 claude.ai 官方頁並看時（常見情境：對照配額），視覺直覺直接衝突。

修法候選（留給 diagnose 裁決）

1. UsageBar 翻轉為 used 導向：ProgressView(value: utilization)、標籤「N% 已用」、判色改用已用比例（可直接共用 HUDUsageLevel 的 70/90 分帶，順便統一兩處的閾值與色彩）。
2. reset 時間顯示等其餘元素不動。

Notes

• 環境：Logos HEAD 75932b8
• Related: Redesign the native status bar into a claude-hud-style HUD bar #90（HUD bar 的 consumed-fraction 設計，本 issue 的既有正確範本）

---

Current Status

Phase: verified
Last updated: 2026-08-04 by /idd-verify（經 /idd-all 批次 #110–114）

Key Decisions

• 顯示層量化做一次：utilizationPercent（clamped raw 四捨五入）是唯一量化點，label / 填充 / 色階全部從它導出 —— 數字與顏色不能跨門檻分岔
• 模型層與顯示層的精度刻意不同：percentRemaining 與 raw utilization 精確互補；utilizationFraction 是量化後的顯示投影。12.5 → 顯示 13% 已用、模型 87.5% 剩餘，是兩個精度不是矛盾
• 非有限值政策：讀不到有效值 = 0% 已用 / 100% 剩餘 / nominal 綠（非 critical 紅）
• 極性方向為已用（本 issue 方向），推翻 狀態列與帳號用量的用量標示極性相反:一個標「已用」、一個標「剩餘」——統一到剩餘 #114 的「剩餘」要求
• HUDUsageLevel → UsageLevel 下移 LogosUsage，兩畫面共用 70/90 門檻

Scope Changes

• 從 狀態列與帳號用量的用量標示極性相反:一個標「已用」、一個標「剩餘」——統一到剩餘 #114 併入：顏色門檻統一（已做）、共用元件範圍（已拍板：只共用 enum）
• 狀態列 context 段分母排除 —— 屬 狀態列 context 分母卡在 200k:1M session 的 window 沒有任何可讀訊號（#95 的 settings.json 路徑為空） #113

Blocking

• (none) —— verify PASS，等人工 /idd-close

Commits

• 22b4d32 refactor: move the usage colour bands down into LogosUsage as UsageLevel (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)
• 0dab2fe refactor: HUDProgressBar reads the shared UsageLevel from LogosUsage (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)
• 82381d8 fix: 帳號用量 bars render consumed, not remaining (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)
• bb6b1fd refactor: plan-usage HUD feeds the clamped model fraction (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)
• d2f637d fix: guard non-finite utilization before it reaches any usage bar (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110) — verify R1
• 9acd6ee fix: quantise the displayed percent once, and derive the band from it (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110) — verify R2

[kiki830621]

Note — 與 #114 的方向衝突已裁定，本 issue 為實作主體

Timestamp: 2026-08-04（/idd-all Phase 0 batch 排序時發現）

#114（2026-08-03 建立）記錄的使用者原話要求把兩處統一到剩餘，與本 issue 的已用方向相反。使用者於 2026-08-04 明確裁定採用本 issue 的方向（已用，比照 claude.ai）。

裁定全文與理由見 #114 的 Decision comment。對本 issue 的影響：

• 本 issue 的 ## Expected 與「修法候選」維持不變，是正確方向。
• 從 狀態列與帳號用量的用量標示極性相反:一個標「已用」、一個標「剩餘」——統一到剩餘 #114 併入的殘餘 scope（帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110 原本未涵蓋）：
  • 顏色門檻統一 —— 帳號用量現行 10/25（剩餘基準）、狀態列 70/90（已用基準）。翻轉 UsageBar 後應共用 HUDUsageLevel 的 70/90 分帶，否則同一帳號在兩畫面仍可能一綠一橘。這一點本 issue 的修法候選 1 已提到「可直接共用 HUDUsageLevel」，此處確認為 必做而非 optional。
  • 是否抽共用元件 —— UsageBar（帳號用量）與 HUDProgressBar（狀態列）兩套獨立實作是極性會分岔的結構原因，收斂與否由本 issue 的 diagnose 裁決。
• 狀態列 context 段（97k / 200k）不在本 issue 範圍 —— 分母問題見 狀態列 context 分母卡在 200k:1M session 的 window 沒有任何可讀訊號（#95 的 settings.json 路徑為空） #113。

[kiki830621]

Diagnosis

Type

bug（UI 語意一致性）

Root Cause / Analysis

依 superpowers:systematic-debugging 四階段。這不是 crash 類 bug，沒有 error message 可讀，Phase 1 的「重現」是純渲染的確定性行為，因此重心放在資料流追蹤與變更史。

資料流（Phase 1 步驟 5） —— 極性的分岔點在顯示層，不在資料層：

endpoint limits[].percent
  → UsageClient.swift:117 decodeIfPresent(.utilization)      // 原始值 = 已用 %
  → UsageWindow.utilization (UsageModels.swift:13)           // 0–100 已用，單一事實來源
      ├─→ PlanUsageStatusItem.swift:87-89  utilization        → HUDProgressBar(fraction: /100)   [已用極性]
      └─→ UsageModels.swift:29 percentRemaining = 100 - utilization
             └─→ AccountRowView.swift:103,135,138  percentRemaining → ProgressView(value:)        [剩餘極性]

UsageModels.swift:6-8 的註解確認 utilization 就是 endpoint 的 limits[].percent（已實測對照）。資料層本身沒有歧義，percentRemaining 純粹是顯示層的加工。

變更史（Phase 1 步驟 3）—— 這是分岔真正的來源：

commit	內容	極性
d03dd4b	feat: 帳號用量 window — display-only registry consumer (task 6.1) —— 建立 AccountRowView / UsageBar	剩餘（先寫的）
f7a2f6b	feat: redesign the status bar as a claude-hud-style HUD … (#90) —— 建立 HUDProgressBar / HUDUsageLevel	已用（後寫的）

也就是說：root cause 不是任一元件寫錯，而是 #90 在新元件裡引入了 claude-hud 慣例（已用），卻沒有回頭改寫既存的 UsageBar。兩套慣例各自獨立成立、互不知情 —— 這是典型的「新慣例未回溯套用」而非邏輯錯誤。#90 的 commit message 自述目標就是 "claude-hud-style"，方向正確，只是沒收尾。

Phase 2 —— 對照 working example 與 broken 的每一處差異（working = HUDProgressBar + HUDUsageLevel）：

面向	HUDProgressBar（對的）	UsageBar（要改的）
值來源	window.utilization / 100	window.percentRemaining
標籤	\(Int(utilization))%（隱含已用）	\(Int(percentRemaining))% 剩餘
顏色門檻	HUDUsageLevel：<0.70 綠 / <0.90 黃 / ≥0.90 紅（以已用計）	barColor：<10 紅 / <25 橘 / else 綠（以剩餘計）
元件型別	自繪 Capsule + 固定寬 46pt	SwiftUI ProgressView(value:total:)，滿寬
判色邏輯可測性	HUDUsageLevel 是純 enum，Tests/LogosTests/HUDUsageLevelTests.swift 直接單測	barColor 是 View 內 private computed property，無法單測

Phase 3 假設：root cause 是「#90 的已用慣例只落在新元件、未回溯 UsageBar」，修法是讓 UsageBar 直接吃 utilization 並把判色委派給 HUDUsageLevel。

但驗證假設時撞到一個模組邊界問題（本次診斷最重要的發現）：

Sources/LogosUsage/AccountRowView.swift   → 屬 LogosUsage 目標（library）
Sources/Logos/Views/StatusBar/HUDProgressBar.swift → 屬 Logos 目標（app）
Package.swift：Logos 依賴 LogosUsage，反向不成立

HUDUsageLevel 目前住在 app 模組，UsageBar 住在 library 模組。UsageBar 無法 import HUDUsageLevel —— 依賴方向不允許。所以「共用 70/90 門檻」（#114 裁定列為必做）不是改幾行值就好，必須把 HUDUsageLevel 下移到 LogosUsage，這是跨模組的抽象搬遷，連帶 HUDUsageLevelTests（現為 @testable import Logos）要跟著換家。

Impact

影響的檔案（估計）：

• Sources/LogosUsage/AccountRowView.swift —— UsageBar 翻轉（值、標籤、判色委派）
• Sources/Logos/Views/StatusBar/HUDProgressBar.swift —— HUDUsageLevel 移出
• Sources/LogosUsage/（新檔，暫名 UsageLevel.swift）—— 承接下移的 enum，改 public
• Tests/LogosTests/HUDUsageLevelTests.swift → Tests/LogosUsageTests/（import 改 @testable import LogosUsage）
• 新增 UsageBar 判色的單測（現在 barColor 無測試保護，翻轉後更需要）

影響的使用者流程：帳號用量視窗每一列的用量條與百分比標籤。狀態列 HUD 不動。

測試 blast radius（實查，非推測）：

• Tests/LogosUsageTests/UsageClientTests.swift 有 4 處斷言 percentRemaining（:39/:44/:106/:157-158）。這些測的是 model helper 本身，翻轉顯示層不會讓它們變紅；但 percentRemaining 會失去唯一的 production 消費者，要決定留（當作 model API）或刪（避免死碼）。
• Snapshot 基準不受影響 —— LogosHostedTests/__Snapshots__/ViewSnapshotTests/ 的 test_accountRow_* 拍的是 Sources/Logos/Views/AccountSwitcher/AccountRow.swift（帳號切換器的列），不是 UsageAccountRow / UsageBar。整個帳號用量視窗目前沒有任何 snapshot 覆蓋，所以本次翻轉不會 RED，也代表沒有像素層防護。
• BuildGraphDriftTests 只檢查 Package.swift 的 library target 是否都在 project.yml。本案不新增 target（只在既有 LogosUsage 內加檔案），故不觸發 drift。

Strategy

• 把 HUDUsageLevel 從 Sources/Logos/Views/StatusBar/HUDProgressBar.swift 下移到 Sources/LogosUsage/，改 public（含 init(fraction:) 與 color）
• HUDProgressBar 改 import LogosUsage 使用下移後的 enum；行為零變更
• HUDUsageLevelTests 移到 Tests/LogosUsageTests/，import 改 @testable import LogosUsage；斷言內容不動（門檻語意不變）
• UsageBar 翻轉：percentRemaining → utilization、標籤 N% 剩餘 → N% 已用、ProgressView(value: utilization, total: 100)、barColor 刪除改為 HUDUsageLevel(fraction: utilization / 100).color
• 新增 UsageBar 判色/標籤的單測（補上原本缺的保護）
• 決定 percentRemaining 去留（保留為 model API，或刪除 + 移除 UsageClientTests 對應斷言）
• 人工目視確認帳號用量視窗與狀態列同向

先寫測試（TDD）：門檻語意搬家後必須先有 RED，再改 UsageBar。

Conflict Class

C_shared_module_coord

共享資源具名：HUDUsageLevel（要跨 Logos → LogosUsage 模組邊界搬遷的判色抽象）與其牽動的 Package.swift / 測試 target 歸屬。任何同時段修改狀態列 HUD 或 LogosUsage view 層的 issue 必須與本 issue 序列化，不可交錯。本批次的 #111 / #112（AccountUsageWindow.swift、RegistryUsageModel.swift）與 #113（ClaudeUsageReader.swift、WindowUsageModel.swift）皆無檔案重疊，可排在前後而不衝突。

Complexity

Plan

Hard-gate: triggered —— 兩條判準都命中：

1. shared abstraction：HUDUsageLevel 修完後會被 HUDProgressBar.swift 與 AccountRowView.swift 兩處引用（現況僅自身檔案 + 測試），且搬遷跨越模組邊界。硬閘要求 Plan 必涵蓋 family-wide 影響 —— 已在 Strategy 列出全部 call site。
2. 單一概念散佈 ≥5 檔：「極性 + 門檻統一」這一個概念估計觸及 5 個檔案（AccountRowView.swift、HUDProgressBar.swift、新 UsageLevel.swift、HUDUsageLevelTests.swift 搬遷、新 UsageBar 測試）。這些檔案不是各自獨立（Layer 1 的 multi-file 豁免不適用），而是同一改動的散佈。

sdd_bias 未設（config 無此欄）→ 硬閘出口為 Plan，非 Spectra。

非 Spectra 的理由（Layer 2 未滿足）：LogosUsage 不在 Package.swift 的 products 內（products 只有 Logos executable 與 LogoSwitch library），HUDUsageLevel 轉 public 只是套件內跨模組可見，沒有對外 published API 給 future callers，不需要 frozen spec contract。

Layer P 亦命中（即使無硬閘也會是 Plan）：cross-file refactor 但無 external contract change（抽共用元件）；且有 2+ 合理做法需拍板（見 Risks）。

Risks

• 抽象該放哪裡有 2 個合理選擇，會影響 code shape，需要在 Plan 階段拍板：
  1. HUDUsageLevel 下移到 LogosUsage（本 Strategy 採用）—— 最小搬遷，但把「HUD」命名帶進非 HUD 的模組，名稱語意變髒（可順勢改名 UsageLevel）。
  2. 連 HUDProgressBar 一起下移、兩個畫面共用同一個 bar view —— 收斂最徹底，但兩者的視覺規格不同（固定 46pt 膠囊 vs 滿寬 ProgressView），硬合併會犧牲其中一邊的版面。
• percentRemaining 若刪除，UsageClientTests 4 處斷言要一起改；若保留則留下無 production 消費者的 API（死碼 vs 保留彈性的取捨）。
• ProgressView(value:) 的 .tint 在不同 macOS 版本的渲染差異 —— 翻轉後高用量會是紅色滿條，視覺權重比現在的紅色空條重很多，可能需要調整不透明度。屬視覺微調，不阻擋。
• 帳號用量視窗無 snapshot 覆蓋，翻轉後沒有像素層迴歸保護（見下方 Sister Concerns）。

Residue

本 issue 的意圖裡有一段無法被 operationalize：「與 claude.ai 官方頁並看時視覺直覺一致」。可操作的部分是極性、標籤語意、顏色遞進方向 —— 這些都會做到。無法操作的是色相對齊：claude.ai 用 藍 → 琥珀 → 紅，Logos 用 綠 → 黃 → 紅（HUDUsageLevel.color）。要不要連色相一起對齊是獨立的設計決定，本 issue 不處理、也不假裝已涵蓋。

---

Diagnosis by /idd-diagnose #110（RCA 框架委派 superpowers:systematic-debugging）。方向裁定見本 issue 的 Note comment 與 #114 的 Decision comment。

Vagueness Pre-check

• V1 (vague WHAT): 2 — issue body 的 ## Expected 與「修法候選」已具名檔案與符號（AccountRowView.swift 的 UsageBar、ProgressView(value: utilization)、HUDUsageLevel 的 70/90 分帶），且 狀態列與帳號用量的用量標示極性相反:一個標「已用」、一個標「剩餘」——統一到剩餘 #114 的 Decision comment 已把方向釘死為「已用」。要做什麼有具體錨點，非開放式。
• V4 (vague ACCEPTANCE): 2 — 完成定義可機械檢查：填滿 = 已用、標籤「N% 已用」、判色以已用比例遞進、兩個畫面同向。唯一不可操作的部分（色相是否對齊 claude.ai 的藍/琥珀）已明確寫入 ### Residue，不混入驗收條件。
• Triggered: no — both axes ≤ 3

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

• 帳號用量視窗零 snapshot 覆蓋:UsageBar 極性/門檻顏色無像素層防護 (sister concern from #110) #115 —— 帳號用量視窗零 snapshot 覆蓋。RCA 的 Phase 2「對照 working example」實查 LogosHostedTests/__Snapshots__/ViewSnapshotTests/ 時發現：test_accountRow_* 拍的是帳號切換器的 AccountRow，不是 UsageAccountRow / UsageBar，整個帳號用量視窗無像素層防護。與本 issue 同根（都源自 UsageBar 的孤立性）但不同修法，故另立。明確不在本批次（帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110–114）範圍。

[kiki830621]

Implementation Plan (Plan tier)

Files & Changes

• Sources/LogosUsage/UsageLevel.swift（新檔）—— 承接從 app 模組下移的判色 enum，改名 HUDUsageLevel → UsageLevel 並轉 public（init(fraction:) + color）。門檻語意與數值零變更（<0.70 綠 / 0.70–0.90 黃 / ≥0.90 紅，以已用比例計）。改名理由：搬進 LogosUsage 後「HUD」前綴指涉的是 app 層的狀態列，留著會讓 library 模組帶著錯的語意標籤。
• Sources/LogosUsage/UsageModels.swift —— 新增 public var utilizationFraction: Double { max(0, min(1, utilization / 100)) }。兩個畫面都改吃這個 clamped 0–1 值，取代各自的 /100。順帶補掉 PlanUsageStatusItem 現行 utilization / 100 未 clamp 的小缺口（目前靠 HUDProgressBar 內部 clamp 兜住，沒有可見 bug，但 model 層 clamp 才與既有的 percentRemaining 一致）。
• Sources/LogosUsage/AccountRowView.swift —— UsageBar 翻轉：
  • percentRemaining: Double → utilization: Double（call site :103 一併改）
  • 標籤 "\(Int(percentRemaining.rounded()))% 剩餘" → "\(Int(utilization.rounded()))% 已用"
  • ProgressView(value: percentRemaining, total: 100) → ProgressView(value: utilization, total: 100)
  • 刪除 private barColor（10/25 剩餘門檻），改 .tint(UsageLevel(fraction: window.utilizationFraction).color)
• Sources/Logos/Views/StatusBar/HUDProgressBar.swift —— 移除 HUDUsageLevel enum 定義，加 import LogosUsage，.fill(UsageLevel(fraction: clamped).color)。HUDProgressBar / HUDDivider 兩個 view 留在原地（見 Decision Points）。渲染行為零變更。
• Sources/Logos/Views/StatusBar/PlanUsageStatusItem.swift —— :89 HUDProgressBar(fraction: window.utilization / 100) → HUDProgressBar(fraction: window.utilizationFraction)。help / accessibility 文案已寫「% used」，不動。
• Tests/LogosUsageTests/UsageLevelTests.swift（新檔，由 Tests/LogosTests/HUDUsageLevelTests.swift 搬遷）—— import 改 import LogosUsage（enum 轉 public 後不需 @testable），型別名改 UsageLevel，斷言內容逐字不動（門檻語意未變，測試值全部沿用）。
• Tests/LogosTests/HUDUsageLevelTests.swift —— 刪除（內容已搬走）
• Tests/LogosUsageTests/UsageModelsTests.swift（新檔）—— utilizationFraction 的邊界測試：0 → 0、100 → 1、130 → 1（clamp）、-5 → 0（clamp）、87 → 0.87。

Family-wide scope (shared-abstraction hard-gate trigger only)

硬閘因 shared abstraction 命中（HUDUsageLevel），故列舉該抽象搬遷後的全部 call site，確保 Plan 不只覆蓋觸發當下那個檔案：

Call site	現況	改後
Sources/Logos/Views/StatusBar/HUDProgressBar.swift:57	HUDUsageLevel(fraction: clamped).color	UsageLevel(fraction: clamped).color（跨模組）
Sources/LogosUsage/AccountRowView.swift:147-153	private barColor（剩餘門檻）	UsageLevel(fraction:).color（新 call site）
Tests/LogosTests/HUDUsageLevelTests.swift	@testable import Logos	搬到 Tests/LogosUsageTests/，import LogosUsage

utilizationFraction 的 call site：AccountRowView.swift（新）、PlanUsageStatusItem.swift:89（取代現行 /100）。ContextUsageStatusItem 不在此 family —— 它的 fraction 來自 token 計數（contextTokens / contextMax）不是 UsageWindow，本次不碰。

Sequencing & Dependencies

1. 先建 Tests/LogosUsageTests/UsageLevelTests.swift + UsageModelsTests.swift → 編譯失敗（UsageLevel / utilizationFraction 尚不存在）= RED。
2. 建 Sources/LogosUsage/UsageLevel.swift + UsageModels.swift 加 utilizationFraction → 新測試 GREEN；此時舊的 HUDUsageLevelTests 仍綠（舊 enum 還在，兩個型別並存不衝突，分屬不同模組）。
3. 改 HUDProgressBar.swift（刪舊 enum + import）→ 舊 Tests/LogosTests/HUDUsageLevelTests.swift 編譯失敗 → 同一步刪除該檔。
4. 翻 UsageBar（AccountRowView.swift）。
5. 改 PlanUsageStatusItem.swift:89 用 utilizationFraction。
6. swift test 全綠 → 目視確認兩個畫面同向。

步驟 2 必須在 3 之前（HUDProgressBar 要能 import 到新 enum）；步驟 3 的刪檔必須與改檔同一步（否則中間狀態編譯不過）。

Decision Points

Diagnosis 的 Risks 列了 2 個合理做法，本 plan 明確選擇：

1. 只下移 enum，不下移 view —— HUDProgressBar（固定 46pt 自繪膠囊）與 UsageBar（滿寬 ProgressView）視覺規格不同，硬合併會犧牲其中一邊的版面。共用「判色語意」已足以消除極性分岔，共用「渲染實作」則是為了收斂而犧牲設計。選最小共用面。
2. enum 改名 UsageLevel —— 不留 typealias HUDUsageLevel。只有 1 個既有 call site + 1 個測試檔，直接改乾淨勝過留相容層。
3. percentRemaining 保留不刪 —— 它是 LogosUsage 的 model-level public API，有 UsageClientTests 4 處斷言覆蓋，刪除只會把 diff 擴散到測試而沒有實質收益。翻轉後它暫時沒有 production 消費者，會在宣告處加一行註解說明「model-level API，view 層一律用 utilization / utilizationFraction」，避免未來有人以為它是顯示層的正解。

Risks & Mitigations

Risk	Mitigation
跨模組搬遷造成中間狀態編譯不過	Sequencing 步驟 3 把「改 HUDProgressBar」與「刪舊測試檔」綁成同一步；每步結束都跑 swift test
翻轉後高用量是紅色滿條，視覺權重比現在的紅色空條重很多	屬預期行為（正是 claude.ai 的呈現）。若實機看起來過重，調 .tint 不透明度即可，不改語意；本 plan 不預先調整
ProgressView(value:) 吃系統強調色 vs .tint 覆蓋	現行 code 已用 .tint(barColor) 覆蓋，改後同樣用 .tint(...)，行為一致
BuildGraphDriftTests 因新檔 fail	不新增 target，只在既有 LogosUsage target 的 source glob 內加檔案 → drift guard 不觸發。步驟 6 的 swift test 會實測確認
帳號用量視窗無 snapshot 覆蓋，翻轉無像素層防護	已另立 #115 追蹤；本 issue 以單元測試（UsageLevelTests + UsageModelsTests）覆蓋判色與 fraction 語意

Test Plan

Test	對應改動	RED 預期	GREEN 預期
UsageLevelTests（搬遷）	UsageLevel 下移 + 改名	編譯失敗：cannot find 'UsageLevel' in scope	5 個 band 斷言全過（0.0/0.50/0.699 → nominal；0.70/0.80 → warning；0.90+ → critical；非有限值 → nominal）
UsageModelsTests.utilizationFraction（新）	utilizationFraction	編譯失敗：value of type 'UsageWindow' has no member 'utilizationFraction'	0→0、87→0.87、100→1、130→1、-5→0
既有 UsageClientTests（不動）	percentRemaining 保留	—	4 處斷言維持綠（證明 model 層未被破壞）
既有 HUDUsageLevelTests（刪除）	enum 搬走	步驟 3 後編譯失敗 → 刪檔	n/a

Out-of-scope (will NOT be touched)

• 色相對齊 claude.ai 的 藍/琥珀/紅 —— Logos 是 綠/黃/紅。這是獨立的設計決定，已記在 diagnosis 的 ### Residue。
• 狀態列 context 段（97k / 200k）的分母 —— 屬 狀態列 context 分母卡在 200k:1M session 的 window 沒有任何可讀訊號（#95 的 settings.json 路徑為空） #113。本次只碰它的 HUDProgressBar 共用 enum，不碰 ContextUsageStatusItem 的邏輯。
• 帳號用量視窗的 snapshot 覆蓋 —— 屬 帳號用量視窗零 snapshot 覆蓋:UsageBar 極性/門檻顏色無像素層防護 (sister concern from #110) #115。
• UsageBar 與 HUDProgressBar 合併成單一 view —— 見 Decision Point 1，明確不做。
• percentRemaining 刪除 —— 見 Decision Point 3，明確保留。

Tangential Observations (filed mid-plan, v2.42.0+ #524)

• 帳號用量視窗零 snapshot 覆蓋:UsageBar 極性/門檻顏色無像素層防護 (sister concern from #110) #115（帳號用量視窗零 snapshot 覆蓋）—— 已於 diagnose Step 3.6 立案，不重複。
• PlanUsageStatusItem 的 utilization / 100 未 clamp —— 併入本次 scope（utilizationFraction），不另立 issue：它與極性/門檻統一是同一個概念的一部分，且修正只有一行。
• 其餘 none surfaced。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• Sources/LogosUsage/UsageLevel.swift —— enum 下移 + 改名 + 轉 public → 22b4d32
• Sources/LogosUsage/UsageModels.swift —— 加 utilizationFraction；percentRemaining 保留並註明是 model-level API → 22b4d32
• Tests/LogosUsageTests/UsageLevelTests.swift —— 由 Tests/LogosTests/HUDUsageLevelTests.swift 搬遷，斷言不動 → 22b4d32（建）/ 0dab2fe（原檔刪除）
• Tests/LogosUsageTests/UsageModelsTests.swift —— utilizationFraction 邊界測試（含一條與 percentRemaining 互補的守門） → 22b4d32
• Sources/Logos/Views/StatusBar/HUDProgressBar.swift —— 刪 HUDUsageLevel 定義、import LogosUsage、改用 UsageLevel → 0dab2fe
• Sources/LogosUsage/AccountRowView.swift —— UsageBar 翻轉為已用導向、刪 barColor → 82381d8
• Sources/Logos/Views/StatusBar/PlanUsageStatusItem.swift —— 改吃 utilizationFraction → bb6b1fd

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)

Changes

• 22b4d32 refactor: move the usage colour bands down into LogosUsage as UsageLevel (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)
• 0dab2fe refactor: HUDProgressBar reads the shared UsageLevel from LogosUsage (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)
• 82381d8 fix: 帳號用量 bars render consumed, not remaining (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)
• bb6b1fd refactor: plan-usage HUD feeds the clamped model fraction (帳號用量 bar 語意與 Claude 官方相反：填滿量是剩餘而非已用，與 status bar HUD 兩套慣例並存 #110)

Deviation from the approved plan（誠實記錄）

Plan 寫 ProgressView(value: utilization, total: 100)，實作用 ProgressView(value: fraction, total: 1)（fraction = window.utilizationFraction）。

理由：utilization 未 clamp，若 endpoint 回 130 則 value: 130, total: 100 會讓 ProgressView 溢出，而顏色卻是用 clamped fraction 判的 —— 條與色會不同步。改吃同一個 clamped fraction 讓兩者恆一致。UsageBar 因此收兩個參數：utilization（標籤顯示的原始百分比）與 fraction（條與判色）。渲染語意與 plan 完全相同，只是把 clamp 從「只保護顏色」擴到「也保護條長」。

Files Changed

 Sources/Logos/Views/StatusBar/HUDProgressBar.swift | 36 +------------
 Sources/Logos/Views/StatusBar/PlanUsageStatusItem.swift |  2 +-
 Sources/LogosUsage/AccountRowView.swift            | 30 ++++++-----
 Sources/LogosUsage/UsageLevel.swift                | 42 +++++++++++++++
 Sources/LogosUsage/UsageModels.swift               |  9 ++++
 Tests/LogosTests/HUDUsageLevelTests.swift          | 55 -------------------
 Tests/LogosUsageTests/UsageLevelTests.swift        | 62 ++++++++++++++++++++++
 Tests/LogosUsageTests/UsageModelsTests.swift       | 47 ++++++++++++++++
 8 files changed, 179 insertions(+), 104 deletions(-)

Verification

• TDD：RED 先行已實測 —— 新測試檔在型別存在前 swift build --build-tests 報 cannot find 'UsageLevel' in scope（plan 預期的失敗訊息，逐字相符），建完型別後轉 GREEN。
• swift test：647 tests / 86 suites 全綠（每個 commit 後都跑過一次，非只在最後）。
• 既有 UsageClientTests 4 處 percentRemaining 斷言維持綠 → 證明 model 層未被破壞。
• BuildGraphDriftTests 綠 → 確認未新增 target、project.yml 無需同步。

Scope Compliance

git diff --name-only 的 8 個檔案與 Plan 的 Files & Changes 逐一對應，零溢出。4 個 commit 全部帶 (#110)，無 Closes trailer（IDD 紀律：由 /idd-close 關案）。

Sister Bugs Filed (mid-impl, v2.44.0+ #526)

none surfaced —— 實作期間編譯一次過、無相鄰同根 bug 浮現。診斷期已立案的 #115（帳號用量視窗零 snapshot 覆蓋）不重複列。

Next: verification pending

[kiki830621]

Verify: #110

Engine

pai-ensemble 2.20.1 (canonical #207) — 4 IDD lenses + Devil's Advocate + Codex (gpt-5.6-sol, xhigh), model: sonnet（依 CLAUDE.md 的 fan-out doctrine 顯式 pin，避免寬 fan-out 繼承高階 session model）

兩輪，各 6 個獨立 AI：

Round	Frozen SHA	Findings	Subagent tokens	Duration
R1	bb6b1fd	3 HIGH + 5 MEDIUM	697,633	15m 25s
R2	d2f637d	0 HIGH + 5 MEDIUM	573,583	9m 23s

Diff-freshness gate（#228）：兩輪皆通過 —— R1 開始到結束期間 HEAD 維持 bb6b1fd 未動（verify in-flight 不 commit 的紀律），R2 同理。無 stale-snapshot verdict。

Aggregate

PASS — 0 blocking remaining. R1 的 3 個 HIGH 全部關閉並經 R2 獨立確認；R2 的 5 個 MEDIUM 全部歸類為 in-scope fix 並已修（9acd6ee）。

要求覆蓋率

4 / 4 —— 極性翻轉、標籤語意、顏色門檻統一（70/90 共用 UsageLevel）、跨模組抽象搬遷。

---

Findings（合併後）

#	Round	Severity	Finding	Source	Action
1	R1	HIGH	Int(Double) 對非有限值 trap；兩處 label 都直接轉未驗證的 Double	codex	Fixed d2f637d
2	R1	HIGH	max(0, min(1, u/100)) 不 sanitize NaN → 非有限值變成滿條/紅色，反轉了原本的空條/綠色防禦。推翻 implementer「HUD rendering 不變」的宣稱	devils-advocate	Fixed d2f637d
3	R1	HIGH	label 改用 raw utilization 引入新的崩潰路徑（舊的 percentRemaining 剛好把 NaN 吸收成 100）	devils-advocate	Fixed d2f637d
4	R1	MEDIUM	clamp 與 UsageLevel 文件的「非有限值→nominal」政策矛盾	codex	Fixed d2f637d
5	R1	MEDIUM	UsageBar 收兩個可獨立設定的參數，可渲染出 label 與 bar 互相矛盾的列	codex	Fixed d2f637d
6	R1	MEDIUM	範圍政策不對稱：label 顯示原始值、bar 做 clamp	codex + logic	Fixed d2f637d
7	R1	MEDIUM	新測試只搬移舊斷言，沒有覆蓋「label 說已用而非剩餘」的 view 層行為	codex	Deferred → #115（帳號用量視窗零 snapshot 覆蓋）
8	R2	MEDIUM	utilizationPercent 走 ÷100 → ×100 round-trip，binary64 不精確，恰好 14.5 / 28.5 / 56.5 / 57.5 四個值比舊 label 少 1 —— 違反「in-range 顯示數字不得改變」	logic + regression	Fixed 9acd6ee
9	R2	MEDIUM	label 四捨五入、色階讀未四捨五入的 fraction → 89.995 顯示「90% 已用」卻是黃色，與本型別自己文件的「red at/above 0.90」矛盾	codex + devils-advocate	Fixed 9acd6ee
10	R2	MEDIUM	非有限值下 percentRemaining 仍算 100 - .infinity → clamp 成 0，同一 window 同時「0% 已用」與「0% 剩餘」	codex	Fixed 9acd6ee
11	R2	MEDIUM	R2 新增的 labelAgreesWithBar 是套套邏輯 —— 拿定義 percent 的同一個表達式去比對 percent，無法偵測任何 rounding 方向錯誤	logic + regression + devils-advocate	Fixed 9acd6ee（改為獨立陳述的期望值）

Independent reproduction（不採信 agent 的原話，逐條自己驗）

R1 的兩個 HIGH 與 R2 的三個 MEDIUM 都用 Swift 實跑確認後才接受：

min(1.0, .nan)            = 1.0      ← Swift min 是 y < x ? y : x，NaN 比較恆 false
fraction(.nan)            = 1.0      ← 舊 clamp 把非有限值變成 critical/red
舊 hudClamp(nan/100)      = 0.0      ← 原本是 nominal/green（證實 rendering 確實改了）
舊 remaining(.nan)        = 100.0    ← 舊 label 剛好安全，新 label 會 trap
round-trip 漂移集合        = [14.5, 28.5, 56.5, 57.5]（直接 clamp 實作為空集合）
u=89.995 → label 90% / band yellow   ← 修正後為 red
u=.infinity → 已用 0% / 剩餘 0%       ← 修正後為 已用 0% / 剩餘 100%

修正後端到端確認：

u=14.5   label=15%   fill=0.15  band=green     (與舊 label 一致，漂移消失)
u=69.995 label=70%   fill=0.70  band=yellow    (數字與顏色同步跨門檻)
u=89.995 label=90%   fill=0.90  band=red
u=99.6   label=100%  fill=1.00  band=red
u=130    label=100%  fill=1.00  band=red
u=NaN    label=0%    fill=0.00  band=green

Process Gaps

• R1 的 6 個 reviewer 全部漏掉 PlanUsageStatusItem:153 的 accessibility label（VoiceOver 字串，與可見 Text 是不同的一行）。可見 label 被三個 lens 抓到，無障礙 label 同一 trap class 卻無人提及 —— 由 implementer 自己的 grep sweep 補上。ensemble 對「同一 bug 的第二個出現位置」有系統性盲點，這點值得記進 IDD 的 verify 慣例。
• R1 有 2 個 agent、R2 有 1 個 agent 回傳空 findings（requirements / security lens 判定無問題）—— 屬正常 clean 回報，非 agent 失敗（agents_error: 0）。

Scope Check

git diff --name-only 75932b8..9acd6ee = 8 個檔案，與 Implementation Plan 的 Files & Changes 逐一對應，零溢出。6 個 commit 全部帶 (#110)，無 Closes trailer。

Residue

• Finding 7 未在本 issue 關閉 —— 帳號用量視窗的 view 層／snapshot 覆蓋仍是零，「label 文字確實是『已用』」沒有任何自動化守門。追蹤於 帳號用量視窗零 snapshot 覆蓋:UsageBar 極性/門檻顏色無像素層防護 (sister concern from #110) #115。本 issue 用單元測試覆蓋了判色、量化、互補性與 trap-safety，但覆蓋不到渲染出來的字。
• 色相仍是 綠/黃/紅，非 claude.ai 的 藍/琥珀/紅（原 diagnosis 的 Residue，未變）。
• 超額顯示的誠實性：DA 被要求論證「把 130 顯示成 100% 隱藏了真實超額狀態」。目前選擇 clamp（label 與 bar 一致優先）。若之後認為超額需要可見，應是獨立的產品決定而非 bug fix。